aontu 0.52.1 → 0.53.0

package/src/trim.ts

@@ -0,0 +1,195 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+// 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'
+import type { VetFinding } from './vet'
+import type { TrustOptions } from './type'
+
+
+export type TrimVerdict = 'clean' | 'redundant' | 'error'
+
+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[]
+}
+
+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
+}
+
+
+function pathText(path: string[]): string {
+  return '$' + (0 < path.length ? '.' + path.join('.') : '')
+}
+
+
+// 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
+  }
+  if (true === v.isMap && null != v.peg) {
+    for (const k of Object.keys(v.peg)) {
+      out.push([...path, k])
+      candidates(v.peg[k], [...path, k], out)
+    }
+  }
+  else if (true === v.isList && null != v.peg) {
+    // List ELEMENTS are not candidates: removing one shifts every
+    // later index, which is a different document, not the same one
+    // minus a redundancy. Entries of maps INSIDE lists still are.
+    for (const k of Object.keys(v.peg)) {
+      candidates(v.peg[k], [...path, k], out)
+    }
+  }
+}
+
+
+// Delete the entry at path from a parsed tree. False when the path
+// does not address a map entry (which cannot happen for a candidate
+// enumerated from an identical parse, but the walk stays honest).
+export function deleteAt(root: any, path: string[]): boolean {
+  let node: any = root
+  for (const seg of path.slice(0, -1)) {
+    if ((true === node?.isMap || true === node?.isList) && null != node.peg) {
+      node = node.peg[seg]
+    }
+    else {
+      return false
+    }
+  }
+  const key = path[path.length - 1]
+  if (true !== node?.isMap || null == node.peg ||
+    !Object.prototype.hasOwnProperty.call(node.peg, key)) {
+    return false
+  }
+  delete node.peg[key]
+  // Always an array on a parsed bag (BagVal initialises it).
+  node.optionalKeys = node.optionalKeys.filter((k: string) => k !== key)
+  return true
+}
+
+
+// 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(
+    null == opts.trust ? undefined : { trust: opts.trust })
+  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
+      // The failing ROOT travels with the context: a nil root can
+      // arrive with an EMPTY error list (`&: id(root)`), and the
+      // finding is built from it then (use-cases/BUGS.md §43).
+      sink.failed = failed
+    }
+    return undefined
+  }
+  const parsed: any = aontu.parse(src, parseOpts, ctx)
+  if (0 < ctx.err.length || null == parsed) {
+    return fail()
+  }
+  if (null != delPath && !deleteAt(parsed, delPath)) {
+    return undefined
+  }
+  const v: any = aontu.unify(parsed, parseOpts, ctx)
+  if (0 < ctx.err.length || true === v?.isNil) {
+    return fail(v)
+  }
+  return v.canon
+}
+
+
+// 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 ?? {}
+
+  const sink: { ctx?: any, failed?: any } = {}
+  const baseline = evalCanon(src, options, undefined, sink)
+  if (undefined === baseline) {
+    return {
+      verdict: 'error',
+      redundant: [],
+      errors: [failureFinding(sink.ctx, options.path, sink.failed)],
+    }
+  }
+
+  const aontu = new Aontu()
+  const ctx = aontu.ctx({ collect: true })
+  const parseOpts = null == options.path ? undefined : { path: options.path }
+  const parsed: any = aontu.parse(src, parseOpts, ctx)
+  const paths: string[][] = []
+  candidates(parsed, [], paths)
+
+  const redundant: string[] = []
+  for (const path of paths) {
+    const parent = pathText(path.slice(0, -1))
+    if (redundant.some((r) => r === parent || parent.startsWith(r + '.'))) {
+      continue
+    }
+    if (baseline === evalCanon(src, options, path)) {
+      redundant.push(pathText(path))
+    }
+  }
+
+  return {
+    verdict: 0 === redundant.length ? 'clean' : 'redundant',
+    redundant,
+  }
+}

package/src/tsconfig.json

@@ -3,15 +3,21 @@
     "esModuleInterop": true,
     "module": "nodenext",
     "noEmitOnError": true,
-    "outDir":"../dist",
-    "rootDir":".",
+    "noFallthroughCasesInSwitch": true,
+    "noImplicitReturns": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "outDir": "../dist",
+    "rootDir": ".",
     "resolveJsonModule": true,
     "sourceMap": true,
     "strict": true,
     "target": "es2021",
     "declaration": true,
     "declarationDir": "../dist",
-    "types": ["node"]
+    "types": [
+      "node"
+    ],
+    "composite": true
   }
 }
-

package/src/type.ts

@@ -6,7 +6,6 @@ import * as Fs from 'node:fs'
 
 import { Resolver } from '@tabnas/multisource'
 
-import { AontuContext } from './ctx'
 import { Val, DONE, SPREAD } from './val/Val'
 import type { ValMark, ValSpec } from './val/Val'
 
@@ -15,6 +14,44 @@ 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)
+}
+
+type TrustOptions = {
+  include?: TrustInclude
+  budget?: TrustBudget
+}
+
 type AontuOptions = {
   src?: string    // Source text.
   print?: number  // Print debug verbosity
@@ -30,6 +67,15 @@ type AontuOptions = {
   collect?: boolean // Collect errors into an errs property, rather than throw them.
   err?: any[]
   explain?: any[]
+  trust?: TrustOptions // Trust profile (G5, docs/trust.md)
+
+  // 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
 }
 
 
@@ -50,7 +96,7 @@ type ValList = Val[]
 type ErrContext = {
   src?: string,
   fs?: FST
-} /* node:coverage ignore next 20 */
+} /* node:coverage ignore next 24 */
 
 export type {
   Val,
@@ -61,6 +107,9 @@ export type {
   AontuOptions,
   ErrContext,
   FST,
+  TrustInclude,
+  TrustBudget,
+  TrustOptions,
 }
 
 export {