@nifrajs/cli 2.14.1 → 3.2.0

package/dist/check.js

@@ -15,1602 +15,16 @@
  * `nifra_check` MCP tool, so an agent acts on diagnostics instead of scraping prose). Exits non-zero if
  * anything fails. Pure scanners (`scanFetchText`, `scanServerOnlyImports`) are unit-tested.
  */
-import { existsSync, readFileSync, realpathSync } from "node:fs";
-import { dirname, isAbsolute, join, resolve, sep } from "node:path";
-import { snapshotProjectEvidence } from "@nifrajs/core/evidence";
-import { Glob } from "bun";
-import { diagnostic } from "./diagnostics.js";
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import { collectCheckDiagnostics, } from "./check-diagnostics.js";
 import { createSourceFacts } from "./internal/source-facts.js";
 import { importProjectTypeScript } from "./internal/typescript-import.js";
-import { freezeProjectFacts } from "./project-facts.js";
 import { RULE_CODES } from "./rules/codes.js";
-import { commentBlockMarkerReason } from "./rules/comment-markers.js";
-import { parseRulePacks, runRuleRegistry, sourceIndex } from "./rules/index.js";
-import { LEGACY_RULE_CODES, legacyRules } from "./rules/legacy.js";
-import { routeRules } from "./rules/routes.js";
-import { securityRules } from "./rules/security.js";
-// `fetch( <ws> ('|"|`) / (not /)` - a string/template arg starting with a single `/` is a relative URL,
-// i.e. same-origin = this app's own API. `(?<![.\w])` skips `.fetch(` (a method) and `prefetch(`; the
-// `(?!\/)` skips protocol-relative `//host` (an external origin). A variable arg (`fetch(url)`) is left
-// alone on purpose - undecidable from source, and flagging it would punish legitimate external calls.
-const GLOBAL_FETCH_CALL = /(?<![.\w])fetch\s*\(/g;
-const FETCH_CALL = /(?<![.\w])fetch\s*\(/g;
-const HTTP_VERBS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD", "OPTIONS"]);
-const SIMPLE_REWRITE_METHODS = new Set(["GET", "DELETE", "HEAD", "OPTIONS"]);
-// Don't scan deps, build output, or generated client entries. `dist(-<runtime>)?` also covers
-// per-runtime output dirs (dist-bun/dist-node/dist-deno/dist-vercel). Never source, for any scan.
-const IGNORED_DIR = /(^|\/)(node_modules|dist(-[a-z0-9]+)?|build|\.nifra|\.git|\.wrangler|coverage)\//;
-// A test/spec module. Excluded from `nifra check`'s scans, which are about what SHIPS - a test
-// legitimately drives `fetch`, hand-rolls a client, and calls a route directly. It is NOT excluded from
-// `nifra doctor`: tsc typechecks tests, so an import a test declares nowhere is a real broken build.
-const TEST_FILE = /\.(test|spec)\.[cm]?[jt]sx?$/;
-const IGNORED = new RegExp(`${IGNORED_DIR.source}|${TEST_FILE.source}`);
-// A file under `routes/` - a page module bundled for the browser, where a server-only import is unsafe.
+import { sourceIndex } from "./rules/index.js";
+import { createProjectSqlImports, resolveServerOnlyChains, scanFetchText, scanInterpolatedSql, scanRemovedImports, scanResponseRoutes, scanServerManifestDrift, scanStaticRouteText, scanUntypedClient, walkSource, } from "./check-scan.js";
+export * from "./check-scan.js";
 const ROUTE_FILE = /(^|\/)routes\//;
-// Module specifiers that must never be VALUE-imported into a route module: node:/bun: builtins, common
-// DB drivers/ORМ server entrypoints, and the conventional `./db` module the scaffold generates.
-const SERVER_ONLY = /^(?:node:|bun:)|^(?:postgres|pg|mysql2|ioredis|redis|better-sqlite3|mongodb|@libsql\/client)$|^drizzle-orm\/(?:node-postgres|postgres-js|bun-sqlite|libsql|mysql2|pglite)\b|^(?:\.\.?\/)+db(?:\.[cm]?[jt]sx?)?$/;
-// A static, non-type import with a string specifier. `import type …` is erased at build, so it's safe
-// and skipped. Dynamic `import(…)` (the correct way to lazy-load server code in a loader) has `(` right
-// after `import`, so `import\s+` never matches it.
-const STATIC_IMPORT = /\bimport\s+(?!type\b)(?:[^'"();]*?\bfrom\s+)?['"]([^'"]+)['"]/g;
-const ROUTE_REGISTRATION_DQ = /\.([A-Za-z]+)\s*\(\s*"((?:\\.|[^"\\])*)"/g;
-const ROUTE_REGISTRATION_SQ = /\.([A-Za-z]+)\s*\(\s*'((?:\\.|[^'\\])*)'/g;
-const IDENT = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
-/** Line number (1-based) of a match index within `content`. */
-const lineAt = (content, index) => content.slice(0, index).split("\n").length;
-function parseQuotedLiteral(raw) {
-    try {
-        return JSON.parse(raw);
-    }
-    catch {
-        if (!raw.startsWith("'") || !raw.endsWith("'"))
-            return undefined;
-        try {
-            // Convert the single-quoted body to a JSON string body by scan, handling backslash pairs
-            // atomically: `\'` becomes `'`, other escapes pass through untouched, and a bare `"` is
-            // escaped. A quote-only `replace` mis-handles content with backslashes (double-escaping
-            // an already-escaped quote, or letting a trailing backslash swallow the added escape).
-            const inner = raw.slice(1, -1);
-            let body = "";
-            for (let i = 0; i < inner.length; i++) {
-                const ch = inner[i];
-                if (ch === "\\" && i + 1 < inner.length) {
-                    const next = inner[i + 1];
-                    body += next === "'" ? "'" : ch + next;
-                    i++;
-                }
-                else if (ch === '"') {
-                    body += '\\"';
-                }
-                else {
-                    body += ch;
-                }
-            }
-            return JSON.parse(`"${body}"`);
-        }
-        catch {
-            return undefined;
-        }
-    }
-}
-function findMatchingParen(src, openIndex) {
-    let depth = 0;
-    let quote;
-    for (let i = openIndex; i < src.length; i++) {
-        const c = src[i];
-        if (quote !== undefined) {
-            if (c === "\\") {
-                i++;
-                continue;
-            }
-            if (c === quote)
-                quote = undefined;
-            continue;
-        }
-        if (c === '"' || c === "'" || c === "`") {
-            quote = c;
-            continue;
-        }
-        if (c === "(")
-            depth++;
-        else if (c === ")") {
-            depth--;
-            if (depth === 0)
-                return i;
-        }
-    }
-    return undefined;
-}
-function splitTopLevelArgs(src) {
-    const args = [];
-    let start = 0;
-    let depth = 0;
-    let quote;
-    for (let i = 0; i < src.length; i++) {
-        const c = src[i];
-        if (quote !== undefined) {
-            if (c === "\\") {
-                i++;
-                continue;
-            }
-            if (c === quote)
-                quote = undefined;
-            continue;
-        }
-        if (c === '"' || c === "'" || c === "`") {
-            quote = c;
-            continue;
-        }
-        if (c === "(" || c === "{" || c === "[")
-            depth++;
-        else if (c === ")" || c === "}" || c === "]")
-            depth--;
-        else if (c === "," && depth === 0) {
-            args.push(src.slice(start, i).trim());
-            start = i + 1;
-        }
-    }
-    if (quote !== undefined || depth !== 0)
-        return undefined;
-    const tail = src.slice(start).trim();
-    if (tail !== "")
-        args.push(tail);
-    return args;
-}
-function parseMethodOnlyInit(raw) {
-    if (raw === undefined)
-        return "GET";
-    const init = raw.trim();
-    if (!/^\{[\s\S]*\}$/.test(init))
-        return undefined;
-    const body = init.slice(1, -1).trim();
-    if (body === "")
-        return "GET";
-    const m = /^(?:"method"|'method'|method)\s*:\s*(["'])([A-Za-z]+)\1\s*,?$/.exec(body);
-    if (!m)
-        return undefined;
-    const method = (m[2] ?? "").toUpperCase();
-    return HTTP_VERBS.has(method) ? method : undefined;
-}
-function parseSimpleFetchCall(snippet) {
-    FETCH_CALL.lastIndex = 0;
-    const matches = [...snippet.matchAll(FETCH_CALL)];
-    if (matches.length !== 1)
-        return undefined;
-    const match = matches[0];
-    if (match === undefined || match.index === undefined)
-        return undefined;
-    const open = match.index + match[0].lastIndexOf("(");
-    const close = findMatchingParen(snippet, open);
-    if (close === undefined)
-        return undefined;
-    const args = splitTopLevelArgs(snippet.slice(open + 1, close));
-    if (args === undefined || args.length === 0 || args.length > 2)
-        return undefined;
-    const first = args[0] ?? "";
-    const quote = first[0];
-    if ((quote !== '"' && quote !== "'") || first[first.length - 1] !== quote)
-        return undefined;
-    const path = parseQuotedLiteral(first);
-    if (path === undefined ||
-        !path.startsWith("/") ||
-        path.startsWith("//") ||
-        path.includes("?") ||
-        path.includes("#")) {
-        return undefined;
-    }
-    const method = parseMethodOnlyInit(args[1]);
-    if (method === undefined)
-        return undefined;
-    return { path, method, start: match.index, end: close + 1 };
-}
-function isPotentialBackendSource(code) {
-    return (code.includes("@nifrajs/core") ||
-        /(?<![.\w])server\s*\(/.test(code) ||
-        /(?:from\s*|import\s*)["']hono["']/.test(code) ||
-        /new\s+Hono(?:<[^>]+>)?\s*\(/.test(code));
-}
-function scanRoutePattern(file, content, code, pattern, facts) {
-    const out = [];
-    const lines = content.split("\n");
-    pattern.lastIndex = 0;
-    for (let m = pattern.exec(code); m !== null; m = pattern.exec(code)) {
-        const method = (m[1] ?? "").toUpperCase();
-        if (!HTTP_VERBS.has(method))
-            continue;
-        const path = parseQuotedLiteral(`${pattern === ROUTE_REGISTRATION_DQ ? '"' : "'"}${m[2] ?? ""}${pattern === ROUTE_REGISTRATION_DQ ? '"' : "'"}`);
-        if (path === undefined || !path.startsWith("/") || path.startsWith("//"))
-            continue;
-        if (facts !== undefined) {
-            const source = facts.parse(file, content);
-            // A parseable source model is authoritative for candidate locations. If parsing is unavailable
-            // or the source is malformed, retain the lexical finding and fail closed.
-            if (source !== undefined &&
-                facts.isRouteRegistrationAt(source, m.index, method, path) !== true)
-                continue;
-        }
-        const line = lineAt(content, m.index);
-        out.push({ file, line, snippet: (lines[line - 1] ?? "").trim(), method, path });
-    }
-    return out;
-}
-/**
- * Blank, with spaces (newlines preserved, so every byte offset - and line number - is unchanged):
- *   - `//` line comments and block comments;
- *   - the CONTENTS of backtick template literals - code-as-text (doc `CodeBlock` examples, code
- *     generators), never a real statement to lint.
- * Single/double-quoted strings are KEPT (a real import/Response specifier lives in one). A small
- * char-state machine, not a full lexer: it doesn't model regex literals, so a regex containing a quote
- * could mis-skip - in practice the constructs these scanners look for sit before any such regex.
- * Shared by the source scanners here and by `nifra doctor` ({@link ./doctor.ts}).
- */
-export function stripComments(src) {
-    const out = src.split("");
-    const n = src.length;
-    let i = 0;
-    const blank = (a, b) => {
-        for (let k = a; k < b; k++)
-            if (out[k] !== "\n")
-                out[k] = " ";
-    };
-    while (i < n) {
-        const c = src[i];
-        const d = src[i + 1];
-        if (c === "/" && d === "/") {
-            let j = i + 2;
-            while (j < n && src[j] !== "\n")
-                j++;
-            blank(i, j);
-            i = j;
-        }
-        else if (c === "/" && d === "*") {
-            let j = i + 2;
-            while (j < n && !(src[j] === "*" && src[j + 1] === "/"))
-                j++;
-            j = Math.min(j + 2, n);
-            blank(i, j);
-            i = j;
-        }
-        else if (c === "`") {
-            let j = i + 1;
-            while (j < n && src[j] !== "`") {
-                if (src[j] === "\\")
-                    j++;
-                j++;
-            }
-            blank(i + 1, j); // keep the backticks, blank the code-as-text inside
-            i = j + 1;
-        }
-        else if (c === "'" || c === '"') {
-            let j = i + 1;
-            while (j < n && src[j] !== c) {
-                if (src[j] === "\\")
-                    j++; // skip the escaped char
-                j++;
-            }
-            i = j + 1;
-        }
-        else {
-            i++;
-        }
-    }
-    return out.join("");
-}
-/** Blank comments and every quoted/template literal while preserving offsets. Unlike
- * {@link stripComments}, this is a code-position mask: scanners use it to find a call expression in
- * executable code, then inspect the original source for the call's literal argument. That prevents
- * documentation strings such as `const example = 'client("/")'` from becoming diagnostics. */
-export function codePositionMask(src) {
-    const out = src.split("");
-    const n = src.length;
-    let i = 0;
-    const blank = (a, b) => {
-        for (let k = a; k < b; k++)
-            if (out[k] !== "\n")
-                out[k] = " ";
-    };
-    while (i < n) {
-        const c = src[i];
-        const d = src[i + 1];
-        if (c === "/" && d === "/") {
-            let j = i + 2;
-            while (j < n && src[j] !== "\n")
-                j++;
-            blank(i, j);
-            i = j;
-        }
-        else if (c === "/" && d === "*") {
-            let j = i + 2;
-            while (j < n && !(src[j] === "*" && src[j + 1] === "/"))
-                j++;
-            j = Math.min(j + 2, n);
-            blank(i, j);
-            i = j;
-        }
-        else if (c === "'" || c === '"' || c === "`") {
-            const quote = c;
-            let j = i + 1;
-            while (j < n && src[j] !== quote) {
-                if (src[j] === "\\")
-                    j++;
-                j++;
-            }
-            j = Math.min(j + 1, n);
-            blank(i, j);
-            i = j;
-        }
-        else {
-            i++;
-        }
-    }
-    return out.join("");
-}
-const firstArgumentIndex = (content, callEnd) => {
-    let index = callEnd;
-    while (/\s/.test(content[index] ?? ""))
-        index++;
-    return index;
-};
-// Read the literal URL path of a `fetch("/…")` call starting at `start` (the index of the leading `/`),
-// stopping at the first quote / query / hash / template-expression boundary, and test it against the
-// allowlist. A template like `/auth/${id}` matches on its literal head (`/auth`), so a dynamic sign-in URL
-// is covered too. Match is segment-anchored - `/auth` blesses `/auth` and `/auth/**`, never `/authors`.
-function matchesExternalMount(content, start, mounts) {
-    let end = start;
-    while (end < content.length) {
-        const ch = content[end];
-        if (ch === "'" || ch === '"' || ch === "`" || ch === "?" || ch === "#")
-            break;
-        if (ch === "$" && content[end + 1] === "{")
-            break;
-        end++;
-    }
-    const path = content.slice(start, end);
-    // A `..` segment means the runtime path escapes the literal prefix (`/auth/../api/admin` resolves to
-    // `/api/admin`), so it must NOT be blessed by an `/auth` mount - never let traversal hide a real own-API
-    // fetch. Match is otherwise segment-anchored (`/auth` blesses `/auth` and `/auth/**`, never `/authors`).
-    try {
-        if (path.split("/").some((segment) => decodeURIComponent(segment) === ".."))
-            return false;
-    }
-    catch {
-        // A malformed escape is not a prefix we can prove stays inside the external mount.
-        return false;
-    }
-    return mounts.some((prefix) => path === prefix || path.startsWith(`${prefix}/`));
-}
-function findTopLevelPropertyColon(src) {
-    let depth = 0;
-    let quote;
-    for (let i = 0; i < src.length; i++) {
-        const c = src[i];
-        if (quote !== undefined) {
-            if (c === "\\") {
-                i++;
-                continue;
-            }
-            if (c === quote)
-                quote = undefined;
-            continue;
-        }
-        if (c === '"' || c === "'" || c === "`") {
-            quote = c;
-            continue;
-        }
-        if (c === "(" || c === "{" || c === "[")
-            depth++;
-        else if (c === ")" || c === "}" || c === "]")
-            depth--;
-        else if (c === ":" && depth === 0)
-            return i;
-    }
-    return undefined;
-}
-function parseStaticPropertyName(raw) {
-    const name = raw.trim();
-    if (IDENT.test(name))
-        return name;
-    const quoted = parseQuotedLiteral(name);
-    if (quoted !== undefined)
-        return quoted;
-    if (name.startsWith("[") && name.endsWith("]")) {
-        return parseQuotedLiteral(name.slice(1, -1).trim());
-    }
-    return undefined;
-}
-/** Return a statically named property from a plain object literal. Deliberately does not follow
- * spreads, identifiers, or helper calls: only an inline literal proves this fetch is Nifra's page-data
- * transport rather than an arbitrary same-origin API request. */
-function staticObjectProperty(raw, name) {
-    if (raw === undefined)
-        return undefined;
-    const object = raw.trim();
-    if (!object.startsWith("{") || !object.endsWith("}"))
-        return undefined;
-    const properties = splitTopLevelArgs(object.slice(1, -1));
-    if (properties === undefined)
-        return undefined;
-    for (const property of properties) {
-        const colon = findTopLevelPropertyColon(property);
-        if (colon === undefined || parseStaticPropertyName(property.slice(0, colon)) !== name)
-            continue;
-        return property.slice(colon + 1).trim();
-    }
-    return undefined;
-}
-function hasLiteralNifraDataHeader(content, openParen) {
-    const closeParen = findMatchingParen(content, openParen);
-    if (closeParen === undefined)
-        return false;
-    const args = splitTopLevelArgs(content.slice(openParen + 1, closeParen));
-    if (args === undefined || args.length !== 2)
-        return false;
-    const headers = staticObjectProperty(args[1], "headers");
-    return staticObjectProperty(headers, "x-nifra-data") !== undefined;
-}
-/** Scan one file's text for hand-rolled own-API `fetch()` calls. Pure + line-accurate. `externalMounts`
- * are intentional non-typed mount prefixes (from `nifra.check.json`, e.g. a mounted better-auth owning
- * `/auth/**`) - a relative fetch into one is deliberate, not drift, so it's skipped. A fetch with an
- * inline literal `x-nifra-data` header is Nifra's page-loader transport, not a backend API call, and is
- * skipped too. */
-export function scanFetchText(file, content, externalMounts = []) {
-    const out = [];
-    const lines = content.split("\n");
-    const code = codePositionMask(content);
-    GLOBAL_FETCH_CALL.lastIndex = 0;
-    for (let m = GLOBAL_FETCH_CALL.exec(code); m !== null; m = GLOBAL_FETCH_CALL.exec(code)) {
-        const argument = firstArgumentIndex(content, m.index + m[0].length);
-        const quote = content[argument];
-        if (quote !== "'" && quote !== '"' && quote !== "`")
-            continue;
-        if (content[argument + 1] !== "/" || content[argument + 2] === "/")
-            continue;
-        const openParen = m.index + m[0].lastIndexOf("(");
-        if (hasLiteralNifraDataHeader(content, openParen))
-            continue;
-        if (externalMounts.length > 0 && matchesExternalMount(content, argument + 1, externalMounts))
-            continue;
-        const line = lineAt(content, m.index);
-        out.push({ file, line, snippet: (lines[line - 1] ?? "").trim() });
-    }
-    return out;
-}
-/** Statically collect simple Nifra route registrations from source, without importing app code. */
-export function scanStaticRouteText(file, content, facts) {
-    const code = stripComments(content);
-    if (!isPotentialBackendSource(code))
-        return [];
-    return [
-        ...scanRoutePattern(file, content, code, ROUTE_REGISTRATION_DQ, facts),
-        ...scanRoutePattern(file, content, code, ROUTE_REGISTRATION_SQ, facts),
-    ].sort(bySite);
-}
-/**
- * SQL built by interpolating a value into the statement text. The value is not a parameter, it is
- * STATEMENT, so anything the caller controls can end the literal and continue as SQL.
- *
- * Two things this deliberately does not flag, because both are safe and flagging them would train
- * people to ignore the rule:
- *
- * - A TAGGED template - ``sql`... ${id} ...` `` in postgres.js, drizzle or kysely. The tag receives the
- *   substitutions separately and binds them; that is the parameterised form, not a bypass of it.
- * - A literal with no substitution at all. `db.query("SELECT … WHERE id = ?")` is the shape being
- *   argued for.
- *
- * A SQL keyword is required in the literal, so `cache.query(`user:${id}`)` stays quiet. The named
- * escape hatches (`$queryRawUnsafe`, `sql.unsafe`) are flagged on the call alone: their whole purpose
- * is to take a statement as text, and a substitution in one is the exact thing the name warns about.
- */
-const SQL_METHODS = new Set([
-    "query",
-    "queryRaw",
-    "prepare",
-    "exec",
-    "execute",
-    "run",
-    "unsafe",
-    "$queryRawUnsafe",
-    "$executeRawUnsafe",
-    "raw",
-]);
-const SQL_KEYWORD = /\b(select|insert\s+into|update|delete\s+from|drop\s+table|create\s+table|alter\s+table|truncate|from|where|values|set|join|union)\b/i;
-const ALWAYS_UNSAFE = new Set(["unsafe", "$queryRawUnsafe", "$executeRawUnsafe", "raw"]);
-/** Read one module's top-level `const` bindings and its import/export edges. Pure syntax - no checker,
- * no filesystem. Destructured names, `let`, `var`, and anything nested stay out on purpose: a
- * module-scope `const` is the only form that provably cannot carry request data. */
-function sqlModuleScope(ts, id, source) {
-    const consts = new Map();
-    const imports = new Map();
-    const localExports = new Map();
-    const reExports = new Map();
-    const starExports = [];
-    for (const statement of source.statements) {
-        if (ts.isVariableStatement(statement)) {
-            if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0)
-                continue;
-            const exported = statement.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) === true;
-            for (const declaration of statement.declarationList.declarations) {
-                if (!ts.isIdentifier(declaration.name) || declaration.initializer === undefined)
-                    continue;
-                consts.set(declaration.name.text, declaration.initializer);
-                if (exported)
-                    localExports.set(declaration.name.text, declaration.name.text);
-            }
-            continue;
-        }
-        if (ts.isImportDeclaration(statement)) {
-            const clause = statement.importClause;
-            if (clause === undefined || clause.isTypeOnly)
-                continue;
-            if (!ts.isStringLiteral(statement.moduleSpecifier))
-                continue;
-            const bindings = clause.namedBindings;
-            // Only `import { X }` / `import { X as local }`. A default or namespace import binds a value
-            // whose contents this scan cannot prove, so it stays unbound and every use of it flags.
-            if (bindings === undefined || !ts.isNamedImports(bindings))
-                continue;
-            for (const element of bindings.elements) {
-                if (element.isTypeOnly)
-                    continue;
-                imports.set(element.name.text, {
-                    specifier: statement.moduleSpecifier.text,
-                    exported: element.propertyName?.text ?? element.name.text,
-                });
-            }
-            continue;
-        }
-        if (!ts.isExportDeclaration(statement) || statement.isTypeOnly)
-            continue;
-        const from = statement.moduleSpecifier;
-        if (from !== undefined && !ts.isStringLiteral(from))
-            continue;
-        const clause = statement.exportClause;
-        if (clause === undefined) {
-            // No clause and a specifier is `export * from "./m"`. `export * as ns from "./m"` carries a
-            // NamespaceExport clause instead and falls out below, unresolved, which is what we want.
-            if (from !== undefined)
-                starExports.push(from.text);
-            continue;
-        }
-        if (!ts.isNamedExports(clause))
-            continue;
-        for (const element of clause.elements) {
-            if (element.isTypeOnly)
-                continue;
-            const local = element.propertyName?.text ?? element.name.text;
-            if (from === undefined)
-                localExports.set(element.name.text, local);
-            else
-                reExports.set(element.name.text, { specifier: from.text, exported: local });
-        }
-    }
-    return { id, consts, imports, localExports, reExports, starExports };
-}
-export const createSqlImports = (load) => ({
-    load,
-    scopes: new Map(),
-});
-/** Parse a module for the SQL scan, or `undefined` when it does not parse. Malformed source is already
- * a typecheck failure; parser recovery nodes are not evidence of anything, so a file that fails to
- * parse contributes no findings and proves no constant. */
-function parseSqlSource(ts, file, content) {
-    const kind = /\.[cm]?tsx?$/.test(file) ? ts.ScriptKind.TSX : ts.ScriptKind.JS;
-    const source = ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true, kind);
-    const parseDiagnostics = source.parseDiagnostics;
-    return parseDiagnostics !== undefined && parseDiagnostics.length > 0 ? undefined : source;
-}
-/** Module-boundary hops one name may cross. Barrels are why it is not 1: `route → index → fragments`
- * already spends two, and the third leaves room for one more layer without letting the scan wander the
- * module graph. Past the cap the name is unresolved, so the interpolation flags. */
-const SQL_IMPORT_HOPS = 3;
-/** Load + parse the module a specifier names, through the run's cache. */
-function loadSqlModuleScope(ts, imports, fromModule, specifier) {
-    const loaded = imports.load(fromModule, specifier);
-    if (loaded === undefined)
-        return undefined;
-    if (imports.scopes.has(loaded.id))
-        return imports.scopes.get(loaded.id);
-    const source = parseSqlSource(ts, loaded.id, loaded.content);
-    const scope = source === undefined ? undefined : sqlModuleScope(ts, loaded.id, source);
-    imports.scopes.set(loaded.id, scope);
-    return scope;
-}
-/**
- * Follow an exported name to its `const` initializer, across re-export hops.
- *
- * Handles the three forms a fragments module actually uses: `export const NAME = …`, the two-statement
- * `const NAME = …; export { NAME }` (including the pass-through `import { A } …; export { A }`), and
- * barrels - `export { X } from "./m"` and `export * from "./m"`. Bounded by {@link SQL_IMPORT_HOPS} and
- * a per-chain visited set, so a cyclic barrel terminates instead of recursing.
- *
- * Two `export *` sources providing the same name is a conflict, and the scan refuses rather than
- * picking one: guessing here would silence a real finding.
- */
-function resolveExportedConst(ts, imports, scope, name, hops, seen) {
-    if (hops > SQL_IMPORT_HOPS)
-        return undefined;
-    const key = `${scope.id}#${name}`;
-    if (seen.has(key))
-        return undefined;
-    const nextSeen = new Set(seen).add(key);
-    const follow = (edge) => {
-        const target = loadSqlModuleScope(ts, imports, scope.id, edge.specifier);
-        return target === undefined
-            ? undefined
-            : resolveExportedConst(ts, imports, target, edge.exported, hops + 1, nextSeen);
-    };
-    const local = scope.localExports.get(name);
-    if (local !== undefined) {
-        const initializer = scope.consts.get(local);
-        if (initializer !== undefined)
-            return { expression: initializer, scope };
-        // `import { A } from "./a"; export { A }` - the same pass-through as `export { A } from "./a"`,
-        // written in two statements. Anything else the name could be (a `let`, a function, a class) has no
-        // initializer in `consts` and no import edge, so it lands on `undefined` and flags.
-        const via = scope.imports.get(local);
-        return via === undefined ? undefined : follow(via);
-    }
-    const reExported = scope.reExports.get(name);
-    if (reExported !== undefined)
-        return follow(reExported);
-    let found;
-    for (const specifier of scope.starExports) {
-        const hit = follow({ specifier, exported: name });
-        if (hit === undefined)
-            continue;
-        if (found !== undefined)
-            return undefined;
-        found = hit;
-    }
-    return found;
-}
-/** Whether `name`, read at `at`, might be re-declared by anything between the read and module scope.
- * Conservative on purpose: the OUTERMOST enclosing function/block subtree is scanned for ANY binding
- * of the name (parameter, `var`/`let`/`const`, catch, local function, destructuring element) - so a
- * hoisted `var` in a sibling block, or a binding in a branch that never runs, still refuses
- * resolution. Over-refusal flags a safe line (the pre-feature behavior); under-refusal would resolve
- * the wrong binding, which is why the cheap-and-broad scan wins over scope simulation. A use with no
- * enclosing function or block reads module scope directly and cannot be shadowed. */
-function isShadowedAt(ts, at, name) {
-    let scope;
-    for (let node = at.parent; node !== undefined; node = node.parent) {
-        if (ts.isSourceFile(node))
-            break;
-        if (ts.isFunctionLike(node) || ts.isBlock(node))
-            scope = node;
-    }
-    if (scope === undefined)
-        return false;
-    const bindsName = (binding) => ts.isIdentifier(binding)
-        ? binding.text === name
-        : binding.elements.some((element) => !ts.isOmittedExpression(element) &&
-            (ts.isIdentifier(element.name) ? element.name.text === name : bindsName(element.name)));
-    let found = false;
-    const scan = (node) => {
-        if (found)
-            return;
-        if ((ts.isVariableDeclaration(node) || ts.isParameter(node)) &&
-            bindsName(node.name)) {
-            found = true;
-            return;
-        }
-        if (ts.isFunctionDeclaration(node) && node.name?.text === name) {
-            found = true;
-            return;
-        }
-        ts.forEachChild(node, scan);
-    };
-    scan(scope);
-    return found;
-}
-const CONST_RESOLUTION_DEPTH = 5;
-/**
- * Resolve an interpolated expression to compile-time text, or `undefined` when it can carry runtime
- * data. Pure syntax, no type checker - the same honest limit the rule already documents. What
- * resolves: string/number literals, no-substitution templates, templates whose every span resolves,
- * ternaries with both branches resolvable (BOTH branch texts are returned, so a hostile keyword in
- * either still feeds the keyword scan), `as`/`satisfies` wrappers, a module-scope `const` whose
- * initializer resolves (recursively, depth-capped), and - when `scope.imports` is configured - such a
- * `const` imported by name from another in-project module. Everything else - `let`, a parameter, a
- * call, a member access, a shadowed name, a bare-specifier import - stays unresolved and the
- * interpolation is flagged exactly as before.
- */
-function resolveStaticSqlText(ts, node, scope, depth) {
-    if (depth > CONST_RESOLUTION_DEPTH)
-        return undefined;
-    if (ts.isParenthesizedExpression(node)) {
-        return resolveStaticSqlText(ts, node.expression, scope, depth);
-    }
-    if (ts.isAsExpression(node) || ts.isSatisfiesExpression(node)) {
-        return resolveStaticSqlText(ts, node.expression, scope, depth);
-    }
-    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
-        return node.text;
-    if (ts.isNumericLiteral(node))
-        return node.text;
-    if (ts.isTemplateExpression(node)) {
-        let text = node.head.text;
-        for (const span of node.templateSpans) {
-            const part = resolveStaticSqlText(ts, span.expression, scope, depth + 1);
-            if (part === undefined)
-                return undefined;
-            text += part + span.literal.text;
-        }
-        return text;
-    }
-    if (ts.isConditionalExpression(node)) {
-        const whenTrue = resolveStaticSqlText(ts, node.whenTrue, scope, depth + 1);
-        const whenFalse = resolveStaticSqlText(ts, node.whenFalse, scope, depth + 1);
-        if (whenTrue === undefined || whenFalse === undefined)
-            return undefined;
-        return `${whenTrue} ${whenFalse}`;
-    }
-    if (ts.isIdentifier(node)) {
-        const initializer = scope.module.consts.get(node.text);
-        const edge = initializer === undefined ? scope.module.imports.get(node.text) : undefined;
-        // Membership first: `isShadowedAt` walks a subtree, and most identifiers in a query are neither a
-        // module const nor an import binding.
-        if (initializer === undefined && edge === undefined)
-            return undefined;
-        // Shadowing is a property of where the identifier is WRITTEN, so one check is right on both sides
-        // of an import hop: an initializer in the imported module sits at module scope with nothing above
-        // it to shadow it, while a use inside a function in this file is still refused.
-        if (isShadowedAt(ts, node, node.text))
-            return undefined;
-        if (initializer !== undefined)
-            return resolveStaticSqlText(ts, initializer, scope, depth + 1);
-        if (edge === undefined || scope.imports === undefined)
-            return undefined;
-        const target = loadSqlModuleScope(ts, scope.imports, scope.module.id, edge.specifier);
-        if (target === undefined)
-            return undefined;
-        const exported = resolveExportedConst(ts, scope.imports, target, edge.exported, 1, new Set());
-        if (exported === undefined)
-            return undefined;
-        // The imported initializer's own identifiers read THAT module's consts, never this file's. A
-        // caller that happens to have its own `const DIR` must not silently supply the fragment's `DIR`,
-        // which is the one way cross-module resolution could resolve to text nobody wrote.
-        return resolveStaticSqlText(ts, exported.expression, { module: exported.scope, imports: scope.imports }, depth + 1);
-    }
-    return undefined;
-}
-/** A template's contribution to the shape: resolved span texts fold into `staticText` (so the
- * keyword scan still sees what a `const` carries); any unresolvable span keeps it `dynamic`. */
-function templateShape(ts, template, scope) {
-    let staticText = template.head.text;
-    let dynamic = false;
-    for (const span of template.templateSpans) {
-        const resolved = scope === undefined ? undefined : resolveStaticSqlText(ts, span.expression, scope, 0);
-        if (resolved === undefined)
-            dynamic = true;
-        else
-            staticText += resolved;
-        staticText += span.literal.text;
-    }
-    return { staticText, dynamic };
-}
-/** Whether `name` is written to anywhere in the file - a plain, compound, or `++`/`--` assignment to a
- * bare identifier of that name. A `let` that is is over-cautiously refused (it might be reassigned from
- * request data); a `const` never needs this. Over-refusal only ever leaves an interpolation flagged as
- * before, never the reverse. */
-function isReassignedInFile(ts, source, name) {
-    let found = false;
-    const visit = (node) => {
-        if (found)
-            return;
-        if (ts.isBinaryExpression(node) &&
-            node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
-            node.operatorToken.kind <= ts.SyntaxKind.LastAssignment &&
-            ts.isIdentifier(node.left) &&
-            node.left.text === name) {
-            found = true;
-            return;
-        }
-        if ((ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) &&
-            (node.operator === ts.SyntaxKind.PlusPlusToken ||
-                node.operator === ts.SyntaxKind.MinusMinusToken) &&
-            ts.isIdentifier(node.operand) &&
-            node.operand.text === name) {
-            found = true;
-            return;
-        }
-        ts.forEachChild(node, visit);
-    };
-    visit(source);
-    return found;
-}
-/** Does `binding` bind `name` (as a plain identifier or nested inside a destructuring pattern)? Mirrors
- * the pattern walk in {@link isShadowedAt}. */
-function bindingNameCovers(ts, binding, name) {
-    return ts.isIdentifier(binding)
-        ? binding.text === name
-        : binding.elements.some((element) => !ts.isOmittedExpression(element) &&
-            (ts.isIdentifier(element.name)
-                ? element.name.text === name
-                : bindingNameCovers(ts, element.name, name)));
-}
-/** Inspect the bindings a single scope node introduces DIRECTLY (not nested) for `name`: parameters and
- * catch variables of a function/catch, `var`/`let`/`const` and function/class declarations of a
- * statement list. Returns the readable initializer, `"shadow"` for a form we cannot read through, or
- * `undefined` when this scope does not bind the name at all. */
-function directBinding(ts, source, scope, name) {
-    if (ts.isFunctionLike(scope)) {
-        for (const parameter of scope.parameters) {
-            if (bindingNameCovers(ts, parameter.name, name))
-                return "shadow";
-        }
-    }
-    if (ts.isCatchClause(scope)) {
-        const declared = scope.variableDeclaration;
-        if (declared !== undefined && bindingNameCovers(ts, declared.name, name))
-            return "shadow";
-    }
-    const statements = ts.isSourceFile(scope)
-        ? scope.statements
-        : ts.isBlock(scope) || ts.isModuleBlock(scope)
-            ? scope.statements
-            : ts.isCaseClause(scope) || ts.isDefaultClause(scope)
-                ? scope.statements
-                : undefined;
-    const lists = [];
-    if (statements !== undefined) {
-        for (const statement of statements) {
-            if (ts.isVariableStatement(statement))
-                lists.push(statement.declarationList);
-            if ((ts.isFunctionDeclaration(statement) || ts.isClassDeclaration(statement)) &&
-                statement.name?.text === name) {
-                return "shadow";
-            }
-        }
-    }
-    if ((ts.isForStatement(scope) || ts.isForInStatement(scope) || ts.isForOfStatement(scope)) &&
-        scope.initializer !== undefined &&
-        ts.isVariableDeclarationList(scope.initializer)) {
-        lists.push(scope.initializer);
-    }
-    for (const list of lists) {
-        for (const declaration of list.declarations) {
-            if (!bindingNameCovers(ts, declaration.name, name))
-                continue;
-            // A destructured or uninitialized binding, or a `var` (hoisting + reassignment risk), is not a
-            // value we can read one expression out of.
-            if (!ts.isIdentifier(declaration.name) || declaration.initializer === undefined)
-                return "shadow";
-            const isConst = (list.flags & ts.NodeFlags.Const) !== 0;
-            const isLet = (list.flags & ts.NodeFlags.Let) !== 0;
-            if (isConst)
-                return { initializer: declaration.initializer };
-            if (isLet && !isReassignedInFile(ts, source, name))
-                return { initializer: declaration.initializer };
-            return "shadow";
-        }
-    }
-    return undefined;
-}
-/**
- * Resolve a query-call ARGUMENT identifier to the expression it was initialized from, so a statement
- * parked in a variable is scanned as if it had been written inline at the call. This is the counterpart
- * to {@link resolveStaticSqlText}: that folds a const's text INTO a template's shape; this unfolds the
- * whole statement back out of the variable it was lifted into. Without it, ANY interpolated-SQL finding
- * could be silenced, invisibly, by hoisting the statement to `const q = …` first.
- *
- * Same-file only. Nearest enclosing declaration wins, so a shadowing local is read and never a
- * same-named module const. Reads through a `const`, or a `let` the file never reassigns, at function or
- * module scope; transitive through an identifier-valued initializer; depth-capped. A parameter, an
- * imported or destructured binding, a reassigned `let`, a `var`, or a name with no same-file
- * declaration returns `undefined` - which leaves the argument scanned as itself (unflagged unless it is
- * a module const that resolves to static text: exactly the pre-feature behavior).
- */
-function resolveArgumentInitializer(ts, node, depth) {
-    if (depth > CONST_RESOLUTION_DEPTH)
-        return undefined;
-    const source = node.getSourceFile();
-    const name = node.text;
-    for (let scope = node.parent; scope !== undefined; scope = scope.parent) {
-        const binding = directBinding(ts, source, scope, name);
-        if (binding === "shadow")
-            return undefined;
-        if (binding !== undefined) {
-            let init = binding.initializer;
-            while (ts.isParenthesizedExpression(init))
-                init = init.expression;
-            return ts.isIdentifier(init) ? resolveArgumentInitializer(ts, init, depth + 1) : init;
-        }
-        if (ts.isSourceFile(scope))
-            break;
-    }
-    return undefined;
-}
-/** Describe only the first argument's syntax; comments/strings elsewhere cannot influence the result. */
-function sqlExpressionShape(ts, node, scope) {
-    if (ts.isParenthesizedExpression(node))
-        return sqlExpressionShape(ts, node.expression, scope);
-    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
-        return {
-            staticText: node.text,
-            dynamic: false,
-            concatenated: false,
-            literal: true,
-            parameterizedTag: false,
-        };
-    }
-    if (ts.isTaggedTemplateExpression(node)) {
-        const tag = node.tag;
-        const parameterizedTag = (ts.isIdentifier(tag) && tag.text === "sql") ||
-            (ts.isPropertyAccessExpression(tag) && tag.getText() === "Prisma.sql");
-        const template = node.template;
-        const templated = ts.isTemplateExpression(template)
-            ? templateShape(ts, template, parameterizedTag ? undefined : scope)
-            : { staticText: template.text, dynamic: false };
-        const staticText = templated.staticText;
-        // Only the ecosystem's binding tags are trusted, by NAME - which is the honest limit of a scanner
-        // that reads syntax and runs no type checker. `sql` is what postgres.js, drizzle, slonik and Bun's
-        // own driver all call theirs, and `Prisma.sql` is Prisma's; taking those at their word is a
-        // deliberate trade, and it is worth stating what it costs: a no-op function named `sql` in the
-        // same file is trusted too, so this rule finds mistakes, not an adversary who reads it first.
-        //
-        // Trusting anything else widens that for no gain. This list briefly also held `sqlIdentifiers`,
-        // a name invented for Nifra's own adapters - a second forgeable name that no user has a
-        // convention for, added so Nifra's source would pass its own rule. Names earn their place here by
-        // being what drivers already call the thing, not by being convenient for the framework.
-        //
-        // Everything else - `String.raw`, an identity tag, a member access that merely ends in `.sql` -
-        // is treated as plain interpolation.
-        return {
-            staticText,
-            dynamic: templated.dynamic && !parameterizedTag,
-            concatenated: false,
-            literal: !ts.isTemplateExpression(template),
-            parameterizedTag,
-        };
-    }
-    if (ts.isTemplateExpression(node)) {
-        const templated = templateShape(ts, node, scope);
-        return {
-            staticText: templated.staticText,
-            dynamic: templated.dynamic,
-            concatenated: false,
-            literal: false,
-            parameterizedTag: false,
-        };
-    }
-    if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
-        const left = sqlExpressionShape(ts, node.left, scope);
-        const right = sqlExpressionShape(ts, node.right, scope);
-        return {
-            staticText: left.staticText + right.staticText,
-            // A resolved const operand is static text, not a dynamic part - so the old `!literal` test
-            // narrows to what it always actually meant: an operand that carries runtime data (dynamic) or
-            // a binding tag being concatenated into plain text (which un-parameterizes it).
-            dynamic: left.dynamic || right.dynamic || left.parameterizedTag || right.parameterizedTag,
-            concatenated: true,
-            literal: left.literal && right.literal,
-            parameterizedTag: false,
-        };
-    }
-    // A resolvable expression (a module-`const` name, a literal ternary) contributes its compile-time
-    // text and stays non-dynamic - this is what lets `"SELECT " + COLS + " FROM t"` and
-    // `db.query(`${COLS} FROM t WHERE id = $1`)` pass while a mutable or unprovable name still flags.
-    // `literal` stays false: the named escape hatches (`unsafe`, `$queryRawUnsafe`) keep flagging a
-    // resolved const, because taking statement text from ANY variable is what their rule warns about.
-    if (scope !== undefined) {
-        const resolved = resolveStaticSqlText(ts, node, scope, 0);
-        if (resolved !== undefined) {
-            return {
-                staticText: resolved,
-                dynamic: false,
-                concatenated: false,
-                literal: false,
-                parameterizedTag: false,
-            };
-        }
-    }
-    // A bare name that did not resolve to compile-time text. If it is a same-file binding we can prove
-    // holds one expression, scan THAT expression's shape - so a statement hoisted into `const q = …` is
-    // read exactly as if it were written inline at the call, closing the "extract a variable to launder
-    // the finding" hole. `literal` is forced false: the value arrived through a variable, which is the
-    // property the `unsafe`/`$queryRawUnsafe` hatch rule keys on.
-    if (ts.isIdentifier(node)) {
-        const initializer = resolveArgumentInitializer(ts, node, 0);
-        if (initializer !== undefined) {
-            return { ...sqlExpressionShape(ts, initializer, scope), literal: false };
-        }
-    }
-    return {
-        staticText: "",
-        dynamic: true,
-        concatenated: false,
-        literal: false,
-        parameterizedTag: false,
-    };
-}
-function sqlMethod(ts, call) {
-    if (ts.isPropertyAccessExpression(call.expression)) {
-        const method = call.expression.name.text;
-        return SQL_METHODS.has(method)
-            ? { method, receiver: call.expression.expression.getText() }
-            : undefined;
-    }
-    if (ts.isElementAccessExpression(call.expression) &&
-        call.expression.argumentExpression !== undefined &&
-        ts.isStringLiteral(call.expression.argumentExpression)) {
-        const method = call.expression.argumentExpression.text;
-        return SQL_METHODS.has(method)
-            ? { method, receiver: call.expression.expression.getText() }
-            : undefined;
-    }
-    return undefined;
-}
-const SQL_RECEIVER = /(?:^|\.)(?:db|sql|prisma|drizzle|database|conn|connection|client|tx)$/i;
-/** The opt-out pragma that silences one interpolated-SQL finding. Written `// nifra-expect sql-dynamic:
- * <reason>` on the flagged line or in the comment block directly above it; the reason after the colon
- * is mandatory (see {@link commentBlockMarkerReason}). Scoped to the single statement it sits on. */
-const SQL_DYNAMIC_PRAGMA = "nifra-expect sql-dynamic";
-/**
- * Scan one file's text for SQL assembled by interpolation. Pure + line-accurate.
- *
- * `imports` opts into following a fragment `const` into another module. Without it the scan is
- * same-file only, which is what the unit tests exercise and what any caller that has no module graph
- * to offer gets. With it, only what {@link createProjectSqlImports} will hand back is followed.
- */
-export function scanInterpolatedSql(file, content, ts, imports) {
-    const out = [];
-    const lines = content.split("\n");
-    // Malformed source is already a typecheck failure. Do not turn parser recovery nodes into a second,
-    // misleading SQL diagnostic (notably an unterminated template recovered as an interpolation).
-    const source = parseSqlSource(ts, file, content);
-    if (source === undefined)
-        return out;
-    // Module-scope bindings, read once per file: an interpolated `const` that resolves to compile-time
-    // text cannot carry request data, so the shared-projection idiom (`const COLS = "id, name"` …
-    // `${COLS}`) stays quiet while mutable, parameter, shadowed, and unprovable names flag as before.
-    const scope = { module: sqlModuleScope(ts, file, source), imports };
-    const visit = (node) => {
-        if (ts.isCallExpression(node)) {
-            const sink = sqlMethod(ts, node);
-            const argument = node.arguments[0];
-            if (sink !== undefined && argument !== undefined) {
-                const shape = sqlExpressionShape(ts, argument, scope);
-                const unsafeEscape = ALWAYS_UNSAFE.has(sink.method) && !shape.literal && !shape.parameterizedTag;
-                const assembledSql = shape.dynamic &&
-                    (SQL_KEYWORD.test(shape.staticText) ||
-                        (shape.concatenated && SQL_RECEIVER.test(sink.receiver)));
-                if (unsafeEscape || assembledSql) {
-                    const index = node.getStart(source);
-                    const line = source.getLineAndCharacterOfPosition(index).line + 1;
-                    // Sanctioned escape hatch for genuinely-dynamic-but-bound SQL (batch VALUES placeholder
-                    // generation, an allowlisted identifier). The reason is mandatory: a bare `// nifra-expect
-                    // sql-dynamic` with no reason after the colon does NOT silence, so the hatch always leaves a
-                    // greppable audit trail instead of becoming a second laundering trick.
-                    const silenced = commentBlockMarkerReason(lines, line, SQL_DYNAMIC_PRAGMA) !== undefined;
-                    if (!silenced)
-                        out.push({ file, line, snippet: (lines[line - 1] ?? "").trim() });
-                }
-            }
-        }
-        ts.forEachChild(node, visit);
-    };
-    visit(source);
-    return out;
-}
-/**
- * Collect interpolated-SQL findings across the project.
- *
- * Returns `undefined` - not an empty array - when TypeScript is not installed. The rule parses source
- * with the compiler, so without it there is nothing to report and, more to the point, no basis for
- * reporting nothing. An empty result would read as "no interpolated SQL found", which is the one
- * answer a security rule must never give when it did not run.
- */
-export async function scanProjectSql(cwd) {
-    const ts = await importProjectTypeScript(cwd);
-    if (ts === undefined)
-        return undefined;
-    const out = [];
-    const imports = createProjectSqlImports(cwd);
-    await walkSource(cwd, (rel, content) => out.push(...scanInterpolatedSql(rel, content, ts, imports)));
-    return out.sort(bySite);
-}
-/** A declaration file. Excluded from cross-module resolution: `declare const X: string` has no
- * initializer to read, so following one could only ever produce a "proved" the source never wrote. */
-const SQL_DECLARATION_FILE = /\.d\.[cm]?ts$/;
-/** The extensions the SQL scan will parse - the same set {@link walkSource} globs. */
-const SQL_SOURCE_FILE = /\.[cm]?tsx?$/;
-/**
- * The on-disk loader for cross-module `const` resolution, scoped to one project.
- *
- * Deliberately narrow, because every widening here is a way for a real finding to go quiet:
- *
- * - **Relative specifiers only.** A bare specifier names a dependency whose exports can change without
- *   this project changing, so "provably a `const` string" is not a property the project owns.
- * - **Inside `cwd`, outside the ignored trees.** The resolved path is realpath'd and must still sit
- *   under the project root: a symlink pointing out of the tree is not source this scan reads. The
- *   `node_modules` / `dist` / build exclusions are the same ones the walk applies.
- * - **Real source only.** A `.d.ts` carries no initializer, and a non-TS file is not parsed.
- *
- * A miss on any of those returns `undefined`, which leaves the name unresolved and the interpolation
- * flagged - the pre-feature answer.
- */
-export function createProjectSqlImports(cwd) {
-    const root = (() => {
-        try {
-            return realpathSync(resolve(cwd));
-        }
-        catch {
-            return resolve(cwd);
-        }
-    })();
-    return createSqlImports((fromModule, specifier) => {
-        if (!isRelativeSpecifier(specifier))
-            return undefined;
-        try {
-            // `fromModule` is the cwd-RELATIVE path the walk supplies for an entry file, and ABSOLUTE for
-            // every module reached through a hop (their ids are the resolved paths).
-            const fromAbs = isAbsolute(fromModule) ? fromModule : join(root, fromModule);
-            const resolved = realpathSync(Bun.resolveSync(specifier, dirname(fromAbs)));
-            if (!resolved.startsWith(root + sep))
-                return undefined;
-            const rel = resolved.slice(root.length + 1);
-            if (IGNORED_DIR.test(rel))
-                return undefined;
-            if (SQL_DECLARATION_FILE.test(resolved) || !SQL_SOURCE_FILE.test(resolved))
-                return undefined;
-            return { id: resolved, content: readFileSync(resolved, "utf8") };
-        }
-        catch {
-            return undefined; // unresolvable, unreadable, or outside the project
-        }
-    });
-}
-// `client("` / `client('` / `client(\`` - a URL-first call WITHOUT the `<typeof app>` generic:
-// the compiler has nothing to derive types from, so the anti-drift guarantee silently vanishes.
-// `client<typeof app>("…")` has `<…>` between the name and `(` so it never matches; the published-
-// contract form `client(contract, url)` starts with an identifier, not a quote - also unmatched.
-const CLIENT_CALL = /(?<![.\w])client\s*\(/g;
-/** Scan one file's text for untyped `client("…")` calls. Pure + line-accurate. */
-export function scanUntypedClient(file, content) {
-    const out = [];
-    const lines = content.split("\n");
-    const code = codePositionMask(content);
-    CLIENT_CALL.lastIndex = 0;
-    for (let m = CLIENT_CALL.exec(code); m !== null; m = CLIENT_CALL.exec(code)) {
-        const argument = firstArgumentIndex(content, m.index + m[0].length);
-        const quote = content[argument];
-        if (quote !== "'" && quote !== '"' && quote !== "`")
-            continue;
-        const line = lineAt(content, m.index);
-        out.push({ file, line, snippet: (lines[line - 1] ?? "").trim() });
-    }
-    return out;
-}
-/**
- * Specifiers that no longer exist, and what replaced them.
- *
- * These are the breaks a typecheck does not catch and a test suite does not either. `@nifrajs/core/ws`
- * was a side-effect import removed in 2.0 in favour of `.use(websocket())`; a consuming package kept
- * the import and a 533-test suite stayed green while the app could not boot. `@nifrajs/budget` folded
- * into core with no npm deprecation, so `bun install` fails workspace-wide with a resolution error
- * that names neither the cause nor the replacement.
- *
- * A lint is the right shape for this: it runs before boot, names the file and line, and states the
- * replacement - which is what neither the resolver error nor the runtime failure does.
- */
-const REMOVED_IMPORTS = [
-    {
-        specifier: "@nifrajs/budget",
-        since: "2.0",
-        replacement: 'import from "@nifrajs/core/budget" - the package folded into core and npm `latest` is still 1.13.0, so a `^2` range resolves to nothing',
-    },
-    {
-        specifier: "@nifrajs/core/ws",
-        since: "2.0",
-        sideEffectOnly: true,
-        replacement: 'a bare `import "@nifrajs/core/ws"` no longer installs the runtime - register it explicitly with `.use(websocket())`, importing `websocket` from the same module',
-    },
-];
-/** Whether the import statement at `index` is the bare side-effect form (`import "x"`), rather than
- * one with bindings (`import { y } from "x"`). */
-function isSideEffectImport(content, index) {
-    // `staticImportEdges` reports the index of the STATEMENT, not of the specifier, so read forward:
-    // a side-effect import is `import` followed directly by the quoted specifier, with no bindings and
-    // no `from` in between.
-    return /^import\s*["'`]/.test(content.slice(index, index + 32));
-}
-/** Flag an import of a specifier that no longer exists. Pure; matches the exact specifier or a subpath
- * of it, so `@nifrajs/budget/x` is caught alongside `@nifrajs/budget`. */
-export function scanRemovedImports(file, content) {
-    const out = [];
-    const lines = content.split("\n");
-    for (const edge of staticImportEdges(content)) {
-        const removed = REMOVED_IMPORTS.find((entry) => edge.specifier === entry.specifier || edge.specifier.startsWith(`${entry.specifier}/`));
-        if (removed === undefined)
-            continue;
-        if (removed.sideEffectOnly === true && !isSideEffectImport(content, edge.index))
-            continue;
-        const line = lineAt(content, edge.index);
-        out.push({ file, line, snippet: (lines[line - 1] ?? "").trim() });
-    }
-    return out;
-}
-/** Scan a route module for top-level server-only imports. Returns `[]` for non-route files (only
- * `routes/` modules are browser-bundled, so a server-only import elsewhere is fine). Each finding carries
- * the offending `specifier` so the diagnostic can render the `routeFile → specifier` chain. Pure. */
-export function scanServerOnlyImports(file, content, facts) {
-    if (!ROUTE_FILE.test(file))
-        return [];
-    const out = [];
-    const lines = content.split("\n");
-    const code = stripComments(content);
-    const positions = codePositionMask(content);
-    STATIC_IMPORT.lastIndex = 0;
-    for (let m = STATIC_IMPORT.exec(code); m !== null; m = STATIC_IMPORT.exec(code)) {
-        if (positions[m.index] === " ")
-            continue;
-        const specifier = m[1] ?? "";
-        if (!SERVER_ONLY.test(specifier))
-            continue;
-        if (facts !== undefined) {
-            const source = facts.parse(file, content);
-            // Inline `import { type X } from "…"` is erased just like `import type`; don't call it a
-            // runtime leak. A parse failure keeps the old lexical finding so the security rule fails closed.
-            if (source !== undefined && facts.isValueImportAt(source, m.index, specifier) === false)
-                continue;
-        }
-        const line = lineAt(content, m.index);
-        out.push({ file, line, snippet: (lines[line - 1] ?? "").trim(), specifier });
-    }
-    return out;
-}
-// ---------------------------------------------------------------------------------------------------
-// #4.4 - TRANSITIVE import-chain resolution for `server-only-import`. `scanServerOnlyImports` above is a
-// pure per-file regex scan: it sees only the route's DIRECT `import` line, so it reports the direct edge
-// `routes/x → ../db`. The build leak-guard, which has the real module graph, reports the full transitive
-// `route → ../data → ../db → pg`. These helpers give `nifra check` the same depth via a BOUNDED
-// import-resolution walk: from a flagged route, resolve its local imports (`Bun.resolveSync`), BFS the
-// local module graph, and build the shortest chain to a server-only SINK. It's best-effort: an import
-// that can't be precisely resolved (a bare pkg, a tsconfig path alias) falls back to the direct edge.
-// ---------------------------------------------------------------------------------------------------
-// Server-only specifiers that are TERMINAL sinks - a bare `node:`/`bun:` builtin or a known server-only
-// npm package. These are never local source we can walk into, so the chain ends here. (Same vocabulary
-// as SERVER_ONLY, minus the relative `../db` arm - a relative `db` module IS local source we resolve.)
-const SERVER_ONLY_SINK = /^(?:node:|bun:)|^(?:postgres|pg|mysql2|ioredis|redis|better-sqlite3|mongodb|@libsql\/client)$|^drizzle-orm\/(?:node-postgres|postgres-js|bun-sqlite|libsql|mysql2|pglite)\b/;
-// The `.server` convention: a module named `*.server.ts(x)` is server-only (the client build empties it).
-const SERVER_MODULE_FILE = /\.server(\.[cm]?[jt]sx?)?$/;
-// The explicit poison-import marker (`@nifrajs/web/server-only`) - a module opting into the client-leak
-// guard. A resolved file whose source carries this side-effect import is a server-only sink.
-const SERVER_ONLY_MARKER_IMPORT = /import\s+["']@nifrajs\/web\/server-only["']/;
-// Depth/visited caps keep the walk linear + cycle-safe. A route's server-only dependency sits within a
-// few hops in practice; the bound stops a pathological graph from blowing up the per-file scan.
-const TRANSITIVE_MAX_DEPTH = 8;
-const TRANSITIVE_MAX_VISITED = 200;
-/** A relative module specifier (`./x`, `../y`) - the only kind we resolve + walk into (a bare specifier
- * is either a sink we recognise by name or a third-party dep we don't follow into node_modules). */
-const isRelativeSpecifier = (spec) => spec.startsWith("./") || spec.startsWith("../");
-// A FRESH copy of the static-import regex per scan. The transitive walk is REENTRANT - the outer
-// per-route loop and the inner BFS both scan imports - and a single shared global-flag regex carries
-// `lastIndex` state, so reusing the module-level `STATIC_IMPORT` across nested calls corrupts the outer
-// loop's position (it restarts forever). A fresh instance per call keeps each scan's state private.
-const staticImportRegex = () => new RegExp(STATIC_IMPORT.source, STATIC_IMPORT.flags);
-/** Extract the static, non-type import specifiers from a module's source (the edges to follow/inspect),
- * each with the match index (for line attribution). Mirrors {@link STATIC_IMPORT}, so `import type` +
- * dynamic `import()` are already excluded. Uses a fresh regex instance, so it's safe under the reentrant
- * transitive walk. Pure. */
-function staticImportEdges(content, facts, file) {
-    const edges = [];
-    const re = staticImportRegex();
-    const code = stripComments(content);
-    const positions = codePositionMask(content);
-    for (let m = re.exec(code); m !== null; m = re.exec(code)) {
-        if (positions[m.index] === " ")
-            continue;
-        if (m[1] === undefined)
-            continue;
-        if (facts !== undefined && file !== undefined) {
-            const source = facts.parse(file, content);
-            if (source !== undefined && facts.isValueImportAt(source, m.index, m[1]) === false)
-                continue;
-        }
-        edges.push({ specifier: m[1], index: m.index });
-    }
-    return edges;
-}
-/** Extract the static, non-type import specifiers from a module's source (the edges to follow/inspect).
- * Mirrors {@link STATIC_IMPORT}, so `import type` + dynamic `import()` are already excluded. Pure. */
-export function parseStaticImports(content, facts, file) {
-    return staticImportEdges(content, facts, file).map((e) => e.specifier);
-}
-/** The server-only SINK an import specifier names directly (a `node:`/`bun:` builtin or a known
- * server-only package), or `undefined` if it isn't a by-name sink. Pure - the label is the specifier
- * itself (it's already the actionable name). */
-export function directSinkSpecifier(spec) {
-    return SERVER_ONLY_SINK.test(spec) ? spec : undefined;
-}
-/**
- * BFS the LOCAL module graph from a route file for the SHORTEST import chain that reaches a server-only
- * sink, returning `[routeFile, …as-written specifiers…, sink]` or `undefined` if none is reachable. A
- * node's outgoing edges are its static imports; an edge is followed only when it's a RELATIVE specifier
- * that `resolve` maps to a readable local file (so the walk never descends into node_modules or chases an
- * unresolvable alias). At each node, a by-name sink import (`node:fs`, `postgres`) OR a resolved
- * `*.server` / `server-only`-marked dependency terminates the chain. Bounded by depth + a visited set, so
- * it's linear and cycle-free. `routeFile`/`routeContent` seed the walk; `resolve`/`read` supply the graph
- * - pure given those, so it's unit-testable with a fake graph.
- */
-export function walkServerOnlyChain(routeFile, routeContent, resolve, read, facts) {
-    const seen = new Set([routeFile]);
-    let frontier = [{ abs: routeFile, content: routeContent, chain: [routeFile], depth: 0 }];
-    let visited = 0;
-    while (frontier.length > 0) {
-        const next = [];
-        for (const node of frontier) {
-            if (node.depth >= TRANSITIVE_MAX_DEPTH)
-                continue;
-            for (const spec of parseStaticImports(node.content, facts, node.abs)) {
-                // (a) A by-name sink (builtin / known server-only pkg) → the chain ends here (shortest first,
-                // since BFS reaches the nearest sink before any deeper one).
-                const sink = directSinkSpecifier(spec);
-                if (sink !== undefined)
-                    return [...node.chain, sink];
-                // (b) Only relative specifiers are local source we resolve + walk into. A bare third-party
-                // specifier that isn't a known sink is a leaf - don't follow it into node_modules.
-                if (!isRelativeSpecifier(spec))
-                    continue;
-                const abs = resolve(node.abs, spec);
-                if (abs === undefined || seen.has(abs))
-                    continue;
-                // (c) A resolved `*.server` module is a server-only sink by the `.server` convention - the chain
-                // ends at it (named by the as-written specifier).
-                if (SERVER_MODULE_FILE.test(abs))
-                    return [...node.chain, spec];
-                const content = read(abs);
-                if (content === undefined)
-                    continue; // unreadable → can't walk; treat as a leaf
-                // (d) A resolved module that opts into the `server-only` marker is a sink too.
-                if (SERVER_ONLY_MARKER_IMPORT.test(content))
-                    return [...node.chain, spec];
-                if (visited >= TRANSITIVE_MAX_VISITED)
-                    continue;
-                visited++;
-                seen.add(abs);
-                next.push({ abs, content, chain: [...node.chain, spec], depth: node.depth + 1 });
-            }
-        }
-        frontier = next;
-    }
-    return undefined;
-}
-/**
- * Resolve the FULL transitive server-only chain(s) for a route module, given a real fs-backed resolver +
- * reader. For each of the route's top-level imports, if a precise transitive walk finds a sink, the
- * finding carries the full chain; otherwise - when the first hop is itself a direct by-name sink the
- * regex scan already flags, or when a relative import can't be resolved - it falls back to the DIRECT
- * edge (`fallback: true`), never a fabricated chain. Returns one finding per offending top-level import,
- * de-duplicated to the shortest chain per first-hop specifier. Non-route files yield `[]`.
- */
-export function resolveServerOnlyChains(file, content, resolve, read, facts) {
-    if (!ROUTE_FILE.test(file))
-        return [];
-    const lines = content.split("\n");
-    const out = [];
-    const flaggedSpecifiers = new Set();
-    // Collect the route's import edges up front (fresh-regex scan) so the per-edge logic below can call
-    // the REENTRANT transitive walk without corrupting a shared regex's `lastIndex` (the walk also scans
-    // imports). Driving `STATIC_IMPORT.exec` here directly would restart this loop forever.
-    for (const { specifier, index } of staticImportEdges(content, facts, file)) {
-        if (flaggedSpecifiers.has(specifier))
-            continue;
-        const line = lineAt(content, index);
-        const snippet = (lines[line - 1] ?? "").trim();
-        // (1) A direct by-name sink (`node:fs`, `postgres`) - the route imports it itself; chain is the
-        // direct edge. (Length-2 chain == the regex scan's existing `[route, specifier]`.)
-        if (directSinkSpecifier(specifier) !== undefined) {
-            flaggedSpecifiers.add(specifier);
-            out.push({ file, line, snippet, specifier, chain: [file, specifier], fallback: false });
-            continue;
-        }
-        // (2) A relative local import - try the transitive walk from the resolved dependency. If it reaches
-        // a sink, emit the full chain rooted at THIS route's import line.
-        if (isRelativeSpecifier(specifier)) {
-            const abs = resolve(file, specifier);
-            if (abs === undefined) {
-                // Unresolvable relative import. If it's the known server-only `../db` convention the regex scan
-                // flags directly, fall back to the direct edge (precise resolve impossible - say so via
-                // `fallback`). Any other unresolvable relative import we can't assert is server-only - skip it.
-                if (SERVER_ONLY.test(specifier)) {
-                    flaggedSpecifiers.add(specifier);
-                    out.push({ file, line, snippet, specifier, chain: [file, specifier], fallback: true });
-                }
-                continue;
-            }
-            // The `.server` / marker sink can be the first hop itself.
-            if (SERVER_MODULE_FILE.test(abs)) {
-                flaggedSpecifiers.add(specifier);
-                out.push({ file, line, snippet, specifier, chain: [file, specifier], fallback: false });
-                continue;
-            }
-            const depContent = read(abs);
-            if (depContent === undefined)
-                continue;
-            if (SERVER_ONLY_MARKER_IMPORT.test(depContent)) {
-                flaggedSpecifiers.add(specifier);
-                out.push({ file, line, snippet, specifier, chain: [file, specifier], fallback: false });
-                continue;
-            }
-            // Walk INTO the dependency: build the chain `[depAbs, …]` then re-root it at the route's import.
-            const subChain = walkServerOnlyChain(abs, depContent, resolve, read, facts);
-            if (subChain !== undefined) {
-                flaggedSpecifiers.add(specifier);
-                // subChain is `[depAbs, …hops…, sink]`; replace its head (the resolved dep path) with the
-                // route's as-written specifier so the chain reads `routes/x → ../data → ../db → node:crypto`.
-                const chain = [file, specifier, ...subChain.slice(1)];
-                out.push({ file, line, snippet, specifier, chain, fallback: false });
-                continue;
-            }
-            // (3) The relative `../db`-style convention the regex scan flags directly, but where the walk
-            // found no deeper sink (e.g. the file wasn't readable past the first hop) - fall back to the
-            // direct edge so we still surface the known-server-only convention rather than going silent.
-            if (SERVER_ONLY.test(specifier)) {
-                flaggedSpecifiers.add(specifier);
-                out.push({ file, line, snippet, specifier, chain: [file, specifier], fallback: true });
-            }
-        }
-    }
-    return out;
-}
-// A route handler returning a raw `Response` (`=> new Response(`, `return Response.json(`, …) makes the
-// typed client infer `data: never` (`Jsonify<Response>` is `never`) - so frontend/backend drift detection
-// silently vanishes for that route. Advisory, not a failure: a raw Response is sometimes intended
-// (redirects, files, streams). Fix is to return a plain object, or declare `{ response: t.… }` to type it.
-const RESPONSE_RETURN = /(?:=>\s*|return\s+)(?:new\s+Response|Response\s*\.\s*json)\s*\(/g;
-/** Scan a backend module (one that calls `server(`) for handlers returning a raw `Response`, which collapses
- * the typed client's `data` to `never`. Pure + line-accurate; returns `[]` for files with no `server(` call. */
-export function scanResponseRoutes(file, content, facts) {
-    // Strip comments + template literals first: a commented-out or doc-example `return new Response(`
-    // must not raise a spurious advisory. Lengths are preserved, so lineAt + the raw-line snippet align.
-    const code = stripComments(content);
-    if (!/(?<![.\w])server\s*\(/.test(code))
-        return [];
-    const out = [];
-    const lines = content.split("\n");
-    RESPONSE_RETURN.lastIndex = 0;
-    for (let m = RESPONSE_RETURN.exec(code); m !== null; m = RESPONSE_RETURN.exec(code)) {
-        if (facts !== undefined) {
-            const source = facts.parse(file, content);
-            // A parseable AST rejects `return new Response(` text that only lives in a normal string. On
-            // malformed source we keep the lexical candidate; the typecheck gate will report the syntax error.
-            if (source !== undefined && facts.isResponseSyntaxAt(source, m.index) !== true)
-                continue;
-        }
-        const line = lineAt(content, m.index);
-        // A `// nifra-expect raw-response` pragma marks an intentional raw Response (a file/redirect that can't
-        // be a typed route), silencing this advisory. Honor it on the return line itself, OR on the line above
-        // ONLY when that line is a standalone comment - so a TRAILING pragma on one route's return line can't
-        // leak down and suppress the very next route's genuine advisory. `stripComments` blanks the pragma in
-        // `code` (so it never affects the match); the raw `lines` still carry it.
-        const thisLine = lines[line - 1] ?? "";
-        const aboveLine = lines[line - 2] ?? "";
-        const aboveSuppresses = aboveLine.trimStart().startsWith("//") && aboveLine.includes(RAW_RESPONSE_PRAGMA);
-        if (thisLine.includes(RAW_RESPONSE_PRAGMA) || aboveSuppresses)
-            continue;
-        out.push({ file, line, snippet: thisLine.trim() });
-    }
-    return out;
-}
-/** The opt-out pragma that suppresses the {@link scanResponseRoutes} advisory for an intentional raw Response. */
-const RAW_RESPONSE_PRAGMA = "nifra-expect raw-response";
-/** Walk the project's `.ts`/`.tsx` source (skipping deps and build output), calling `visit` per file.
- * Exported so `nifra doctor` ({@link ./doctor.ts}) scans the same source surface as `nifra check`.
- *
- * `includeTests` widens the surface to `*.test.ts`/`*.spec.ts`, which the default excludes. It exists
- * for `nifra doctor`: `tsc` compiles tests, so a test importing a package no manifest declares is a
- * build that a clean install cannot produce - the exact false confidence doctor is for. */
-/**
- * Paths git considers ignored under `cwd`, in ONE batched `git check-ignore` call - so `.gitignore`
- * (root + nested + the global excludesfile) is honoured, not just the built-in {@link IGNORED} list. This
- * is what keeps the scan out of generated/build trees that live under a repo but aren't source: a monorepo
- * that gitignores, say, `builder/projects/` (238 generated apps) would otherwise be walked in full - 40k+
- * findings, a 50 MB+ result that overwhelms the caller. Returns an EMPTY set when there's no git / not a
- * repo / git errors, so the scan simply degrades to the {@link IGNORED} regex - never throws, never blocks.
- */
-async function gitIgnored(cwd, rels) {
-    if (rels.length === 0)
-        return new Set();
-    try {
-        const proc = Bun.spawn(["git", "check-ignore", "--stdin"], {
-            cwd,
-            stdin: "pipe",
-            stdout: "pipe",
-            stderr: "ignore",
-        });
-        proc.stdin.write(`${rels.join("\n")}\n`);
-        await proc.stdin.end();
-        // git echoes back each ignored path exactly as fed on stdin (one per line); exit 1 = none matched.
-        const out = await new Response(proc.stdout).text();
-        await proc.exited;
-        return new Set(out
-            .split("\n")
-            .map((s) => s.trim())
-            .filter(Boolean));
-    }
-    catch {
-        return new Set();
-    }
-}
-export async function walkSource(cwd, visit, opts = {}) {
-    const skip = opts.includeTests === true ? IGNORED_DIR : IGNORED;
-    // List candidates first (cheap - no reads), drop the built-in ignores, then exclude gitignored paths in
-    // one batch before the (expensive) reads. So a gitignored generated/build tree is never read or scanned.
-    const rels = [];
-    for await (const rel of new Glob("**/*.{ts,tsx,mts,cts}").scan({ cwd, dot: false })) {
-        if (!skip.test(rel))
-            rels.push(rel);
-    }
-    const ignored = await gitIgnored(cwd, rels);
-    for (const rel of rels) {
-        if (ignored.has(rel))
-            continue;
-        visit(rel, await Bun.file(join(cwd, rel)).text());
-    }
-}
-const bySite = (a, b) => a.file.localeCompare(b.file) || a.line - b.line;
-/** Collect own-API `fetch()` findings across the project. */
-export async function scanProject(cwd) {
-    const out = [];
-    await walkSource(cwd, (rel, content) => out.push(...scanFetchText(rel, content)));
-    return out.sort(bySite);
-}
-// #7 - server-manifest drift. `server-manifest.ts` is a COMMITTED generated file (it bakes the route
-// list + client-entry hash for a disk-less worker). If `routes/` changes but the manifest isn't
-// regenerated, the worker serves a stale route table - a silent edge break that no other check catches.
-// We diff each committed manifest's imported route files against the live `routes/` tree.
-// The marker comment `generateServerManifest` emits at the top of the file - identifies a generated
-// manifest unambiguously (so a user file merely named `server-manifest.ts` isn't mistaken for one).
-const GENERATED_MARKER = "GENERATED by @nifrajs/web generateServerManifest";
-// The first route-import specifier's prefix up to `routes/` (e.g. `./`, `../`, `./src/`) - used to
-// locate the routes dir relative to the manifest, and to strip to route-relative keys.
-const ROUTES_PREFIX = /["'](\.{1,2}(?:\/[^"'/]+)*?\/routes\/)[^"']+["']/;
-// Route file extensions discovery recognises (mirrors `@nifrajs/web/fs`'s filter).
-const ROUTE_FILE_EXT = /\.(tsx|jsx|svelte|vue|mdx)$/;
-/**
- * Scan the project for committed, generated `server-manifest.ts` files and report any that have drifted
- * from the live `routes/` tree. For each, the routes dir is derived from the manifest's own import
- * prefix (so a manifest that imports `../routes/x` is checked against the sibling `routes/`), its route
- * imports are parsed (`parseManifestRouteFiles`), and the set is diffed against the actual route files
- * on disk. A clean manifest yields no finding. Returns one finding per drifted manifest. Never throws on
- * a per-manifest miss (an unreadable routes dir is simply skipped).
- */
-export async function scanServerManifestDrift(cwd) {
-    const { parseManifestRouteFiles, diffManifestRoutes, isManifestInSync } = await import("@nifrajs/web/build");
-    const findings = [];
-    for await (const rel of new Glob("**/server-manifest.ts").scan({ cwd, dot: false })) {
-        if (IGNORED.test(rel))
-            continue;
-        const source = await Bun.file(join(cwd, rel)).text();
-        if (!source.includes(GENERATED_MARKER))
-            continue; // not a generated manifest - skip
-        const prefixMatch = ROUTES_PREFIX.exec(source);
-        if (prefixMatch?.[1] === undefined)
-            continue; // no `routes/` imports → nothing to diff (empty app)
-        const routesPrefix = prefixMatch[1];
-        const manifestFiles = parseManifestRouteFiles(source, routesPrefix);
-        // The routes dir sits at `<manifest dir>/<prefix>` - resolve it relative to the manifest file.
-        const manifestDir = rel.includes("/") ? rel.slice(0, rel.lastIndexOf("/")) : "";
-        const routesDir = join(cwd, manifestDir, routesPrefix);
-        let discovered;
-        try {
-            discovered = (await Array.fromAsync(new Glob("**/*.{tsx,jsx,svelte,vue,mdx}").scan({ cwd: routesDir })))
-                .map((f) => f.replaceAll("\\", "/"))
-                .filter((f) => ROUTE_FILE_EXT.test(f));
-        }
-        catch {
-            continue; // routes dir gone/unreadable - not a drift we can assess
-        }
-        const drift = diffManifestRoutes(manifestFiles, discovered);
-        if (!isManifestInSync(drift)) {
-            findings.push({ file: rel, missing: drift.missing, extra: drift.extra });
-        }
-    }
-    return findings.sort((a, b) => a.file.localeCompare(b.file));
-}
 /**
  * Find the project's `tsc` the way module resolution would: `node_modules/typescript/bin/tsc` in
  * cwd, then each parent directory up to the filesystem root. A workspace package in a monorepo has
@@ -1681,12 +95,7 @@ async function typecheck(cwd, signal) {
     };
 }
 // `src/x.tsx(12,5): error TS2322: <message>` → one structured diagnostic.
-const TSC_LINE = /^(.+?)\((\d+),\d+\):\s*(?:error|warning)\s+TS\d+:\s*(.+)$/;
 const OVERRIDE_SEVERITIES = ["error", "warn", "info", "off"];
-/** Load `nifra.check.json` if present. Fail-open + total: absent → empty; malformed JSON → empty plus a
- * parse `error`; an invalid entry → skipped plus a `warnings` note the caller surfaces as a `warning`
- * diagnostic (never throws, never blocks the gate). Mount entries are normalized to bare path prefixes
- * (`/auth/**` and `/auth/` both become `/auth`). */
 async function loadCheckConfig(cwd) {
     const path = join(cwd, "nifra.check.json");
     const empty = { externalMounts: [], rules: {} };
@@ -1748,138 +157,6 @@ async function loadCheckConfig(cwd) {
         };
     }
 }
-const UNTYPED_CLIENT_HINT = 'client("…") without a type argument - write client<typeof app>("…") (or client(contract, url)) so the compiler can catch drift';
-const FETCH_HINT = "hand-rolled fetch() to your own API - call it through client<typeof app> (from @nifrajs/client) so the compiler catches drift";
-const SERVER_IMPORT_HINT = "server-only import in a route module (bundled for the browser) - reach it via c.db / ctx.api inside a loader, never a top-level import";
-const RESPONSE_ROUTE_HINT = "route handler returns a raw Response - the typed client infers `data: never`, so drift detection is lost for this route. Return a plain object (it's serialized for you); for a stream use a typed SSE route (`app.sse(...)`), which keeps typed events; or, if a raw Response is intended (file/redirect), add `{ response: t.… }` or a `// nifra-expect raw-response` comment to mark it and silence this";
-const PIPELINE_DOC_HINT = "nifra runs one bundler per phase - `vitePlugins` feed Vite, `clientPlugins`/`serverPlugins` feed Bun, and the file `nifra build` imports the adapter from is bundled into the server. See the Gotchas section of the Dev & HMR guide.";
-const UNDECLARED_DEP_HINT = "imported package is not declared in package.json dependencies - run bun add to declare it";
-const SQL_COMPILER_MISSING_HINT = "the interpolated-SQL rule did NOT run - it parses source with the TypeScript compiler, which is an optional peer and is not installed here. This report says nothing about SQL injection either way. Install it with `bun add -d typescript`";
-const SQL_INTERPOLATION_EXAMPLE = "$" + "{value}";
-const INTERPOLATED_SQL_HINT = `SQL built by interpolating a value into the statement text - the value becomes statement, not a parameter, so anything the caller controls can end the literal and continue as SQL. Pass it as a bound parameter (\`?\` / \`$1\` and an argument), or use your driver's tagged template (sql\`… ${SQL_INTERPOLATION_EXAMPLE} …\`), which binds the substitutions for you`;
-const MANIFEST_DRIFT_HINT = "server-manifest.ts is out of sync with routes/ - re-run the build to regenerate it (a disk-less worker bakes this route table, so the drift is a silent edge break), then commit it";
-const TRUST_MANIFEST_DRIFT_HINT = "nifra.manifest.json is missing, invalid, or out of sync - run `nifra manifest emit`, review it, and commit the regenerated trust artifact";
-const CAPABILITY_HINT = "effect/capability assurance failed - align the route declaration with approved adapter provenance; never bypass an owned effect seam";
-function oneLineDiff(file, line, before, after) {
-    return `--- ${file}:${line}\n+++ ${file}:${line}\n@@\n-${before}\n+${after}`;
-}
-function untypedClientSuggestion(f) {
-    const replacement = f.snippet.replace(/(?<![.\w])client\s*\(/, "client<typeof app>(");
-    return replacement === f.snippet
-        ? {
-            kind: "manual",
-            title: "Add the app type argument to the client factory",
-            steps: [
-                'Change `client("...")` to `client<typeof app>("...")`.',
-                "Make sure the backend app type is imported or otherwise in scope.",
-            ],
-        }
-        : {
-            kind: "edit",
-            title: "Insert `<typeof app>` into the client factory call",
-            diff: oneLineDiff(f.file, f.line, f.snippet, replacement),
-            steps: ["Make sure the backend app type is imported or otherwise in scope."],
-        };
-}
-function routeKey(method, path) {
-    return `${method.toUpperCase()} ${path}`;
-}
-function typedClientCall(method, path) {
-    const segs = path.split("/").filter((seg) => seg !== "");
-    let chain = "api";
-    if (segs.length === 0)
-        chain += ".index";
-    else {
-        for (const seg of segs) {
-            chain += IDENT.test(seg) ? `.${seg}` : `[${JSON.stringify(seg)}]`;
-        }
-    }
-    return `${chain}.${method.toLowerCase()}()`;
-}
-function staticRouteMap(routes) {
-    const out = new Map();
-    for (const route of routes) {
-        if (route.path.includes(":") || route.path.includes("*"))
-            continue;
-        const key = routeKey(route.method, route.path);
-        const bucket = out.get(key);
-        if (bucket === undefined)
-            out.set(key, [route]);
-        else
-            bucket.push(route);
-    }
-    return out;
-}
-function ownFetchEditSuggestion(f, routes) {
-    const call = parseSimpleFetchCall(f.snippet);
-    if (call === undefined || !SIMPLE_REWRITE_METHODS.has(call.method))
-        return undefined;
-    const matches = routes.get(routeKey(call.method, call.path));
-    if (matches === undefined || matches.length !== 1)
-        return undefined;
-    const replacementCall = typedClientCall(call.method, call.path);
-    const replacement = `${f.snippet.slice(0, call.start)}${replacementCall}${f.snippet.slice(call.end)}`;
-    if (replacement === f.snippet)
-        return undefined;
-    const route = matches[0];
-    if (route === undefined)
-        return undefined;
-    return {
-        kind: "edit",
-        title: "Rewrite simple own-API fetch to the typed nifra client",
-        diff: oneLineDiff(f.file, f.line, f.snippet, replacement),
-        steps: [
-            `Matched ${route.method} ${route.path} at ${route.file}:${route.line}.`,
-            "Use an in-scope typed client named `api` (`client<typeof app>(baseUrl)` or the route loader/action `api`).",
-            "Update downstream `Response` handling to branch on `{ ok, data, error }` if this variable is used later.",
-        ],
-    };
-}
-function ownFetchSuggestion(f, routes) {
-    const exact = ownFetchEditSuggestion(f, routes);
-    if (exact !== undefined)
-        return exact;
-    return {
-        kind: "manual",
-        title: "Replace own-API fetch with the typed nifra client",
-        steps: [
-            "Call `nifra_routes` or read `nifra://routes` for the exact typed-client call form.",
-            "Create `const api = client<typeof app>(baseUrl)` from `@nifrajs/client`.",
-            "Replace the relative `fetch()` call with the generated `api...get/post/...` call and branch on `{ ok, data, error }`.",
-        ],
-    };
-}
-function serverImportSuggestion(specifier, chain, fallback) {
-    const sink = chain[chain.length - 1] ?? specifier;
-    // Surface the resolved chain in the fix steps so the agent sees the full path (`route → ../data →
-    // ../db → node:crypto`) and which module to cut - not just the route's own top-level import.
-    const chainStep = chain.length > 2
-        ? fallback
-            ? `Server-only code reaches this route through \`${chain.join(" → ")}\` (the deeper chain couldn't be resolved precisely - trace it from \`${specifier}\`).`
-            : `Server-only code reaches this route transitively: \`${chain.join(" → ")}\`. The sink is \`${sink}\`; break the chain at the first hop (\`${specifier}\`) or move the sink behind the server boundary.`
-        : undefined;
-    return {
-        kind: "manual",
-        title: "Move server-only code behind the route server boundary",
-        steps: [
-            ...(chainStep !== undefined ? [chainStep] : []),
-            `Remove the top-level \`import … from "${specifier}"\` from this route module (it's bundled for the browser).`,
-            "Access backend/data work through the route `loader`/`action` context (`api`, `env`, or project server context).",
-            `If a direct module import is unavoidable, lazy-load it (\`await import("${specifier}")\`) inside the server-only loader/action path.`,
-        ],
-    };
-}
-function responseRouteSuggestion() {
-    return {
-        kind: "manual",
-        title: "Preserve typed-client response inference",
-        steps: [
-            "Prefer returning a plain object from JSON routes; nifra serializes it for you.",
-            "For a stream, use a typed SSE route - `app.sse(...)` (or `sse(c, run)` from `@nifrajs/core/server`) - which keeps typed events instead of collapsing the client to `data: never`.",
-            "If this route must return a raw Response (redirect, file), declare an explicit response schema, or add a `// nifra-expect raw-response` comment above the return to mark it intentional and silence this advisory.",
-        ],
-    };
-}
 /** Build the rule input from one source walk and the other check-wide scans. */
 async function buildProjectScan(cwd, opts) {
     const fetches = [];
@@ -1954,625 +231,10 @@ async function buildProjectScan(cwd, opts) {
 }
 /** Run the three checks and assemble a structured, machine-readable result. The single source the CLI
  * report, `--json`, and the MCP tool all render from. */
+/** Run the scan, freeze its facts, and project them into the public diagnostic result. */
 export async function collectCheckResult(cwd, opts = {}) {
     const scan = await buildProjectScan(cwd, opts);
-    const factsSeed = scan.facts;
-    const { fetches, untypedClients, removedImports, responseRoutes, interpolatedSql } = factsSeed.sourceFindings;
-    const staticRoutes = factsSeed.routes;
-    const serverImports = factsSeed.importGraph;
-    const { doctor: dr, manifestDrift } = factsSeed.packages;
-    const { checkConfig } = factsSeed.policies;
-    const tc = scan.typecheck;
-    const sqlCompiler = scan.sqlCompiler;
-    const checkConfigError = scan.checkConfigError;
-    const checkConfigWarnings = scan.checkConfigWarnings;
-    const diagnostics = [];
-    const structuredExtras = [];
-    if (checkConfigError !== undefined) {
-        diagnostics.push({
-            rule: "check-config",
-            severity: "warning",
-            file: "nifra.check.json",
-            message: `nifra.check.json could not be parsed (${checkConfigError}) - its external-mount allowlist was ignored`,
-            fix: "Fix the JSON syntax in nifra.check.json",
-        });
-    }
-    for (const warning of checkConfigWarnings) {
-        diagnostics.push({
-            rule: "check-config",
-            severity: "warning",
-            file: "nifra.check.json",
-            message: `nifra.check.json: ${warning}`,
-            fix: "Fix the entry in nifra.check.json",
-        });
-    }
-    if (tc.missingTypeScript === true) {
-        // A tsconfig with no reachable `typescript` install is a broken gate, not a benign skip: the
-        // contract check the project asked for (by having a tsconfig) silently didn't run. Fail closed.
-        diagnostics.push({
-            rule: "typecheck",
-            severity: "error",
-            file: "tsconfig.json",
-            message: "tsconfig.json is present but no `typescript` install was found from this directory upward - the typecheck gate did NOT run",
-            fix: "bun add -d typescript",
-            suggestion: {
-                kind: "command",
-                title: "Install TypeScript so the contract gate can run",
-                command: ["bun", "add", "-d", "typescript"],
-            },
-        });
-    }
-    if (tc.ran && !tc.ok) {
-        const lines = (tc.output ?? "").split("\n");
-        let matched = false;
-        for (const l of lines) {
-            const m = TSC_LINE.exec(l.trim());
-            if (m) {
-                matched = true;
-                diagnostics.push({
-                    rule: "typecheck",
-                    severity: "error",
-                    file: m[1],
-                    line: Number(m[2]),
-                    message: m[3],
-                    suggestion: {
-                        kind: "manual",
-                        title: "Fix the TypeScript contract error",
-                        steps: [
-                            "Open the reported file and line.",
-                            "Align the handler, route schema, or typed-client call with the compiler error.",
-                            "Run `nifra_check` again after the edit.",
-                        ],
-                    },
-                });
-            }
-        }
-        if (!matched)
-            diagnostics.push({
-                rule: "typecheck",
-                severity: "error",
-                message: tc.output || "typecheck failed",
-                suggestion: {
-                    kind: "manual",
-                    title: "Fix the TypeScript contract error",
-                    steps: ["Run `tsc --noEmit` locally for the full compiler output."],
-                },
-            });
-    }
-    const routes = staticRouteMap(staticRoutes);
-    for (const f of [...fetches].sort(bySite)) {
-        diagnostics.push({
-            rule: "typed-client",
-            severity: "error",
-            file: f.file,
-            line: f.line,
-            message: `${f.snippet} - ${FETCH_HINT}`,
-            fix: FETCH_HINT,
-            suggestion: ownFetchSuggestion(f, routes),
-        });
-    }
-    for (const f of [...removedImports].sort(bySite)) {
-        const entry = REMOVED_IMPORTS.find((candidate) => f.snippet.includes(`"${candidate.specifier}`) ||
-            f.snippet.includes(`'${candidate.specifier}`));
-        diagnostics.push({
-            rule: "removed-import",
-            severity: "error",
-            file: f.file,
-            line: f.line,
-            message: `${f.snippet} - removed in nifra ${entry?.since ?? "2.0"}: ${entry?.replacement ?? "see the changelog"}`,
-            fix: entry?.replacement ?? "see the changelog",
-        });
-    }
-    for (const f of [...untypedClients].sort(bySite)) {
-        diagnostics.push({
-            rule: "untyped-client",
-            severity: "error",
-            file: f.file,
-            line: f.line,
-            message: `${f.snippet} - ${UNTYPED_CLIENT_HINT}`,
-            fix: UNTYPED_CLIENT_HINT,
-            suggestion: untypedClientSuggestion(f),
-        });
-    }
-    for (const f of [...serverImports].sort(bySite)) {
-        // #4.4: the FULL transitive chain the import-resolution walk found - `route → ../data → ../db →
-        // node:crypto`, matching the build leak-guard's depth - instead of just the direct edge. The chain's
-        // tail is the actual server-only sink; the head is the route. When a precise resolve wasn't possible
-        // (a bare pkg / path alias), `fallback` is set and the chain degrades to the honest direct edge.
-        const chain = f.chain;
-        const sink = chain[chain.length - 1] ?? f.specifier;
-        diagnostics.push({
-            rule: "server-only-import",
-            severity: "error",
-            file: f.file,
-            line: f.line,
-            message: `${f.snippet} - server-only "${sink}" reaches the browser bundle via ${chain.join(" → ")}${f.fallback ? " (direct edge - couldn't resolve the transitive chain precisely)" : ""}; ${SERVER_IMPORT_HINT}`,
-            fix: SERVER_IMPORT_HINT,
-            chain,
-            suggestion: serverImportSuggestion(f.specifier, chain, f.fallback),
-        });
-    }
-    if (sqlCompiler === undefined) {
-        // A security rule that could not run must say so. Silence here is indistinguishable from a clean
-        // result, and this is the one rule whose clean result means "no SQL injection was found".
-        diagnostics.push({
-            rule: "interpolated-sql",
-            severity: "warning",
-            message: SQL_COMPILER_MISSING_HINT,
-            fix: SQL_COMPILER_MISSING_HINT,
-            suggestion: {
-                kind: "command",
-                title: "Install TypeScript so the SQL rule can run",
-                command: ["bun add -d typescript"],
-            },
-        });
-    }
-    for (const f of [...interpolatedSql].sort(bySite)) {
-        diagnostics.push({
-            rule: "interpolated-sql",
-            severity: "error",
-            file: f.file,
-            line: f.line,
-            message: `${f.snippet} - ${INTERPOLATED_SQL_HINT}`,
-            fix: "bind the value as a parameter instead of interpolating it into the statement",
-            suggestion: {
-                kind: "manual",
-                title: "Bind the value instead of interpolating it",
-                steps: [
-                    "Replace the interpolation with a placeholder your driver understands (`?` for SQLite/MySQL, `$1` for Postgres).",
-                    "Pass the value as an argument alongside the statement, so the driver binds it.",
-                    `Or switch to the driver's tagged template (sql\`… ${SQL_INTERPOLATION_EXAMPLE} …\`): the tag receives substitutions separately and binds them.`,
-                    "An identifier that genuinely cannot be bound (a table or column name) must be checked against an allowlist you control, never taken from the request.",
-                    "If the statement is dynamic but every value is already bound (generating `($1),($2),…` for a batch insert), mark it with a `// nifra-expect sql-dynamic: <reason>` comment on the line above - the reason is required.",
-                ],
-            },
-        });
-    }
-    // Advisory - surfaced but NOT folded into `ok`, so it never fails the gate (a raw Response is valid).
-    for (const f of [...responseRoutes].sort(bySite)) {
-        diagnostics.push({
-            rule: "response-route",
-            severity: "warning",
-            file: f.file,
-            line: f.line,
-            message: `${f.snippet} - ${RESPONSE_ROUTE_HINT}`,
-            fix: RESPONSE_ROUTE_HINT,
-            suggestion: responseRouteSuggestion(),
-        });
-    }
-    if (dr.ran) {
-        for (const f of dr.findings) {
-            diagnostics.push({
-                rule: "undeclared-dependency",
-                severity: "error",
-                file: f.file,
-                line: f.line,
-                message: `imports ${f.package} which is not declared in package.json - ${UNDECLARED_DEP_HINT}`,
-                fix: `add ${f.package} to package.json dependencies`,
-                suggestion: {
-                    kind: "command",
-                    title: `Declare ${f.package} in package.json`,
-                    command: ["bun", "add", f.package],
-                },
-            });
-        }
-        for (const finding of dr.duplicateInstalls) {
-            const copies = finding.copies.map((copy) => `${copy.version} at ${copy.path}`).join("; ");
-            diagnostics.push({
-                rule: "duplicate-install",
-                severity: "error",
-                message: `${finding.package} identity preflight found ${finding.cause} (${copies}) - ${finding.explanation}`,
-                fix: finding.remediation,
-                suggestion: {
-                    kind: "manual",
-                    title: `Deduplicate ${finding.package}`,
-                    steps: [
-                        "Align workspace dependency and peer ranges on one compatible version.",
-                        "Remove stale nested installs and run the package manager from the workspace root.",
-                        "Run `nifra doctor` again; do not suppress same-version duplicate paths.",
-                    ],
-                },
-            });
-        }
-        // Advisory (never fails the gate): while actively editing a linked package its dist is always
-        // momentarily behind. The finding earns its keep when a dev server is about to start against it -
-        // Bun reads live `src` while Vite's SSR runner reads the artifact, so a stale one 500s inside
-        // framework/shared-package code and reads exactly like an upstream regression.
-        for (const f of dr.staleDists) {
-            diagnostics.push({
-                rule: "stale-workspace-dist",
-                severity: "warning",
-                message: f.missing
-                    ? `${f.package} was never built - ${f.distFile} is missing, but its export map serves it to Vite SSR/node consumers while Bun reads src - rebuild ${f.package}`
-                    : `${f.package} has a stale build artifact - ${f.distFile} is ${f.behindSeconds}s older than ${f.sourceFile}, and Vite SSR/node consumers read the artifact while Bun reads src - rebuild ${f.package}`,
-                fix: `rebuild ${f.package}`,
-                evidence: [f.package, f.distFile, f.sourceFile],
-                suggestion: {
-                    kind: "manual",
-                    title: `Rebuild ${f.package}`,
-                    steps: [
-                        `Run the package's build (usually \`bun run build\` in its directory) so ${f.distFile} matches its source again.`,
-                        "Only workspace-linked installs drift; npm tarballs are immutable and never flagged.",
-                    ],
-                },
-            });
-        }
-    }
-    // The two-pipeline rule, read from the config as TEXT (doctor collects it - see ./pipeline-report.ts).
-    // `loadApp` already refuses a misplaced plugin, but only when something loads the app; a check that
-    // never executes project code, and CI that never starts a dev server, would otherwise meet these for
-    // the first time as a production server that built cleanly and died at startup.
-    for (const f of dr.pipeline?.findings ?? []) {
-        diagnostics.push({
-            rule: "pipeline",
-            severity: f.severity,
-            file: f.file,
-            ...(f.line !== undefined ? { line: f.line } : {}),
-            message: f.message,
-            fix: f.fix,
-            suggestion: { kind: "manual", title: f.fix, steps: [PIPELINE_DOC_HINT] },
-        });
-    }
-    // #7: a committed server-manifest.ts that drifted from routes/ - name the exact missing/extra routes.
-    for (const f of manifestDrift) {
-        const parts = [];
-        if (f.missing.length > 0)
-            parts.push(`missing from manifest: ${f.missing.join(", ")}`);
-        if (f.extra.length > 0)
-            parts.push(`stale in manifest: ${f.extra.join(", ")}`);
-        diagnostics.push({
-            rule: "server-manifest-drift",
-            severity: "error",
-            file: f.file,
-            message: `${f.file} drifted from routes/ (${parts.join("; ")}) - ${MANIFEST_DRIFT_HINT}`,
-            fix: MANIFEST_DRIFT_HINT,
-            evidence: [...f.missing, ...f.extra],
-            suggestion: {
-                kind: "manual",
-                title: "Regenerate the committed server manifest",
-                steps: [
-                    "Re-run your build (`nifra build --target <t>` or your build script) - it regenerates server-manifest.ts from the current routes/.",
-                    "Commit the updated server-manifest.ts.",
-                ],
-            },
-        });
-    }
-    // G+B+D+F: when the project opts into capability assurance, `nifra check` becomes the static
-    // provenance firewall as well as the typed-contract gate. Loading is explicit/config-owned; projects
-    // without nifra.assurance.ts retain the historical scan and hot path unchanged.
-    const provided = opts.assurance;
-    let applicationRulePacks = [];
-    let loadedPolicy = provided;
-    let loadedCapability = provided?.capability;
-    const assuranceConfigPath = join(cwd, "nifra.assurance.ts");
-    if (provided !== undefined ? provided.present : existsSync(assuranceConfigPath)) {
-        try {
-            // Either the shared reflection from `collectProjectVerification` (no second pass) or, on the
-            // standalone path, loaded + reflected here. Both branches yield the same config + evidence.
-            let config;
-            let project;
-            let routeAssurance;
-            let evidence;
-            if (provided !== undefined) {
-                // A load/evaluate failure travels as `provided.error`; re-throwing lands it in the same
-                // capability-config diagnostic the standalone catch produces.
-                if (provided.error !== undefined)
-                    throw provided.error;
-                config = provided.config;
-                project = provided.capability;
-                routeAssurance = provided.routeAssurance;
-                evidence = provided.evidence;
-            }
-            else {
-                const { loadAssuranceConfig } = await import("./assure.js");
-                config = await loadAssuranceConfig(cwd);
-                if (config.capabilities !== undefined) {
-                    const { collectCapabilityProjectReport } = await import("./capabilities-tool.js");
-                    project = await collectCapabilityProjectReport(cwd, config.source, config.capabilities);
-                }
-                loadedPolicy = {
-                    present: true,
-                    config,
-                    ...(routeAssurance === undefined ? {} : { routeAssurance }),
-                    ...(project === undefined ? {} : { capability: project }),
-                    ...(evidence === undefined ? {} : { evidence }),
-                };
-                loadedCapability = project;
-            }
-            applicationRulePacks = parseRulePacks(config.rulePacks);
-            const capabilityReport = project?.report;
-            if (config.capabilities !== undefined && project !== undefined) {
-                for (const finding of project.report.findings) {
-                    const violation = finding.code === "forbidden-effect-import"
-                        ? project.violations.find((candidate) => candidate.method === finding.method && candidate.path === finding.path)
-                        : undefined;
-                    const truncation = finding.code === "provenance-truncated"
-                        ? project.truncations.find((candidate) => candidate.method === finding.method && candidate.path === finding.path)
-                        : undefined;
-                    // An unmatched seam is a policy defect, not a route defect: the fix is in the policy file,
-                    // so it gets its own steps instead of the route-side provenance guidance.
-                    const seamFix = finding.code === "unmatched-provenance-seam"
-                        ? "Write the seam exactly as the code imports it, or delete the rule."
-                        : undefined;
-                    diagnostics.push({
-                        rule: "capability-assurance",
-                        severity: "error",
-                        ...(violation !== undefined
-                            ? { file: violation.module, chain: violation.chain }
-                            : truncation !== undefined
-                                ? { chain: truncation.chain }
-                                : {}),
-                        message: `${finding.message}${seamFix === undefined ? ` - ${CAPABILITY_HINT}` : ""}`,
-                        fix: seamFix ?? CAPABILITY_HINT,
-                        suggestion: seamFix === undefined
-                            ? {
-                                kind: "manual",
-                                title: "Restore declared effect provenance",
-                                steps: [
-                                    "Route effectful work through an import listed in capabilities.provenance.imports.",
-                                    "Declare the exact capability token on the route; do not widen unrelated routes in the same file.",
-                                    "For domain writes, add the adapter the capability definition requires: `schema.idempotency` for the `request` tier, `.use(durableCommand({ journal }))` from @nifrajs/middleware for the `durable` tier.",
-                                    "Run `nifra capabilities snapshot` only after assurance passes, then review the lockfile diff.",
-                                ],
-                            }
-                            : {
-                                kind: "manual",
-                                title: "Point the provenance rule at a module that exists",
-                                steps: [
-                                    "Copy the specifier from the import statement itself - it is matched as written, with no extension or index resolution.",
-                                    "Use a trailing `/*` when the seam is a directory of modules (`@myorg/db/*`).",
-                                    "For a routeModules entry, give the project-relative path of the file that implements the route.",
-                                    "Delete the rule if the seam it governed is gone; leaving it in place proves nothing.",
-                                ],
-                            },
-                    });
-                }
-            }
-            if (config.manifest !== undefined) {
-                const { buildNifraManifest, parseNifraManifest, serializeNifraManifest } = await import("@nifrajs/core/manifest");
-                const assurance = routeAssurance ??
-                    (await import("@nifrajs/core/assurance")).evaluateRouteAssurance(config.source, config.policy, {
-                        ...(config.capabilities !== undefined
-                            ? { definitions: config.capabilities.definitions }
-                            : {}),
-                    });
-                evidence ??= snapshotProjectEvidence(config.source, {
-                    assurance,
-                    ...(capabilityReport !== undefined ? { capabilities: capabilityReport } : {}),
-                });
-                const path = resolve(cwd, config.manifest.path ?? "nifra.manifest.json");
-                let message;
-                if (!assurance.ok || (capabilityReport !== undefined && !capabilityReport.ok)) {
-                    message =
-                        "the configured assurance policy is failing, so a trusted manifest cannot be built";
-                }
-                else if (!existsSync(path)) {
-                    message = "the configured trust manifest is missing";
-                }
-                else {
-                    try {
-                        const current = await buildNifraManifest({
-                            evidence,
-                            assurance,
-                            ...(capabilityReport !== undefined ? { capabilities: capabilityReport } : {}),
-                        });
-                        const storedText = await Bun.file(path).text();
-                        const stored = await parseNifraManifest(storedText, path);
-                        const expectedText = `${serializeNifraManifest(current)}\n`;
-                        if (storedText !== expectedText || stored.contentHash !== current.contentHash) {
-                            message = "the configured trust manifest does not match live route reflection";
-                        }
-                    }
-                    catch (error) {
-                        message = `the configured trust manifest is invalid: ${error instanceof Error ? error.message : String(error)}`;
-                    }
-                }
-                if (message !== undefined) {
-                    diagnostics.push({
-                        rule: "manifest-drift",
-                        severity: "error",
-                        file: path,
-                        message: `${message} - ${TRUST_MANIFEST_DRIFT_HINT}`,
-                        fix: TRUST_MANIFEST_DRIFT_HINT,
-                        suggestion: {
-                            kind: "command",
-                            title: "Regenerate the signed-manifest input artifact",
-                            command: ["nifra", "manifest", "emit"],
-                            steps: [
-                                "Review the route, assurance, capability, and classification delta before committing it.",
-                            ],
-                        },
-                    });
-                }
-            }
-        }
-        catch (err) {
-            loadedPolicy = { present: true, error: err };
-            diagnostics.push({
-                rule: "capability-config",
-                severity: "error",
-                file: "nifra.assurance.ts",
-                message: `capability assurance config could not be evaluated: ${err instanceof Error ? err.message : String(err)}`,
-                suggestion: {
-                    kind: "manual",
-                    title: "Repair the assurance config",
-                    steps: [
-                        "Ensure nifra.assurance.ts default-exports defineAssuranceConfig({ source, policy, capabilities }).",
-                        "Fix configuration/import errors; the provenance firewall fails closed when its policy cannot load.",
-                    ],
-                },
-            });
-        }
-    }
-    try {
-        const { checkContractsLock } = await import("./contracts.js");
-        if (!existsSync(join(cwd, "backend.ts")) && !existsSync(join(cwd, "contracts.lock.json"))) {
-            throw new Error("contract source not configured");
-        }
-        const contract = await checkContractsLock(cwd);
-        if (!contract.present) {
-            structuredExtras.push(diagnostic({
-                code: "NF-K001",
-                severity: "info",
-                message: "no contract lock; run `nifra contracts snapshot` to enable drift detection",
-                verify: "nifra contracts snapshot",
-            }));
-        }
-        else {
-            if (contract.vacuous) {
-                // Every route hashes to the empty-schema digest, so the lock exists but the drift rule guards
-                // nothing: it can only ever compare "no schema" to "no schema". Say so, or a green contract check
-                // reads as proof of a stable contract when there is no contract to be stable.
-                structuredExtras.push(diagnostic({
-                    code: "NF-K001",
-                    severity: "info",
-                    message: "no route schemas declared - the trust manifest is vacuous: every contract hash is the empty-schema digest, so drift detection guards nothing. Declare route schemas (body/query/params/response) so the lock has a contract to protect.",
-                    verify: "nifra check --lints-only",
-                }));
-            }
-            for (const finding of contract.diagnostics) {
-                diagnostics.push({
-                    rule: "contract-drift",
-                    severity: "error",
-                    code: "NF-K001",
-                    ...(finding.route !== undefined ? { evidence: [finding.route] } : {}),
-                    message: finding.message,
-                    fix: "run `nifra contracts snapshot` after reviewing the contract change",
-                    verify: "nifra check --lints-only",
-                });
-            }
-        }
-    }
-    catch (error) {
-        if (error instanceof Error && error.message === "contract source not configured") {
-            // API-only source scans have no contract surface to snapshot.
-        }
-        else {
-            diagnostics.push({
-                rule: "contract-drift",
-                severity: "error",
-                code: "NF-K001",
-                message: `contract lock could not be checked: ${error instanceof Error ? error.message : String(error)}`,
-                verify: "nifra contracts snapshot",
-            });
-        }
-    }
-    const projectFacts = freezeProjectFacts({
-        ...factsSeed,
-        policies: {
-            ...factsSeed.policies,
-            ...(loadedPolicy === undefined ? {} : { assurance: loadedPolicy }),
-            ...(loadedCapability === undefined ? {} : { capability: loadedCapability }),
-            rulePacks: applicationRulePacks,
-        },
-    }, diagnostics);
-    const ruleContext = {
-        root: cwd,
-        sources: projectFacts.source,
-        project: projectFacts,
-    };
-    const structuredDiagnostics = [...structuredExtras];
-    let registryDiagnostics = [];
-    try {
-        registryDiagnostics = await runRuleRegistry(ruleContext, [...legacyRules, ...securityRules, ...routeRules], projectFacts.policies.rulePacks);
-        structuredDiagnostics.push(...registryDiagnostics);
-    }
-    catch (error) {
-        registryDiagnostics = [
-            diagnostic({
-                code: "NF-C017",
-                severity: "error",
-                message: `rule registry failed closed: ${error instanceof Error ? error.message : String(error)}`,
-                fix: { recipe: "rule-pack.repair", command: "nifra check --lints-only" },
-                verify: "nifra check --lints-only",
-            }),
-        ];
-        structuredDiagnostics.push(...registryDiagnostics);
-    }
-    for (const item of registryDiagnostics) {
-        // The legacy adapters publish stable structured findings; the human compatibility view already
-        // contains their original rule names. Security rules and application packs still need a legacy-view
-        // row because they have no pre-registry diagnostic.
-        if (legacyRules.some((rule) => rule.code === item.code))
-            continue;
-        diagnostics.push({
-            rule: item.code,
-            severity: item.severity === "error" ? "error" : "warning",
-            code: item.code,
-            ...(item.file !== undefined ? { file: item.file } : {}),
-            ...(item.line !== undefined ? { line: item.line } : {}),
-            message: item.message,
-            ...(item.evidence !== undefined ? { evidence: item.evidence } : {}),
-            ...(item.verify !== undefined ? { verify: item.verify } : {}),
-        });
-    }
-    // Per-rule overrides from `nifra.check.json` `rules`, applied centrally to BOTH diagnostic views
-    // before `ok` is computed - never inside individual rules, so no rule can dodge (or double-apply)
-    // them. A key matches the legacy rule name or the stable NF- code.
-    const overrideFor = (...keys) => {
-        for (const key of keys) {
-            if (key !== undefined && checkConfig.rules[key] !== undefined)
-                return checkConfig.rules[key];
-        }
-        return undefined;
-    };
-    const ignoreGlobs = new Map();
-    const dropped = (override, file) => {
-        if (override.severity === "off")
-            return true;
-        if (override.ignore === undefined || file === undefined)
-            return false;
-        let globs = ignoreGlobs.get(override);
-        if (globs === undefined) {
-            globs = override.ignore.map((pattern) => new Glob(pattern));
-            ignoreGlobs.set(override, globs);
-        }
-        return globs.some((glob) => glob.match(file));
-    };
-    const codeToLegacy = new Map(Object.entries(LEGACY_RULE_CODES).map(([name, code]) => [code, name]));
-    const finalDiagnostics = diagnostics.flatMap((d) => {
-        const override = overrideFor(d.rule, d.code, LEGACY_RULE_CODES[d.rule]);
-        if (override === undefined)
-            return [d];
-        if (dropped(override, d.file))
-            return [];
-        // "off" is fully handled by `dropped` above - only real severities reach the retag.
-        if (override.severity === undefined || override.severity === "off")
-            return [d];
-        return [{ ...d, severity: override.severity === "warn" ? "warning" : override.severity }];
-    });
-    const finalStructured = structuredDiagnostics.flatMap((d) => {
-        const override = overrideFor(d.code, codeToLegacy.get(d.code));
-        if (override === undefined)
-            return [d];
-        if (dropped(override, d.file))
-            return [];
-        if (override.severity === undefined || override.severity === "off")
-            return [d];
-        return [Object.freeze({ ...d, severity: override.severity })];
-    });
-    // Cap the diagnostics when asked (the MCP path), so a project with thousands of findings can't return a
-    // message that breaks the stdio transport. `ok` reflects the FULL set - truncation never flips it.
-    const total = finalDiagnostics.length;
-    const max = opts.maxDiagnostics;
-    const shown = max !== undefined && total > max ? finalDiagnostics.slice(0, max) : finalDiagnostics;
-    const result = {
-        ok: !finalDiagnostics.some((diagnostic) => diagnostic.severity === "error"),
-        typecheck: tc.ran ? (tc.ok ? "pass" : "fail") : "skipped",
-        ...(!tc.ran && tc.note !== undefined ? { typecheckNote: tc.note } : {}),
-        diagnostics: shown,
-        ...(dr.pipeline !== undefined ? { pipeline: dr.pipeline } : {}),
-        ...(checkConfig.externalMounts.length > 0
-            ? { externalMounts: checkConfig.externalMounts }
-            : {}),
-        ...(Object.keys(checkConfig.rules).length > 0 ? { ruleOverrides: checkConfig.rules } : {}),
-        ...(shown.length < total ? { truncated: { shown: shown.length, total } } : {}),
-    };
-    Object.defineProperty(result, "structuredDiagnostics", {
-        value: finalStructured.slice(0, shown.length + structuredExtras.length),
-        enumerable: false,
-    });
-    return result;
+    return collectCheckDiagnostics(cwd, scan, opts);
 }
 /** The named rule sections of the human report, in print order. A rule absent from this list is NOT
  * dropped: {@link renderCheckReport} renders every remaining diagnostic in a generic section keyed by