zpl_toolchain_spec_compiler 0.4.0

Spec-file compiler that generates parser tables and documentation for ZPL commands
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

# zpl_toolchain_spec_compiler

Part of the [zpl-toolchain](https://github.com/trevordcampbell/zpl-toolchain) project.

## Purpose
- Validate per-command JSONC files under `spec/commands/` against `spec/schema/zpl-spec.schema.jsonc`.
- Merge into a single registry and emit generated artifacts:
  - `generated/parser_tables.json`
  - `generated/constraints_bundle.json`
  - `generated/docs_bundle.json`
  - `generated/coverage.json`

## CLI
```bash
zpl-spec-compiler build --spec-dir spec --out-dir generated
zpl-spec-compiler check --spec-dir spec
```

## Inputs
- `spec/commands/*.jsonc`: one file per command family (`codes[]` + `arity` + `signature` + `args/constraints`).
- Schema reference: `../../spec/schema/zpl-spec.schema.jsonc`.

## Outputs
- `parser_tables.json`: canonical table set consumed by parser/validator (includes the opcode trie inline), per-command `structuralRules`, and top-level `structuralRuleIndex` (by kind/trigger/effect).
- `constraints_bundle.json`: constraints extracted per command code (not consumed at runtime; available for external tooling such as IDE plugins and documentation generators).
- `docs_bundle.json`: per-code docs view with signature, args, docs, enumValues, composites.exposesArgs, missingFields (not consumed at runtime; available for external tooling).
- `coverage.json`: present/missing counts; per_code stats (arg_count, union_positions, missing fields, validation_errors).

## Notes
- Comments are allowed in source JSONC; the compiler strips them before validation.
- The compiler passes through fields to `spec-tables` structures and performs cross-field validation (signature/args/composites/overrides; arg hygiene), including structural rule binding validation.
- A `constraint_kinds_match_schema` test validates that `ConstraintKind::ALL` (the Rust enum) and the JSONC schema's `kind` enum stay in sync.
- A structural trigger invariant test validates `CommandEntry` trigger flags align with `structuralRuleIndex.byTrigger`.
- Schema version policy is strict: all loaded spec files must use a single schema version, and it must match the compiler `SCHEMA_VERSION` constant. Mixed or unexpected versions fail `check`/`build`.