aontu 0.57.0 → 0.59.0

package/src/format.ts

@@ -148,6 +148,10 @@ type Node = {
   // value; spread: the value.
   key?: string
   opt?: boolean
+  // pair: written with `=`, the alias declaration operator, rather than
+  // a colon. The spelling is the parse's -- a colon after an alias name
+  // is a refused document, and the formatter keeps it one.
+  alias?: boolean
   value?: Node
 
   // map, list: the entries, and the comment on the opener's line.
@@ -349,8 +353,9 @@ class Reader {
     if (this.atKey()) {
       const tok = this.T[this.i]
       const opt = '#QM' === this.name(1)
+      const alias = '=' === this.T[this.i + (opt ? 2 : 1)].src
       this.i += opt ? 3 : 2
-      return { t: 'pair', key: keyText(tok), opt, value: this.value(), at }
+      return { t: 'pair', key: keyText(tok), opt, alias, value: this.value(), at }
     }
     return this.value()
   }
@@ -590,6 +595,11 @@ function width(s: string): number {
 }
 
 function pairHead(node: Node, tight: boolean): 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 ? ':' : ': ')
 }
 
@@ -1104,7 +1114,7 @@ function mergeRuns(body: Node[]): Node[] {
       continue
     }
     out.push({
-      t: 'pair', key: first.key, opt: first.opt,
+      t: 'pair', key: first.key, opt: first.opt, alias: first.alias,
       value: { t: 'map', body: mergeRuns(merged) }, orig: group,
     })
     i = j - carry.length

package/src/hints.ts

@@ -122,7 +122,7 @@ const hints: Record<string, string> = {
     '  grouping     (...)  (?:...)      alternation  a|b\n' +
     '  anchors      ^  $  \\A  \\z  \\b  \\B\n' +
     ' \n' +
-    'Aontu DEFINES the abbreviations rather than inheriting either\n' +
+    'aontu DEFINES the abbreviations rather than inheriting either\n' +
     'host regex engine, so they mean the same in both ports:\n' +
     '  \\d [0-9]   \\w [0-9A-Za-z_]   \\s [ \\t\\n\\r\\f\\v]   . [^\\n]\n' +
     'Note \\s is these six ASCII characters only -- not U+00A0.\n' +
@@ -164,13 +164,17 @@ const hints: Record<string, string> = {
   merge_conflict: 'A version-control conflict marker was found in the source. The\nfile still holds an unresolved merge: resolve it and remove the\n`<<<<<<<`, `=======` and `>>>>>>>` lines before unifying.\n \nExamples:\n  <<<<<<< HEAD  -> nil  # A conflict marker, not a `<` operation;\n  =======       -> nil  # ... nor a chain of `=` characters;\n  >>>>>>> other -> nil  # ... nor a `>` operation.',
 
   include_denied: 'An @"..." include was refused by the active trust profile\n(docs/trust.md). The document asked to read a source the evaluation\'s\ninclude capability does not allow: widen the capability if the read is\nintended, or remove the include if it is not.\n \nExamples:\n  a:@"in-root.aon"    -> {..}  # Inside the confinement root: allowed;\n  a:@"../secret.aon"  -> nil   # ... but escaping the root is denied;\n  a:@"/etc/hostname"  -> nil   # ... and so is an absolute path outside it.',
-  include_extension: 'An @\"...\" include named a file the engine does not read. THE\nEXTENSION DECIDES which of two things a file is: `.aon` and\n`.aontu` are Aontu source, with the whole language in them, and\n`.json`, `.jsonld`, `.jsonc`, `.json5`, `.jsonic`, `.jsc`, `.toml`,\n`.yaml`, `.yml` and `.ini` are configuration DATA, read by that\nformat\'s own parser. Anything else -- and a name with no extension\n-- is refused rather than guessed at: a guess produces a document\nthat looks right and is not.\n \nExamples:\n  a:@\"model.aon\"    -> {..}  # Aontu source;\n  a:@\"server.toml\"  -> {..}  # ... config data, read as TOML;\n  a:@\"notes.txt\"    -> nil   # ... but text is not a document;\n  a:@\"data\"         -> nil   # ... and neither is an unnamed kind.',
+  include_extension: 'An @\"...\" include named a file the engine does not read. THE\nEXTENSION DECIDES which of two things a file is: `.aon` and\n`.aontu` are aontu source, with the whole language in them, and\n`.json`, `.jsonld`, `.jsonc`, `.json5`, `.jsonic`, `.jsc`, `.toml`,\n`.yaml`, `.yml` and `.ini` are configuration DATA, read by that\nformat\'s own parser. Anything else -- and a name with no extension\n-- is refused rather than guessed at: a guess produces a document\nthat looks right and is not.\n \nExamples:\n  a:@\"model.aon\"    -> {..}  # aontu source;\n  a:@\"server.toml\"  -> {..}  # ... config data, read as TOML;\n  a:@\"notes.txt\"    -> nil   # ... but text is not a document;\n  a:@\"data\"         -> nil   # ... and neither is an unnamed kind.',
 
   func_arity: 'This function was called with the wrong number of arguments:\n{func} takes {want}, but was given {got}.\n \nExamples:\n  upper(\"a\")     -> \"A\"  # One argument, which is what upper takes;\n  upper(\"a\",\"b\") -> nil  # ... so two is a mistake in the source;\n  key()          -> \"\"   # key takes none, or one level count;\n  neq(1,2,3)     -> neq  # ... and neq takes one or more exclusions.',
   func_arg: 'This argument does not fit the function\'s signature:\n \n  {sig}\n  argument {argn} (`{arg}`) was `{got}`.\n \nThe signature is the declared call surface (one line per builtin,\ntest/spec/signature.tsv); an argument slot admits a concrete value\nof its declared kind, `number` admitting every numeric leaf and\n`string` admitting a path.\n \nExamples:\n  upper("a")     -> "A"    # A string fits upper(s: string|number);\n  upper(1)       -> 1      # ... and so does a number;\n  upper(true)    -> nil    # ... but a boolean fits neither word;\n  add([1],2)     -> nil    # ... and a list is no operand.',
 
   elided_value: 'A key or element was written with no value after the colon. An\nelided value is a mistake in the source rather than a null: write\n`null` if that is what was meant, or supply the value.\n \nExamples:\n  a:null  -> null  # An explicit null, which is a value;\n  a:      -> nil   # ... but nothing at all is not;\n  a: b:1  -> {..}  # A colon chain is not an elision;\n  [1,]    -> [1]   # ... nor is a trailing comma.',
 
+  alias_colon: 'An alias is declared with `=`: write `%name = value`. Until 0.57.0\nthe declaration was spelled with a colon, `%name: value`, and that\nform is refused rather than read as an ordinary key -- a document\nwritten for the old spelling fails here, at the declaration, instead\nof gaining a key named `%name` and a use that resolves to nothing.\n \nExamples:\n  %u8 = integer & min(0)  -> {..}  # Declares %u8, which a: %u8 uses;\n  %u8: integer            -> nil   # The form before 0.58.0, refused;\n  "%u8": 1                -> {..}  # A quoted key is an ordinary key.',
+
+  bare_punct: 'A bare string holds letters, digits, `-` and `_`, and nothing else.\nThis one holds `{char}`, in `{text}`. Every other punctuation\ncharacter is either syntax or an error, never silently part of a\nstring: a value that needs one is written quoted, and a `>` or `<`\nthat was meant as a bound is written as min(x), max(x), above(x) or\nbelow(x).\n \nExamples:\n  a: team-payments  -> "team-payments"  # `-` and `_` are text;\n  a: 2026-09-05     -> "2026-09-05"     # ... digits included;\n  a: x=y            -> nil              # `=` is not;\n  a: "x=y"          -> "x=y"            # ... so quote it;\n  a: >10            -> nil              # Not an operator: write above(10).',
+
 
 
 
@@ -191,6 +195,11 @@ const hints: Record<string, string> = {
 
   view_kind_unknown: 'The figure kind is not one the verb draws. The kinds are tree, matrix,\ngraph, layer, sets, layers, ladder and poset; the note lists them.',
 
+  render_path: 'A unit path is written below the output directory: relative, with no\n`..` segment, and no two units the same. Rename the unit.',
+  render_lang: 'A text escape carries verbatim syntax of ONE language, and it must be\nthe unit\'s: a text of another language in this unit would be written\nas if it were this one. Move it to a unit of its own language.',
+  render_profile: 'Only fragments and text escapes render without a lowering, under the\ntext profile. A record, enum, alias, const or func needs a profile\nwhose language has one (typescript, go): set the unit\'s lang, or\nwrite the declaration as a fragment.',
+  render_strict: 'Under strict, an opaque escape -- a text declaration or a raw piece,\nwhich the renderer cannot check -- is refused. Write it as lines, or\nrender without strict and read the loss report.',
+  render_unit: 'The unit asked for is not in the instance. The report names the\npath; the units are listed by `--format json`.',
   view_profile_unknown: 'The figure kind does not render into the profile asked for: there is no\ntext form of a node-link drawing and no Mermaid form of a matrix. The\nnote lists the profiles the kind declares; the first is its default.',
 
   format_check: 'The formatted text is not the same document, so nothing was written.\nThis is a formatter defect: please report it, with the source.',
@@ -234,7 +243,15 @@ const hints: Record<string, string> = {
 
   emit_none: 'No template matched a node, and there is no catch-all. `emit`\ntries each template in the order written and takes the first the\nnode unifies with; the node {value} unified with none of {tried}.\nAdd a template whose `match` is `any` — last, since the first match\nwins — if the rest of the selection was meant to be allowed.\n \nExamples:\n  emit([1], [{match:integer,body:[a]}])  -> [..]  # A pattern matches;\n  emit([x], [{match:any,body:[a]}])      -> [..]  # ... or a catch-all;\n  emit([x], [{match:integer,body:[a]}])  -> nil   # ... but nothing here.',
 
-  esc_variant: 'esc() and usc() were given a variant that names no convention.\nA variant names a CONVENTION rather than a language, because several\nlanguages share one and one language has several. The names are `sq`,\n`sql`, `shell`, `xml`, `uri` and `regex`; written with no variant at\nall it is the C escape, JSON canonical, which covers the double-quoted\nliteral of every C-family language.\n \nExamples:\n  esc(text)          -> ...   # C / JSON, the default;\n  esc(text, sq)      -> ...   # ... single-quoted C-family;\n  esc(text, pascal)  -> nil   # ... but that is not a convention.',
+  replace_overlap: "Two keys of a template's `replace` map overlap: {key} is inside\n{other}. A replacement is one left-to-right scan of the body's literal\ntext taking the longest key at each position, and a key inside\nanother is ambiguous whatever the order -- so it is refused on the\ntemplate, before any node is visited.\n \nExamples:\n  replace: {PIN: .pin, MSG: .msg}  # Two keys, neither inside the other;\n  replace: {PIN: .pin}            # ... or one alone;\n  replace: {P: .p, PIN: .pin}     # ... but P is inside PIN.",
+
+  replace_unused: 'A key of a template\'s `replace` map matches nothing: {key} appears\nin none of the body\'s literal lines. A replacement key is an exact\nstring the body already holds as ordinary target text, so a key the\nbody does not hold means the template drifted from its map -- refused\nbefore any node is visited, since the drift is the same for every\nnode.\n \nExamples:\n  {replace: {PIN: .pin}, body: ["listen(PIN)"]}  # The body holds PIN;\n  {replace: {PIN: .pin}, body: ["pin: PIN"]}     # ... anywhere in a line;\n  {replace: {PIN: .pin}, body: ["listen(pin)"]}  # ... but not here.',
+
+  replace_value: 'A replacement value is not text: the `replace` key {key} came to\n{value} at the node. A value reaches the body as a string -- a number\nor a boolean spells itself, as it does after `+` -- and it has to\nhave settled by the time the dispatch fires, so a map, a list, a\nnull or a value still unresolved is refused rather than written into\na file as something else.\n \nExamples:\n  replace: {PIN: .pin}    # A string field;\n  replace: {PORT: .port}  # ... or a number, as digits;\n  replace: {ALL: _}       # ... but the node itself is a map.',
+
+  form_data: 'The first argument to form() is not a bag. `form` makes one list\nelement per child of its DATA, so the data has to have children: a\nlist, or a map whose values are taken in sorted-key order.\n \nExamples:\n  form([a,b], upper(_))  -> [..]  # A list, in source order;\n  form({b:2,a:1}, _)     -> [..]  # ... a map, in sorted-key order;\n  form(1, _)             -> nil   # ... but a scalar has no children.',
+
+  esc_variant: 'esc(), usc() or a template\'s `esc:` key were given a variant that\nnames no convention.\nA variant names a CONVENTION rather than a language, because several\nlanguages share one and one language has several. The names are `sq`,\n`sql`, `shell`, `xml`, `uri` and `regex`; written with no variant at\nall it is the C escape, JSON canonical, which covers the double-quoted\nliteral of every C-family language.\n \nExamples:\n  esc(text)          -> ...   # C / JSON, the default;\n  esc(text, sq)      -> ...   # ... single-quoted C-family;\n  esc(text, pascal)  -> nil   # ... but that is not a convention.',
 
   usc_malformed: 'usc() was given text the convention could not have produced,\nso there is nothing to read back out: a truncated code-point escape, an\nescape the convention does not define, or an escape character standing\nalone where the convention doubles it. `usc` is the LEFT inverse of\n`esc` and it is partial — every escaped value has an original, but not\nevery string is an escaped value.\n \nExamples:\n  usc(esc(text))     -> ...   # Whatever esc() wrote;\n  usc(text, sql)     -> ...   # ... in the same convention;\n  usc(text, shell)   -> nil   # ... but not in another one.',
 
@@ -267,7 +284,7 @@ const hints: Record<string, string> = {
     'This exact decimal exceeds the exactness budget: at most 4096\n' +
     'coefficient digits and an absolute scale of at most 4096. The\n' +
     'budget applies to computed results as well as to literals.\n' +
-    'Aontu never rounds, so a value beyond the budget is refused\n' +
+    'aontu never rounds, so a value beyond the budget is refused\n' +
     'rather than approximated.' +
     '\n \nExamples:\n' +
     '  0d1e1000000000    -> nil  # Scale far beyond the budget;\n' +
@@ -277,7 +294,7 @@ const hints: Record<string, string> = {
   lossy_integer_literal:
     'This integer literal, {src}, is not exactly representable in\n' +
     'binary64, so storing it would silently round it to a DIFFERENT\n' +
-    'number. Aontu refuses rather than corrupts: write it as a `0d`\n' +
+    'number. aontu refuses rather than corrupts: write it as a `0d`\n' +
     'literal to get the exact integer.\n' +
     'The rule is exactness, not magnitude -- a literal far outside the\n' +
     'int64 window is still a value when it lands exactly on a binary64.' +
@@ -289,7 +306,7 @@ const hints: Record<string, string> = {
     '  100000000000000000000 -> 1e20 # 10^20 is huge and exact.',
 
   exact_float_mix:
-    'Aontu cannot mix an exact number with a binary float.\n' +
+    'aontu cannot mix an exact number with a binary float.\n' +
     'Here the operands are {left} and {right}, in that order.\n' +
     'A big type never silently becomes a binary float, in either\n' +
     'operand order -- binary64 cannot hold every exact value, so the\n' +
@@ -354,7 +371,7 @@ const hints: Record<string, string> = {
 
   divide_by_zero:
     'Division by zero. `div`, `mod` and `rem` refuse a zero divisor in\n' +
-    'every numeric leaf, including binary floats: Aontu is a JSON\n' +
+    'every numeric leaf, including binary floats: aontu is a JSON\n' +
     'superset with no notation for an infinity, so there is no value\n' +
     'the operation could answer with. A definition that divides by zero\n' +
     'is wrong, and this says so where it is written rather than\n' +
@@ -380,7 +397,7 @@ const hints: Record<string, string> = {
 
   float_overflow:
     'This result is not a finite binary64 number, so it is not a value\n' +
-    'Aontu can carry. There is no notation for an infinity or a NaN in\n' +
+    'aontu can carry. There is no notation for an infinity or a NaN in\n' +
     'a JSON superset, and no JSON a generator could emit for one, so\n' +
     'the operation is refused where it is written rather than escaping\n' +
     'as an internal error or an unserialisable value.\n' +
@@ -395,7 +412,7 @@ const hints: Record<string, string> = {
     'The `integer` leaf holds a value only when it is integral, within\n' +
     'the int64 range, and exactly representable in binary64. This\n' +
     'result is not: {sum}.\n' +
-    'Aontu computes integers exactly and refuses to store a rounded\n' +
+    'aontu computes integers exactly and refuses to store a rounded\n' +
     'answer -- write `0d<digits>` for an exact integer beyond that\n' +
     'window.' +
     '\n \nExamples:\n' +
@@ -537,6 +554,15 @@ const codeClasses: Record<string, string> = {
   view_profile_unknown: 'reference',
   view_style_profile: 'reference',
   view_style_unknown: 'reference',
+  // The renderer (docs/design/RENDER.0.md D7, D8): a unit path that is
+  // not a relative descent of its own, a text escape in the wrong
+  // language, a declaration with no lowering, an opaque escape under
+  // strict, a unit filter that names nothing.
+  render_path: 'parse',
+  render_lang: 'conflict',
+  render_profile: 'parse',
+  render_strict: 'conflict',
+  render_unit: 'reference',
   // The formatter's self-check (docs/design/FMT.0.md): a report-layer
   // code, class internal -- the formatter, not the document, is wrong.
   format_check: 'internal',
@@ -596,6 +622,16 @@ const codeClasses: Record<string, string> = {
   emit_none: 'conflict',
   emit_ref: 'conflict',
 
+  // RENDER P6 -- `replace` on a template, and `form`. The two
+  // template checks are class `parse`: what is wrong is the TEMPLATE
+  // as written, before any node. `replace_value` is class `conflict`:
+  // the node's value and the body that wanted text disagreed.
+  // `form_data` is `each_data`'s twin.
+  replace_overlap: 'parse',
+  replace_unused: 'parse',
+  replace_value: 'conflict',
+  form_data: 'parse',
+
   // G8 phase 3 -- the placeholder. Class `conflict`: two values met
   // and neither could answer for the other, which is what every
   // conflict is.
@@ -627,6 +663,8 @@ const codeClasses: Record<string, string> = {
   pref_implicit_bag: 'parse',
   alias_not_toplevel: 'parse',
   alias_in_path: 'parse',
+  alias_colon: 'parse',
+  bare_punct: 'parse',
   not_number: 'parse',
   negative: 'parse',
   decimal_syntax: 'parse',