feat: object-based buildPURL

[oritwoen]

Replaces the 6 positional args on buildPURL with a single object that matches ParsedPURL. This means parsePURL output goes straight into buildPURL for lossless round-trips, qualifiers and subpath included.

• buildPURL({ type, name, version?, namespace?, qualifiers?, subpath? })
• Removed the separate stringifyPURL that existed briefly - buildPURL covers it now
• 11 new tests covering qualifiers, subpath, encoding, and parse→build round-trips

Closes #1

---

Summary by cubic

Switched buildPURL to a single object parameter that matches ParsedPURL, with support for qualifiers and subpath. Subpaths and namespaces are now encoded per segment so "/" remains literal, enabling spec-compliant, lossless parse→build; stringifyPURL is removed.

• Migration
  • Replace buildPURL(type, name, version?, namespace?) with buildPURL({ type, name, version?, namespace? }).
  • Pass qualifiers and subpath via buildPURL({ qualifiers, subpath }).
  • Remove stringifyPURL usage; use buildPURL(parts) instead.

^{Written for commit c411f34. Summary will update on new commits.}

[coderabbitai]

📝 Walkthrough

Walkthrough

The buildPURL function API was refactored to accept a single object parameter containing type, name, version, namespace, qualifiers, and subpath, replacing the previous positional parameter approach. Implementation and tests were updated accordingly to reflect the new signature.

Changes

Cohort / File(s)	Summary
Core Implementation src/core/purl.ts	Updated buildPURL signature from positional parameters to single object parameter. Added logic to URL-encode and append qualifiers as query string and subpath as fragment when present. Maintains inverse relationship with parsePURL.
Test Suite test/unit/purl.test.ts	Updated all buildPURL invocations to use new object parameter syntax. Added new test cases for qualifiers, multiple qualifiers, subpath, all components, and round-trip validation with parsePURL.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 The PURL now wears a simpler hat,
One object instead of positional splat!
With qualifiers, subpath in tow,
Round-tripping's now the way to go! ✨
A cleaner API, we all agree. 🎉

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title 'feat: object-based buildPURL' clearly summarizes the main change: converting buildPURL to accept an object parameter instead of positional arguments.
Linked Issues check	✅ Passed	The PR fully addresses issue #1 by replacing positional arguments with an object matching ParsedPURL shape, enabling round-trip capability with qualifiers and subpath support.
Out of Scope Changes check	✅ Passed	All changes are within scope: buildPURL signature update, implementation adjustments, removal of stringifyPURL, and comprehensive test updates covering the new API.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Description check	✅ Passed	The pull request description clearly explains the API change from positional arguments to an object parameter, mentions new test coverage, and directly relates to the code changes shown in the summary.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

• 📝 Generate docstrings (stacked PR)
• 📝 Generate docstrings (commit on current branch)

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch buildpurl-object-api

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ad727c08bd

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[cubic-dev-ai]

1 issue found across 2 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="src/core/purl.ts">

<violation number="1" location="src/core/purl.ts:127">
P2: Subpath encoding escapes `/`, but PURL subpath requires `/` separators to remain unescaped. Encode each segment instead so canonical subpaths like `a/b` remain `a/b` rather than `a%2Fb`.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@src/core/purl.ts`:
- Around line 113-127: The namespace and subpath are currently encoded as whole
strings which encodes '/' characters; update the logic that builds the purl (the
code using parts.namespace, parts.subpath, encodeURIComponent and purl) to split
namespace and subpath on '/' into segments, percent-encode each segment with
encodeURIComponent, then rejoin with '/' so the separators remain unencoded; for
namespace do: parts.namespace.split('/').map(encodeURIComponent).join('/') and
append the trailing '/', and for subpath do:
parts.subpath.split('/').map(encodeURIComponent).join('/') after the '#' so the
resulting PURL matches ECMA-427 segment-wise encoding.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 81dbd0a4-f337-4868-8544-0b57ec9201d3

📥 Commits

Reviewing files that changed from the base of the PR and between 35d443b and ad727c0.

📒 Files selected for processing (2)

• src/core/purl.ts
• test/unit/purl.test.ts

📜 Review details

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (1)

• GitHub Check: cubic · AI code reviewer

🔇 Additional comments (1)

test/unit/purl.test.ts (1)

159-235: Good test migration for the object-based API.

This suite now covers the updated call shape plus qualifiers, subpath, and parse→build round-trip behavior well.