diffninja 0.3.1 → 0.4.0

package/dist/languages/grammars.js

@@ -1,55 +1,135 @@
 import { createRequire } from "node:module";
 import { execFileSync } from "node:child_process";
-import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync, } from "node:fs";
+import { createHash } from "node:crypto";
+import { chmodSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, isAbsolute, join } from "node:path";
 import { z } from "zod";
+import { packageVersion } from "../review/version.js";
+import { npmEnvironment } from "./child-env.js";
+import { GRAMMAR_BUILD_ONLY, GRAMMAR_PACKAGE_JSON, GRAMMAR_PACKAGE_LOCK, GRAMMAR_PINS } from "./grammar-lock.js";
 function errnoCode(err) {
     // SAFETY: Node require/fs failures are ErrnoException with optional string code.
     return err.code;
 }
-/** On-disk cache of npm-installed tree-sitter grammar packages. */
+/**
+ * Grammars that ship inside diffninja's own package (regular dependencies). Any
+ * other grammar comes only from the cache below, never from whatever
+ * `node_modules` happens to sit above the install.
+ */
+const BUNDLED_GRAMMARS = new Set(["tree-sitter-javascript", "tree-sitter-typescript"]);
+/**
+ * Where `diffninja grammars install` puts the pinned grammars. Private to
+ * diffninja: the shared calldiff cache holds whatever an unpinned install once
+ * fetched, and is never read.
+ */
 export function grammarCacheDir() {
-    const override = process.env.CALLDIFF_GRAMMAR_CACHE;
+    const override = process.env.DIFFNINJA_GRAMMAR_CACHE;
     if (override)
         return override;
-    return join(homedir(), ".cache", "calldiff", "grammars");
+    return join(homedir(), ".cache", "diffninja", "grammars");
+}
+/**
+ * Written last by the installer, so a cache without it (or with another lock's) is not trusted.
+ * It is a consistency check, not authentication. It holds only public data (the lock's digest),
+ * so anyone who can write the directory can write one. Ownership is what cacheDirectoryProblem checks.
+ */
+const CACHE_MARKER = ".diffninja-grammars.json";
+const markerSchema = z.object({ format: z.literal(1), lockSha256: z.string(), installedAt: z.string(), built: z.boolean().optional() });
+/**
+ * Why grammars in this directory must not be loaded, or undefined when it is safe to.
+ * It must belong to the user running diffninja and be writable by no one else. A missing
+ * directory is no problem, since there is nothing in it to trust. Windows has no uid or mode bits,
+ * so nothing is checked there.
+ */
+export function cacheDirectoryProblem(dir) {
+    const uid = process.getuid?.();
+    const stats = uid === undefined ? undefined : statSync(dir, { throwIfNoEntry: false });
+    if (stats === undefined)
+        return undefined;
+    if (stats.uid !== uid)
+        return `${dir} belongs to another user (uid ${stats.uid})`;
+    if ((stats.mode & 0o022) !== 0)
+        return `other users can write to ${dir} (mode ${(stats.mode & 0o777).toString(8)})`;
+    return undefined;
+}
+/** The exact version diffninja pins for a grammar package, or undefined when it is not one of them. */
+export function pinnedVersion(npmPackage) {
+    // hasOwn: "constructor" and the like must not read as pinned through the prototype.
+    // SAFETY: hasOwn just proved npmPackage is one of GRAMMAR_PINS's own keys.
+    return Object.hasOwn(GRAMMAR_PINS, npmPackage) ? GRAMMAR_PINS[npmPackage] : undefined;
+}
+function needsBuild(npmPackage) {
+    // SAFETY: widening a tuple of string literals to string[] only to test membership.
+    return GRAMMAR_BUILD_ONLY.includes(npmPackage);
 }
-function packageInstalled(cacheDir, npmPackage) {
-    return existsSync(join(cacheDir, "node_modules", npmPackage));
+let cachedDigest;
+/** Fingerprint of the lock this build of diffninja installs from. */
+export function grammarLockDigest() {
+    cachedDigest ??= createHash("sha256").update(JSON.stringify(GRAMMAR_PACKAGE_LOCK)).digest("hex");
+    return cachedDigest;
+}
+/** The marker of a cache this diffninja's lock installed, or undefined for anything else. */
+function readCacheMarker(cacheDir) {
+    if (cacheDirectoryProblem(cacheDir) !== undefined)
+        return undefined;
+    try {
+        const marker = markerSchema.safeParse(JSON.parse(readFileSync(join(cacheDir, CACHE_MARKER), "utf8")));
+        return marker.success && marker.data.lockSha256 === grammarLockDigest() ? marker.data : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+const packageVersionSchema = z.object({ version: z.string() });
+/** The installed directory of a pinned grammar, when the cache is one diffninja installed and holds exactly the pinned version. */
+function pinnedGrammarRoot(cacheDir, npmPackage) {
+    const pinned = pinnedVersion(npmPackage);
+    const marker = pinned === undefined ? undefined : readCacheMarker(cacheDir);
+    if (pinned === undefined || marker === undefined)
+        return undefined;
+    // A grammar with no prebuilt binary loads only after the person asked for its source build.
+    if (needsBuild(npmPackage) && marker.built !== true)
+        return undefined;
+    const root = join(cacheDir, "node_modules", npmPackage);
+    try {
+        const manifest = packageVersionSchema.safeParse(JSON.parse(readFileSync(join(root, "package.json"), "utf8")));
+        return manifest.success && manifest.data.version === pinned ? root : undefined;
+    }
+    catch {
+        return undefined;
+    }
 }
-const cacheManifestSchema = z
-    .object({ allowScripts: z.record(z.string(), z.unknown()).optional() })
-    .catchall(z.unknown());
 /**
- * The cache's own package.json, which also allows the grammar's install
- * script: npm 12 blocks dependency install scripts unless `allowScripts`
- * names them, and rejects `--allow-scripts` in a project install like this
- * one. Earlier npm ignores the field. A cache written before this keeps its
- * other fields and gains the entry.
+ * The command that installs these grammars where this diffninja reads them. It names this
+ * version, because a cache is read only by a diffninja with the same lock, and `@latest` or
+ * whatever `diffninja` is on PATH may have another. Kotlin and Perl need `--build`.
  */
-export function ensureCachePackageJson(cacheDir, npmPackage) {
-    mkdirSync(cacheDir, { recursive: true });
-    const pkgPath = join(cacheDir, "package.json");
-    let pkg = {
-        name: "calldiff-grammar-cache",
-        private: true,
-        description: "On-demand tree-sitter grammars for calldiff",
-    };
-    if (existsSync(pkgPath)) {
-        try {
-            const parsed = cacheManifestSchema.safeParse(JSON.parse(readFileSync(pkgPath, "utf8")));
-            if (parsed.success)
-                pkg = parsed.data;
-        }
-        catch {
-            // An unreadable cache manifest is replaced; the grammars beside it stay.
-        }
+export function grammarsInstallCommand(npmPackages) {
+    return `npx -y diffninja@${packageVersion()} grammars install${npmPackages.some(needsBuild) ? " --build" : ""}`;
+}
+/**
+ * A grammar this review needed is not installed. diffninja never downloads code
+ * while it reviews; the person installs the pinned set once, on purpose.
+ */
+export class GrammarNotInstalledError extends Error {
+    npmPackage;
+    constructor(npmPackage) {
+        super(pinnedVersion(npmPackage) === undefined
+            ? `${npmPackage} is not one of the grammars diffninja installs, so call flows skip its files.`
+            : needsBuild(npmPackage)
+                ? `The ${npmPackage} grammar ships no prebuilt binary, so call flows skip its files until it is compiled on this machine. diffninja does not download or build code while it reviews: run \`${grammarsInstallCommand([npmPackage])}\` once (needs Python and a C/C++ compiler), then review again.`
+                : `The ${npmPackage} grammar is not installed, so call flows skip its files. diffninja does not download code while it reviews: run \`${grammarsInstallCommand([npmPackage])}\` once to add the pinned grammars, then review again.`);
+        this.npmPackage = npmPackage;
+        this.name = "GrammarNotInstalledError";
     }
-    if (pkg.allowScripts?.[npmPackage] === true && existsSync(pkgPath))
-        return;
-    pkg.allowScripts = { ...pkg.allowScripts, [npmPackage]: true };
-    writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
+}
+const missingGrammars = new Set();
+/** The grammars that were needed and absent since the last call, sorted; clears the record. */
+export function takeMissingGrammars() {
+    const names = [...missingGrammars].sort();
+    missingGrammars.clear();
+    return names;
 }
 /**
  * Absolute path to one of npm's JS entry points (`npm-cli.js`, `npx-cli.js`),
@@ -215,98 +295,90 @@ function requireGrammar(require, npmPackage, packageRoot) {
                 return binding;
         }
         else {
-            // A mislabeled prebuild blocks node-gyp-build's own source-build
-            // fallback. This directory is diffninja's own grammar cache, so remove
-            // the bad artifact and let the load retry compile from source.
+            // A prebuild for another CPU cannot load, and repairing it means compiling:
+            // say so instead of editing the cache.
             const bad = mislabeledPrebuild(packageRoot);
             if (bad !== null) {
-                rmSync(bad, { force: true });
-                try {
-                    // SAFETY: grammar packages export a module compatible with GrammarModule.
-                    return require(npmPackage);
-                }
-                catch {
-                    const binding = loadNativeBinding(packageRoot);
-                    if (binding)
-                        return binding;
-                }
+                throw new Error(`${npmPackage} ships a native build for another CPU (${bad}), so it cannot load on ${process.platform}/${process.arch}.`);
             }
         }
         throw new Error(withNativeLoadHints(npmPackage, failure));
     }
 }
-function installSpecFor(npmPackage) {
-    switch (npmPackage) {
-        case "tree-sitter-c-sharp":
-            return "tree-sitter-c-sharp@0.23.1";
-        case "@tree-sitter-grammars/tree-sitter-lua":
-            // 0.4+ is ESM-with-TLA; 0.2.0 is CJS and loads via createRequire.
-            return "@tree-sitter-grammars/tree-sitter-lua@0.2.0";
-        default:
-            return npmPackage;
-    }
-}
-function sleepMs(ms) {
-    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-}
-/** Why this grammar's install can fail beyond npm itself, for the error text. */
-function installFailureHint(npmPackage) {
-    if (npmPackage === "tree-sitter-swift") {
-        return ("tree-sitter-swift downloads its parser CLI from GitHub Releases during " +
-            "install; a proxy or offline network fails that download. Retry with " +
-            "network access to github.com, or pre-populate CALLDIFF_GRAMMAR_CACHE.");
+function runNpm(cwd, args, build) {
+    const npm = npmSpawnSpec(args);
+    try {
+        // A minimal environment: no token of the engineer's reaches npm or any install script.
+        execFileSync(npm.file, npm.args, { cwd, env: npmEnvironment(process.env, { npm_config_global: "false", npm_config_location: "project" }, { build }), stdio: ["ignore", "pipe", "pipe"], timeout: 300_000, maxBuffer: 32 * 1024 * 1024 });
     }
-    if (npmPackage === "tree-sitter-perl" || npmPackage === "tree-sitter-kotlin") {
-        return ("this grammar ships no prebuilt binary and compiles from source: Python " +
-            "and a C/C++ toolchain (build-essential, Xcode command line tools, or " +
-            "Visual Studio Build Tools) are required.");
+    catch (err) {
+        // SAFETY: catch bindings are unknown; execFileSync errors carry the child's stderr.
+        const failure = err;
+        const tail = String(failure.stderr ?? "").split("\n").filter(line => line.trim() !== "").slice(-6).join("\n");
+        throw new Error(`npm could not install the grammars: ${failure.message}${tail === "" ? "" : `\n${tail}`}`);
     }
-    return null;
 }
 /**
- * Install an on-demand grammar into the cache, retrying transient network
- * failures (the Swift parser CLI download is the known flaky one). Throws an
- * actionable error when the install cannot succeed.
+ * Install exactly the pinned grammars, and nothing else, into the cache. This is
+ * the only place diffninja downloads grammar code, and only when a person runs
+ * `diffninja grammars install`. `npm ci` from the shipped lock refuses any
+ * tarball whose sha512 differs, `--ignore-scripts` keeps every install script
+ * (the packages' own and their dependencies') from running, and the grammars
+ * load from their bundled prebuilt binaries. Reviews never call this.
  */
-function installGrammarPackage(cacheDir, npmPackage) {
-    const npm = npmSpawnSpec([
-        "install",
-        "--prefix",
-        cacheDir,
-        "--no-save",
-        "--no-fund",
-        "--no-audit",
-        "--legacy-peer-deps",
-        installSpecFor(npmPackage),
-    ]);
-    for (let attempt = 1; attempt <= 3; attempt++) {
+export function installPinnedGrammars(options = {}) {
+    const cacheDir = options.cacheDir ?? grammarCacheDir();
+    mkdirSync(cacheDir, { recursive: true, mode: 0o700 });
+    // mkdir leaves an existing directory's mode alone, so tighten one's own and refuse anyone else's.
+    if (statSync(cacheDir).uid === process.getuid?.())
+        chmodSync(cacheDir, 0o700);
+    const problem = cacheDirectoryProblem(cacheDir);
+    if (problem !== undefined)
+        throw new Error(`Refusing to install grammars: ${problem}, so its contents could not be trusted. Set DIFFNINJA_GRAMMAR_CACHE to a directory of your own.`);
+    // Untrusted until the install below finishes and verifies.
+    rmSync(join(cacheDir, CACHE_MARKER), { force: true });
+    writeFileSync(join(cacheDir, "package.json"), JSON.stringify(GRAMMAR_PACKAGE_JSON, null, 2) + "\n", "utf8");
+    writeFileSync(join(cacheDir, "package-lock.json"), JSON.stringify(GRAMMAR_PACKAGE_LOCK, null, 2) + "\n", "utf8");
+    // No --prefix: `npm ci` rejects it. The working directory is the project, whatever the user's npm config says.
+    const npm = options.runNpm ?? ((cwd, args) => runNpm(cwd, args, options.build === true));
+    npm(cacheDir, ["ci", "--ignore-scripts", "--legacy-peer-deps", "--no-audit", "--no-fund"]);
+    // The one place an install script runs: the source build of the grammars with no prebuilt
+    // binary, for exactly those packages, and only because the person asked for --build.
+    if (options.build === true)
+        npm(cacheDir, ["rebuild", "--legacy-peer-deps", "--no-audit", "--no-fund", ...GRAMMAR_BUILD_ONLY]);
+    const packages = [];
+    for (const [name, version] of Object.entries(GRAMMAR_PINS)) {
+        let installed;
         try {
-            execFileSync(npm.file, npm.args, {
-                stdio: ["ignore", "pipe", "pipe"],
-                env: process.env,
-                timeout: 300_000,
-            });
-            return;
+            const manifest = packageVersionSchema.safeParse(JSON.parse(readFileSync(join(cacheDir, "node_modules", name, "package.json"), "utf8")));
+            installed = manifest.success ? manifest.data.version : undefined;
         }
-        catch (err) {
-            if (attempt === 3) {
-                // SAFETY: catch bindings are unknown; normalize to Error at the boundary.
-                const failure = err instanceof Error ? err : new Error(String(err));
-                const hint = installFailureHint(npmPackage);
-                throw new Error(`Could not install the ${npmPackage} grammar into ${cacheDir}: ${failure.message}` +
-                    (hint ? ` ${hint}` : ""));
-            }
-            sleepMs(2000 * attempt);
+        catch {
+            installed = undefined;
         }
+        if (installed !== version)
+            throw new Error(`${name}@${version} is not in ${cacheDir} after the install (found ${installed ?? "nothing"}); leaving the cache untrusted.`);
+        packages.push({ name, version });
     }
+    writeFileSync(join(cacheDir, CACHE_MARKER), JSON.stringify({ format: 1, lockSha256: grammarLockDigest(), installedAt: new Date().toISOString(), built: options.build === true }) + "\n", "utf8");
+    return { cacheDir, packages };
+}
+export function grammarStatus(cacheDir = grammarCacheDir()) {
+    return {
+        cacheDir,
+        trusted: readCacheMarker(cacheDir) !== undefined,
+        packages: Object.entries(GRAMMAR_PINS).map(([name, version]) => ({ name, version, installed: pinnedGrammarRoot(cacheDir, name) !== undefined, needsBuild: needsBuild(name) })),
+    };
 }
 /**
- * Install an npm grammar package into the shared cache if missing, then require it.
- * Reuses the cache across CLI invocations.
+ * The grammar package's module. Bundled grammars come from diffninja's own
+ * dependencies; every other one from the cache `diffninja grammars install`
+ * filled, and only when that cache holds the exact pinned version. Nothing is
+ * ever downloaded here: a missing grammar throws GrammarNotInstalledError, which
+ * call-flow analysis reports once instead of skipping silently.
  */
 export function loadGrammarPackage(npmPackage) {
-    // Prefer the app's own dependency when present (e.g. tree-sitter-typescript).
-    try {
+    if (BUNDLED_GRAMMARS.has(npmPackage)) {
         const localRequire = createRequire(import.meta.url);
         try {
             // SAFETY: local dependency resolves to a tree-sitter grammar module.
@@ -316,27 +388,22 @@ export function loadGrammarPackage(npmPackage) {
             // SAFETY: catch bindings are unknown; normalize to Error at the boundary.
             const failure = err instanceof Error ? err : new Error(String(err));
             const code = errnoCode(failure);
-            if (code === "ERR_REQUIRE_ASYNC_MODULE" ||
-                failure.message.includes("top-level await")) {
-                const entry = localRequire.resolve(npmPackage);
-                const packageRoot = join(entry, "..", "..");
+            if (code === "ERR_REQUIRE_ASYNC_MODULE" || failure.message.includes("top-level await")) {
+                const packageRoot = join(localRequire.resolve(npmPackage), "..", "..");
                 const binding = loadNativeBinding(packageRoot);
                 if (binding)
                     return binding;
             }
-            throw err;
+            throw failure;
         }
     }
-    catch {
-        // fall through to cache
-    }
     const cacheDir = grammarCacheDir();
-    if (!packageInstalled(cacheDir, npmPackage)) {
-        ensureCachePackageJson(cacheDir, npmPackage);
-        installGrammarPackage(cacheDir, npmPackage);
+    const packageRoot = pinnedGrammarRoot(cacheDir, npmPackage);
+    if (packageRoot === undefined) {
+        missingGrammars.add(npmPackage);
+        throw new GrammarNotInstalledError(npmPackage);
     }
     const require = createRequire(join(cacheDir, "package.json"));
-    const packageRoot = join(cacheDir, "node_modules", npmPackage);
     return requireGrammar(require, npmPackage, packageRoot);
 }
 /** Resolve the value to pass to parser.setLanguage. */

package/dist/review/call-flow-html.d.ts

@@ -21,7 +21,9 @@ import type { ReviewReport } from "./types.js";
  * reaches the reviewer as a glyph plus color for a call that was added,
  * removed, or contains a change, and plain dimmed text for an unchanged call.
  */
-export declare function renderCallFlows(report: ReviewReport): string;
+export declare function renderCallFlows(report: ReviewReport, options?: {
+    readonly treeOnly?: boolean;
+}): string;
 export declare const CALL_FLOW_STYLES = "\n.cf {\n  display: flex; flex-direction: column; gap: 12px; margin-top: 18px;\n  --cf-add: #1a7f37; --cf-add-soft: #dafbe1;\n  --cf-del: #cf222e; --cf-del-soft: #ffebe9;\n  --cf-chg: #9a6700; --cf-chg-soft: #fff8c5;\n  --cf-quiet: var(--ink-soft);\n}\n@media (prefers-color-scheme: dark) {\n  .cf {\n    --cf-add: #3fb950; --cf-add-soft: rgba(46, 160, 67, 0.15);\n    --cf-del: #f85149; --cf-del-soft: rgba(248, 81, 73, 0.12);\n    --cf-chg: #d29922; --cf-chg-soft: rgba(187, 128, 9, 0.15);\n  }\n}\n/* Mode sections, folded files and the breadcrumb are toggled with the hidden\n   attribute, so the module carries that rule itself instead of relying on the page. */\n.cf [hidden] { display: none !important; }\n.cf-head { display: flex; flex-direction: column; gap: 4px; }\n.cf-prov { font-size: 12px; color: var(--ink-soft); }\n.cf-note { font-size: 12px; color: var(--ink-soft); overflow-wrap: anywhere; }\n.cf-absence { padding: 16px 0; }\n.cf-bounds {\n  margin: 10px 0 0;\n  padding: 2px 0 2px 10px;\n  border-left: 2px solid var(--cf-chg);\n  color: var(--ink-soft);\n  font-size: 12px;\n  overflow-wrap: anywhere;\n}\n.cf-controls { display: flex; align-items: center; flex-wrap: wrap; gap: 10px; }\n.cf-ready .cf-controls { position: sticky; top: var(--toolbar-height, 0px); z-index: 4; background: var(--bg); padding: 8px 0; }\n.cf, .cf-files, .cf-file-body, .cf-mode { min-width: 0; }\n.cf-modes {\n  display: inline-flex;\n  align-items: stretch;\n  border: 1px solid var(--line);\n  border-radius: 6px;\n  overflow: hidden;\n  background: var(--panel);\n}\n.cf-mode-link {\n  display: inline-flex;\n  align-items: center;\n  padding: 5px 14px;\n  font-size: 12px;\n  color: var(--ink-soft);\n  text-decoration: none;\n  border-right: 1px solid var(--line);\n}\n.cf-mode-link:last-child { border-right: 0; }\n.cf-mode-link:hover, .cf-mode-link:focus-visible { color: var(--ink); background: var(--sunken); }\n.js .cf-mode-link[aria-current] { color: var(--ink); background: var(--sunken); font-weight: 600; }\n.cf-jump ul {\n  display: flex;\n  flex-wrap: wrap;\n  gap: 8px;\n  list-style: none;\n  margin: 0;\n  padding: 0;\n  max-height: 22vh;\n  overflow-y: auto;\n}\n.cf-jump-link {\n  display: inline-flex;\n  align-items: center;\n  gap: 8px;\n  max-width: 100%;\n  min-width: 0;\n  padding: 4px 10px 4px 9px;\n  border: 1px solid var(--line);\n  border-radius: 6px;\n  background: var(--panel);\n  color: var(--ink);\n  font-size: 12px;\n  text-decoration: none;\n}\n.cf-jump-link:hover, .cf-jump-link:focus-visible { border-color: var(--cursor); }\n.cf-jump-path { min-width: 0; max-width: 32ch; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }\n.cf-jump-count { color: var(--ink-soft); white-space: nowrap; }\n.cf-crumbs {\n  display: flex;\n  align-items: center;\n  flex-wrap: nowrap;\n  gap: 6px;\n  font-size: 12.5px;\n  padding-bottom: 3px;\n  overflow-x: auto;\n  overscroll-behavior-x: contain;\n}\n.cf-crumb {\n  display: inline-flex;\n  align-items: center;\n  gap: 6px;\n  flex: 0 0 auto;\n  max-width: 34ch;\n  font: inherit;\n  font-size: 12px;\n  padding: 3px 10px;\n  border: 1px solid var(--line-strong);\n  border-radius: 999px;\n  background: var(--panel);\n  color: var(--ink);\n  cursor: pointer;\n  white-space: nowrap;\n}\n.cf-crumb[aria-current] { border-color: var(--cursor); font-weight: 600; }\n.cf-crumb-label { overflow: hidden; text-overflow: ellipsis; }\n.cf-crumb-file {\n  flex: 0 0 auto;\n  max-width: 22ch;\n  overflow: hidden;\n  text-overflow: ellipsis;\n  font-size: 11px;\n  color: var(--ink-soft);\n}\n.cf-sep { flex: 0 0 auto; color: var(--ink-soft); }\n.cf-files { display: flex; flex-direction: column; gap: 12px; }\n.cf-file {\n  background: var(--panel);\n  border: 1px solid var(--line);\n  border-left: 3px solid var(--line-strong);\n  border-radius: 6px;\n  overflow: hidden;\n}\n.cf-file { --cf-color: var(--ink-soft); --cf-fill: var(--sunken); }\n.cf-file-attention { border-left-color: var(--alarm); --cf-color: var(--alarm); --cf-fill: var(--alarm-bg); }\n.cf-file-uncertain { border-left-color: var(--warn); --cf-color: var(--warn); --cf-fill: var(--warn-bg); }\n.cf-file-low { border-left-color: var(--line-strong); }\n.cf-file-passed { border-left-color: var(--teal); --cf-color: var(--teal); --cf-fill: var(--teal-bg); }\n.cf-file-head {\n  display: flex;\n  align-items: center;\n  flex-wrap: wrap;\n  gap: 10px;\n  padding: 8px 12px;\n  background: var(--sunken);\n  cursor: pointer;\n  list-style: none;\n}\n.cf-file-head::-webkit-details-marker { display: none; }\n.cf-file-head::after {\n  content: \"\u25B8\";\n  margin-left: auto;\n  font-size: 11px;\n  color: var(--ink-soft);\n  transition: transform 0.15s ease;\n}\n.cf-file[open] > .cf-file-head::after { transform: rotate(90deg); }\n.cf-file-head:focus-visible { outline: 2px solid var(--cursor); outline-offset: -2px; }\n.cf-file-path { flex: 1 1 260px; min-width: 0; font-size: 12.5px; font-weight: 600; overflow-wrap: anywhere; }\n.cf-file-count { font-size: 12px; color: var(--ink-soft); white-space: nowrap; }\n.cf-diff-link { font-size: 12px; white-space: nowrap; }\n.cf-file-body { border-top: 1px solid var(--line); padding: 0 12px 12px; }\n.cf-mode { padding-top: 12px; }\n.cf-noscript { display: block; }\n.cf-noscript .cf-note { margin: 6px 0 0; }\n.cf-mode + .cf-mode { margin-top: 12px; border-top: 1px dashed var(--line); }\n.cf-mode-head {\n  margin: 0 0 8px;\n  font-size: 11.5px;\n  font-weight: 700;\n  letter-spacing: 0.08em;\n  text-transform: uppercase;\n  color: var(--ink-soft);\n}\n.cf-ready .cf-mode-head { display: none; }\n.cf-ready .cf-mode + .cf-mode { margin-top: 0; border-top: 0; }\n.cf-tree, .cf-children { list-style: none; margin: 0; padding: 0; }\n.cf-children { margin-left: 15px; padding-left: 10px; border-left: 1px dashed var(--line); }\n.cf-row { display: flex; align-items: center; flex-wrap: wrap; gap: 0 8px; padding: 2px 6px; border-radius: 6px; min-width: 0; }\n.cf-row:hover { background: var(--sunken); }\n.cf-fold > .cf-row { cursor: pointer; list-style: none; }\n.cf-fold > .cf-row::-webkit-details-marker { display: none; }\n.cf-fold > .cf-row::before { content: \"\u25B8\"; font-size: 10px; color: var(--ink-soft); transition: transform 0.15s ease; }\n.cf-fold[open] > .cf-row::before { transform: rotate(90deg); }\n.cf-badge, .cf-chip-badge {\n  display: inline-flex;\n  align-items: center;\n  justify-content: center;\n  flex: 0 0 auto;\n  min-width: 16px;\n  height: 16px;\n  border: 1px solid transparent;\n  border-radius: 4px;\n  font-family: var(--mono);\n  font-size: 11px;\n  font-weight: 700;\n}\n.cf-badge, .cf-chip-badge { color: var(--cf-node-color); background: var(--cf-node-fill); }\n.cf-label {\n  font: 400 12.5px/1.5 var(--mono);\n  padding: 0 2px;\n  border: 1px solid transparent;\n  border-radius: 4px;\n  background: none;\n  text-align: left;\n  /* Capped so a long call never pushes its row onto a second line; the\n     location takes what is left and truncates first. */\n  flex: 0 1 auto;\n  min-width: 0;\n  max-width: 62%;\n  white-space: nowrap;\n  overflow: hidden;\n  text-overflow: ellipsis;\n}\n.js .cf-label { cursor: pointer; }\n.js .cf-label:hover, .cf-label:focus-visible { text-decoration: underline; }\n.cf-label:focus-visible { outline: 2px solid var(--cursor); outline-offset: 1px; }\n.cf-loc { flex: 1 1 0; min-width: 0; font-size: 11px; color: var(--ink-soft); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }\n.cf-loc-none { font-style: italic; }\n.cf-node, .cf-gnode, .cf-chip { --cf-node-color: var(--cf-chg); --cf-node-fill: var(--cf-chg-soft); --cf-node-weight: 600; --cf-node-decoration: none; }\n.cf-st-added { --cf-node-color: var(--cf-add); --cf-node-fill: var(--cf-add-soft); }\n.cf-st-removed { --cf-node-color: var(--cf-del); --cf-node-fill: var(--cf-del-soft); --cf-node-decoration: line-through; }\n.cf-node.cf-st-same, .cf-gnode.cf-st-same, .cf-chip.cf-st-same { --cf-node-color: var(--ink-soft); --cf-node-fill: var(--sunken); --cf-node-weight: 400; }\n.cf-label { color: var(--cf-node-color); font-weight: var(--cf-node-weight); text-decoration: var(--cf-node-decoration); }\n.cf-node.cf-ancestor > .cf-fold > .cf-row { display: none; }\n.cf-node.cf-ancestor > .cf-fold > .cf-children { margin: 0; padding: 0; border: 0; }\n.cf-svg-wrap {\n  max-width: 100%;\n  overflow: auto;\n  border: 1px solid var(--line);\n  border-radius: 6px;\n  background: var(--sunken);\n  overscroll-behavior: contain;\n}\n.cf-svg { display: block; max-width: none; }\n.cf-ready .cf-svg-wrap { height: clamp(220px, 42vh, 400px); overflow: hidden; touch-action: none; cursor: grab; }\n.cf-diagram-btn, .cf-diagram-close {\n  display: inline-flex; align-items: center; gap: 6px; height: 29px; padding: 0 12px;\n  border: 1px solid var(--line); border-radius: 6px; background: var(--panel);\n  font: 500 12px/1 var(--sans, inherit); color: var(--ink); cursor: pointer;\n}\n.cf-diagram-btn { color: var(--cursor); border-color: var(--cursor); }\n.cf-diagram-btn::after { content: \"\\2197\"; font-size: 12px; }\n.cf-diagram-btn:hover, .cf-diagram-close:hover { background: var(--sunken); }\n.cf-diagram-close { margin-left: auto; }\n.cf-diagram-hint { margin: 0 0 0 auto; font-size: 12px; color: var(--ink-soft); }\n.cf-diagram-hint + .cf-diagram-close { margin-left: 12px; }\n.cf.cf-diagram-open .cf-head { display: none; }\n/* The diagram view fills the browser window, and the graph gets nearly all of its height. */\n.cf.cf-diagram-open {\n  position: fixed; inset: 0; z-index: 50; margin: 0; padding: 12px 20px 20px;\n  background: var(--bg); overflow: auto; overscroll-behavior: contain;\n}\n.cf.cf-diagram-open .cf-controls { position: sticky; top: -12px; z-index: 5; background: var(--bg); padding: 10px 0; }\n.cf.cf-diagram-open .cf-modes, .cf.cf-diagram-open .cf-diagram-btn { display: none !important; }\n.cf.cf-diagram-open { padding-left: 292px; }\n.cf.cf-diagram-open .cf-svg-wrap { height: calc(100vh - 150px); min-height: 320px; }\n/* One canvas at a time: the entry point picked in the list, in its own file. */\n.cf.cf-diagram-open .cf-jump, .cf.cf-diagram-open .cf-bounds, .cf.cf-diagram-open .cf-omitted { display: none !important; }\n.cf.cf-diagram-open .cf-file:not(.cf-file-current) { display: none; }\n.cf.cf-diagram-open .cf-graph-frame:not(.cf-frame-current) { display: none; }\n.cf.cf-diagram-open .cf-file-body { padding-bottom: 0; }\n.cf-diagram-nav {\n  position: fixed; top: 0; bottom: 0; left: 0; width: 276px; overflow-y: auto; z-index: 6;\n  padding: 16px 12px; background: var(--sunken); border-right: 1px solid var(--line);\n}\n.cf-diagram-nav-head { margin: 0 0 10px; font-size: 13px; font-weight: 600; color: var(--ink); }\n.cf-diagram-nav-file {\n  margin: 14px 0 4px; font: 600 12px var(--mono); color: var(--ink-soft);\n  white-space: nowrap; overflow: hidden; text-overflow: ellipsis;\n}\n.cf-diagram-nav ul { list-style: none; margin: 0; padding: 0; display: flex; flex-direction: column; gap: 2px; }\n.cf-diagram-nav button {\n  display: flex; flex-direction: column; align-items: flex-start; gap: 1px; width: 100%;\n  padding: 6px 8px; border: 0; border-radius: 6px; background: none; color: var(--ink); text-align: left; cursor: pointer;\n}\n.cf-diagram-nav button:hover { background: var(--panel); }\n.cf-diagram-nav button[aria-current] { background: var(--panel); box-shadow: inset 3px 0 0 var(--cursor); }\n.cf-diagram-nav-name { max-width: 100%; font: 600 12px/1.35 var(--mono); overflow-wrap: anywhere; }\n.cf-diagram-nav-count { max-width: 100%; font-size: 11px; color: var(--ink-soft); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }\n@media (max-width: 760px) {\n  .cf.cf-diagram-open { padding-left: 12px; padding-top: 12px; }\n  .cf-diagram-nav { position: static; width: auto; max-height: 30vh; margin: 0 0 8px; border: 1px solid var(--line); border-radius: 6px; }\n}\n.cf-ready .cf-svg-wrap:focus-visible { outline: 2px solid var(--cursor); outline-offset: 2px; }\n.cf-ready .cf-svg-wrap.cf-dragging { cursor: grabbing; user-select: none; }\n.cf-ready .cf-svg { width: 100%; height: 100%; }\n.cf-graph-frame + .cf-graph-frame { margin-top: 14px; }\n.cf-camera-tools { align-items: center; flex-wrap: wrap; gap: 5px; margin-bottom: 6px; }\n.cf-camera-tools button { min-height: 28px; padding: 0 10px; font-size: 12px; }\n.cf-scale { min-width: 4ch; text-align: center; font: 11px var(--mono); color: var(--ink-soft); }\n.cf-omitted { display: none; }\n.cf-ready .cf-omitted { display: block; }\n.cf-node.cf-selected > .cf-row, .cf-node.cf-selected > .cf-fold > .cf-row,\n.cf-chip.cf-selected { outline: 2px solid var(--cursor); outline-offset: 1px; border-radius: 5px; }\n.cf-edge { fill: none; stroke: var(--line-strong); stroke-width: 1.5; }\n.cf-gnode rect { fill: var(--panel); stroke: var(--line-strong); stroke-width: 1.5; }\n.cf-gnode:focus-visible { outline: none; }\n.cf-gzoom circle { fill: var(--panel); stroke: var(--line-strong); }\n.cf-gzoom text { fill: var(--ink); font: 14px var(--mono); }\n.cf-gzoom:hover circle, .cf-gzoom:focus-visible circle { stroke: var(--cursor); stroke-width: 2; }\n.cf-gzoom:focus-visible { outline: none; }\n.cf-glabel { font-family: var(--mono); font-size: 12px; fill: var(--ink); }\n.cf-gloc { font-family: var(--mono); font-size: 10px; fill: var(--ink-soft); }\n.cf-gnode.cf-st-same rect { stroke: var(--line); fill: transparent; }\n.cf-gnode.cf-st-same .cf-glabel { fill: var(--ink-soft); }\n.cf-gnode:not(.cf-st-same) rect { stroke: var(--cf-node-color); fill: var(--panel); }\n.cf-gnode:not(.cf-st-same) .cf-glabel { fill: var(--cf-node-color); font-weight: 600; }\n.cf-gnode:hover rect, .cf-gnode:focus-visible rect { stroke: var(--cursor); stroke-width: 2.5; }\n.cf-gnode.cf-selected rect { stroke: var(--cursor); stroke-width: 3; }\n.cf-paths { display: flex; flex-direction: column; gap: 6px; list-style: none; margin: 0; padding: 0; }\n.cf-path {\n  display: flex;\n  align-items: center;\n  flex-wrap: wrap;\n  gap: 4px 6px;\n  padding: 6px 8px;\n  border: 1px solid var(--line);\n  border-radius: 6px;\n  background: var(--panel);\n}\n.cf-chip {\n  display: inline-flex;\n  align-items: center;\n  gap: 6px;\n  max-width: 100%;\n  min-width: 0;\n  padding: 2px 8px 2px 4px;\n  border: 1px solid var(--line);\n  border-left: 3px solid var(--cf-node-color);\n  border-radius: 6px;\n  background: var(--panel);\n  color: var(--ink);\n}\n.cf-chip:hover, .cf-chip:focus-within { border-color: var(--cursor); }\n.cf-chip-zoom {\n  display: inline-flex;\n  align-items: center;\n  gap: 6px;\n  max-width: 100%;\n  min-width: 0;\n  color: inherit;\n  text-decoration: none;\n}\n.cf-chip-label { min-width: 0; max-width: 36ch; font-size: 12px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }\n.cf-chip-loc { min-width: 0; max-width: 28ch; font-size: 10.5px; color: var(--ink-soft); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }\n.cf-chip.cf-st-same .cf-chip-label { color: var(--ink-soft); }\n.cf-chip:not(.cf-st-same) .cf-chip-label { color: var(--cf-node-color); font-weight: 600; }\n.cf-chip .cf-desc { max-width: 28ch; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }\n.cf-arrow { color: var(--ink-soft); font-size: 12px; }\n/* One description line per call, only when the backend attached one. */\n.cf-desc { font-size: 11.5px; color: var(--ink-soft); font-style: italic; overflow-wrap: anywhere; }\n.cf-business { display: flex; flex-direction: column; gap: 6px; margin: 4px 0 10px; }\n.cf-business-note { font-size: 13px; color: var(--ink-soft); }\n.cf-plumbing-toggle { display: inline-flex; align-items: center; gap: 7px; font-size: 13px; color: var(--ink-soft); cursor: pointer; width: fit-content; }\n.cf:has(.cf-show-plumbing:not(:checked)) .cf-node.cf-plumbing { display: none; }\n.cf-purpose { font-family: var(--sans); font-size: 13.5px; font-weight: 550; color: var(--ink); overflow-wrap: anywhere; }\n.cf-row > .cf-purpose { flex: 1 0 100%; order: -1; padding-left: 26px; }\n.cf-fold > .cf-row > .cf-purpose { padding-left: 16px; }\n.cf-node.cf-explained > .cf-row .cf-label, .cf-node.cf-explained > .cf-fold > .cf-row .cf-label { font-size: 11.5px; }\n.cf-chip .cf-purpose { font-size: 12.5px; max-width: 34ch; }\n.cf-gpurpose { font-family: var(--sans); font-size: 12px; font-weight: 600; fill: var(--ink); }\n.cf-diagram-nav-name.cf-diagram-nav-purpose { font-family: var(--sans); white-space: normal; }\n.cf-row > .cf-desc { flex: 1 0 100%; order: 5; padding-left: 26px; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }\n.cf-row > .cf-src-link { order: 4; }\n.cf-depth { align-items: center; gap: 4px; }\n.cf-depth-label { font-size: 12px; color: var(--ink-soft); }\n.cf-depth-btn { padding: 3px 9px; font-size: 12px; }\n.cf-depth-btn[aria-pressed=\"true\"] { border-color: var(--cursor); color: var(--cursor); font-weight: 600; }\n/* Numbered, clickable call order on the graph edges. */\n.cf-edge-num circle { fill: var(--panel); stroke: var(--line-strong); stroke-width: 1.5; }\n.cf-edge-num text { font-family: var(--mono); font-size: 10.5px; fill: var(--ink-soft); }\n.cf-edge-num:hover circle, .cf-edge-num:focus-visible circle { stroke: var(--cursor); stroke-width: 2; }\n.cf-edge-num:hover text, .cf-edge-num:focus-visible text { fill: var(--cursor); font-weight: 700; }\n.cf-edge-num:focus-visible { outline: none; }\n.cf-gdesc { font-family: var(--mono); font-size: 10px; font-style: italic; fill: var(--ink-soft); }\n/* Resolved definition of one call: a native disclosure without the script, and\n   the body the script clones into its single shared panel. */\n.cf-source { margin: 3px 0 3px 24px; }\n.cf-ready .cf-source { display: none; }\n.cf-src-sum { width: fit-content; cursor: pointer; list-style: none; font-size: 11.5px; color: var(--ink-soft); }\n.cf-src-sum::-webkit-details-marker { display: none; }\n.cf-src-sum::before { content: \"\u25B8\"; margin-right: 6px; font-size: 10px; transition: transform 0.15s ease; display: inline-block; }\n.cf-source[open] > .cf-src-sum::before { transform: rotate(90deg); }\n.cf-src-sum:hover, .cf-src-sum:focus-visible { color: var(--cursor); }\n.cf-src-body { padding: 6px 0 4px; }\n.cf-src-ref { margin: 0 0 5px; font-size: 11.5px; color: var(--ink-soft); overflow-wrap: anywhere; }\n.cf-src-code {\n  margin: 0;\n  padding: 6px 9px;\n  border: 1px solid var(--line);\n  border-radius: 6px;\n  background: var(--sunken);\n  font-family: var(--mono);\n  font-size: 11.5px;\n  line-height: 1.5;\n  overflow-x: auto;\n}\n.cf-src-line { display: block; white-space: pre; }\n.cf-src-no {\n  display: inline-block;\n  width: 4ch;\n  margin-right: 10px;\n  text-align: right;\n  color: var(--ink-soft);\n  user-select: none;\n}\n.cf-src-note { margin: 0; font-size: 11.5px; color: var(--ink-soft); font-style: italic; }\n.cf-src-panel {\n  padding: 8px 12px 10px;\n  border: 1px solid var(--line-strong);\n  border-radius: 6px;\n  background: var(--panel);\n}\n.cf-src-panel-sum { width: fit-content; cursor: pointer; font-size: 12.5px; font-weight: 600; }\n.cf-src-panel-body { padding-top: 6px; }\n.cf-src-panel-body { max-height: 40vh; overflow: auto; }\n.cf-src-head-line { margin: 0 0 6px; font-size: 12px; color: var(--ink-soft); overflow-wrap: anywhere; }\n.cf-src-missing { margin: 0; }\n.cf-src-link {\n  flex: 0 0 auto;\n  font-size: 11px;\n  color: var(--ink-soft);\n  text-decoration: none;\n  white-space: nowrap;\n  padding: 0 6px;\n  border: 1px solid var(--line);\n  border-radius: 999px;\n}\n.cf-src-link:hover { text-decoration: none; }\n.cf-src-link:hover, .cf-src-link:focus-visible { color: var(--cursor); }\n@media (max-width: 680px) {\n  .cf-jump ul { max-height: 38vh; }\n  .cf-jump-link { width: 100%; }\n  .cf-jump-path { max-width: none; flex: 1 1 auto; }\n  .cf-file-body { padding: 0 11px 12px; }\n  .cf-crumb { max-width: 24ch; }\n  .cf-crumb-file { max-width: 12ch; }\n  .cf-source { margin-left: 10px; }\n  .cf-src-no { width: 3ch; margin-right: 7px; }\n  .cf-chip, .cf-chip-zoom { min-width: 0; flex-wrap: wrap; }\n  .cf-chip-loc { overflow-wrap: anywhere; }\n}\n";
 /**
  * Progressive enhancement for the rendered call flow. Nothing here is

package/dist/review/call-flow-html.js

@@ -24,7 +24,8 @@ import { nodeFunctionId, purposesOf, wrapPurpose } from "./explanation.js";
  * reaches the reviewer as a glyph plus color for a call that was added,
  * removed, or contains a change, and plain dimmed text for an unchanged call.
  */
-export function renderCallFlows(report) {
+export function renderCallFlows(report, options = {}) {
+    const treeOnly = options.treeOnly === true;
     const purposes = purposesOf(report);
     const files = collectFiles(report.callFlows, report.items, purposes);
     if (files.length === 0) {
@@ -35,7 +36,7 @@ export function renderCallFlows(report) {
         '<div class="cf">',
         renderSummary(files, new Set(report.items.map(item => item.file)).size),
         renderPlumbingToggle(plumbing, report.agentExplanation?.explainedBy),
-        renderControls(),
+        treeOnly ? "" : renderControls(),
         renderJump(files),
         '<nav class="cf-crumbs" id="cf-crumbs" aria-label="Visited call trail" hidden></nav>',
         // One panel the script fills with the focused call's definition; without the
@@ -45,7 +46,7 @@ export function renderCallFlows(report) {
         '<div class="cf-src-panel-body" id="cf-src-panel-body"></div>',
         "</details>",
         '<div class="cf-files">',
-        files.map((view, index) => renderFile(view, index + 1)).join("\n"),
+        files.map((view, index) => renderFile(view, index + 1, treeOnly)).join("\n"),
         "</div>",
         "</div>",
     ].join("\n");
@@ -85,6 +86,7 @@ const AVAILABILITY_NOTE = {
     available: "No call tree reaches a changed file in this range. This is not evidence of safety.",
     "needs-git-range": "Call paths need a git range. This input was a patch, so no call trees were built.",
     "no-changes": "No call path reaches a changed file. This is not evidence of safety.",
+    partial: "No call tree was drawn, but call flows left out some source files of this revision (very large files, or files past the per-revision limit), so a path through them is absent. This is not evidence of safety.",
     failed: "Call-flow analysis failed, so no call trees were built. The diff review is unaffected.",
 };
 /** Call paths drawn per file in Sequence mode before the omitted-path note. */
@@ -267,7 +269,7 @@ function renderJump(files) {
     ].join("\n");
 }
 /** One file section: severity, path, call count and its diff link. */
-function renderFile(view, at) {
+function renderFile(view, at, treeOnly) {
     const { dot, tone, count } = fileFacts(view);
     const status = view.status;
     const diff = `<a class="cf-diff-link" data-open-hunk href="#item-${view.rank}">View diff #${view.rank}</a>`;
@@ -284,8 +286,8 @@ function renderFile(view, at) {
         view.truncated
             ? `<p class="cf-bounds">Bounds reached for this file: ${escapeHtml(BOUNDS_TEXT)}. Calls cut at a bound are omitted.</p>`
             : "",
-        modesNote(),
-        renderModes(view, at),
+        treeOnly ? "" : modesNote(),
+        treeOnly ? renderTreeMode(view, at, false) : renderModes(view, at),
         "</div>",
         "</details>",
     ]
@@ -303,7 +305,7 @@ function renderFile(view, at) {
  */
 function renderModes(view, at) {
     return [
-        renderTreeMode(view, at),
+        renderTreeMode(view, at, true),
         lazyMode("graph", at, renderGraphMode(view, at)),
         lazyMode("sequence", at, renderSequenceMode(view, at)),
     ].join("\n");
@@ -321,10 +323,10 @@ function modesNote() {
         `resolved definition opens on its own. The diff holds every changed line.` +
         `</p></noscript>`);
 }
-function modeSection(mode, at, body) {
+function modeSection(mode, at, body, headed = true) {
     return [
         `<section class="cf-mode cf-mode-${mode}" id="cf-f${at}-${mode}" data-cf-mode-body="${mode}">`,
-        `<h3 class="cf-mode-head">${MODE_LABEL[mode]}</h3>`,
+        headed ? `<h3 class="cf-mode-head">${MODE_LABEL[mode]}</h3>` : "",
         body,
         "</section>",
     ].join("\n");
@@ -333,11 +335,11 @@ function modeSection(mode, at, body) {
 function lazyMode(mode, at, section) {
     return `<template data-cf-lazy-mode="${mode}" data-cf-file="${at}">${section}</template>`;
 }
-function renderTreeMode(view, at) {
+function renderTreeMode(view, at, headed) {
     const trees = view.trees
         .map((tree, root) => renderTreeNode(tree, [root], at, view.file, view.purposes))
         .join("\n");
-    return modeSection("tree", at, `<ul class="cf-tree">${trees}</ul>`);
+    return modeSection("tree", at, `<ul class="cf-tree">${trees}</ul>`, headed);
 }
 /** The resolved definition of one call. It is a native disclosure, so the actual
  *  source is readable without the script, and the script clones this body into

package/dist/review/change-facts.d.ts

@@ -17,6 +17,8 @@
  *
  *   - only file types listed here are read; any other file answers no question
  *     at all, never `no`;
+ *   - a hunk with a changed line longer than {@link MAX_READ_LINE_CHARS} is not
+ *     read either, rather than answered from part of that line;
  *   - `no` means the changed lines the hunk shows contain no such pattern, never
  *     that the property is absent from the file or the program;
  *   - a line moved without change cancels out, because every question compares
@@ -45,7 +47,10 @@ export interface ChangeFactEvidence {
     readonly text: string;
 }
 export interface ChangeFacts {
-    /** Null when this analysis cannot read the file type; then no question is answered. */
+    /**
+     * Null when this analysis does not read the hunk: a file type it cannot read,
+     * or a changed line longer than {@link MAX_READ_LINE_CHARS}. Then no question is answered.
+     */
     readonly language: ChangeFactLanguage | null;
     /**
      * True when the removed and added text are the same once comments and layout
@@ -62,8 +67,23 @@ export interface ChangeFacts {
     readonly answers: Readonly<Partial<Record<ChangeFactQuestion, ChangeFactAnswer>>>;
     readonly evidence: Readonly<Partial<Record<ChangeFactQuestion, ChangeFactEvidence>>>;
 }
+/**
+ * The longest changed line the analysis reads. A longer one is minified or
+ * generated text, or padding that would push a change past any bound on how
+ * much of a line is read, so its hunk is left unread and uncertain instead.
+ */
+export declare const MAX_READ_LINE_CHARS = 4000;
+/** What diffninja does not read in a hunk whose facts have no language, as a phrase after "does not read". */
+export declare function unreadCause(file: string): string;
 export declare function changeFactLanguageOf(file: string): ChangeFactLanguage | null;
 /** The questions a file of this kind is asked; none for an unread type. */
 export declare function factQuestionsFor(language: ChangeFactLanguage | null): readonly ChangeFactQuestion[];
+/**
+ * The line without its `--` comment, as `line.replace(/--.*$/, "")` does it, in
+ * linear time. `.` refuses the four line terminators, so the comment must start
+ * after the last one; the regex rescanned the rest of the line from every `--`
+ * whenever a terminator followed, quadratic on a long line of them.
+ */
+export declare function withoutSqlComment(line: string): string;
 /** The facts for one hunk, each `yes` with the changed line it rests on. */
 export declare function changeFactsOf(unit: Pick<ReviewUnit, "file" | "diff">): ChangeFacts;