aontu 0.52.1 → 0.53.0

package/src/relation.ts

@@ -0,0 +1,395 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+// RELATION GRAPH CHECKS (G4 phase 5,
+// docs/capability-review/g4-identity-relations.md): acyclicity and
+// inverse consistency over the edge set, checked AFTER unification and
+// never by it.
+//
+// Why not in the lattice. Both properties are GLOBAL and NON-MONOTONE:
+// an acyclic graph becomes cyclic when one more edge unifies in, and an
+// inverse that is present becomes absent when the far side is narrowed.
+// The lattice guarantee is that more information never falsifies what
+// has been observed, so a constraint that could be true and then false
+// is not a constraint the lattice may hold. These are facts about the
+// finished model, and the verb that reports facts about a finished
+// model is where they belong.
+//
+// A relation is DECLARED as data, under the `relations` key of the
+// document root, which is the `std/system` vocabulary's convention:
+//
+//   relations: dependsOn: $.std.Relation & {
+//     target: $.std.Service, inverse: dependedOnBy, acyclic: true
+//   }
+//
+// Nothing in the engine knows the name `relations`; this pass does,
+// and says so.
+
+import { Aontu } from './aontu'
+import { failureFinding } from './vet'
+import type { VetFinding } from './vet'
+import type { TrustOptions, Val } from './type'
+import { graphOf } from './graph'
+import type { Edge, EntityEntry, Graph } from './graph'
+import { cmpCodePoint } from './keyorder'
+import { unite } from './unify'
+
+
+export type RelationVerdict = 'pass' | 'fail' | 'error'
+
+export type RelationFinding = {
+  code: string
+  // The relation the finding is about.
+  relation: string
+  // Where the offending edge is written, as a `$.dotted.path`.
+  at: string
+  // For a cycle, the entities it runs through, in the order the walk
+  // found them, closing back on the first. For a missing inverse, the
+  // two ends and the relation that should have mirrored it.
+  detail: string[]
+}
+
+export type RelationReport = {
+  verdict: RelationVerdict
+  findings: RelationFinding[]
+
+  // WHY the graph could not be looked at, in the same finding shape
+  // vet reports in (the review's finding F). `findings` is about the
+  // GRAPH and stays that way; a document that does not stand up has no
+  // graph to have findings about, and an `error` verdict used to
+  // arrive with an empty list -- something is wrong, and nothing about
+  // what. Present ONLY on an `error` verdict.
+  errors?: VetFinding[]
+}
+
+export type RelationOptions = {
+  // Where the document CAME FROM, so a relative `@"file"` load inside
+  // it resolves from its own directory (trimCheck's 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
+}
+
+
+// One declared relation, as the document spells it.
+type Declared = {
+  name: string
+  inverse?: string
+  acyclic: boolean
+  // What the FAR END must satisfy, if the relation says. Absent when
+  // the relation declares none, and when it declares `top` -- which
+  // constrains nothing and would report nothing, so reading it as a
+  // declaration would only cost a meet per edge.
+  target?: Val
+}
+
+
+// The entity an address names — everything before the first dot. An
+// edge into `svc/auth.ports.http` is an edge to `svc/auth`: a relation
+// holds between ENTITIES, and the path inside one says which part of it
+// the link reaches.
+function entityOf(addr: string): string {
+  const dot = addr.indexOf('.')
+  return dot < 0 ? addr : addr.slice(0, dot)
+}
+
+
+// The node an address names, or undefined. The entity's own position
+// comes from the graph (a merged entity sits at every position that
+// declared it, and they hold the same value, so the FIRST in the
+// graph's sorted list is as good as any and is the same one in both
+// ports); the rest of the address walks into it, exactly as the
+// address's own grammar says.
+// NO GUARD ON THE LOOKUP OR THE WALK. An edge exists only because
+// `refer()` RESOLVED its full address, so `find` cannot miss and no
+// segment can fall off: an address that does not walk is
+// `refer_unresolved` at unification and the document never reaches the
+// graph (probed for a missing key, a scalar mid-path and an
+// out-of-range index, in both ports). An unreachable `if` is a branch
+// arm the ADR-002 gate counts and no marker suppresses, so the Go twin
+// keeps its guards — where a nil would PANIC rather than propagate,
+// and where the marker mechanism can carry them — and this one relies
+// on optional chaining instead.
+function addressed(
+  root: any, graph: Graph, addr: string
+): any {
+  const dot = addr.indexOf('.')
+  const name = dot < 0 ? addr : addr.slice(0, dot)
+  const entry = graph.entities.find((e) => e.id === name) as EntityEntry
+  const segs = entry.paths[0].slice(2).split('.')
+    .concat(dot < 0 ? [] : addr.slice(dot + 1).split('.'))
+  let node: any = root
+  for (const seg of segs) {
+    node = node?.peg?.[seg]
+  }
+  return node
+}
+
+
+// Does the far end satisfy the declared target? A TEST, never a flow:
+// the check reports on a finished model and writing into it would be
+// generation, which `relations` does not do (the same rule that keeps
+// it from writing an author's inverse for them). So both sides are
+// CLONED into a throwaway context and the meet is taken there; what
+// the document holds is untouched either way.
+//
+// `refer(t)` is the other half of this and does flow, at the site. The
+// two agree on what "satisfies" means -- a meet that is not a nil --
+// which is what lets a relation declare once what every site would
+// otherwise repeat.
+// `root` is the DOCUMENT, not the node: a target lifted out of the
+// model (`target: $.std.Service`) can still hold a reference that
+// resolves against the document, and a probe rooted at the far end
+// answers `no_path` for it -- which the worked example in
+// test/spec/relation.tsv caught the moment this check existed.
+function meets(
+  aontu: any, root: any, node: any, target: any
+): string | undefined {
+  const ctx = aontu.ctx({ collect: true })
+  ctx.root = root
+  const out: any = unite(ctx, node.clone(ctx), target.clone(ctx), 'relation-target')
+  if (true === out?.isNil) {
+    return out.why as string
+  }
+  if (0 < ctx.err.length) {
+    return ctx.err[0].why as string
+  }
+
+  // A MEET THAT LEAVES A HOLE IS NOT SATISFACTION. `target:
+  // {kind: service, port: integer}` against a far end with no `port`
+  // does not CONFLICT -- the meet simply carries `integer` into a key
+  // that had none -- and a check that stopped at "no conflict" would
+  // pass a far end that is missing half of what the relation demands.
+  //
+  // What `refer(t)` does at the site is the yardstick: it flows `t` in,
+  // and the document then fails to generate, because `integer` is not a
+  // value. So the same question is asked here -- can the far end still
+  // generate once the target is met? -- and the answer is compared with
+  // the far end ALONE, so a node that was already incomplete for its
+  // own reasons is not blamed on the relation that points at it.
+  // The REASON reported is the engine's own -- the code `refer(t)` at
+  // the site would have raised -- rather than a name invented here.
+  const probe = (v: any): string | undefined => {
+    const gctx = aontu.ctx({ collect: true })
+    gctx.root = root
+    v.gen(gctx)
+    return 0 === gctx.err.length ? undefined : (gctx.err[0].why as string)
+  }
+  const alone = probe(node.clone(aontu.ctx({ collect: true })))
+  const met = probe(out)
+  return undefined === alone && undefined !== met ? met : undefined
+}
+
+
+function declaredRelations(root: any): Declared[] {
+  const rels = root?.peg?.relations
+  if (true !== rels?.isMap) {
+    return []
+  }
+  const out: Declared[] = []
+  for (const name of Object.keys(rels.peg).sort(cmpCodePoint)) {
+    const r: any = rels.peg[name]
+    if (true !== r?.isMap) {
+      continue
+    }
+    const inv: any = r.peg.inverse
+    const acy: any = r.peg.acyclic
+    const tgt: any = r.peg.target
+    out.push({
+      name,
+      inverse: true === inv?.isScalar && 'string' === typeof inv.peg
+        ? inv.peg : undefined,
+      acyclic: true === acy?.isScalar && true === acy.peg,
+      target: true === tgt?.isVal && true !== tgt.isTop ? tgt : undefined,
+    })
+  }
+  return out
+}
+
+
+// The first cycle reachable from `start`, as the entities it runs
+// through, or undefined. Depth-first with the path as the stack, and
+// the successors visited in sorted order, so the cycle a report names
+// is the same one in both ports.
+function findCycle(
+  start: string,
+  succ: Map<string, string[]>,
+  done: Set<string>,
+): string[] | undefined {
+  const stack: string[] = []
+  const onStack = new Set<string>()
+
+  const walk = (node: string): string[] | undefined => {
+    if (onStack.has(node)) {
+      return [...stack.slice(stack.indexOf(node)), node]
+    }
+    if (done.has(node)) {
+      return undefined
+    }
+    done.add(node)
+    stack.push(node)
+    onStack.add(node)
+    for (const next of succ.get(node) ?? []) {
+      const found = walk(next)
+      if (undefined !== found) {
+        return found
+      }
+    }
+    stack.pop()
+    onStack.delete(node)
+    return undefined
+  }
+
+  return walk(start)
+}
+
+
+// The relation checks for one document.
+export function relationCheck(
+  src: string, opts?: RelationOptions): RelationReport {
+  const options = opts ?? {}
+  const aontu = new Aontu(
+    null == options.trust ? undefined : { trust: options.trust })
+  const ctx = aontu.ctx({ collect: true })
+  const parseOpts = null == options.path ? undefined : { path: options.path }
+  const root: any = aontu.unify(src, parseOpts, ctx)
+
+  // A document that does not stand up is not a document with a bad
+  // graph: the errors it already has are the answer, and blaming its
+  // relations on top would be noise.
+  if (0 < ctx.err.length || true === root?.isNil) {
+    return {
+      verdict: 'error',
+      findings: [],
+      errors: [failureFinding(ctx, options.path, root)],
+    }
+  }
+
+  const declared = declaredRelations(root)
+  if (0 === declared.length) {
+    return { verdict: 'pass', findings: [] }
+  }
+
+  const graph = graphOf(root)
+  const edges = graph.edges
+  const findings: RelationFinding[] = []
+
+  // The edge set, indexed the two ways the checks read it.
+  const byRelation = new Map<string, Edge[]>()
+  const pairs = new Set<string>()
+  for (const e of edges) {
+    if ('' === e.from) {
+      // An edge outside every entity has no source to be a relation OF.
+      continue
+    }
+    const list = byRelation.get(e.key)
+    if (undefined === list) {
+      byRelation.set(e.key, [e])
+    }
+    else {
+      list.push(e)
+    }
+    pairs.add(e.key + ' ' + e.from + ' ' + entityOf(e.to))
+  }
+
+  for (const rel of declared) {
+    const mine = byRelation.get(rel.name) ?? []
+
+    if (rel.acyclic) {
+      const succ = new Map<string, string[]>()
+      for (const e of mine) {
+        const list = succ.get(e.from)
+        const to = entityOf(e.to)
+        if (undefined === list) {
+          succ.set(e.from, [to])
+        }
+        else {
+          list.push(to)
+        }
+      }
+      for (const list of succ.values()) {
+        list.sort(cmpCodePoint)
+      }
+
+      // The roots are visited in sorted order, and a node already
+      // settled is not revisited, so one cycle is reported once and the
+      // SAME one in both ports.
+      const done = new Set<string>()
+      const roots = [...succ.keys()].sort(cmpCodePoint)
+      for (const from of roots) {
+        const cycle = findCycle(from, succ, done)
+        if (undefined !== cycle) {
+          // The cycle's first node is a key of `succ`, and every key of
+          // `succ` came from an edge's `from`, so the edge is there.
+          const at = mine.find((e) => e.from === cycle[0]) as Edge
+          findings.push({
+            code: 'relation_cycle',
+            relation: rel.name,
+            at: at.at,
+            detail: cycle,
+          })
+          break
+        }
+      }
+    }
+
+    // TARGET: the far end IS what the relation says it is (the review's
+    // finding J). The declaration used to be inert -- `target` was read
+    // by nothing, on the reasoning that `refer(t)` already flows the
+    // type in at the site. It does, and that is exactly why the
+    // declaration was worth nothing: the site has to REPEAT it, and the
+    // idiom that avoids repeating it (`refer($.std.Service)`) tripped
+    // the fixpoint until §19 was fixed, so every real model wrote bare
+    // `refer()` and a typed-endpoint declaration checked nothing.
+    //
+    // Reported per EDGE, not per entity: an entity reached by two
+    // relations must satisfy both, and the report points at the link
+    // that made the demand.
+    if (undefined !== rel.target) {
+      for (const e of mine) {
+        // No guard on the node either, and for the same reason
+        // `addressed` needs none: an unresolved link is a nil in the
+        // tree, so this document would not have reached the graph.
+        const why = meets(aontu, root, addressed(root, graph, e.to),
+          rel.target)
+        if (undefined !== why) {
+          findings.push({
+            code: 'relation_target_unmet',
+            relation: rel.name,
+            at: e.at,
+            detail: [e.from, e.to, why],
+          })
+        }
+      }
+    }
+
+    if (undefined !== rel.inverse) {
+      for (const e of mine) {
+        const to = entityOf(e.to)
+        if (!pairs.has(rel.inverse + ' ' + to + ' ' + e.from)) {
+          findings.push({
+            code: 'relation_inverse_missing',
+            relation: rel.name,
+            at: e.at,
+            detail: [e.from, to, rel.inverse],
+          })
+        }
+      }
+    }
+  }
+
+  // SORTED, because a report is read by a machine that diffs it: by the
+  // position the offending edge is written at, then by code. No third
+  // key: one edge sits under one key and one key is one relation, so
+  // two findings can share (at, code) only by being the same finding.
+  // The sort is STABLE, and the relations were iterated in sorted
+  // order, so what order remains is fixed anyway.
+  findings.sort((a, b) =>
+    cmpCodePoint(a.at, b.at) || cmpCodePoint(a.code, b.code))
+
+  return {
+    verdict: 0 === findings.length ? 'pass' : 'fail',
+    findings,
+  }
+}

package/src/report-sarif.ts

@@ -0,0 +1,137 @@
+/* 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'
+
+import { exactJSON } from './exactjson'
+
+
+// SARIF levels are error/warning/note; the report's severities are
+// error/warning/info. Only `info` needs translating, but the map spells
+// out all three so a new severity fails loudly here rather than
+// silently emitting itself.
+const SARIF_LEVEL: Record<string, string> = {
+  error: 'error',
+  warning: 'warning',
+  info: 'note',
+}
+
+
+// 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 = ''
+  for (const b of bytes) {
+    const c = String.fromCharCode(b)
+    if (b < 128 && /[A-Za-z0-9\-._~/!$&'()*+,;=:@]/.test(c)) {
+      out += c
+    }
+    else {
+      out += '%' + b.toString(16).toUpperCase().padStart(2, '0')
+    }
+  }
+  return out
+}
+
+
+function sarifLocation(site: VetSite): any {
+  const physical: any = {
+    artifactLocation: { uri: sarifUri(site.file) },
+  }
+  // SARIF regions are 1-based. A finding with no position — a parse
+  // failure reports at -1:-1 — gets a location with no region rather
+  // than an invented one.
+  if (1 <= site.row) {
+    physical.region = { startColumn: site.col, startLine: site.row }
+  }
+  return { physicalLocation: physical }
+}
+
+
+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])],
+    message: { text: finding.message },
+    properties: finding,
+    ruleId: 'aontu/' + finding.code,
+  }
+  const related = finding.sites.slice(1)
+  if (0 < related.length) {
+    result.relatedLocations = related.map(sarifLocation)
+  }
+  return result
+}
+
+
+/**
+ * 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,
+      }],
+      results: report.findings.map(sarifResult),
+      tool: {
+        driver: {
+          informationUri: 'https://github.com/rjrodger/aontu',
+          name: 'aontu',
+          version,
+        },
+      },
+    }],
+    version: '2.1.0',
+  }, 2)
+} /* node:coverage ignore next 6 */
+
+
+export {
+  sarifReport,
+}

package/src/site.ts

@@ -6,12 +6,45 @@ import type {
 } from './type'
 
 
-type SiteSpec = { row?: number, col?: number, url?: string }
+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.
 class Site {
   row: number
   col: number
   url: string
+  len: number
+  src: string
 
   constructor(val?: Val | SiteSpec) {
     const site = ((val as any)?.site ?? val) as SiteSpec
@@ -19,6 +52,8 @@ class Site {
     this.row = site?.row ?? -1
     this.col = site?.col ?? -1
     this.url = site?.url ?? ''
+    this.len = site?.len ?? -1
+    this.src = site?.src ?? ''
   }
 } /* node:coverage ignore next 6 */
 

package/src/std.ts

@@ -0,0 +1,73 @@
+/* Copyright (c) 2025 Richard Rodger, MIT License */
+
+// THE BUNDLED VOCABULARY (G4 phase 4,
+// docs/capability-review/g4-identity-relations.md): `@"std/system"` is
+// served from the engine itself — no filesystem, no package resolution
+// — so a document may use it under every include capability except
+// `none`, and the hermeticity posture is not widened by a source that
+// never leaves the process.
+//
+// The TEXT is the shared artifact: go/std.go carries the same bytes,
+// and test/spec/std-system.tsv pins its canon and its canon-hash in
+// both engines, so the two copies cannot drift without a red suite.
+// It carries no backtick for that reason: one string literal per port,
+// and Go's raw string has no escape.
+
+const STD_SYSTEM = `# std/system --- the SYSTEM VOCABULARY (G4 phase 4). Ports, components
+# and relations need no syntax: they are schemas. Everything here is
+# ordinary unification --- conjunction, spreads, marks, defaults ---
+# so the vocabulary costs the language nothing, and an author who wants
+# a different one writes it the same way.
+#
+# EXPERIMENTAL until the distribution layer can version it by
+# canon-hash. Entity ids deliberately do NOT embed versions: fusing
+# identity and version makes "v1 and v2 describe the same entity"
+# inexpressible.
+
+std: {
+
+  # One end of a connection.
+  Port: type({
+    direction: *in | out | inout
+    protocol?: string
+  })
+
+  # A node with ports. A Component that is not itself an entity is a
+  # component OF its nearest identified ancestor, which is the
+  # entity/component distinction and needs no mark of its own.
+  Component: type({
+    ports?: {&: $.std.Port}
+  })
+
+  # A component that is a service. Written out rather than as
+  # $.std.Component & {kind: service}: a reference from one member of
+  # this file to another does not survive being INCLUDED into a
+  # document (the marks the include carries make the referring member
+  # unusable), so the vocabulary states each schema on its own.
+  Service: type({
+    kind: service
+    ports?: {&: $.std.Port}
+  })
+
+  # A DECLARED RELATION. "target" is what the far end must satisfy,
+  # "inverse" names the relation that must mirror it, and "acyclic"
+  # asks that the edge set have no cycle. The last two are checked
+  # AFTER unification, not by it: they are global and non-monotone ---
+  # an acyclic graph becomes cyclic when one more edge unifies in ---
+  # and no lattice citizen may be falsified by more information.
+  Relation: type({
+    target?: top
+    inverse?: string
+    acyclic?: *false | boolean
+  })
+}
+`
+
+
+// The bundled sources, by the name a document writes. Both the bare
+// name and the `.aon` spelling resolve, because both are what an
+// author reaches for.
+export const STD_SOURCES: Record<string, string> = {
+  'std/system': STD_SYSTEM,
+  'std/system.aon': STD_SYSTEM,
+}