@nifrajs/cli 3.3.0 → 4.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nifrajs/cli",
-  "version": "3.3.0",
+  "version": "4.0.0",
   "description": "The nifra CLI - zero-config dev/build/start for a nifra app (`nifra dev`, `nifra build`, `nifra start`).",
   "keywords": [
     "bun",
@@ -17,6 +17,9 @@
     "dev-server"
   ],
   "type": "module",
+  "nifra": {
+    "environment": "backend"
+  },
   "bin": {
     "nifra": "./dist/cli.js"
   },
@@ -66,14 +69,17 @@
     "access": "public"
   },
   "dependencies": {
-    "@nifrajs/client": "3.3.0",
-    "@nifrajs/core": "3.3.0",
-    "@nifrajs/mcp": "3.3.0",
-    "@nifrajs/runner": "3.3.0",
-    "@nifrajs/schema": "3.3.0",
-    "@nifrajs/testing": "3.3.0",
-    "@nifrajs/web": "3.3.0",
-    "create-nifra": "3.3.0"
+    "@nifrajs/client": "4.0.0",
+    "@nifrajs/core": "4.0.0",
+    "@nifrajs/agent-review": "4.0.0",
+    "@nifrajs/i18n": "4.0.0",
+    "@nifrajs/mcp": "4.0.0",
+    "@nifrajs/mcp-db": "4.0.0",
+    "@nifrajs/runner": "4.0.0",
+    "@nifrajs/schema": "4.0.0",
+    "@nifrajs/testing": "4.0.0",
+    "@nifrajs/web": "4.0.0",
+    "create-nifra": "4.0.0"
   },
   "repository": {
     "type": "git",
@@ -85,7 +91,7 @@
   },
   "homepage": "https://github.com/nifrajs/nifra#readme",
   "peerDependencies": {
-    "typescript": "^5.0.0 || ^6.0.0"
+    "typescript": "^5.0.0 || ^6.0.0 || ^7.0.0"
   },
   "peerDependenciesMeta": {
     "typescript": {
@@ -93,6 +99,8 @@
     }
   },
   "devDependencies": {
-    "typescript": "^6.0.3"
+    "typescript": "^6.0.3",
+    "typescript5": "npm:typescript@5.9.3",
+    "typescript7": "npm:typescript@7.0.2"
   }
 }

package/src/app-files.ts

@@ -0,0 +1,40 @@
+/**
+ * Where an app's own entry files live, in one place for every command.
+ *
+ * - `nifra.config.ts` - the CLI's config (dev/build tooling); only the CLI imports it.
+ * - `backend/framework.ts` - the render adapter and the options the generated server entry imports,
+ *   kept free of build tooling because it is bundled into every server build.
+ * - `backend/app.ts` - exports `backend`, the app's API (a `@nifrajs/core` server). Optional.
+ */
+import { existsSync } from "node:fs"
+import { resolve } from "node:path"
+
+export const CONFIG_FILE = "nifra.config.ts"
+export const FRAMEWORK_FILE = "backend/framework.ts"
+export const BACKEND_APP_FILE = "backend/app.ts"
+
+/** The root files this layout retired, and where each lives now. */
+export const RETIRED_ROOT_FILES: Readonly<Record<string, string>> = {
+  "backend.ts": BACKEND_APP_FILE,
+  "framework.ts": FRAMEWORK_FILE,
+}
+
+/** Refuse an app still on the retired root files: run against it, a command would silently miss them. */
+export function assertCurrentLayout(cwd: string): void {
+  const retired = Object.entries(RETIRED_ROOT_FILES).filter(([file]) =>
+    existsSync(resolve(cwd, file)),
+  )
+  if (retired.length === 0) return
+  const moves = retired.map(([from, to]) => `${from} -> ${to}`).join(", ")
+  throw new Error(
+    `[nifra] this app uses the retired root layout (${moves}). Run \`nifra migrate layout\` to see the ` +
+      "move (it also splits each route into x.tsx and x.backend.ts), then `nifra migrate layout --write`.",
+  )
+}
+
+/** The file the generated server entry imports the adapter from: `backend/framework.ts` when it exists,
+ * else the config (a single-target app may keep everything in `nifra.config.ts`). */
+export function adapterFile(cwd: string): string {
+  const framework = resolve(cwd, FRAMEWORK_FILE)
+  return existsSync(framework) ? framework : resolve(cwd, CONFIG_FILE)
+}

package/src/assure-hydration.ts

@@ -1,9 +1,8 @@
 import { existsSync, statSync } from "node:fs"
-import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"
+import { copyFile, mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"
 import { tmpdir } from "node:os"
 import { basename, join, resolve } from "node:path"
 import { fileURLToPath, pathToFileURL } from "node:url"
-import { inProcessClient } from "@nifrajs/client"
 import { defineReplayFile } from "@nifrajs/core/replay"
 import { type AppLike, runApp } from "@nifrajs/runner"
 import { createWebApp, type RenderAdapter } from "@nifrajs/web"
@@ -12,6 +11,8 @@ import { discoverRoutes } from "@nifrajs/web/fs"
 import type { BunPlugin } from "bun"
 import { collectDoctorResult } from "./doctor.ts"
 import { loadApp, resolvePlugins } from "./load.ts"
+import { CHILD_OUTPUT_MAX_BYTES, joinHeadTail, readBoundedStream, readHeadTail } from "./mcp-io.ts"
+import { frameworkWebAppOptions } from "./web-app-options.ts"
 
 const HYDRATION_ASSURANCE = Symbol.for("nifra.hydration.assurance")
 const SOURCE_GLOB = "**/*.{ts,tsx,js,jsx,vue,svelte,mdx}"
@@ -176,6 +177,8 @@ async function buildHydrationApp(cwd: string): Promise<BuiltHydrationApp | { ski
     const client = await buildClient({
       routesDir: loaded.routesDir,
       outDir: clientOutput,
+      // The runner imports the entry from disk, where a `/assets/` chunk URL is a filesystem path.
+      publicPath: `${pathToFileURL(clientOutput).href}/`,
       clientModule: loaded.framework.clientModule,
       ...(plugins.length === 0 ? {} : { plugins: plugins as BunPlugin[] }),
       ...(loaded.framework.conditions === undefined
@@ -186,6 +189,9 @@ async function buildHydrationApp(cwd: string): Promise<BuiltHydrationApp | { ski
       ...(loaded.framework.publicEnvPrefix === undefined
         ? {}
         : { publicEnvPrefix: loaded.framework.publicEnvPrefix }),
+      ...(loaded.framework.secretExemptions === undefined
+        ? {}
+        : { secretExemptions: loaded.framework.secretExemptions }),
     })
     if (client.entry.trim() === "" || client.assets.length === 0) {
       await rm(workDir, { recursive: true, force: true })
@@ -200,7 +206,7 @@ async function buildHydrationApp(cwd: string): Promise<BuiltHydrationApp | { ski
       adapter: loaded.framework.adapter as RenderAdapter,
       manifest: discoverRoutes(loaded.routesDir),
       clientEntry: client.entry,
-      ...(loaded.backend === undefined ? {} : { api: inProcessClient(loaded.backend as never) }),
+      ...frameworkWebAppOptions(loaded.framework, loaded.backend),
     }) as unknown as AppLike
     return {
       app: webApp,
@@ -232,21 +238,14 @@ async function sourceFiles(cwd: string): Promise<Array<{ file: string; content:
   return files
 }
 
+/** How long a route may take to mark itself hydrated before the gate fails it. */
+const HYDRATION_TIMEOUT_MS = 5_000
+let entryCopies = 0
+
 function outputPath(outputDir: string, entry: string): string {
   return join(outputDir, basename(entry))
 }
 
-function globalValue(html: string, name: string): unknown {
-  const expression = new RegExp(`window\\.${name}=([\\s\\S]*?)(?:</script>|;window\\.)`)
-  const value = expression.exec(html)?.[1]?.replace(/;$/, "")
-  if (value === undefined) return undefined
-  try {
-    return JSON.parse(value)
-  } catch {
-    return undefined
-  }
-}
-
 async function runDomHydration(
   cwd: string,
   built: BuiltHydrationApp,
@@ -288,11 +287,21 @@ async function runDomHydration(
     else if (name === "cancelAnimationFrame") globals[name] = (id: number) => clearTimeout(id)
     else globals[name] = windowValue[name]
   }
+  // Framework runtimes reach for more DOM globals (Vue's `SVGElement`, `Text`, `Comment`). Lend every
+  // one the runtime does not define itself, so its own `fetch`, `URL` and timers stay in place.
+  for (const name of Object.getOwnPropertyNames(windowValue)) {
+    if (name in globals) continue
+    let value: unknown
+    try {
+      value = windowValue[name]
+    } catch {
+      continue
+    }
+    previous.set(name, undefined)
+    globals[name] =
+      typeof value === "function" && !/^[A-Z]/.test(name) ? value.bind(windowValue) : value
+  }
   const windowRecord = windowValue as Record<string, unknown>
-  windowRecord.__NIFRA_ROUTE__ = globalValue(html, "__NIFRA_ROUTE__")
-  windowRecord.__NIFRA_DATA__ = globalValue(html, "__NIFRA_DATA__")
-  windowRecord.__NIFRA_LAYOUT_DATA__ = globalValue(html, "__NIFRA_LAYOUT_DATA__")
-  windowRecord.__NIFRA_ACTION__ = globalValue(html, "__NIFRA_ACTION__")
   windowRecord.console = console
   const errors: string[] = []
   const recover = (error: unknown, info?: unknown): void => {
@@ -310,7 +319,12 @@ async function runDomHydration(
       documentValue.querySelector as (selector: string) => { innerHTML?: unknown } | null
     )("#root")
     const before = String(beforeRoot?.innerHTML ?? "")
-    const entry = outputPath(built.outputDir, built.client.entry)
+    // Bun evaluates a file module once per path, query or not, so each route imports its own copy.
+    // A fresh directory each time: Bun's resolver caches a directory's listing once it has read it.
+    const copyDir = join(built.outputDir, `route-${++entryCopies}`)
+    await mkdir(copyDir)
+    const entry = join(copyDir, basename(built.client.entry))
+    await copyFile(outputPath(built.outputDir, built.client.entry), entry)
     const originalError = console.error
     const originalWarn = console.warn
     console.error = (...args) => {
@@ -323,10 +337,32 @@ async function runDomHydration(
       if (/hydr|mismatch|server|client|expected|recover/i.test(message)) errors.push(message)
       originalWarn(...args)
     }
+    // A render that throws on the client surfaces from a scheduler task, not from the import.
+    const uncaught = (error: unknown): void => {
+      errors.push(`uncaught: ${error instanceof Error ? error.message : String(error)}`)
+    }
+    process.on("uncaughtException", uncaught)
+    process.on("unhandledRejection", uncaught)
+    let hydrated = false
     try {
-      await import(`${pathToFileURL(entry).href}?nifra-hydration=${encodeURIComponent(path)}`)
-      await new Promise((resolvePromise) => setTimeout(resolvePromise, 0))
+      await import(pathToFileURL(entry).href)
+      // The entry marks <html> once the adapter has mounted the route. `Date.now` is pinned by the
+      // deterministic runtime, so the bound is measured with `performance.now`.
+      const marked = documentValue.documentElement as { hasAttribute(name: string): boolean }
+      const started = performance.now()
+      for (;;) {
+        hydrated = marked.hasAttribute("data-nifra-hydrated")
+        if (hydrated || errors.length > 0 || performance.now() - started >= HYDRATION_TIMEOUT_MS)
+          break
+        await new Promise((resolvePromise) => setTimeout(resolvePromise, 1))
+      }
+      // The framework commits the hydration in its own scheduler tasks after the marker's frame.
+      for (let tick = 0; tick < 10; tick++) {
+        await new Promise((resolvePromise) => setTimeout(resolvePromise, 0))
+      }
     } finally {
+      process.off("uncaughtException", uncaught)
+      process.off("unhandledRejection", uncaught)
       console.error = originalError
       console.warn = originalWarn
     }
@@ -335,6 +371,16 @@ async function runDomHydration(
     )("#root")
     const after = String(afterRoot?.innerHTML ?? "")
     const diagnostics: import("./diagnostics.ts").Diagnostic[] = []
+    if (!hydrated && errors.length === 0) {
+      diagnostics.push(
+        diagnostic(
+          "NF-H001",
+          `client hydration did not complete within ${HYDRATION_TIMEOUT_MS / 1000}s`,
+          undefined,
+          [built.framework],
+        ),
+      )
+    }
     if (errors.length > 0 || before !== after) {
       diagnostics.push(
         diagnostic("NF-H001", "client hydration reported a recoverable mismatch", undefined, [
@@ -555,57 +601,104 @@ async function runHydrationProof(cwd: string, options: HydrationOptions): Promis
   }
 }
 
+/** How long one hydration run may take: it builds the client and renders every route. */
+const HYDRATION_RUN_TIMEOUT_MS = 300_000
+
+/** Bounds on a hydration run beyond its {@link HydrationOptions}. */
+export interface HydrationRunControl {
+  readonly signal?: AbortSignal
+  /** Default 300000 (five minutes). */
+  readonly timeoutMs?: number
+}
+
 /** Run hydration in a fresh process so the project's current client and framework modules are isolated. */
 export async function runHydrationAssurance(
   cwd: string,
   options: HydrationOptions = {},
+  control: HydrationRunControl = {},
 ): Promise<HydrationResult> {
+  const failed = (reason: string): HydrationResult => ({
+    diagnostics: [diagnostic("NF-H001", `hydration runner failed: ${reason}`)],
+  })
+  if (control.signal?.aborted) return failed("cancelled")
   const root = resolve(cwd)
   const entry = fileURLToPath(import.meta.url)
+  // The answer line carries this token, so whatever project code prints cannot be read as the result.
+  const token = crypto.randomUUID()
   const proc = Bun.spawn(
     [process.execPath, entry, root, "--nifra-hydration-child", JSON.stringify(options)],
     {
-      stdin: "ignore",
+      cwd: root,
+      // Explicit: without `env`, Bun passes the environment it started with, missing `--env-file` values.
+      env: process.env,
+      stdin: "pipe",
       stdout: "pipe",
       stderr: "pipe",
     },
   )
-  const [stdout, stderr] = await Promise.all([
-    new Response(proc.stdout).text(),
-    new Response(proc.stderr).text(),
-  ])
-  await proc.exited
+  let stopped: string | undefined
+  const stop = (reason: string): void => {
+    stopped ??= reason
+    proc.kill()
+  }
+  const onAbort = (): void => stop("cancelled")
+  control.signal?.addEventListener("abort", onAbort, { once: true })
+  const timeoutMs = control.timeoutMs ?? HYDRATION_RUN_TIMEOUT_MS
+  const timer = setTimeout(() => stop(`timed out after ${timeoutMs} ms`), timeoutMs)
   try {
-    return JSON.parse(stdout) as HydrationResult
-  } catch {
-    return {
-      diagnostics: [
-        diagnostic(
-          "NF-H001",
-          `hydration runner failed: ${stderr.trim() || stdout.trim() || "no result"}`,
-        ),
-      ],
+    try {
+      proc.stdin.write(`${token}\n`)
+      await proc.stdin.end()
+    } catch {
+      // The child exited before reading its token; its stderr says why.
+    }
+    const [stdout, stderr] = await Promise.all([
+      readBoundedStream(proc.stdout, CHILD_OUTPUT_MAX_BYTES, () =>
+        stop(`output exceeded ${CHILD_OUTPUT_MAX_BYTES} bytes`),
+      ),
+      readHeadTail(proc.stderr, 2048, 2048),
+      proc.exited,
+    ])
+    if (stopped !== undefined) return failed(stopped)
+    const prefix = `${token} `
+    const answer = stdout.text.split("\n").find((line) => line.startsWith(prefix))
+    if (answer !== undefined) {
+      try {
+        return JSON.parse(answer.slice(prefix.length)) as HydrationResult
+      } catch {
+        // A truncated answer line falls through to the stderr report.
+      }
     }
+    return failed(joinHeadTail(stderr).trim() || "no result")
+  } finally {
+    clearTimeout(timer)
+    control.signal?.removeEventListener("abort", onAbort)
   }
 }
 
 if (import.meta.main && process.argv.includes("--nifra-hydration-child")) {
+  // Bound before project code loads, so a `console.log` in a config or loader goes to stderr and
+  // never reaches the answer channel.
+  const stdout = process.stdout.write.bind(process.stdout)
+  const toStderr = (...args: unknown[]): void => {
+    process.stderr.write(`${args.map((arg) => String(arg)).join(" ")}\n`)
+  }
+  console.log = toStderr
+  console.info = toStderr
+  console.debug = toStderr
+  const token = (await readBoundedStream(Bun.stdin.stream(), 256)).text.trim()
   const cwd = process.argv[2] ?? process.cwd()
   const rawOptions = process.argv[4]
+  let result: HydrationResult
   try {
     process.chdir(cwd)
     const options = rawOptions === undefined ? {} : (JSON.parse(rawOptions) as HydrationOptions)
-    const result = await runHydrationProof(cwd, options)
-    await Bun.write(Bun.stdout, JSON.stringify(result))
+    result = await runHydrationProof(cwd, options)
   } catch (error) {
-    await Bun.write(
-      Bun.stdout,
-      JSON.stringify({
-        diagnostics: [
-          diagnostic("NF-H001", error instanceof Error ? error.message : String(error)),
-        ],
-      }),
-    )
+    result = {
+      diagnostics: [diagnostic("NF-H001", error instanceof Error ? error.message : String(error))],
+    }
   }
+  await new Promise<void>((done) => stdout(`${token} ${JSON.stringify(result)}\n`, () => done()))
   process.exit(0)
 }

package/src/assure.ts

@@ -4,6 +4,7 @@ import { existsSync } from "node:fs"
 import { join, resolve } from "node:path"
 import { pathToFileURL } from "node:url"
 import type { AssuranceConfig, AssuranceReport } from "@nifrajs/core/assurance"
+import { CONFIG_FILE, FRAMEWORK_FILE } from "./app-files.ts"
 import type { Diagnostic } from "./diagnostics.ts"
 
 export interface AssureSink {
@@ -92,10 +93,24 @@ export async function loadAssuranceConfig(
 
 export function formatAssuranceReport(report: AssuranceReport): string {
   if (report.ok) {
+    const contracted = report.routes.filter((route) => route.responseContract !== undefined)
+    const enforced = contracted.filter((route) => route.responseContract === "enforce").length
+    const warned = contracted.filter((route) => route.responseContract === "warn").length
+    const unchecked = contracted.filter((route) => route.responseContract === "unchecked").length
+    const runtimeContract =
+      contracted.length === 0
+        ? " No declared response/error schemas were found."
+        : " Runtime response contracts: " +
+          enforced +
+          " enforced, " +
+          warned +
+          " warn-only, " +
+          unchecked +
+          " typed-only."
     const capability = report.capabilities
       ? ` Capability assurance covered ${report.capabilities.routes.length} route${report.capabilities.routes.length === 1 ? "" : "s"}.`
       : ""
-    return `✓ route assurance: ${report.routes.length} route${report.routes.length === 1 ? "" : "s"} classified; all required evidence is present.${capability}`
+    return `✓ route assurance: ${report.routes.length} route${report.routes.length === 1 ? "" : "s"} classified; all required evidence is present.${capability}${runtimeContract}`
   }
   const messages = [
     ...report.findings.map((finding) => finding.message),
@@ -280,7 +295,7 @@ export async function collectAssureBundle(
   })
 
   await addGate("render", async () => {
-    if (!existsSync(join(cwd, "nifra.config.ts")) && !existsSync(join(cwd, "framework.ts")))
+    if (!existsSync(join(cwd, CONFIG_FILE)) && !existsSync(join(cwd, FRAMEWORK_FILE)))
       return { diagnostics: [], skipReason: "no client render target configured" }
     const { renderPages } = await import("./mcp-render.ts")
     const result = await renderPages(cwd, [{ path: "/" }])

package/src/capabilities-tool.ts

@@ -16,11 +16,14 @@ import {
   snapshotCapabilities,
   validCapabilityId,
 } from "@nifrajs/core/capabilities"
-import { reflectRoutes } from "@nifrajs/core/reflection"
+import { expandOptionalParams } from "@nifrajs/core/pattern"
+import { type ReflectedMount, type ReflectedRoute, reflectRoutes } from "@nifrajs/core/reflection"
 import { scanStaticRouteText, stripComments, walkSource } from "./check.ts"
 
+// Import and re-export clauses are spelled out (a default binding, then `* as ns` or a `{ … }` list)
+// rather than scanned lazily, which is quadratic on a long semicolon-free module.
 const EFFECT_IMPORT =
-  /\bimport\s+(?!type\b)(?:[^'"();]*?\bfrom\s+)?["']([^"']+)["']|\bimport\s*\(\s*["']([^"']+)["']\s*\)|\brequire\s*\(\s*["']([^"']+)["']\s*\)|\bexport\s+(?!type\b)[^'";]*?\bfrom\s*["']([^"']+)["']/g
+  /\bimport\s*(?!type\b)(?:(?:[\w$]+\s*,?\s*)?(?:\*\s*(?:as\b\s*[\w$]+\s*)?|\{[^{}'"]*\}\s*)?from\s*)?["']([^"']+)["']|\bimport\s*\(\s*["']([^"']+)["']\s*\)|\brequire\s*\(\s*["']([^"']+)["']\s*\)|\bexport\s*(?!type\b)(?:\*\s*(?:as\b\s*[\w$]+\s*)?|\{[^{}'"]*\}\s*)from\s*["']([^"']+)["']/g
 // `\\` is excluded from both inner classes: letting the class also match a lone backslash makes the
 // `(A*(\\.A*)*)` shape ambiguous, which is exponential on a run of backslashes.
 const TEMPLATE_EFFECT_IMPORT = /\b(?:import|require)\s*\(\s*`([^`$\\]*(?:\\.[^`$\\]*)*)`\s*\)/g
@@ -312,27 +315,44 @@ async function walkRouteModules(
   return { covered, evidence, violations, truncations }
 }
 
+/** The reflected paths a statically collected pattern stands for; a malformed pattern is itself. */
+function staticRouteForms(path: string): readonly string[] {
+  try {
+    return expandOptionalParams(path)
+  } catch {
+    return [path]
+  }
+}
+
 /** Build coverage-qualified static evidence for every reflected route. */
 export async function collectCapabilityProjectReport(
   cwd: string,
   source: unknown,
   policyInput: CapabilityPolicy,
+  options: {
+    readonly routes?: readonly ReflectedRoute[]
+    readonly mounts?: readonly ReflectedMount[]
+  } = {},
 ): Promise<CapabilityProjectReport> {
   const policy = defineCapabilityPolicy(policyInput)
   const sources = await readSources(cwd)
   const automatic = new Map<string, Set<string>>()
   for (const [file, content] of sources) {
     for (const route of scanStaticRouteText(file, content)) {
-      const modules = automatic.get(routeKey(route.method, route.path)) ?? new Set<string>()
-      modules.add(file)
-      automatic.set(routeKey(route.method, route.path), modules)
+      // A path ending in optional params is reflected as one route per form it serves.
+      for (const path of staticRouteForms(route.path)) {
+        const modules = automatic.get(routeKey(route.method, path)) ?? new Set<string>()
+        modules.add(file)
+        automatic.set(routeKey(route.method, path), modules)
+      }
     }
   }
 
   const evidenceRoutes = []
   const violations: CapabilityImportViolation[] = []
   const truncations: CapabilityProvenanceTruncation[] = []
-  for (const route of reflectRoutes(source)) {
+  const reflectedRoutes = options.routes ?? reflectRoutes(source)
+  for (const route of reflectedRoutes) {
     const modules = new Set(automatic.get(routeKey(route.method, route.path)) ?? [])
     for (const association of policy.provenance.routeModules ?? []) {
       if (
@@ -394,7 +414,11 @@ export async function collectCapabilityProjectReport(
     }
   }
 
-  const evaluated = evaluateCapabilityAssurance(source, policy, { routes: evidenceRoutes })
+  const evaluated = evaluateCapabilityAssurance(source, policy, {
+    routes: evidenceRoutes,
+    reflectedRoutes,
+    ...(options.mounts === undefined ? {} : { mounts: options.mounts }),
+  })
   const report: CapabilityAssuranceReport =
     violations.length === 0 && truncations.length === 0 && unmatchedSeams.length === 0
       ? evaluated
@@ -674,9 +698,11 @@ export async function runCapabilityCheck(
         2,
       ),
     )
-  } else if (ok) {
-    console.log("✓ capability assurance and lockfile are current")
   } else {
+    if (ok) console.log("✓ capability assurance and lockfile are current")
+    // Stated on every run, passing or not: a gap is the report's own boundary, not a failure.
+    for (const gap of result.report.gaps ?? [])
+      console.log(`• known gap, not analyzed: ${gap.path} - ${gap.reason}`)
     for (const finding of result.report.findings) console.log(`✖ ${finding.message}`)
     for (const violation of result.violations)
       console.log(