updating-npm-purl-package

name	updating-npm-purl-package
description	Syncs socket-packageurl-js feature parity with the purl npm package (https://github.com/ljharb/purl). Checks for new API features, URL type coverage, registry validation support, and normalization behaviors. Triggers when user mentions "sync purl package", "purl feature parity", or "check purl npm".

Phase 2: Fetch Upstream Package Info

Get the latest purl package version and check for changes:

# Current purl version
npm view purl version

# Check purl changelog/releases
gh api repos/ljharb/purl/releases --jq '.[0:5] | .[] | {tag: .tag_name, date: .published_at, name: .name}'

# Get recent commits for feature changes
gh api repos/ljharb/purl/commits --jq '.[0:20] | .[] | {sha: .sha[0:7], date: .commit.author.date, message: .commit.message}'

---

Phase 3: Compare URL Type Coverage

Compare registry URL generation between purl and our implementation:

purl supports URL generation for: bioconductor, bitbucket, cargo, chrome, clojars, cocoapods, composer, conan, conda, cpan, deno, docker, elm, gem, github, golang, hackage, hex, homebrew, huggingface, luarocks, maven, npm, nuget, pub, pypi, swift, vscode

Check our UrlConverter coverage:

# Extract types from our url-converter.ts
grep "case '" src/url-converter.ts | sed "s/.*case '//;s/'.*//" | sort -u

Compare lists. Missing types need new case handlers in src/url-converter.ts.

---

Phase 4: Compare Registry Validation Coverage

Compare registry existence checking support:

purl validate() supports: npm, pypi, gem, cargo, nuget, hex, maven, composer, pub, hackage, cocoapods

Check our purlExists coverage:

grep -E 'Exists\(' src/purl-exists.ts | grep 'export' | sed 's/.*function //;s/Exists.*//' | sort

Compare lists and identify gaps.

---

Phase 5: Compare Normalization Behaviors

Test key normalization differences:

For each supported type, compare how purl and our implementation normalize:

• Type casing
• Namespace casing and encoding
• Name casing and encoding
• Version encoding
• Qualifier key ordering
• @ encoding in npm scoped packages

Use the purl npm package's test suite as a reference:

gh api repos/ljharb/purl/contents/test --jq '.[].name'

---

Phase 6: Implement Missing Features

For each identified gap, implement the feature:

For each missing URL type:

1. Add case handler to src/url-converter.ts (both toRepositoryUrl and toDownloadUrl)
2. Add test cases to test/url-converter.test.mts

For each missing registry validator:

1. Add function to src/purl-exists.ts
2. Add test cases to corresponding test/registry-*.test.mts

For normalization fixes:

1. Update type handler in src/purl-types/{type}.ts
2. Add edge case tests

# Validate after each change
pnpm run check
pnpm test

Commit atomically per logical feature:

git add <files>
git commit -m "feat(url-converter): add {type} registry URL support

Added repository and download URL generation for {type} ecosystem."

---

Phase 7: Final Validation

Run full validation (skip in CI mode):

if [ "$CI_MODE" = "true" ]; then
  echo "CI mode: Skipping final validation"
else
  pnpm run fix
  pnpm run check
  pnpm test
  pnpm run cover
fi

---

Phase 8: Report Summary

Generate feature parity report:

## Feature Parity Sync Complete

### purl npm package version: vX.Y.Z

### URL Type Coverage:
| Type | purl | socket-packageurl-js | Status |
|------|------|---------------------|--------|
| ... | ... | ... | Added/Already supported/N/A |

### Registry Validation:
| Type | purl | socket-packageurl-js | Status |
|------|------|---------------------|--------|
| ... | ... | ... | Added/Already supported |

### Normalization Fixes:
- [list any fixes applied]

### API Features:
- [list any new features added]

### Commits Created:
- [list commits]

Success Criteria

• URL type coverage matches or exceeds purl package
• Registry validation covers all purl-supported types
• Normalization behavior matches TC54 spec
• All tests pass with 100% coverage
• Feature parity report generated

Context

This skill is useful for:

• Monthly feature parity checks
• After new purl npm releases
• Before major version releases
• When users report behavioral differences vs purl package

Safety: Read-only analysis first, changes only after user review (interactive mode).