feat!: replace hash-based IDs with semantic versioning for variant ID generation

[mfkaptan-motius]

Replace hash-based IDs with semantic versioning for variant ID generation

Summary

This MR replaces the hash-based variant ID generation system with a semantic versioning approach that provides better traceability and human-readable IDs. Variant increments are now automatically tied to changes detected by GraphQL Inspector.

What Changed

New Variant ID System

• Variant IDs now use semantic versioning format: Concept/vM.m (e.g., Vehicle.speed/v1.0)
• Each concept tracks a variant counter that increments with modifications
• Variant increments are tied to graphql-inspector detected changes for accurate change tracking
• Support for marking concepts as removed in specific versions
• Version tags are now required for all registry operations

GraphQL Inspector Integration

New: graphql_inspector_diff.js - Node.js script using @graphql-inspector/core API

• Generates structured JSON diff output comparing schema versions
• Detects field additions, removals, and modifications
• Identifies breaking vs non-breaking changes
• Provides concept-level change tracking for variant increments

New: diff_parser.py - Python module to process GraphQL Inspector output

• Parses structured diff JSON
• Maps changes to concept names for variant tracking
• Supports automated variant increment logic

Architecture Changes

Removed: src/s2dm/idgen/ module (old hash-based system)

Added: src/s2dm/registry/ module with:

• variant_ids.py: Models for semantic version-based variant IDs
• concept_uris.py: Concept URI registry management
• spec_history.py: Spec history tracking
• search.py: Moved from tools (previously skos_search.py)

Added: src/s2dm/tools/graphql_inspector_diff.js - Structured diff generation

Added: src/s2dm/tools/diff_parser.py - Diff output processing

Updated: src/s2dm/tools/graphql_inspector.py - Integration with new diff system

CLI Changes

• All registry commands now require --version-tag parameter
• registry update requires --previous-ids parameter
• Optional --diff-file parameter for providing structured diffs from GraphQL Inspector
• Removed --strict-mode option from registry id command

How It Works

1. Schema Comparison: s2dm diff graphql uses GraphQL Inspector to compare old and new schemas
2. Change Detection: Identifies specific changes (field additions, removals, type changes)
3. Variant Increment: Each detected change triggers a variant increment for affected concepts
4. Semantic Versioning: Concepts receive incremental versions (v1.0, v1.1, v2.0, etc.)

Example workflow:

# Generate diff using s2dm diff command
s2dm diff graphql --schema old.graphql --val-schema new.graphql --output changes.json

# Update registry with detected changes
s2dm registry update \
  --current-schema new.graphql \
  --previous-ids variant_ids_v1.0.0.json \
  --previous-spec-history spec_history_v1.0.0.json \
  --diff-file changes.json \
  --version-tag v1.1.0 \
  --output-dir ./registry

Breaking Changes

1. Removed idgen module: The hash-based ID generation system has been completely removed
2. CLI parameter changes:
   • --version-tag is now required for registry id, registry init, and registry update
   • --previous-ids is now required for registry update
   • --strict-mode option removed from registry id
3. ID format change: Variant IDs now use semantic versioning (vM.m) instead of content hashes
4. New dependency: Requires @graphql-inspector/core npm package for diff generation

Documentation

• Updated src/s2dm/exporters/README.md with variant ID documentation
• Added src/s2dm/registry/README.md with registry module overview
• Updated examples/spec-history-registry/README.md with new CLI usage
• All new modules include docstrings

Testing

Added tests covering:

• Variant ID generation and format validation
• Major/minor version increment logic
• Breaking vs non-breaking change handling
• Enum changes and propagation
• Variant counter tracking
• Edge cases (empty diffs, multiple changes, removed fields)

Updated E2E CLI tests for new registry commands.

Test Infrastructure Improvements

GraphQL Inspector Test Marker: Implemented explicit test management for GraphQL Inspector dependencies:

• Added @pytest.mark.graphql_inspector marker for tests requiring npm dependencies
• Created inspector_path pytest fixture that auto-locates node_modules directory
• Tests automatically skip with helpful message when @graphql-inspector/cli not installed
• Developers can selectively skip these tests: pytest -m "not graphql_inspector"
• Documented skip behavior in CONTRIBUTING.md

Related to #153