Module grammar 

CLI grammar: one introspected source of truth for the command surface.

Ports the lazaret nu/grammar.nu idea (INTERFACE / dump / violations / check) onto clap: every signature fact comes from each bin’s Args::command() via clap::CommandFactory — never a hand-maintained list. check fails on any new violation and on any baseline entry that no longer reproduces, so the baseline can only shrink.

Rules enforced by violations:

• global-flags — introspected bins expose exactly the pinned root long-option vocabulary (PINNED_ROOT_LONGS); missing and unexpected spellings both violate.
• selector — selector (node/set-selection) options match PINNED_SELECTORS exactly per (bin, subcommand); missing and unexpected selectors both violate. molt pins an empty set; cast subcommands are strict whitelists.
• registry — every bin maps to an existing source file and ships a tests/<bin>_tests.rs.
• compat — claw/molt/pinch short flags equal the frozen upstream ClusterShell sets (parity is pinned by the consortium-tests oracle).
• typed — every introspected argument carries help text.

Structs

CheckReport

Result of comparing the live grammar against a baseline.

Row

One introspected argument (or a registry placeholder row for the non-introspected cascade bins).

Violation

One rule violation, addressable by rule bin subcommand arg. The subcommand distinguishes the same argument ID on different subcommands (e.g. cast build --tag vs cast deploy --tag); root-level violations use the explicit ROOT marker.

Constants

KINDS

Module kinds. legacy: upstream ClusterShell parity surface (frozen); orchestration: new surface, free to evolve. cascade-copy is registry-checked but not introspected (its Args stay private in src/bin/); the cascade CLI surface lives in cast and is introspected through it.

PINNED_ROOT_LONGS

Exact reviewed root long-option vocabulary per introspected bin. global-flags rejects both missing and unexpected spellings; clap’s autogenerated help/version are excluded.

PINNED_SELECTORS

Exact selector (node/set-selection) long-option vocabulary per (bin, subcommand); "" denotes the root command. Both directions are enforced: a pinned selector missing from the live grammar and a selector-like option outside the pinned set both violate. molt (stdin aggregator) pins an empty set. cast subcommands are strict: any non-shared long option outside the pinned set violates, so arbitrary unknown selectors (e.g. cast eval --zone) are rejected even though they are absent from the cross-bin vocabulary.

PINNED_SHORT_FLAGS

Frozen upstream short flags (clush/clubak/cluset compat). The shared OutputArgs shorts (-v, -F) are consortium additions and are excluded from this comparison; long-only upstream flags are unaffected.

ROOT

Unambiguous root marker in baseline keys; no subcommand may be named this, so rule bin (root) arg can never collide with a subcommand key.

SHARED_FLAGS

Shared output vocabulary every introspected bin must expose at its root (from output::OutputArgs).

Functions

check

Compare live violations with the baseline file (JSON array of rule bin subcommand arg keys, root level marked ROOT). Errors on new, stale, or duplicate entries.

check_keys

Pure new-vs-stale comparison over baseline keys: errors when the live set has keys the baseline lacks (new violations) or the baseline has keys that no longer reproduce (stale entries — the baseline can only shrink). Returns the live violation count on success.

dump

One row per exported argument across all bins, straight from clap — the same data a human reads off --help, as a table.

key_of

Stable join key for baseline comparison.

manifest_bins

[[bin]] entries parsed from a Cargo.toml manifest, in declaration order: (name, path) with path relative to the manifest directory (Cargo’s default src/bin/<name>.rs when path is omitted).

registry_violations

Registry rule evaluated live against a Cargo.toml manifest (whose directory is the crate root holding src/ and tests/). Used by temporary-manifest tests; production uses the embedded build facts.

violations

Interface rules evaluated against the live grammar.