aontu 0.57.0 → 0.59.0

package/skill/SKILL.md

@@ -1,23 +1,23 @@
 ---
 name: aontu
 description: >-
-  Write, check and query Aontu definitions — a JSON superset where
+  Write, check and query aontu definitions — a JSON superset where
   documents UNIFY instead of overwriting. Use when a repository holds
   `.aon` files, when configuration must satisfy a schema rather than
   merely parse, or when you need to ask what a configuration says at a
   path and why it says it.
 ---
 
-# Aontu
+# aontu
 
-Aontu is JSON plus a lattice. Two documents do not override each
+aontu is JSON plus a lattice. Two documents do not override each
 other, they **unify**: the result is the most specific value that
 satisfies both, or an error naming the contradiction. That makes a
 definition checkable, queryable and safe to change.
 
 Start here:
 
-- Every JSON document is an Aontu document. Write JSON, then add
+- Every JSON document is an aontu document. Write JSON, then add
   what JSON cannot say.
 - [`grammar-card.md`](grammar-card.md) — the whole surface on one
   page.

package/skill/error-codes.md

@@ -1,6 +1,6 @@
 # What a refusal means
 
-Every Aontu error carries a **code**, and every code has a **class**.
+Every aontu error carries a **code**, and every code has a **class**.
 The class says what kind of thing went wrong, which is what decides
 your next move. The full registry — every code, its class, and the
 version it appeared in — is

package/skill/examples.md

@@ -1,4 +1,4 @@
-# Aontu by example
+# aontu by example
 
 The ladder: start with the JSON you already know, add one thing at a
 time. Every rung is a valid document.

package/skill/grammar-card.md

@@ -1,4 +1,4 @@
-# Aontu grammar card
+# aontu grammar card
 
 Everything the language spells, on one page. The published machine
 grammars are [`grammar/aontu.abnf`](../grammar/aontu.abnf) — the

package/src/agentsmd.ts

@@ -81,7 +81,7 @@ export function agentsMd(
     AGENTSMD_BEGIN,
     '## Ground truth: `' + name + '`',
     '',
-    'The values below are DERIVED from `' + name + '`, an Aontu',
+    'The values below are DERIVED from `' + name + '`, an aontu',
     'definition. Do not restate them here — read them from the source,',
     'which is the only copy that cannot go stale.',
     '',

package/src/alias.ts

@@ -0,0 +1,112 @@
+/* Copyright (c) 2021-2026 Richard Rodger, MIT License */
+
+// ALIAS EXPANSION FOR CANON. An alias is a name for a value, and
+// nothing more (docs/design/ALIASES.0.md §4): the declaration is
+// erased from generation, canon and the hash, and a reference resolves
+// to the value in place. One place a reference is NOT resolved in
+// place is a spread template -- `[&: %unit]`, `{&: {a: %u}}` -- because
+// a template applies to children that have not arrived, so it stands
+// in the settled tree as the reference it was written as. Canon has
+// erased the declaration, so the name alone would not reparse, and the
+// hash of `t: {&: %u}` would differ from the hash of `t: {&: integer}`,
+// which is the same document.
+//
+// This walk runs ONCE, after the last unification pass, and attaches
+// to every standing alias reference the value it names, which its
+// canon then renders instead of the name. The tree is not changed:
+// the reference still stands, still resolves at each destination, and
+// unification never reads the expansion.
+//
+// What a reference expands to. The ref-spread SNAPSHOT where one was
+// taken (MapVal.snapshotRefSpread: a path-dependent template captured
+// before its key()/path() resolved at the declaration), else the
+// declaration's settled value at the root. The snapshot is the
+// template the destinations actually saw; the settled value of
+// `%row = {name: key()}` is `{name: "%row"}`, the leak the snapshot
+// exists to prevent, and canon must not print it either.
+//
+// The knot. A recursive alias names itself inside its own template
+// (`%json = null | ... | [&: %json] | {&: %json}`). Its expansion
+// contains a reference to the name being expanded, and that reference
+// keeps its name: canon cannot spell the declaration it erased, and
+// an infinite unrolling is not a canon. Such a canon does not reparse
+// on its own -- the one place alias erasure and canon convergence
+// pull apart (use-cases/BUGS.md §82). Only the reference that closes
+// the cycle is left as a name; everything up to it expands.
+//
+// Every value is visited once (templates are shared across
+// destinations, and one declaration is reached through many
+// references), children in code-point key order, so the two ports
+// attach the same expansions in the same order and print one canon.
+// Twin of expandAliases in go/alias.go.
+
+import type { Val } from './type'
+
+import { cmpCodePoint } from './keyorder'
+import { spreadSnapKey } from './val/MapVal'
+
+
+function expandAliases(root: Val, snapmap: Map<string, Val>): void {
+  if (true !== (root as any).isMap) {
+    return
+  }
+
+  const seen = new Set<Val>()
+
+  const visit = (v: any, stack: string[]): void => {
+    if (null == v || true !== v.isVal || seen.has(v)) {
+      return
+    }
+    seen.add(v)
+
+    if (true === v.isRef) {
+      const name: string | undefined = v.aliasName
+      if (undefined === name) {
+        return
+      }
+      v.expansion = undefined
+      if (stack.includes(name)) {
+        return
+      }
+      const target: Val | undefined =
+        snapmap.get(spreadSnapKey(v)) ?? (root as any).peg[name]
+      if (null == target) {
+        return
+      }
+      v.expansion = target
+      visit(target, [...stack, name])
+      return
+    }
+
+    if (true === v.isMap) {
+      // A declaration is reached through its references, each under
+      // its own name, never as a child: a self-reference inside it
+      // is a knot only from inside.
+      const keys = Object.keys(v.peg)
+        .filter((k: string) => !v.aliasKeys.includes(k))
+        .sort(cmpCodePoint)
+      for (const k of keys) {
+        visit(v.peg[k], stack)
+      }
+    }
+    else if (Array.isArray(v.peg)) {
+      for (const e of v.peg) {
+        visit(e, stack)
+      }
+    }
+    else if (null != v.peg && true === v.peg.isVal) {
+      visit(v.peg, stack)
+    }
+
+    if ((true === v.isMap || true === v.isList) && null != v.spread.cj) {
+      visit(v.spread.cj, stack)
+    }
+  }
+
+  visit(root, [])
+} /* node:coverage ignore next 5 */
+
+
+export {
+  expandAliases,
+}

package/src/aontu.ts

@@ -25,6 +25,8 @@ import { agentsMd } from './agentsmd'
 import { graphOf } from './graph'
 import { relationCheck, relationErrors } from './relation'
 import { view, viewSet, viewTree } from './view'
+import { render, renderValue, renderProfile } from './render'
+import { desugarTemplate, resugarTemplate, markerFor } from './template'
 import { format, unifiedDiff } from './format'
 export type { LintFinding, FormatReport, FormatOptions } from './format'
 
@@ -36,7 +38,7 @@ export type { LintFinding, FormatReport, FormatOptions } from './format'
 // Kept in step with package.json by the `version` npm lifecycle script,
 // which runs on `npm version` / `npm run repo-bump`. version.test.ts
 // fails if the two ever drift.
-const VERSION = '0.57.0'
+const VERSION = '0.59.0'
 
 
 // A module file's VALUE, as far as it goes. COLLECTED, not raised: a
@@ -101,6 +103,7 @@ class Aontu {
   ctx(cfg?: AontuContextConfig): AontuContext {
     cfg = cfg ?? {}
     cfg.fs = cfg.fs ?? this.opts.fs
+    ;(cfg as any).errfs = (cfg as any).errfs ?? (this.opts as any).errfs
     // The trust profile rides the instance (its resolver is built once,
     // in the Lang constructor); the context needs it too, for the
     // budgets (G5, docs/trust.md).
@@ -287,7 +290,7 @@ class Aontu {
       if (err instanceof AontuError || true === err.aontu) {
         throw err
       }
-      const unex = new AontuError('Aontu: unexpected error: ' + err.message)
+      const unex = new AontuError('aontu: unexpected error: ' + err.message)
       Object.assign(unex, err)
       unex.stack = err.stack
       throw unex
@@ -478,6 +481,21 @@ export {
   viewSet,
   viewTree,
 
+  // G9 -- the renderer (docs/design/RENDER.0.md): evaluate, vet and
+  // fold an aontu:code instance into bytes, or the fold alone over
+  // generate() output.
+  render,
+  renderValue,
+  renderProfile,
+
+  // The template surface (docs/design/TEMPLATE.0.md): the two text
+  // transforms behind `aontu template`, and the marker an extension
+  // names. Neither evaluates anything -- a template is a spelling of
+  // a generator, so the transforms are text in and text out.
+  desugarTemplate,
+  resugarTemplate,
+  markerFor,
+
   // The source formatter (docs/design/FMT.0.md): the agreed form of a
   // document, and the unified diff `aontu fmt --diff` prints.
   format,