RFC-0012 · Design Q&A
Versioned draft snapshot
RFCs, reference catalogs, and evidence reflect Spec 3b2e3e7a114fb826b1445d39a48756b8fff629cd. Counts and pending/status notes belong to that snapshot. Read the dated project update for later progress.
Source repositories are private during staging. Links marked “repository access required” need access to the linked repository.
Q: Should gnomon fmt be a separate binary or a subcommand?
A: gnomon fmt is a subcommand of the main gnomon CLI, consistent with gnomon build, gnomon test, gnomon update. A separate binary would fragment the toolchain installation story and create version-skew risk between formatter and compiler. The formatter accesses the compiler’s grammar, so they MUST be the same version.
Where normative: §3 (CLI structure) of RFC-0012
Q: Should the LSP server be bundled with the gnomon CLI or distributed as a separate package?
A: Bundled with the gnomon CLI (gnomon lsp subcommand). Bundling ensures the formatter, compiler, and LSP server are always the same version, eliminating a class of version-skew bugs where the LSP produces diagnostics based on a different grammar than the compiler.
Where normative: §3 (CLI structure) of RFC-0012
Q: Should conformance fixtures be authored in a dedicated format or as separate paired files?
A: Separate paired files. Each conformance fixture is a pair of files: <name>.gnm (the input to compile) and a companion expected-output file (the canonical AST for a successful input or diagnostics for a failing input). This format is the simplest to add and review — pull requests show the input and expected output side by side. A single-file annotated format would require a custom parser and complicate tooling for non-Gnomon editors.
Where normative: §6.3 (conformance test fixtures) of RFC-0012
Q: Should gnomon fmt have a --verify mode?
A: Yes. gnomon fmt --verify asserts that the formatted output is byte-for-byte identical to the input (i.e., the input is already in canonical form). Exit code 0 if canonical, exit code 1 if not. This is used in CI to enforce that committed .gnm files are always formatted. The mode MUST NOT modify any file — it is read-only. Canonical usage: gnomon fmt --verify ./... in CI pre-push hook.
Where normative: §4 (formatter) of RFC-0012
Owner decision (2026-10-05)
The owner selected expected canonical ASTs for successful fixtures and expected
diagnostics for failing fixtures. Section 6.3 now distinguishes these outcomes.
The protobuf fixture-envelope schema and comparison runner are implemented.
Canonical language AST messages, real parser/compiler and diagnostic adapters,
and the executable conformance corpus remain outstanding; see
../../RFC0012_FORMATTER_CONTRACT_PROPOSAL.md.