aontu 0.62.0 → 0.63.0

package/src/render.ts

@@ -1,25 +1,6 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
 
-// THE RENDERER (docs/design/RENDER.0.md; docs/capability-review/
-// g9-transformation.md §3). `render` evaluates a document, takes the
-// value at `--at` (the root by default), vets it against the bundled
-// `aontu:code` vocabulary, and folds `code.units` into bytes;
-// `renderValue` is the fold alone, over `generate()` output. The fold
-// is pure and total: it never touches the Val tree, never reads or
-// writes a file, never sorts and never iterates a map, and every piece
-// of a fragment carries its own depth (`at`), so the renderer owns
-// every prefix and no piece nests another (the second amendment's
-// fragment algebra, RENDER.0.md D2 and D6).
-//
-// WHAT THIS PHASE RENDERS (RENDER.0.md P3): fragments -- a line, a
-// blank run, a raw block, a bare string piece, a reference inline --
-// and the `text` escape, under a profile that knows its language. The
-// one bundled profile is `aontu:lang/text`, which every fragment-only
-// unit falls back to; a declaration (`record`, `enum`, ...) needs a
-// LOWERING, which P5 brings with the TypeScript and Go profiles, and
-// until then is `render_profile`.
-
 import { Aontu } from './aontu'
 import { vet, failureFinding, anchorAt } from './vet'
 import type { VetFinding } from './vet'
@@ -42,12 +23,6 @@ export type RenderUnit = {
   text: string
 }
 
-// THE THREE LOSS TIERS (RENDER.0.md D7). Tier 1 is a check the target's
-// type system cannot enforce (the declaration lowering's, P5); tier 2
-// a fragment -- structured, re-indentable, terminator-checked, saying
-// nothing about target syntax; tier 3 an opaque escape, a `text`
-// declaration or a `raw` piece. `strict` refuses tier 3 and only
-// tier 3.
 export type RenderLoss = {
   unit: string
   path: string
@@ -56,12 +31,6 @@ export type RenderLoss = {
   reason: string
 }
 
-// ONE PIECE'S PROVENANCE (RENDER.0.md D9, D11; P7). A dispatch stamps
-// every piece it emits with the node it matched and the rule it took,
-// and the fold reads the stamps back off the instance: `piece` is the
-// piece's own path there, `unit` the unit it landed in, `node` the
-// model address the rule matched, and `rule` the rule's address --
-// its table's, then `#`, then its index in that table.
 export type RenderTrace = {
   unit: string
   piece: string
@@ -69,8 +38,6 @@ export type RenderTrace = {
   rule: string
 }
 
-// THE COVERAGE REPORT (P7; G9 §6, "coverage cuts both ways"). Two
-// lists, and both are set computations over what the run recorded.
 export type RenderCoverage = {
   // Every model path a reference resolved to, in walk order: what the
   // render READ.
@@ -78,27 +45,15 @@ export type RenderCoverage = {
   // Dead model: the SHALLOWEST model paths no read reached. A path
   // whose subtree holds a read is not named; its unread children are.
   dead: string[]
-  // A silent hole: a rendered declaration no rule produced. In a
-  // document with no rule table that is every declaration, which is
-  // the true statement about it -- the rule layer governs none of this
-  // output.
   unruled: { unit: string, path: string }[]
 }
 
 export type RenderReport = {
   verdict: RenderVerdict
-  // In `units[]` order. Empty on `error`.
   units: RenderUnit[]
   // Per unit and path. Empty on `error`.
   lossy: RenderLoss[]
-  // On `error` only, in vet's finding shape: the document did not
-  // stand up, the instance is not `aontu:code`, or a unit could not be
-  // rendered (`render_*`).
   errors?: VetFinding[]
-  // The dispatch trace, under `trace` or `coverage` (P7), in document
-  // order. Absent when it is empty, on `error`, and from
-  // `renderValue`, which folds an instance the recorder never watched
-  // being built.
   trace?: RenderTrace[]
   // The coverage report, under `coverage` (P7).
   coverage?: RenderCoverage
@@ -111,31 +66,21 @@ export type RenderOptions = IncludeOptions & {
   // Where the document CAME FROM, so a relative `@"file"` load inside
   // it resolves from its own directory.
   path?: string
-  // Profiles supplied by the caller, each an evaluated profile map
-  // (`{lang, indent, ...}`), matched to a unit by `lang` before the
-  // bundled set is asked (RENDER.0.md D5, step 1).
   profiles?: any[]
   // Render only the unit at this path.
   unit?: string
-  // Refuse tier-3 loss: the opaque escapes.
   strict?: boolean
-  // RECORD THE DISPATCH TRACE (P7). Off by default: an instrumented
-  // run stamps every value a reference resolves and every piece a rule
-  // emits, and an ordinary one pays one property load per meet.
   trace?: boolean
   // Compute the coverage report, which needs the trace and turns it on.
   coverage?: boolean
-  // Measure coverage under this path only, instead of the document
-  // root (RENDER.0.md X-3). The narrower measure a document with its
-  // model under one key wants.
   coverageAt?: string
 }
 
 
 const VOCABULARY = '@"aontu:code"'
-// The bundled profiles, by lang: aontu:lang/<lang>.
-const BUNDLED_LANGS = ['go', 'text', 'typescript']
-const PROFILE_VOCABULARY = '@"aontu:profile"'
+// The bundled profiles, by lang: aontu:render/lang/<lang>.
+const BUNDLED_LANGS = ['go', 'markdown', 'text', 'typescript']
+const PROFILE_VOCABULARY = '@"aontu:render"'
 
 
 function finding(
@@ -150,29 +95,10 @@ function errorReport(errors: VetFinding[]): RenderReport {
 }
 
 
-// The verb's evaluation, before the fold (RENDER.0.md D1): evaluate,
-// anchor, vet the anchored value against the vocabulary as `aontu vet`
-// would, and generate the MEET of the two -- so the vocabulary's
-// defaults (`at: 0`, `n: 1`, `reindent: true`) are in the instance the
-// fold reads, whether or not the document included the vocabulary
-// itself. THE VET AND THE MEET READ THE SETTLED VALUE, re-sourced
-// through its hash form (valid source that evaluates to the same
-// value), not the document's text: a fragment's lines are what a
-// transform COMPUTED -- an `emit`, a `join` -- and the vocabulary's
-// alternatives are tried against values, not against calls that are
-// still waiting to fire. A finding from that vet therefore addresses
-// the instance by path, which is the addressing every render finding
-// uses (G9 §3); a document that does not stand up at all is reported
-// with its own sites, before any of this.
 export function render(src: string, options?: RenderOptions): RenderReport {
   const opts = options ?? {}
   const aontu = new Aontu(includeOpts(opts))
 
-  // THE RECORDER (P7), on for a run that was asked for a trace or a
-  // coverage report and off for every other. Its presence is the one
-  // switch: the read set fills as references resolve, and the two
-  // riders that carry a read address and a dispatch stamp are written
-  // only while it is there.
   const rec = true === opts.trace || true === opts.coverage
   const reads = rec ? new Set<string>() : undefined
 
@@ -198,40 +124,20 @@ export function render(src: string, options?: RenderOptions): RenderReport {
     node = found
   }
 
-  // UNDER NO CALLER CAPABILITY, here and in the meet below: the
-  // vocabulary is the engine's own and the instance is a canon, which
-  // includes nothing, so the caller's include capability -- which
-  // governs the DOCUMENT -- has nothing to govern here, and `none`
-  // must not deny the renderer its own schema.
   const value = hcanon(node)
   const report = vet(VOCABULARY, value)
   if ('valid' !== report.verdict) {
     return errorReport(report.findings)
   }
 
-  // The meet, keyed: the vocabulary's root holds `aontu.Code`, and so
-  // does the instance's (a value the vet admitted is a map), and a
-  // document with no `code` at all is the vocabulary's own empty
-  // instance. The key is namespaced (ADR-029), so the reach is two deep.
   const codeVal: any = node.peg.aontu?.peg?.Code
   const instance = new Aontu().generate(
     VOCABULARY + (undefined === codeVal ? '' : '\naontu: Code: ' + hcanon(codeVal)))
   const folded = renderValue(instance, opts)
 
-  // THE TWO REPORTS ARE JOINED TO THE FOLD BY PATH (P7), which is what
-  // lets the fold stay the pure total function D6 asks for: the
-  // dispatch stamps ride the VALUE, the instance the fold reads is
-  // that value re-sourced through its hash form, and a piece is at the
-  // same path in both. Nothing to report on `error`: there are no
-  // units to attribute pieces to.
   if (rec && 'error' !== folded.verdict) {
     const marks = emitted(node)
     const trace = traceOf(marks, instance, folded.units)
-    // AN EMPTY TRACE IS NO TRACE, in both ports: Go omits an empty
-    // slice, and a report shape that differed by port would be the one
-    // thing the shared rows exist to refuse. A run that emitted no
-    // piece has nothing to attribute, and the coverage report says so
-    // in its own words.
     if (0 < trace.length) {
       folded.trace = trace
     }
@@ -268,10 +174,6 @@ function walkVals(root: any, fn: (v: any, path: string[]) => boolean): void {
     }
     else if (true === v.isMap && null != v.peg) {
       for (const k of Object.keys(v.peg).sort(cmpCodePoint)) {
-        // AN ALIAS DECLARATION IS NOT A MEMBER, here for the reason
-        // every fold has it (./val/members.ts): `%wire = …` holds a
-        // value the document never generates, so it is neither a piece
-        // to trace nor model that could be called dead.
         if (!v.aliasKeys.includes(k)) {
           walk(v.peg[k], [...path, k])
         }
@@ -303,13 +205,6 @@ function emitted(node: any): { path: string, mark: any }[] {
 }
 
 
-// The trace: one entry per stamped piece that a RENDERED unit holds. A
-// piece is IN the unit whose path prefixes its own, which is the whole
-// of the question -- no path is parsed, and a stamp that lies under no
-// unit at all (a rule set held under a key of its own, and referred to
-// from a unit) simply matches nothing. A unit the run did not render
-// (`--unit` names one) has no bytes for a piece of it to be in, so it
-// is not among the prefixes either.
 function traceOf(marks: { path: string, mark: any }[], instance: any,
   units: RenderUnit[]): RenderTrace[] {
   const pre: { at: string, path: string }[] = []
@@ -341,10 +236,6 @@ function ancestors(a: string): string[] {
 }
 
 
-// Is the value at `a` covered by the set -- the address itself in it,
-// or an address above it? An address ABOVE it covers the whole subtree:
-// a reference that read `$.schema` read everything under it, and a rule
-// that emitted a unit emitted every declaration in it.
 function covered(set: Set<string>, a: string): boolean {
   if (set.has(a)) {
     return true
@@ -358,15 +249,6 @@ function covered(set: Set<string>, a: string): boolean {
 }
 
 
-// THE COVERAGE REPORT (P7). Dead model is measured over the DOCUMENT
-// ROOT, or under `coverageAt` when a document keeps its model under one
-// key (X-3, decided here): the read set is absolute, so a narrower
-// measure is a narrower walk, not a different origin. The render's own
-// output -- the `aontu` namespace under the anchor -- is not model and
-// is never walked into: nothing reads it, so every document would
-// otherwise report it dead. The whole NAMESPACE is excluded, not just
-// `aontu.Code` (ADR-029): everything under it is language-supplied, so
-// an included vocabulary is not dead model either.
 function coverOf(root: any, node: any, reads: Set<string>,
   opts: RenderOptions, marks: { path: string, mark: any }[], instance: any,
   units: RenderUnit[]): RenderCoverage | undefined {
@@ -386,8 +268,6 @@ function coverOf(root: any, node: any, reads: Set<string>,
     base = found.path
   }
 
-  // The two questions asked of the read set, as sets: is this address
-  // read (or under one that is), and does a read lie BELOW it?
   const above = new Set<string>(reads)
   const below = new Set<string>()
   for (const r of reads) {
@@ -402,11 +282,6 @@ function coverOf(root: any, node: any, reads: Set<string>,
     if (a === codeAddr || covered(above, a)) {
       return false
     }
-    // THE ROOT OF THE MEASURE IS NEVER ITSELF DEAD MODEL, and is
-    // descended into whatever the read set holds. A document that is
-    // only a transform reads nothing above its own model, and naming
-    // the root there would report the whole document dead while its
-    // one live subtree sat inside it.
     if (below.has(a) || 0 === path.length) {
       return true
     }
@@ -446,25 +321,19 @@ function coverOf(root: any, node: any, reads: Set<string>,
 // whose declarations are fragments and text escapes only.
 const bundled: Record<string, any> = {}
 
-// A bundled profile, evaluated once: the meet of aontu:lang/<lang>
+// A bundled profile, evaluated once: the meet of aontu:render/lang/<lang>
 // with the vocabulary, so its defaults are in it.
 function bundledProfile(lang: string): any {
   if (!BUNDLED_LANGS.includes(lang)) {
     return undefined
   }
   if (undefined === bundled[lang]) {
-    bundled[lang] = new Aontu().generate('@"aontu:lang/' + lang + '"').aontu.Profile
+    bundled[lang] = new Aontu().generate('@"aontu:render/lang/' + lang + '"').aontu.render.Lang
   }
   return bundled[lang]
 }
 
 
-// PROFILE SELECTION, per unit (RENDER.0.md D5): a caller-supplied
-// profile whose `lang` is the unit's; else the bundled profile of that
-// `lang`; else `aontu:lang/text`, if and only if every declaration in
-// the unit is a fragment or a text escape; else nothing, which the
-// caller reports as `render_profile`. The unit's inline `profile` is
-// merged over whichever base was found.
 function profileFor(lang: string, given: any[] | undefined, fragOnly: boolean): any {
   const supplied = (given ?? []).find((p: any) => p?.lang === lang)
   if (undefined !== supplied) {
@@ -496,16 +365,6 @@ function mergeProfile(base: any, over: any): any {
 }
 
 
-// THE FOLD (RENDER.0.md D6). `pad(at)` is `indent.unit` repeated
-// `indent.width × at` times; a line is `pad + text + LF`, and an empty
-// text emits no pad; a blank is its terminators alone; a raw block's
-// lines each get the pad unless `reindent: false`, which emits them
-// at column 0 verbatim -- and common leading indentation is never
-// stripped. A reference inline is its name, verbatim (a
-// declaration-capable profile puts it through its identifier rules,
-// P5). Nothing is trimmed (D3): the text is the transform's.
-// A profile with no indent -- a caller-supplied map the vocabulary
-// never filled -- takes the vocabulary's own default, two spaces.
 function pad(profile: any, at: number): string {
   const indent = profile.indent ?? { unit: ' ', width: 2 }
   return (indent.unit ?? ' ').repeat((indent.width ?? 2) * at)
@@ -532,7 +391,7 @@ function foldPiece(
     return line(profile, 0, piece)
   }
   if ('line' === piece.k) {
-    return line(profile, piece.at ?? 0, piece.of.map((p: any) => inline(p, ctx)).join(''))
+    return line(profile, piece.at ?? 0, piece.n.map((p: any) => inline(p, ctx)).join(''))
   }
   if ('blank' === piece.k) {
     return '\n'.repeat(piece.n ?? 1)
@@ -551,13 +410,6 @@ function foldPiece(
 }
 
 
-// A PROFILE DOCUMENT (RENDER.0.md D5), evaluated the way `render`
-// evaluates its own: under the caller's include options, then vetted
-// against aontu:profile as a settled value and met with that vocabulary
-// so its defaults (`indent.width: 2`, ...) are in it. The answer is the
-// `profile` map the fold reads -- what `--profile <file>` hands to
-// RenderOptions.profiles -- or the findings that refused the document:
-// one that does not stand up, or one the vocabulary rejects.
 export function renderProfile(src: string, options?: RenderOptions):
   { profile?: any, errors?: VetFinding[] } {
   const opts = options ?? {}
@@ -574,9 +426,9 @@ export function renderProfile(src: string, options?: RenderOptions):
   // The meet, keyed as render's is: the vocabulary requires `profile`,
   // so a value the vet admitted has one.
   const instance = new Aontu().generate(
-    PROFILE_VOCABULARY + '\naontu: Profile: ' +
-    hcanon(root.peg.aontu.peg.Profile))
-  return { profile: instance.aontu.Profile }
+    PROFILE_VOCABULARY + '\naontu: render: Lang: ' +
+    hcanon(root.peg.aontu.peg.render.peg.Lang))
+  return { profile: instance.aontu.render.Lang }
 }
 
 
@@ -589,10 +441,6 @@ function unitList(instance: any): any[] {
 }
 
 
-// The fold alone, over `generate()` output: the instance is
-// `{code: {units: [...]}}` as the vocabulary shapes it, with its
-// defaults filled -- which is what `render` hands over, and what a
-// caller of this function is responsible for.
 export function renderValue(instance: any, options?: RenderOptions): RenderReport {
   const opts = options ?? {}
   const errors: VetFinding[] = []
@@ -638,15 +486,11 @@ export function renderValue(instance: any, options?: RenderOptions): RenderRepor
     if (undefined === base) {
       errors.push(finding('render_profile', 'parse', upath + '.lang',
         'no profile renders ' + lang + ': a declaration needs a lowering, and ' +
-        'only fragments and text escapes render under aontu:lang/text.'))
+        'only fragments and text escapes render under aontu:render/lang/text.'))
       return
     }
     const profile = null == unit.profile ? base : mergeProfile(base, unit.profile)
 
-    // THE LOWERING (D5, P5), when the profile names one: the unit's
-    // header -- banner, package clause, imports -- and each declaration
-    // as pieces the fold takes, a blank line between two lowered
-    // declarations. A fragment or a text escape owns its own blanks.
     const family: string | undefined = profile.lowering
     const ctx: LowerCtx | undefined = undefined === family ? undefined
       : { profile, family, unit: path, lossy }
@@ -666,12 +510,16 @@ export function renderValue(instance: any, options?: RenderOptions): RenderRepor
       const dpath = upath + '.decls.' + j
       if ('frag' === decl.k) {
         lowered = false
-        lossy.push({
-          unit: path, path: dpath, tier: 2, construct: 'frag',
-          reason: 'a fragment says nothing about ' + lang + ' syntax',
-        })
-        decl.of.forEach((piece: any, n: number) => {
-          text += foldPiece(piece, profile, path, dpath + '.of.' + n, lossy, ctx)
+        // Lossy only against a language whose DECLARATIONS could have
+        // been lowered instead: a fragment is all the others have.
+        if (null != profile.lowering) {
+          lossy.push({
+            unit: path, path: dpath, tier: 2, construct: 'frag',
+            reason: 'a fragment says nothing about ' + lang + ' syntax',
+          })
+        }
+        decl.n.forEach((piece: any, n: number) => {
+          text += foldPiece(piece, profile, path, dpath + '.n.' + n, lossy, ctx)
         })
       }
       else if ('text' === decl.k) {

package/src/report-sarif.ts

@@ -1,25 +1,5 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 
-// SARIF rendering for a vet report (G2 phase 5,
-// docs/capability-review/g2-validation-verb.md).
-//
-// A MINIMAL SARIF 2.1.0 profile, and deliberately nothing more: one
-// run, one `result` per finding, the finding's first site as the
-// primary location, its remaining sites under `relatedLocations`, and
-// the whole finding object embedded in `properties` so a SARIF consumer
-// still holds the native contract. No fixes, no code flows, no
-// baselines — the JSON report is the native contract, SARIF is the
-// interchange skin CI systems already ingest (GitHub code scanning
-// uploads, PR annotation).
-//
-// This is library API, not CLI plumbing, for the same reason the vet
-// engine is: an embedder (and G7's MCP server later) must be able to
-// emit the interchange form without shelling out. The Go twin is
-// go/report_sarif.go, and the two are held to byte parity over the
-// shared fixture pair in test/spec/files/vet-sarif/ — with the message
-// text and producer version redacted, exactly as test/spec/vet.tsv
-// carves the message out of its goldens, because prose and the two
-// independent version series are deliberately not in cross-port parity.
 
 import type { VetReport, VetFinding, VetSite } from './vet'
 
@@ -37,13 +17,6 @@ const SARIF_LEVEL: Record<string, string> = {
 }
 
 
-// A site's file is a filesystem path, and a SARIF artifactLocation.uri
-// is a URI reference: `#`, `%`, spaces and every other URI-significant
-// character must be percent-encoded or a consumer parses the path as
-// something else (text after `#` becomes a fragment). Encoded BY BYTE
-// over UTF-8, with RFC 3986's unreserved and path characters kept
-// literal, so the Go twin produces identical bytes from an identical
-// loop (go/report_sarif.go sarifURI).
 function sarifUri(path: string): string {
   const bytes = Buffer.from(path, 'utf8')
   let out = ''
@@ -75,11 +48,6 @@ function sarifLocation(site: VetSite): any {
 
 
 function sarifResult(finding: VetFinding): any {
-  // The engine orders sites data-first (the thing to fix), so the first
-  // site is the primary location and the rest are related — which for a
-  // two-site conflict puts the schema's declaration under
-  // `relatedLocations`, exactly where a code-scanning UI shows "the
-  // other side".
   const result: any = {
     level: SARIF_LEVEL[finding.severity],
     locations: [sarifLocation(finding.sites[0])],
@@ -95,26 +63,10 @@ function sarifResult(finding: VetFinding): any {
 }
 
 
-/**
- * Render a vet report as SARIF 2.1.0 text (a minimal profile: one run,
- * one result per finding, the finding embedded in `properties`).
- *
- * @param report   A report from `vet()`.
- * @param version  The producer version for `tool.driver.version` —
- *                 the CLI passes its package version; the two ports'
- *                 version series are independent by design.
- * @returns        The SARIF JSON text, indented two spaces, keys in
- *                 the canonical emitter's sorted order.
- */
 function sarifReport(report: VetReport, version: string): string {
   return exactJSON({
     $schema: 'https://json.schemastore.org/sarif-2.1.0.json',
     runs: [{
-      // An `error` verdict means the run could not be set up (an
-      // unusable schema): zero findings from a FAILED run must not
-      // read like zero findings from a clean one, so the failure is
-      // carried in SARIF's own invocation metadata rather than by an
-      // indistinguishable empty result list.
       invocations: [{
         executionSuccessful: 'error' !== report.verdict,
       }],

package/src/sig.ts

@@ -1,29 +1,5 @@
 /* Copyright (c) 2021-2026 Richard Rodger, MIT License */
 
-// THE SIGNATURE REGISTRY (docs/design/SIGNATURES.0.md). The call
-// surface of the built-in functions is DECLARED, in the signature
-// syntax itself, in test/spec/signature.tsv; this module is the
-// TypeScript half of the pair that reads it. The declaration text is
-// inlined at build time (ts/src/sigdecl.ts, `make sig`) and parsed at
-// initialisation by the signature grammar -- a custom tabnas grammar,
-// the same engine the aontu grammar itself is built on -- into the
-// registry the runtime signature checker, the error-message builder,
-// the docs table and the LSP all consume. Neither port authors a
-// table: go/sig.go parses the same text with the same grammar, and
-// the shared suite round-trips every line (render(parse(line)) is the
-// line) so the two parsers cannot drift.
-//
-//   line = name '(' [ arg {',' arg} ] ')' ':' type
-//   arg  = [mode] name ['?'] ':' type
-//        | '...' name ':' ( type | '(' [mode] type {',' [mode] type} ')' )
-//   type = word {'|' word}
-//   mode = 'capture' | 'template' | 'trial' | 'projector' | 'text'
-//
-// `value` mode is unmarked; the five marked modes are the vocabulary
-// plain pseudo-TypeScript cannot say (a captured spelling is not a
-// string value). The grammar is line-oriented: the loader strips
-// comment and blank lines and parses each declaration line alone, so
-// the grammar never sees line structure.
 
 import { Tabnas } from '@tabnas/parser'
 
@@ -59,11 +35,6 @@ const ARG_MODES: Record<string, boolean> = {
 }
 
 
-// The signature grammar, as a tabnas grammar plugin. Rules: sig (the
-// line) -> args -> arg -> argtype -> type | group -> gmember. Alts
-// match at most two tokens, the engine's shape; lists loop the
-// json-grammar way (the element rule replaces itself on ',' and
-// backtracks the closer for its parent to consume).
 function sigGrammar(tn: any) {
   tn.options({
     fixed: {
@@ -326,12 +297,6 @@ export type {
   FuncSig,
 }
 
-// The parsed registry, built once from the inlined declaration -- the
-// one source every consumer (the arity tables, the runtime gate, the
-// hints, the docs table, the LSP) reads. A parse failure here throws
-// at module load: the inlined text is repository content whose parse
-// the round-trip suite gates, so a failure is a build defect, not a
-// runtime condition. Twin: funcSig in go/sig.go.
 const funcSig: Record<string, FuncSig> =
   parseSigText(SIGDECL) /* node:coverage ignore next 9 */
 

package/src/sigdecl.ts

@@ -6,6 +6,6 @@
 // this copy is identical with the shared file.
 
 const SIGDECL: string =
-"# The call surface: one declaration line per built-in function\n# (docs/design/SIGNATURES.0.md). THIS FILE IS THE SOURCE — both ports\n# carry a build-time-inlined copy (ts/src/sigdecl.ts, go/sigdecl.txt;\n# `make sig` regenerates both, and each port's suite asserts its copy\n# is byte-identical with this file) and parse it at initialisation\n# with the signature grammar, a tabnas grammar (ts/src/sig.ts,\n# go/sig.go). The suites also round-trip every line:\n# render(parse(line)) must be the line exactly, in both ports.\n#\n# The syntax (rendered TypeScript-ish, honest about argument MODES):\n#   line = name '(' [ arg {',' arg} ] ')' ':' type\n#   arg  = [mode] name ['?'] ':' type\n#        | '...' name ':' '(' [mode] type {',' [mode] type} ')'\n#   type = word {'|' word}\n#   mode = 'capture' | 'template' | 'trial' | 'projector' | 'text'\n# `value` mode is unmarked. `constraint` is the result word for\n# residuals whose meet depends on the peer; `any` is the honest type\n# where a function is a wrapper.\nupper(s: string|number, start?: integer|biginteger, len?: integer|biginteger) : string\nlower(s: string|number, start?: integer|biginteger, len?: integer|biginteger) : string\ncopy(v: any) : any\npref(v: any) : any\nsuper(t: any) : any\ntype(t: any) : any\nhide(v: any) : any\nclose(m: any) : any\nopen(m: any) : any\nmove(v: any) : any\npath(capture p?: path) : path\nmap() : map\nlist() : list\nmin(n: number|string) : constraint\nmax(n: number|string) : constraint\nabove(n: number|string) : constraint\nbelow(n: number|string) : constraint\nre(text p: string) : constraint\nlength(n: number|constraint) : constraint\nkey(up?: integer|biginteger) : string\nunique(projector k?: string) : constraint\nneq(...vals: number|string) : constraint\nmust(trial c: any, text msg: string) : constraint\ndeprecate(v: any, r?: map) : any\nacyclic() : constraint\ninverse(projector k: string) : constraint\nrefer(template t?: any) : constraint\nrel(template t?: any) : constraint\npack(d: map|list, template t: any) : map\neach(d: map|list, template t: any) : list\nfilter(d: map|list, trial c: any) : map|list\nmatch(s: any, ...pr: (trial any, any), dflt?: any) : any\nadd(a: number, b: number) : number\nsub(a: number, b: number) : number\nmul(a: number, b: number) : number\ndiv(a: number, b: number) : number\nmod(a: number, b: number) : number\nrem(a: number, b: number) : number\nsum(d: map|list) : number\nleast(d: map|list) : number\ngreatest(d: map|list) : number\npick(d: map|list, projector k: string|integer) : any\njoin(d: map|list, sep?: string) : string\nesc(s: string, variant?: string) : string\nusc(s: string, variant?: string) : string\nrep(s: string, text p: string, text sub: string) : string\nsplit(s: string, sep: string|constraint) : list\nemit(s: map|list, template t: map|list) : list\n"
+"# The call surface: one declaration line per built-in function\n# (docs/design/SIGNATURES.0.md). THIS FILE IS THE SOURCE — both ports\n# carry a build-time-inlined copy (ts/src/sigdecl.ts, go/sigdecl.txt;\n# `make sig` regenerates both, and each port's suite asserts its copy\n# is byte-identical with this file) and parse it at initialisation\n# with the signature grammar, a tabnas grammar (ts/src/sig.ts,\n# go/sig.go). The suites also round-trip every line:\n# render(parse(line)) must be the line exactly, in both ports.\n#\n# The syntax (rendered TypeScript-ish, honest about argument MODES):\n#   line = name '(' [ arg {',' arg} ] ')' ':' type\n#   arg  = [mode] name ['?'] ':' type\n#        | '...' name ':' '(' [mode] type {',' [mode] type} ')'\n#   type = word {'|' word}\n#   mode = 'capture' | 'template' | 'trial' | 'projector' | 'text'\n# `value` mode is unmarked. `constraint` is the result word for\n# residuals whose meet depends on the peer; `any` is the honest type\n# where a function is a wrapper.\nupper(s: string|number, start?: integer|biginteger, len?: integer|biginteger) : string\nlower(s: string|number, start?: integer|biginteger, len?: integer|biginteger) : string\ncopy(v: any) : any\npref(v: any) : any\nsuper(t: any) : any\ntype(t: any) : any\nhide(v: any) : any\nmaybe(v: any) : any\nclose(m: any) : any\nopen(m: any) : any\nmove(v: any) : any\npath(capture p?: path) : path\nmap() : map\nlist() : list\nmin(n: number|string) : constraint\nmax(n: number|string) : constraint\nabove(n: number|string) : constraint\nbelow(n: number|string) : constraint\nre(text p: string) : constraint\nlength(n: number|constraint) : constraint\nkey(up?: integer|biginteger) : string\nunique(projector k?: string) : constraint\nneq(...vals: number|string) : constraint\nmust(trial c: any, text msg: string) : constraint\ndeprecate(v: any, r?: map) : any\nacyclic() : constraint\ninverse(projector k: string) : constraint\nrefer(template t?: any) : constraint\nrel(template t?: any) : constraint\npack(d: map|list, template t: any) : map\neach(d: map|list, template t: any) : list\nfilter(d: map|list, trial c: any) : map|list\nmatch(s: any, ...pr: (trial any, any), dflt?: any) : any\nadd(a: number, b: number) : number\nsub(a: number, b: number) : number\nmul(a: number, b: number) : number\ndiv(a: number, b: number) : number\nmod(a: number, b: number) : number\nrem(a: number, b: number) : number\nsum(d: map|list) : number\nleast(d: map|list) : number\ngreatest(d: map|list) : number\npick(d: map|list, projector k: string|integer) : any\nsort(d: map|list, projector k?: string|integer, dir?: string) : list\njoin(d: map|list, sep?: string) : string\nesc(s: string, variant?: string) : string\nusc(s: string, variant?: string) : string\nrep(s: string, text p: string, text sub: string) : string\nsplit(s: string, sep: string|constraint) : list\nemit(s: map|list, template t: map|list) : list\nabnf(g: string) : string\nparse(g: string, v?: string) : map|list|constraint\nnom(name: string, style?: string|list, acronyms?: list) : string|map\ntranslate(s: string, from: string, to?: string) : string\nproject(spec?: string|map, children?: list) : map\nfolder(spec: string|map, children?: list) : map\nfile(spec: string|map, children?: list) : map\ncontent(spec: string|map) : map\nline(spec: string|map) : map\nfragment(spec: string|map, children?: list) : map\nslot(spec: string|map, children?: list) : map\ninject(spec: string|map, children?: list) : map\ncopyfiles(spec: string|map) : map\nlistitems(spec: map, children?: list) : map\n"
 
 export { SIGDECL }

package/src/siggate.ts

@@ -1,31 +1,5 @@
 /* Copyright (c) 2021-2026 Richard Rodger, MIT License */
 
-// THE RUNTIME SIGNATURE CHECKER (docs/design/SIGNATURES.0.md). One
-// argument gate, run by the shared function machinery
-// (FuncBaseVal.unify) just before a call resolves, when its arguments
-// are driven: for each VALUE-mode argument whose declared type is
-// scalar-kind words, the driven Val must be a concrete scalar of an
-// admitted kind. A failure refuses as `func_arg`, whose hint renders
-// the signature line and names the offending argument -- the
-// error-message builder the registry exists for.
-//
-// The gate owns exactly the argument-shape refusals that were bare
-// `invalid-arg` at the call: the case family's operand, the
-// arithmetic operands, join's separator, pick's key. Everything with
-// more meaning than a shape mismatch keeps its own code: the bag
-// arguments (`pack_data`, `each_data`, `filter_data`,
-// `aggregate_data` -- container words are not gate words), the
-// constraint atoms (not on this path at all -- their refusals ride
-// the residual), `key()` (whose level meaning `key_level` names, and
-// which is skipped here for that reason), and the capture, template,
-// trial, projector and text modes, none of which are read as values.
-//
-// What the gate refuses it must POSITIVELY identify: a concrete
-// scalar of a wrong kind, a map, a list, or a scalar KIND marker
-// where a value belongs. Anything else -- a preference, a residual, a
-// disjunct -- passes through to the builtin's own logic, which is
-// what keeps arith's unpref reading and join's deferral working.
-// Twin: sigRefuse in go/siggate.go.
 
 import type { Val } from './type'
 import { AontuContext } from './ctx'
@@ -44,10 +18,6 @@ import {
 } from './val/ScalarKindVal'
 
 
-// The scalar-kind words the gate enforces, each to its lattice
-// marker. A declared type is gate-checkable only when EVERY union
-// word is here: `any`, `constraint`, and the container words leave
-// the argument to the builtin.
 const SIG_KIND = new Map<string, any>([
   ['string', String],
   ['number', Number],

package/src/site.ts

@@ -10,35 +10,9 @@ type SiteSpec = {
   row?: number, col?: number, url?: string, len?: number, src?: string,
 }
 
-// Site locates a value in the text that produced it: where it starts
-// (row, col), HOW FAR IT RUNS (len), and the source text itself (src).
-//
-// THE EXTENT IS NOT OPTIONAL DETAIL — it is what makes a site safe to
-// edit. Without it the only length available is the CANON, and canon is
-// not source text: `port: 0x1F` has canon `31`, so replacing
-// `(col, canon.length)` writes `port: 5x1F` and corrupts the document.
-// The parser knew the extent all along — the token carries `len` and
-// `src` beside the `rI`/`cI` this already read — and dropping it was
-// the whole defect (status report 2026-08-21, §5).
-//
-// WHAT THE EXTENT COVERS is the TOKEN THE SITE POINTS AT, which is the
-// same thing row and col have always pointed at:
-//
-//   0x1F         a scalar literal   len 4   the whole literal
-//   "hi there"   a string           len 10  quotes included
-//   {x:1}        a map              len 1   the opening brace
-//   min(3)       a constraint       len 3   the name, not the call
-//
-// So for a SCALAR — which is what a repair edits, and what `set` and
-// the manual fallback rewrite — `(col, len)` is exactly the span to
-// replace. For a container it under-reaches to the opening delimiter,
-// which is safe in the direction that matters: a highlight that is too
-// short is a cosmetic flaw, while canon.length on a map over-reaches
-// across lines into text the value never occupied.
-//
-// -1 and '' mean UNKNOWN, the same convention row and col already use:
-// a value minted by unification rather than written by a document has
-// no site, and must not be edited as though it had one.
+// row, col and len -1, url and src empty, mean UNKNOWN: a value the
+// engine minted rather than read has no site, and must not be edited
+// as though it had one.
 class Site {
   row: number
   col: number