feat!: replace hash-based IDs with semantic versioning for variant ID generation (#163)

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

Add variant-based ID generation and registry management to the
s2dm-publish GitHub Action. The workflow now automatically initializes
or updates the registry based on schema changes detected via GraphQL
Inspector diff.

- Add new `registry` module with variant ID tracking using semantic versions
- Add `variant_ids.py` with VariantEntry and VariantIDFile models
- Add `graphql_inspector_diff.js` for automated schema change detection
- Add `diff_parser.py` to process GraphQL Inspector output
- Variant increments now tied to graphql-inspector detected changes
- Update ID exporter to generate semantic version-based variant IDs
- Update spec history exporter to work with new variant ID system
- Move `skos_search.py` to registry module
- Add variant counter tracking for concept modifications
- Add support for marking concepts as removed in specific versions
- Add 15 comprehensive tests for variant ID generation logic
- Update E2E CLI tests for new registry commands

BREAKING CHANGES:
- Removed `idgen` module and hash-based ID generation
- `registry id` command now requires `--version-tag` parameter
- `registry id` command removed `--strict-mode` option
- `registry init` command now requires `--version-tag` parameter
- `registry update` command now requires `--version-tag` and `--previous-ids`
- Variant IDs use semantic versioning format (Concept/vM.m) instead of hashes
- Integrate variant registry into automated workflow
- Remove dry_run parameter from IDExporter
- Registry operations now require version tags and
previous registry files from release artifacts.

Signed-off-by: Mustafa Kaptan <mustafa.kaptan@motius.de>

* refactor(graphql-inspector): add local dependencies and decorator pattern

- Add package.json for local Node.js dependency management
- Add @requires_graphql_inspector decorator for dependency injection
- Add locate_graphql_inspector() to find node_modules automatically
- Resolve CLI path once during initialization for performance
- Improve dependency checking with runtime verification
- Update CI/Actions to use npm install instead of global install
- Update documentation in CONTRIBUTING.md and tools/README.md

Replaces global npm install with local package.json management.
The decorator pattern auto-injects inspector_path to CLI commands,
eliminating repeated lookups and global state.

Signed-off-by: Mustafa Kaptan <mustafa.kaptan@motius.de>

* fix: Add missing elements in example schema

Tools expect explicit references to all elements

Signed-off-by: JD Alvarez <8550265+jdacoello@users.noreply.github.com>

* fix: Add missing elements to updated example schema

Tools expect now all elements explicitly.

Signed-off-by: JD Alvarez <8550265+jdacoello@users.noreply.github.com>

---------

Signed-off-by: Mustafa Kaptan <mustafa.kaptan@motius.de>
Signed-off-by: JD Alvarez <8550265+jdacoello@users.noreply.github.com>
Co-authored-by: JD Alvarez <8550265+jdacoello@users.noreply.github.com>

Author: mfkaptan-motius

.github/workflows/ci.yml

@@ -29,12 +29,12 @@ jobs:
         with:
           node-version: "20"
 
+      - name: install node dependencies
+        run: npm install
+
       - name: uv
         uses: astral-sh/setup-uv@v7
 
-      - name: npm install gql-inspector
-        run: npm i --global @graphql-inspector/cli graphql
-
       - name: sync
         run: |
           uv sync --frozen

.gitignore

@@ -180,4 +180,5 @@ cython_debug/
 #  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
+.idea/
+.cursor/

CONTRIBUTING.md

@@ -25,6 +25,24 @@ uv sync
 ```
 
 It will create a virtual environment `.venv` in the root of the project.
+
+### Node.js Dependencies
+
+Some features require Node.js dependencies for GraphQL schema operations. Install them with:
+
+```shell
+npm install
+```
+
+This installs `@graphql-inspector/cli`, `@graphql-inspector/core`, and `graphql` packages required by:
+- `s2dm diff graphql` - Structured diff output
+- `s2dm check version-bump` - Version bump detection
+- `s2dm validate graphql` - Schema validation
+- `s2dm similar graphql` - Type similarity search
+- `s2dm registry init` and `s2dm registry update` - Registry functionality
+
+> [!NOTE]
+> The `@requires_graphql_inspector` decorator automatically locates and injects the path to the local `node_modules` directory. Commands will fail with clear error messages if dependencies are missing. The GraphQL Inspector wrapper resolves the CLI path once during initialization for optimal performance.
 You can run things in the virtual environment by using a `uv run` prefix for commands, e.g.:
 
 ```shell
@@ -80,6 +98,42 @@ pytest --cov-report term-missing --cov=s2dm -vv
 
 New code should ideally have tests and not break existing tests.
 
+#### Skipping GraphQL Inspector Tests
+
+Some tests require the `@graphql-inspector/cli` package to be installed via npm. These tests are marked with `@pytest.mark.graphql_inspector`.
+
+**If you don't have Node.js dependencies installed:**
+
+These tests will automatically be skipped with a message:
+```
+SKIPPED [9] tests/conftest.py:309: graphql-inspector not found. Run 'npm install' to install dependencies.
+```
+
+**To explicitly skip these tests:**
+
+```bash
+# Skip all graphql_inspector tests
+pytest -m "not graphql_inspector"
+
+# Skip graphql_inspector tests with verbose output
+pytest -m "not graphql_inspector" -v
+
+# Run only graphql_inspector tests
+pytest -m "graphql_inspector"
+```
+
+**To run these tests:**
+
+1. Install Node.js dependencies first:
+   ```bash
+   npm install
+   ```
+
+2. Then run all tests normally:
+   ```bash
+   pytest
+   ```
+
 ### Type Checking
 
 Simplified Semantic Data Modeling uses type annotations throughout, and `mypy` to do the checking.

actions/s2dm-publish/README.md

@@ -5,7 +5,6 @@ GitHub Action for automated artifact generation and publishing workflow through
 ## Features
 
 - Automatic version bump detection
-- Units synchronization
 - Registry management (init/update)
 - GraphQL schema composition
 - JSON schema generation
@@ -178,14 +177,39 @@ Your repository must have:
  commit_args = ""
 ```
 
+## Registry and Variant IDs
+
+The action automatically manages variant-based IDs for schema concepts:
+
+- **Variant IDs**: Each concept gets a semantic version (e.g., `Vehicle.speed/v1.0`)
+- **Change Detection**: GraphQL Inspector detects schema changes and triggers version increments
+- **Breaking vs Non-Breaking**: Breaking changes increment major version (v1.0 → v2.0), non-breaking changes increment minor (v1.0 → v1.1)
+- **History Tracking**: All concept definitions are saved to a history directory for traceability
+
+### Release Artifacts
+
+Each release includes:
+- `registry.json` - Complete spec history with variant IDs
+- `variant_ids_<tag>.json` - Current variant ID mappings
+- `concept_uris_<tag>.json` - Concept URI definitions
+- `history/` - Directory with historical concept definitions
+
 ## How It Works
 
 1. **Validation**: Validates that the spec directory exists and contains at least one .graphql file
-2. **Setup**: Checks out S2DM repository, installs Python 3.13, uv, and S2DM dependencies
-3. **Download Previous Release**: Downloads previous release artifacts (if available)
-4. **Version Check**: Compares current spec with previous schema to determine version bump type
-5. **Units Sync**: Synchronizes units definitions
-6. **Registry Management**: Initializes registry for first release or updates it for subsequent releases
-7. **Artifact Generation**: Generates all required artifacts (GraphQL, JSON Schema, SHACL, SKOS, VSpec) to temporary location outside repository
-8. **Version Bump**: Updates version using bump-my-version and creates git tag
-9. **Release Creation**: Creates GitHub release with all generated artifacts in a tarball
+1. **Setup**: Checks out S2DM repository, installs Python 3.13, Node.js 20, uv, and S2DM dependencies
+2. **Version Check**: Downloads previous release and compares current spec to determine version bump type
+3. **GraphQL Diff Generation**: Uses `s2dm diff graphql` (powered by @graphql-inspector/core) to detect schema changes (for updates)
+4. **Registry Management**:
+   - For initial release: Initializes registry with variant IDs starting at v1.0
+   - For updates: Increments variant IDs based on detected changes (major for breaking, minor for non-breaking)
+5. **Artifact Generation**: Generates all required artifacts (GraphQL, JSON Schema, SHACL, SKOS, VSpec)
+6. **Version Bump**: Updates version using bump-my-version and creates git tag
+7. **Release Creation**: Creates GitHub release with all generated artifacts including:
+   - Composed GraphQL schema
+   - JSON Schema
+   - SHACL shapes
+   - SKOS RDF
+   - VSpec
+   - Registry files (spec_history, variant_ids, concept_uris)
+   - History directory with concept definitions