zpl_toolchain_spec_compiler 0.4.0

Spec-file compiler that generates parser tables and documentation for ZPL commands
Documentation

zpl_toolchain_spec_compiler

Part of the 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

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.