Codebase / Codebase development standards

Codebase development standards

Good compiler work should be easy to read, easy to test and hard to misinterpret. These references cover implementation style, test design and the validation gates that show a change is ready.

Codebase style guide

This document owns implementation style for new and refactored compiler code.

For test strategy and test construction, read docs/src/docs/codebase/style-guide/testing.mtf.

For final technical gates and completion checks, read docs/src/docs/codebase/style-guide/validation.mtf.

Priorities:

1. Readability
2. Modularity
3. Correctness and diagnostics

No user-input panics

• Active frontend stages must reject unsupported syntax and malformed input with structured diagnostics, not panic!, todo! or user-data-driven .unwrap().
• Panic paths are only for proven internal invariants that indicate a compiler bug.

Diagnostics

• Use CompilerDiagnostic for normal user-facing source, config, import, syntax, type, rule, borrow and deferred-feature diagnostics.
• Use CompilerError only for internal compiler, filesystem, backend, dev-server and tooling infrastructure failures.
• Diagnostic payloads and reason enums should carry structured facts, not pre-rendered prose.
• Preserve SourceLocation and source labels wherever the compiler can point to useful source context.
• Type diagnostics should carry semantic TypeIds and render them through DiagnosticRenderContext, not cloned DataType values or formatted type names.
• Use DiagnosticBag for stage-local accumulation and CompilerMessages only at build/render boundaries.

For test assertion policy, see testing.mtf.

Naming

• Use descriptive full names. Avoid abbreviations except simple iterators such as i and j.
• Functions should be self-describing through clear names.
• Compiler passes should use explicit names such as build_ast, generate_hir and emit_wasm.

Avoid vague names when they cross more than a few lines or function boundaries:

• prefer function_signature over sig.
• prefer expression over expr outside tiny scopes.
• prefer data_type or the concrete type name over ty.
• prefer scope_context or module_environment over ctx or env when several contexts/environments exist.

format! and printing

• Use the saying library macro say!() for stdout when creating user-facing messages that may need colour styling in the future.

Use variables directly in format! strings whenever possible.

Imports

Avoid inline imports. They are only acceptable when they are one level deep and help local reasoning.

    // ACCEPTABLE: builtin_type_ids is imported, but kept inline because it's terse and clear.
    let type_id = builtin_type_ids::BOOL

    // BAD: large inline import, even if this is only used once, it's too noisy inline.
    let type_id = crate::compiler_frontend::datatypes::ids::builtin_type_ids::BOOL

    // BAD: inline imports with long paths should be imported at the top, even if only used once.
    fn lookup_constant(
        &self,
    ) -> Option<(
        crate::compiler_frontend::external_packages::ExternalConstantId,
        &crate::compiler_frontend::external_packages::ExternalConstantDef,
    )> {
        ...
    }
    

Avoid aliasing unless it clearly improves readability.

Code style and organisation

• Maintain clear separation between compilation stages.
• Each module should have one clear responsibility. Don't mix concerns.
• Split files by task category. Aim for files under ~2000 lines where practical.
• mod.rs should be the module entry point and structural map. It exposes the public surface, shows the flow of the module and points to the files that contain the real implementation.
• Keep mod.rs focused on orchestration, re-exports and documentation rather than core implementation.
• A reader should be able to open mod.rs first and quickly understand what the module does, which stages or responsibilities it contains and where to find the important functions and types.
• Use comments and doc comments in mod.rs to explain the module's structure, data flow and why the pieces are arranged that way.
• Prefer context structs for shared state instead of passing many state values between functions.
• Separate unrelated statements and all functions with an extra newline.
• Keep new abstractions small, stage-local and easy to justify.
• Avoid .unwrap() unless it's blatantly safe and tied to an internal invariant.
• Prefer .to_owned() over .clone() when copying owned string-like data.
• Use .clone() when a general copy is genuinely required and clearer.

For test-file placement, see testing.mtf.

Readable Rust style

Compiler code should optimise for fast human review. Dense code is harder to scan and easier to extend badly.

Prefer code that reads as a sequence of named steps over dense expression chains, clever iterator nesting or large inline matches. The best code in this compiler should make the data flow obvious before the reader understands every detail.

Good compiler code has:

• clear stage ownership
• named intermediate values
• short functions with one job
• explicit control flow for multi-step logic
• narrow helper functions
• context/input structs instead of long parameter lists
• enums for meaningful states instead of loose booleans
• comments that act as reading landmarks
• vertical spacing between logical blocks

Avoid code that compresses too much logic into one expression. Brevity is less important than clarity.

Vertical spacing

Use vertical spacing to show structure.

Required:

• one blank line between functions.
• one blank line between unrelated statement groups.
• one blank line between major control-flow blocks inside long functions.
• one blank line between match arms unless the arms are tiny and visually identical.
• one blank line before a comment that introduces a new logical step.

Prefer this:

    let source_file = header.source_file.clone();
    let visibility = import_environment.visibility_for(&source_file)?;

    // Resolve type aliases before constants because constant folding may depend on alias-expanded types.
    self.resolve_type_aliases(&headers, visibility, string_table)?;

    self.resolve_constant_headers(&headers, visibility, string_table)?;
    

Avoid this:

    let source_file = header.source_file.clone();
    let visibility = import_environment.visibility_for(&source_file)?;
    self.resolve_type_aliases(&headers, visibility, string_table)?;
    self.resolve_constant_headers(&headers, visibility, string_table)?;
    

Comments as reading landmarks

Comments are encouraged when they make code faster to understand. They should be terse and focus on wider context rather than re-describing the code. Write comments aimed at programmers reading the codebase for the first time, trying to navigate around and understand how everything flows and is connected together in the wider picture.

Always:

• Add doc comments at the top of new files.
• Add concise WHAT/WHY comments in these top of file doc comments and for complex functions & methods (not small methods or helpers or self-describing code) and important structs.

WHAT comments should mostly provide context about what something does from the perspective of its role in the wider module / compiler. They should only help condense complexity or provide wider codebase/non-local context concisely.

Comments should help a reader understand code locally without reading large parts of the codebase first. They should not restate syntax, especially for functions with already descriptive names and signatures.

Be comment-positive, but not noisy.

They should explain:

• what role this code plays in the larger subsystem
• which later stage, caller or output consumes the result
• why the control flow is shaped this way
• invariants
• failure conditions
• subtle bug fixes
• non-obvious data flow
• important joins between phases
• unusual or project-specific code
• code used widely across the repository

Use terse comments to mark:

• stage boundaries
• non-obvious ordering requirements
• invariants
• why a fallback exists
• why a branch intentionally does nothing
• why an error is reported at this stage instead of a later stage
• control-flow joins in large functions
• the reason a helper exists

Good comments are grammatical, readable and explain intent:

    // Register same-file declarations before imports so aliases cannot shadow local names.
    for declaration in same_file_declarations {
        visible_names.register_same_file_declaration(declaration)?;
    }

    // Prelude names are registered as reserved names first, then inserted only if not shadowed.
    for symbol in external_package_registry.prelude_symbols() {
        visible_names.reserve_prelude_symbol(symbol)?;
    }
    

Refactor moves

When moving code across compiler stages, don't copy the old module shape unchanged. Use the move to correct ownership, names, APIs, comments and data flow.

Moved code must:

• remove obsolete wrappers and compatibility paths
• replace long parameter lists with context/input structs
• split mixed-responsibility modules
• update file-level docs to match the new owner
• delete the old owner once the new path is wired

Don't preserve a bad API shape just because it already exists.

API breakage

• Moth is pre-release. Backward compatibility isn't a priority.
• When APIs change, thread the new shape through the compiler and remove the old one.
• Don't add compatibility wrappers, forwarding shims, parallel structs or defaulted legacy entry points just to preserve an older interface.
• Prefer one current API shape, not transitional layers.

Type ordering

Order types in a file from higher-level abstractions to lower-level supporting types.

    pub struct HirModule { ... }
    pub struct HirBlock { ... }
    pub struct HirNode { ... }
    pub struct HirExpression { ... }
    

Iterators versus loops

• Use iterators for simple transformations.
• Use explicit loops for complex multi-stage logic where control flow is clearer.

    let mut processed_nodes = Vec::new();

    for node in ast_nodes {
        if let Some(ir_node) = convert_to_ir(&node)? {
            if ir_node.is_optimizable() {
                processed_nodes.push(optimize_node(ir_node));
            }
        }
    }
    

Function size

Functions should usually stay under ~200 lines. Longer functions are fine when they still represent one coherent operation, such as a compiler transformation, state machine or tightly coupled sequential process.

Split functions when they mix unrelated responsibilities, are hard to test or no longer match their name.

Match readability

Large matches should be grouped by meaning.

Use blank lines and short comments to make each group obvious. If a match grows too large, extract branch handling into named helpers.

Prefer:

    match resolution {
        // Constants create dependency edges.
        ConstantReference::SourceConstant { path, source_file } => {
            add_constant_dependency(header, path, source_file)?;
        }

        // Type names are valid to resolve but do not create value dependency edges.
        ConstantReference::SourceTypeAlias { .. } => {}

        // These are structurally invalid in constant initializers.
        ConstantReference::SourceNonConstant { path }
        | ConstantReference::ExternalNonConstant { .. } => {
            errors.push(non_constant_reference_error(path, location.clone()));
        }

        // Unknown names may produce better diagnostics during AST expression parsing.
        ConstantReference::Unknown => {}
    }
    

Avoid long ungrouped matches where every branch looks equally important.

Avoid clever Rust

Don't use advanced Rust features just to make code shorter.

Avoid:

• nested iterator chains with side effects
• clever Option / Result combinator pipelines for validation logic
• large closures with mutation
• broad generic helpers that hide compiler-stage ownership
• macro abstractions for ordinary compiler flow
• boolean-heavy APIs where an enum would explain the state
• tuple-heavy returns where a named struct would explain the result

Prefer named types and straightforward flow:

    pub(crate) struct ImportResolution {
        pub(crate) target: ResolvedImportTarget,
        pub(crate) local_name: StringId,
        pub(crate) location: SourceLocation,
    }
    

Instead of:

    Result<(ResolvedImportTarget, StringId, SourceLocation), CompilerError>
    

A few more lines are fine when the result is easier to inspect and harder to misuse.

Macros

• Keep macro usage minimal
• Use small declarative macros only where they clearly reduce repetition
• Avoid creating procedural macros

Warnings and lints

• Use clippy.
• Use the default Rust formatter.
• Keep unused variables and dead code to a minimum.
• Use allow(dead_code) attributes only with clear justification. Dead code must have a comment stating that it's a todo or used only in tests.

Section banners

Use section banners only in long functions, large files or complex orchestration code where phase boundaries help a reader jump into the process.

Use exactly this format:

    // ------------------------
    //  Resolve template slots
    // ------------------------
    

Rules:

• Three lines
• Top and bottom lines use // followed by dashes
• The title line starts with // and uses one extra leading space after the comment marker
• Dash lines should exceed the title text by the same amount on each side
• Use title case or clear imperative phase names consistently within the file
• Don't use banners around small helpers
• Don't use banners to hide a file that should be split

Good uses:

• parser phases
• compiler lowering phases
• template folding stages
• import resolution stages
• diagnostic rendering stages
• long build orchestration functions

Returning errors

The diagnostic system has two paths:

• CompilerDiagnostic is the current user-facing diagnostic type. Use typed payloads (DiagnosticPayload) and stable diagnostic codes. This is the correct path for all source-language diagnostics: syntax, type, rule, import, borrow and config.
• CompilerError is for internal/tooling failures only: compiler bugs, HIR lowering failures, filesystem errors and backend failures. Don't route user-facing diagnostics through CompilerError.

Rules for new code

• New user-facing diagnostics must use CompilerDiagnostic with typed constructors in compiler_diagnostic.rs. Don't add new CompilerError for syntax, type, rule, import or borrow diagnostics.
• Use return_compiler_error! only for internal compiler bugs or broken invariants.
• Use DiagnosticBag for stage-local accumulation of multiple diagnostics.
• Convert to CompilerMessages only at clear build/render boundaries.
• When a local Result error boundary carries CompilerDiagnostic or CompilerError and Clippy reports result_large_err, box the payload inside the local boundary enum or use a stage-local boxed diagnostic result alias.
• Keep DiagnosticBag and CompilerMessages owning plain CompilerDiagnostic values at accumulation and render/build boundaries.
• Prefer Option<CompilerDiagnostic> over Result<(), CompilerDiagnostic> for predicate-only validation helpers that only need to report one diagnostic or continue.
• Prefer explicit loops over iterator closures when the closure would infer Result<_, CompilerDiagnostic>.
• Include a SourceLocation for every user-facing diagnostic.
• Keep paths interned until render time. Don't duplicate them as owned PathBufs.
• New type diagnostics must carry semantic TypeIds and context enums, not rendered type strings or cloned DataType payloads.
• Render type names through the diagnostic render context.
• Be specific. Include exact tokens, types or names.
• Be helpful. Suggest corrections when practical.

Examples

    // Typed diagnostic constructor.
    return Err(CompilerDiagnostic::invalid_assignment_target(
        InvalidAssignmentTargetReason::ImmutableVariable,
        variable_name,
        location,
    ));

    // Internal bug path.
    return_compiler_error!(
        "Unsupported AST node type: {:?}",
        node_type; {
            CompilationStage => "AST Processing",
            PrimarySuggestion => "This is a compiler bug - please report it"
        }
    );
    

Codebase documentation

Codebase pages and Moth template references have different jobs.

• @page.moth owns the website page, title, introduction, navigation and layout
• overview.mtf provides a compact routing and contract reference and must not be imported by @page.moth
• Topic-named .mtf files own detailed design content
• Website pages may import topic-named .mtf files
• Topic-named .mtf files should remain useful when read directly
• Website pages should make the subject easy to explore
• Compact references should reach the contract quickly

Writing rules:

• Use British English.
• Avoid hollow intensifiers (incredibly, extremely, highly, pivotal, crucial, profound).
• Don't use semicolons, oxford commas and em dashes.
• Avoid filler (just, really, basically, actually, simply).
• Avoid excessive preambles or commentary about the structure or description of the document itself unless it is specifically required. Get to the point.
• DO NOT summarise the preceding text at the end of a section. If the point has been made, move on without concluding it.
• NEVER use generic transitions and transitional terms (however, therefore and consequently,furthermore, moreover, thus, herein, aforementioned, notably).
• Use direct, active language. Eliminate all passive constructions and copula verbs (is, has, serves as). Ensure the subject of every sentence directly performs the action. Don't mask verbs as nouns.
• Avoid hedging and vague qualifiers (various, numerous, several, to some extent, broadly speaking).
• Avoids restating or over-describing, cliché metaphors, culturally dated or pop culture language.
• Use contractions. Only keep hard must and must not language for deliberate stern emphasis.
• Use normal ' apostrophes, never U+2019.
• Mix up your sentence structure. Combine shorter, punchy sentences with longer, conversational ones in the same paragraph to create a more natural rhythm. Never write three consecutive sentences of similar length.
• Keep quotes or code syntax exact even when it contains punctuation or rule violations from this style guide.
• Example names must use "Priya" as a first choice for examples.

Style checklist

Before considering an implementation slice structurally complete, check:

• The module has one clear owner responsibility.
• The file-level documentation says what the module owns and must not own.
• The main function reads as a sequence of named steps.
• Complex blocks have concise intent comments.
• Imports remain readable and are not needlessly fully inline.
• Match arms are grouped by meaning.
• Unrelated blocks have visual spacing.
• Function arguments are not noisy or repetitive.
• Named states are used instead of boolean-heavy APIs.
• Error construction isn't duplicated across branches.
• The code avoids cleverness that slows review.
• No stale comments describe an older design.
• No compatibility wrappers preserve obsolete paths.
• Lint suppression is justified and documented.

Testing standards

This document owns test selection, test structure, assertions, fixture design and test pruning for compiler work.

It does not define the final validation command. For completion gates, read docs/src/docs/codebase/style-guide/validation.mtf.

The primary goal is end-to-end language and artifact correctness. Prefer real usage patterns and complete Moth snippets over narrow implementation-shaped tests.

Default testing preference

Integration tests written in Moth are the default for user-visible language behaviour. They exercise the real compiler path and usually provide the strongest regression coverage.

• Prefer integration coverage for user-visible language behaviour
• Add or update unit tests only where subsystem-local behaviour genuinely benefits from them
• Avoid redundant fixtures that assert the same behaviour in slightly different forms
• Prefer meaningful end-to-end cases over brittle implementation-shaped assertions
• When backend or runtime behaviour matters, strengthen artifact assertions where goldens alone are too vague

Supporting rules

• Prefer externally observable behaviour over implementation detail.
• Use unit tests for hidden invariants that integration output cannot inspect.
• Use one clear primary test owner per behaviour.
• Do not create multiple fixtures that prove the same contract without a distinct stage or backend reason.
• Prefer realistic end-to-end snippets.
• Tests should remain understandable without reading the implementation first.
• Do not make exact internal layout contractual unless that layout is the invariant.

Test ownership

Each behavior should have one primary owner. Secondary coverage is justified only when it protects a distinct boundary, target, diagnostic lane or internal invariant.

Test location and module layout

• Tests do not live in production implementation files.
• Module-specific tests belong under the module's test directory, for example:

        src/compiler_frontend/hir/tests/
    

• End-to-end or multi-module Rust harness tests belong under:

        src/compiler_tests/
    

• Language and project integration cases belong under:

        tests/cases/
    

• Test-only utilities should live with the tests that own them.
• Do not create broad shared test utility modules for one or two callers.
• Split cross-stage test support only when actual ownership boundaries justify it.

Unit tests

Retain unit tests for:

• pure data invariants
• impossible states
• side-table facts
• transfer rules
• backend planning policy not observable from artifacts
• narrow parser or formatter algorithms

Prefer integration tests for user-visible behavior. Once a subsystem is stable, prune superseded unit tests. Rewrite obsolete tests rather than preserving old API shapes. A unit test should name the invariant it protects. Do not use unit coverage as a substitute for an end-to-end case when user behavior changed.

Integration cases

• moth tests runs the integration test runner.
• Use real Moth snippets.
• Each canonical case is one self-contained scenario directory.
• Keep helper source files inside the owning case's input/ directory.
• Do not let helper files become unintended standalone cases.
• Add strong output assertions where behavior is visible.
• Prefer top-level templates to simulate output.
• Avoid io.line(...) unless console behavior is itself under test.

Successful backend intent

Every successful HTML and HTML-Wasm backend run applies its universal backend baseline. The baseline protects harness and target invariants. It is not the case's authored semantic contract.

Use success_contract = "acceptance_only" only when that backend has no stronger case-specific semantic, artifact, golden, absence or expected-warning assertion.

        [backends.html]
        mode = "success"
        warnings = "forbid"
        success_contract = "acceptance_only"
    

Acceptance-only intent does not disable the baseline. The audit records both baseline_applied = true and acceptance_only = true, with backend_baseline and acceptance_only in assertion_kinds.

Do not combine acceptance-only intent with artifact assertions, golden mode, rendered-output assertions, artifact-absence assertions or an authored expected-warning contract. A whole case whose backends are all acceptance-only uses role = "smoke". A mixed-backend case may use a boundary or backend role when another backend owns a stronger contract.

A successful backend with only the universal baseline is invalid. Typed fixture loading rejects it before policy evaluation, listing, audit, or execution.

For new type-system syntax, include:

• positive usage
• value/type namespace misuse
• import visibility
• duplicates
• cross-file resolution
• target/backend rejection where relevant

Canonical fixture shape:

        tests/cases/
        ├── manifest.toml
        └── case_name/
            ├── input/
            │   ├── main.moth
            │   └── helper.moth
            ├── expect.toml
            └── golden/
                ├── html/
                └── html_wasm/
    

• manifest.toml is the authoritative case order. Every case declares a unique canonical id, unique fixture path and at least one non-empty tag.
• Manifest case paths are relative and may not contain absolute, platform-prefix, parent or current-directory components. Canonicalised fixture roots must remain inside tests/cases/, including through symlinks.
• IDs, paths, tags, contracts, roles and configured entries reject leading or trailing whitespace. Tags within one case must be unique.
• Every canonical case declares a role. Supported roles are primary, boundary, backend, adversarial and smoke.
• Every non-smoke case declares a contract. A whole-case acceptance-only smoke may remain contractless because it has no case-specific semantic owner. Do not invent a contract for it.
• A primary case requires a contract, and one contract may have at most one primary case.
• A contract family without a primary is reported once in manifest order. Backend-only and adversarial-only families are deliberate advisories. Mixed or ordinary secondary-only families remain visible for ownership review.
• Case IDs, tags, contracts and roles are retained as typed runner metadata. Do not reconstruct them from display text or fixture paths.
• One case folder owns all inputs and expectations for that scenario.

Manifest entry shape:

        [[case]]
        id = "borrow_conflict_resolved_by_reordering"
        path = "borrow_conflict_resolved_by_reordering"
        tags = ["integration", "borrows"]
        contract = "language.bindings.alias_final_use_allows_mutable_rebinding"
        role = "primary"
    

Focused integration selection and inventory

Use the canonical case ID and retained metadata for local iteration:

        cargo run --quiet -- tests --case arithmetic_operator_precedence --backend html
        cargo run --quiet -- tests --tag borrows --tag diagnostics --backend html
        cargo run --quiet -- tests --contract 
        cargo run --quiet -- tests --list --tag borrows
    

• --case and --contract are exact matches.
• Repeatable --tag filters compose as logical AND.
• Case, tag, contract and backend filters compose and preserve manifest/backend order.
• --list accepts selection filters and reports canonical ID, selected backend blocks, tags, contract and role without compiling cases.
• Duplicate singleton options, duplicate tag values, missing values, unknown flags and positional arguments are errors.

Use the audit mode to validate and inventory the complete canonical suite without compiling cases:

        cargo run --quiet -- tests --audit
    

Audit writes its JSON inventory before returning hard-policy failure. Normal listing and execution use the same policy evaluator and reject hard findings before compiling a case. Missing roles, missing contracts on non-smoke cases, primary cases without contracts and duplicate primary owners are hard findings. Contractless whole-case acceptance-only smoke cases are valid.

Audit cannot be combined with filters or --list. It writes the reporting-owned JSON inventory to target/test-reports/integration_suite_inventory.json, including canonical metadata, backend expectation facts, hard-policy violations and primary-less contract-family advisories. The report is review input only; it never deletes, merges or rewrites fixtures.

The schema 6 inventory reports acceptance-only, rendered-output, artifact, golden, absence and expected-warning backend counts, plus the zero baseline-only invariant. It reports exact, ordered and exact-once runtime contracts separately. Per-backend fields keep baseline_applied, acceptance_only, assertion_kinds, golden_present, golden_mode, every rendered-output form, exact warning codes, diagnostic match mode and any contains-mode reason separate so the report matches what ran.

Hard policy has one suite-policy owner. Missing roles, missing non-smoke contracts, duplicate primary contracts, a primary without a contract and a whole-case acceptance-only fixture without role = "smoke" are hard findings. Normal list and execution modes reject hard findings before selection or compilation. Audit still writes the complete JSON report, then returns failure. Primary-less contract-family advisories remain non-fatal.

Runtime output assertions

Runtime assertions use one Node harness. It records console output and HTML fragment inserts in one event array when each event happens, then joins their text with newlines in that same order. Channel views are derived from the event array. They never reconstruct chronology after execution.

The harness runs only when a backend declares a rendered-output assertion. It executes the emitted page scripts and waits for one documented microtask tick so scheduled reactive updates can flush. Do not make extra scheduler turns or incidental microtask counts contractual.

Choose the narrowest field that owns the behaviour:

• rendered_output_exact protects the complete combined output. It is mutually exclusive with the other rendered-output fields. Exact comparison normalizes line endings only and preserves every other whitespace difference.
• rendered_output_contains_in_order protects the relative order of two or more fragments.
• rendered_output_contains_exactly_once protects activation, mounting and helper output from duplication.
• rendered_output_contains and rendered_output_not_contains protect required and forbidden fragments when complete output isn't the contract.

        [backends.html]
        mode = "success"
        warnings = "forbid"
        rendered_output_contains = ["active-root"]
        rendered_output_not_contains = ["imported-root"]
        rendered_output_contains_in_order = ["before-loop", "after-loop"]
        rendered_output_contains_exactly_once = ["active-root", "mounted"]
    

Use exact output for small deterministic behaviours such as loop or map operation results. Use ordered and exact-once fragments when unrelated output may coexist. Prefer these runtime contracts over generated JavaScript text or a whole-page golden when execution is the real owner.

Diagnostics assertions

• Ordinary source/config/import/type/rule/borrow failures should assert stable diagnostic_codes.
• diagnostic_codes is an exact unordered multiset by default. Repeat a code when the diagnostic must occur more than once.
• Add rendered message fragments only when wording or rendered labels are part of the contract.
• Infrastructure-boundary tests may assert infrastructure ErrorType.
• Preserve source location assertions where location behavior is important.
• Do not use full rendered diagnostic snapshots when a stable code and structured assertion are sufficient.
• Do not weaken a diagnostic case into a generic "must fail" assertion.

        [backends.html]
        mode = "failure"
        warnings = "forbid"
        diagnostic_codes = ["MOTH-RULE-0033", "MOTH-RULE-0033"]
    

Use diagnostic_assertions when a broad code needs a compiler-owned reason or when source remapping is part of the contract. Each table selects one diagnostic by stable code and one-based occurrence. A unique code may omit occurrence. Repeat the code in diagnostic_codes to preserve its exact multiplicity.

        [[backends.html.diagnostic_assertions]]
        code = "MOTH-RULE-0057"
        reason = "invalid_generic_instantiation.recursive_function_instantiation"
        path = "input/@page.moth"
        line = 3
        count = 1

        [[backends.html.diagnostic_assertions.secondary_labels]]
        occurrence = 1
        path = "input/helpers.moth"
        line = 2
    

• Reason keys come from the compiler payload identity. The runner must not invent a parallel reason taxonomy or derive identity from rendered text.
• Paths are normalized relative to the owning fixture and lines are one-based display lines.
• Assert columns only when exact token-span precision is the contract.
• A secondary-label occurrence is one-based among that diagnostic's secondary labels in emitted order. Assert only the labels whose location or ordering is the behaviour owner.
• Keep message_contains only when rendered wording or label prose is itself contractual.

Use diagnostic_match = "contains" only when intentional independent recovery or cascades make additional diagnostics part of the accepted current behaviour. Every contains-mode block needs a substantive diagnostic_match_reason. The suite audit reports the reason and treats a missing or blank reason as a hard policy finding.

        diagnostic_match = "contains"
        diagnostic_match_reason = "Independent recovery may emit additional diagnostics from another source unit."
    

Warnings use a separate backend-local contract:

• warnings = "forbid" rejects every warning and accepts no warning_codes field.
• warnings = "ignore" deliberately makes warnings non-contractual and accepts no warning_codes field.
• warnings = "exact" requires warning_codes as an exact unordered multiset. Repeat duplicate codes to preserve their required count.

        [backends.html]
        mode = "success"
        warnings = "exact"
        warning_codes = ["MOTH-RULE-0022", "MOTH-RULE-0022"]
        rendered_output_contains = ["warning-contract result=one"]
    

Backend matrices and artifact assertions

Use one expect.toml per case with backend-specific assertion blocks.

        entry = "."

        [backends.html]
        mode = "success"
        warnings = "forbid"
        artifacts_must_not_exist = ["unexpected.html"]

        [backends.html_wasm]
        mode = "success"
        warnings = "forbid"

        [[backends.html_wasm.artifact_assertions]]
        path = "page.wasm"
        kind = "wasm"
        validate_wasm = true
        must_export = ["memory", "moth_str_ptr", "moth_str_len", "moth_release"]
    

• Use backend-specific blocks within one case.
• entry = "." is the one supported current-directory sentinel and selects the case's input/ directory. Every other entry is a relative contained path with no absolute, platform-prefix, parent or current-directory component. Its canonical path must remain inside the owning input/ directory, including through symlinks.
• Store strict goldens in:

        golden//
    

• Use artifact assertions for structure: file presence, Wasm validity, exports, imports, expected snippets, absence of forbidden output.
• Use artifacts_must_not_exist for success cases whose contract requires an exact normalized output path to be absent. Paths reported as NotBuilt are ignored because they were never emitted.
• Use strict goldens only where exact emitted text is contractual.
• The canonical suite currently has no file-backed golden blocks. A future golden needs an explicit exact-artifact rationale that a runtime or narrow artifact assertion cannot express.
• Golden discovery recursively counts actual files. Empty or directory-only golden trees do not create a contract. Nested files do.
• golden_mode without at least one discovered file is invalid. When files exist, strict is the default if no mode is authored. When no files exist, audit reports golden_present = false and golden_mode = null.
• Prefer semantic or rendered-output assertions for behavior-first cases.
• Strengthen artifact assertions when a golden can pass while structural behavior is wrong.
• Do not require unsupported backends to succeed merely for matrix symmetry. Assert the intended rejection contract.

HIR and internal-IR assertions

• Assert semantic relationships rather than incidental indexes.
• Prefer branch joins, merge-local relationships, jump arguments, region ownership, side-table keys, stable call targets and required operation kinds.
• Avoid exact block IDs or vector offsets unless exact layout is the invariant.
• Do not make temporary lowering order part of the public test contract.
• For HIR validation, distinguish malformed-HIR invariant tests from user-facing source diagnostic tests.

Fixtures and temporary files

• Prefer tempfile::tempdir() for temporary directories and files.
• Use unmanaged paths only when the test intentionally owns cleanup.
• Keep fixtures local to their owner.
• Do not commit generated dev/ or release/ outputs from test or benchmark projects.
• Avoid shared fixture builders that hide important source shape.

Pruning and duplicate coverage

• Remove tests tied only to deleted implementation paths.
• Avoid several fixtures that differ only cosmetically.
• Preserve duplicates only when they protect different stages, diagnostic reasons, backends, source locations or artifact contracts.
• Localize one-caller fixtures.
• When two tests overlap, identify the primary owner and either merge them, narrow each to a distinct invariant or delete the weaker one.
• Do not preserve obsolete fixtures for historical compatibility.

Benchmarks are not correctness tests

Benchmark fixtures are performance evidence, not correctness coverage.

Do not use benchmark coverage as a substitute for unit or integration tests. Negative diagnostics belong in tests/cases, not benchmark fixtures.

Use bench-check to detect broad performance regressions after correctness has already been established by ordinary tests.

Testing checklist

Before considering test coverage complete, check:

• The behavior has one clear primary test owner.
• User-visible behavior has end-to-end integration coverage.
• Internal-only invariants have focused unit coverage where needed.
• Failure cases assert stable diagnostic codes.
• Rendered text is asserted only when it is contractual.
• Backend behavior uses the narrowest useful artifact assertions.
• Goldens are used only where exact output is a contract.
• HIR tests avoid incidental block and local numbering.
• Multi-file fixtures remain inside one case directory.
• Temporary files use owned cleanup.
• No benchmark fixture is being used as a correctness substitute.
• Redundant or obsolete coverage has been removed.

Validation gates

This document defines the technical gates a completed compiler or documentation slice must pass.

The required final gate depends on whether the slice changes implementation or is strictly documentation-only.

Compiler invocation

Use an up-to-date release build of the compiler when one is available. The moth command in PATH is the usual direct form:

    moth check docs --terse
    moth build docs --release
    

If a suitable release build is not available, run the same operations through Cargo from the repository root:

    cargo run --quiet -- check docs --terse
    cargo run --quiet -- build docs --release
    

Choose the final gate by scope

The justfile is the executable authority for the full code-bearing gate.

Code-bearing final gate

A slice is code-bearing if it changes Rust, compiler or build-system sources, libraries, tests, benchmarks, manifests, scripts, configuration or any other non-documentation implementation file.

Before declaring a non-trivial code-bearing slice complete, run:

    just validate
    

What just validate runs

• ci-clippy uses the pinned Rust toolchain configured in the justfile.
• Warnings are denied.
• It checks the complete workspace on the native host, Linux x64 and Windows x64 targets.
• The workspace test command includes the compiler, CLI and xtask packages.
• bench-ci preflights every benchmark manifest case once, then measures only the quick CLI and frontend subsets with three iterations.
• bench-ci does not update local history or tracked benchmark summaries.

The integration command loads the complete canonical suite and applies the shared hard-policy evaluator before selection or compilation. This makes missing ownership, duplicate primaries and other hard suite-policy findings part of the normal validation gate. Run the audit command when the JSON inventory under target/test-reports/ is also required:

    cargo run --quiet -- tests --audit
    

Documentation-only release-build gate

A slice is documentation-only only when every modified file is documentation source or generated documentation.

Allowed examples include:

• files under docs/**
• an explicitly requested root documentation file such as README.md, CONTRIBUTING.md or AGENTS.md
• generated files under docs/release/**

A documentation-only slice must not change Rust, tests, libraries, build configuration, manifests, scripts, benchmark code or fixtures, compiler configuration or other executable project sources.

For a strictly documentation-only slice, run one documentation release build using a current compiler.

The direct release-binary form is:

    moth build docs --release
    

If no suitable release build is available, use cargo run --quiet -- build docs --release instead.

Then:

• inspect every changed route
• inspect the generated diff
• verify links, tables and code examples
• confirm generated output came from source changes
• confirm the changed-file list contains documentation only.

Do not additionally run just validate, Clippy, unit tests, integration tests or benchmark checks for a documentation-only slice. A Cargo invocation of the compiler is an alternative way to run the same documentation gate, not an extra gate.

If any non-documentation file changed, the documentation-only exception does not apply. Use the full code-bearing gate.

Fast iteration commands

Passing one targeted command does not imply a code-bearing slice passes the complete gate.

Formatting

• Run cargo fmt when Rust files changed.
• just validate does not currently format source automatically.
• Do not solve formatting failures through lint suppression.
• Documentation-only changes do not require Rust formatting.

The ship recipe formats before validation, while validate itself does not.

Generated documentation

Do not edit files under docs/release/** directly.

The documentation release build is:

    moth build docs --release
    

A generated diff must result from documentation source changes, not manual HTML edits.

Manual architecture audits

When a code-bearing slice changes stage ownership, frontend boundaries, HIR, diagnostics, types or backend handoff, perform a manual architecture audit in addition to the automated gate.

Audit that:

• stage ownership remains narrow
• AST and HIR type representation still respect TypeEnvironment and TypeId
• user-facing failures use CompilerDiagnostic
• internal and infrastructure failures use CompilerError
• no obsolete API or duplicated path remains
• no backend reparses source syntax
• no analysis mutates HIR when its contract is side-table based
• comments and documentation name the current owner
• no compatibility shim preserves an obsolete path

This full architecture audit is not required for a prose-only documentation change.

Progress-matrix review

Review the progress matrix whenever behaviour, support, rejection, backend coverage or test coverage changes.

Update it when current status changed. Do not make a meaningless edit for a pure refactor or prose-only correction.

Benchmark safety

• just validate uses non-recording bench-ci.
• bench-ci validates every benchmark case before it measures the quick subset. It replaces the full ten-iteration CLI and frontend checks inside the normal validation gate.
• Use just bench-check and just bench-frontend-check for deliberate full-suite performance evidence. Both commands remain non-recording.
• Do not run or commit recording benchmark output unless performance history is intentionally being updated.
• A benchmark fluctuation does not replace correctness evidence.
• Generated benchmark history is outside this standards split.

Failure handling

• Do not ignore or suppress a failed required gate.
• Do not remove tests merely to make validation pass.
• Do not use lint allowances without documented justification.
• If a required command fails for environmental reasons, report the exact command, failure, completed checks and remaining uncertainty.
• Do not claim full validation when only targeted commands or the documentation-only gate ran.

Code-bearing completion checklist

Before declaring a non-trivial code-bearing slice complete, check:

• Rust source was formatted where applicable.
• The changed code follows style-guide.mtf.
• Test selection and assertions follow testing.mtf.
• Relevant architecture boundaries were reviewed.
• Diagnostics remain structured and stage appropriate.
• The progress matrix was reviewed and updated when status changed.
• Documentation was rebuilt when required.
• Generated output was not edited manually.
• Benchmark history was not changed accidentally.
• just validate passes.

Documentation-only completion checklist

Before declaring a documentation-only slice complete, check:

• The changed-file list contains documentation only.
• The documentation release build succeeds.
• Changed routes, links, tables and examples were inspected.
• Generated output was produced from source changes.
• No generated HTML was edited manually.
• No code, test, build, library, manifest, script, benchmark or configuration file changed.