@nifrajs/cli 3.3.0 → 4.0.0

package/src/check-diagnostics.ts

@@ -6,31 +6,30 @@
  */
 
 import { existsSync } from "node:fs"
-import { join, resolve } from "node:path"
+import { join } from "node:path"
 import type { AssuranceConfig, AssuranceReport } from "@nifrajs/core/assurance"
-import { type ProjectEvidenceSnapshot, snapshotProjectEvidence } from "@nifrajs/core/evidence"
-import { SINGLE_COPY_REGISTER_SPECIFIER } from "@nifrajs/core/single-copy"
+import type { CapabilityGap } from "@nifrajs/core/capabilities"
+import type { ProjectEvidenceSnapshot } from "@nifrajs/core/evidence"
 import type { CapabilityProjectReport } from "./capabilities-tool.ts"
-import type { SourceFinding, StaticRouteFinding } from "./check-scan.ts"
 import {
-  IDENT,
-  parseSimpleFetchCall,
-  REMOVED_IMPORTS,
-  SIMPLE_REWRITE_METHODS,
-} from "./check-scan.ts"
-import { type Diagnostic, diagnostic } from "./diagnostics.ts"
+  type Diagnostic,
+  type DiagnosticSuggestion,
+  diagnostic,
+  diagnosticCompatibilityOf,
+} from "./diagnostics.ts"
 import type { DuplicateInstallFinding } from "./doctor.ts"
-import type { TypeScriptApi } from "./internal/typescript-import.ts"
 import type { PipelineReport } from "./pipeline-report.ts"
 import { freezeProjectFacts, type ProjectFactsSeed } from "./project-facts.ts"
-import { parseRulePacks, type RuleContext, runRuleRegistry } from "./rules/index.ts"
+import { dataGuardRules } from "./rules/data-guard.ts"
+import { parseRulePacks, runRuleRegistry } from "./rules/index.ts"
 import { islandRules } from "./rules/islands.ts"
-import { LEGACY_RULE_CODES, legacyRules } from "./rules/legacy.ts"
+import { LEGACY_RULE_CODES, LEGACY_RULE_ORDER, legacyRules } from "./rules/legacy.ts"
 import { nanoRules } from "./rules/nano.ts"
+import { pageRules } from "./rules/pages.ts"
 import { routeRules } from "./rules/routes.ts"
+import { secretRules } from "./rules/secrets.ts"
 import { securityRules } from "./rules/security.ts"
-
-const TSC_LINE = /^(.+?)\((\d+),\d+\):\s*(?:error|warning)\s+TS\d+:\s*(.+)$/
+import { zoneRules } from "./rules/zones.ts"
 
 /** A single machine-readable check failure - the unit an agent (or CI) acts on. */
 export interface CheckDiagnostic {
@@ -67,14 +66,7 @@ export interface CheckDiagnostic {
   readonly verify?: string
 }
 
-export interface CheckSuggestion {
-  readonly kind: "edit" | "command" | "manual"
-  readonly title: string
-  readonly diff?: string
-  /** argv array, not a shell string, so MCP clients can run it without quoting hazards. */
-  readonly command?: readonly string[]
-  readonly steps?: readonly string[]
-}
+export type CheckSuggestion = DiagnosticSuggestion
 
 /** The structured result of a full check - what `--json` prints and the `nifra_check` MCP tool returns. */
 export interface CheckResult {
@@ -97,6 +89,9 @@ 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[]
+  /** Mounts declared `opaque` - outside capability assurance on purpose, each with its stated reason.
+   * Listed on every run so the report states its own boundary; never a failure. */
+  readonly knownGaps?: readonly CapabilityGap[]
   /** 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. */
@@ -355,29 +350,6 @@ function matchIgnoreGlobClass(spec: string, value: string): boolean {
   return negated ? !matched : matched
 }
 
-const UNTYPED_CLIENT_HINT =
-  'client("…") without a type argument - write client<typeof app>("…") (or client(contract, url)) so the compiler can catch drift'
-const FETCH_HINT =
-  "hand-rolled fetch() to your own API - call it through client<typeof app> (from @nifrajs/client) so the compiler catches drift"
-const SERVER_IMPORT_HINT =
-  "server-only import in a route module (bundled for the browser) - reach it via c.db / ctx.api inside a loader, never a top-level import"
-const RESPONSE_ROUTE_HINT =
-  "route handler returns a raw Response - the typed client infers `data: never`, so drift detection is lost for this route. Return a plain object (it's serialized for you); for a stream use a typed SSE route (`app.sse(...)`), which keeps typed events; or, if a raw Response is intended (file/redirect), add `{ response: t.… }` or a `// nifra-expect raw-response` comment to mark it and silence this"
-const PIPELINE_DOC_HINT =
-  "nifra runs one bundler per phase - `vitePlugins` feed Vite, `clientPlugins`/`serverPlugins` feed Bun, and the file `nifra build` imports the adapter from is bundled into the server. See the Gotchas section of the Dev & HMR guide."
-const UNDECLARED_DEP_HINT =
-  "imported package is not declared in package.json dependencies - run bun add to declare it"
-const SQL_COMPILER_MISSING_HINT =
-  "the interpolated-SQL rule did NOT run - it parses source with the TypeScript compiler, which is an optional peer and is not installed here. This report says nothing about SQL injection either way. Install it with `bun add -d typescript`"
-const SQL_INTERPOLATION_EXAMPLE = "$" + "{value}"
-const INTERPOLATED_SQL_HINT = `SQL built by interpolating a value into the statement text - the value becomes statement, not a parameter, so anything the caller controls can end the literal and continue as SQL. Pass it as a bound parameter (\`?\` / \`$1\` and an argument), or use your driver's tagged template (sql\`… ${SQL_INTERPOLATION_EXAMPLE} …\`), which binds the substitutions for you`
-const MANIFEST_DRIFT_HINT =
-  "server-manifest.ts is out of sync with routes/ - re-run the build to regenerate it (a disk-less worker bakes this route table, so the drift is a silent edge break), then commit it"
-const TRUST_MANIFEST_DRIFT_HINT =
-  "nifra.manifest.json is missing, invalid, or out of sync - run `nifra manifest emit`, review it, and commit the regenerated trust artifact"
-const CAPABILITY_HINT =
-  "effect/capability assurance failed - align the route declaration with approved adapter provenance; never bypass an owned effect seam"
-
 export interface CheckTypecheckResult {
   readonly ran: boolean
   readonly ok: boolean
@@ -388,10 +360,6 @@ export interface CheckTypecheckResult {
 
 export interface CheckAnalysisInput {
   readonly facts: ProjectFactsSeed
-  readonly typecheck: CheckTypecheckResult
-  readonly sqlCompiler: TypeScriptApi | undefined
-  readonly checkConfigError?: string
-  readonly checkConfigWarnings: readonly string[]
 }
 
 export interface CheckDiagnosticsOptions {
@@ -399,761 +367,175 @@ export interface CheckDiagnosticsOptions {
   readonly assurance?: CheckAssuranceContext
 }
 
-const bySite = (a: SourceFinding, b: SourceFinding): number =>
-  a.file.localeCompare(b.file) || a.line - b.line
-
-function oneLineDiff(file: string, line: number, before: string, after: string): string {
-  return `--- ${file}:${line}\n+++ ${file}:${line}\n@@\n-${before}\n+${after}`
-}
-
-function untypedClientSuggestion(f: SourceFinding): CheckSuggestion {
-  const replacement = f.snippet.replace(/(?<![.\w])client\s*\(/, "client<typeof app>(")
-  return replacement === f.snippet
-    ? {
-        kind: "manual",
-        title: "Add the app type argument to the client factory",
-        steps: [
-          'Change `client("...")` to `client<typeof app>("...")`.',
-          "Make sure the backend app type is imported or otherwise in scope.",
-        ],
-      }
-    : {
-        kind: "edit",
-        title: "Insert `<typeof app>` into the client factory call",
-        diff: oneLineDiff(f.file, f.line, f.snippet, replacement),
-        steps: ["Make sure the backend app type is imported or otherwise in scope."],
-      }
-}
-
-function routeKey(method: string, path: string): string {
-  return `${method.toUpperCase()} ${path}`
-}
-
-function typedClientCall(method: string, path: string): string {
-  const segs = path.split("/").filter((seg) => seg !== "")
-  let chain = "api"
-  if (segs.length === 0) chain += ".index"
-  else {
-    for (const seg of segs) {
-      chain += IDENT.test(seg) ? `.${seg}` : `[${JSON.stringify(seg)}]`
-    }
-  }
-  return `${chain}.${method.toLowerCase()}()`
-}
-
-function staticRouteMap(routes: readonly StaticRouteFinding[]): Map<string, StaticRouteFinding[]> {
-  const out = new Map<string, StaticRouteFinding[]>()
-  for (const route of routes) {
-    if (route.path.includes(":") || route.path.includes("*")) continue
-    const key = routeKey(route.method, route.path)
-    const bucket = out.get(key)
-    if (bucket === undefined) out.set(key, [route])
-    else bucket.push(route)
-  }
-  return out
-}
-
-function ownFetchEditSuggestion(
-  f: SourceFinding,
-  routes: Map<string, StaticRouteFinding[]>,
-): CheckSuggestion | undefined {
-  const call = parseSimpleFetchCall(f.snippet)
-  if (call === undefined || !SIMPLE_REWRITE_METHODS.has(call.method)) return undefined
-  const matches = routes.get(routeKey(call.method, call.path))
-  if (matches === undefined || matches.length !== 1) return undefined
-  const replacementCall = typedClientCall(call.method, call.path)
-  const replacement = `${f.snippet.slice(0, call.start)}${replacementCall}${f.snippet.slice(call.end)}`
-  if (replacement === f.snippet) return undefined
-  const route = matches[0]
-  if (route === undefined) return undefined
-  return {
-    kind: "edit",
-    title: "Rewrite simple own-API fetch to the typed nifra client",
-    diff: oneLineDiff(f.file, f.line, f.snippet, replacement),
-    steps: [
-      `Matched ${route.method} ${route.path} at ${route.file}:${route.line}.`,
-      "Use an in-scope typed client named `api` (`client<typeof app>(baseUrl)` or the route loader/action `api`).",
-      "Update downstream `Response` handling to branch on `{ ok, data, error }` if this variable is used later.",
-    ],
-  }
-}
-
-function ownFetchSuggestion(
-  f: SourceFinding,
-  routes: Map<string, StaticRouteFinding[]>,
-): CheckSuggestion {
-  const exact = ownFetchEditSuggestion(f, routes)
-  if (exact !== undefined) return exact
-  return {
-    kind: "manual",
-    title: "Replace own-API fetch with the typed nifra client",
-    steps: [
-      "Call `nifra_routes` or read `nifra://routes` for the exact typed-client call form.",
-      "Create `const api = client<typeof app>(baseUrl)` from `@nifrajs/client`.",
-      "Replace the relative `fetch()` call with the generated `api...get/post/...` call and branch on `{ ok, data, error }`.",
-    ],
-  }
-}
-
-function serverImportSuggestion(
-  specifier: string,
-  chain: readonly string[],
-  fallback: boolean,
-): CheckSuggestion {
-  const sink = chain[chain.length - 1] ?? specifier
-  // Surface the resolved chain in the fix steps so the agent sees the full path (`route → ../data →
-  // ../db → node:crypto`) and which module to cut - not just the route's own top-level import.
-  const chainStep =
-    chain.length > 2
-      ? fallback
-        ? `Server-only code reaches this route through \`${chain.join(" → ")}\` (the deeper chain couldn't be resolved precisely - trace it from \`${specifier}\`).`
-        : `Server-only code reaches this route transitively: \`${chain.join(" → ")}\`. The sink is \`${sink}\`; break the chain at the first hop (\`${specifier}\`) or move the sink behind the server boundary.`
-      : undefined
-  return {
-    kind: "manual",
-    title: "Move server-only code behind the route server boundary",
-    steps: [
-      ...(chainStep !== undefined ? [chainStep] : []),
-      `Remove the top-level \`import … from "${specifier}"\` from this route module (it's bundled for the browser).`,
-      "Access backend/data work through the route `loader`/`action` context (`api`, `env`, or project server context).",
-      `If a direct module import is unavoidable, lazy-load it (\`await import("${specifier}")\`) inside the server-only loader/action path.`,
-    ],
-  }
-}
-
-function responseRouteSuggestion(): CheckSuggestion {
-  return {
-    kind: "manual",
-    title: "Preserve typed-client response inference",
-    steps: [
-      "Prefer returning a plain object from JSON routes; nifra serializes it for you.",
-      "For a stream, use a typed SSE route - `app.sse(...)` (or `sse(c, run)` from `@nifrajs/core/server`) - which keeps typed events instead of collapsing the client to `data: never`.",
-      "If this route must return a raw Response (redirect, file), declare an explicit response schema, or add a `// nifra-expect raw-response` comment above the return to mark it intentional and silence this advisory.",
-    ],
-  }
-}
-
 export async function collectCheckDiagnostics(
   cwd: string,
   scan: CheckAnalysisInput,
   opts: CheckDiagnosticsOptions = {},
 ): Promise<CheckResult> {
-  const factsSeed = scan.facts
-  const { fetches, untypedClients, removedImports, responseRoutes, interpolatedSql } =
-    factsSeed.sourceFindings
-  const staticRoutes = factsSeed.routes
-  const serverImports = factsSeed.importGraph
-  const { doctor: dr, manifestDrift } = factsSeed.packages
-  const { checkConfig } = factsSeed.policies
-  const tc = scan.typecheck
-  const sqlCompiler = scan.sqlCompiler
-  const checkConfigError = scan.checkConfigError
-  const checkConfigWarnings = scan.checkConfigWarnings
-  const diagnostics: CheckDiagnostic[] = []
-  const structuredExtras: Diagnostic[] = []
-  if (checkConfigError !== undefined) {
-    diagnostics.push({
-      rule: "check-config",
-      severity: "warning",
-      file: "nifra.check.json",
-      message: `nifra.check.json could not be parsed (${checkConfigError}) - its external-mount allowlist was ignored`,
-      fix: "Fix the JSON syntax in nifra.check.json",
-    })
-  }
-  for (const warning of checkConfigWarnings) {
-    diagnostics.push({
-      rule: "check-config",
-      severity: "warning",
-      file: "nifra.check.json",
-      message: `nifra.check.json: ${warning}`,
-      fix: "Fix the entry in nifra.check.json",
-    })
-  }
-  if (tc.missingTypeScript === true) {
-    // A tsconfig with no reachable `typescript` install is a broken gate, not a benign skip: the
-    // contract check the project asked for (by having a tsconfig) silently didn't run. Fail closed.
-    diagnostics.push({
-      rule: "typecheck",
-      severity: "error",
-      file: "tsconfig.json",
-      message:
-        "tsconfig.json is present but no `typescript` install was found from this directory upward - the typecheck gate did NOT run",
-      fix: "bun add -d typescript",
-      suggestion: {
-        kind: "command",
-        title: "Install TypeScript so the contract gate can run",
-        command: ["bun", "add", "-d", "typescript"],
-      },
-    })
-  }
-  if (tc.ran && !tc.ok) {
-    const lines = (tc.output ?? "").split("\n")
-    let matched = false
-    for (const l of lines) {
-      const m = TSC_LINE.exec(l.trim())
-      if (m) {
-        matched = true
-        diagnostics.push({
-          rule: "typecheck",
-          severity: "error",
-          file: m[1] as string,
-          line: Number(m[2]),
-          message: m[3] as string,
-          suggestion: {
-            kind: "manual",
-            title: "Fix the TypeScript contract error",
-            steps: [
-              "Open the reported file and line.",
-              "Align the handler, route schema, or typed-client call with the compiler error.",
-              "Run `nifra_check` again after the edit.",
-            ],
-          },
-        })
-      }
-    }
-    if (!matched)
-      diagnostics.push({
-        rule: "typecheck",
-        severity: "error",
-        message: tc.output || "typecheck failed",
-        suggestion: {
-          kind: "manual",
-          title: "Fix the TypeScript contract error",
-          steps: ["Run `tsc --noEmit` locally for the full compiler output."],
-        },
-      })
-  }
-  const routes = staticRouteMap(staticRoutes)
-  for (const f of [...fetches].sort(bySite)) {
-    diagnostics.push({
-      rule: "typed-client",
-      severity: "error",
-      file: f.file,
-      line: f.line,
-      message: `${f.snippet} - ${FETCH_HINT}`,
-      fix: FETCH_HINT,
-      suggestion: ownFetchSuggestion(f, routes),
-    })
-  }
-  for (const f of [...removedImports].sort(bySite)) {
-    const entry = REMOVED_IMPORTS.find(
-      (candidate) =>
-        f.snippet.includes(`"${candidate.specifier}`) ||
-        f.snippet.includes(`'${candidate.specifier}`),
-    )
-    diagnostics.push({
-      rule: "removed-import",
-      severity: "error",
-      file: f.file,
-      line: f.line,
-      message: `${f.snippet} - removed in nifra ${entry?.since ?? "2.0"}: ${entry?.replacement ?? "see the changelog"}`,
-      fix: entry?.replacement ?? "see the changelog",
-    })
-  }
-  for (const f of [...untypedClients].sort(bySite)) {
-    diagnostics.push({
-      rule: "untyped-client",
-      severity: "error",
-      file: f.file,
-      line: f.line,
-      message: `${f.snippet} - ${UNTYPED_CLIENT_HINT}`,
-      fix: UNTYPED_CLIENT_HINT,
-      suggestion: untypedClientSuggestion(f),
-    })
-  }
-  for (const f of [...serverImports].sort(bySite)) {
-    // #4.4: the FULL transitive chain the import-resolution walk found - `route → ../data → ../db →
-    // node:crypto`, matching the build leak-guard's depth - instead of just the direct edge. The chain's
-    // tail is the actual server-only sink; the head is the route. When a precise resolve wasn't possible
-    // (a bare pkg / path alias), `fallback` is set and the chain degrades to the honest direct edge.
-    const chain = f.chain
-    const sink = chain[chain.length - 1] ?? f.specifier
-    diagnostics.push({
-      rule: "server-only-import",
-      severity: "error",
-      file: f.file,
-      line: f.line,
-      message: `${f.snippet} - server-only "${sink}" reaches the browser bundle via ${chain.join(" → ")}${f.fallback ? " (direct edge - couldn't resolve the transitive chain precisely)" : ""}; ${SERVER_IMPORT_HINT}`,
-      fix: SERVER_IMPORT_HINT,
-      chain,
-      suggestion: serverImportSuggestion(f.specifier, chain, f.fallback),
-    })
-  }
-  if (sqlCompiler === undefined) {
-    // A security rule that could not run must say so. Silence here is indistinguishable from a clean
-    // result, and this is the one rule whose clean result means "no SQL injection was found".
-    diagnostics.push({
-      rule: "interpolated-sql",
-      severity: "warning",
-      message: SQL_COMPILER_MISSING_HINT,
-      fix: SQL_COMPILER_MISSING_HINT,
-      suggestion: {
-        kind: "command",
-        title: "Install TypeScript so the SQL rule can run",
-        command: ["bun add -d typescript"],
-      },
-    })
-  }
-  for (const f of [...interpolatedSql].sort(bySite)) {
-    diagnostics.push({
-      rule: "interpolated-sql",
-      severity: "error",
-      file: f.file,
-      line: f.line,
-      message: `${f.snippet} - ${INTERPOLATED_SQL_HINT}`,
-      fix: "bind the value as a parameter instead of interpolating it into the statement",
-      suggestion: {
-        kind: "manual",
-        title: "Bind the value instead of interpolating it",
-        steps: [
-          "Replace the interpolation with a placeholder your driver understands (`?` for SQLite/MySQL, `$1` for Postgres).",
-          "Pass the value as an argument alongside the statement, so the driver binds it.",
-          `Or switch to the driver's tagged template (sql\`… ${SQL_INTERPOLATION_EXAMPLE} …\`): the tag receives substitutions separately and binds them.`,
-          "An identifier that genuinely cannot be bound (a table or column name) must be checked against an allowlist you control, never taken from the request.",
-          "If the statement is dynamic but every value is already bound (generating `($1),($2),…` for a batch insert), mark it with a `// nifra-expect sql-dynamic: <reason>` comment on the line above - the reason is required.",
-        ],
-      },
-    })
-  }
-  // Advisory - surfaced but NOT folded into `ok`, so it never fails the gate (a raw Response is valid).
-  for (const f of [...responseRoutes].sort(bySite)) {
-    diagnostics.push({
-      rule: "response-route",
-      severity: "warning",
-      file: f.file,
-      line: f.line,
-      message: `${f.snippet} - ${RESPONSE_ROUTE_HINT}`,
-      fix: RESPONSE_ROUTE_HINT,
-      suggestion: responseRouteSuggestion(),
-    })
-  }
-  if (dr.ran) {
-    for (const f of dr.findings) {
-      diagnostics.push({
-        rule: "undeclared-dependency",
-        severity: "error",
-        file: f.file,
-        line: f.line,
-        message: `imports ${f.package} which is not declared in package.json - ${UNDECLARED_DEP_HINT}`,
-        fix: `add ${f.package} to package.json dependencies`,
-        suggestion: {
-          kind: "command",
-          title: `Declare ${f.package} in package.json`,
-          command: ["bun", "add", f.package],
-        },
-      })
-    }
-    for (const finding of dr.duplicateInstalls) {
-      // One line per physical copy: version, resolved absolute path, and who pulled it in. The
-      // absolute path is what a reader pastes into an editor or `rm -rf`; the importer list is what
-      // tells them WHICH package.json to fix - a relative path alone answers neither.
-      const copyLines = finding.copies.map(
-        (copy) =>
-          `${finding.package}@${copy.version} at ${copy.absolutePath ?? copy.path} - pulled in by ${copy.importers.join(", ")}`,
-      )
-      diagnostics.push({
-        rule: "duplicate-install",
-        severity: "error",
-        message: `${finding.package} identity preflight found ${finding.cause} - ${finding.explanation}${finding.topology === undefined ? "" : `. Topology: ${finding.topology}`}${finding.scope === undefined ? "" : `. Scope: ${finding.scope}`}`,
-        fix: finding.remediation,
-        evidence: copyLines,
-        suggestion: {
-          kind: "manual",
-          title: `Resolve ${finding.package} to one loaded copy`,
-          // The renderer prints this block verbatim before the steps: the exact config for fix 2, so
-          // the reader pastes instead of transcribing prose into JSON and TOML.
-          diff: [
-            "package.json:",
-            `  "nifra": { "singleCopy": ["${finding.package}"] }`,
-            "bunfig.toml:",
-            `  preload = ["${SINGLE_COPY_REGISTER_SPECIFIER}"]`,
-            "  [test]",
-            `  preload = ["${SINGLE_COPY_REGISTER_SPECIFIER}"]`,
-          ].join("\n"),
-          steps: [
-            ...copyLines.map((line) => `Copy: ${line}`),
-            "Fix 1 - deduplicate: align workspace dependency and peer ranges on one compatible version, remove stale nested installs, and reinstall from the workspace root so every importer resolves one physical copy.",
-            `Fix 2 - declare single-copy: apply the package.json and bunfig.toml config printed above; nifra then rewrites every duplicate to this app's copy.${finding.cause === "version-skew" ? " A declaration only covers same-version duplicates, so fix 1's range alignment must land first." : ""}`,
-            "Re-run `nifra check`; the gate stays failing until one fix lands.",
-          ],
-        },
-      })
-    }
-    // Declared single-copy: the resolver collapses these before anything loads, so the build is sound
-    // and the gate stays green. It is still worth a line - the guarantee lives in a declaration now,
-    // and a reader who deletes it gets a null hook dispatcher with no obvious cause.
-    for (const finding of dr.deduplicatedInstalls ?? []) {
-      const copies = finding.copies.map((copy) => copy.path).join("; ")
-      diagnostics.push({
-        rule: "duplicate-install",
-        severity: "warning",
-        message: `${finding.package} is installed at ${finding.copies.length} paths (${copies}) and is declared single-copy - nifra resolves every duplicate to this app's copy`,
-        fix: finding.remediation,
-      })
-    }
-    // Advisory (never fails the gate): while actively editing a linked package its dist is always
-    // momentarily behind. The finding earns its keep when a dev server is about to start against it -
-    // Bun reads live `src` while Vite's SSR runner reads the artifact, so a stale one 500s inside
-    // framework/shared-package code and reads exactly like an upstream regression.
-    for (const f of dr.staleDists) {
-      // The rebuild is only actionable with the LOCATION: a workspace link routinely points into a
-      // sibling repo, so "rebuild @nifrajs/core" left the developer to go find the checkout and guess
-      // the script. Name the directory and the package's own script, or say plainly that it declares
-      // none - never suggest a command that would fail.
-      const rebuild =
-        f.buildScript === undefined
-          ? `${f.packageDir} declares no build script - build it the way that package expects`
-          : `cd ${f.packageDir} && bun run ${f.buildScript}   (or \`nifra fix --code NF-C010\`)`
-      diagnostics.push({
-        rule: "stale-workspace-dist",
-        severity: "warning",
-        message: f.missing
-          ? `${f.package} was never built - ${f.distFile} is missing, but its export map serves it to Vite SSR/node consumers while Bun reads src - ${rebuild}`
-          : `${f.package} has a stale build artifact - ${f.distFile} is ${f.behindSeconds}s older than ${f.sourceFile}, and Vite SSR/node consumers read the artifact while Bun reads src - ${rebuild}`,
-        fix: rebuild,
-        evidence: [f.package, f.distFile, f.sourceFile, f.packageDir],
-        suggestion: {
-          kind: "manual",
-          title: `Rebuild ${f.package}`,
-          steps: [
-            rebuild,
-            "Only workspace-linked installs drift; npm tarballs are immutable and never flagged.",
-          ],
-        },
-      })
-    }
-  }
-  // The two-pipeline rule, read from the config as TEXT (doctor collects it - see ./pipeline-report.ts).
-  // `loadApp` already refuses a misplaced plugin, but only when something loads the app; a check that
-  // never executes project code, and CI that never starts a dev server, would otherwise meet these for
-  // the first time as a production server that built cleanly and died at startup.
-  for (const f of dr.pipeline?.findings ?? []) {
-    diagnostics.push({
-      rule: "pipeline",
-      severity: f.severity,
-      file: f.file,
-      ...(f.line !== undefined ? { line: f.line } : {}),
-      message: f.message,
-      fix: f.fix,
-      suggestion: { kind: "manual", title: f.fix, steps: [PIPELINE_DOC_HINT] },
-    })
-  }
-  // #7: a committed server-manifest.ts that drifted from routes/ - name the exact missing/extra routes.
-  for (const f of manifestDrift) {
-    const parts: string[] = []
-    if (f.missing.length > 0) parts.push(`missing from manifest: ${f.missing.join(", ")}`)
-    if (f.extra.length > 0) parts.push(`stale in manifest: ${f.extra.join(", ")}`)
-    diagnostics.push({
-      rule: "server-manifest-drift",
-      severity: "error",
-      file: f.file,
-      message: `${f.file} drifted from routes/ (${parts.join("; ")}) - ${MANIFEST_DRIFT_HINT}`,
-      fix: MANIFEST_DRIFT_HINT,
-      evidence: [...f.missing, ...f.extra],
-      suggestion: {
-        kind: "manual",
-        title: "Regenerate the committed server manifest",
-        steps: [
-          "Re-run your build (`nifra build --target <t>` or your build script) - it regenerates server-manifest.ts from the current routes/.",
-          "Commit the updated server-manifest.ts.",
-        ],
-      },
-    })
-  }
-
-  // G+B+D+F: when the project opts into capability assurance, `nifra check` becomes the static
-  // provenance firewall as well as the typed-contract gate. Loading is explicit/config-owned; projects
-  // without nifra.assurance.ts retain the historical scan and hot path unchanged.
-  const provided = opts.assurance
-  let applicationRulePacks: readonly import("./rules/index.ts").RulePack[] = []
-  let loadedPolicy = provided
-  let loadedCapability: CapabilityProjectReport | undefined = provided?.capability
+  // The rule registry is the only diagnostic producer. This preparation phase may load executable
+  // assurance configuration because rules need its reflected facts, but it never formats findings.
+  let factsSeed = scan.facts
+  let loadedPolicy = opts.assurance ?? factsSeed.policies.assurance
+  let loadedCapability = loadedPolicy?.capability ?? factsSeed.policies.capability
+  let applicationRulePacks = factsSeed.policies.rulePacks
   const assuranceConfigPath = join(cwd, "nifra.assurance.ts")
-  if (provided !== undefined ? provided.present : existsSync(assuranceConfigPath)) {
-    try {
-      // Either the shared reflection from `collectProjectVerification` (no second pass) or, on the
-      // standalone path, loaded + reflected here. Both branches yield the same config + evidence.
-      let config: 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.
-        if (provided.error !== undefined) throw provided.error
-        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)
-        if (config.capabilities !== undefined) {
-          const { collectCapabilityProjectReport } = await import("./capabilities-tool.ts")
-          project = await collectCapabilityProjectReport(cwd, config.source, config.capabilities)
-        }
-        loadedPolicy = {
-          present: true,
-          config,
-          ...(routeAssurance === undefined ? {} : { routeAssurance }),
-          ...(project === undefined ? {} : { capability: project }),
-          ...(evidence === undefined ? {} : { evidence }),
-        }
-        loadedCapability = project
-      }
-      applicationRulePacks = parseRulePacks(config.rulePacks)
-      const capabilityReport = project?.report
-      if (config.capabilities !== undefined && project !== undefined) {
-        for (const finding of project.report.findings) {
-          const violation =
-            finding.code === "forbidden-effect-import"
-              ? project.violations.find(
-                  (candidate) =>
-                    candidate.method === finding.method && candidate.path === finding.path,
-                )
-              : undefined
-          const truncation =
-            finding.code === "provenance-truncated"
-              ? project.truncations.find(
-                  (candidate) =>
-                    candidate.method === finding.method && candidate.path === finding.path,
-                )
-              : undefined
-          // An unmatched seam is a policy defect, not a route defect: the fix is in the policy file,
-          // so it gets its own steps instead of the route-side provenance guidance.
-          const seamFix =
-            finding.code === "unmatched-provenance-seam"
-              ? "Write the seam exactly as the code imports it, or delete the rule."
-              : undefined
-          diagnostics.push({
-            rule: "capability-assurance",
-            severity: "error",
-            ...(violation !== undefined
-              ? { file: violation.module, chain: violation.chain }
-              : truncation !== undefined
-                ? { chain: truncation.chain }
-                : {}),
-            message: `${finding.message}${seamFix === undefined ? ` - ${CAPABILITY_HINT}` : ""}`,
-            fix: seamFix ?? CAPABILITY_HINT,
-            suggestion:
-              seamFix === undefined
-                ? {
-                    kind: "manual",
-                    title: "Restore declared effect provenance",
-                    steps: [
-                      "Route effectful work through an import listed in capabilities.provenance.imports.",
-                      "Declare the exact capability token on the route; do not widen unrelated routes in the same file.",
-                      "For domain writes, add the adapter the capability definition requires: `schema.idempotency` for the `request` tier, `.use(durableCommand({ journal }))` from @nifrajs/middleware for the `durable` tier.",
-                      "Run `nifra capabilities snapshot` only after assurance passes, then review the lockfile diff.",
-                    ],
-                  }
-                : {
-                    kind: "manual",
-                    title: "Point the provenance rule at a module that exists",
-                    steps: [
-                      "Copy the specifier from the import statement itself - it is matched as written, with no extension or index resolution.",
-                      "Use a trailing `/*` when the seam is a directory of modules (`@myorg/db/*`).",
-                      "For a routeModules entry, give the project-relative path of the file that implements the route.",
-                      "Delete the rule if the seam it governed is gone; leaving it in place proves nothing.",
-                    ],
-                  },
-          })
-        }
-      }
-      if (config.manifest !== undefined) {
-        const { buildNifraManifest, parseNifraManifest, serializeNifraManifest } = await import(
-          "@nifrajs/core/manifest"
-        )
-        const assurance =
-          routeAssurance ??
-          (await import("@nifrajs/core/assurance")).evaluateRouteAssurance(
-            config.source,
-            config.policy,
-            {
-              ...(config.capabilities !== undefined
-                ? { definitions: config.capabilities.definitions }
-                : {}),
-            },
-          )
-        evidence ??= snapshotProjectEvidence(config.source, {
-          assurance,
-          ...(capabilityReport !== undefined ? { capabilities: capabilityReport } : {}),
-        })
-        const path = resolve(cwd, config.manifest.path ?? "nifra.manifest.json")
-        let message: string | undefined
-        if (!assurance.ok || (capabilityReport !== undefined && !capabilityReport.ok)) {
-          message =
-            "the configured assurance policy is failing, so a trusted manifest cannot be built"
-        } else if (!existsSync(path)) {
-          message = "the configured trust manifest is missing"
-        } else {
-          try {
-            const current = await buildNifraManifest({
-              evidence,
-              assurance,
-              ...(capabilityReport !== undefined ? { capabilities: capabilityReport } : {}),
-            })
-            const storedText = await Bun.file(path).text()
-            const stored = await parseNifraManifest(storedText, path)
-            const expectedText = `${serializeNifraManifest(current)}\n`
-            if (storedText !== expectedText || stored.contentHash !== current.contentHash) {
-              message = "the configured trust manifest does not match live route reflection"
-            }
-          } catch (error) {
-            message = `the configured trust manifest is invalid: ${error instanceof Error ? error.message : String(error)}`
-          }
-        }
-        if (message !== undefined) {
-          diagnostics.push({
-            rule: "manifest-drift",
-            severity: "error",
-            file: path,
-            message: `${message} - ${TRUST_MANIFEST_DRIFT_HINT}`,
-            fix: TRUST_MANIFEST_DRIFT_HINT,
-            suggestion: {
-              kind: "command",
-              title: "Regenerate the signed-manifest input artifact",
-              command: ["nifra", "manifest", "emit"],
-              steps: [
-                "Review the route, assurance, capability, and classification delta before committing it.",
-              ],
-            },
-          })
-        }
-      }
-    } catch (err) {
-      loadedPolicy = { present: true, error: err }
-      diagnostics.push({
-        rule: "capability-config",
-        severity: "error",
-        file: "nifra.assurance.ts",
-        message: `capability assurance config could not be evaluated: ${err instanceof Error ? err.message : String(err)}`,
-        suggestion: {
-          kind: "manual",
-          title: "Repair the assurance config",
-          steps: [
-            "Ensure nifra.assurance.ts default-exports defineAssuranceConfig({ source, policy, capabilities }).",
-            "Fix configuration/import errors; the provenance firewall fails closed when its policy cannot load.",
-          ],
-        },
-      })
-    }
-  }
 
-  try {
-    const { checkContractsLock } = await import("./contracts.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 {
-      if (contract.vacuous) {
-        // Every route hashes to the empty-schema digest, so the lock exists but the drift rule guards
-        // nothing: it can only ever compare "no schema" to "no schema". Say so, or a green contract check
-        // reads as proof of a stable contract when there is no contract to be stable.
-        structuredExtras.push(
-          diagnostic({
-            code: "NF-K001",
-            severity: "info",
-            message:
-              "no route schemas declared - the trust manifest is vacuous: every contract hash is the empty-schema digest, so drift detection guards nothing. Declare route schemas (body/query/params/response) so the lock has a contract to protect.",
-            verify: "nifra check --lints-only",
-          }),
-        )
+  if (loadedPolicy === undefined && existsSync(assuranceConfigPath)) {
+    try {
+      const { loadAssuranceConfig } = await import("./assure.ts")
+      const config = await loadAssuranceConfig(cwd)
+      let capability: import("./capabilities-tool.ts").CapabilityProjectReport | undefined
+      if (config.capabilities !== undefined) {
+        const { collectCapabilityProjectReport } = await import("./capabilities-tool.ts")
+        capability = await collectCapabilityProjectReport(cwd, config.source, config.capabilities)
       }
-      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",
-        })
+      loadedPolicy = {
+        present: true,
+        config,
+        ...(capability === undefined ? {} : { capability }),
       }
+      loadedCapability = capability
+      applicationRulePacks = parseRulePacks(config.rulePacks)
+    } catch (error) {
+      loadedPolicy = { present: true, error }
+      loadedCapability = undefined
+      applicationRulePacks = []
     }
-  } 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",
-      })
+  } else if (loadedPolicy?.present === true && loadedPolicy.error === undefined) {
+    try {
+      if (loadedPolicy.config === undefined) throw new Error("assurance configuration unavailable")
+      applicationRulePacks = parseRulePacks(loadedPolicy.config.rulePacks)
+      loadedCapability = loadedPolicy.capability ?? loadedCapability
+    } catch (error) {
+      loadedPolicy = { present: true, error }
+      loadedCapability = undefined
+      applicationRulePacks = []
     }
   }
 
-  const projectFacts = freezeProjectFacts(
-    {
-      ...factsSeed,
-      policies: {
-        ...factsSeed.policies,
-        ...(loadedPolicy === undefined ? {} : { assurance: loadedPolicy }),
-        ...(loadedCapability === undefined ? {} : { capability: loadedCapability }),
-        rulePacks: applicationRulePacks,
-      },
+  factsSeed = {
+    ...factsSeed,
+    policies: {
+      ...factsSeed.policies,
+      ...(loadedPolicy === undefined ? {} : { assurance: loadedPolicy }),
+      ...(loadedCapability === undefined ? {} : { capability: loadedCapability }),
+      rulePacks: applicationRulePacks,
     },
-    diagnostics,
-  )
-  const ruleContext: RuleContext = {
+  }
+  const projectFacts = freezeProjectFacts(factsSeed)
+  const ruleContext = {
     root: cwd,
     sources: projectFacts.source,
     project: projectFacts,
-  }
-  const structuredDiagnostics = [...structuredExtras]
+    ...(projectFacts.check.typescriptSession === undefined
+      ? {}
+      : { typescriptSession: projectFacts.check.typescriptSession }),
+  }
+
+  const builtInRules = [
+    ...legacyRules,
+    ...securityRules,
+    ...routeRules,
+    ...pageRules,
+    ...zoneRules,
+    ...dataGuardRules,
+    ...secretRules,
+    ...islandRules,
+    ...nanoRules,
+  ]
   let registryDiagnostics: Diagnostic[] = []
+  let builtInsSucceeded = false
   try {
-    registryDiagnostics = await runRuleRegistry(
-      ruleContext,
-      [...legacyRules, ...securityRules, ...routeRules, ...islandRules, ...nanoRules],
-      projectFacts.policies.rulePacks,
-    )
-    structuredDiagnostics.push(...registryDiagnostics)
+    registryDiagnostics = await runRuleRegistry(ruleContext, builtInRules)
+    builtInsSucceeded = true
   } catch (error) {
     registryDiagnostics = [
       diagnostic({
         code: "NF-C017",
         severity: "error",
-        message: `rule registry failed closed: ${error instanceof Error ? error.message : String(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)
   }
+  if (builtInsSucceeded && projectFacts.policies.rulePacks.length > 0) {
+    try {
+      registryDiagnostics.push(
+        ...(await runRuleRegistry(ruleContext, [], projectFacts.policies.rulePacks)),
+      )
+    } catch (error) {
+      // Keep all built-in findings when an application rule fails. The old compatibility path had
+      // already materialized those findings before packs ran; preserving that property matters when
+      // a broken pack must not hide a more actionable built-in failure.
+      registryDiagnostics.push(
+        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",
+        }),
+      )
+    }
+  }
+
+  const knownLegacyCodes = new Set(Object.values(LEGACY_RULE_CODES))
+  const compatibilityRows: CheckDiagnostic[] = []
   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({
+    const compatibility = diagnosticCompatibilityOf(item)
+    if (compatibility !== undefined) {
+      compatibilityRows.push({
+        rule: compatibility.rule,
+        severity: item.severity === "warn" ? "warning" : item.severity,
+        ...(compatibility.includeCode === true ? { code: item.code } : {}),
+        ...(item.file === undefined ? {} : { file: item.file }),
+        ...(item.line === undefined ? {} : { line: item.line }),
+        message: item.message,
+        ...(compatibility.fix === undefined ? {} : { fix: compatibility.fix }),
+        // A legacy chain was a separate field; canonical diagnostics expose the same values as
+        // evidence for structured consumers, so do not leak that projection back into the old view.
+        ...(item.evidence === undefined || compatibility.chain !== undefined
+          ? {}
+          : { evidence: item.evidence }),
+        ...(compatibility.chain === undefined ? {} : { chain: compatibility.chain }),
+        ...(compatibility.suggestion === undefined ? {} : { suggestion: compatibility.suggestion }),
+        ...(item.verify === undefined ? {} : { verify: item.verify }),
+      })
+      continue
+    }
+    // A structured informational contract note intentionally has no old human/legacy row. Every
+    // other non-legacy rule (security, route, island, nano, or an application pack) retains the
+    // existing fallback row keyed by its stable code.
+    if (knownLegacyCodes.has(item.code)) continue
+    compatibilityRows.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 } : {}),
+      ...(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 } : {}),
+      ...(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.
+  // Keep the old compatibility order stable even though the canonical registry order is explicit.
+  const order = new Map(LEGACY_RULE_ORDER.map((rule, index) => [rule, index]))
+  const orderedLegacy = compatibilityRows
+    .map((value, index) => ({ value, index }))
+    .sort(
+      (a, b) =>
+        (order.get(a.value.rule) ?? LEGACY_RULE_ORDER.length) -
+          (order.get(b.value.rule) ?? LEGACY_RULE_ORDER.length) || a.index - b.index,
+    )
+    .map((entry) => entry.value)
+
+  const checkConfig = projectFacts.policies.checkConfig
   const overrideFor = (...keys: (string | undefined)[]): RuleOverride | undefined => {
     for (const key of keys) {
       if (key !== undefined && checkConfig.rules[key] !== undefined) return checkConfig.rules[key]
@@ -1168,51 +550,71 @@ export async function collectCheckDiagnostics(
   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 finalDiagnostics = orderedLegacy.flatMap<CheckDiagnostic>((value) => {
+    const override = overrideFor(value.rule, value.code, LEGACY_RULE_CODES[value.rule])
+    if (override === undefined) return [value]
+    if (dropped(override, value.file)) return []
+    if (override.severity === undefined || override.severity === "off") return [value]
+    return [{ ...value, 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 })]
+
+  const structuredExtras = registryDiagnostics.filter(
+    (value) => diagnosticCompatibilityOf(value) === undefined && knownLegacyCodes.has(value.code),
+  )
+  const structuredDiagnostics = [
+    ...structuredExtras,
+    ...registryDiagnostics.filter((value) => !structuredExtras.includes(value)),
+  ]
+  const finalStructured = structuredDiagnostics.flatMap<Diagnostic>((value) => {
+    const override = overrideFor(value.code, codeToLegacy.get(value.code))
+    if (override === undefined) return [value]
+    if (dropped(override, value.file)) return []
+    if (override.severity === undefined || override.severity === "off") return [value]
+    return [Object.freeze({ ...value, severity: override.severity })]
   })
 
-  // Cap the diagnostics when asked (the MCP path), so a project with thousands of findings can't return a
-  // message that breaks the stdio transport. `ok` reflects the FULL set - truncation never flips it.
   const total = finalDiagnostics.length
   const max = opts.maxDiagnostics
   const shown = max !== undefined && total > max ? finalDiagnostics.slice(0, max) : finalDiagnostics
+  const nonLegacyStructuredCount = finalStructured.filter(
+    (value) => knownLegacyCodes.has(value.code) && diagnosticCompatibilityOf(value) === undefined,
+  ).length
+  const structuredLimit =
+    shown.length < total ? shown.length + nonLegacyStructuredCount : finalStructured.length
+
+  const doctor = projectFacts.packages.doctor
+  const knownGaps = projectFacts.policies.capability?.report.gaps ?? []
   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 } : {}),
+    ok: !finalDiagnostics.some((value) => value.severity === "error"),
+    typecheck: projectFacts.check.typecheck.ran
+      ? projectFacts.check.typecheck.ok
+        ? "pass"
+        : "fail"
+      : "skipped",
+    ...(!projectFacts.check.typecheck.ran && projectFacts.check.typecheck.note !== undefined
+      ? { typecheckNote: projectFacts.check.typecheck.note }
+      : {}),
     diagnostics: shown,
-    ...(dr.pipeline !== undefined ? { pipeline: dr.pipeline } : {}),
-    ...(dr.ran
+    ...(projectFacts.pipeline !== undefined ? { pipeline: projectFacts.pipeline } : {}),
+    ...(doctor.ran
       ? {
           identityPreflight: {
-            ...(dr.identityBasis !== undefined ? { basis: dr.identityBasis } : {}),
-            ...(dr.identityScanTruncated === true ? { truncated: true } : {}),
-            duplicates: dr.duplicateInstalls,
-            deduplicated: dr.deduplicatedInstalls ?? [],
+            ...(doctor.identityBasis === undefined ? {} : { basis: doctor.identityBasis }),
+            ...(doctor.identityScanTruncated === true ? { truncated: true } : {}),
+            duplicates: doctor.duplicateInstalls,
+            deduplicated: doctor.deduplicatedInstalls ?? [],
           },
         }
       : {}),
-    ...(checkConfig.externalMounts.length > 0
-      ? { externalMounts: checkConfig.externalMounts }
-      : {}),
-    ...(Object.keys(checkConfig.rules).length > 0 ? { ruleOverrides: checkConfig.rules } : {}),
+    ...(checkConfig.externalMounts.length === 0
+      ? {}
+      : { externalMounts: checkConfig.externalMounts }),
+    ...(knownGaps.length === 0 ? {} : { knownGaps }),
+    ...(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),
+    value: finalStructured.slice(0, structuredLimit),
     enumerable: false,
   })
   return result