aontu 0.60.0 → 0.61.0

package/src/cli.ts

@@ -27,7 +27,7 @@ import {
   renderProfile,
 } from './aontu'
 import type { RenderCoverage, RenderReport } from './render'
-import { desugarTemplate, resugarTemplate, markerFor } from './template'
+import { desugarTemplate, resugarTemplate, templateOutputs, markerFor } from './template'
 import { outsideRoot } from './mcp'
 import { sarifReport } from './report-sarif'
 import { main as lspMain } from './lsp-server'
@@ -83,7 +83,7 @@ const HELP = `Usage: aontu [options] [file]
        aontu why <path> [options] <file>
        aontu set <path>=<value>... --entry <file> --overlay <file>
        aontu agentsmd [--write <AGENTS.md>] <file>
-       aontu fmt [-w|-l|--check|-d|--lint] <file>...
+       aontu fmt [-w|-l|--check|-d|--lint] [--marker <token>] <file>...
        aontu lsp
        aontu mcp [--root <dir>]
 
@@ -351,10 +351,18 @@ Fmt options:
   --lint          Report the style findings, key case and repeated
                   shapes, on standard error, and print nothing else
   --strict        With --lint, and exit 1 when there is a finding
+  --marker <t>    The file is a generator, and this is its marker
+                  (default //-, and #- --- /*- by extension)
 
 The fmt verb prints one document in the agreed form; with no file it
 reads standard input. Several files need one of the options above.
 
+A file whose extension is not .aon is a GENERATOR, as it is for render:
+the aontu its marker lines carry is formatted, the marker stands at the
+left margin with the aontu indented after it, and every line of output
+is held on a line of its own. A file with no marker line in it is
+another language's, and is refused.
+
 Fmt exit codes: 0 formatted or clean, 1 a --check file would change or
 a --strict finding, 2 usage, 4 a document does not parse.
 
@@ -3945,7 +3953,8 @@ function runAgentsMd(argv: string[]): number {
 // the form itself is the library's (ts/src/format.ts), and the two
 // ports agree on it row by row in test/spec/fmt.tsv.
 
-const FMT_HELP = 'aontu fmt [-w|-l|--check|-d|--lint] <file>... (try --help)'
+const FMT_HELP =
+  'aontu fmt [-w|-l|--check|-d|--lint] [--marker <token>] <file>... (try --help)'
 
 type FmtFlags = {
   write: boolean, list: boolean, check: boolean, diff: boolean, lint: boolean, strict: boolean,
@@ -3953,11 +3962,13 @@ type FmtFlags = {
 
 function runFmt(argv: string[]): number | Promise<number> {
   const files: string[] = []
+  let marker: string | undefined = undefined
   const flags: FmtFlags = {
     write: false, list: false, check: false, diff: false, lint: false, strict: false,
   }
 
-  for (const arg of argv) {
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
     if ('-h' === arg || '--help' === arg) {
       process.stdout.write(HELP)
       return 0
@@ -3981,6 +3992,16 @@ function runFmt(argv: string[]): number | Promise<number> {
       flags.lint = true
       flags.strict = true
     }
+    else if ('--marker' === arg) {
+      // THE MARKER SAYS THE FILE IS A GENERATOR, whatever its
+      // extension: `render` and `template` take the same option for
+      // the same reason, a language the table has never seen.
+      marker = argv[++i]
+      if (null == marker) {
+        process.stderr.write('aontu: --marker needs a token\n')
+        return 2
+      }
+    }
     else if (arg.startsWith('-')) {
       process.stderr.write(`aontu: unknown fmt option ${arg} (try --help)\n`)
       return 2
@@ -4002,7 +4023,7 @@ function runFmt(argv: string[]): number | Promise<number> {
       let src = ''
       process.stdin.setEncoding('utf8')
       process.stdin.on('data', (d) => (src += d))
-      process.stdin.on('end', () => resolve(fmtOne('<stdin>', src, flags)))
+      process.stdin.on('end', () => resolve(fmtOne('<stdin>', src, flags, marker)))
     })
   }
 
@@ -4018,23 +4039,6 @@ function runFmt(argv: string[]): number | Promise<number> {
 
   let worst = 0
   for (const file of files) {
-    // FMT FORMATS AONTU SOURCE, AND THE EXTENSION SAYS WHAT A FILE IS
-    // (ADR-012's rule, and the one `render` reads a template by).
-    // A TEMPLATE FILE IS NOT AONTU (docs/design/TEMPLATE.0.md; P8):
-    // its marker lines are fragments of a document and its other lines
-    // are the target's, so there is nothing here to format that would
-    // not also rewrite the output. Refused rather than attempted, and
-    // refused BY NAME rather than by a parse failure, because a `#-`
-    // template parses: `#` opens a comment, so every marker line
-    // vanishes and what is left is read as a document that was never
-    // written. The verb answered `0` over one, having understood none
-    // of it.
-    if (!/[.](aon|aontu)$/.test(file)) {
-      process.stderr.write(
-        `aontu: ${file} is not aontu source (.aon, .aontu); a generator ` +
-        'written in the target\'s own syntax is aontu template\'s\n')
-      return 2
-    }
     let src: string
     try {
       src = readFileSync(file, 'utf8')
@@ -4043,11 +4047,46 @@ function runFmt(argv: string[]): number | Promise<number> {
       process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`)
       return 2
     }
-    worst = Math.max(worst, fmtOne(file, src, flags))
+    const mark = fmtMarker(file, src, marker)
+    if (false === mark) {
+      process.stderr.write(
+        `aontu: ${file} is not aontu source (.aon, .aontu) and carries no ` +
+        `${markerFor(file)} marker line, so there is no aontu in it to ` +
+        'format; --marker names the marker for a language the table does ' +
+        'not know\n')
+      return 2
+    }
+    worst = Math.max(worst, fmtOne(file, src, flags, mark))
   }
   return worst
 }
 
+// WHAT A FILE IS, BY ITS EXTENSION (ADR-012's rule, and the one
+// `render` reads an entry by): `.aon` and `.aontu` are aontu source,
+// and anything else is a GENERATOR written in the target's own syntax
+// (docs/design/TEMPLATE.0.md), whose marker lines carry the document
+// this formats and whose other lines are output. `undefined` is aontu,
+// a string is the generator's marker, and `false` is neither.
+//
+// A FILE WITH NO MARKER LINE IN IT IS NEITHER, and that is what keeps
+// FMT.0.md §9's boundary where it stood: a `.json`, `.yaml` or `.toml`
+// include is another language's file, and reading one as a generator
+// would answer it back unchanged having understood none of it. The
+// marker is the evidence that a file was written to carry aontu at
+// all. `--marker` says so outright, and then the file is a generator
+// whatever it is called.
+function fmtMarker(
+  file: string, src: string, marker: string | undefined): string | undefined | false {
+  if (undefined !== marker) {
+    return marker
+  }
+  if (/[.](aon|aontu)$/.test(file)) {
+    return undefined
+  }
+  const mark = markerFor(file)
+  return templateOutputs(src, mark).some((out) => !out) ? mark : false
+}
+
 // An option that says what to do with a file, in place of printing
 // it: what to do when its form would change, or the lint.
 function fmtQuiet(flags: FmtFlags): boolean {
@@ -4059,8 +4098,9 @@ function fmtQuiet(flags: FmtFlags): boolean {
 // document that does not format, with the finding that says why. The
 // style findings go to standard error, one line each, in the shape
 // every linter prints: `file:line:col: rule: message`.
-function fmtOne(name: string, src: string, flags: FmtFlags): number {
-  const report = format(src, { path: name, lint: flags.lint })
+function fmtOne(
+  name: string, src: string, flags: FmtFlags, marker?: string): number {
+  const report = format(src, { path: name, lint: flags.lint, template: marker })
   if ('error' === report.verdict) {
     process.stderr.write(`aontu: ${name} was not formatted\n` +
       report.errors.map(renderFinding).join('\n') + '\n')

package/src/format.ts

@@ -26,6 +26,7 @@ import { Aontu } from './aontu'
 import { failureFinding } from './vet'
 import type { VetFinding } from './vet'
 import type { Resolver } from './type'
+import { desugarTemplate, resugarTemplate, templateOutputs } from './template'
 
 
 // The packing budget (§3.1). It decides which of two legal spellings
@@ -46,6 +47,12 @@ 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
 }
 
 // A style finding (§4): what the formatter points at and never
@@ -183,6 +190,10 @@ type Node = {
 
   // The source index of the node's first token: the lint's positions.
   at?: number
+
+  // The node begins a line of the target's own file (§3.14), so it has
+  // no one-line form and every container holding it opens.
+  held?: boolean
 }
 
 const BINARY: Record<string, boolean> = { '#E&': true, '#E|': true, '#E+': true }
@@ -608,7 +619,7 @@ function pairHead(node: Node, tight: boolean): string {
 // 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) {
+  if (undefined !== node.trail || node.held) {
     return undefined
   }
   switch (node.t) {
@@ -744,6 +755,15 @@ 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, '')
+    }
+  }
+
   // The lines since a mark replaced by a text: the spelling before,
   // where a rewrite did not pass its check.
   replace(mark: number, text: string): void {
@@ -776,29 +796,57 @@ function rtrim(s: string): string {
 // 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): void {
+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) {
     if ('blank' === node.t) {
       pending = 0 < count
       continue
     }
+    const gapped = pending
     w.open(indent, pending)
+    if (gapped || !noted) {
+      head = w.mark()
+    }
     pending = false
     count++
     if ('comment' === node.t) {
+      noted = true
       w.text(node.text!)
       continue
     }
+    noted = false
+    const from = w.mark()
     if (undefined !== stmt && 'pair' === node.t) {
       emitStatement(w, node, indent, stmt, '')
-      continue
     }
-    const e = chain(node)
-    emitValue(w, e, indent)
-    if (undefined !== e.trail) {
-      w.text(' ' + e.trail)
+    else {
+      const e = chain(node)
+      emitValue(w, e, indent)
+      if (undefined !== e.trail) {
+        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
     }
   }
 }
@@ -1282,7 +1330,7 @@ function emitAt(nodes: Node[], indent: number): string {
 function emit(root: Node[], meet: Meet | undefined): string {
   const w = new Writer()
   emitBody(w, undefined === meet ? root : mergeRuns(root), 0,
-    undefined === meet ? undefined : { meet, covered: false })
+    undefined === meet ? undefined : { meet, covered: false }, true)
   return w.finish()
 }
 
@@ -1516,13 +1564,66 @@ 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)) {
+      node.held = true
+    }
+    holdOutput(node.body ?? [], at)
+    holdOutput(node.args ?? [], at)
+    holdOutput(node.inner ?? [], at)
+    holdOutput(node.items ?? [], at)
+    if (undefined !== node.value) {
+      holdOutput([node.value], at)
+    }
+  }
+}
+
+
+// The offsets the flagged lines of a document begin at.
+function outputAt(doc: string, flags: boolean[]): Set<number> {
+  const at = new Set<number>()
+  let off = 0
+  const lines = doc.split('\n')
+  for (let k = 0; k < lines.length; k++) {
+    if (flags[k]) {
+      at.add(off)
+    }
+    off += lines[k].length + 1
+  }
+  return at
+}
+
+
+// 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 }))
+}
+
+
 // Format one document. The text is the agreed form of the source;
 // `changed` says whether it differs from what was given, which is
 // 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[] = []
-  const parsed = parseDoc(text, opts?.path, toks)
+  const parsed = parseDoc(doc, opts?.path, toks)
   if (undefined !== parsed.errors) {
     return { verdict: 'error', errors: parsed.errors }
   }
@@ -1531,6 +1632,9 @@ export function format(src: string, opts?: FormatOptions, hooks?: FormatHooks):
   if (reader.deep) {
     return { verdict: 'error', errors: [depthFinding()] }
   }
+  if (undefined !== mark) {
+    holdOutput(root, outputAt(doc, templateOutputs(text, mark)))
+  }
   // The syntactic tier first, checked against the parse tree; then the
   // lawful tier over it, each rewrite checked by the meet.
   const plain = emit(root, undefined)
@@ -1542,9 +1646,10 @@ export function format(src: string, opts?: FormatOptions, hooks?: FormatHooks):
     }
   }
   const out = emit(root, hooks?.meet ?? sameByMeet)
+  const done = undefined === mark ? out : resugarTemplate(out, mark)
   return {
-    verdict: 'formatted', text: out, changed: out !== src,
-    findings: opts?.lint ? lintOf(root, text) : [],
+    verdict: 'formatted', text: done, changed: done !== src,
+    findings: opts?.lint ? shiftFindings(lintOf(root, doc), mark) : [],
   }
 }
 

package/src/std.ts

@@ -186,6 +186,7 @@ const STD_CODE = String.raw`# aontu:code --- THE OUTPUT VOCABULARY. An aontu tra
   k: "prim"
   prim: "string" | "int" | "bigint" | "float" | "decimal" | "bool" | "null" | "any"
 })
+
 %ref = close({ k:"ref" name:%name unit?:string })
 %leaf = %prim | %ref | %text
 
@@ -208,6 +209,7 @@ const STD_CODE = String.raw`# aontu:code --- THE OUTPUT VOCABULARY. An aontu tra
 })
 
 %member = close({ name:%name value?:string | number doc?:%doc x?:{} })
+
 %param = close({
   name: %name
   type: %type
@@ -221,12 +223,14 @@ const STD_CODE = String.raw`# aontu:code --- THE OUTPUT VOCABULARY. An aontu tra
 %inline = string & re("^[^\n\r]*$") | %ref
 %line = close({ k:"line" at:*0 | integer & min(0) & max(64) of:[&: %inline] })
 %blank = close({ k:"blank" n:*1 | integer & min(1) & max(16) })
+
 %raw = close({
   k: "raw"
   at: *0 | integer & min(0) & max(64)
   text: string
   reindent: *true | boolean
 })
+
 %piece = %line | %blank | %raw | string & re("^[^\n\r]*$")
 %frag = close({ k:"frag" of:[&: %piece] })
 %body = %frag | close({ k:"abstract" })
@@ -241,7 +245,9 @@ const STD_CODE = String.raw`# aontu:code --- THE OUTPUT VOCABULARY. An aontu tra
   check?: [&: %check]
   x?: {}
 })
+
 %enum = close({ k:"enum" name:%name doc?:%doc members:[&: %member] x?:{} })
+
 %alias = close({
   k: "alias"
   name: %name
@@ -250,6 +256,7 @@ const STD_CODE = String.raw`# aontu:code --- THE OUTPUT VOCABULARY. An aontu tra
   check?: [&: %check]
   x?: {}
 })
+
 %const = close({
   k: "const"
   name: %name
@@ -258,6 +265,7 @@ const STD_CODE = String.raw`# aontu:code --- THE OUTPUT VOCABULARY. An aontu tra
   value: string | number | boolean | null
   x?: {}
 })
+
 %func = close({
   k: "func"
   name: %name

package/src/template.ts

@@ -24,12 +24,22 @@
 // comment, and derives for a language this table has never seen: the
 // caller passes the token.
 //
-// A MARKER IS RECOGNISED AFTER LEADING WHITESPACE AND KEEPS ITS OWN
-// INDENTATION (D2). That is what lets a template be written exactly
-// where its output appears (D7): a body line is verbatim, so a line
-// indented two spaces in the template is indented two spaces in the
-// generated file, and the marker lines around it are indented to match
-// the code they sit in rather than to the aontu they carry.
+// A MARKER IS RECOGNISED AFTER LEADING WHITESPACE, AND THE INDENTATION
+// THE RESUGARING WRITES IS THE AONTU'S (D2, amended 2026-09-07). An
+// output line is verbatim -- a line indented two spaces in the template
+// is indented two spaces in the generated file (D7) -- and that is the
+// half a reader of the TARGET needs. The other half is the document:
+// the marker lines carry a tree, and a tree nobody can see the shape of
+// is the one thing this surface took away. So the marker stands at the
+// left margin and the aontu is indented AFTER it, which `aontu fmt`
+// (FMT.0.md M-BM-'3.14) is what writes.
+//
+// Reading is unchanged and stays generous: a marker after leading
+// whitespace is a marker, and its own indentation still counts toward
+// the aontu it carries, so a template written the other way desugars to
+// the same document. What changes is the spelling the round trip
+// answers, and `template --check` names the difference as the drift it
+// is.
 //
 // THE SUGAR IS THE FIXPOINT OF THE TWO TRANSFORMS (D6), and that is
 // the whole of the resugaring's safety. A canonical line that looks
@@ -128,13 +138,19 @@ function indentOf(line: string): number {
 }
 
 
-// The line without its indentation or its trailing spaces and tabs.
-function trimLine(line: string): string {
+// The line without its trailing spaces and tabs.
+function trimEnd(line: string): string {
   let end = line.length
   while (0 < end && (' ' === line[end - 1] || '\t' === line[end - 1])) {
     end--
   }
-  return line.slice(indentOf(line), end)
+  return line.slice(0, end)
+}
+
+
+// The line without its indentation or its trailing spaces and tabs.
+function trimLine(line: string): string {
+  return trimEnd(line).slice(indentOf(line))
 }
 
 
@@ -159,12 +175,15 @@ function readLine(line: string, marker: string): Line {
   // The block form's closer is part of the marker, not of the aontu.
   // A block marker line that never closes is not a marker line: the
   // language's own parser would not read it as a comment either.
+  // Only the TRAILING space goes: what stands between the opener and
+  // the aontu is the aontu's indentation, exactly as it is for a line
+  // marker, and the one-space rule below takes the marker's own.
   if (isBlock(marker)) {
     const end = body.lastIndexOf(BLOCK_CLOSE)
     if (end < 0) {
       return { marker: false, indent: '', text: line }
     }
-    body = trimLine(body.slice(0, end))
+    body = trimEnd(body.slice(0, end))
   }
   // ONE SPACE AFTER THE MARKER IS THE MARKER'S, so `//- x: 1` carries
   // `x: 1` and the resugaring writes the space back. A marker written
@@ -273,19 +292,40 @@ function resugarTemplate(src: string, marker?: string): string {
     if (undefined !== target && desugarTemplate(target, mark) === trimLine(line)) {
       return target
     }
-    const cut = indentOf(line)
-    const text = line.slice(cut)
-    const open = line.slice(0, cut) + mark
+    // THE MARKER STANDS AT THE LEFT MARGIN and the line's indentation
+    // is written after it, so the aontu's own shape is on the page.
+    // The one space is the marker's, which the reading takes back.
+    const text = trimEnd(line)
     const close = isBlock(mark) ? ' ' + BLOCK_CLOSE : ''
-    return '' === text ? open + close : open + ' ' + text + close
+    return '' === text ? mark + close : mark + ' ' + text + close
   })
   return out.join('\n') + (tail ? '\n' : '')
-} /* node:coverage ignore next 8 */
+}
+
+
+// WHICH LINES OF THE DESUGARED DOCUMENT ARE THE TARGET'S. The
+// desugaring is line for line, so this is one flag per line of what
+// `desugarTemplate` returns: true where the template's line was not a
+// marker, and so where the document's line is one quoted line of the
+// generated file.
+//
+// `aontu fmt` reads it (FMT.0.md M-BM-'3.14) to hold those lines on lines of
+// their own. A body element is a string like any other, and the packing
+// budget would put three of them on one line -- which is aontu where
+// three lines of output were, and a generator that writes them as one.
+function templateOutputs(src: string, marker: string): boolean[] {
+  const lines = src.split('\n')
+  if (1 < lines.length && '' === lines[lines.length - 1]) {
+    lines.pop()
+  }
+  return lines.map((line) => !readLine(line, marker).marker)
+} /* node:coverage ignore next 9 */
 
 
 export {
   desugarTemplate,
   resugarTemplate,
+  templateOutputs,
   markerFor,
   DEFAULT_MARKER,
 }