aontu 0.66.0 → 0.67.0

package/src/cli.ts

@@ -166,22 +166,30 @@ query between a document and its own earlier versions.
 
 Options:
   -c, --canon     Print the canonical form instead of generated JSON
-  --format <f>    text (default) or json. The json form wraps the
-                  answer as {aontu, findings, ok, out}, so a failure
-                  here reads like every other verb's
+                  (the bare command's, as --jsonl is; model get has
+                  its own)
+  --format <f>    text (default) or json, on every verb that answers a
+                  report. The json form is one object opening with an
+                  aontu block; the bare command's carries findings, ok
+                  and out
   -h, --help      Show this help and exit (the verbs and their flags);
                   aontu help is the LANGUAGE, and lists its own topics
   --jsonl         REPL: answer every command as one JSON line
   -v, --version   Print the version and exit
-  --trust <t>     Include capability: system (default), none, or
-                  root[:dir] to confine @"..." below a directory.
-                  Every verb takes it too, and a bare root means the
-                  document's own directory
+  --trust <t>     Include capability: system, none, or root[:dir] to
+                  confine @"..." below a directory. A bare root means
+                  the entry root: the document's own directory, or the
+                  project's for the package verbs. Every verb takes it
+                  but help, explain, init and lsp, which read no
+                  document, and mcp, which is the npm build's server
+                  and confines with --root. Unset, a run behaves as
+                  system, and the bare command warns once for an
+                  include that leaves the entry root
   --include-root <dir>  Shorthand for --trust root:<dir>
-  --text-ext <e>  Read these extensions as text too, comma-separated
-                  and without dots (md,sql). .txt needs no flag; a
+  --text-ext <e>  Read these extensions as text too, comma-separated,
+                  with or without dots (md,sql). .txt needs no flag; a
                   named format keeps its meaning, and .js stays
-                  refused. Every verb takes it
+                  refused. The verbs that take --trust take it too
 
 Package verbs (a module is imported; a package is published):
   sync      Make the project correct: resolve by minimum version
@@ -708,7 +716,7 @@ function takeTrust(argv: string[], io: Io = PROCESS_IO):
     }
     else if ('--include-root' === arg) {
       const dir = argv[++i]
-      if (null == dir) {
+      if (null == dir || '' === dir) {
         io.err('aontu: --include-root needs a directory\n')
         return undefined
       }
@@ -2704,20 +2712,42 @@ function pkgNetText(verb: string, report: any): string {
 const MODEL_HELP = 'aontu model get|why|set ... (try --help)'
 
 // One document, interrogated or edited (ADR-039 part 5).
+// Where the subcommand is, past any global flag that precedes it.
+// `takeTrust` strips those anywhere in a tail, so the subcommand has
+// to be found past a flag AND past its value: in `--text-ext get` the
+// `get` is the extension list, not the subcommand.
+const MODEL_SUBS = ['get', 'why', 'set']
+const GLOBAL_VALUED = ['--trust', '--include-root', '--text-ext']
+
+
+function modelSubAt(argv: string[]): number {
+  for (let i = 0; i < argv.length; i++) {
+    if (GLOBAL_VALUED.includes(argv[i])) {
+      i++
+      continue
+    }
+    return MODEL_SUBS.includes(argv[i]) ? i : -1
+  }
+  return -1
+}
+
+
 function runModel(argv: string[]): number {
   const sub = argv[0]
   if ('-h' === sub || '--help' === sub) {
     process.stdout.write(HELP)
     return 0
   }
-  if ('get' === sub) {
-    return runGet(argv.slice(1))
-  }
-  if ('why' === sub) {
-    return runWhy(argv.slice(1))
-  }
-  if ('set' === sub) {
-    return runSet(argv.slice(1))
+  const at = modelSubAt(argv)
+  if (0 <= at) {
+    const tail = argv.slice(0, at).concat(argv.slice(at + 1))
+    if ('get' === argv[at]) {
+      return runGet(tail)
+    }
+    if ('why' === argv[at]) {
+      return runWhy(tail)
+    }
+    return runSet(tail)
   }
   process.stderr.write(`aontu: model needs get, why or set\n${MODEL_HELP}\n`)
   return 2
@@ -2931,6 +2961,70 @@ function isDirectory(path: string): boolean {
 }
 
 
+// A `File` the write path skips, RENAMED rather than removed: dropping
+// the node would take its children's claims with it and hide drift the
+// write path does make. The skip is the File's own save alone, so what
+// separates the runs is its output path, composed by the runtime rather
+// than here.
+const EXCLUDED_NAME = '.aontu-check-excluded-'
+
+
+// `exclude` as the runtime reads it: `true`, or a string or list member
+// equal to the node's COMPONENT path, the chain of `name` props above
+// it, which a Project's `folder` is not part of. The Go runtime honours
+// the boolean alone, so the ports' `--check` answers differ for the
+// path forms (test/spec/divergent.tsv).
+function excludedFile(exclude: any, at: string[]): boolean {
+  if (true === exclude) {
+    return true
+  }
+  const path = at.join('/')
+  if ('string' === typeof exclude) {
+    return exclude === path
+  }
+  return Array.isArray(exclude) && exclude.includes(path)
+}
+
+
+function renameExcluded(node: any, at: string[], cut: number[]): any {
+  if (Array.isArray(node)) {
+    return node.map((child) => renameExcluded(child, at, cut))
+  }
+  // A hand-written tree carries nodes with no `props` and nodes with
+  // no `children`, and neither needs an arm of its own.
+  const props: any = node.props ?? {}
+  const below = 'string' === typeof props.name ? at.concat(props.name) : at
+  if ('File' === node.cmp && excludedFile(props.exclude, below)) {
+    cut.push(1)
+    return { ...node, props: { ...props, name: EXCLUDED_NAME + cut.length } }
+  }
+  if (!Array.isArray(node.children)) {
+    return node
+  }
+  return { ...node, children: renameExcluded(node.children, below, cut) }
+}
+
+
+// A file the runtime declined to touch, its copy on disk carrying the
+// protect marker, is in none of the lists it answers with: they hold
+// what was DONE to a file, and nothing was. The run's own record names
+// it. `since` drops what earlier runs left.
+function renderSkipped(folder: string, since: number): string[] {
+  const at = join(folder, '.jostraca', 'jostraca.meta.log')
+  let meta: any
+  try {
+    meta = JSON.parse(readFileSync(at, 'utf8'))
+  }
+  catch (err: any) {
+    return []
+  }
+  return Object.entries(meta?.files ?? {})
+    .filter(([_, f]: [string, any]) => 'skip' === f?.action && since <= f?.when)
+    .map(([path]) => path)
+    .sort(cmpCodePoint)
+}
+
+
 async function runRender(argv: string[]): Promise<number> {
   const trusted = takeTrust(argv)
   if (null == trusted) {
@@ -3081,7 +3175,22 @@ async function runRender(argv: string[]): Promise<number> {
   try {
     if (check) {
       const res = await runtime.check({ folder }, root)
-      const drift = res.drift.map((d: any) => ({ kind: d.kind, path: d.path }))
+      let drift = res.drift.map((d: any) => ({ kind: d.kind, path: d.path }))
+      // `--check` answers "would `render` change anything", so a file
+      // the write path leaves alone is not held to the generator's
+      // bytes. The skip is gated on the target BEING there -- `render`
+      // writes an absent one -- so drift at a path with nothing at it
+      // survives, which is the `missing` a deleted file reports.
+      const cut: number[] = []
+      const renamed = renameExcluded(tree, [], cut)
+      if (0 < cut.length) {
+        const kept = new Set<string>((await Jostraca().check(
+          { folder }, cmpTree(renamed, { raw: true }))).checked)
+        const skipped = new Set<string>(
+          res.checked.filter((p: string) => !kept.has(p)))
+        drift = drift.filter((d: any) => !skipped.has(d.path) ||
+          !existsSync(join(folder, d.path)))
+      }
       if ('json' === format) {
         process.stdout.write(exactJSON({
           aontu: { version: version(), verb: 'render' },
@@ -3098,14 +3207,21 @@ async function runRender(argv: string[]): Promise<number> {
       return 0 === drift.length ? 0 : 1
     }
 
+    const since = Date.now()
     const res = await runtime.generate({ folder }, root)
+    const skipped = renderSkipped(folder, since)
     if ('json' === format) {
       process.stdout.write(exactJSON({
         aontu: { version: version(), verb: 'render' },
         verdict: 'ok',
-        files: res.files,
+        files: { ...res.files, skipped },
       }, 2) + '\n')
     }
+    else {
+      for (const path of skipped) {
+        process.stdout.write(`skipped: ${path}\n`)
+      }
+    }
     return 0
   }
   catch (err: any) {
@@ -3932,7 +4048,7 @@ function runHash(argv: string[]): number {
   if (0 < ctx.err.length || true === v?.isNil) {
     process.stderr.write(
       `aontu: ${files[0]} does not evaluate on its own; nothing to hash\n` +
-      renderFinding(evalFailure(ctx)) + '\n')
+      renderFinding(evalFailure(ctx, v)) + '\n')
     return 4
   }
 
@@ -5322,7 +5438,7 @@ function main(argv: string[], servers: Servers = SERVERS): void {
     }
     else if ('--include-root' === arg) {
       const dir = args[++i]
-      if (null == dir) {
+      if (null == dir || '' === dir) {
         process.stderr.write('aontu: --include-root needs a directory\n')
         return finish(2)
       }
@@ -5385,7 +5501,7 @@ export {
   runJsonSchema,
   runTemplate,
   runTrace,
-  runRender,
+  runRender, renderSkipped,
   runPkg, runModel, runPackageVerb, pkgToolOptions, serveUntilInterrupted,
   runHash, runGet, runHelp, runExplain, runInit, nearestVerb,
   looksLikeVerb,

package/src/hints.ts

@@ -181,7 +181,7 @@ const hints: Record<string, string> = {
 
   merge_conflict: 'A version-control conflict marker was found in the source. The\nfile still holds an unresolved merge: resolve it and remove the\n`<<<<<<<`, `=======` and `>>>>>>>` lines before unifying.\n \nExamples:\n  <<<<<<< HEAD  -> nil  # A conflict marker, not a `<` operation;\n  =======       -> nil  # ... nor a chain of `=` characters;\n  >>>>>>> other -> nil  # ... nor a `>` operation.',
 
-  include_denied: 'An @"..." include was refused by the active trust profile\n(docs/trust.md). The document asked to read a source the evaluation\'s\ninclude capability does not allow: widen the capability if the read is\nintended, or remove the include if it is not.\n \nExamples:\n  a:@"./in-root.aon"    -> {..}  # Inside the confinement root: allowed;\n  a:@"../secret.aon"  -> nil   # ... but escaping the root is denied;\n  a:@"/etc/hostname"  -> nil   # ... and so is an absolute path outside it.',
+  include_denied: 'An @"..." include was refused by the active trust profile\n(docs/trust.md). The document asked to read a source the evaluation\'s\ninclude capability does not allow: widen the capability if the read is\nintended, or remove the include if it is not.\n \nExamples:\n  a:@"./in-root.aon"  -> {..}  # Inside the confinement root: allowed;\n  a:@"../secret.aon"  -> nil   # ... but escaping the root is denied;\n  a:@"/etc/hostname"  -> nil   # ... and so is an absolute path outside it.',
   include_extension: 'An @\"...\" include named a file the engine does not read. THE\nEXTENSION DECIDES which of two things a file is: `.aon` and\n`.aontu` are aontu source, with the whole language in them, and\n`.json`, `.jsonld`, `.jsonc`, `.json5`, `.jsonic`, `.jsc`, `.toml`,\n`.yaml`, `.yml` and `.ini` are configuration DATA, read by that\nformat\'s own parser. Anything else -- and a name with no extension\n-- is refused rather than guessed at: a guess produces a document\nthat looks right and is not.\n \nExamples:\n  a:@\"model.aon\"    -> {..}  # aontu source;\n  a:@\"server.toml\"  -> {..}  # ... config data, read as TOML;\n  a:@\"notes.txt\"    -> nil   # ... but text is not a document;\n  a:@\"data\"         -> nil   # ... and neither is an unnamed kind.',
 
   func_arity: 'This function was called with the wrong number of arguments:\n{func} takes {want}, but was given {got}.\n \nExamples:\n  upper(\"a\")     -> \"A\"  # One argument, which is what upper takes;\n  upper(\"a\",\"b\") -> nil  # ... so two is a mistake in the source;\n  key()          -> \"\"   # key takes none, or one level count;\n  neq(1,2,3)     -> neq  # ... and neq takes one or more exclusions.',
@@ -780,6 +780,7 @@ const codeClasses: Record<string, string> = {
 
   // internal -- the engine reached a state it should not reach
   internal: 'internal',
+  unify_failed: 'internal',
   unify_no_res: 'internal',
   unknown_op: 'internal',
 }

package/src/lang.ts

@@ -1544,9 +1544,13 @@ function makeModelResolver(options: any) {
 
   const memCapability =
     'object' === typeof capability && null != (capability as any).mem
+  // An EMPTY root denies: resolving it yields the process directory.
+  const emptyRoot =
+    'object' === typeof capability && '' === (capability as any).root
   const rootDir: string | undefined =
     'object' === typeof capability &&
-      'string' === typeof (capability as any).root
+      'string' === typeof (capability as any).root &&
+      '' !== (capability as any).root
       ? pathResolve((capability as any).root) : undefined
 
   let memResolver = makeMemResolver(memCapability
@@ -1584,7 +1588,7 @@ function makeModelResolver(options: any) {
   const deny = (path: string): never => {
     // Only 'none' and 'root' can deny: the mem capability's misses are
     // not-found (its set is the whole world), so there is no third arm.
-    const capname = 'none' === capability ? 'none' : 'root:' + rootDir
+    const capname = null == rootDir ? 'none' : 'root:' + rootDir
     const err: any = new Error(
       'include denied: ' + path + ' (capability: ' + capname + ')')
     err.code = 'include_denied'
@@ -1679,7 +1683,7 @@ function makeModelResolver(options: any) {
       return { found: false, path: '' + (path ?? ''), search: [] }
     }
 
-    if ('none' === capability) {
+    if ('none' === capability || emptyRoot) {
       deny(path)
     }
 

package/src/mcp-server.ts

@@ -33,7 +33,7 @@ export function parseArgs(argv: string[]): ServerArgs {
     }
     if ('--root' === arg) {
       const dir = argv[++i]
-      if (null == dir) {
+      if (null == dir || '' === dir) {
         return { err: 'aontu-mcp: --root needs a directory' }
       }
       root = dir

package/src/mcp.ts

@@ -653,7 +653,7 @@ function hashOf(
   const v: any = aontu.unify(
     src, null == path ? undefined : { path }, ctx)
   if (0 < ctx.err.length || null == v || true === v.isNil) {
-    return { ok: false, hash: '', findings: [evalFailure(ctx)] }
+    return { ok: false, hash: '', findings: [evalFailure(ctx, v)] }
   }
   return {
     ok: true,

package/src/query.ts

@@ -5,7 +5,7 @@ import { includeOpts } from './utility'
 import { Aontu } from './aontu'
 import type { TrustOptions } from './type'
 import { exactJSON } from './exactjson'
-import { anchorAt } from './vet'
+import { anchorAt, engineFinding } from './vet'
 import type { VetFinding } from './vet'
 import { cmpCodePoint } from './keyorder'
 import { Provenance } from './provenance'
@@ -87,9 +87,6 @@ export function pathParts(path: string): string[] {
 }
 
 
-// The queried path, normalised the way anchorAt reads it — so a
-// finding names `$.a.b` whether the caller wrote that, `a.b` or
-// `$.a.b.` — and `$` for the root.
 function pathText(path: string): string {
   const parts = pathParts(path)
   return '$' + (0 < parts.length ? '.' + parts.join('.') : '')
@@ -170,9 +167,10 @@ function finding(
 }
 
 
-export function evalFailure(ctx: any): VetFinding {
-  const err: any = ctx.err[0]
-  return finding(err.why, '$', err.msg)
+// A document that does not stand up, reported at the root: a literal
+// nil adds nothing to `ctx.err`, so `failed` carries the only code.
+export function evalFailure(ctx: any, failed?: any): VetFinding {
+  return engineFinding(ctx.err[0] ?? failed, ctx, '$')
 }
 
 
@@ -216,7 +214,7 @@ export function get(
   const root: any = aontu.unify(src, parseOpts, ctx)
 
   if (0 < ctx.err.length || null == root || true === root.isNil) {
-    return { ok: false, out: '', findings: [evalFailure(ctx)] }
+    return { ok: false, out: '', findings: [evalFailure(ctx, root)] }
   }
 
   const node: any = anchorAt(root, path)
@@ -232,10 +230,7 @@ export function get(
       return {
         ok: false,
         out: '',
-        findings: [finding(
-          err?.why ?? 'no_gen',
-          pathText(path),
-          err?.msg ?? 'The value at this path is not concrete.')],
+        findings: [engineFinding(err, ctx, pathText(path))],
       }
     }
     return { ok: true, out: exactJSON(gen, 2), findings: [] }
@@ -274,7 +269,7 @@ export function why(
 
   const root: any = aontu.unify(parsed, parseOpts, ctx)
   if (0 < ctx.err.length || null == root || true === root.isNil) {
-    return { ok: false, findings: [evalFailure(ctx)] }
+    return { ok: false, findings: [evalFailure(ctx, root)] }
   }
 
   const node: any = anchorAt(root, path)

package/src/tsconfig.json

@@ -18,6 +18,7 @@
     "types": [
       "node"
     ],
-    "composite": true
+    "composite": true,
+    "tsBuildInfoFile": "../.tsbuild/src.tsbuildinfo"
   }
 }

package/src/vet.ts

@@ -10,6 +10,7 @@ import {
 } from 'node:path'
 
 import { descErr, getHint } from './err'
+import { codeClass } from './hints'
 import { ConjunctVal } from './val/ConjunctVal'
 import { walkVals, collectNils } from './walk'
 import { sizingResidue } from './val/BagVal'
@@ -204,6 +205,9 @@ function materialise(nil: any, ctx: any): void {
 }
 
 
+const UNSHAPED = 'unify_failed'
+
+
 // The terminal colour escapes the parser puts in its message text. A
 // RegExp built from a string, not a literal: the escape is a control
 // character, and spelling it `\u001b` keeps the source readable.
@@ -214,16 +218,10 @@ function stripAnsi(s: string): string {
 }
 
 
-function findingOf(nil: any, prov: Prov): VetFinding {
+// The registry's hint and a code's own `details` fields: the same set
+// on every finding reporting an ENGINE code.
+function fromRegistry(finding: VetFinding, nil: any): VetFinding {
   const details = nil.details ?? {}
-  const finding: VetFinding = {
-    code: nil.why,
-    class: nil.class,
-    severity: 'error',
-    path: pathText(nil.path),
-    message: stripAnsi(nil.msg.split('\n')[0]),
-    sites: sitesOf(nil, prov),
-  }
 
   const hint = getHint(nil.why, nil.details)
   if (null != hint && '' !== hint) {
@@ -244,6 +242,18 @@ function findingOf(nil: any, prov: Prov): VetFinding {
 }
 
 
+function findingOf(nil: any, prov: Prov): VetFinding {
+  return fromRegistry({
+    code: nil.why,
+    class: nil.class,
+    severity: 'error',
+    path: pathText(nil.path),
+    message: stripAnsi(nil.msg.split('\n')[0]),
+    sites: sitesOf(nil, prov),
+  }, nil)
+}
+
+
 const ORDER_PAD = 9
 
 
@@ -265,6 +275,34 @@ function orderKey(f: VetFinding, index: number): string {
 }
 
 
+// An ENGINE code at a path the caller names: class from the registry
+// through NilVal.class, message materialised first (a `gen` nil has none).
+export function engineFinding(
+  nil: any, ctx: any, path: string): VetFinding {
+  if (null == nil) {
+    return {
+      code: UNSHAPED,
+      class: codeClass(UNSHAPED),
+      severity: 'error',
+      path,
+      message: 'The document does not evaluate.',
+      sites: [],
+    }
+  }
+
+  materialise(nil, ctx)
+
+  return fromRegistry({
+    code: nil.why,
+    class: nil.class,
+    severity: 'error',
+    path,
+    message: stripAnsi(nil.msg.split('\n')[0]),
+    sites: [],
+  }, nil)
+}
+
+
 export function failureFinding(
   ctx: any, url?: string, failed?: any): VetFinding {
   const nil: any = ctx.err[0] ?? failed

package/src/view.ts

@@ -4,7 +4,7 @@
 import { basename, dirname, isAbsolute, relative, resolve } from 'node:path'
 
 import { Aontu } from './aontu'
-import { failureFinding, anchorAt, throughResidue } from './vet'
+import { failureFinding, engineFinding, anchorAt, throughResidue } from './vet'
 import type { VetFinding } from './vet'
 import type { TrustOptions } from './type'
 import { graphOf } from './graph'
@@ -2544,10 +2544,8 @@ function drawLoaded(
       const before = ctx.err.length
       value = root.gen(ctx)
       if (before < ctx.err.length) {
-        const err: any = ctx.err[before]
         return {
-          errors: [finding(err?.why ?? 'unify_failed', 'reference', '$',
-            err?.msg ?? 'The document does not generate.')],
+          errors: [engineFinding(ctx.err[before], ctx, '$')],
         }
       }
     }
@@ -2749,11 +2747,9 @@ export function viewSet(
   const before = ctx.err.length
   const value = root.gen(ctx)
   if (before < ctx.err.length) {
-    const err: any = ctx.err[before]
     return {
       verdict: 'error', views: [],
-      errors: [finding(err?.why ?? 'unify_failed', 'reference', '$',
-        err?.msg ?? 'The document does not generate.')],
+      errors: [engineFinding(ctx.err[before], ctx, '$')],
     }
   }
   const declared = genAt(value, at)