@nifrajs/cli 2.10.0 → 2.12.0

package/dist/check.js

@@ -15,10 +15,18 @@
  * `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 } from "node:fs";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+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 { importTypeScript } from "./internal/typescript-import.js";
+import { diagnostic } from "./diagnostics.js";
+import { createSourceFacts } from "./internal/source-facts.js";
+import { importProjectTypeScript } from "./internal/typescript-import.js";
+import { RULE_CODES } from "./rules/codes.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
@@ -201,7 +209,7 @@ function isPotentialBackendSource(code) {
         /(?:from\s*|import\s*)["']hono["']/.test(code) ||
         /new\s+Hono(?:<[^>]+>)?\s*\(/.test(code));
 }
-function scanRoutePattern(file, content, code, pattern) {
+function scanRoutePattern(file, content, code, pattern, facts) {
     const out = [];
     const lines = content.split("\n");
     pattern.lastIndex = 0;
@@ -212,6 +220,14 @@ function scanRoutePattern(file, content, code, pattern) {
         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 });
     }
@@ -459,13 +475,13 @@ export function scanFetchText(file, content, externalMounts = []) {
     return out;
 }
 /** Statically collect simple Nifra route registrations from source, without importing app code. */
-export function scanStaticRouteText(file, content) {
+export function scanStaticRouteText(file, content, facts) {
     const code = stripComments(content);
     if (!isPotentialBackendSource(code))
         return [];
     return [
-        ...scanRoutePattern(file, content, code, ROUTE_REGISTRATION_DQ),
-        ...scanRoutePattern(file, content, code, ROUTE_REGISTRATION_SQ),
+        ...scanRoutePattern(file, content, code, ROUTE_REGISTRATION_DQ, facts),
+        ...scanRoutePattern(file, content, code, ROUTE_REGISTRATION_SQ, facts),
     ].sort(bySite);
 }
 /**
@@ -498,23 +514,154 @@ const SQL_METHODS = new Set([
 ]);
 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"]);
-/** Collect the file's top-level `const NAME = <initializer>` declarations. 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 moduleConstsOf(ts, source) {
-    const map = new Map();
+/** 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))
-            continue;
-        if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0)
+        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;
-        for (const declaration of statement.declarationList.declarations) {
-            if (ts.isIdentifier(declaration.name) && declaration.initializer !== undefined) {
-                map.set(declaration.name.text, declaration.initializer);
+        }
+        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 map;
+    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
@@ -561,19 +708,20 @@ const CONST_RESOLUTION_DEPTH = 5;
  * 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, and a same-file module-scope
- * `const` whose initializer resolves (recursively, depth-capped). Everything else - an imported
- * name, `let`, a parameter, a call, a member access, a shadowed name - stays unresolved and the
+ * 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, consts, depth) {
+function resolveStaticSqlText(ts, node, scope, depth) {
     if (depth > CONST_RESOLUTION_DEPTH)
         return undefined;
     if (ts.isParenthesizedExpression(node)) {
-        return resolveStaticSqlText(ts, node.expression, consts, depth);
+        return resolveStaticSqlText(ts, node.expression, scope, depth);
     }
     if (ts.isAsExpression(node) || ts.isSatisfiesExpression(node)) {
-        return resolveStaticSqlText(ts, node.expression, consts, depth);
+        return resolveStaticSqlText(ts, node.expression, scope, depth);
     }
     if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node))
         return node.text;
@@ -582,7 +730,7 @@ function resolveStaticSqlText(ts, node, consts, depth) {
     if (ts.isTemplateExpression(node)) {
         let text = node.head.text;
         for (const span of node.templateSpans) {
-            const part = resolveStaticSqlText(ts, span.expression, consts, depth + 1);
+            const part = resolveStaticSqlText(ts, span.expression, scope, depth + 1);
             if (part === undefined)
                 return undefined;
             text += part + span.literal.text;
@@ -590,29 +738,48 @@ function resolveStaticSqlText(ts, node, consts, depth) {
         return text;
     }
     if (ts.isConditionalExpression(node)) {
-        const whenTrue = resolveStaticSqlText(ts, node.whenTrue, consts, depth + 1);
-        const whenFalse = resolveStaticSqlText(ts, node.whenFalse, consts, depth + 1);
+        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 = consts.get(node.text);
-        if (initializer === undefined)
+        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;
-        return resolveStaticSqlText(ts, initializer, consts, depth + 1);
+        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, consts) {
+function templateShape(ts, template, scope) {
     let staticText = template.head.text;
     let dynamic = false;
     for (const span of template.templateSpans) {
-        const resolved = consts === undefined ? undefined : resolveStaticSqlText(ts, span.expression, consts, 0);
+        const resolved = scope === undefined ? undefined : resolveStaticSqlText(ts, span.expression, scope, 0);
         if (resolved === undefined)
             dynamic = true;
         else
@@ -622,9 +789,9 @@ function templateShape(ts, template, consts) {
     return { staticText, dynamic };
 }
 /** Describe only the first argument's syntax; comments/strings elsewhere cannot influence the result. */
-function sqlExpressionShape(ts, node, consts) {
+function sqlExpressionShape(ts, node, scope) {
     if (ts.isParenthesizedExpression(node))
-        return sqlExpressionShape(ts, node.expression, consts);
+        return sqlExpressionShape(ts, node.expression, scope);
     if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
         return {
             staticText: node.text,
@@ -640,7 +807,7 @@ function sqlExpressionShape(ts, node, consts) {
             (ts.isPropertyAccessExpression(tag) && tag.getText() === "Prisma.sql");
         const template = node.template;
         const templated = ts.isTemplateExpression(template)
-            ? templateShape(ts, template, parameterizedTag ? undefined : consts)
+            ? 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
@@ -665,7 +832,7 @@ function sqlExpressionShape(ts, node, consts) {
         };
     }
     if (ts.isTemplateExpression(node)) {
-        const templated = templateShape(ts, node, consts);
+        const templated = templateShape(ts, node, scope);
         return {
             staticText: templated.staticText,
             dynamic: templated.dynamic,
@@ -675,8 +842,8 @@ function sqlExpressionShape(ts, node, consts) {
         };
     }
     if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.PlusToken) {
-        const left = sqlExpressionShape(ts, node.left, consts);
-        const right = sqlExpressionShape(ts, node.right, consts);
+        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
@@ -690,11 +857,11 @@ function sqlExpressionShape(ts, node, consts) {
     }
     // 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 an imported or mutable name still flags.
+    // `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 (consts !== undefined) {
-        const resolved = resolveStaticSqlText(ts, node, consts, 0);
+    if (scope !== undefined) {
+        const resolved = resolveStaticSqlText(ts, node, scope, 0);
         if (resolved !== undefined) {
             return {
                 staticText: resolved,
@@ -731,27 +898,31 @@ function sqlMethod(ts, call) {
     return undefined;
 }
 const SQL_RECEIVER = /(?:^|\.)(?:db|sql|prisma|drizzle|database|conn|connection|client|tx)$/i;
-/** Scan one file's text for SQL assembled by interpolation. Pure + line-accurate. */
-export function scanInterpolatedSql(file, content, ts) {
+/**
+ * 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");
-    const kind = /\.[cm]?tsx?$/.test(file) ? ts.ScriptKind.TSX : ts.ScriptKind.JS;
-    const source = ts.createSourceFile(file, content, ts.ScriptTarget.Latest, true, kind);
     // 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 parseDiagnostics = source.parseDiagnostics;
-    if (parseDiagnostics !== undefined && parseDiagnostics.length > 0)
+    const source = parseSqlSource(ts, file, content);
+    if (source === undefined)
         return out;
-    // Module-scope consts, resolved once per file: an interpolated same-file `const` cannot carry
-    // request data, so the shared-projection idiom (`const COLS = "id, name"` … `${COLS}`) stays quiet
-    // while imported, mutable, parameter, and shadowed names flag exactly as before.
-    const consts = moduleConstsOf(ts, source);
+    // 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, consts);
+                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) ||
@@ -777,13 +948,65 @@ export function scanInterpolatedSql(file, content, ts) {
  * answer a security rule must never give when it did not run.
  */
 export async function scanProjectSql(cwd) {
-    const ts = await importTypeScript();
+    const ts = await importProjectTypeScript(cwd);
     if (ts === undefined)
         return undefined;
     const out = [];
-    await walkSource(cwd, (rel, content) => out.push(...scanInterpolatedSql(rel, content, ts)));
+    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-
@@ -857,7 +1080,7 @@ export function scanRemovedImports(file, content) {
 /** 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) {
+export function scanServerOnlyImports(file, content, facts) {
     if (!ROUTE_FILE.test(file))
         return [];
     const out = [];
@@ -871,6 +1094,13 @@ export function scanServerOnlyImports(file, content) {
         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 });
     }
@@ -910,7 +1140,7 @@ const staticImportRegex = () => new RegExp(STATIC_IMPORT.source, STATIC_IMPORT.f
  * 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) {
+function staticImportEdges(content, facts, file) {
     const edges = [];
     const re = staticImportRegex();
     const code = stripComments(content);
@@ -918,15 +1148,21 @@ function staticImportEdges(content) {
     for (let m = re.exec(code); m !== null; m = re.exec(code)) {
         if (positions[m.index] === " ")
             continue;
-        if (m[1] !== undefined)
-            edges.push({ specifier: m[1], index: m.index });
+        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) {
-    return staticImportEdges(content).map((e) => e.specifier);
+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
@@ -944,7 +1180,7 @@ export function directSinkSpecifier(spec) {
  * 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) {
+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;
@@ -953,7 +1189,7 @@ export function walkServerOnlyChain(routeFile, routeContent, resolve, read) {
         for (const node of frontier) {
             if (node.depth >= TRANSITIVE_MAX_DEPTH)
                 continue;
-            for (const spec of parseStaticImports(node.content)) {
+            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);
@@ -995,7 +1231,7 @@ export function walkServerOnlyChain(routeFile, routeContent, resolve, read) {
  * 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) {
+export function resolveServerOnlyChains(file, content, resolve, read, facts) {
     if (!ROUTE_FILE.test(file))
         return [];
     const lines = content.split("\n");
@@ -1004,7 +1240,7 @@ export function resolveServerOnlyChains(file, content, resolve, read) {
     // 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)) {
+    for (const { specifier, index } of staticImportEdges(content, facts, file)) {
         if (flaggedSpecifiers.has(specifier))
             continue;
         const line = lineAt(content, index);
@@ -1045,7 +1281,7 @@ export function resolveServerOnlyChains(file, content, resolve, read) {
                 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);
+            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
@@ -1072,7 +1308,7 @@ export function resolveServerOnlyChains(file, content, resolve, read) {
 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) {
+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);
@@ -1082,6 +1318,13 @@ export function scanResponseRoutes(file, content) {
     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
@@ -1213,14 +1456,38 @@ export async function scanServerManifestDrift(cwd) {
     }
     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
+ * its TypeScript hoisted to the workspace root, so the literal `join(cwd, "node_modules", …)` probe
+ * this replaces reported "typescript not installed" - and silently skipped the gate - whenever
+ * `nifra check` ran from the package directory instead of the repo root.
+ */
+function resolveTscBin(cwd) {
+    let dir = cwd;
+    while (true) {
+        const candidate = join(dir, "node_modules", "typescript", "bin", "tsc");
+        if (existsSync(candidate))
+            return candidate;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
 /** Run the project's own `tsc --noEmit`, if TypeScript + a tsconfig are present. Never auto-installs. */
 async function typecheck(cwd, signal) {
     const tsconfig = join(cwd, "tsconfig.json");
-    const tscBin = join(cwd, "node_modules", "typescript", "bin", "tsc");
     if (!(await Bun.file(tsconfig).exists()))
         return { ran: false, ok: true, note: "no tsconfig.json" };
-    if (!(await Bun.file(tscBin).exists())) {
-        return { ran: false, ok: true, note: "typescript not installed (run: bun add -d typescript)" };
+    const tscBin = resolveTscBin(cwd);
+    if (tscBin === undefined) {
+        return {
+            ran: false,
+            ok: false,
+            missingTypeScript: true,
+            note: "typescript not installed (run: bun add -d typescript)",
+        };
     }
     if (signal?.aborted)
         return { ran: true, ok: false, cancelled: true, output: "cancelled" };
@@ -1260,25 +1527,69 @@ 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*(.+)$/;
-/** Load `nifra.check.json` if present. Fail-open + total: absent → empty; malformed → empty plus a parse
- * `error` 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`). */
+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: {} };
     if (!existsSync(path))
-        return { config: { externalMounts: [] } };
+        return { config: empty, warnings: [] };
     try {
         const parsed = JSON.parse(await Bun.file(path).text());
         const raw = Array.isArray(parsed.externalMounts) ? parsed.externalMounts : [];
         const externalMounts = raw
             .filter((m) => typeof m === "string" && m.startsWith("/"))
             .map((m) => m.replace(/\/\*+$/, "").replace(/\/+$/, "") || "/");
-        return { config: { externalMounts } };
+        const warnings = [];
+        const rules = {};
+        if (parsed.rules !== undefined) {
+            if (typeof parsed.rules !== "object" ||
+                parsed.rules === null ||
+                Array.isArray(parsed.rules)) {
+                warnings.push('`rules` must be an object of { "<rule>": { severity?, ignore? } } - ignored');
+            }
+            else {
+                for (const [rule, value] of Object.entries(parsed.rules)) {
+                    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+                        warnings.push(`rules["${rule}"] must be an object - ignored`);
+                        continue;
+                    }
+                    const entry = value;
+                    const override = {};
+                    if (entry.severity !== undefined) {
+                        if (typeof entry.severity === "string" &&
+                            OVERRIDE_SEVERITIES.includes(entry.severity)) {
+                            override.severity = entry.severity;
+                        }
+                        else {
+                            warnings.push(`rules["${rule}"].severity must be "error" | "warn" | "info" | "off" - ignored`);
+                        }
+                    }
+                    if (entry.ignore !== undefined) {
+                        if (Array.isArray(entry.ignore) &&
+                            entry.ignore.every((g) => typeof g === "string")) {
+                            if (entry.ignore.length > 0)
+                                override.ignore = entry.ignore;
+                        }
+                        else {
+                            warnings.push(`rules["${rule}"].ignore must be an array of file globs - ignored`);
+                        }
+                    }
+                    if (override.severity !== undefined || override.ignore !== undefined)
+                        rules[rule] = override;
+                }
+            }
+        }
+        return { config: { externalMounts, rules }, warnings };
     }
     catch (error) {
         return {
-            config: { externalMounts: [] },
+            config: empty,
             error: error instanceof Error ? error.message : String(error),
+            warnings: [],
         };
     }
 }
@@ -1286,6 +1597,7 @@ const UNTYPED_CLIENT_HINT = 'client("…") without a type argument - write clien
 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}";
@@ -1426,29 +1738,38 @@ export async function collectCheckResult(cwd, opts = {}) {
     // Route modules (rel + content) collected during the walk, so the TRANSITIVE server-only resolution
     // (#4.4) - which needs fs-backed import resolution, not just per-file text - runs after the walk.
     const routeModules = [];
+    const sourceFiles = [];
     // Load the optional check config first - the typed-client scan needs the external-mount allowlist as it
     // walks. It's a tiny pure-JSON read; a malformed file surfaces as a warning below, never blocking.
-    const { config: checkConfig, error: checkConfigError } = await loadCheckConfig(cwd);
+    const { config: checkConfig, error: checkConfigError, warnings: checkConfigWarnings, } = await loadCheckConfig(cwd);
     // The interpolated-SQL rule parses with the TypeScript compiler, which is an optional peer. Resolved
     // once, before the walk, so a project without it is told the rule did not run rather than being
     // handed a clean report the rule never produced.
-    const sqlCompiler = await (opts.loadTypeScript ?? importTypeScript)();
+    const sqlCompiler = await (opts.loadTypeScript ?? (() => importProjectTypeScript(cwd)))();
+    // AST facts are a lazy refinement of lexical candidates. The parser is not invoked for a file until
+    // one of the route/import/response scanners finds something worth disambiguating, and the cache is
+    // shared across those rules for this check run.
+    const sourceFacts = sqlCompiler === undefined ? undefined : createSourceFacts(sqlCompiler);
+    // One loader + parse cache for the whole walk, so a shared `sql-fragments.ts` is read once no matter
+    // how many route modules import a fragment out of it.
+    const sqlImports = sqlCompiler === undefined ? undefined : createProjectSqlImports(cwd);
     // lintsOnly: skip the tsc pass (seconds on a big project) and run just the near-instant source
     // lints - the agent inner-loop mode; the full gate stays the definition of done.
     const [tc, _, dr, manifestDrift] = await Promise.all([
         opts.lintsOnly
-            ? Promise.resolve({ ran: false, ok: true, note: "skipped (lintsOnly)" })
+            ? Promise.resolve({ ran: false, ok: true, note: "lints-only mode" })
             : typecheck(cwd, opts.signal),
         walkSource(cwd, (rel, content) => {
+            sourceFiles.push({ file: rel, content });
             fetches.push(...scanFetchText(rel, content, checkConfig.externalMounts));
-            staticRoutes.push(...scanStaticRouteText(rel, content));
+            staticRoutes.push(...scanStaticRouteText(rel, content, sourceFacts));
             untypedClients.push(...scanUntypedClient(rel, content));
             removedImports.push(...scanRemovedImports(rel, content));
             if (ROUTE_FILE.test(rel))
                 routeModules.push({ rel, content });
-            responseRoutes.push(...scanResponseRoutes(rel, content));
+            responseRoutes.push(...scanResponseRoutes(rel, content, sourceFacts));
             if (sqlCompiler !== undefined)
-                interpolatedSql.push(...scanInterpolatedSql(rel, content, sqlCompiler));
+                interpolatedSql.push(...scanInterpolatedSql(rel, content, sqlCompiler, sqlImports));
         }),
         import("./doctor.js").then((m) => m.collectDoctorResult(cwd)),
         scanServerManifestDrift(cwd),
@@ -1478,9 +1799,10 @@ export async function collectCheckResult(cwd, opts = {}) {
         }
     };
     for (const { rel, content } of routeModules) {
-        serverImports.push(...resolveServerOnlyChains(rel, content, resolveModule, readModule));
+        serverImports.push(...resolveServerOnlyChains(rel, content, resolveModule, readModule, sourceFacts));
     }
     const diagnostics = [];
+    const structuredExtras = [];
     if (checkConfigError !== undefined) {
         diagnostics.push({
             rule: "check-config",
@@ -1490,6 +1812,31 @@ export async function collectCheckResult(cwd, opts = {}) {
             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;
@@ -1676,6 +2023,7 @@ export async function collectCheckResult(cwd, opts = {}) {
                     ? `${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}`,
@@ -1687,6 +2035,21 @@ export async function collectCheckResult(cwd, opts = {}) {
             });
         }
     }
+    // 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 = [];
@@ -1700,6 +2063,7 @@ export async function collectCheckResult(cwd, opts = {}) {
             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",
@@ -1714,6 +2078,7 @@ export async function collectCheckResult(cwd, opts = {}) {
     // 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 = [];
     const assuranceConfigPath = join(cwd, "nifra.assurance.ts");
     if (provided !== undefined ? provided.present : existsSync(assuranceConfigPath)) {
         try {
@@ -1722,6 +2087,7 @@ export async function collectCheckResult(cwd, opts = {}) {
             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.
@@ -1730,6 +2096,7 @@ export async function collectCheckResult(cwd, opts = {}) {
                 config = provided.config;
                 project = provided.capability;
                 routeAssurance = provided.routeAssurance;
+                evidence = provided.evidence;
             }
             else {
                 const { loadAssuranceConfig } = await import("./assure.js");
@@ -1739,6 +2106,7 @@ export async function collectCheckResult(cwd, opts = {}) {
                     project = await collectCapabilityProjectReport(cwd, config.source, config.capabilities);
                 }
             }
+            applicationRulePacks = parseRulePacks(config.rulePacks);
             const capabilityReport = project?.report;
             if (config.capabilities !== undefined && project !== undefined) {
                 for (const finding of project.report.findings) {
@@ -1748,6 +2116,11 @@ export async function collectCheckResult(cwd, opts = {}) {
                     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",
@@ -1756,18 +2129,29 @@ export async function collectCheckResult(cwd, opts = {}) {
                             : truncation !== undefined
                                 ? { chain: truncation.chain }
                                 : {}),
-                        message: `${finding.message} - ${CAPABILITY_HINT}`,
-                        fix: CAPABILITY_HINT,
-                        suggestion: {
-                            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.",
-                            ],
-                        },
+                        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.",
+                                ],
+                            },
                     });
                 }
             }
@@ -1779,6 +2163,10 @@ export async function collectCheckResult(cwd, opts = {}) {
                             ? { 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)) {
@@ -1791,7 +2179,7 @@ export async function collectCheckResult(cwd, opts = {}) {
                 else {
                     try {
                         const current = await buildNifraManifest({
-                            source: config.source,
+                            evidence,
                             assurance,
                             ...(capabilityReport !== undefined ? { capabilities: capabilityReport } : {}),
                         });
@@ -1842,84 +2230,289 @@ export async function collectCheckResult(cwd, opts = {}) {
             });
         }
     }
+    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 {
+            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 ruleContext = {
+        root: cwd,
+        sources: sourceIndex(sourceFiles),
+        project: {
+            legacyDiagnostics: diagnostics,
+            assurance: opts.assurance,
+            // Route registrations collected during the source walk, so the route-table rules
+            // (rules/routes.ts) lint them without a second scan.
+            staticRoutes,
+        },
+    };
+    const structuredDiagnostics = [...structuredExtras];
+    let registryDiagnostics = [];
+    try {
+        registryDiagnostics = await runRuleRegistry(ruleContext, [...legacyRules, ...securityRules, ...routeRules], applicationRulePacks);
+        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 = diagnostics.length;
+    const total = finalDiagnostics.length;
     const max = opts.maxDiagnostics;
-    const shown = max !== undefined && total > max ? diagnostics.slice(0, max) : diagnostics;
-    return {
-        ok: !diagnostics.some((diagnostic) => diagnostic.severity === "error"),
+    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;
 }
-/** Run the full check; print a report (`--json` for machine output) and return whether it passed. */
-export async function runCheck(cwd, opts = {}) {
-    // The check view over the one project verification: the same collector `assure` and `levels` read.
-    const { collectProjectVerification } = await import("./verification.js");
-    const verification = await collectProjectVerification(cwd, { lintsOnly: opts.lintsOnly ?? false });
-    const result = await verification.check();
-    if (opts.json) {
-        console.log(JSON.stringify(result, null, 2));
-        return result.ok;
-    }
-    console.log("nifra check\n");
-    console.log(result.typecheck === "pass"
+/** 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
+ * its rule code, so a finding that can flip the exit code is never invisible in the default output. */
+const REPORT_SECTIONS = [
+    ["typecheck", "typecheck"],
+    ["typed-client", "hand-rolled fetch() to your own API"],
+    ["untyped-client", 'client("…") missing its <typeof app> type argument'],
+    ["server-only-import", "server-only import in a route module"],
+    ["interpolated-sql", "SQL built by interpolating a value into the statement"],
+    ["response-route", "route returns a raw Response (typed client → data: never)"],
+    ["undeclared-dependency", "undeclared dependency in package.json"],
+    ["duplicate-install", "duplicate identity-sensitive dependency install"],
+    ["stale-workspace-dist", "workspace-linked dist older than its source"],
+    ["pipeline", "bundler pipeline (Vite/Bun) config"],
+    ["server-manifest-drift", "server-manifest.ts drifted from routes/"],
+    ["manifest-drift", "versioned trust manifest drift"],
+    ["capability-assurance", "effect/capability assurance"],
+    ["capability-config", "capability assurance config"],
+    ["check-config", "nifra.check.json"],
+];
+/**
+ * Render the human-readable check report as lines. Pure (no I/O, no cwd) so tests can assert
+ * report/exit-code parity: every diagnostic in `result.diagnostics` appears in the output, and the
+ * trailer states the error/advisory counts that produced `ok`.
+ */
+export function renderCheckReport(result) {
+    const lines = [];
+    lines.push("nifra check", "");
+    lines.push(result.typecheck === "pass"
         ? "✓ typecheck passed"
         : result.typecheck === "fail"
             ? "✗ typecheck failed - the frontend/backend contract is broken"
-            : "• typecheck skipped (no tsconfig / typescript not installed)");
+            : `⚠ typecheck SKIPPED - ${result.typecheckNote ?? "no tsconfig / typescript not installed"} (the contract gate did not run)`);
+    // Stated on every run, passing or not. "Which bundler is this app on" decides which plugin slot is
+    // live and which toolchain compiles a component, so it belongs in the report rather than only in the
+    // dev server's banner - where CI never sees it.
+    if (result.pipeline !== undefined) {
+        lines.push(result.pipeline.pipeline === "unknown"
+            ? `• bundler: not readable from ${result.pipeline.configFile} - ${result.pipeline.reason}`
+            : `• bundler: ${result.pipeline.pipeline} (${result.pipeline.reason})`);
+    }
     if (result.externalMounts !== undefined && result.externalMounts.length > 0) {
-        console.log(`• intentional external mounts (not typed-client checked): ${result.externalMounts.join(", ")}`);
-    }
-    const counts = (rule) => result.diagnostics.filter((d) => d.rule === rule);
-    for (const [rule, label] of [
-        ["typecheck", "typecheck"],
-        ["typed-client", "hand-rolled fetch() to your own API"],
-        ["untyped-client", 'client("…") missing its <typeof app> type argument'],
-        ["server-only-import", "server-only import in a route module"],
-        ["interpolated-sql", "SQL built by interpolating a value into the statement"],
-        ["response-route", "route returns a raw Response (typed client → data: never)"],
-        ["undeclared-dependency", "undeclared dependency in package.json"],
-        ["duplicate-install", "duplicate identity-sensitive dependency install"],
-        ["stale-workspace-dist", "workspace-linked dist older than its source"],
-        ["server-manifest-drift", "server-manifest.ts drifted from routes/"],
-        ["manifest-drift", "versioned trust manifest drift"],
-        ["capability-assurance", "effect/capability assurance"],
-        ["capability-config", "capability assurance config"],
-        ["check-config", "nifra.check.json"],
-    ]) {
-        const ds = counts(rule);
-        if (rule === "response-route" || rule === "stale-workspace-dist") {
-            // Advisory: surfaced with ⚠, never folded into pass/fail.
-            console.log(ds.length === 0 ? `✓ ${label}: none` : `⚠ ${label}: ${ds.length} (advisory)`);
-        }
-        else if (rule !== "typecheck") {
-            console.log(ds.length === 0 ? `✓ ${label}: none` : `✗ ${label}: ${ds.length}`);
+        lines.push(`• intentional external mounts (not typed-client checked): ${result.externalMounts.join(", ")}`);
+    }
+    if (result.ruleOverrides !== undefined) {
+        const active = Object.entries(result.ruleOverrides).map(([rule, override]) => {
+            const parts = [];
+            if (override.severity !== undefined)
+                parts.push(`severity=${override.severity}`);
+            if (override.ignore !== undefined)
+                parts.push(`ignore=${override.ignore.join(",")}`);
+            return `${rule} (${parts.join(", ")})`;
+        });
+        lines.push(`• rule overrides from nifra.check.json: ${active.join("; ")}`);
+    }
+    const renderSection = (rule, label, ds) => {
+        if (rule !== "typecheck") {
+            // Marked by SEVERITY, not by rule name. `response-route` and `stale-workspace-dist` are advisory
+            // in whole; `pipeline` is the first rule that is advisory in part (a misplaced plugin fails, a
+            // resolve condition the Bun dev bundler can't take does not), so the counts are split rather than
+            // rounded up to the worse of the two.
+            const errors = ds.filter((d) => d.severity === "error").length;
+            const advisory = ds.length - errors;
+            lines.push(ds.length === 0
+                ? `✓ ${label}: none`
+                : errors === 0
+                    ? `⚠ ${label}: ${advisory} (advisory)`
+                    : `✗ ${label}: ${errors}${advisory > 0 ? ` (+${advisory} advisory)` : ""}`);
         }
         for (const d of ds) {
-            console.log(`    ${d.file ?? ""}${d.line ? `:${d.line}` : ""}  ${d.message}`);
+            lines.push(`    ${d.file ?? ""}${d.line ? `:${d.line}` : ""}  ${d.message}`);
             if (d.suggestion !== undefined) {
-                console.log(`      fix: ${d.suggestion.title}`);
+                lines.push(`      fix: ${d.suggestion.title}`);
                 if (d.suggestion.command !== undefined) {
-                    console.log(`      command: ${d.suggestion.command.join(" ")}`);
+                    lines.push(`      command: ${d.suggestion.command.join(" ")}`);
                 }
                 if (d.suggestion.diff !== undefined) {
-                    console.log(d.suggestion.diff
-                        .split("\n")
-                        .map((line) => `      ${line}`)
-                        .join("\n"));
+                    for (const line of d.suggestion.diff.split("\n"))
+                        lines.push(`      ${line}`);
                 }
                 for (const step of d.suggestion.steps ?? [])
-                    console.log(`      - ${step}`);
+                    lines.push(`      - ${step}`);
             }
         }
+    };
+    for (const [rule, label] of REPORT_SECTIONS) {
+        renderSection(rule, label, result.diagnostics.filter((d) => d.rule === rule));
+    }
+    // Generic section: diagnostics whose rule has no named section above (registry rules publishing
+    // under their NF- code, application rule packs). These count toward `ok` exactly like the named
+    // ones, so they get the same severity-marked rendering - only "✓ …: none" is skipped, because
+    // the set of possible unlisted rules is open-ended.
+    const named = new Set(REPORT_SECTIONS.map(([rule]) => rule));
+    const extraRules = [];
+    for (const d of result.diagnostics) {
+        if (!named.has(d.rule) && !extraRules.includes(d.rule))
+            extraRules.push(d.rule);
+    }
+    for (const rule of extraRules) {
+        const title = RULE_CODES[rule];
+        renderSection(rule, title !== undefined ? `${title} (${rule})` : rule, result.diagnostics.filter((d) => d.rule === rule));
+    }
+    if (result.truncated !== undefined) {
+        lines.push(`• showing ${result.truncated.shown} of ${result.truncated.total} diagnostics (truncated)`);
+    }
+    const errors = result.diagnostics.filter((d) => d.severity === "error").length;
+    const advisory = result.diagnostics.length - errors;
+    lines.push("", result.ok
+        ? advisory > 0
+            ? `✓ check passed (${advisory} advisory)`
+            : "✓ check passed"
+        : `✗ check failed: ${errors} error${errors === 1 ? "" : "s"}${advisory > 0 ? ` (+${advisory} advisory)` : ""}`);
+    return lines;
+}
+/** Run the full check; print a report (`--json` for machine output) and return whether it passed. */
+export async function runCheck(cwd, opts = {}) {
+    // The check view over the one project verification: the same collector `assure` and `levels` read.
+    const { collectProjectVerification } = await import("./verification.js");
+    const verification = await collectProjectVerification(cwd, { lintsOnly: opts.lintsOnly ?? false });
+    const result = await verification.check();
+    if (opts.json) {
+        console.log(JSON.stringify(opts.structured === true && result.structuredDiagnostics !== undefined
+            ? { ...result, diagnostics: result.structuredDiagnostics }
+            : result, null, 2));
+        return result.ok;
     }
-    console.log(result.ok ? "\n✓ check passed" : "\n✗ check failed");
+    console.log(renderCheckReport(result).join("\n"));
     // Discoverability nudge: a project with no `.mcp.json` hasn't wired its nifra MCP for coding agents.
     // `nifra init-agents` writes it (+ .cursor/mcp.json + a CLAUDE.md preamble), no-clobber. A non-fatal
     // one-line tip in the human report only (the `--json` path returns above, unaffected).