Updating Spec

updating-spec

Upstream Sources:

Current Implementation:

• 41 package type handlers in src/purl-types/
• Official test suite at test/data/spec/specification-test.json
• Community tests at test/data/contrib-tests.json
• Type-specific tests in test/data/types/

Reference: See reference.md for detailed spec comparison procedures, type registry, and edge cases.

CI Mode (detected via CI=true or GITHUB_ACTIONS):

• Create atomic commits, skip build validation
• Workflow handles push and PR creation

Interactive Mode (default):

• Validate each change with build/tests before proceeding
• Report findings to user for review before committing

Do NOT:

• Implement draft or unratified spec changes without user confirmation
• Remove existing type support without spec justification
• Modify test suite data without verifying against upstream

Do ONLY:

• Sync from official upstream sources
• Add new types that are ratified in the spec
• Update test suites from upstream
• Fix normalization/validation to match spec clarifications

Process

Phase 1: Validate Environment

if [ "$CI" = "true" ] || [ -n "$GITHUB_ACTIONS" ]; then
  CI_MODE=true
  echo "Running in CI mode"
else
  CI_MODE=false
  echo "Running in interactive mode"
fi

git status --porcelain

Phase 2: Fetch Upstream Spec Changes

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

# 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

# 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

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

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

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

## 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.