schemagen

Overview ¶

Command schemagen is the dev-time companion code generator for the `spec` package. It is invoked ONLY by `task cue:gen` (never at runtime) and has two modes:

-mode=concat -out=<file>   Concatenate schema/*.cue into one file
                           headed `package spec` + the file-level `@go(spec)`
                           attribute, ready for `cue exp gengotypes`.
-mode=vocab  -out=<file>   Compile the concatenation via the embedded
                           cuelang.org/go API and emit spec/vocab_gen.go
                           — the single-source vocabulary lists (kind keywords,
                           document directives, step keywords, contexts, the
                           flat #Op verb/modifier field set, and the live-verb
                           method allowlists).

CONCATENATION CONTRACT (R3): concatSchema replicates EXACTLY the mechanism the runtime uses in charly core (cue_schema.go) `sharedCueSchema` — every package-less schema/*.cue file, sorted by name, joined with a trailing newline. The runtime reads the files from `//go:embed`; this tool reads them from disk (it runs at dev time with the working tree present). If you change the runtime concatenation order, change it here too — the two MUST stay byte-identical or the generated Go types drift from what the runtime validates.

PARAM-GEN SCOPE (the two modes diverge by INPUT, not by mechanism): the `vocab` mode reads the FULL schema (every schema/*.cue) — it needs #Node's arms (node.cue) to derive KindWords, so its concatenation stays byte-identical to the runtime `sharedCueSchema`. The `concat` mode (which feeds `cue exp gengotypes` → the Go param structs) reads the schema MINUS node.cue: it defines the node-disjunction wrappers (#Node/#NodeDoc/#*Arm/#*Value), which gengotypes degrades to `map[string]any` and which are NOT charly param structs. (The egress validation schemas moved to candy/plugin-egress in M16, so they no longer live here to exclude.) The entity defs (#Box/#Deploy/#Op/#Vm/…) do not reference node.cue, so the exclusion is compile-clean. Both modes share the ONE concatSchema helper (R3); only the file filter differs.