aontu 0.57.0 → 0.59.0

package/src/cli.ts

@@ -23,7 +23,12 @@ import {
   exactJSON, vet, subsume, trimCheck, relationCheck,
   hcanon, canonHash,
   get, why, patch, agentsMd,
+  render,
+  renderProfile,
 } from './aontu'
+import type { RenderCoverage, RenderReport } from './render'
+import { desugarTemplate, resugarTemplate, markerFor } from './template'
+import { outsideRoot } from './mcp'
 import { sarifReport } from './report-sarif'
 import { main as lspMain } from './lsp-server'
 import { main as mcpMain } from './mcp-server'
@@ -68,6 +73,10 @@ const HELP = `Usage: aontu [options] [file]
        aontu view <kind> [options] <file>...
        aontu view --views <path> [--check] [options] <file>
        aontu jsonschema [--at <path>] [--strict] [options] <file>
+       aontu render [--at <path>] [--profile <file>]... [--unit <path>]
+                    [--stdout | --out <dir> | --check <dir> | --coverage]
+                    [--coverage-at <path>] [--strict] <file>
+       aontu template [--resugar] [--check] [--marker <token>] <file>
        aontu hash [options] <file>
        aontu mod tidy|verify|vendor|manifest [options] [dir]
        aontu get <path> [options] <file>
@@ -78,7 +87,7 @@ const HELP = `Usage: aontu [options] [file]
        aontu lsp
        aontu mcp [--root <dir>]
 
-Evaluate an Aontu source file and print the result as JSON.
+Evaluate an aontu source file and print the result as JSON.
 With no file on an interactive terminal, start a REPL.
 With no file and piped input, read the source from stdin.
 
@@ -260,6 +269,51 @@ View exit codes: 0 rendered, 1 --check mismatch or lossy under
 --strict, 2 usage or --max-rows exceeded, 4 the document does not stand
 up on its own, or a relation, root or path that names nothing.
 
+Render options:
+  --at <path>       Render the value at this path ($.a.b); the root by
+                    default
+  --profile <file>  A profile document, profile: {lang, ...}, vetted
+                    against aontu:profile; repeatable, one per language
+  --unit <path>     Render only the unit with this path
+  --stdout          One unit's bytes and nothing else (with --unit when
+                    the instance has several)
+  --out <dir>       Write every unit below dir, or nothing; never deletes
+  --check <dir>     Compare every unit with dir/<path>; drift is listed
+  --coverage        Report what the render read and what it did not:
+                    model paths no output consumed, and rendered
+                    declarations no rule produced. Writes nothing
+  --coverage-at <p> Measure coverage under this path only, instead of
+                    the document root
+  --strict          Refuse the opaque escapes (a text declaration, a raw
+                    block)
+  --format <f>      text (default) or json, the whole report; json
+                    carries the dispatch trace, one entry per emitted
+                    piece
+
+Render exit codes: 0 rendered, 1 lossy under --strict or drift under
+--check, 2 usage or I/O (a refused unit path included), 4 the document
+does not stand up or the instance is not aontu:code.
+
+A render entry file whose extension is not .aon is a TEMPLATE: a
+generator in the target's own syntax, whose marker lines carry aontu
+and whose other lines are output. It is desugared before it is
+evaluated, and --marker names the marker for a language the table does
+not know.
+
+Template options:
+  --resugar       The file is the canonical aontu; print the template
+                  form instead of reading one
+  --check         Desugar and resugar, and exit 1 if the file is not
+                  what the round trip answers
+  --marker <t>    The marker, when the extension does not name it
+                  (default //-, and #- --- /*- by extension)
+
+The template verb prints the canonical aontu form of a generator
+written in the target's own syntax: a marked line is aontu source, and
+every other line is a line of output.
+
+Template exit codes: 0 written, 1 --check drift, 2 usage or I/O.
+
 Set options:
   --entry <file>    The document the change is checked against
   --overlay <file>  The file the change is appended to (created if
@@ -549,7 +603,17 @@ function runFile(file: string, mode: Mode, trust: TrustArg): number {
   }
 
   const path = resolve(file)
-  const aontu = new Aontu({ path, ...trustOpts(trust, dirname(path)) })
+  // `fs` IS WHAT MAKES A FRAME EXCERPT THE FILE IT NAMES. Without it,
+  // err.ts's resolveSrc falls back to the ENTRY text, so a frame whose
+  // arrow says `lib/types.aon:2:6` printed the entry's line 2 under it
+  // -- a real file name over another file's line, which
+  // docs/reference-api.md forbids in the same words it uses to require
+  // the name.
+  const aontu = new Aontu({
+    path,
+    errfs: { existsSync, readFileSync },
+    ...trustOpts(trust, dirname(path)),
+  })
   const res = evalSource(aontu, src, mode)
   ;(res.ok ? process.stdout : process.stderr).write(res.text + '\n')
   return res.ok ? 0 : 1
@@ -729,7 +793,7 @@ function runRepl(initialMode: Mode, jsonl: boolean, trust: TrustArg): void {
 
   if (!jsonl) {
     process.stdout.write(
-      `Aontu v${version()} REPL — :help for commands, :quit to exit\n`)
+      `aontu v${version()} REPL — :help for commands, :quit to exit\n`)
   }
   rl.prompt()
 
@@ -2857,6 +2921,439 @@ function runJsonSchema(argv: string[]): number {
     strict && 'lossy' === report.verdict ? 1 : 0
 }
 
+// ---------------------------------------------------------------------
+// THE RENDER VERB (docs/design/RENDER.0.md D8): evaluate a document,
+// vet the value at --at against aontu:code, fold code.units into bytes,
+// and put them where the flag says -- one unit on stdout, every unit
+// below --out (all or nothing), or compared against --check. Exit codes
+// mirror jsonschema's: 0 ok; 1 lossy under --strict or drift under
+// --check; 2 usage or I/O, a refused unit path included; 4 the
+// document does not stand up or the instance is not aontu:code.
+
+const RENDER_HELP =
+  'aontu render [--at <path>] [--profile <file>]... [--unit <path>] ' +
+  '[--stdout | --out <dir> | --check <dir> | --coverage] ' +
+  '[--coverage-at <path>] [--strict] [--marker <token>] <file> (try --help)'
+
+function runRender(argv: string[]): number {
+  const trusted = takeTrust(argv)
+  if (null == trusted) {
+    return 2
+  }
+  argv = trusted.argv
+  const trust = trusted.trust
+  const files: string[] = []
+  const profileFiles: string[] = []
+  let format: SubsumeFormat = 'text'
+  let at: string | undefined = undefined
+  let unit: string | undefined = undefined
+  let out: string | undefined = undefined
+  let check: string | undefined = undefined
+  let toStdout = false
+  let strict = false
+  let coverage = false
+  let coverageAt: string | undefined = undefined
+  let marker: string | undefined = undefined
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if ('-h' === arg || '--help' === arg) {
+      process.stdout.write(HELP)
+      return 0
+    }
+    if ('--format' === arg) {
+      const f = argv[++i]
+      if ('text' !== f && 'json' !== f) {
+        process.stderr.write('aontu: --format needs text or json\n')
+        return 2
+      }
+      format = f
+    }
+    else if ('--at' === arg) {
+      at = argv[++i]
+      if (null == at) {
+        process.stderr.write('aontu: --at needs a path\n')
+        return 2
+      }
+    }
+    else if ('--unit' === arg) {
+      unit = argv[++i]
+      if (null == unit) {
+        process.stderr.write('aontu: --unit needs a unit path\n')
+        return 2
+      }
+    }
+    else if ('--profile' === arg) {
+      const pf = argv[++i]
+      if (null == pf) {
+        process.stderr.write('aontu: --profile needs a file\n')
+        return 2
+      }
+      profileFiles.push(pf)
+    }
+    else if ('--out' === arg) {
+      out = argv[++i]
+      if (null == out) {
+        process.stderr.write('aontu: --out needs a directory\n')
+        return 2
+      }
+    }
+    else if ('--check' === arg) {
+      check = argv[++i]
+      if (null == check) {
+        process.stderr.write('aontu: --check needs a directory\n')
+        return 2
+      }
+    }
+    else if ('--stdout' === arg) {
+      toStdout = true
+    }
+    else if ('--coverage' === arg) {
+      coverage = true
+    }
+    else if ('--marker' === arg) {
+      marker = argv[++i]
+      if (null == marker) {
+        process.stderr.write('aontu: --marker needs a token\n')
+        return 2
+      }
+    }
+    else if ('--coverage-at' === arg) {
+      coverageAt = argv[++i]
+      if (null == coverageAt) {
+        process.stderr.write('aontu: --coverage-at needs a path\n')
+        return 2
+      }
+    }
+    else if ('--strict' === arg) {
+      strict = true
+    }
+    else if (arg.startsWith('-')) {
+      process.stderr.write(
+        `aontu: unknown render option ${arg} (try --help)\n`)
+      return 2
+    }
+    else {
+      files.push(arg)
+    }
+  }
+
+  if (1 !== files.length) {
+    process.stderr.write(`aontu: render needs one file\n${RENDER_HELP}\n`)
+    return 2
+  }
+  const modes = [toStdout, undefined !== out, undefined !== check, coverage]
+    .filter((on) => on).length
+  if (1 < modes) {
+    process.stderr.write(
+      'aontu: render takes one of --stdout, --out, --check or --coverage\n')
+    return 2
+  }
+  // A NARROWER MEASURE NEEDS SOMETHING TO NARROW. `--coverage-at`
+  // without `--coverage` asks for a report the run does not compute,
+  // and answering silently would be the wrong half of the request.
+  if (undefined !== coverageAt && !coverage) {
+    process.stderr.write('aontu: --coverage-at needs --coverage\n')
+    return 2
+  }
+
+  let src: string
+  try {
+    src = readFileSync(files[0], 'utf8')
+  }
+  catch (err: any) {
+    process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`)
+    return 2
+  }
+
+  // THE ENTRY MAY BE A TEMPLATE (TEMPLATE.0.md; P8), and its EXTENSION
+  // decides, as an include's extension decides what the include is
+  // (ADR-012): a generator is a file in the target's own syntax, so it
+  // carries the target's extension and never `.aon`. Desugared here
+  // rather than anywhere deeper, because a template is an entry
+  // spelling and not a value: an include is still aontu.
+  if (!files[0].endsWith('.aon')) {
+    src = desugarTemplate(src, marker ?? markerFor(files[0]))
+  }
+
+  // THE PROFILES (D5): each --profile file is a document whose root is
+  // `profile: {lang, ...}`, evaluated under the verb's trust and vetted
+  // against aontu:profile as a settled value before the fold reads it
+  // (renderProfile, which also fills the defaults). Two files claiming
+  // one lang is a usage error: the fold could not choose.
+  const profiles: any[] = []
+  const langs = new Map<string, string>()
+  for (const pf of profileFiles) {
+    let text: string
+    try {
+      text = readFileSync(pf, 'utf8')
+    }
+    catch (err: any) {
+      process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`)
+      return 2
+    }
+    const loaded = renderProfile(text,
+      { path: resolve(pf), ...verbOpts(trust, entryRootOf(pf)) })
+    if (undefined !== loaded.errors) {
+      process.stderr.write(loaded.errors.map(renderFinding).join('\n') + '\n')
+      return 4
+    }
+    const profile = loaded.profile
+    const prev = langs.get(profile.lang)
+    if (undefined !== prev) {
+      process.stderr.write(
+        `aontu: two profiles claim ${profile.lang}: ${prev} and ${pf}\n`)
+      return 2
+    }
+    langs.set(profile.lang, pf)
+    profiles.push(profile)
+  }
+
+  const report = render(src, {
+    at, unit, strict, profiles, path: files[0],
+    coverage, coverageAt,
+    // THE JSON REPORT CARRIES THE TRACE (D9), which is what the shape
+    // there has always said; a text run computes it only when the
+    // coverage report needs it.
+    trace: 'json' === format,
+    ...verbOpts(trust, entryRootOf(files[0])),
+  })
+
+  if ('json' === format) {
+    process.stdout.write(exactJSON({
+      aontu: { version: version(), verb: 'render' },
+      verdict: report.verdict,
+      units: report.units,
+      lossy: report.lossy,
+      ...(null == report.errors ? {} : { errors: report.errors }),
+      ...(null == report.trace ? {} : { trace: report.trace }),
+      ...(null == report.coverage ? {} : { coverage: report.coverage }),
+    }, 2) + '\n')
+    return renderExit(report, 0)
+  }
+  if ('error' === report.verdict) {
+    process.stderr.write(
+      (report.errors as VetFinding[]).map(renderFinding).join('\n') + '\n')
+    return renderExit(report, 0)
+  }
+
+  let drift = 0
+  if (toStdout) {
+    // ONE UNIT'S BYTES AND NOTHING ELSE, so the output can be piped
+    // into a formatter or a file.
+    if (1 !== report.units.length) {
+      process.stderr.write(
+        'aontu: --stdout needs exactly one unit, and the instance has ' +
+        `${report.units.length}; --unit names one\n`)
+      return 2
+    }
+    process.stdout.write(report.units[0].text)
+  }
+  else if (undefined !== out) {
+    // EVERY UNIT BELOW <dir>, OR NOTHING: every unit rendered first
+    // (the report above), and no file touched unless all did. The
+    // directory is realpath-confined; a unit path is already a relative
+    // descent (render_path refuses the rest), and the check here is
+    // against the symlink inside it. render never deletes.
+    for (const u of report.units) {
+      if (outsideRoot(out, resolve(out, u.path))) {
+        process.stderr.write(`aontu: ${u.path} escapes ${out}\n`)
+        return 2
+      }
+    }
+    for (const u of report.units) {
+      const full = resolve(out, u.path)
+      try {
+        mkdirSync(dirname(full), { recursive: true })
+        writeFileSync(full, u.text, 'utf8')
+      }
+      catch (err: any) {
+        process.stderr.write(`aontu: cannot write ${u.path}: ${err.message}\n`)
+        return 2
+      }
+      process.stderr.write(`wrote ${u.path}\n`)
+    }
+  }
+  else if (undefined !== check) {
+    // RENDER AND COMPARE: a unit whose bytes differ from the file at
+    // <dir>/<path>, or whose file is absent, is drift, listed by path.
+    // The CI form.
+    for (const u of report.units) {
+      let have: string | undefined = undefined
+      try {
+        have = readFileSync(resolve(check, u.path), 'utf8')
+      }
+      catch {
+        // Absent is drift, reported below.
+      }
+      if (undefined === have) {
+        drift++
+        process.stderr.write(`aontu: ${u.path} is missing from ${check}\n`)
+      }
+      else if (have !== u.text) {
+        drift++
+        process.stderr.write(`aontu: ${u.path} differs from the rendered unit\n`)
+      }
+    }
+  }
+  else if (coverage) {
+    // THE COVERAGE REPORT (P7), one line per finding and a count at
+    // the end: dead model first, then the declarations no rule
+    // produced. A clean report is the count line alone.
+    const cov = report.coverage as RenderCoverage
+    for (const d of cov.dead) {
+      process.stdout.write(`dead: ${d}\n`)
+    }
+    for (const u of cov.unruled) {
+      process.stdout.write(`unruled: ${u.unit} ${u.path}\n`)
+    }
+    process.stdout.write(
+      `coverage: ${cov.read.length} path(s) read, ${cov.dead.length} ` +
+      `no output consumed, ${cov.unruled.length} declaration(s) ` +
+      'no rule produced\n')
+  }
+  else {
+    // THE SUMMARY: one line per unit -- its path, its language and its
+    // size -- since several units have no one text to print.
+    for (const u of report.units) {
+      process.stdout.write(`${u.path}\t${u.lang}\t${u.text.length} bytes\n`)
+    }
+  }
+  for (const l of report.lossy) {
+    process.stderr.write(
+      `lossy: ${l.unit} ${l.path} tier ${l.tier} ${l.construct}: ${l.reason}\n`)
+  }
+  return renderExit(report, drift)
+}
+
+// D8's exit table over a report: a refused unit path is usage (2), a
+// strict refusal is lossy (1), any other error is the document's (4);
+// drift under --check is 1.
+function renderExit(report: RenderReport, drift: number): number {
+  if ('error' === report.verdict) {
+    const errors = report.errors as VetFinding[]
+    if (errors.every((f) => 'render_path' === f.code)) {
+      return 2
+    }
+    if (errors.every((f) => 'render_strict' === f.code)) {
+      return 1
+    }
+    return 4
+  }
+  return 0 < drift ? 1 : 0
+}
+
+
+// ---------------------------------------------------------------------
+// THE TEMPLATE SURFACE (docs/design/TEMPLATE.0.md; RENDER.0.md P8): the
+// two transforms and the round trip between them. `render` reads a
+// template directly, by its extension; this verb is for seeing the
+// canonical form, for writing one by hand and sugaring it, and for the
+// check that keeps a committed template and its meaning in agreement.
+
+const TEMPLATE_HELP =
+  'aontu template [--resugar] [--check] [--marker <token>] <file> (try --help)'
+
+function runTemplate(argv: string[]): number {
+  const files: string[] = []
+  let resugar = false
+  let check = false
+  let marker: string | undefined = undefined
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i]
+    if ('-h' === arg || '--help' === arg) {
+      process.stdout.write(HELP)
+      return 0
+    }
+    else if ('--resugar' === arg) {
+      resugar = true
+    }
+    else if ('--check' === arg) {
+      check = true
+    }
+    else if ('--marker' === arg) {
+      marker = argv[++i]
+      if (null == marker) {
+        process.stderr.write('aontu: --marker needs a token\n')
+        return 2
+      }
+    }
+    else if (arg.startsWith('-')) {
+      process.stderr.write(
+        `aontu: unknown template option ${arg} (try --help)\n`)
+      return 2
+    }
+    else {
+      files.push(arg)
+    }
+  }
+
+  if (1 !== files.length) {
+    process.stderr.write(`aontu: template needs one file\n${TEMPLATE_HELP}\n`)
+    return 2
+  }
+  // THE TWO ARE DIRECTIONS, NOT MODES THAT COMPOSE: `--check` reads a
+  // template and asks whether the round trip answers it back, and
+  // `--resugar` reads the canonical form instead. A run cannot be both
+  // at once, because the file is one thing or the other.
+  if (resugar && check) {
+    process.stderr.write(
+      'aontu: template takes one of --resugar or --check\n')
+    return 2
+  }
+
+  let src: string
+  try {
+    src = readFileSync(files[0], 'utf8')
+  }
+  catch (err: any) {
+    process.stderr.write(`aontu: cannot read ${err.path}: ${err.message}\n`)
+    return 2
+  }
+
+  const mark = marker ?? markerFor(files[0])
+
+  if (check) {
+    // THE ROUND TRIP IS THE CHECK (D6): the file held to the spelling
+    // the two transforms answer. What that names is a marker line the
+    // transform would not have written -- one without its space, or one
+    // whose aontu is indented after the marker rather than before it,
+    // since the marker keeps its own indentation. It does NOT name a
+    // changed body line: a template's whitespace is output, so a
+    // trimmed trailing space is still a valid template and it is
+    // `render --check` against the committed files that catches it.
+    // The first line that differs is the report, since a whole diff of
+    // a generator is the file again.
+    const back = resugarTemplate(desugarTemplate(src, mark), mark)
+    if (back === src) {
+      return 0
+    }
+    const want = back.split('\n')
+    const have = src.split('\n')
+    let n = 0
+    while (n < want.length && n < have.length && want[n] === have[n]) {
+      n++
+    }
+    // THE TWO ARE THE SAME LENGTH, always: each transform maps one
+    // line to one line and applies the same trailing-newline rule, so
+    // `back` has as many lines as `src`. The loop above therefore stops
+    // at a real difference rather than by running out of either -- an
+    // equal prefix all the way to the end IS `back === src`, which
+    // returned above. So both indexes are in range here.
+    process.stderr.write(
+      `aontu: ${files[0]}:${n + 1} is not what the round trip answers\n` +
+      `  have: ${JSON.stringify(have[n])}\n` +
+      `  want: ${JSON.stringify(want[n])}\n`)
+    return 1
+  }
+
+  process.stdout.write(resugar ?
+    resugarTemplate(src, mark) : desugarTemplate(src, mark))
+  return 0
+}
+
+
 // ---------------------------------------------------------------------
 // The canon-hash (G6 phase 1): the pin an agent, a lockfile or a
 // registry stores for "this module, this meaning". The hash covers the
@@ -3521,6 +4018,23 @@ function runFmt(argv: string[]): number | Promise<number> {
 
   let worst = 0
   for (const file of files) {
+    // FMT FORMATS AONTU SOURCE, AND THE EXTENSION SAYS WHAT A FILE IS
+    // (ADR-012's rule, and the one `render` reads a template by).
+    // A TEMPLATE FILE IS NOT AONTU (docs/design/TEMPLATE.0.md; P8):
+    // its marker lines are fragments of a document and its other lines
+    // are the target's, so there is nothing here to format that would
+    // not also rewrite the output. Refused rather than attempted, and
+    // refused BY NAME rather than by a parse failure, because a `#-`
+    // template parses: `#` opens a comment, so every marker line
+    // vanishes and what is left is read as a document that was never
+    // written. The verb answered `0` over one, having understood none
+    // of it.
+    if (!/[.](aon|aontu)$/.test(file)) {
+      process.stderr.write(
+        `aontu: ${file} is not aontu source (.aon, .aontu); a generator ` +
+        'written in the target\'s own syntax is aontu template\'s\n')
+      return 2
+    }
     let src: string
     try {
       src = readFileSync(file, 'utf8')
@@ -3734,6 +4248,14 @@ function main(argv: string[], servers: Servers = SERVERS): void {
     return finish(runJsonSchema(argv.slice(3)))
   }
 
+  if ('render' === argv[2]) {
+    return finish(runRender(argv.slice(3)))
+  }
+
+  if ('template' === argv[2]) {
+    return finish(runTemplate(argv.slice(3)))
+  }
+
   if ('reaches' === argv[2]) {
     return finish(runReaches(argv.slice(3)))
   }
@@ -3840,7 +4362,7 @@ function main(argv: string[], servers: Servers = SERVERS): void {
   else {
     runStdin(mode, trust).then((code) => finish(code))
   }
-} /* node:coverage ignore next 16 */
+} /* node:coverage ignore next 18 */
 
 
 // No require.main guard here: bin/aontu.js is the executable entry and
@@ -3852,6 +4374,8 @@ export {
   runReaches,
   runView,
   runJsonSchema,
+  runRender,
+  runTemplate,
   runMod,
   runHash, runGet,
   runWhy, renderWhyText, runSet, runAgentsMd, runFmt,

package/src/ctx.ts

@@ -26,7 +26,16 @@ type AontuContextConfig = {
   // uninstrumented run. Shared by reference down every descend, as the
   // error list is, so one run has one record.
   prov?: any
+
+  // THE READ SET (RENDER.0.md P7), or absent for an uninstrumented
+  // run: every tree path a reference resolved to, in one shared set.
+  // It is what `render --coverage` measures the model against -- a
+  // path no read reached is model the transform never consumed -- and
+  // its presence is also what switches the two render riders on
+  // (Val.origin, Val.emitted), so one flag turns the whole record on.
+  reads?: Set<string>
   fs?: any
+  errfs?: any
   path?: string[]
   root?: Val
   seen?: Record<string, number>
@@ -69,6 +78,8 @@ class AontuContext {
   vars: Record<string, Val> = {}
   src?: string
   fs?: FST
+  // The error renderer's own reader; see type.ts's `errfs`.
+  errfs?: FST
 
   seenI: number
   seen: Record<string, number>
@@ -94,6 +105,10 @@ class AontuContext {
   // context through the prototype chain, so one run has one record.
   prov?: any
 
+  // The read set (RENDER.0.md P7), or undefined for an uninstrumented
+  // run. Inherited exactly as `prov` is.
+  reads?: Set<string>
+
   // errlist: Omit<NilVal[], "push">  // Nil error log of current unify.
   err: any[]
   explain: any[] | null
@@ -181,11 +196,13 @@ class AontuContext {
 
     this.collect = cfg.collect ?? null != cfg.err
     this.prov = cfg.prov
+    this.reads = cfg.reads
 
     this.err = cfg.err ?? []
     this.explain = Array.isArray(cfg.explain) ? cfg.explain : null
 
     this.fs = cfg.fs ?? null
+    this.errfs = cfg.errfs ?? null
 
     // Multiple unify passes will keep incrementing Val counter.
     this.vc = null == cfg.vc ? 1_000_000_000 : cfg.vc
@@ -307,6 +324,7 @@ class AontuContext {
     this.err = this.opts.err ?? this.err
     this.deps = this.opts.deps ?? this.deps
     this.fs = this.opts.fs ?? this.fs
+    this.errfs = (this.opts as any).errfs ?? this.errfs
     this.explain = this.opts.explain ?? this.explain
 
     this.src = ('string' === typeof this.opts.src ? this.opts.src : undefined) ?? this.src

package/src/err.ts

@@ -208,9 +208,12 @@ function resolveSrc(v: Val, errctx: ErrContext | undefined) {
     }
     else {
       try {
-        const fileExists = errctx?.fs?.existsSync(url)
+        // errfs first: the CLI gives the renderer a reader without
+        // giving the resolver one (type.ts, `errfs`).
+        const reader = errctx?.errfs ?? errctx?.fs
+        const fileExists = reader?.existsSync(url)
         if (fileExists) {
-          src = errctx?.fs?.readFileSync(url, 'utf8') ?? undefined
+          src = reader?.readFileSync(url, 'utf8') ?? undefined
         }
       }
       catch (fe: any) {
@@ -228,7 +231,7 @@ function resolveSrc(v: Val, errctx: ErrContext | undefined) {
     }
     else if (errctx) {
       src = 'SOURCE-NOT-FOUND:' + (null != url ? (' ' + url) : '') +
-        (null == errctx?.fs ? ' (NO-FS)' : '')
+        (null == (errctx?.errfs ?? errctx?.fs) ? ' (NO-FS)' : '')
     }
   }