Merge pull request #266 from yoskini/chore/#185_Validate_GTS_identifiers

feat: Add GTS documentation validator and associated tests

Author: MikeFalcon77

Cargo.lock

@@ -20,6 +20,7 @@ codegen-units = 1
 [workspace]
 members = [
     "apps/hyperspot-server",
+    "apps/gts-docs-validator",
     "libs/modkit",
     "libs/modkit-macros",
     "libs/modkit-db",
@@ -264,6 +265,10 @@ urlencoding = "2.1"
 # Regex for env expansion
 regex = "1.10"
 
+# CLI and terminal output
+glob = "0.3"
+colored = "2"
+
 # gRPC support
 tonic = { version = "0.14", features = ["transport"] }
 prost = { version = "0.14" }

Cargo.toml

@@ -69,7 +69,7 @@ fmt:
 # |             | - Use 'make dylint-list' to see all available custom lints           |
 # +-------------+----------------------------------------------------------------------+
 
-.PHONY: clippy kani geiger safety lint dylint dylint-list dylint-test
+.PHONY: clippy kani geiger safety lint dylint dylint-list dylint-test gts-docs gts-docs-vendor gts-docs-release gts-docs-vendor-release gts-docs-test
 
 # Run clippy linter (excludes gts-rust submodule which has its own lint settings)
 clippy:
@@ -92,6 +92,42 @@ geiger:
 lint:
 	RUSTFLAGS="-D warnings" cargo check --workspace --all-targets --all-features
 
+## Validate GTS identifiers in .md and .json files (DE0903)
+# Uses gts-docs-validator from apps/gts-docs-validator
+# Vendor enforcement is available via the gts-docs-vendor target (--vendor x)
+gts-docs:
+	cargo run -p gts-docs-validator -- \
+		--exclude "target/*" \
+		--exclude "docs/api/*" \
+		docs modules libs examples
+
+## Validate GTS docs with vendor check (ensures all IDs use vendor "x")
+gts-docs-vendor:
+	cargo run -p gts-docs-validator -- \
+		--vendor x \
+		--exclude "target/*" \
+		--exclude "docs/api/*" \
+		docs modules libs examples
+
+## Validate GTS identifiers (release build)
+gts-docs-release:
+	cargo run --release -p gts-docs-validator -- \
+		--exclude "target/*" \
+		--exclude "docs/api/*" \
+		docs modules libs examples
+
+## Validate GTS docs with vendor check (release build)
+gts-docs-vendor-release:
+	cargo run --release -p gts-docs-validator -- \
+		--vendor x \
+		--exclude "target/*" \
+		--exclude "docs/api/*" \
+		docs modules libs examples
+
+## Run tests for GTS documentation validator
+gts-docs-test:
+	cargo test -p gts-docs-validator
+
 ## List all custom project compliance lints (see dylint_lints/README.md)
 dylint-list:
 	@cd dylint_lints && \
@@ -289,7 +325,7 @@ oop-example:
 	cargo run --bin hyperspot-server --features oop-example,users-info-example,tenant-resolver-example -- --config config/quickstart.yaml run
 
 # Run all quality checks
-check: fmt clippy security dylint-test dylint test
+check: fmt clippy security dylint-test dylint gts-docs test
 
 # Run CI pipeline
 ci: check

Makefile

@@ -0,0 +1,43 @@
+[package]
+name = "gts-docs-validator"
+version.workspace = true
+edition.workspace = true
+license.workspace = true
+authors.workspace = true
+repository.workspace = true
+description = "GTS identifier validator for documentation files (DE0903)"
+
+[[bin]]
+name = "gts-docs-validator"
+path = "src/main.rs"
+
+[dependencies]
+# CLI parsing
+clap = { workspace = true }
+
+# GTS library for ID validation
+gts = { workspace = true }
+
+# File system traversal
+walkdir = { workspace = true }
+glob = { workspace = true }
+
+# Regex for pattern matching
+regex = { workspace = true }
+
+# Serialization
+serde = { workspace = true }
+serde_json = { workspace = true }
+
+# Error handling
+anyhow = { workspace = true }
+thiserror = { workspace = true }
+
+# For colored terminal output
+colored = { workspace = true }
+
+[dev-dependencies]
+tempfile = { workspace = true }
+
+[lints]
+workspace = true

apps/gts-docs-validator/Cargo.toml

@@ -0,0 +1,82 @@
+# GTS Documentation Validator (DE0903)
+
+A Rust CLI tool that validates GTS (Global Type System) identifiers in documentation files (`.md`, `.json`, `.yaml`, `.yml`).
+
+This complements the Dylint-based DE0901 lint that validates GTS identifiers in Rust source code.
+
+## Usage
+
+```bash
+# Basic validation
+gts-docs-validator docs modules libs examples
+
+# With vendor validation (ensures all IDs use expected vendor)
+gts-docs-validator --vendor x docs modules libs examples
+
+# With exclusions
+gts-docs-validator --exclude "target/*" --exclude "docs/api/*" .
+
+# JSON output (for CI integration)
+gts-docs-validator --json docs
+
+# Verbose output (shows files being scanned)
+gts-docs-validator --verbose docs
+```
+
+## Makefile Targets
+
+```bash
+make gts-docs         # Validate GTS IDs (structural only)
+make gts-docs-vendor  # Validate with --vendor x check
+make gts-docs-test    # Run unit tests
+```
+
+## Options
+
+| Option | Description |
+|--------|-------------|
+| `--vendor <VENDOR>` | Expected vendor for all GTS IDs (e.g., `--vendor x`) |
+| `--exclude <PATTERN>` | Glob patterns to exclude (can be repeated) |
+| `--json` | Output results as JSON |
+| `--verbose` | Show file scanning progress |
+
+## Example Vendors
+
+When using `--vendor`, the following example/placeholder vendors are always tolerated (commonly used in documentation and tutorials):
+
+- `acme`
+- `globex`
+- `example`
+- `demo`
+- `test`
+- `sample`
+- `tutorial`
+
+## Smart Context Detection
+
+The validator automatically handles:
+
+- **Wildcard patterns**: `gts.x.*` is allowed in filter/pattern contexts (e.g., `$filter`, `pattern`, `match`)
+- **Bad examples**: GTS IDs near "invalid", "wrong", "❌" markers are skipped
+- **Trailing tildes**: Schema IDs ending with `~` are properly validated
+
+## GTS Identifier Format
+
+```text
+gts.<vendor>.<org>.<package>.<type>.<version>~
+    │        │      │         │      └── Version (v1, v1.2, etc.)
+    │        │      │         └── Type name (snake_case)
+    │        │      └── Package name
+    │        └── Organization
+    └── Vendor identifier
+```
+
+## Exit Codes
+
+- `0` - All GTS identifiers are valid
+- `1` - Invalid GTS identifiers found
+
+## Related
+
+- **DE0901**: Dylint lint for GTS patterns in Rust source (`make dylint`)
+- **DE0902**: Prevents `schema_for!` on GTS structs (`make dylint`)