Skip to content

Formatter

Accepted

Accepted as the compiler-owned formatter direction; the reference compiler CLI is cata.

The Catalyst compiler should ship a canonical formatter for .ct source. The formatter is invoked with cata fmt and renders accepted source into the canonical style documented in Code Style.

Tool Contract

Formatting must be deterministic and idempotent:

  • formatting the same source with the same compiler version produces the same bytes
  • formatting already formatted source produces no diff
  • formatting never changes source semantics
  • comments, documentation comments, attributes, and literal contents are preserved
  • parse errors are reported as formatter diagnostics and should leave the source unchanged in write mode

The formatter should operate over lexer/parser output plus preserved trivia. It should not need name resolution or type checking to format ordinary source. If a future formatting decision appears to require semantic information, prefer changing the source syntax or style rule so formatting stays syntax-owned.

Minimal Configuration

Catalyst formatter configuration should stay minimal for the same reasons as Zig's formatter: one normal shape reduces style debate, makes unfamiliar code easier to scan, and keeps formatter/editor/compiler behavior easier to reason about.

Projects should not configure:

  • indentation width
  • tabs vs spaces
  • brace placement
  • line ending style for formatted .ct files
  • naming style
  • alternative wrapping profiles
  • alignment preferences for ordinary declarations or expressions

Allowed controls are operational rather than stylistic:

  • check-only mode vs write mode
  • file and directory selection
  • generated-file exclusion
  • editor range formatting when it can still produce canonical output for the touched syntax region
  • source-local formatter suppression for exceptional generated, embedded, or table-like regions

Source-Local Suppression

Formatter suppression is an escape hatch, not a style configuration system. The directive spelling is:

// cata fmt: off
const matrix = [
    1.0, 0.0, 0.0, 0.0,
    0.0, 1.0, 0.0, 0.0,
    0.0, 0.0, 1.0, 0.0,
    0.0, 0.0, 0.0, 1.0,
]
// cata fmt: on

Suppressed regions must still lex and parse as ordinary Catalyst source unless they are inside comments or string literals. A missing on directive suppresses formatting through the end of the file and should produce a formatter warning.

List Wrapping Signal

Trailing commas are the preferred source-level way to request vertical layout for lists that could otherwise fit on one line. The formatter may add or remove whitespace, but it should not remove a trailing comma that is carrying vertical-layout intent.

When a comma-separated list has more than two items, the formatter should prefer one item per line and include a trailing comma where the grammar allows it.

Integration

Compiler-provided autofixes should either produce already formatted edits or run through the same formatting renderer before being presented. Lints that enforce naming or API conventions are separate from formatting: the formatter fixes layout, not semantic or convention names.

Formatter check mode should be usable as a CI gate. Failing formatter checks should report stable file paths and spans without depending on terminal-specific rendering.