@nifrajs/web 2.14.1 → 3.1.0

package/src/internal/parity.ts

@@ -9,7 +9,15 @@
 import { existsSync, readdirSync, readFileSync, realpathSync } from "node:fs"
 import { lstat, realpath, stat } from "node:fs/promises"
 import { dirname, join, relative, resolve, sep } from "node:path"
+import {
+  matchesSingleCopyDeclaration,
+  readSingleCopyDeclaration,
+  readSingleCopyRegistration,
+  SINGLE_COPY_REGISTER_SPECIFIER,
+  type SingleCopyRegistration,
+} from "@nifrajs/core/single-copy"
 import { discoverRoutes } from "../fs.ts"
+import { isIdentitySensitivePackage } from "./identity-policy.ts"
 
 const DEPENDENCY_FIELDS = [
   "dependencies",
@@ -17,15 +25,6 @@ const DEPENDENCY_FIELDS = [
   "peerDependencies",
   "optionalDependencies",
 ] as const
-const IDENTITY_SENSITIVE_PACKAGES = new Set([
-  "@nifrajs/core",
-  "react",
-  "react-dom",
-  "preact",
-  "svelte",
-  "solid-js",
-  "vue",
-])
 const MAX_WORKSPACE_IMPORTERS = 2_048
 const MAX_LINKED_PACKAGES = 64
 const MAX_LINK_PROBES = 4_096
@@ -47,16 +46,86 @@ export interface IdentityParityFinding {
   readonly cause: IdentityParityCause
   readonly explanation: string
   readonly remediation: string
+  /**
+   * Why the copies exist, in install-topology terms: how many physical paths sit under how many
+   * install roots, and whether any of those roots is outside the scanned project.
+   *
+   * A path list alone leaves the reader to reverse-engineer the shape. The two shapes need opposite
+   * fixes: a NESTED install under the scanned root shadows the hoisted copy and one reinstall
+   * collapses it, while a SIBLING install root (a linked checkout, a standalone app beside this one)
+   * owns its own `node_modules` and no reinstall here can touch it.
+   *
+   * Absent on a finding built by hand (a test fixture, an older cached result).
+   */
+  readonly topology?: string
+  /**
+   * Why a copy the invoked directory does not import is still fatal here.
+   *
+   * The gate is workspace-wide on purpose. Scoping it to the invoked app would be more precise and
+   * would also reintroduce the blindness this guard was built for: a copy that arrives through a
+   * workspace-linked dependency is not visible from the app directory, and that case shipped a
+   * broken dev server while the check reported "none". A workspace-wide answer over-reports in
+   * exchange for never under-reporting - and over-reporting is the failure a developer can see and
+   * act on, where under-reporting is the one nobody knows happened.
+   *
+   * Present only when the answer would otherwise look wrong: a subdirectory was scanned as its
+   * workspace, and at least one copy sits outside that subdirectory.
+   */
+  readonly scope?: string
+  /**
+   * The copies exist but the app declared this package single-copy, so the resolver collapses them
+   * before anything loads. Reported, never fatal - see `SingleCopyCoverage`.
+   */
+  readonly deduplicated: boolean
+}
+
+/**
+ * What the app declared about deduplication, and how much of it is actually armed.
+ *
+ * A duplicate physical path is only a defect if something still LOADS both copies. An app consuming a
+ * linked sibling repository cannot collapse the paths without giving up the property it chose `link:`
+ * for - each repository owning its own `node_modules` - so nifra lets it declare the packages instead
+ * (`"nifra": { "singleCopy": [...] }` in package.json) and verifies the declaration here rather than
+ * failing on the raw path count.
+ *
+ * Bundled phases need nothing further: `buildClient`/`buildServer`/dev inject the resolver themselves.
+ * Unbundled phases do, because Bun's runtime never offers a bare specifier to a resolver hook, so the
+ * plugin has to be preloaded to intercept the load. `registration` is that proof, read statically out
+ * of `bunfig.toml`.
+ */
+export interface SingleCopyCoverage {
+  /** Declared package names and patterns, exactly as written. Empty when nothing was declared. */
+  readonly declared: readonly string[]
+  readonly registration: SingleCopyRegistration
 }
 
 export interface IdentityParityResult {
+  /**
+   * The governing workspace root: where importer enumeration starts, and how far a copy lookup may
+   * walk up from an importer.
+   *
+   * EVERY caller resolves this the same way. The doctor and the build/dev preflight used to differ
+   * here - one anchored at the workspace, the other at the app directory - so the same project could
+   * be told it had duplicates by one command and a clean bill by the other. Two answers from one
+   * toolchain is worse than either answer, so the basis is now fixed and reported rather than chosen.
+   */
   readonly workspaceRoot: string
+  /** The directory the caller asked about. Differs from `workspaceRoot` when a package subdirectory
+   * is governed by a workspace above it; carried so a report can state the basis it scanned on. */
+  readonly requestedRoot: string
+  /**
+   * Enumeration stopped at `MAX_WORKSPACE_IMPORTERS`, so this scan is PARTIAL.
+   *
+   * An empty `findings` then means "nothing found in the part that was scanned", never "clean" - a
+   * caller that prints a clean bill on a truncated scan is the exact silence this flag exists to
+   * prevent.
+   */
+  readonly truncated: boolean
+  /** Findings that no declaration covers - the ones a build must refuse to start on. */
   readonly findings: readonly IdentityParityFinding[]
-}
-
-export interface IdentityParityOptions {
-  /** Scan the governing workspace when the caller is a package subdirectory. */
-  readonly useWorkspaceRoot?: boolean
+  /** Duplicates the declaration covers. Worth printing, never worth failing. */
+  readonly deduplicated: readonly IdentityParityFinding[]
+  readonly singleCopy: SingleCopyCoverage
 }
 
 export interface BuildManifestLike {
@@ -81,11 +150,20 @@ export interface DevelopmentParityInput {
   readonly routes: Readonly<Record<string, number>>
   readonly publicFiles: readonly string[]
   readonly css: readonly string[]
+  /** The scanned first-party source root, carried only so a css parity failure can name where the
+   * scanner looked. Optional: callers that hand-build an input for a unit test may omit it. */
+  readonly sourceRoot?: string
 }
 
 const SOURCE_EXTENSIONS = /\.(?:c|m)?(?:j|t)sx?$|\.(?:mdx|svelte|vue)$/
+/** A first-party reference to a stylesheet by an explicit path specifier. Covers static `import`,
+ * re-export `from`, dynamic `import(...)`, and `require(...)`. It stays deliberately *sound*: it only
+ * matches when a stylesheet specifier genuinely exists, never on an unreferenced `.css` file in the
+ * tree. With the css parity comparison now directional (a scanner miss passes, a false positive fails),
+ * a loose pattern would fail correct apps. Specifiers that cannot end in a stylesheet extension (a bare
+ * package `exports` subpath) stay unreachable without a resolver; those fall in the passing direction. */
 const CSS_IMPORT =
-  /(?:import\s+(?:[^"']+\s+from\s+)?|from\s+)["'][^"']+\.(?:css|scss|sass|less|styl)(?:\?[^"']*)?["']/i
+  /(?:import\s+(?:[^"']+\s+from\s+)?|from\s+|(?:import|require)\s*\(\s*)["'][^"']+\.(?:css|scss|sass|less|styl)(?:\?[^"']*)?["']/i
 /** A single-file-component `<style>` block (Svelte/Vue). The bundler extracts these into the app
  * stylesheet even though no `import "...css"` statement exists, so the dev contract must count them
  * or a scoped-style component would look style-free next to a production manifest that carries css. */
@@ -166,6 +244,16 @@ const workspaceContains = async (
   return false
 }
 
+/** The real path, or the input when it cannot be resolved. Roots are compared against each other and
+ * printed side by side, so they have to be normalized the same way (`/var` vs `/private/var`). */
+const realpathOrSelf = (path: string): string => {
+  try {
+    return realpathSync(path)
+  } catch {
+    return path
+  }
+}
+
 /** Resolve the workspace root once, even when the caller starts in a workspace package. */
 export async function resolveParityWorkspaceRoot(
   start: string,
@@ -184,17 +272,33 @@ export async function resolveParityWorkspaceRoot(
   }
 }
 
+/**
+ * Every workspace manifest that can install its own copy of a dependency.
+ *
+ * A pathological workspace must not make the scan unbounded, but it must not make it LIE either: the
+ * cap used to discard everything collected and return an empty list, which reads downstream as "no
+ * duplicates" - a clean bill from a scan that never ran. The bounded prefix is kept and `truncated`
+ * says the rest was not looked at.
+ */
 const workspaceImporters = async (
   root: string,
   rootPackage: Record<string, unknown>,
-): Promise<readonly { root: string; package: Record<string, unknown> }[]> => {
+): Promise<{
+  readonly importers: readonly { root: string; package: Record<string, unknown> }[]
+  readonly truncated: boolean
+}> => {
   const manifests = new Set<string>([join(root, "package.json")])
+  let truncated = false
   for (const pattern of workspacePatterns(rootPackage)) {
+    if (truncated) break
     const packagePattern = `${pattern.replace(/\/$/, "")}/package.json`
     for await (const match of new Bun.Glob(packagePattern).scan({ cwd: root, dot: false })) {
       if (match.split(/[\\/]/).includes("node_modules")) continue
+      if (manifests.size >= MAX_WORKSPACE_IMPORTERS) {
+        truncated = true
+        break
+      }
       manifests.add(join(root, match))
-      if (manifests.size > MAX_WORKSPACE_IMPORTERS) return []
     }
   }
   const importers: { root: string; package: Record<string, unknown> }[] = []
@@ -202,7 +306,7 @@ const workspaceImporters = async (
     const pkg = await readJson(manifest)
     if (pkg !== undefined) importers.push({ root: dirname(manifest), package: pkg })
   }
-  return importers
+  return { importers, truncated }
 }
 
 export const resolvedInstalledCopy = async (
@@ -231,7 +335,23 @@ export const resolvedInstalledCopy = async (
   }
 }
 
+/**
+ * How far above a linked package its dependencies may legitimately live.
+ *
+ * A linked SOURCE CHECKOUT (`link:../../nifra/packages/core`) really does resolve its imports from its
+ * own repo's `node_modules`, so the walk goes up to that repo's `.git` - a duplicate found there is one
+ * this project genuinely dual-loads.
+ *
+ * A path that lands INSIDE a `node_modules` directory is a package-manager store copy, not a checkout:
+ * a symlink into another project's store (bun's `.bun/<pkg>@<version>`, an `npm link` target, a shared
+ * global store) resolves there. Everything above such a copy belongs to whoever owns that store, and
+ * walking up would sweep an unrelated project's entire dependency tree into this project's duplicate
+ * report - permanent findings in a repo the developer is not even working in, that no change here can
+ * clear. Clamp to the copy itself: only its own nested `node_modules` counts, which is exactly the set
+ * of modules it can actually load.
+ */
 const linkedRepoBoundary = async (packageRoot: string): Promise<string> => {
+  if (packageRoot.split(sep).includes("node_modules")) return packageRoot
   let dir = packageRoot
   for (let depth = 0; depth < 8; depth++) {
     if (await pathExists(join(dir, ".git"))) return dir
@@ -246,7 +366,7 @@ const linkedPackageRoots = async (
   importerRoots: readonly string[],
   manifests: readonly Record<string, unknown>[],
   scanRoot: string,
-): Promise<readonly string[]> => {
+): Promise<{ readonly roots: readonly string[]; readonly truncated: boolean }> => {
   const realScanRoot = await realpath(scanRoot).catch(() => scanRoot)
   const found = new Map<string, true>()
   let probes = 0
@@ -254,7 +374,11 @@ const linkedPackageRoots = async (
     const pkg = manifests[index]
     if (pkg === undefined) continue
     for (const name of dependencyNames(pkg)) {
-      if (probes++ >= MAX_LINK_PROBES || found.size >= MAX_LINKED_PACKAGES) return [...found.keys()]
+      // Same rule as the importer cap: a bounded scan reports that it stopped. Returning the prefix
+      // silently would let a duplicate sitting past the cap read as a clean bill.
+      if (probes++ >= MAX_LINK_PROBES || found.size >= MAX_LINKED_PACKAGES) {
+        return { roots: [...found.keys()], truncated: true }
+      }
       const candidate = join(importerRoot, "node_modules", ...name.split("/"))
       const link = await lstat(candidate).catch(() => undefined)
       if (link === undefined || !link.isSymbolicLink()) continue
@@ -263,7 +387,7 @@ const linkedPackageRoots = async (
       found.set(resolved, true)
     }
   }
-  return [...found.keys()]
+  return { roots: [...found.keys()], truncated: false }
 }
 
 export const displayPath = (cwd: string, path: string): string => {
@@ -271,29 +395,131 @@ export const displayPath = (cwd: string, path: string): string => {
   return rel === "" ? "." : rel
 }
 
+/**
+ * The install root a copy belongs to: the directory ABOVE its last `node_modules` segment.
+ *
+ * That directory is what a package manager operates on, so it is the unit a fix is expressed in. A
+ * copy that sits in no `node_modules` at all is a source checkout, which is its own install root.
+ */
+const installRootOf = (path: string): string => {
+  const parts = path.split(sep)
+  const last = parts.lastIndexOf("node_modules")
+  if (last <= 0) return path
+  return parts.slice(0, last).join(sep)
+}
+
+/**
+ * State the SHAPE of a duplicate, not just its paths.
+ *
+ * The failure a developer has to act on is a topology, and the two topologies take opposite fixes.
+ * Copies under one install root (a nested `node_modules` shadowing the hoisted one) collapse with a
+ * single reinstall from that root. Copies under separate roots - a linked checkout, a standalone app
+ * beside this one with its own `node_modules` - do not: that second root belongs to another install,
+ * and nothing this project runs can merge it. Naming which case this is turns a path list into a
+ * decision.
+ */
+const describeTopology = (
+  base: string,
+  scanRoot: string,
+  paths: readonly string[],
+): string | undefined => {
+  if (paths.length === 0) return undefined
+  const counts = new Map<string, number>()
+  for (const path of paths) {
+    const root = installRootOf(path)
+    counts.set(root, (counts.get(root) ?? 0) + 1)
+  }
+  const roots = [...counts.entries()].sort(([a], [b]) => a.localeCompare(b))
+  const breakdown = roots
+    .map(([root, count]) => `${count} under ${displayPath(base, root)}`)
+    .join(", ")
+  const outside = roots.filter(([root]) => !pathInside(scanRoot, root))
+  const shape =
+    outside.length > 0
+      ? `${outside.length} install root${outside.length === 1 ? " is" : "s are"} outside the scanned root (${outside
+          .map(([root]) => displayPath(base, root))
+          .join(
+            ", ",
+          )}), so that copy is installed by another project and reinstalling here cannot remove it`
+      : roots.length > 1
+        ? "all install roots are inside the scanned root, so a nested install is shadowing the hoisted copy and one reinstall from the workspace root collapses it"
+        : "one install root holds every copy, so the split is inside a single install (a nested or stored copy), not across projects"
+  return `${paths.length} paths under ${roots.length} install root${roots.length === 1 ? "" : "s"}: ${breakdown}; ${shape}`
+}
+
+/**
+ * State that the gate is workspace-wide, when that is what makes a finding look wrong.
+ *
+ * Running `nifra build` inside `apps/web` can fail on a copy held by `apps/admin` - a package this
+ * app never imports. That is deliberate, not a miss: the scan is anchored on the workspace because
+ * copies reached through a workspace-linked dependency are invisible from the app directory, and
+ * anchoring on the app is exactly how this guard once reported "none" while dev was already broken.
+ * The trade is over-reporting instead of under-reporting, and the note says so rather than leaving a
+ * developer to conclude the tool is confused about which project it is checking.
+ */
+const describeScope = (
+  requestedRoot: string,
+  scanRoot: string,
+  paths: readonly string[],
+): string | undefined => {
+  if (requestedRoot === scanRoot) return undefined
+  const outside = paths.filter((path) => !pathInside(requestedRoot, path))
+  if (outside.length === 0) return undefined
+  const here = relative(scanRoot, requestedRoot) || "."
+  return `${outside.length} of these copies ${outside.length === 1 ? "is" : "are"} outside ${here}, so this fails every build in the workspace, including apps that never import the package. The scan is anchored on the workspace on purpose: a copy reached through a workspace-linked dependency cannot be seen from ${here} alone, and scoping to it would miss the case this check exists for. Fix the copies where they live, or declare the package single-copy.`
+}
+
 const identityTargets = (pkg: Record<string, unknown>): readonly string[] =>
-  dependencyNames(pkg)
-    .filter((name) => name.startsWith("@nifrajs/") || IDENTITY_SENSITIVE_PACKAGES.has(name))
-    .sort()
+  dependencyNames(pkg).filter(isIdentitySensitivePackage).sort()
 
-const IDENTITY_REMEDIATION =
+/** version-skew is a range problem: one reinstall from the root collapses it. */
+const VERSION_SKEW_REMEDIATION =
   "Align dependency ranges and reinstall from the workspace root so every importer resolves one physical copy; nifra does not rewrite lockfiles for identity conflicts."
+/** duplicate-path is a topology problem. When the copies come from a linked sibling repo a reinstall
+ * does not collapse them - each tree keeps its own copy, which is the whole reason `link:` was chosen.
+ * So the fix is either one physical path, or a declaration that nifra can verify and enforce. */
+const duplicatePathRemediation = (name: string): string =>
+  `Deduplicate so ${name} resolves to a single physical path, or declare it single-copy: add "nifra": { "singleCopy": ["${name}"] } to package.json and preload "${SINGLE_COPY_REGISTER_SPECIFIER}" from bunfig.toml. nifra then rewrites every duplicate to this app's copy - at one version only, so align ranges first if the copies ever differ.`
+const identityRemediation = (cause: IdentityParityCause, name: string): string =>
+  cause === "version-skew" ? VERSION_SKEW_REMEDIATION : duplicatePathRemediation(name)
+
+/** What is left to do about a duplicate the declaration already covers. */
+const deduplicatedRemediation = (registration: SingleCopyRegistration): string =>
+  registration.run || registration.test
+    ? "Declared single-copy and enforced: every duplicate is rewritten to this app's copy, so one module instance loads."
+    : `Declared single-copy, so bundled output is deduplicated by the build. Unbundled runs are NOT: Bun's runtime never offers a bare specifier to a resolver, so add preload = ["${SINGLE_COPY_REGISTER_SPECIFIER}"] to bunfig.toml (and under [test]) or \`bun test\` still loads both copies.`
+
+/**
+ * Read the declaration and its runtime proof, preferring the directory the caller is in.
+ *
+ * A monorepo declares this per app, not once at the root: the app is what owns the `node_modules` the
+ * duplicates must collapse into, and two apps in one workspace can legitimately differ. The workspace
+ * root is the fallback so a single-package project needs no second file.
+ */
+const singleCopyCoverage = (cwd: string, scanRoot: string): SingleCopyCoverage => {
+  const declared = readSingleCopyDeclaration(cwd) ?? readSingleCopyDeclaration(scanRoot) ?? []
+  const local = readSingleCopyRegistration(cwd)
+  const registration = local.run || local.test ? local : readSingleCopyRegistration(scanRoot)
+  return { declared, registration }
+}
 
 /** Find duplicate identity-sensitive package realpaths without reading application payloads. */
 export async function collectIdentityParity(
   cwd: string,
   rootPackage?: Record<string, unknown>,
-  options: IdentityParityOptions = {},
 ): Promise<IdentityParityResult> {
-  const requestedRoot = resolve(cwd)
+  const requestedRoot = realpathOrSelf(resolve(cwd))
   const localPackage = await readJson(join(requestedRoot, "package.json"))
+  // One basis for every caller. A package subdirectory is scanned as the workspace that governs it,
+  // because that workspace is what installed the copies it loads - and because a doctor and a build
+  // that anchor differently answer the same question differently, which is how a guard loses trust.
   const workspace =
-    options.useWorkspaceRoot && localPackage !== undefined
-      ? await resolveParityWorkspaceRoot(requestedRoot)
-      : { root: requestedRoot, package: localPackage ?? rootPackage ?? {} }
+    localPackage === undefined
+      ? { root: requestedRoot, package: rootPackage ?? {} }
+      : await resolveParityWorkspaceRoot(requestedRoot)
   const scanRoot = workspace.root
   const scanPackage = workspace.package
-  const importers = await workspaceImporters(scanRoot, scanPackage)
+  const { importers, truncated } = await workspaceImporters(scanRoot, scanPackage)
   const byPackage = new Map<string, Map<string, { version: string; importers: Set<string> }>>()
   const record = (
     name: string,
@@ -313,20 +539,20 @@ export async function collectIdentityParity(
       if (importer.package.name === name) continue
       targets.add(name)
       const copy = await resolvedInstalledCopy(importer.root, scanRoot, name)
-      if (copy !== undefined) record(name, copy, displayPath(cwd, importer.root))
+      if (copy !== undefined) record(name, copy, displayPath(requestedRoot, importer.root))
     }
   }
   for (const name of targets) {
     const copy = await resolvedInstalledCopy(scanRoot, scanRoot, name)
-    if (copy !== undefined) record(name, copy, displayPath(cwd, scanRoot))
+    if (copy !== undefined) record(name, copy, displayPath(requestedRoot, scanRoot))
   }
 
-  const linkedRoots = await linkedPackageRoots(
+  const linked = await linkedPackageRoots(
     [...importers.map((importer) => importer.root), scanRoot],
     [...importers.map((importer) => importer.package), scanPackage],
     scanRoot,
   )
-  for (const linkedRoot of linkedRoots) {
+  for (const linkedRoot of linked.roots) {
     const linkedPackage = await readJson(join(linkedRoot, "package.json"))
     const boundary = await linkedRepoBoundary(linkedRoot)
     const linkedTargets = new Set([
@@ -336,23 +562,33 @@ export async function collectIdentityParity(
     for (const name of linkedTargets) {
       if (linkedPackage?.name === name) continue
       const copy = await resolvedInstalledCopy(linkedRoot, boundary, name)
-      if (copy !== undefined) record(name, copy, displayPath(cwd, linkedRoot))
+      if (copy !== undefined) record(name, copy, displayPath(requestedRoot, linkedRoot))
     }
   }
 
+  const singleCopy = singleCopyCoverage(requestedRoot, scanRoot)
   const findings: IdentityParityFinding[] = []
+  const deduplicated: IdentityParityFinding[] = []
   for (const [name, copies] of [...byPackage.entries()].sort(([a], [b]) => a.localeCompare(b))) {
     if (copies.size < 2) continue
+    const absolutePaths = [...copies.keys()].sort()
     const resolvedCopies = [...copies.entries()]
       .sort(([a], [b]) => a.localeCompare(b))
       .map(([path, copy]) => ({
         version: copy.version,
-        path: displayPath(cwd, path),
+        path: displayPath(requestedRoot, path),
         importers: [...copy.importers].sort(),
       }))
+    const topology = describeTopology(requestedRoot, scanRoot, absolutePaths)
+    const scope = describeScope(requestedRoot, scanRoot, absolutePaths)
     const versions = [...new Set(resolvedCopies.map((copy) => copy.version))].sort()
     const cause: IdentityParityCause = versions.length > 1 ? "version-skew" : "duplicate-path"
-    findings.push({
+    // A declaration never covers a version skew. Redirecting across versions would hand a package a
+    // version it did not ask for, which converts a loud install problem into a quiet behavioural one -
+    // so the skew stays fatal and the ranges have to be fixed.
+    const covered =
+      cause === "duplicate-path" && matchesSingleCopyDeclaration(singleCopy.declared, name)
+    const finding: IdentityParityFinding = {
       package: name,
       copies: resolvedCopies,
       versions,
@@ -360,14 +596,29 @@ export async function collectIdentityParity(
       explanation:
         cause === "version-skew"
           ? `${name} resolves to multiple versions and physical paths, so module state and symbols are not shared`
-          : `${name} is loaded from more than one physical path, so module state and symbols are not shared`,
-      remediation: IDENTITY_REMEDIATION,
-    })
+          : covered
+            ? `${name} is installed at more than one physical path and is declared single-copy, so every duplicate is rewritten to this app's copy`
+            : `${name} is loaded from more than one physical path, so module state and symbols are not shared`,
+      remediation: covered
+        ? deduplicatedRemediation(singleCopy.registration)
+        : identityRemediation(cause, name),
+      ...(topology === undefined ? {} : { topology }),
+      ...(scope === undefined ? {} : { scope }),
+      deduplicated: covered,
+    }
+    ;(covered ? deduplicated : findings).push(finding)
+  }
+  return {
+    workspaceRoot: scanRoot,
+    requestedRoot,
+    truncated: truncated || linked.truncated,
+    findings,
+    deduplicated,
+    singleCopy,
   }
-  return { workspaceRoot: scanRoot, findings }
 }
 
-/** One `- pkg [cause]: ...` line per finding, shared by the hard failure and the dev warning. */
+/** One `- pkg [cause]: ...` block per finding, shared by the hard failure and the dev warning. */
 export function formatIdentityParityFindings(findings: readonly IdentityParityFinding[]): string {
   return findings
     .map(
@@ -375,25 +626,62 @@ export function formatIdentityParityFindings(findings: readonly IdentityParityFi
         `- ${finding.package} [${finding.cause}]: ${finding.explanation}. ${finding.remediation}\n` +
         `  versions: ${finding.versions.join(", ")}; paths: ${finding.copies
           .map((copy) => copy.path)
-          .join(", ")}`,
+          .join(", ")}` +
+        (finding.topology === undefined ? "" : `\n  topology: ${finding.topology}`) +
+        (finding.scope === undefined ? "" : `\n  scope: ${finding.scope}`),
     )
     .join("\n")
 }
 
+/**
+ * The basis a scan ran on, for any surface that reports its result.
+ *
+ * A verdict about installs is only as good as where it looked, and the reader cannot see that from a
+ * list of relative paths. Stating it also makes a truncated scan impossible to read as a clean one.
+ */
+export function identityParityBasis(result: IdentityParityResult): string {
+  const scope =
+    result.workspaceRoot === result.requestedRoot
+      ? `scanned ${result.workspaceRoot}`
+      : `scanned ${result.workspaceRoot} (the workspace governing ${result.requestedRoot})`
+  return result.truncated
+    ? `${scope}; PARTIAL - enumeration stopped at a scan limit (${MAX_WORKSPACE_IMPORTERS} workspace packages, ${MAX_LINKED_PACKAGES} linked packages, or ${MAX_LINK_PROBES} link probes), so installs beyond it were not examined`
+    : scope
+}
+
 /** `2 primary package findings` / `1 primary package finding`. */
 export const identityParityHeadline = (count: number): string =>
   `${count} primary package finding${count === 1 ? "" : "s"}`
 
-/** Fail before dev/build when the same identity-sensitive package has multiple realpaths. */
+/**
+ * Fail before dev/build when the same identity-sensitive package has multiple realpaths AND nothing
+ * is collapsing them.
+ *
+ * A declared package is not a suppression: the build injects the single-copy resolver, so the duplicate
+ * genuinely cannot reach the output. Failing on it anyway would leave the only supported answer being
+ * to change the install topology, which is the thing an app using linked sibling repositories cannot
+ * do. `result.deduplicated` still carries every covered duplicate for the caller to print.
+ */
 export async function assertIdentityParity(
   cwd: string,
   rootPackage?: Record<string, unknown>,
-  options: IdentityParityOptions = {},
 ): Promise<IdentityParityResult> {
-  const result = await collectIdentityParity(cwd, rootPackage, options)
-  if (result.findings.length === 0) return result
+  const result = await collectIdentityParity(cwd, rootPackage)
+  if (result.findings.length === 0) {
+    // A bounded scan that found nothing has not shown there is nothing: the duplicate can be sitting
+    // in the part it never reached. `truncated` is exactly that state, so the hard gate refuses to
+    // read it as a pass - a guard that answers "clean" from an incomplete scan is how a guard stops
+    // being worth having. Reporting surfaces (`nifra doctor`, the dev warning) still print the
+    // partial result through `identityParityBasis`; only the gate that must not be wrong stops here.
+    if (result.truncated) {
+      throw new Error(
+        `[nifra] identity parity inconclusive - scan limit reached (${identityParityBasis(result)}). Narrow the scan (run from the app or workspace that governs this install) or reduce the workspace/linked-package topology so the scan can complete.`,
+      )
+    }
+    return result
+  }
   throw new Error(
-    `[nifra] identity parity failed (${identityParityHeadline(result.findings.length)}):\n${formatIdentityParityFindings(result.findings)}`,
+    `[nifra] identity parity failed (${identityParityHeadline(result.findings.length)}; ${identityParityBasis(result)}):\n${formatIdentityParityFindings(result.findings)}`,
   )
 }
 
@@ -449,9 +737,13 @@ export function normalizeBuildManifest(manifest: BuildManifestLike): ParityManif
           .sort(([a], [b]) => a.localeCompare(b))
           .map(([route, chunks]) => [route, chunks.length]),
       ),
-      emittedAssets: logicalStaticAssets(manifest).filter(
-        (asset) => !asset.startsWith("css:") && !asset.startsWith("public:"),
-      ),
+      // Allowlist, not denylist: the dev/prod module-graph contract is the JavaScript module graph
+      // only. `js:entry` and `js:route:<id>:<n>` are the roles dev can reconstruct from source. Which
+      // *non-JS* files a bundler emits (svg, woff2, an extracted stylesheet) is an output detail, not
+      // a claim dev can make - dev serves those from source. The stylesheet claim that matters keeps
+      // its own `css` section; `public/` keeps `publicFiles`. A denylist admitted every future
+      // `asset:*` prefix by default, which is how an emitted `asset:svg` hard-failed every build.
+      emittedAssets: logicalStaticAssets(manifest).filter((asset) => asset.startsWith("js:")),
     },
     publicFiles: [...(manifest.publicFiles ?? [])].sort(),
     css: (manifest.css ?? []).length > 0 ? ["css:present"] : [],
@@ -530,6 +822,7 @@ export function collectDevelopmentParityInput(
     routes,
     publicFiles: publicFilesUnder(publicDir),
     css,
+    sourceRoot,
   }
 }
 
@@ -552,11 +845,73 @@ export function compareManifestParity(
       development: development.publicFiles,
       production: production.publicFiles,
     })
-  if (!equal(development.css, production.css))
+  // css is the one section with an inference-based side. The dev scanner (CSS_IMPORT) is
+  // sound-but-incomplete by construction, so `dev empty, prod css` is a scanner miss, not an app
+  // defect - it passes. Fail only the load-bearing direction: dev found styles the build does not
+  // ship, so the production page would render unstyled. module-graph and public-files stay on equality
+  // because both sides are ground truth there.
+  if (development.css.length > 0 && production.css.length === 0)
     differences.push({ section: "css", development: development.css, production: production.css })
   return differences
 }
 
+/** The forms `CSS_IMPORT` cannot see, quoted in a css parity failure so the reader knows where to look. */
+const CSS_SCANNER_BLIND_SPOTS =
+  "a dynamic import(), a bare package subpath (exports), require(), an @import inside a stylesheet, or plugin-injected css"
+
+const symmetricDifference = (
+  a: readonly string[],
+  b: readonly string[],
+): { readonly onlyDevelopment: readonly string[]; readonly onlyProduction: readonly string[] } => {
+  const left = new Set(a)
+  const right = new Set(b)
+  return {
+    onlyDevelopment: a.filter((value) => !right.has(value)),
+    onlyProduction: b.filter((value) => !left.has(value)),
+  }
+}
+
+/** Turn one parity difference into a message that names the offending files, not two opaque blobs. */
+function explainParityDifference(
+  difference: ManifestParityDifference,
+  development: DevelopmentParityInput,
+  production: BuildManifestLike,
+): string {
+  if (difference.section === "css") {
+    const shipped = (production.css ?? []).join(", ")
+    const where = development.sourceRoot === undefined ? "" : ` under ${development.sourceRoot}`
+    return (
+      `css: production ships [${shipped || "(none)"}] but the development scanner found no static ` +
+      `stylesheet import${where} - it is blind to ${CSS_SCANNER_BLIND_SPOTS}`
+    )
+  }
+  if (difference.section === "module-graph") {
+    const dev = difference.development as ParityManifest["moduleGraph"]
+    const prod = difference.production as ParityManifest["moduleGraph"]
+    const routes = symmetricDifference(dev.routes, prod.routes)
+    const assets = symmetricDifference(dev.emittedAssets, prod.emittedAssets)
+    const parts: string[] = []
+    if (routes.onlyDevelopment.length > 0 || routes.onlyProduction.length > 0)
+      parts.push(
+        `routes only in development=${JSON.stringify(routes.onlyDevelopment)} only in production=${JSON.stringify(routes.onlyProduction)}`,
+      )
+    if (assets.onlyDevelopment.length > 0 || assets.onlyProduction.length > 0)
+      parts.push(
+        `chunks only in development=${JSON.stringify(assets.onlyDevelopment)} only in production=${JSON.stringify(assets.onlyProduction)}`,
+      )
+    if (parts.length === 0)
+      parts.push(
+        `route chunk counts differ: development=${JSON.stringify(dev.routeChunks)} production=${JSON.stringify(prod.routeChunks)}`,
+      )
+    return `module-graph: ${parts.join("; ")}`
+  }
+  const files = symmetricDifference(
+    difference.development as readonly string[],
+    difference.production as readonly string[],
+  )
+  return `${difference.section}: only in development=${JSON.stringify(files.onlyDevelopment)} only in production=${JSON.stringify(files.onlyProduction)}`
+}
+
 /** Validate a production manifest against the source manifest a development server should serve. */
 export function assertDevelopmentProductionParity(
   development: DevelopmentParityInput,
@@ -568,10 +923,7 @@ export function assertDevelopmentProductionParity(
   )
   if (differences.length > 0) {
     const detail = differences
-      .map(
-        (difference) =>
-          `${difference.section}: development=${JSON.stringify(difference.development)} production=${JSON.stringify(difference.production)}`,
-      )
+      .map((difference) => explainParityDifference(difference, development, production))
       .join("; ")
     throw new Error(`[nifra] development and production manifest parity failed: ${detail}`)
   }