Numan Parser Checker
Relevant source files
The following files were used as context for generating this wiki page:
The Numan Parser Checker is a specialized validation tool within the numan-registry repository designed to ensure "parser parity" between the registry's JSON index and the production Rust parser used by the Numan CLI. It acts as a critical safety gate in the Continuous Integration (CI) pipeline, preventing changes to the package catalog that might conform to a JSON schema but fail to be processed by the actual Numan application logic.
Sources: REVIEW.md:46, README.md:65-67
Architecture and Integration
The checker is implemented as a Rust project located in tools/numan-parser-check/. Unlike the Python-based linting and validation scripts, this tool uses the exact production registry parser code from the Numan core repository to validate the index.json file.
Dependency Structure
The tool explicitly pins a specific revision of the numan-cli project to ensure that the registry remains compatible with the version of the parser currently in production or targeted for the next release.
[dependencies]
# Keep this revision explicit: registry CI must parse candidates with the
# production parser that Numan ships, rather than a look-alike schema.
numan-cli = { git = "https://github.com/tonythethompson/numan.git%22%2C rev = "6e93c27307a5a256fa6e6dcab602edf1707ed7d1" }
Sources: tools/numan-parser-check/Cargo.toml:8-10
CI Pipeline Placement
The Numan Parser Checker is a mandatory "Stage 2" gate. It is executed within the repo-safety.yml GitHub Actions workflow. It runs after basic secret scanning and preflight checks but before any signing or deployment actions occur.
The following diagram illustrates the validation flow:
The flow ensures that only syntactically and semantically valid catalog data proceeds to the signing phase.
Sources: AGENTS.md:16-24, README.md:42-45
Key Functions and Usage
The tool is invoked via Cargo and targets the main registry index. It is designed to be run in locked mode in CI to ensure reproducibility.
Execution Command
The standard command used in the agent environment and CI workflows is:
cargo run --locked --manifest-path tools/numan-parser-check/Cargo.toml -- registry/index.json
Sources: AGENTS.md:21-22, REVIEW.md:14
Validation Scope
The checker validates the following invariants:
- Parser Parity: Ensures index changes parse correctly with the production Rust registry parser.
- Trust Root Compatibility: Verifies that the package metadata structures align with what the CLI expects when syncing against the
officialtrust root. - Data Integrity: Catches "silent index corruption" or "schema/parser mismatch" that standard JSON schema validators might overlook.
Sources: REVIEW.md:32-34, REVIEW.md:46
Severity and Impact
The Numan Parser Checker addresses high-priority risks defined in the repository's review guidelines.
| Category | Impact Level | Description |
|---|---|---|
| Parser Mismatch | P1 | Failure to parse the index renders the registry unusable for all production clients. |
| Index Corruption | P0 | Subtle formatting errors that lead to silent failures in the CLI's logic. |
| Schema Drift | P1 | When the JSON schema and the Rust structs in numan-cli diverge. |
Sources: REVIEW.md:21-24, README.md:65-67
Data Interaction
The checker primarily interacts with the registry/index.json file. It verifies the top-level structure and the individual package entries.
The Rust parser enforces strict adherence to the data model required for the official-2026-07-01 trust root.
Sources: registry/index.json:1-10, README.md:7-11
Conclusion
The Numan Parser Checker is an essential component of the repository's "repo-safety" infrastructure. By utilizing the actual production Rust code from the Numan project, it provides a level of validation that exceeds static JSON schema checks, ensuring that every update to the package catalog is fully compatible with the end-user's CLI environment.