@nifrajs/cli 3.1.0 → 3.2.0

package/dist/check-diagnostics.js

@@ -0,0 +1,1009 @@
+/**
+ * Diagnostic model and projections for the nifra verification pipeline.
+ *
+ * Scanners publish frozen facts; this module turns those facts plus policy into the stable legacy and
+ * structured diagnostic views. The CLI, JSON output, and MCP all consume the resulting CheckResult.
+ */
+import { existsSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { snapshotProjectEvidence } from "@nifrajs/core/evidence";
+import { SINGLE_COPY_REGISTER_SPECIFIER } from "@nifrajs/core/single-copy";
+import { IDENT, parseSimpleFetchCall, REMOVED_IMPORTS, SIMPLE_REWRITE_METHODS, } from "./check-scan.js";
+import { diagnostic } from "./diagnostics.js";
+import { freezeProjectFacts } from "./project-facts.js";
+import { parseRulePacks, runRuleRegistry } from "./rules/index.js";
+import { islandRules } from "./rules/islands.js";
+import { LEGACY_RULE_CODES, legacyRules } from "./rules/legacy.js";
+import { nanoRules } from "./rules/nano.js";
+import { routeRules } from "./rules/routes.js";
+import { securityRules } from "./rules/security.js";
+const TSC_LINE = /^(.+?)\((\d+),\d+\):\s*(?:error|warning)\s+TS\d+:\s*(.+)$/;
+const MAX_IGNORE_GLOB_LENGTH = 4096;
+const MAX_IGNORE_GLOB_ALTERNATIVES = 64;
+/**
+ * Match the small file-glob language used by check overrides without compiling user input into a
+ * regular expression. `nifra.check.json` is commonly supplied by a project or CI wrapper, so an
+ * attacker who can influence it must not be able to turn a diagnostic filter into a ReDoS input.
+ * The matcher supports the portable glob forms users expect here: `*`, `?`, `**`, character
+ * classes, and brace alternatives.
+ */
+function safeIgnoreGlobMatch(pattern, file) {
+    if (pattern.length === 0 || pattern.length > MAX_IGNORE_GLOB_LENGTH)
+        return false;
+    for (const alternative of expandIgnoreGlobBraces(pattern)) {
+        if (matchIgnoreGlobPath(alternative, file))
+            return true;
+    }
+    return false;
+}
+function expandIgnoreGlobBraces(pattern) {
+    const open = firstUnescaped(pattern, "{");
+    if (open === -1)
+        return [pattern];
+    const close = matchingBrace(pattern, open);
+    if (close === -1)
+        return [pattern];
+    const choices = splitBraceChoices(pattern.slice(open + 1, close));
+    if (choices.length < 2)
+        return [pattern];
+    const expanded = [];
+    for (const choice of choices) {
+        const prefix = pattern.slice(0, open) + choice + pattern.slice(close + 1);
+        for (const nested of expandIgnoreGlobBraces(prefix)) {
+            expanded.push(nested);
+            if (expanded.length >= MAX_IGNORE_GLOB_ALTERNATIVES)
+                return expanded;
+        }
+    }
+    return expanded;
+}
+function firstUnescaped(value, needle) {
+    let escaped = false;
+    for (let index = 0; index < value.length; index++) {
+        const char = value[index];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (char === needle)
+            return index;
+    }
+    return -1;
+}
+function matchingBrace(value, open) {
+    let depth = 0;
+    let escaped = false;
+    for (let index = open; index < value.length; index++) {
+        const char = value[index];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (char === "{")
+            depth++;
+        else if (char === "}" && --depth === 0)
+            return index;
+    }
+    return -1;
+}
+function splitBraceChoices(value) {
+    const choices = [];
+    let start = 0;
+    let depth = 0;
+    let escaped = false;
+    for (let index = 0; index < value.length; index++) {
+        const char = value[index];
+        if (escaped) {
+            escaped = false;
+            continue;
+        }
+        if (char === "\\") {
+            escaped = true;
+            continue;
+        }
+        if (char === "{")
+            depth++;
+        else if (char === "}")
+            depth--;
+        else if (char === "," && depth === 0) {
+            choices.push(value.slice(start, index));
+            start = index + 1;
+        }
+    }
+    choices.push(value.slice(start));
+    return choices;
+}
+function matchIgnoreGlobPath(pattern, file) {
+    const patternParts = pattern.split("/");
+    const fileParts = file.split("/");
+    let reachable = new Array(fileParts.length + 1).fill(false);
+    reachable[0] = true;
+    for (const part of patternParts) {
+        const next = new Array(fileParts.length + 1).fill(false);
+        if (part === "**") {
+            let canReach = false;
+            for (let index = 0; index <= fileParts.length; index++) {
+                canReach ||= reachable[index] === true;
+                next[index] = canReach;
+            }
+        }
+        else {
+            for (let index = 0; index < fileParts.length; index++) {
+                if (reachable[index] && matchIgnoreGlobPart(part, fileParts[index]))
+                    next[index + 1] = true;
+            }
+        }
+        reachable = next;
+    }
+    return reachable[fileParts.length] === true;
+}
+function matchIgnoreGlobPart(pattern, value) {
+    let previous = new Array(value.length + 1).fill(false);
+    previous[0] = true;
+    for (let patternIndex = 0; patternIndex < pattern.length; patternIndex++) {
+        const char = pattern[patternIndex];
+        const next = new Array(value.length + 1).fill(false);
+        if (char === "*") {
+            next[0] = previous[0] === true;
+            for (let valueIndex = 1; valueIndex <= value.length; valueIndex++)
+                next[valueIndex] = previous[valueIndex] === true || next[valueIndex - 1] === true;
+        }
+        else if (char === "?") {
+            for (let valueIndex = 1; valueIndex <= value.length; valueIndex++)
+                next[valueIndex] = previous[valueIndex - 1] === true;
+        }
+        else if (char === "\\" && patternIndex + 1 < pattern.length) {
+            const literal = pattern[++patternIndex];
+            for (let valueIndex = 1; valueIndex <= value.length; valueIndex++)
+                next[valueIndex] = previous[valueIndex - 1] === true && value[valueIndex - 1] === literal;
+        }
+        else if (char === "[") {
+            const classEnd = ignoreGlobClassEnd(pattern, patternIndex + 1);
+            if (classEnd === -1)
+                return matchIgnoreGlobPart(`\\[${pattern.slice(patternIndex + 1)}`, value);
+            for (let valueIndex = 1; valueIndex <= value.length; valueIndex++)
+                next[valueIndex] =
+                    previous[valueIndex - 1] === true &&
+                        matchIgnoreGlobClass(pattern.slice(patternIndex + 1, classEnd), value[valueIndex - 1]);
+            patternIndex = classEnd;
+        }
+        else {
+            for (let valueIndex = 1; valueIndex <= value.length; valueIndex++)
+                next[valueIndex] = previous[valueIndex - 1] === true && value[valueIndex - 1] === char;
+        }
+        previous = next;
+    }
+    return previous[value.length] === true;
+}
+function ignoreGlobClassEnd(pattern, start) {
+    for (let index = start; index < pattern.length; index++) {
+        if (pattern[index] === "]" && index > start)
+            return index;
+    }
+    return -1;
+}
+function matchIgnoreGlobClass(spec, value) {
+    let index = 0;
+    let negated = false;
+    if (spec[0] === "!" || spec[0] === "^") {
+        negated = true;
+        index++;
+    }
+    let matched = false;
+    while (index < spec.length) {
+        const first = spec[index] === "\\" ? spec[++index] : spec[index];
+        if (first === undefined)
+            break;
+        index++;
+        if (spec[index] === "-" && index + 1 < spec.length) {
+            index++;
+            const last = spec[index] === "\\" ? spec[++index] : spec[index];
+            if (last !== undefined && first <= value && value <= last)
+                matched = true;
+            index++;
+        }
+        else if (value === first) {
+            matched = true;
+        }
+    }
+    return negated ? !matched : matched;
+}
+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";
+const bySite = (a, b) => a.file.localeCompare(b.file) || a.line - b.line;
+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.",
+        ],
+    };
+}
+export async function collectCheckDiagnostics(cwd, scan, 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) {
+            // One line per physical copy: version, resolved absolute path, and who pulled it in. The
+            // absolute path is what a reader pastes into an editor or `rm -rf`; the importer list is what
+            // tells them WHICH package.json to fix - a relative path alone answers neither.
+            const copyLines = finding.copies.map((copy) => `${finding.package}@${copy.version} at ${copy.absolutePath ?? copy.path} - pulled in by ${copy.importers.join(", ")}`);
+            diagnostics.push({
+                rule: "duplicate-install",
+                severity: "error",
+                message: `${finding.package} identity preflight found ${finding.cause} - ${finding.explanation}${finding.topology === undefined ? "" : `. Topology: ${finding.topology}`}${finding.scope === undefined ? "" : `. Scope: ${finding.scope}`}`,
+                fix: finding.remediation,
+                evidence: copyLines,
+                suggestion: {
+                    kind: "manual",
+                    title: `Resolve ${finding.package} to one loaded copy`,
+                    // The renderer prints this block verbatim before the steps: the exact config for fix 2, so
+                    // the reader pastes instead of transcribing prose into JSON and TOML.
+                    diff: [
+                        "package.json:",
+                        `  "nifra": { "singleCopy": ["${finding.package}"] }`,
+                        "bunfig.toml:",
+                        `  preload = ["${SINGLE_COPY_REGISTER_SPECIFIER}"]`,
+                        "  [test]",
+                        `  preload = ["${SINGLE_COPY_REGISTER_SPECIFIER}"]`,
+                    ].join("\n"),
+                    steps: [
+                        ...copyLines.map((line) => `Copy: ${line}`),
+                        "Fix 1 - deduplicate: align workspace dependency and peer ranges on one compatible version, remove stale nested installs, and reinstall from the workspace root so every importer resolves one physical copy.",
+                        `Fix 2 - declare single-copy: apply the package.json and bunfig.toml config printed above; nifra then rewrites every duplicate to this app's copy.${finding.cause === "version-skew" ? " A declaration only covers same-version duplicates, so fix 1's range alignment must land first." : ""}`,
+                        "Re-run `nifra check`; the gate stays failing until one fix lands.",
+                    ],
+                },
+            });
+        }
+        // Declared single-copy: the resolver collapses these before anything loads, so the build is sound
+        // and the gate stays green. It is still worth a line - the guarantee lives in a declaration now,
+        // and a reader who deletes it gets a null hook dispatcher with no obvious cause.
+        for (const finding of dr.deduplicatedInstalls ?? []) {
+            const copies = finding.copies.map((copy) => copy.path).join("; ");
+            diagnostics.push({
+                rule: "duplicate-install",
+                severity: "warning",
+                message: `${finding.package} is installed at ${finding.copies.length} paths (${copies}) and is declared single-copy - nifra resolves every duplicate to this app's copy`,
+                fix: finding.remediation,
+            });
+        }
+        // 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) {
+            // The rebuild is only actionable with the LOCATION: a workspace link routinely points into a
+            // sibling repo, so "rebuild @nifrajs/core" left the developer to go find the checkout and guess
+            // the script. Name the directory and the package's own script, or say plainly that it declares
+            // none - never suggest a command that would fail.
+            const rebuild = f.buildScript === undefined
+                ? `${f.packageDir} declares no build script - build it the way that package expects`
+                : `cd ${f.packageDir} && bun run ${f.buildScript}   (or \`nifra fix --code NF-C010\`)`;
+            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} 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}`,
+                fix: rebuild,
+                evidence: [f.package, f.distFile, f.sourceFile, f.packageDir],
+                suggestion: {
+                    kind: "manual",
+                    title: `Rebuild ${f.package}`,
+                    steps: [
+                        rebuild,
+                        "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, ...islandRules, ...nanoRules], 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 dropped = (override, file) => {
+        if (override.severity === "off")
+            return true;
+        if (override.ignore === undefined || file === undefined)
+            return false;
+        return override.ignore.some((pattern) => safeIgnoreGlobMatch(pattern, 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 } : {}),
+        ...(dr.ran
+            ? {
+                identityPreflight: {
+                    ...(dr.identityBasis !== undefined ? { basis: dr.identityBasis } : {}),
+                    ...(dr.identityScanTruncated === true ? { truncated: true } : {}),
+                    duplicates: dr.duplicateInstalls,
+                    deduplicated: dr.deduplicatedInstalls ?? [],
+                },
+            }
+            : {}),
+        ...(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;
+}
+//# sourceMappingURL=check-diagnostics.js.map