aontu 0.62.0 → 0.64.0

package/src/format.ts

@@ -1,26 +1,5 @@
 /* Copyright (c) 2026 Richard Rodger, MIT License */
 
-// THE SOURCE FORMATTER (docs/design/FMT.0.md): `aontu fmt`, in the
-// tradition of gofmt. One agreed form for Aontu source, so that layout
-// is never argued about and a diff shows only what changed.
-//
-// It reads the token stream the parser reads -- the lex subscriber the
-// parser stack exposes -- so it sees what the value tree throws away:
-// comments, blank lines, the quote a string used, the spelling of a
-// number. From that stream it builds a layout tree, decides the shape
-// of every container by the rules of the note's §3, and emits. Before
-// returning it re-parses what it wrote and compares the two parse
-// trees: a formatter that cannot prove its output is the same document
-// refuses rather than return it.
-//
-// Two tiers. The syntactic (P1): whitespace, commas, quotes, bare
-// keys, chains and pair elements, none of which changes the parse
-// tree. The lawful (P2), over it: repeat the prefix, and merge what
-// repeats -- rewrites that rest on the meet, each checked by the meet
-// in isolation and kept only where the engine agrees.
-//
-// The Go twin is go/format.go, function for function; the shared
-// behaviour is test/spec/fmt.tsv, executed by both spec runners.
 
 import { Aontu } from './aontu'
 import { failureFinding } from './vet'
@@ -29,16 +8,8 @@ import type { Resolver } from './type'
 import { desugarTemplate, resugarTemplate, templateOutputs } from './template'
 
 
-// The packing budget (§3.1). It decides which of two legal spellings
-// to use, one line or several, and nothing else: the formatter never
-// breaks a line, so a value wider than this stays as wide as it is.
 const BUDGET = 80
 
-// THE DEPTH BUDGET. The layout is recursive, as the tree it reads is,
-// and the canonical port's stack is finite: past the evaluation budget
-// of 1000 levels -- the depth at which unification itself refuses --
-// the formatter stops reading and refuses, so a pathological document
-// is a finding rather than a crash.
 const MAX_DEPTH = 1000
 
 export type FormatOptions = {
@@ -47,11 +18,6 @@ export type FormatOptions = {
   // Report the style findings of §4 -- key case, repeated shapes --
   // beside the text. The formatter never acts on them.
   lint?: boolean
-  // THE SOURCE IS A GENERATOR, and this is its marker
-  // (docs/design/TEMPLATE.0.md; FMT.0.md §3.14). The file is desugared,
-  // formatted and resugared, so `text` is a template again -- the aontu
-  // in the agreed form, indented after the marker, and every line of
-  // output exactly where it was.
   template?: string
 }
 
@@ -82,18 +48,10 @@ export type FormatReport =
 
 type Tok = { name: string, src: string, val: any, sI: number }
 
-// EVERY INCLUDE RESOLVES TO NOTHING. The formatter reads the file it is
-// given and no other (§3.13), so `@"..."` is answered from memory with
-// an empty source: the directive parses, the include is a token like
-// any other, and no capability is needed because no file is read.
 const stubResolver: Resolver = ((spec: any) => ({
   ...spec, kind: 'aon', full: '__fmt__.aon', src: '', found: true, search: [],
 })) as any
 
-// ONE ENGINE, ONE SUBSCRIBER. The parser's subscriber list is
-// append-only, so the subscription is made once and writes to
-// whichever sink the current parse installed; the sink is cleared
-// before the parse returns, so the check's re-parse collects nothing.
 let ENGINE: Aontu | undefined
 let SINK: Tok[] | undefined
 
@@ -102,10 +60,6 @@ function engine(): Aontu {
     ENGINE = new Aontu({ resolver: stubResolver })
     ENGINE.lang.jsonic.sub({
       lex: (tkn: any) => {
-        // Spaces carry nothing the layout needs, and the end token
-        // arrives once per nested parse -- the stub's empty includes
-        // among them -- so both are dropped here rather than skipped
-        // everywhere below.
         if (undefined !== SINK && '#SP' !== tkn.name && '#ZZ' !== tkn.name) {
           SINK.push({ name: tkn.name, src: tkn.src, val: tkn.val, sI: tkn.sI })
         }
@@ -138,21 +92,14 @@ function parseDoc(src: string, path: string | undefined, sink: Tok[] | undefined
 }
 
 
-// ---------------------------------------------------------------------
-// The layout tree
-
 // One node shape for the whole tree, so the Go twin is one struct:
 // the kind says which fields are meaningful.
 type Node = {
   t: 'pair' | 'spread' | 'include' | 'comment' | 'blank' | 'map' | 'list'
   | 'atom' | 'call' | 'paren' | 'expr' | 'op' | 'prefix' | 'note'
 
-  // atom, include, comment, note, op, prefix: the text as written,
-  // normalised where §3.9 says (quotes), and nothing else.
   text?: string
 
-  // pair: the key as it will be written, the optional marker, and the
-  // value; spread: the value.
   key?: string
   opt?: boolean
   // pair: written with `=`, the alias declaration operator, rather than
@@ -175,7 +122,6 @@ type Node = {
   // comment inside the expression), in source order.
   items?: Node[]
 
-  // op: the author broke the line at this operator (§3.11).
   brk?: boolean
 
   // A comment on the last line of this entry.
@@ -273,10 +219,6 @@ class Reader {
       ('#QM' === this.name(1) && '#CL' === this.name(2)))
   }
 
-  // The entries of a container up to its closer, or of the document up
-  // to its end. Comments attach by the rules of §3.7: on the line of
-  // the entry that precedes them, or of the opener, they trail it;
-  // alone on a line they stand as entries and precede what follows.
   body(close: string, opened: boolean): { body: Node[], open?: string } {
     const body: Node[] = []
     let open: string | undefined
@@ -584,11 +526,6 @@ function unwrap(root: Node[]): Node[] {
 // ---------------------------------------------------------------------
 // The layout
 
-// D1: a one-pair map in value position is written as a chain, and a
-// one-pair map as a list element as a pair element. A map whose only
-// entry is a spread keeps its braces (X-7), and one holding a comment
-// keeps them too, because the comment needs the lines. A trailing
-// comment on the map's line joins the pair's own.
 function chain(node: Node): Node {
   if ('map' !== node.t || undefined !== node.open || 1 !== node.body!.length ||
     'pair' !== node.body![0].t) {
@@ -605,19 +542,17 @@ function width(s: string): number {
   return Array.from(s).length
 }
 
-function pairHead(node: Node, tight: boolean): string {
+function pairHead(node: Node, tight: boolean, value?: string): string {
   // An alias declaration is `%name = value` at every width: the `=` is
   // an operator, and operators are spaced (§3.2).
   if (node.alias) {
     return node.key! + ' = '
   }
-  return node.key! + (node.opt ? '?' : '') + (tight ? ':' : ': ')
+  const pad = !tight ||
+    (undefined !== value && '' !== value && OPENS.includes(value[0]))
+  return node.key! + (node.opt ? '?' : '') + (pad ? ': ' : ':')
 }
 
-// The one-line spelling of a node, or undefined where it has none: a
-// comment, a blank line, a break the author kept, a string that spans
-// lines. `tight` is the inline form of a pair, `a:1`, used inside a
-// container; a statement's pair is `a: 1`.
 function inline(node: Node, tight: boolean): string | undefined {
   if (undefined !== node.trail || node.held) {
     return undefined
@@ -628,7 +563,7 @@ function inline(node: Node, tight: boolean): string | undefined {
       return node.text!.includes('\n') ? undefined : node.text
     case 'pair': {
       const v = inline(chain(node.value!), tight)
-      return undefined === v ? undefined : pairHead(node, tight) + v
+      return undefined === v ? undefined : pairHead(node, tight, v) + v
     }
     case 'spread': {
       // `{ &: integer }`, padded inside braces too: the marker reads as
@@ -685,12 +620,17 @@ function inlineSeq(items: Node[]): string | undefined {
   return out
 }
 
+// A value that OPENS keeps the space after the colon (§3.2); `|` is
+// tight within a line and spaced where it leads one (§3.11, §7.7).
+const OPENS = '*{[('
+const TIGHT_OP = '|'
+
 function sepOf(node: Node): string {
   return node.sep ? ', ' : ' '
 }
 
-// Binary operators spaced, prefixes tight (§3.11). An operand is
-// never directly after an operand: the reader ends a value there.
+// Binary operators spaced, prefixes and `|` tight (§3.11). An operand
+// is never directly after an operand: the reader ends a value there.
 function inlineExpr(items: Node[]): string | undefined {
   let out = ''
   for (const it of items) {
@@ -698,7 +638,7 @@ function inlineExpr(items: Node[]): string | undefined {
       return undefined
     }
     if ('op' === it.t) {
-      out += ' ' + it.text + ' '
+      out += TIGHT_OP === it.text ? it.text : ' ' + it.text + ' '
       continue
     }
     if ('prefix' === it.t) {
@@ -755,9 +695,6 @@ class Writer {
     return this.lines.slice(mark).concat([this.line]).map(rtrim).join('\n') + '\n'
   }
 
-  // A blank line above the line at an index: the gap of §3.8, opened
-  // once the statement below it turns out to be a tree. Never at the
-  // top of the page, and never a second time.
   gap(at: number): void {
     if (0 < at && '' !== this.lines[at - 1]) {
       this.lines.splice(at, 0, '')
@@ -790,21 +727,11 @@ function rtrim(s: string): string {
 }
 
 
-// The entries of a body, one per line at the indentation, with the
-// blank lines the author kept between them (§3.8) -- never at the
-// start or the end. In STATEMENT position (`stmt`: the root, and the
-// body of a plain map that is itself the value of a statement) a pair
-// is laid out by §3.4, which may repeat its key; anywhere else -- a
-// list, an operand, an argument -- by §3.5 alone.
 function emitBody(
   w: Writer, body: Node[], indent: number, stmt: Stmt | undefined, root?: boolean
 ): void {
   let pending = false
   let count = 0
-  // Where the run being written begins: a statement, with the comments
-  // standing directly above it, so that the gap below opens ABOVE the
-  // comments rather than between them and what they describe. A blank
-  // line ends a run -- comments across a gap belong to what is above.
   let head = 0
   let noted = false
   for (const node of body) {
@@ -836,14 +763,6 @@ function emitBody(
         w.text(' ' + e.trail)
       }
     }
-    // A TOP-LEVEL STATEMENT WRITTEN AS A TREE STANDS APART (§3.8). A
-    // document states several things -- a service, then its entities,
-    // then its errors -- and where one of them is a tree rather than a
-    // line, the eye finds it by the space around it. What counts as a
-    // tree is measured rather than guessed: the statement took more
-    // than one line to write. So `a: 1` beside `b: 2` is left alone,
-    // and this rule cannot fire below the root, where a blank line is
-    // the author's (§3.8) and nothing else.
     if (root && from < w.mark()) {
       w.gap(head)
       pending = true
@@ -892,18 +811,6 @@ function emitValue(w: Writer, node: Node, indent: number): void {
   }
 }
 
-// A call, or a parenthesis, that has no one-line form or is too wide
-// for the budget. Three shapes. Arguments that are all FLAT -- none
-// holds a container -- stay on the one line however wide it is: a
-// scalar is no narrower on a line of its own, and the formatter never
-// breaks a line. The last argument HUGS the parentheses, `hide({` ...
-// `})`, `close($.E & {` ... `})`, when it is a container, or an
-// expression the author did not break that ends in one, and the
-// arguments before it fit on the opener's line: the container decides
-// its own lines. Otherwise the parenthesis opens a block: one argument
-// per line one level in, the closer alone at the opener's level. A
-// call whose last argument hugs is hugged in turn, `type(close({` ...
-// `}))`: the schema idiom.
 function emitCall(w: Writer, node: Node, indent: number): void {
   const items = 'call' === node.t ? node.args! : node.inner!
   const open = ('call' === node.t ? node.name! : '') + '('
@@ -1005,21 +912,8 @@ function emitBlock(
   w.text(close)
 }
 
-// An expression that has no one-line form, or one too wide for the
-// budget: the author's breaks are kept, each at its operator, which
-// leads its continuation line (§3.11). The continuation is one level
-// in when the expression follows a key on its line, and level with
-// the first operand when the expression has the line to itself -- an
-// argument of a block call, say -- so a disjunction of alternatives
-// reads as the list it is. A container operand that does not fit from
-// where it stands is a block whose closer lines up with the line that
-// opened it.
 function emitExpr(w: Writer, items: Node[], indent: number): void {
   const cont = w.fresh() ? indent : indent + 2
-  // Whether the last item was an operand: a comment after one is a
-  // space away, and after an operator or the colon it is not. An
-  // operand is never directly after an operand (the reader ends a
-  // value there), so operands need no such check.
   let operand = false
   let cur = indent
   for (const it of items) {
@@ -1032,7 +926,7 @@ function emitExpr(w: Writer, items: Node[], indent: number): void {
         w.text(it.text + ' ')
       }
       else {
-        w.text(' ' + it.text + ' ')
+        w.text(TIGHT_OP === it.text ? it.text! : ' ' + it.text + ' ')
       }
       operand = false
       continue
@@ -1058,25 +952,6 @@ function emitExpr(w: Writer, items: Node[], indent: number): void {
 }
 
 
-// ---------------------------------------------------------------------
-// The lawful tier (§3.4): repeat the prefix, and merge what repeats.
-//
-// Both rewrites rest on the meet. `s: a: 1` / `s: b: 2` is one document
-// with `s: { a:1 b:2 }`, because a key written twice is a meet and the
-// meet of two maps with disjoint keys is their union. So they apply
-// only to a PLAIN map in STATEMENT position -- an entry of the root, or
-// of a map that is itself the plain value of such an entry -- and never
-// to a map that is an operand, an argument or a list element, where
-// splitting it would change the document (`close({a:1})` /
-// `close({b:2})` does not evaluate at all). And every statement the
-// tier rewrites is checked by unification, locally (§7.3): the spelling
-// before and the spelling after must come to the same meet, or the
-// statement keeps the spelling before. The check is the engine's
-// agreement, not the formatter's self-check -- the engine's own repros
-// hold maps whose two spellings it evaluates differently -- so failing
-// it is no refusal.
-
-// The check of one rewrite: the spelling before and the spelling after.
 type Meet = (before: string, after: string) => boolean
 
 // Statement position: the check, and whether the statement being laid
@@ -1084,10 +959,6 @@ type Meet = (before: string, after: string) => boolean
 // Undefined anywhere else -- a list, an operand, an argument.
 type Stmt = { meet: Meet, covered: boolean }
 
-// The entries of a plain map value: a braced map, or a chain, which is
-// a one-entry map. A map with a comment on its opener keeps its braces
-// (§3.7), so it is not plain here; nor is a map holding an include,
-// which the local check cannot follow.
 function plainEntries(v: Node): Node[] | undefined {
   if ('pair' === v.t) {
     return [v]
@@ -1115,17 +986,6 @@ function members(p: Node): Node[] | undefined {
   return entries.slice(0, -1).concat([{ ...last, trail }])
 }
 
-// Adjacent statements naming one key, whose values are plain maps, are
-// one map: their entries in order, with the comments and blank lines
-// between the statements travelling with the statement they preceded.
-// Only ADJACENT statements merge -- a `server:` line, something else,
-// then another `server:` line stays as it is, because merging them
-// would move a statement, and the formatter never reorders (§3.13).
-// Nor do two statements merge into a map with two spreads: the engine
-// keeps those as a conjunction, which is not the meet of the two maps.
-// The tree is not changed: a merged statement is a new node that keeps
-// the statements it replaces as its `orig`, its spelling before, and a
-// statement merged somewhere below is copied the same way.
 function mergeRuns(body: Node[]): Node[] {
   const out: Node[] = []
   let i = 0
@@ -1190,15 +1050,6 @@ function mergeDeep(p: Node): Node {
   return { ...p, value: 'pair' === v.t ? body[0] : { ...v, body }, orig: [p] }
 }
 
-// Whether a value is a RECORD: a braced map of several entries, every
-// one of them a VALUE rather than another map. A field, an error, a
-// rule row -- something whose keys are what it IS, as against a level
-// of the tree, whose keys are a way through to something else.
-//
-// A CHAIN IS NOT ONE, whatever it holds: a one-entry map is D1's, and
-// D1 writes it as a chain at every width. Nor is a map holding a
-// spread, which says something about the map's MEMBERS and which D1's
-// exception already gives a spelling of its own inside a repeat.
 function record(v: Node, entries: Node[]): boolean {
   if ('map' !== v.t) {
     return false
@@ -1219,24 +1070,6 @@ function record(v: Node, entries: Node[]): boolean {
   return 1 < pairs
 }
 
-// The lines of a map repeated under a prefix (§3.4, rule 2): every
-// entry written with the prefix in front of it as one line, or --
-// where an entry's value is a map that does not fit -- descended into
-// under the longer prefix. Comments and blank lines are kept where
-// they stood. Undefined where an entry cannot be one line: a list that
-// does not fit, a value that spans lines, a comment closing the map
-// (which a repeat could not keep in the map) -- and where the map holds
-// two spreads, which repeated would be two maps, and a different meet.
-//
-// A DESCENT ENDS AT A RECORD (§3.4, D2's amendment). The prefix reaches
-// through maps that hold maps, because those keys are a path and a line
-// carrying the whole path says where it is. It stops at a map that
-// holds only values: there the keys are the thing's own fields, the
-// prefix in front of each of them is the same prefix again, and the
-// map is written as a braced BLOCK under the prefix instead --
-// `entity: planet: field: id: {` and its seven facts indented once.
-// The statement's own map is not an entry of anything and is
-// unaffected, so a flat `service: host: …` is still one repeat.
 type Line = {
   t: 'text' | 'comment' | 'blank' | 'block'
   text?: string
@@ -1284,12 +1117,6 @@ function repeatLines(entries: Node[], prefix: string, indent: number): Line[] |
     if (undefined === lines) {
       return undefined
     }
-    // THE DESCENT COULD GO ON, AND WHAT IT REACHES IS A RECORD: it
-    // stops, and the record is a block under the prefix instead. The
-    // deeper repeat is asked for first and thrown away deliberately --
-    // the block REPLACES a descent that would have worked, and never
-    // rescues one that would not, so a map this rule cannot reach two
-    // ways round is laid out exactly as it was before the amendment.
     if (record(e.value!, sub)) {
       out.push({ t: 'block', text: head, node: e.value!, trail })
       continue
@@ -1315,18 +1142,6 @@ function fits(indent: number, text: string): boolean {
   return indent + width(text) <= BUDGET
 }
 
-// A pair in statement position, by §3.4. `prefix` is what stands
-// before it on its line: the heads of the chain it hangs from, not yet
-// written. Its value is laid out by §3.5 unless it is a plain map, and
-// then in this order: a chain, when the map holds exactly one pair
-// (D1); one line, when that fits the budget; the key repeated over the
-// entries, when every entry can be one line that way; a braced block
-// otherwise, whose entries are statements in turn. Whether the
-// statement was rewritten by this tier -- merged, or repeated -- is
-// returned, and the outermost such statement is checked: its spelling
-// on the page against what the syntactic tier writes for the
-// statements it came from, at the same indentation, which is what
-// stays on the page when the check fails.
 function emitStatement(w: Writer, p: Node, indent: number, stmt: Stmt, prefix: string): boolean {
   const mark = w.mark()
   let rewritten = undefined !== p.orig
@@ -1407,12 +1222,6 @@ function emit(root: Node[], meet: Meet | undefined): string {
 }
 
 
-// ---------------------------------------------------------------------
-// The lint (§4): what the formatter points at and never touches. Two
-// rules, both advice: the formatter never renames a key (§4.1) and
-// never introduces an alias (§4.2), and a rule with a mechanical fix
-// that keeps the document would belong to §3 instead (§4.3).
-
 // The shape width at which a repeat is worth an alias (§4.2): below
 // it, `{ a:1 }` twice is the shorter spelling. Measured over the use
 // cases when the lint landed (§7.10).
@@ -1464,11 +1273,6 @@ function lineCol(text: string, at: number): { line: number, col: number } {
   return { line: before.split('\n').length, col: at - before.lastIndexOf('\n') }
 }
 
-// D4 (§4.1): keys are lower-case words, or CamelCase when a key is
-// several. A bare key holding `_`, or beginning with two capitals, is
-// reported with the spelling that would follow the form; a quoted key
-// is a deliberate spelling and a key of underscores alone names
-// nothing the rule can respell.
 function keyCase(node: Node, text: string, out: LintFinding[]): void {
   if ('pair' === node.t && BARE.test(node.key!) && /[A-Za-z]/.test(node.key!)) {
     const why = node.key!.includes('_') ? 'holds an underscore'
@@ -1485,9 +1289,6 @@ function keyCase(node: Node, text: string, out: LintFinding[]): void {
   }
 }
 
-// The key as lower-case words or CamelCase: `credit_cents` is
-// `creditCents`, `HTTP_PORT` is `httpPort`, `HTTPServer` is
-// `httpServer`, `ID` is `id`.
 function camel(key: string): string {
   const words = key.split('_').filter((w) => '' !== w)
     .map((w) => /^[A-Z]+$/.test(w) ? w.toLowerCase() : w)
@@ -1496,12 +1297,6 @@ function camel(key: string): string {
     words.slice(1).map((w) => w.charAt(0).toUpperCase() + w.slice(1)).join('')
 }
 
-// D3 (§4.2): a shape written twice can drift, and an alias names it
-// once. Every map or list whose shape recurs in the file, and whose
-// shape is REPEAT_MIN_WIDTH or wider, is reported once, at its first
-// site, with the count and the other sites; the naming is the
-// author's. A repeat inside a repeat is the outer one's: the walk does
-// not descend into a shape it reports.
 function repeats(nodes: Node[], text: string, out: LintFinding[]): void {
   const counts = new Map<string, number>()
   const tally = (node: Node): void => {
@@ -1537,9 +1332,6 @@ function repeats(nodes: Node[], text: string, out: LintFinding[]): void {
   }
 }
 
-// A node's shape: its spelling with the layout, the comments and, for
-// a map, the order of its entries taken out, so that two spellings of
-// one value are one shape, as they are one canon.
 function shape(node: Node): string {
   switch (node.t) {
     case 'map':
@@ -1581,15 +1373,6 @@ function sameDocument(root: any, after: string): boolean {
   return undefined === p.errors && root.canon === p.root.canon
 }
 
-// The check of a lawful rewrite: the spelling before and the spelling
-// after, evaluated in isolation, come to the same canon, the same
-// kinds of failure, and the same outcome of generation (§7.3). Local,
-// so it needs no include and no capability, and it applies whether or
-// not the document as a whole evaluates. The kinds, not the count: how
-// often one unresolved reference is reported depends on the order the
-// meet took. Generation too, because the engine generates from more
-// than the canon: a meet of maps with a nil member has refused a key
-// the same map written once generates.
 function sameByMeet(before: string, after: string): boolean {
   return meetOf(before) === meetOf(after)
 }
@@ -1636,12 +1419,6 @@ function checkFinding(path: string | undefined, expected: string, actual: string
   }
 }
 
-// THE TARGET'S OWN LINES ARE HELD ON LINES OF THEIR OWN (§3.14). The
-// desugaring is line for line, so a line of output is known by the
-// offset it begins at, and the node beginning there -- the quoted
-// string the desugaring wrote -- is marked. From there on it has no
-// one-line form, so every container holding it opens, and no two lines
-// of the generated file are ever packed onto one.
 function holdOutput(nodes: Node[], at: Set<number>): void {
   for (const node of nodes) {
     if (undefined !== node.at && at.has(node.at)) {
@@ -1673,11 +1450,6 @@ function outputAt(doc: string, flags: boolean[]): Set<number> {
 }
 
 
-// A finding's column in the TEMPLATE rather than in the document it
-// carries (§3.14): the marker and its one space stand before the aontu
-// on every line the resugaring writes. Every finding is on such a
-// line -- the two rules point at a key or at a container, and a line of
-// output is a bare string, which is neither.
 function shiftFindings(findings: LintFinding[], mark: string | undefined): LintFinding[] {
   return undefined === mark ? findings :
     findings.map((f) => ({ ...f, col: f.col + mark.length + 1 }))
@@ -1689,9 +1461,6 @@ function shiftFindings(findings: LintFinding[], mark: string | undefined): LintF
 // what `--check` and `--list` report.
 export function format(src: string, opts?: FormatOptions, hooks?: FormatHooks): FormatReport {
   const text = lf(src)
-  // A GENERATOR IS FORMATTED AS THE DOCUMENT IT CARRIES (§3.14): the
-  // template surface's two transforms stand either side of the
-  // formatter, and between them is what happens to any other document.
   const mark = opts?.template
   const doc = undefined === mark ? text : desugarTemplate(text, mark)
   const toks: Tok[] = []
@@ -1726,9 +1495,6 @@ export function format(src: string, opts?: FormatOptions, hooks?: FormatHooks):
 }
 
 
-// ---------------------------------------------------------------------
-// The unified diff of `--diff`
-
 // A patience diff: lines unique to both sides, in order, are the
 // anchors, and the gaps between them recurse. Not always the shortest
 // edit script, but linear in space, and the same script from both
@@ -1736,11 +1502,6 @@ export function format(src: string, opts?: FormatOptions, hooks?: FormatHooks):
 
 type Edit = { op: ' ' | '-' | '+', text: string }
 
-// The lines of a text, with a marker on the last when the text does
-// not end in a newline: such a line never equals its
-// newline-terminated twin, which is how the diff reports the
-// difference, and the marker is rendered as diff renders it. NUL,
-// which no source line ends in.
 const NO_NEWLINE = String.fromCharCode(0)
 
 function textLines(text: string): string[] {
@@ -1846,8 +1607,6 @@ function patience(
   }
 }
 
-// The diff in unified format, three lines of context, the file named
-// on both sides. Empty when the texts are the same.
 export function unifiedDiff(name: string, before: string, after: string): string {
   const a = textLines(before)
   const b = textLines(after)
@@ -1879,8 +1638,6 @@ export function unifiedDiff(name: string, before: string, after: string): string
   for (const [s, e] of hunks) {
     const from = Math.max(s - 3, 0)
     const to = Math.min(e + 4, edits.length)
-    // Everything between two hunks is context -- a change would have
-    // opened a hunk -- so both sides advance together.
     for (; next < from; next++) {
       ai++
       bi++

package/src/grammar.ts

@@ -0,0 +1,72 @@
+/* Copyright (c) 2026 Richard Rodger, MIT License */
+
+// The grammar seam, ADR-033. Twin of go/grammar.go.
+
+import { Tabnas } from '@tabnas/parser'
+import { abnf } from '@tabnas/abnf'
+
+import { AontuContext } from './ctx'
+
+
+// A constant, not a trust knob: this bounds a third party's grammar.
+const PARSE_STEP_MAX = 100000
+
+const PARSE_CHECK_EVERY = 100
+
+
+const cache = new Map<string, [any, string | undefined]>()
+
+
+const steps = { n: 0 }
+
+
+function compileGrammar(src: string): [any, string | undefined] {
+  const hit = cache.get(src)
+  if (undefined !== hit) {
+    return hit
+  }
+
+  let out: [any, string | undefined]
+  try {
+    // Lexing off, or the engine reads `1 . 2 . 3` as `1.2.3`. The hook
+    // is installed here because the engine takes it at construction.
+    const tn = new Tabnas({
+      space: { lex: false },
+      parse: {
+        budget: {
+          checkEveryN: PARSE_CHECK_EVERY,
+          onCheck: () => (steps.n += PARSE_CHECK_EVERY) <= PARSE_STEP_MAX,
+        }
+      }
+    })
+    tn.use(abnf)
+    tn.abnf(src)
+    out = [tn, undefined]
+  }
+  catch (e: any) {
+    out = [undefined, String(e?.message ?? e).split('\n')[0]]
+  }
+
+  cache.set(src, out)
+  return out
+}
+
+
+function parseWith(grammar: any, text: string, _ctx: AontuContext):
+  [any, string | undefined] {
+  steps.n = 0
+  try {
+    return [grammar.parse(text), undefined]
+  }
+  catch (e: any) {
+    return [undefined, String(e?.message ?? e).split('\n')[0]]
+  }
+} /* node:coverage ignore next 8 */
+
+
+export {
+  compileGrammar,
+  parseWith,
+  PARSE_STEP_MAX,
+  PARSE_CHECK_EVERY,
+}