aontu 0.62.0 → 0.64.0

package/src/trace.ts

@@ -0,0 +1,157 @@
+/* Copyright (c) 2026 Richard Rodger, MIT License */
+
+
+import type { Val } from './type'
+
+import { Aontu } from './aontu'
+import { cmpCodePoint } from './keyorder'
+import { includeOpts } from './utility'
+import { anchorAt, failureFinding } from './vet'
+import { makeNilErr } from './err'
+
+import type { IncludeOptions } from './utility'
+import type { VetFinding } from './vet'
+
+
+export type TraceOptions = IncludeOptions & {
+  path?: string
+  at?: string
+}
+
+
+export type TraceReport = {
+  verdict: 'ok' | 'error'
+  trace: TraceEntry[]
+  errors?: VetFinding[]
+}
+
+
+// WHAT A TRACE ENTRY CARRIES. The file it reached, the rule set that
+// wrote it, and the model node the dispatch matched.
+export type TraceEntry = {
+  at: string
+  file: string
+  node: string
+  rule: string
+}
+
+
+function walkVals(root: any, fn: (v: any, path: string[]) => void): void {
+  const walk = (v: any, path: string[]): void => {
+    fn(v, path)
+    if (true === v.isList && null != v.peg) {
+      for (let i = 0; i < v.peg.length; i++) {
+        walk(v.peg[i], [...path, String(i)])
+      }
+    }
+    else if (true === v.isMap && null != v.peg) {
+      for (const k of Object.keys(v.peg).sort(cmpCodePoint)) {
+        if (!v.aliasKeys?.includes(k)) {
+          walk(v.peg[k], [...path, k])
+        }
+      }
+    }
+  }
+  walk(root, [])
+}
+
+
+function addr(path: string[]): string {
+  return '$' + path.map((seg) => '.' + seg).join('')
+}
+
+
+function scalar(v: any): string | undefined {
+  return (true === v?.isScalar && 'string' === typeof v.peg) ? v.peg : undefined
+}
+
+
+function fileName(v: any): string | undefined {
+  if (true !== v?.isMap) {
+    return undefined
+  }
+  return 'File' === scalar(v.peg?.cmp) ? scalar(v.peg?.props?.peg?.name) :
+    undefined
+}
+
+
+// THE INNERMOST FILE WINS: the longest matching prefix, not the first.
+function enclosing(files: { at: string, name: string }[],
+  path: string): string | undefined {
+  let best: string | undefined
+  let long = -1
+  for (const f of files) {
+    if ((path === f.at || path.startsWith(f.at + '.')) && f.at.length > long) {
+      best = f.name
+      long = f.at.length
+    }
+  }
+  return best
+}
+
+
+// Every piece a dispatch stamped, attributed to the file it reached.
+// One pass: `walkVals` is depth-first in document order, so a file is
+// always seen before the marks beneath it.
+function traceTree(root: Val): TraceEntry[] {
+  const files: { at: string, name: string }[] = []
+  const marks: { at: string, mark: any }[] = []
+  walkVals(root, (v: any, path: string[]) => {
+    const name = fileName(v)
+    if (undefined !== name) {
+      files.push({ at: addr(path), name })
+    }
+    if (null != v.emitted) {
+      marks.push({ at: addr(path), mark: v.emitted })
+    }
+  })
+
+  const out: TraceEntry[] = []
+  for (const m of marks) {
+    const file = enclosing(files, m.at)
+    if (undefined === file) {
+      continue
+    }
+    out.push({ at: m.at, file, node: m.mark.node, rule: m.mark.rule })
+  }
+  return out
+}
+
+
+// THE MARKS ARE OPT-IN. `emit` stamps a piece only when the context
+// carries a `reads` set, so the verb asks for one the way `render
+// --trace` did.
+function traceRun(src: string, options?: TraceOptions): TraceReport {
+  const opts = options ?? {}
+  const aontu = new Aontu(includeOpts(opts))
+  const actx = aontu.ctx({ collect: true, reads: new Set<string>() })
+  const root: any = aontu.unify(
+    src, { path: opts.path, collect: true }, actx)
+  if (0 < actx.err.length || true === root?.isNil) {
+    return {
+      verdict: 'error', trace: [],
+      errors: [failureFinding(actx, opts.path, root)],
+    }
+  }
+
+  let node: any = root
+  const at = opts.at ?? '$.out'
+  const found: any = anchorAt(root, at)
+  if (null == found) {
+    const nil: any = makeNilErr(actx, 'no_path', root, undefined, 'at')
+    actx.err.push(nil)
+    return {
+      verdict: 'error', trace: [],
+      errors: [failureFinding(actx, opts.path, root)],
+    }
+  }
+  node = found
+
+  return { verdict: 'ok', trace: traceTree(node) }
+} /* node:coverage ignore next 6 */
+
+
+export {
+  traceTree,
+  traceRun,
+}

package/src/trim.ts

@@ -1,26 +1,6 @@
 /* Copyright (c) 2025 Richard Rodger, MIT License */
 import { includeOpts } from './utility'
 
-// The trim reporter (G3 phase 6,
-// docs/capability-review/g3-subsumption-evolution.md): report REDUNDANT
-// map entries — entries whose removal leaves the evaluated result
-// unchanged, the spread-implied case included — as paths. Report-only,
-// deliberately: canon discards comments and layout, so REWRITING the
-// file needs G7's format-preserving patch surface; trim ships as a
-// reporter here and becomes an editor there.
-//
-// The test is EVALUATE-AND-COMPARE: for each candidate entry, re-parse
-// the source, delete the entry from the parsed tree, evaluate, and
-// compare canons. This subsumes the design's spread case — an entry a
-// spread template re-supplies evaluates to the same canon without its
-// explicit spelling — and is honest about everything the fixpoint can
-// see (references, templates, duplicate-key merges), where a purely
-// structural test would guess. A removal that ERRORS is not redundant:
-// the entry is load-bearing.
-//
-// Parsed trees are single-use (docs/reference-api.md), so every probe
-// is its own parse: one evaluation per candidate plus one for the
-// baseline. A reporter can afford that; an editor loop belongs to G7.
 
 import { Aontu } from './aontu'
 import { failureFinding } from './vet'
@@ -34,12 +14,6 @@ export type TrimReport = {
   verdict: TrimVerdict
   redundant: string[]
 
-  // WHY the run could not be made, in the same finding shape vet
-  // reports in (the review's finding F). An `error` verdict used to
-  // arrive with an empty report -- something is wrong with the
-  // document, and nothing about what -- which is the one answer a
-  // repair loop cannot act on. Present ONLY on an `error` verdict, so
-  // a clean report stays exactly the two fields it always was.
   errors?: VetFinding[]
 }
 
@@ -47,14 +21,8 @@ export type TrimOptions = {
   // Where the document CAME FROM, so a relative `@"file"` load inside
   // it resolves from its own directory (vet's schemaPath precedent).
   path?: string
-  // The include capability this document evaluates under (G5,
-  // docs/trust.md). vet's precedent: the verb passes the profile the
-  // caller asked for, and an absent option means today's default.
   trust?: TrustOptions
 
-  // Extensions additionally read as text (the CLI's `--text-ext`).
-  // Rides beside `trust` because it is the other half of what an
-  // include may read.
   textExt?: string[]
 }
 
@@ -64,14 +32,6 @@ function pathText(path: string[]): string {
 }
 
 
-// Every (map, key) pair in a PARSED tree, parent-first. Candidates come
-// from the parse rather than the evaluation: an entry the fixpoint
-// erases or rewrites still has to be addressable for deletion. The
-// non-Val guard is for a bag's raw peg entries, which degenerate
-// parses can leave behind. Exported (with deleteAt and evalCanon) for
-// the direct unit tests (ADR-002, ts/test/coverage3.test.ts): the
-// defensive arms are unreachable through trimCheck, whose candidates
-// come from an identical parse.
 export function candidates(v: any, path: string[], out: string[][]): void {
   if (null == v || true !== v.isVal) {
     return
@@ -118,21 +78,12 @@ export function deleteAt(root: any, path: string[]): boolean {
 }
 
 
-// One evaluation: parse (deleting the entry at delPath, when given),
-// unify under collect, and answer the canon — or undefined when the
-// source does not stand up, which for the baseline is the caller's
-// error verdict and for a probe means "load-bearing".
 export function evalCanon(
   src: string, opts: TrimOptions, delPath?: string[],
   sink?: { ctx?: any, failed?: any }): string | undefined {
   const aontu = new Aontu(includeOpts(opts))
   const ctx = aontu.ctx({ collect: true })
   const parseOpts = null == opts.path ? undefined : { path: opts.path }
-  // WHY the run failed, for the one caller that reports it. The
-  // BASELINE run passes a sink and a probe does not: a probe's failure
-  // means "load-bearing", which is an answer rather than a fault, and
-  // reporting it would bury the one real finding under one entry's
-  // worth of noise per candidate.
   const fail = (failed?: any): undefined => {
     if (null != sink) {
       sink.ctx = ctx
@@ -158,10 +109,6 @@ export function evalCanon(
 }
 
 
-// The whole reporter: the baseline canon, then one probe per candidate
-// entry, parent-first — and a child of a redundant parent is SKIPPED,
-// because "remove the whole entry" already covers it and reporting
-// both would tell the author to delete the same text twice.
 export function trimCheck(src: string, opts?: TrimOptions): TrimReport {
   const options = opts ?? {}
 

package/src/type.ts

@@ -2,7 +2,6 @@
 
 import * as Fs from 'node:fs'
 
-// TODO: refactor these out
 
 import { Resolver } from '@tabnas/multisource'
 
@@ -13,35 +12,12 @@ import type { ValMark, ValSpec } from './val/Val'
 type FST = typeof Fs
 
 
-
-// The trust profile (G5, docs/trust.md): what an evaluation may read,
-// and how much work it may do. Trust is a property of the EVALUATION,
-// not the document -- a .aon file cannot request more capability -- and
-// the profile adds zero language syntax.
-//
-// The include capability:
-//   'none'            @"..." is always denied
-//   { mem: {...} }    a virtual file set only; nothing else resolves
-//   { root: '/dir' }  real files, realpath-confined below root;
-//                     no package resolution
-//   'system'          the full memory -> file -> package chain
-//                     (today's default, and the unconfined posture)
-//
-// Budgets are integer counts of engine events -- never wall-clock, which
-// would make identical inputs fail differently across machines (the
-// exact nondeterminism docs/trust.md forbids). The defaults are the
-// shared spec-visible constants pinned by test/spec/budget.tsv.
 type TrustInclude =
   | 'none'
   | 'system'
   | { mem: Record<string, string> }
   | { root: string }
 
-// Only the budgets BOTH ports can honour are profile surface: passes
-// and depth. The per-pair revisit bound (999) stays a TS-internal
-// constant — the Go dispatcher has no revisit counter (it is
-// depth-guarded), and a knob one port cannot implement would break the
-// parity contract (ADR-001) by construction.
 type TrustBudget = {
   passes?: number    // fixpoint passes (default 9)
   depth?: number     // structural recursion depth (default 1000)
@@ -53,21 +29,14 @@ type TrustOptions = {
 }
 
 type AontuOptions = {
-  src?: string    // Source text.
+  src?: string
   print?: number  // Print debug verbosity
-  resolver?: Resolver // Source resolver
+  resolver?: Resolver
   base?: string // Base path for resolver
   path?: string // Path of entry file
   debug?: boolean
   trace?: boolean
   fs?: FST
-  // errfs READS FOR THE ERROR RENDERER ONLY, never for resolution.
-  // A frame excerpts the file its arrow names, which means reading
-  // that file -- but handing the same reader to `fs` would change
-  // which leg the include RESOLVER takes (its file leg reads through
-  // the host filesystem when one is given, so a package hit can
-  // become a file hit), and a diagnostic must not move the boundary
-  // it is describing.
   errfs?: FST
   deps?: any
   log?: any
@@ -77,19 +46,8 @@ type AontuOptions = {
   explain?: any[]
   trust?: TrustOptions // Trust profile (G5, docs/trust.md)
 
-  // EXTENSIONS ADDITIONALLY READ AS TEXT, without their dots. `.txt`
-  // is read as text with no option at all; this widens that set for a
-  // host that keeps its prose in `.md`, its queries in `.sql`, or its
-  // templates under some name only it knows. The file's bytes become
-  // one string scalar -- no parser is chosen for it, which is what
-  // makes widening the set safe to offer.
   textExt?: string[]
 
-  // The staged-flip warning window (G5 phase 6, CLI only): under the
-  // default 'system' capability the CLI supplies these, and the
-  // resolver calls trustWarn for every resolution that escapes
-  // trustWarnRoot or goes through package resolution — naming the flag
-  // a future default will require. Not a stable embedding API.
   trustWarn?: (kind: 'escape' | 'pkg', path: string) => void
   trustWarnRoot?: string
 }
@@ -108,7 +66,6 @@ type ValMap = { [key: string]: Val }
 type ValList = Val[]
 
 
-
 type ErrContext = {
   src?: string,
   fs?: FST,