Formatter

Platform spec feature

Formatter

Back to Tooling ◎ Open in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (2)

1. 0001-canonical-pretty-printer Canonical pretty-printer with no user knobs Accepted

   Single source of truth, no width/tabs/brace-style configuration.

   Context

   Most modern languages that ship a first-party formatter (gofmt, rustfmt with default config, dotnet format, csharpier) converged on the same answer to the bikeshed question of formatter style: pick one and don't expose knobs. Languages that allow per-project style files (older prettier configs, clang-format) routinely waste cycles in code review on layout disagreements and create friction for cross-project contributions.

   The Beskid formatter starts from a clean slate. The reference implementation in compiler/crates/beskid_analysis/src/format/ is already opinionated (four-space indent, brace on same line, one blank line between members) and ships through a single CLI surface (beskid format / beskid fmt). The question this ADR resolves is whether to expose layout configuration to consumers.

   Decision

   The Beskid formatter must be a canonical, knob-free pretty-printer. The platform ships exactly one layout style. The formatter:

   1. Must not expose user-configurable width, indent unit, brace style, member ordering, blank-line policy, or comment placement.
   2. Must not read project-level style files (no .beskid-format.toml, no [format] section in Project.proj).
   3. Must be a pure function of the parsed AST and the formatter version compiled into the CLI.
   4. May change formatter output between releases under the rules in the parent hub's Compatibility and versioning section (release notes + idempotency preserved + ADR when the layout policy changes substantively).

   The CLI must continue to support the operational flags --write, --check, and --output; these affect where the output goes, not what it looks like.

   Consequences

   Pros:

   • Zero bikeshedding in code review: there is exactly one correct way for any given input.
   • Deterministic CI: beskid format --check is a reliable PR gate; no per-repo style file ambiguity.
   • Simpler editor integrations: every plugin can shell out to the canonical CLI without re-implementing layout logic.
   • Faster onboarding: new Beskid contributors don't need to learn project-specific style files.

   Cons / accepted trade-offs:

   • Teams with strong existing house style (especially "tabs" or "2-space") cannot satisfy that preference via the formatter; this is by design.
   • Future syntactic features that might benefit from style-aware emission (for example, partial-application chains) must take a layout decision once and ship it as part of the formatter, not defer to user preference.
   • Some downstream tools that wrap the formatter and want to expose style flags must either drop those flags or layer them outside the canonical formatter.

   Verification anchors

   • beskid_analysis::format::policy — single file that owns layout policy; no other formatter file emits \n or indent runs directly.
   • beskid_cli::commands::format::FormatArgs — the clap surface contains only --write, --check, --output; the absence of style flags is observable from beskid format --help.
   • Parent hub Layout policy section — enumerates the fixed indent unit, blank-line rules, and brace style.

   Open full ADR page

2. 0002-emit-trait-policy-split Emit trait and policy module split Accepted

   Layout policy lives in `policy.rs`; per-construct `Emit` impls use `EmitCtx` helpers only.

   Context

   The reference formatter under compiler/crates/beskid_analysis/src/format/ currently splits responsibilities across several files:

   • emit.rs — Emit trait, EmitCtx (context), Emitter (driver), EmitError, and the format_program entry point.
   • policy.rs — three small free functions that encode blank-line / between-member / between-block-items policy.
   • items/, expressions_emit.rs, statements_emit.rs, types_emit.rs — per-construct Emit implementations.

   Two anti-patterns would make this hard to evolve safely:

   1. Scattered layout policy — per-construct emitters writing raw \n or four-space runs make a policy change (for example, "double blank between top-level items") a multi-file refactor.
   2. God-trait Emit — putting blank-line policy inside Emit::emit parameters would force the AST-side modules to know about higher-level layout intent.

   This ADR records the chosen split.

   Decision

   The formatter must preserve the following module decomposition:

   1. Emit trait in format/emit.rs defines a single method emit(&self, w, cx). Per-construct modules must implement Emit for the AST node they own.
   2. EmitCtx in format/emit.rs is the only sanctioned place to mutate indent depth, write newlines, write indents, or open/close braces. AST-side modules must call its helpers (write_indent, nl, ln, space, token, open_brace, close_brace) rather than writing raw layout characters.
   3. policy.rs is the only place that owns inter-declaration, inter-member, and inter-statement blank-line decisions. AST-side modules call cx.between_top_level_declarations(...), cx.between_members(...), and cx.between_block_items(...); they do not duplicate the policy.
   4. mod.rs stays as exports-only. New construct emitters are added as siblings under items/ (or as new files when the construct does not fit an existing role).

   A change that violates rule (2) or (3) must be revised before merging; the parent Verification and traceability article enumerates the file anchors.

   Consequences

   Pros:

   • A new layout rule lands as one edit in policy.rs and an optional method on EmitCtx; downstream emitters don't need to know.
   • The formatter is easier to audit: anyone reviewing layout output knows to read policy.rs first.
   • The per-construct emitters stay readable — each function reads as "what does this node look like in source", not "how do I implement blank-line policy".

   Cons / accepted trade-offs:

   • AST-side modules cannot work around policy by writing raw characters; this is intentional and is enforced by code review.
   • EmitCtx accrues helpers over time. We accept this as the lesser evil compared to scattered policy.

   Verification anchors

   • compiler/crates/beskid_analysis/src/format/emit.rs — single owner of Emit, EmitCtx, Emitter, EmitError, and format_program.
   • compiler/crates/beskid_analysis/src/format/policy.rs — single owner of the three policy helpers.
   • compiler/crates/beskid_analysis/src/format/mod.rs — mod declarations and pub use re-exports only; no business logic.

   Open full ADR page

Articles

• Formatter design model Emit/EmitCtx/Emitter architecture, policy split, and the layout invariants the formatter exposes. article Standard Reviewed Sat May 23
• Formatter verification and traceability Concrete tests, CI hooks, and code anchors that demonstrate formatter contract conformance. article Standard Reviewed Sat May 23

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKarea · 15 SpecSection(s) · 0 H2 heading(s)

Section id	Required	Found
what-this-feature-specifies	yes	yes
implementation-anchors	yes	yes

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Area
  Tooling

  Parent domain

• Feature
  Beskid CLI

  `beskid format` subcommand

• Feature
  Package kinds

  tool kind for future formatter rule packs

• Feature
  Lexical and syntax

  Canonical token model that the formatter projects

What this feature specifies

The formatter — the canonical, opinionated pretty-printer for .bd source. It defines the public command surface (beskid format / beskid fmt), the Emit contract that drives layout, and the invariants the formatter must hold across releases.

This feature governs the shape of formatted Beskid code so that editor plugins, CI checks, and code-review pipelines all converge on byte-identical output for byte-identical input.

Implementation anchors

• compiler/crates/beskid_analysis/src/format/ — Emit/EmitCtx/Emitter traits and the layout policy (policy.rs), per-construct emitters under items/, expressions_emit.rs, statements_emit.rs, types_emit.rs.
• compiler/crates/beskid_analysis/src/format/mod.rs — re-exports format_program, emit_error_semantic_diagnostic, the public surface.
• compiler/crates/beskid_cli/src/commands/format.rs — the beskid format (alias beskid fmt) subcommand: file/dir scan, --write, --check, --output, stdout fallback.
• compiler/crates/beskid_analysis/docs/formatter.md — implementation-side overview, layout rules, and reference table that mirrors this hub.

Contract statement

The Beskid platform must ship exactly one canonical formatter that maps a parsed program back to source text. The formatter:

1. MUST be a pure function of the parsed AST — the same Spanned<Program> must always produce byte-identical output regardless of host platform, locale, or terminal width.
2. MUST preserve program semantics — running the parser on format_program(parser(s)) must yield an AST equivalent to parser(s) modulo trivia that the formatter is allowed to normalize (whitespace, optional separators, member ordering inside a block where the AST is order-independent).
3. MUST be idempotent — format_program(parser(format_program(parser(s)))) must produce the same string as format_program(parser(s)).
4. MUST preserve every token that carries program meaning (identifiers, literals, attributes, doc comments).
5. MUST NOT offer user-tunable style knobs (no width-N, no tabs-vs-spaces flag, no brace-style flag). Style is fixed by this contract; configurability is explicitly out of scope.
6. MUST report layout failures as diagnostics through the existing emit_error_semantic_diagnostic path, not via panics or silent fallbacks.

Inputs and outputs

Surface	Input	Output
format_program(&Spanned<Program>)	Parsed Beskid program (output of services::parse_program_with_source_name)	Result<String, EmitError> — formatted source on success; EmitError on a layout failure
beskid format <file.bd> (single file, no flags)	One .bd file	Formatted source on stdout
beskid format -o <out> <file.bd>	One .bd file	Formatted source written to <out>
beskid format --write <dir-or-file>	Tree or file	In-place rewrite of every .bd file under the input
beskid format --check <dir-or-file>	Tree or file	Exit code 0 if every file is already formatted, non-zero with diff hint otherwise — used by CI

The CLI must not recurse into the conventional ignore set (.git, .svn, .hg, target, node_modules, dist, .venv, vendor, __pycache__).

Layout policy

The reference policy is encoded in beskid_analysis::format::policy and EmitCtx. The normative rules below must hold:

1. Indent unit MUST be four spaces. Tabs must not appear in formatted output.
2. Blank lines:
   • Between top-level declarations: exactly one blank line.
   • Between members of a container (when policy_blank_line_between_members is enabled, the default): exactly one blank line.
   • Inside a block, after a control-flow statement (if, while, for) immediately followed by a let: exactly one blank line; otherwise zero.
3. Braces: open-brace stays on the line that introduces the block; close-brace is on its own line aligned with the opening construct. An empty block must be emitted as { } on the same line.
4. Trailing whitespace: every emitted line must not end in horizontal whitespace.
5. Final newline: every formatted file must end with exactly one \n.
6. Attributes: each attribute ([Export], [Extern(...)], doc-comment-derived markers) must appear on its own line above the construct it decorates.
7. Type names with generics (Option<T>, Channel<T>) must be emitted without spaces inside the angle brackets and without HTML-entity escaping.

Editors must treat any deviation from these rules in formatter output as a defect to be filed against beskid_analysis::format, not as an opportunity to layer post-processing.

State model

The formatter has no persistent state. EmitCtx holds transient layout state (current indent depth, whether to insert blank lines between members) and is constructed afresh for each top-level emit:

• EmitCtx::indent — non-negative integer (usize). push_indent/pop_indent are total: pop_indent saturates at 0.
• EmitCtx::policy_blank_line_between_members — boolean, true by default. Constructs that intentionally suppress inter-member blanks (for example, contiguous import lists) may mutate it locally; they must restore the previous value before returning.

No caching, no I/O, no concurrency. The formatter is safe to call concurrently across independent inputs.

Algorithms and flow

1. Parse the source with services::parse_program_with_source_name to obtain a Spanned<Program>.
2. Construct a fresh EmitCtx via EmitCtx::new().
3. Emit the program through the root Emit impl (items/root_emit.rs), which dispatches each top-level declaration via the per-construct emitters (declarations_emit, functions_emit, attributes_emit, macro_emit, tests_emit).
4. Each declaration emits attributes first (one per line), then the body, then a trailing newline; between_top_level_declarations injects the inter-declaration blank.
5. Inside a block, each statement is preceded by cx.write_indent(...), followed by cx.nl(...). between_block_items runs between adjacent statements and may inject an extra blank when policy requires it.
6. On layout failure (any underlying std::fmt::Error), the emitter returns EmitError; the CLI converts that into a Miette-rendered diagnostic via emit_error_semantic_diagnostic and exits non-zero.

The CLI surface in beskid_cli::commands::format adds the file-scanning and --check/--write machinery around this pure pipeline. The CLI must not call any non-formatter analysis (no name resolution, no type checking) so that an unbuildable file with valid syntax is still formattable.

Edge cases and errors

Case	Required behavior
Empty input file	Format successfully to a single trailing \n (or empty, when the AST has zero top-level items).
Parse error	The CLI must surface the parse diagnostic verbatim and exit non-zero without writing any output.
Empty block { }	Emit on the same line as the opening construct.
Directory passed without --write or --check	The CLI must refuse with a structured error pointing the publisher at the correct flag.
--output with multiple input files	The CLI must refuse: --output is only valid for a single .bd input.
Non-UTF-8 source	The CLI must refuse with a clear I/O / encoding diagnostic; the formatter must not silently lossy-decode.
`--check` finds a non-formatted file	Exit non-zero with message: not formatted, then path, then hint to run beskid format --write on that path (see CLI implementation).

Compatibility and versioning

The formatter is part of the toolchain contract. A new compiler / CLI release may change formatter output if and only if:

1. The change is documented in the release notes under a formatter section.
2. The change preserves idempotency: running the new formatter twice on existing repository content must produce the same result as running it once.
3. The change either (a) tightens the layout policy in a way that affects only previously unspecified trivia, or (b) is accompanied by a follow-up ADR under adr/.

Editor extensions must treat the bundled CLI as the source of truth and must not ship their own divergent layout engine.

Security and performance notes

• The formatter performs no network I/O and no shell execution; it reads source files and writes formatted output (when --write) only.
• File system writes must be atomic per file (the CLI may write to a sibling temp file and rename) so that crashes during --write cannot leave a half-formatted file.
• Memory cost is proportional to the size of the largest formatted file; the formatter holds the parsed AST plus an output String in memory simultaneously.
• The formatter is CPU-bound and deterministic — --check in CI should complete in well under a second for typical packages and must not consume disproportionate memory for source files within usual size envelopes (single file under a few MiB).

Examples

Reformat one file in place:

beskid format --write src/Main.bd

CI check (fail PR on drift):

beskid format --check src/

Preview format for a single file without writing:

beskid format src/Main.bd

Programmatic use from a host that depends on beskid_analysis:

use beskid_analysis::format::format_program;
use beskid_analysis::services::parse_program_with_source_name;

let program = parse_program_with_source_name("src/Main.bd", source)?;
let formatted = format_program(&program)?;

The output of the programmatic call is byte-identical to beskid format --write src/Main.bd.

Decisions

No open decisions. D-TOOL-FMT-0001 (canonical pretty-printer, no user knobs) and D-TOOL-FMT-0002 (Emit trait and EmitCtx policy split) under adr/; use the ADRs tab.

Verification and traceability

• CLI surface tests — cargo test -p beskid_cli format (currently no tests are filtered by the name format; the filter ensures the crate compiles and any future format-named tests run). The CLI behavior is covered by manual --check/--write invocations in the release pipeline.
• Format module tests — cargo test -p beskid_analysis format:: exercises the Emit impls under compiler/crates/beskid_analysis/src/format/items/* (idempotency tests, layout policy tests).
• Implementation overview — compiler/crates/beskid_analysis/docs/formatter.md (kept in sync with this hub; updates to the layout policy section must touch both files in the same change set).
• Spec policies — Indent unit, blank-line policy, and brace style are encoded in beskid_analysis::format::policy and beskid_analysis::format::emit::EmitCtx.

Newcomer reading order

1. Tooling — domain context, why tooling is specified rather than reverse-engineered.
2. This hub — canonical formatter contract and invariants.
3. Design model — Emit/EmitCtx/Emitter architecture and policy split.
4. Verification and traceability — concrete test paths and CI hooks.
5. Decisions ADRs — the rationale for the “no knobs” stance.

Related features

• Beskid CLI — host for the format / fmt subcommand.
• Package kinds — future external formatter rule packs ship as packageKind: tool packages.
• Lexical and syntax — the token grammar that the formatter projects back to source.

Articles

• Canonical pretty-printer with no user knobsSingle source of truth, no width/tabs/brace-style configuration.
• Formatter design modelEmit/EmitCtx/Emitter architecture, policy split, and the layout invariants the formatter exposes.
• Formatter verification and traceabilityConcrete tests, CI hooks, and code anchors that demonstrate formatter contract conformance.