updating-spec

name	updating-spec
description	Syncs socket-packageurl-js against upstream PURL and VERS specifications. Checks purl-spec, vers-spec, TC54/ECMA-427 standards, and the purl npm package for new types, test cases, normalization rules, and spec changes. Triggers when user mentions "update spec", "sync spec", "purl spec changes", or "check upstream".

Phase 2: Fetch Upstream Spec Changes

Check each upstream source for changes since last sync:

2.1: purl-spec repository

# Get recent commits
gh api repos/package-url/purl-spec/commits --jq '.[0:30] | .[] | {sha: .sha[0:7], date: .commit.author.date, message: .commit.message}' 2>/dev/null

# Check for changes to core spec files
gh api repos/package-url/purl-spec/commits --jq '.[0:30] | .[] | select(.commit.message | test("SPECIFICATION|TYPES|test"; "i")) | {sha: .sha[0:7], message: .commit.message}'

2.2: vers-spec repository

gh api repos/package-url/vers-spec/commits --jq '.[0:30] | .[] | {sha: .sha[0:7], date: .commit.author.date, message: .commit.message}' 2>/dev/null

2.3: purl npm package

npm view purl version description 2>/dev/null

2.4: TC54 status

Check https://tc54.org/purl/ for standard updates via WebFetch.

---

Phase 3: Compare Spec Types Against Implementation

Identify new, modified, or deprecated PURL types:

# List our implemented types
ls src/purl-types/ | sed 's/\.ts$//' | sort

# Fetch current PURL-TYPES.rst from upstream
gh api repos/package-url/purl-spec/contents/PURL-TYPES.rst --jq '.content' | base64 -d | grep -E '^\*\*' | head -60

Compare the lists to identify:

• New types in spec not yet implemented
• Types we implement that may have changed rules
• Deprecated types

---

Phase 4: Sync Test Suite

Update the official purl-spec test suite data:

# Fetch latest test suite from purl-spec
gh api repos/package-url/purl-spec/contents/test-suite-data.json --jq '.content' | base64 -d > /tmp/purl-spec-tests.json

# Compare with our copy
diff <(cat test/data/spec/specification-test.json | python3 -m json.tool) <(cat /tmp/purl-spec-tests.json | python3 -m json.tool) || echo "Test suite has changes"

If changes exist:

1. Review the diff for new test cases
2. Copy updated test suite to test/data/spec/specification-test.json
3. Run tests to identify failures
4. Fix implementation to pass new tests

---

Phase 5: Review Normalization and Validation Rules

Check for spec clarifications affecting normalization or validation:

For each type with spec changes, review:

• Case normalization rules (type, namespace, name)
• Required vs optional qualifiers
• Namespace separator rules
• Version encoding requirements
• Subpath handling

See reference.md for type-specific normalization rules.

---

Phase 6: Implement Changes

Apply necessary code changes (interactive mode: confirm with user first):

For each required change:

1. Update type handler in src/purl-types/
2. Add or update tests in test/
3. Update type-specific test data in test/data/types/
4. Run validation: pnpm run check && pnpm test
5. Commit atomically per logical change

# Validate after each change
pnpm run check
pnpm test
pnpm run cover  # Must maintain 100%

---

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 spec sync report:

## Spec Sync Complete

### Upstream Changes Detected:

| Source | Changes Found | Action Taken |
|--------|--------------|--------------|
| purl-spec | X commits | [details] |
| vers-spec | X commits | [details] |
| TC54/ECMA-427 | [status] | [details] |
| purl npm package | vX.Y.Z | [details] |

### Types Added/Updated:
- [list any new or modified type handlers]

### Test Suite:
- Official tests: Updated/No changes
- Coverage: 100%

### Commits Created:
- [list commits]

### Next Steps:
**Interactive mode:**
1. Review changes: `git log --oneline -N`
2. Push to remote: `git push origin main`

**CI mode:**
1. Workflow will push branch and create PR

Success Criteria

• All upstream sources checked for changes
• Test suite synced with purl-spec
• New types implemented if ratified
• Normalization rules updated per spec clarifications
• Full build and tests pass
• 100% test coverage maintained
• Comprehensive report generated

Context

This skill is useful for:

• Monthly spec compliance checks
• After TC54 meetings or spec releases
• Before major version releases
• When users report spec compliance issues

Safety: Changes are validated before committing. Interactive mode requires user confirmation for non-trivial changes.