RFC-0012 · Gnomon Tooling
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.
| Status | Draft corpus. Reference catalogs and RDF projections have generation drift checks; Gnomon proofs and projection semantics remain unverified for release. |
|---|
View the generated reference catalog →
Read design questions and decisions →
Status: Draft Owners: DX, Compiler
1. Scope
Defines the canonical tooling surface for Gnomon: the formatter (gnomon fmt), compiler flags, CI integration requirements, and the language server protocol contract. This RFC governs the developer experience layer; it does not define language semantics (RFC-0008) or the annotation system (RFC-0011).
Tooling defined here MUST be consistent with the language grammar (RFC-0008 §8) and MUST NOT introduce behavior that contradicts any normative statement in the RFC suite.
2. Goals
- One canonical source representation for every valid
.gnmfile — no style debates, no configuration drift - AI-authored and human-authored files are indistinguishable in canonical form
- Compiler internals (desugar pass, symbol table) are inspectable for debugging and conformance testing
- CI enforcement is normative and defined by this RFC, not left to project convention
- The language server provides a consistent, spec-derived authoring experience across all editors
Linked References
The cross-RFC dependency graph is rendered in reference catalog § Linked References. Out-of-KG pointers to legacy code or external resources, when present, remain in this document under “Source-tree references” below.
3. Invariants
gnomon fmtMUST produce identical output for any two.gnmfiles with the same semantic content, regardless of original formatting.gnomon fmtMUST be sugar-preserving: it MUST NOT desugar source files. The canonical formatted form is the human-readable source, not the IR.gnomon fmtMUST NOT change the semantic meaning of any declaration.- The
--print-desugaredflag MUST produce the exact AST that the compiler passes to the semantic analysis phase. Any divergence is a compiler defect. - Every MCP tool and AI agent that writes
.gnmfiles MUST pipe output throughgnomon fmtbefore writing (RFC-0009 §6.4). gnomon fmt --checkMUST be a required CI step. Failure to enforce this in CI is a project governance violation.
4. gnomon fmt: Canonical Formatter
gnomon fmt is the single canonical formatter for all .gnm source files. It is non-configurable and deterministic: for any valid .gnm input, gnomon fmt produces exactly one output. There are no configuration files and no per-project options.
4.1 Design Commitments
- Non-configurable. No
.gnomon-fmt.yaml, no per-project options. One canonical form across all projects and teams. - Sugar-preserving.
@SensitiveDataremains@SensitiveData. Bare fields remain bare fields. The formatter works on the parse tree before desugaring. - Idempotent.
gnomon fmtapplied twice produces the same result as applied once. - Total.
gnomon fmtMUST handle every syntactically valid.gnmfile, including files with only partial declarations. It MUST NOT refuse to format a valid file.
4.2 Canonical Property Ordering
Within any declaration body, gnomon fmt enforces the following property ordering. Properties of the same group may appear in any relative order within the group; gnomon fmt preserves source order within each group.
| Group | Properties | Applies to |
|---|---|---|
| 1 | @ decoration lines (above the keyword line, alphabetical by facet name) | all declarations |
| 2 | annotations { } block | all declarations |
| 3 | meaning, purpose | all declarations |
| 4 | is, flow | entity, type, facet |
| 5 | includes | entity, type, facet (semantic composition) |
| 6 | fields { } block, bare field declarations | entity, type, facet |
| 7 | actor, preconditions, effects, mustSatisfy | action, invariant |
| 8 | requiredEvidence, allowedStatus, policies { } | agent, claim |
| 9 | states, transitions, rules | flow |
| 10 | input, outputs, returns | action, query |
| 11 | show, explain, actions, layout, data, for | view |
| 12 | provider, name, digest, version, parameters { }, roles | model |
| 13 | ruleCompiler, promptTemplate | compiler block (project.gnm only) |
| 14 | audience, version, includes (bundle entries) | app, project |
| 15 | examples | all declarations |
Unrecognized properties are preserved at the end of the block in source order. gnomon fmt emits warning F12700 for each unrecognized property it encounters.
4.3 Formatting Rules
- Indentation: 2 spaces per level. Tabs are converted to 2 spaces.
- Trailing commas: always present on the last item in multi-line
ident-setandstring-seqvalues. - Blank lines: exactly one blank line between top-level declarations. No blank lines inside a declaration body.
gnomon fmtMUST remove intra-body blank lines to produce canonical output. (Formatter Invariant 1 requires identical output for semantically identical content; preserving optional blank lines would violate it.) - String quoting: double quotes only. Single-quoted strings are normalized to double quotes.
- Doc comments:
///lines are placed immediately above their declaration with no blank line between the last///line and the declaration keyword. - Decorator lines: one
@FacetNameper line, alphabetical, no blank lines between decorators or between the last decorator and the declaration keyword. - Line length: no hard limit. Long string values are not reflowed.
- Trailing newline: every file MUST end with a single newline character.
- Compiled-rule comments:
//compiled:and//compiled-by:structured comments immediately following arule "..."statement MUST be preserved verbatim and MUST remain on the line(s) immediately after the rule statement with no intervening blank lines (RFC-0008 §11.3). - Epistemic modifiers:
draft,deprecated,experimental,sealed, andabstractmodifiers are formatted as part of the declaration header line, before the declaration keyword.gnomon fmt --checkin CI MUST NOT suppress or hide epistemic modifier presence; they are visible in formatted output.
4.4 CLI Interface
gnomon fmt [options] [path...]
Options:
--check Exit non-zero if any file differs from canonical form; do not write files
--diff Print unified diff of proposed changes without writing
--stdin Read from stdin, write canonical form to stdout
--verify Exit 0 if file is already in canonical form, exit 1 if not; read-only (no file modifications). For pre-commit hooks and local checks.
Exit codes:
0 All files are already canonical (or --check passed, or --verify passed)
1 Formatter encountered a syntax error (file is not valid .gnm); also exit 1 in --verify mode if file is not in canonical form
2 Files differ from canonical form (--check mode only)
path may be a file, directory (recursive), or omitted (formats all .gnm files in the project from project.gnm root).
4.5 CI Enforcement
gnomon fmt --check MUST be a required step in every project CI pipeline. Exit code 2 MUST fail the CI build. This is a normative requirement, not a recommendation.
Formatter violations are not compiler diagnostics (M08xxx range). They use the F prefix:
- F12700: Unrecognized property encountered during formatting (warning, file is still formatted)
- F12701: File does not end with a newline (auto-corrected by
gnomon fmt, exit code 2 for--check)
4.6 AI Authoring Contract
Every MCP tool, AI agent, or automated process that produces .gnm file content MUST pass that content through gnomon fmt before writing to disk or returning it to the user. This is a normative requirement from RFC-0009 §6.4. A file written by an AI tool that is not in canonical form is a compliance violation of the AI authoring contract.
5. Compiler Flags
5.1 --print-desugared
Emits the post-desugar AST to stdout before semantic analysis. The output format is the canonical block form of the grammar (RFC-0008 §8) with all sugar forms expanded. This flag is the primary tool for:
- Verifying that a sugar form expands as expected
- Debugging desugar pass behavior
- Generating input for conformance test fixtures (RFC-0008 §8)
The output MUST be valid .gnm source that passes gnomon fmt --check without modification.
5.2 --print-symbol-table
Emits the unified symbol table after semantic analysis to stdout in a structured format (JSON or YAML as specified by --format). Useful for tooling that needs to inspect declaration resolution.
5.3 --print-annotation-map
Emits the resolved annotation map for every declaration after the annotation merge pass (RFC-0011 §5). Output includes the source of each annotation value (inline, decorator, aspect) for traceability.
5.4 --format
Specifies the output format for --print-* flags. Values: json (default), yaml.
6. Grammar Conformance CI
The normative EBNF grammar in RFC-0008 §8 MUST be extracted as a standalone PEG grammar file and validated in CI. This section defines the CI contract.
6.1 Extraction
A CI step MUST extract all ebnf code blocks from RFC-0008 §8 (and RFC-0011 §4 for the annotation extensions) into a single canonical grammar file: grammar/gnomon.peg. This file is a derived artifact; the source of truth is the RFC text.
6.2 Validation
The extracted grammar MUST be validated by a PEG parser generator on every RFC commit. Validation fails if:
- Any production rule is syntactically invalid
- Any production references an undefined non-terminal
- The grammar is ambiguous (where PEG ambiguity detection is available)
6.3 Conformance Test Fixtures
Each non-trivial grammar production MUST have at least one successful conformance fixture: a concrete .gnm snippet paired with its expected canonical AST. Failing fixtures MUST pair a .gnm snippet with expected diagnostics and require rejection. Fixtures live in grammar/fixtures/. The CI pipeline MUST:
- Extract the grammar
- Validate the grammar
- Run successful fixtures through the extracted grammar and compiler, compare their canonical ASTs to the expected AST, and assert no errors
- Run failing fixtures through the appropriate grammar or compiler stage, compare the expected diagnostics, and assert rejection
A production without a fixture fails the CI build (warning in draft status, error in accepted status).
7. Language Server Protocol (LSP) Contract
Do not implement from this section. RFC-0017 is the sole normative specification for the LSP contract. This summary is retained for historical context only.
Superseded. The normative LSP contract has been extracted into RFC-0017: Gnomon LSP Contract. RFC-0017 is the authoritative specification for all
gnomon lspbehavior including completions, hover, diagnostics, the rule compiler feedback loop, and model-aware editing.RFC-0012 retains responsibility for the
gnomon fmtformatter, compiler flags, and CI enforcement. RFC-0017 takes responsibility for allgnomon lspbehavior.The summary below is retained for orientation; see RFC-0017 for normative detail.
The Gnomon language server (gnomon lsp) provides editor integration. Required capabilities:
| Capability | Summary |
|---|---|
textDocument/completion | Context-aware property, identifier, model, and annotation completions |
textDocument/hover | Declaration kind, meaning, visibility, model binding, compiled rule expression |
textDocument/definition | Resolve any QUALIFIED reference, model reference, or import path |
textDocument/diagnostics | All compiler M-codes; async rule compiler diagnostics |
textDocument/formatting | Apply gnomon fmt (identical output to CLI) |
textDocument/codeAction | Casing fixes, missing meaning, rule migration, model configuration |
| Rule compiler feedback | Ghost annotation showing compiled constraint expression; Accept/Convert/Edit gestures |
See RFC-0017 for the full normative contract.
Diagnostics
The diagnostic catalog for this RFC is authored in the structured Lean module and
rendered in reference catalog § Diagnostics. Inline mentions in
the prose above (e.g., “rejected with MNNxxx”) cross-link to the catalog
at render time.
9. Security and Authorization
gnomon fmtMUST NOT execute any code from the formatted file. It is a pure syntactic transformation.--print-*flags MUST NOT execute any user-defined code or invoke any runtime component.- AI authoring contract enforcement (§4.6) is a normative security requirement: unformatted AI-authored files bypass the canonical form guarantee and may obscure malicious content differences from human reviewers.
10. Compatibility and Migration
- Changing the canonical property ordering (§4.2) is a breaking change to
gnomon fmtand MUST increment the formatter version. - Adding new properties to the ordering table is a non-breaking change; unknown properties are placed at the end.
- Adding new compiler flags is a non-breaking change.
- Changing the output format of
--print-*flags is a breaking change.