@nifrajs/cli 2.11.0 → 2.12.0

package/src/check.ts

@@ -16,16 +16,24 @@
  * 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 type { AssuranceConfig, AssuranceReport } from "@nifrajs/core/assurance"
+import { type ProjectEvidenceSnapshot, snapshotProjectEvidence } from "@nifrajs/core/evidence"
 import { Glob } from "bun"
 import type * as TSApi from "typescript"
 import type { CapabilityProjectReport } from "./capabilities-tool.ts"
-import { importTypeScript, type TypeScriptApi } from "./internal/typescript-import.ts"
+import { type Diagnostic, diagnostic } from "./diagnostics.ts"
+import { createSourceFacts, type SourceFacts } from "./internal/source-facts.ts"
+import { importProjectTypeScript, type TypeScriptApi } from "./internal/typescript-import.ts"
 // Type-only: `pipeline-report.ts` imports this module's source scanners, so a value import here would
 // close a cycle. Doctor is what actually runs the collector (see the `pipeline` rule below).
 import type { PipelineReport } from "./pipeline-report.ts"
+import { RULE_CODES } from "./rules/codes.ts"
+import { parseRulePacks, type RuleContext, runRuleRegistry, sourceIndex } from "./rules/index.ts"
+import { LEGACY_RULE_CODES, legacyRules } from "./rules/legacy.ts"
+import { routeRules } from "./rules/routes.ts"
+import { securityRules } from "./rules/security.ts"
 
 export interface SourceFinding {
   readonly file: string
@@ -236,6 +244,7 @@ function scanRoutePattern(
   content: string,
   code: string,
   pattern: RegExp,
+  facts?: SourceFacts,
 ): StaticRouteFinding[] {
   const out: StaticRouteFinding[] = []
   const lines = content.split("\n")
@@ -247,6 +256,16 @@ function scanRoutePattern(
       `${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 })
   }
@@ -470,12 +489,16 @@ export function scanFetchText(
 }
 
 /** Statically collect simple Nifra route registrations from source, without importing app code. */
-export function scanStaticRouteText(file: string, content: string): StaticRouteFinding[] {
+export function scanStaticRouteText(
+  file: string,
+  content: string,
+  facts?: SourceFacts,
+): StaticRouteFinding[] {
   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)
 }
 
@@ -522,21 +545,228 @@ interface SqlExpressionShape {
 /** Module-scope `const` initializers by name - the one binding form the SQL scanner resolves. */
 type ModuleConsts = ReadonlyMap<string, TSApi.Expression>
 
-/** 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: TypeScriptApi, source: TSApi.SourceFile): ModuleConsts {
-  const map = new Map<string, TSApi.Expression>()
+/** A name some other module exports, named exactly as the edge that reaches it writes it. */
+interface ExportEdge {
+  readonly specifier: string
+  readonly exported: string
+}
+
+/**
+ * One module's provable module-scope bindings: its top-level `const` initializers plus the exact
+ * import/export edges this scan is allowed to follow.
+ *
+ * Everything absent from these maps stays unresolved, and an unresolved interpolation keeps flagging.
+ * That is the whole safety argument: resolution can only ever make this rule QUIETER, so a form the
+ * scan cannot prove must fall out as "unknown" rather than be guessed at. Deliberately absent:
+ * `export default`, `export let`/`var`, destructured or computed names, default and namespace imports,
+ * `export * as ns`, `require`, and dynamic `import()`.
+ */
+interface SqlModuleScope {
+  /** The module's identity - an absolute path from the loader, or the entry file's path as given. Keys
+   * the parsed-scope cache and the cycle guard, and is the base its own specifiers resolve against. */
+  readonly id: string
+  readonly consts: ModuleConsts
+  /** Local name bound by `import { X as local }` → the edge that provides it. */
+  readonly imports: ReadonlyMap<string, ExportEdge>
+  /** Exported name → the local name it reads (`export { a as b }` → `b` → `a`). */
+  readonly localExports: ReadonlyMap<string, string>
+  /** Exported name → another module's export (`export { a as b } from "./m"`). */
+  readonly reExports: ReadonlyMap<string, ExportEdge>
+  /** `export * from "./m"` specifiers, in source order. */
+  readonly starExports: readonly string[]
+}
+
+/** 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: TypeScriptApi, id: string, source: TSApi.SourceFile): SqlModuleScope {
+  const consts = new Map<string, TSApi.Expression>()
+  const imports = new Map<string, ExportEdge>()
+  const localExports = new Map<string, string>()
+  const reExports = new Map<string, ExportEdge>()
+  const starExports: string[] = []
   for (const statement of source.statements) {
-    if (!ts.isVariableStatement(statement)) continue
-    if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0) 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.isVariableStatement(statement)) {
+      if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0) continue
+      const exported =
+        statement.modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) === true
+      for (const declaration of statement.declarationList.declarations) {
+        if (!ts.isIdentifier(declaration.name) || declaration.initializer === undefined) continue
+        consts.set(declaration.name.text, declaration.initializer)
+        if (exported) localExports.set(declaration.name.text, declaration.name.text)
+      }
+      continue
+    }
+    if (ts.isImportDeclaration(statement)) {
+      const clause = statement.importClause
+      if (clause === undefined || clause.isTypeOnly) continue
+      if (!ts.isStringLiteral(statement.moduleSpecifier)) continue
+      const bindings = clause.namedBindings
+      // Only `import { X }` / `import { X as local }`. A default or namespace import binds a value
+      // whose contents this scan cannot prove, so it stays unbound and every use of it flags.
+      if (bindings === undefined || !ts.isNamedImports(bindings)) continue
+      for (const element of bindings.elements) {
+        if (element.isTypeOnly) continue
+        imports.set(element.name.text, {
+          specifier: statement.moduleSpecifier.text,
+          exported: element.propertyName?.text ?? element.name.text,
+        })
       }
+      continue
+    }
+    if (!ts.isExportDeclaration(statement) || statement.isTypeOnly) continue
+    const from = statement.moduleSpecifier
+    if (from !== undefined && !ts.isStringLiteral(from)) continue
+    const clause = statement.exportClause
+    if (clause === undefined) {
+      // No clause and a specifier is `export * from "./m"`. `export * as ns from "./m"` carries a
+      // NamespaceExport clause instead and falls out below, unresolved, which is what we want.
+      if (from !== undefined) starExports.push(from.text)
+      continue
+    }
+    if (!ts.isNamedExports(clause)) continue
+    for (const element of clause.elements) {
+      if (element.isTypeOnly) continue
+      const local = element.propertyName?.text ?? element.name.text
+      if (from === undefined) localExports.set(element.name.text, local)
+      else reExports.set(element.name.text, { specifier: from.text, exported: local })
     }
   }
-  return map
+  return { id, consts, imports, localExports, reExports, starExports }
+}
+
+/** A module's identity + source, as resolved from a specifier. `id` must be stable and absolute: it
+ * keys the parsed-scope cache, seeds the cycle guard, and is what the module's own relative specifiers
+ * resolve against. */
+export interface SqlModuleSource {
+  readonly id: string
+  readonly content: string
+}
+
+/**
+ * Resolves a specifier written in the module `fromModule` to the target's identity + source, or
+ * `undefined` when it cannot be resolved, read, or proved to be in-project source.
+ *
+ * Injected rather than built in, for the same reason {@link ModuleResolver} is: it keeps
+ * {@link scanInterpolatedSql} pure and filesystem-free, so the resolution rules can be unit-tested
+ * against a virtual module graph. {@link createProjectSqlImports} is the on-disk implementation.
+ */
+export type SqlModuleLoader = (fromModule: string, specifier: string) => SqlModuleSource | undefined
+
+/** Cross-module resolution state for one run: the loader plus a parsed-scope cache, so a fragments
+ * module imported by fifty callers is read and parsed once. A cached `undefined` is a REFUSAL (the
+ * module did not parse), cached so it is not re-attempted. Build with {@link createSqlImports}. */
+export interface SqlImports {
+  readonly load: SqlModuleLoader
+  readonly scopes: Map<string, SqlModuleScope | undefined>
+}
+
+export const createSqlImports = (load: SqlModuleLoader): SqlImports => ({
+  load,
+  scopes: new Map(),
+})
+
+/** Where an expression's identifiers are read: the module the expression physically lives in, plus the
+ * run's cross-module state. `imports === undefined` is same-file-only resolution - the behavior before
+ * imported fragments were followed, and still what an unconfigured `scanInterpolatedSql` call does. */
+interface SqlScope {
+  readonly module: SqlModuleScope
+  readonly imports: SqlImports | undefined
+}
+
+/** 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: TypeScriptApi,
+  file: string,
+  content: string,
+): TSApi.SourceFile | undefined {
+  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 as TSApi.SourceFile & { readonly parseDiagnostics?: readonly TSApi.Diagnostic[] }
+  ).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: TypeScriptApi,
+  imports: SqlImports,
+  fromModule: string,
+  specifier: string,
+): SqlModuleScope | undefined {
+  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
+}
+
+/** One exported name resolved to the `const` initializer behind it, together with the scope that
+ * initializer's OWN identifiers must be read in. */
+interface ResolvedExport {
+  readonly expression: TSApi.Expression
+  readonly scope: SqlModuleScope
+}
+
+/**
+ * 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: TypeScriptApi,
+  imports: SqlImports,
+  scope: SqlModuleScope,
+  name: string,
+  hops: number,
+  seen: ReadonlySet<string>,
+): ResolvedExport | undefined {
+  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: ExportEdge): ResolvedExport | undefined => {
+    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: ResolvedExport | undefined
+  for (const specifier of scope.starExports) {
+    const hit = follow({ specifier, exported: name })
+    if (hit === undefined) continue
+    if (found !== undefined) return undefined
+    found = hit
+  }
+  return found
 }
 
 /** Whether `name`, read at `at`, might be re-declared by anything between the read and module scope.
@@ -588,46 +818,67 @@ 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: TypeScriptApi,
   node: TSApi.Expression,
-  consts: ModuleConsts,
+  scope: SqlScope,
   depth: number,
 ): string | undefined {
   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
   if (ts.isNumericLiteral(node)) return node.text
   if (ts.isTemplateExpression(node)) {
     let text = node.head.text
     for (const span of node.templateSpans) {
-      const part = resolveStaticSqlText(ts, span.expression, consts, depth + 1)
+      const part = resolveStaticSqlText(ts, span.expression, scope, depth + 1)
       if (part === undefined) return undefined
       text += part + span.literal.text
     }
     return text
   }
   if (ts.isConditionalExpression(node)) {
-    const whenTrue = resolveStaticSqlText(ts, node.whenTrue, 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) return 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
 }
@@ -637,13 +888,13 @@ function resolveStaticSqlText(
 function templateShape(
   ts: TypeScriptApi,
   template: TSApi.TemplateExpression,
-  consts: ModuleConsts | undefined,
+  scope: SqlScope | undefined,
 ): { staticText: string; dynamic: boolean } {
   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)
+      scope === undefined ? undefined : resolveStaticSqlText(ts, span.expression, scope, 0)
     if (resolved === undefined) dynamic = true
     else staticText += resolved
     staticText += span.literal.text
@@ -655,9 +906,9 @@ function templateShape(
 function sqlExpressionShape(
   ts: TypeScriptApi,
   node: TSApi.Expression,
-  consts?: ModuleConsts,
+  scope?: SqlScope,
 ): SqlExpressionShape {
-  if (ts.isParenthesizedExpression(node)) return sqlExpressionShape(ts, node.expression, consts)
+  if (ts.isParenthesizedExpression(node)) return sqlExpressionShape(ts, node.expression, scope)
   if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
     return {
       staticText: node.text,
@@ -674,7 +925,7 @@ function sqlExpressionShape(
       (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
@@ -699,7 +950,7 @@ function sqlExpressionShape(
     }
   }
   if (ts.isTemplateExpression(node)) {
-    const templated = templateShape(ts, node, consts)
+    const templated = templateShape(ts, node, scope)
     return {
       staticText: templated.staticText,
       dynamic: templated.dynamic,
@@ -709,8 +960,8 @@ function sqlExpressionShape(
     }
   }
   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
@@ -724,11 +975,11 @@ function sqlExpressionShape(
   }
   // 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,
@@ -773,32 +1024,35 @@ function sqlMethod(
 
 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. */
+/**
+ * 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: string,
   content: string,
   ts: TypeScriptApi,
+  imports?: SqlImports,
 ): SourceFinding[] {
   const out: SourceFinding[] = []
   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 as TSApi.SourceFile & { readonly parseDiagnostics?: readonly TSApi.Diagnostic[] }
-  ).parseDiagnostics
-  if (parseDiagnostics !== undefined && parseDiagnostics.length > 0) 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)
+  const source = parseSqlSource(ts, file, content)
+  if (source === undefined) return out
+  // Module-scope bindings, read once per file: an interpolated `const` that resolves to compile-time
+  // text cannot carry request data, so the shared-projection idiom (`const COLS = "id, name"` …
+  // `${COLS}`) stays quiet while mutable, parameter, shadowed, and unprovable names flag as before.
+  const scope: SqlScope = { module: sqlModuleScope(ts, file, source), imports }
   const visit = (node: TSApi.Node): void => {
     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 =
@@ -827,13 +1081,63 @@ export function scanInterpolatedSql(
  * answer a security rule must never give when it did not run.
  */
 export async function scanProjectSql(cwd: string): Promise<SourceFinding[] | undefined> {
-  const ts = await importTypeScript()
+  const ts = await importProjectTypeScript(cwd)
   if (ts === undefined) return undefined
   const out: SourceFinding[] = []
-  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: string): SqlImports {
+  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-
@@ -922,7 +1226,11 @@ export function scanRemovedImports(file: string, content: string): SourceFinding
 /** 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: string, content: string): ServerImportFinding[] {
+export function scanServerOnlyImports(
+  file: string,
+  content: string,
+  facts?: SourceFacts,
+): ServerImportFinding[] {
   if (!ROUTE_FILE.test(file)) return []
   const out: ServerImportFinding[] = []
   const lines = content.split("\n")
@@ -933,6 +1241,13 @@ export function scanServerOnlyImports(file: string, content: string): ServerImpo
     if (positions[m.index] === " ") continue
     const specifier = m[1] ?? ""
     if (!SERVER_ONLY.test(specifier)) continue
+    if (facts !== undefined) {
+      const source = facts.parse(file, content)
+      // Inline `import { type X } from "…"` is erased just like `import type`; don't call it a
+      // runtime leak. A parse failure keeps the old lexical finding so the security rule fails closed.
+      if (source !== undefined && facts.isValueImportAt(source, m.index, specifier) === false)
+        continue
+    }
     const line = lineAt(content, m.index)
     out.push({ file, line, snippet: (lines[line - 1] ?? "").trim(), specifier })
   }
@@ -979,22 +1294,31 @@ const staticImportRegex = (): RegExp => new RegExp(STATIC_IMPORT.source, STATIC_
  * 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: string): Array<{ specifier: string; index: number }> {
+function staticImportEdges(
+  content: string,
+  facts?: SourceFacts,
+  file?: string,
+): Array<{ specifier: string; index: number }> {
   const edges: Array<{ specifier: string; index: number }> = []
   const re = staticImportRegex()
   const code = stripComments(content)
   const positions = codePositionMask(content)
   for (let m = re.exec(code); m !== null; m = re.exec(code)) {
     if (positions[m.index] === " ") continue
-    if (m[1] !== undefined) 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: string): string[] {
-  return staticImportEdges(content).map((e) => e.specifier)
+export function parseStaticImports(content: string, facts?: SourceFacts, file?: string): string[] {
+  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
@@ -1037,6 +1361,7 @@ export function walkServerOnlyChain(
   routeContent: string,
   resolve: ModuleResolver,
   read: ModuleReader,
+  facts?: SourceFacts,
 ): readonly string[] | undefined {
   // Frontier nodes carry the absolute file to inspect, the source to scan, the display chain so far
   // (route + the as-written specifier of each hop), and the file the imports resolve relative to.
@@ -1053,7 +1378,7 @@ export function walkServerOnlyChain(
     const next: Node[] = []
     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)
@@ -1094,6 +1419,7 @@ export function resolveServerOnlyChains(
   content: string,
   resolve: ModuleResolver,
   read: ModuleReader,
+  facts?: SourceFacts,
 ): TransitiveServerImportFinding[] {
   if (!ROUTE_FILE.test(file)) return []
   const lines = content.split("\n")
@@ -1102,7 +1428,7 @@ export function resolveServerOnlyChains(
   // 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)
     const snippet = (lines[line - 1] ?? "").trim()
@@ -1141,7 +1467,7 @@ export function resolveServerOnlyChains(
         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
@@ -1170,7 +1496,11 @@ const RESPONSE_RETURN = /(?:=>\s*|return\s+)(?:new\s+Response|Response\s*\.\s*js
 
 /** 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: string, content: string): SourceFinding[] {
+export function scanResponseRoutes(
+  file: string,
+  content: string,
+  facts?: SourceFacts,
+): SourceFinding[] {
   // 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)
@@ -1179,6 +1509,12 @@ export function scanResponseRoutes(file: string, content: string): SourceFinding
   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
@@ -1337,16 +1673,42 @@ interface TypecheckResult {
   readonly note?: string
   readonly output?: string
   readonly cancelled?: boolean
+  /** tsconfig.json exists but no `typescript` install was found walking up from cwd. The contract
+   * gate could not run - the caller surfaces this as a FAILING diagnostic, never a silent skip. */
+  readonly missingTypeScript?: boolean
+}
+
+/**
+ * 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: string): string | undefined {
+  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: string, signal?: AbortSignal): Promise<TypecheckResult> {
   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" }
   const proc = Bun.spawn(["bun", tscBin, "--noEmit", "-p", tsconfig], {
@@ -1388,27 +1750,13 @@ const TSC_LINE = /^(.+?)\((\d+),\d+\):\s*(?:error|warning)\s+TS\d+:\s*(.+)$/
 
 /** A single machine-readable check failure - the unit an agent (or CI) acts on. */
 export interface CheckDiagnostic {
-  readonly rule:
-    | "typecheck"
-    | "typed-client"
-    | "untyped-client"
-    | "server-only-import"
-    | "removed-import"
-    | "interpolated-sql"
-    | "response-route"
-    | "undeclared-dependency"
-    | "duplicate-install"
-    | "stale-workspace-dist"
-    | "pipeline"
-    | "server-manifest-drift"
-    | "manifest-drift"
-    | "capability-assurance"
-    | "capability-config"
-    | "check-config"
+  readonly rule: string
   /** `error` fails the gate (a real contract break); `warning` is advisory - surfaced to the agent but
    * does NOT fail `nifra check`, for patterns that are sometimes intentional (a route returning a raw
    * `Response`, which silently drops the typed client to `data: never` but is valid for files/redirects). */
-  readonly severity: "error" | "warning"
+  readonly severity: "error" | "warning" | "info"
+  /** Stable diagnostic protocol code. The legacy `rule` remains for compatibility. */
+  readonly code?: string
   readonly file?: string
   readonly line?: number
   readonly message: string
@@ -1431,6 +1779,8 @@ export interface CheckDiagnostic {
    * edge rather than fabricating a deeper path - never a lie.
    */
   readonly chain?: readonly string[]
+  readonly evidence?: readonly string[]
+  readonly verify?: string
 }
 
 export interface CheckSuggestion {
@@ -1446,7 +1796,12 @@ export interface CheckSuggestion {
 export interface CheckResult {
   readonly ok: boolean
   readonly typecheck: "pass" | "fail" | "skipped"
+  /** Why `typecheck` is `"skipped"` (no tsconfig.json, typescript not installed, lints-only mode).
+   * Absent when the typecheck ran. Echoed in the human report so a skip is never a dim mystery. */
+  readonly typecheckNote?: string
   readonly diagnostics: readonly CheckDiagnostic[]
+  /** Normalized diagnostics with stable codes for agents and external renderers. */
+  readonly structuredDiagnostics?: readonly Diagnostic[]
   /**
    * Which bundler this app's phases run on, read statically from the config, and how nifra concluded
    * it. Returned even when nothing is wrong: an agent reading this project has to know which plugin
@@ -1458,6 +1813,10 @@ export interface CheckResult {
    * better-auth). Echoed here so `--json` / the MCP tool / the report can show what the typed-client scan
    * deliberately skipped - a suppressed prefix stays auditable instead of silently hiding real drift. */
   readonly externalMounts?: readonly string[]
+  /** Active per-rule overrides from `nifra.check.json` `rules`, echoed verbatim so a retagged or
+   * suppressed finding stays auditable in `--json`, the MCP tool, and the human report - config can
+   * lower (or raise) the gate, but never invisibly. */
+  readonly ruleOverrides?: Readonly<Record<string, RuleOverride>>
   /** Set only when the caller passed `maxDiagnostics` and there were more - `diagnostics` then holds the
    * first `shown` of `total`. It caps the serialized size so the `nifra_check` MCP tool can't emit a
    * message large enough to break the stdio transport; fix the shown diagnostics and re-run for the rest. */
@@ -1481,31 +1840,103 @@ export interface CheckAssuranceContext {
   readonly routeAssurance?: AssuranceReport
   /** Static capability provenance, when the config declares a capabilities policy. */
   readonly capability?: CapabilityProjectReport
+  /** Canonical token-only evidence reused by manifest and other offline projections. */
+  readonly evidence?: ProjectEvidenceSnapshot
 }
 
 /** Optional per-project `nifra.check.json` - pure data (no code execution), so it's safe to read before
  * the app is built or even importable, preserving check's pre-`loadApp` invariant. */
 interface CheckConfig {
   readonly externalMounts: readonly string[]
+  readonly rules: Readonly<Record<string, RuleOverride>>
+}
+
+/**
+ * One entry of `nifra.check.json` `rules`, keyed by legacy rule name (`response-route`) or stable
+ * NF- code (`NF-S002`) - one key retags the finding in both diagnostic views. `severity: "off"`
+ * drops the rule's findings; `ignore` drops findings whose file matches any of the globs. Overrides
+ * are applied centrally BEFORE `ok` is computed and echoed in the result and the human report -
+ * configuration can lower (or raise) the gate, but never invisibly.
+ */
+export interface RuleOverride {
+  readonly severity?: "error" | "warn" | "info" | "off"
+  readonly ignore?: readonly string[]
 }
 
-/** 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`). */
-async function loadCheckConfig(cwd: string): Promise<{ config: CheckConfig; error?: string }> {
+const OVERRIDE_SEVERITIES: readonly string[] = ["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: string,
+): Promise<{ config: CheckConfig; error?: string; warnings: readonly string[] }> {
   const path = join(cwd, "nifra.check.json")
-  if (!existsSync(path)) return { config: { externalMounts: [] } }
+  const empty: CheckConfig = { externalMounts: [], rules: {} }
+  if (!existsSync(path)) return { config: empty, warnings: [] }
   try {
-    const parsed = JSON.parse(await Bun.file(path).text()) as { externalMounts?: unknown }
+    const parsed = JSON.parse(await Bun.file(path).text()) as {
+      externalMounts?: unknown
+      rules?: unknown
+    }
     const raw = Array.isArray(parsed.externalMounts) ? parsed.externalMounts : []
     const externalMounts = raw
       .filter((m): m is string => typeof m === "string" && m.startsWith("/"))
       .map((m) => m.replace(/\/\*+$/, "").replace(/\/+$/, "") || "/")
-    return { config: { externalMounts } }
+    const warnings: string[] = []
+    const rules: Record<string, RuleOverride> = {}
+    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 as { severity?: unknown; ignore?: unknown }
+          const override: {
+            severity?: NonNullable<RuleOverride["severity"]>
+            ignore?: readonly string[]
+          } = {}
+          if (entry.severity !== undefined) {
+            if (
+              typeof entry.severity === "string" &&
+              OVERRIDE_SEVERITIES.includes(entry.severity)
+            ) {
+              override.severity = entry.severity as NonNullable<RuleOverride["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): g is string => 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: [],
     }
   }
 }
@@ -1693,28 +2124,41 @@ export async function collectCheckResult(
   // 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: Array<{ rel: string; content: string }> = []
+  const sourceFiles: Array<{ file: string; content: string }> = []
   // 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<TypecheckResult>({ ran: false, ok: true, note: "skipped (lintsOnly)" })
+      ? Promise.resolve<TypecheckResult>({ 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.ts").then((m) => m.collectDoctorResult(cwd)),
     scanServerManifestDrift(cwd),
@@ -1743,10 +2187,13 @@ export async function collectCheckResult(
     }
   }
   for (const { rel, content } of routeModules) {
-    serverImports.push(...resolveServerOnlyChains(rel, content, resolveModule, readModule))
+    serverImports.push(
+      ...resolveServerOnlyChains(rel, content, resolveModule, readModule, sourceFacts),
+    )
   }
 
   const diagnostics: CheckDiagnostic[] = []
+  const structuredExtras: Diagnostic[] = []
   if (checkConfigError !== undefined) {
     diagnostics.push({
       rule: "check-config",
@@ -1756,6 +2203,32 @@ export async function collectCheckResult(
       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
@@ -1946,6 +2419,7 @@ export async function collectCheckResult(
           ? `${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}`,
@@ -1983,6 +2457,7 @@ export async function collectCheckResult(
       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",
@@ -1998,6 +2473,7 @@ export async function collectCheckResult(
   // 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: readonly import("./rules/index.ts").RulePack[] = []
   const assuranceConfigPath = join(cwd, "nifra.assurance.ts")
   if (provided !== undefined ? provided.present : existsSync(assuranceConfigPath)) {
     try {
@@ -2006,6 +2482,7 @@ export async function collectCheckResult(
       let config: AssuranceConfig
       let project: CapabilityProjectReport | undefined
       let routeAssurance: AssuranceReport | undefined
+      let evidence: ProjectEvidenceSnapshot | undefined
       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.
@@ -2013,6 +2490,7 @@ export async function collectCheckResult(
         config = provided.config as AssuranceConfig
         project = provided.capability
         routeAssurance = provided.routeAssurance
+        evidence = provided.evidence
       } else {
         const { loadAssuranceConfig } = await import("./assure.ts")
         config = await loadAssuranceConfig(cwd)
@@ -2021,6 +2499,7 @@ export async function collectCheckResult(
           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) {
@@ -2038,6 +2517,12 @@ export async function collectCheckResult(
                     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",
@@ -2046,18 +2531,30 @@ export async function collectCheckResult(
               : 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.",
+                    ],
+                  },
           })
         }
       }
@@ -2076,6 +2573,10 @@ export async function collectCheckResult(
                 : {}),
             },
           )
+        evidence ??= snapshotProjectEvidence(config.source, {
+          assurance,
+          ...(capabilityReport !== undefined ? { capabilities: capabilityReport } : {}),
+        })
         const path = resolve(cwd, config.manifest.path ?? "nifra.manifest.json")
         let message: string | undefined
         if (!assurance.ok || (capabilityReport !== undefined && !capabilityReport.ok)) {
@@ -2086,7 +2587,7 @@ export async function collectCheckResult(
         } else {
           try {
             const current = await buildNifraManifest({
-              source: config.source,
+              evidence,
               assurance,
               ...(capabilityReport !== undefined ? { capabilities: capabilityReport } : {}),
             })
@@ -2136,80 +2637,221 @@ export async function collectCheckResult(
     }
   }
 
+  try {
+    const { checkContractsLock } = await import("./contracts.ts")
+    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: 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: Diagnostic[] = []
+  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: (string | undefined)[]): RuleOverride | undefined => {
+    for (const key of keys) {
+      if (key !== undefined && checkConfig.rules[key] !== undefined) return checkConfig.rules[key]
+    }
+    return undefined
+  }
+  const ignoreGlobs = new Map<RuleOverride, Glob[]>()
+  const dropped = (override: RuleOverride, file: string | undefined): boolean => {
+    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<CheckDiagnostic>((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<Diagnostic>((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: CheckResult = {
+    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 } } : {}),
   }
-}
-
-/** Run the full check; print a report (`--json` for machine output) and return whether it passed. */
-export async function runCheck(
-  cwd: string,
-  opts: { readonly json?: boolean; readonly lintsOnly?: boolean } = {},
-): Promise<boolean> {
-  // The check view over the one project verification: the same collector `assure` and `levels` read.
-  const { collectProjectVerification } = await import("./verification.ts")
-  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
-  }
+  Object.defineProperty(result, "structuredDiagnostics", {
+    value: finalStructured.slice(0, shown.length + structuredExtras.length),
+    enumerable: false,
+  })
+  return result
+}
+
+/** 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"],
+] as const
 
-  console.log("nifra check\n")
-  console.log(
+/**
+ * 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: CheckResult): string[] {
+  const lines: string[] = []
+  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) {
-    console.log(
+    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(
+    lines.push(
       `• intentional external mounts (not typed-client checked): ${result.externalMounts.join(", ")}`,
     )
   }
-  const counts = (rule: CheckDiagnostic["rule"]): CheckDiagnostic[] =>
-    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"],
-    ["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"],
-  ] as const) {
-    const ds = counts(rule)
+  if (result.ruleOverrides !== undefined) {
+    const active = Object.entries(result.ruleOverrides).map(([rule, override]) => {
+      const parts: string[] = []
+      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: string, label: string, ds: readonly CheckDiagnostic[]): void => {
     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
@@ -2217,7 +2859,7 @@ export async function runCheck(
       // rounded up to the worse of the two.
       const errors = ds.filter((d) => d.severity === "error").length
       const advisory = ds.length - errors
-      console.log(
+      lines.push(
         ds.length === 0
           ? `✓ ${label}: none`
           : errors === 0
@@ -2226,25 +2868,88 @@ export async function runCheck(
       )
     }
     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}`)
+        for (const step of d.suggestion.steps ?? []) lines.push(`      - ${step}`)
       }
     }
   }
-  console.log(result.ok ? "\n✓ check passed" : "\n✗ check failed")
+  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<string>(REPORT_SECTIONS.map(([rule]) => rule))
+  const extraRules: string[] = []
+  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 as Record<string, string | undefined>)[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: string,
+  opts: {
+    readonly json?: boolean
+    readonly lintsOnly?: boolean
+    readonly structured?: boolean
+  } = {},
+): Promise<boolean> {
+  // The check view over the one project verification: the same collector `assure` and `levels` read.
+  const { collectProjectVerification } = await import("./verification.ts")
+  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(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).