@dev-tren/mapd 0.21.0

package/src/core/reachability.js

@@ -0,0 +1,543 @@
+/**
+ * reachability.js — replaces the old binary "covered vs orphan" model with a
+ * real taxonomy. Static import/call tracing genuinely cannot see everything:
+ * runtime directory-scan plugin loaders, and test runners that discover
+ * specs by globbing a config-declared directory rather than importing them,
+ * are both legitimate, common patterns that static analysis cannot resolve.
+ *
+ * The design rule (same as frameworkEntries.js): every detector here either
+ * verifies its finding against real AST structure and a real file/directory
+ * that exists in the project, or it detects nothing. We never claim a file
+ * IS used just because it sits under a dynamically-loaded directory — only
+ * that its reachability is legitimately unverifiable by import tracing, so
+ * it must not be asserted dead either. That's a distinct bucket from "truly
+ * orphaned," not a guess at aliveness.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { parse } from "@babel/parser";
+import _traverse from "@babel/traverse";
+
+const traverse = _traverse.default ?? _traverse;
+const BABEL_OPTS = { sourceType: "unambiguous", errorRecovery: true, plugins: ["typescript", "jsx", "decorators-legacy"] };
+
+const GENERATED_HEADER_RE = /@generated\b|auto-?generated|generated by|do not edit(?:\s+by hand)?/i;
+const GENERATED_NAME_SEGMENTS = new Set(["bundle", "bundled", "min", "generated"]);
+
+/**
+ * Filename convention, checked as a whole path segment (split on -._), not a
+ * bare substring — so "plan-mode-bundle.cjs" (real-world hyphenated bundler
+ * output) matches just as well as "app.bundle.js" (dot-separated), while a
+ * genuinely hand-written file like "bundler.js" (a file *about* bundling,
+ * not *produced by* one) does not.
+ */
+function isGeneratedFilename(relFile) {
+  const base = path.posix.basename(relFile).replace(/\.[cm]?[jt]sx?$/i, "");
+  return base.split(/[-._]/).some((seg) => GENERATED_NAME_SEGMENTS.has(seg.toLowerCase()));
+}
+
+const BUNDLER_TOOLS_RE = /\b(esbuild|webpack|rollup|parcel|vite|tsc|swc|rspack)\b/;
+const OUTPUT_FLAG_RES = [
+  /--outfile[= ]+["']?([^\s"']+)/,
+  /--outdir(?:ir)?[= ]+["']?([^\s"']+)/i,
+  /--output(?:-path)?[= ]+["']?([^\s"']+)/,
+  /--file[= ]+["']?([^\s"']+)/,
+  /(?:^|\s)-o\s+["']?([^\s"']+)/,
+];
+
+/**
+ * Recognizes a package.json script that invokes a known bundler/compiler CLI
+ * and declares its output via a real, literal flag (`--outfile=X`, `-o X`,
+ * etc.) — the strongest possible signal a file is generated, since the
+ * project's OWN build configuration says so, not a naming guess. This is
+ * what catches a real bundler output whose filename doesn't happen to match
+ * any naming convention at all.
+ */
+export function detectBundlerOutputs(pkg) {
+  const outputs = [];
+  for (const [scriptName, cmd] of Object.entries(pkg?.scripts ?? {})) {
+    if (typeof cmd !== "string" || !BUNDLER_TOOLS_RE.test(cmd)) continue;
+    for (const re of OUTPUT_FLAG_RES) {
+      const m = re.exec(cmd);
+      if (m) outputs.push({ path: path.posix.normalize(m[1].replace(/^["']|["']$/g, "")), script: scriptName });
+    }
+  }
+  return outputs;
+}
+
+const BUNDLER_CONFIG_FILES = [
+  "webpack.config.js", "webpack.config.cjs", "webpack.config.mjs", "webpack.config.ts",
+  "rollup.config.js", "rollup.config.cjs", "rollup.config.mjs", "rollup.config.ts",
+];
+
+/** Resolves `path.join/resolve(__dirname, "lit", ...)` to its literal parts, or a plain StringLiteral to its value. */
+function resolveLiteralOrDirnamePath(valueNode) {
+  if (valueNode?.type === "StringLiteral") return valueNode.value;
+  if (valueNode?.type === "CallExpression") {
+    const callee = valueNode.callee;
+    const isPathJoinOrResolve = callee?.type === "MemberExpression" && callee.object?.name === "path" &&
+      (callee.property?.name === "join" || callee.property?.name === "resolve");
+    if (!isPathJoinOrResolve) return null;
+    const args = valueNode.arguments ?? [];
+    if (!args.some((a) => a.type === "Identifier" && a.name === "__dirname")) return null;
+    const literalParts = args.filter((a) => a.type === "StringLiteral").map((a) => a.value);
+    return literalParts.length ? literalParts.join("/") : null;
+  }
+  return null;
+}
+
+/**
+ * webpack/rollup declare their output in a config FILE, not an npm-script
+ * flag — a project building through `webpack --config webpack.config.js`
+ * gives detectBundlerOutputs (script-string parsing) nothing to find, so its
+ * bundle would be scanned as source, the exact bug just fixed for esbuild.
+ * Same verification model as detectViteEntries: anchor on the literal
+ * `output` key, only trust plain string literals or the well-known
+ * `path.join/resolve(__dirname, ...)` pattern — anything dynamic is left
+ * undetected rather than guessed at.
+ *   webpack: output: { path: path.resolve(__dirname, "electron"), filename: "main.js" }
+ *   rollup:  output: { file: "electron/bundle.cjs" }  or  output: { dir: "out" }  (arrays too)
+ */
+export function detectConfigBundlerOutputs(rootDir) {
+  const outputs = [];
+  for (const rel of BUNDLER_CONFIG_FILES) {
+    const abs = path.join(rootDir, rel);
+    if (!fs.existsSync(abs)) continue;
+    let ast;
+    try { ast = parse(fs.readFileSync(abs, "utf8"), BABEL_OPTS); } catch { continue; }
+
+    traverse(ast, {
+      ObjectProperty(p) {
+        const keyName = p.node.key?.name ?? p.node.key?.value;
+        if (keyName !== "output") return;
+        const outputObjs = p.node.value.type === "ArrayExpression"
+          ? p.node.value.elements.filter((el) => el?.type === "ObjectExpression")
+          : p.node.value.type === "ObjectExpression" ? [p.node.value] : [];
+
+        for (const obj of outputObjs) {
+          const prop = (name) => obj.properties.find((pr) => (pr.key?.name ?? pr.key?.value) === name);
+          // rollup: `file` (single output) / `dir` (whole directory)
+          const file = resolveLiteralOrDirnamePath(prop("file")?.value);
+          if (file) { outputs.push({ path: path.posix.normalize(file), script: rel }); continue; }
+          const dir = resolveLiteralOrDirnamePath(prop("dir")?.value);
+          if (dir) { outputs.push({ path: path.posix.normalize(dir), script: rel }); continue; }
+          // webpack: `path` (directory) + optional `filename`
+          const outPath = resolveLiteralOrDirnamePath(prop("path")?.value);
+          if (!outPath) continue;
+          const filename = prop("filename")?.value?.type === "StringLiteral" ? prop("filename").value.value : null;
+          // a webpack filename with substitution tokens ([name].js etc.) means
+          // we can't name the exact file — fall back to the output directory,
+          // which is still fully declared, not guessed.
+          const exact = filename && !filename.includes("[") ? path.posix.join(outPath, filename) : outPath;
+          outputs.push({ path: path.posix.normalize(exact), script: rel });
+        }
+      },
+    });
+  }
+  return outputs;
+}
+
+/**
+ * Filename convention, a declared bundler output (npm-script flag OR
+ * webpack/rollup config file), or an explicit header marker — never a
+ * size/minification guess. `bundlerOutputs` (from detectBundlerOutputs +
+ * detectConfigBundlerOutputs) is optional; passing it in lets a file be
+ * recognized as generated even with no naming convention and no header
+ * comment at all (common for esbuild/webpack output, which often has neither).
+ */
+export function isGeneratedArtifact(rootDir, relFile, bundlerOutputs = []) {
+  if (isGeneratedFilename(relFile)) return { generated: true, reason: `filename convention (${path.posix.basename(relFile)})` };
+  const declared = bundlerOutputs.find((o) => o.path === relFile || relFile.startsWith(`${o.path}/`));
+  if (declared) return { generated: true, reason: `declared build output of "${declared.script}"` };
+  let head;
+  try { head = fs.readFileSync(path.join(rootDir, relFile), "utf8").slice(0, 300); } catch { return { generated: false }; }
+  const m = GENERATED_HEADER_RE.exec(head);
+  if (m) return { generated: true, reason: `header comment ("${m[0]}")` };
+  return { generated: false };
+}
+
+function allAncestorDirs(fileSet) {
+  const dirs = new Set();
+  for (const f of fileSet) {
+    let dir = path.posix.dirname(f);
+    while (dir && dir !== ".") { dirs.add(dir); dir = path.posix.dirname(dir); }
+  }
+  return dirs;
+}
+
+/**
+ * `<something>.load(path.join(__dirname, "tools"))`-style runtime directory
+ * loaders: any call whose argument resolves — via the same verified
+ * `path.join(__dirname, ...)`/`path.resolve(__dirname, ...)` pattern already
+ * used for Electron preload resolution — to a real DIRECTORY (not a single
+ * file) in the project. We record the exact call site as evidence; we do
+ * not attempt to guess which files inside actually get loaded.
+ */
+export function detectDynamicDirectoryReferences(rootDir, files, fileSet) {
+  const dirSet = allAncestorDirs(fileSet);
+  const results = [];
+  for (const f of files) {
+    const relFile = f.file.split(path.sep).join("/");
+    if (!/\.(js|ts|jsx|tsx|mjs|cjs|mts|cts)$/.test(relFile)) continue;
+    let raw;
+    try { raw = fs.readFileSync(path.join(rootDir, relFile), "utf8"); } catch { continue; }
+    if (!raw.includes("__dirname")) continue; // cheap pre-filter, not the verification itself
+    let ast;
+    try { ast = parse(raw, BABEL_OPTS); } catch { continue; }
+    const fileDirPosix = path.posix.dirname(relFile);
+
+    traverse(ast, {
+      CallExpression(p) {
+        const callee = p.node.callee;
+        const isPathJoinOrResolve = callee?.type === "MemberExpression" && callee.object?.name === "path" &&
+          (callee.property?.name === "join" || callee.property?.name === "resolve");
+        if (!isPathJoinOrResolve) return;
+        const args = p.node.arguments ?? [];
+        if (!args.some((a) => a.type === "Identifier" && a.name === "__dirname")) return;
+        const literalParts = args.filter((a) => a.type === "StringLiteral").map((a) => a.value);
+        if (!literalParts.length) return;
+        const resolved = path.posix.normalize(path.posix.join(fileDirPosix, literalParts.join("/")));
+        if (dirSet.has(resolved) && !fileSet.has(resolved)) {
+          results.push({ dir: resolved, referencedFrom: relFile, line: p.node.loc?.start.line ?? null });
+        }
+      },
+    });
+  }
+  return results;
+}
+
+/**
+ * Template-literal dynamic loads: `import(\`./plugins/${name}.js\`)` and
+ * `require(\`./commands/${cmd}.js\`)` — the classic plugin/command-registry
+ * pattern. Static analysis cannot know which file gets loaded, but the
+ * literal PREFIX before the first interpolation names the directory being
+ * loaded from, and that part is fully verifiable: we resolve it relative to
+ * the importing file and only report it when it is a real directory that
+ * contains project files. Same design rule as every other detector here —
+ * verified against real AST structure and a real directory, or nothing.
+ */
+export function detectDynamicImportPrefixes(rootDir, files, fileSet) {
+  const dirSet = allAncestorDirs(fileSet);
+  const results = [];
+  for (const f of files) {
+    const relFile = f.file.split(path.sep).join("/");
+    if (!/\.(js|ts|jsx|tsx|mjs|cjs|mts|cts)$/.test(relFile)) continue;
+    let raw;
+    try { raw = fs.readFileSync(path.join(rootDir, relFile), "utf8"); } catch { continue; }
+    if (!raw.includes("import(") && !raw.includes("require(")) continue; // cheap pre-filter, not the verification itself
+    let ast;
+    try { ast = parse(raw, BABEL_OPTS); } catch { continue; }
+    const fileDirPosix = path.posix.dirname(relFile);
+
+    // only template literals WITH interpolation — a fully-static specifier
+    // is ordinary import resolution's job, not a dynamic edge
+    const checkSpecifier = (arg, node, via) => {
+      if (arg?.type !== "TemplateLiteral" || !arg.expressions?.length) return;
+      const prefix = arg.quasis?.[0]?.value?.cooked ?? "";
+      if (!prefix.startsWith("./") && !prefix.startsWith("../")) return; // bare/absolute specifiers can't be verified against the project tree
+      const dirPart = prefix.includes("/") ? prefix.slice(0, prefix.lastIndexOf("/")) : ".";
+      const resolved = path.posix.normalize(path.posix.join(fileDirPosix, dirPart));
+      if (dirSet.has(resolved)) {
+        results.push({ dir: resolved, referencedFrom: relFile, line: node.loc?.start.line ?? null, via });
+      }
+    };
+
+    traverse(ast, {
+      // Babel 8 parses `import(x)` as its own ImportExpression node
+      ImportExpression(p) {
+        checkSpecifier(p.node.source, p.node, "dynamic-import-template");
+      },
+      CallExpression(p) {
+        const callee = p.node.callee;
+        // Babel 7 shape for `import(x)` was CallExpression with an Import callee
+        if (callee?.type === "Import") return checkSpecifier(p.node.arguments?.[0], p.node, "dynamic-import-template");
+        if (callee?.type === "Identifier" && callee.name === "require") return checkSpecifier(p.node.arguments?.[0], p.node, "require-template");
+      },
+    });
+  }
+  return results;
+}
+
+/**
+ * Vite's `import.meta.glob("./modules/*.js")` — the files matching the glob
+ * really are bundled and loaded (lazily) at runtime, but no ImportDeclaration
+ * ever names them. AST-verified shape: a call whose callee is
+ * `import.meta.glob` (MetaProperty + MemberExpression, not a regex guess)
+ * with literal string glob argument(s). Matched against the real file set
+ * with the same deterministic globToRegex used for annotations — a glob that
+ * matches nothing detects nothing.
+ */
+export function detectImportMetaGlobs(rootDir, files, fileSet) {
+  const results = [];
+  for (const f of files) {
+    const relFile = f.file.split(path.sep).join("/");
+    if (!/\.(js|ts|jsx|tsx|mjs|cjs|mts|cts)$/.test(relFile)) continue;
+    let raw;
+    try { raw = fs.readFileSync(path.join(rootDir, relFile), "utf8"); } catch { continue; }
+    if (!raw.includes("import.meta.glob")) continue; // cheap pre-filter, not the verification itself
+    let ast;
+    try { ast = parse(raw, BABEL_OPTS); } catch { continue; }
+    const fileDirPosix = path.posix.dirname(relFile);
+
+    traverse(ast, {
+      CallExpression(p) {
+        const callee = p.node.callee;
+        const isImportMetaGlob = callee?.type === "MemberExpression" &&
+          callee.object?.type === "MetaProperty" &&
+          callee.object.meta?.name === "import" && callee.object.property?.name === "meta" &&
+          callee.property?.name === "glob";
+        if (!isImportMetaGlob) return;
+        const arg = p.node.arguments?.[0];
+        const patterns = arg?.type === "StringLiteral" ? [arg.value]
+          : arg?.type === "ArrayExpression" ? arg.elements.filter((el) => el?.type === "StringLiteral").map((el) => el.value)
+          : [];
+        for (const pattern of patterns) {
+          if (!pattern.startsWith("./") && !pattern.startsWith("../") && !pattern.startsWith("/")) continue;
+          const resolved = pattern.startsWith("/")
+            ? pattern.slice(1) // Vite: leading / = project root
+            : path.posix.normalize(path.posix.join(fileDirPosix, pattern));
+          const re = globToRegex(resolved);
+          for (const file of fileSet) {
+            if (re.test(file)) results.push({ file, referencedFrom: relFile, line: p.node.loc?.start.line ?? null, via: `import.meta.glob("${pattern}")` });
+          }
+        }
+      },
+    });
+  }
+  return results;
+}
+
+/**
+ * `new Worker(new URL("./worker.js", import.meta.url))` — the standard
+ * bundler-recognized worker pattern. The worker file is genuinely executed
+ * at runtime but never appears in an import statement, so it otherwise reads
+ * as orphaned. AST-verified: NewExpression Worker/SharedWorker whose first
+ * argument is `new URL(<string literal>, import.meta.url)`, resolved relative
+ * to the referencing file and only reported when the target file exists.
+ */
+export function detectWorkerUrls(rootDir, files, fileSet) {
+  const results = [];
+  for (const f of files) {
+    const relFile = f.file.split(path.sep).join("/");
+    if (!/\.(js|ts|jsx|tsx|mjs|cjs|mts|cts)$/.test(relFile)) continue;
+    let raw;
+    try { raw = fs.readFileSync(path.join(rootDir, relFile), "utf8"); } catch { continue; }
+    if (!raw.includes("Worker")) continue; // cheap pre-filter, not the verification itself
+    let ast;
+    try { ast = parse(raw, BABEL_OPTS); } catch { continue; }
+    const fileDirPosix = path.posix.dirname(relFile);
+
+    traverse(ast, {
+      NewExpression(p) {
+        const calleeName = p.node.callee?.type === "Identifier" ? p.node.callee.name : null;
+        if (calleeName !== "Worker" && calleeName !== "SharedWorker") return;
+        const arg = p.node.arguments?.[0];
+        const isNewUrl = arg?.type === "NewExpression" && arg.callee?.type === "Identifier" && arg.callee.name === "URL";
+        if (!isNewUrl) return;
+        const spec = arg.arguments?.[0];
+        const base = arg.arguments?.[1];
+        const isImportMetaUrl = base?.type === "MemberExpression" &&
+          base.object?.type === "MetaProperty" && base.property?.name === "url";
+        if (spec?.type !== "StringLiteral" || !isImportMetaUrl) return;
+        const resolved = path.posix.normalize(path.posix.join(fileDirPosix, spec.value));
+        if (fileSet.has(resolved)) {
+          results.push({ file: resolved, referencedFrom: relFile, line: p.node.loc?.start.line ?? null, via: `new ${calleeName}(new URL(...))` });
+        }
+      },
+    });
+  }
+  return results;
+}
+
+const TEST_GLOB_CONFIGS = [
+  "playwright.config.ts", "playwright.config.js", "playwright.config.mjs", "playwright.config.cjs",
+  "vitest.config.ts", "vitest.config.js", "vitest.config.mjs", "vitest.config.cjs",
+  "jest.config.js", "jest.config.ts", "jest.config.cjs", "jest.config.mjs",
+  "cypress.config.ts", "cypress.config.js",
+];
+const TEST_GLOB_KEYS = new Set(["testDir", "testMatch", "include", "roots", "specPattern", "testRegex"]);
+
+/** Everything up to the first glob metacharacter, with any trailing partial segment trimmed. */
+function staticPrefixOfGlob(globStr) {
+  const idx = globStr.search(/[*{]/);
+  if (idx === -1) return globStr.replace(/\/$/, ""); // no glob metachar at all — the whole string is a literal path
+  const prefix = globStr.slice(0, idx);
+  return prefix.replace(/\/[^/]*$/, ""); // trim the partial segment before the wildcard, e.g. "tests/**" -> "tests"
+}
+
+/**
+ * Playwright/Vitest/Jest/Cypress configs declare WHERE their specs live as a
+ * string or glob value (`testDir`, `include`, ...) — the runner globs that
+ * directory at runtime, it never imports the spec files, so the existing
+ * tooling-config entry-point registration (frameworkEntries.js) doesn't help
+ * here. We only trust literal string values under a fixed, known key set.
+ */
+export function detectTestGlobDirectories(rootDir, fileSet) {
+  const results = [];
+  for (const rel of TEST_GLOB_CONFIGS) {
+    const abs = path.join(rootDir, rel);
+    if (!fs.existsSync(abs)) continue;
+    let ast;
+    try { ast = parse(fs.readFileSync(abs, "utf8"), BABEL_OPTS); } catch { continue; }
+
+    traverse(ast, {
+      ObjectProperty(p) {
+        const keyName = p.node.key?.name ?? p.node.key?.value;
+        if (!TEST_GLOB_KEYS.has(keyName)) return;
+        const value = p.node.value;
+        const literals = [];
+        if (value.type === "StringLiteral") literals.push(value.value);
+        else if (value.type === "ArrayExpression") for (const el of value.elements) if (el?.type === "StringLiteral") literals.push(el.value);
+
+        for (const lit of literals) {
+          const prefix = staticPrefixOfGlob(lit);
+          if (!prefix) continue;
+          const resolved = path.posix.normalize(path.posix.join(".", prefix));
+          if ([...fileSet].some((f) => f === resolved || f.startsWith(`${resolved}/`))) {
+            results.push({ dir: resolved, referencedFrom: rel, key: keyName, line: p.node.loc?.start.line ?? null });
+          }
+        }
+      },
+    });
+  }
+  return results;
+}
+
+/** Tiny deterministic glob: `**` crosses directories, `*` stays within a segment, everything else literal. */
+export function globToRegex(pattern) {
+  const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+  const body = escaped
+    .replace(/\*\*\//g, "ANYDIR")
+    .replace(/\*\*/g, "ANY")
+    .replace(/\*/g, "[^/]*")
+    .replace(/ANYDIR/g, "(?:.*/)?")
+    .replace(/ANY/g, ".*");
+  return new RegExp(`^${body}$`);
+}
+
+/**
+ * User-asserted classifications from .mapdrc `project.annotations` — the
+ * honest answer for things static analysis structurally cannot know (a
+ * timestamped results directory, a plugin folder loaded by a pattern mapd
+ * doesn't recognize). Mapd never guesses these; the user states them, and
+ * every downstream mention is labeled as user-asserted, never as detected.
+ * Returns [{ file, classification, pattern }] for files matching any pattern.
+ */
+export function applyAnnotations(fileSet, annotations = {}) {
+  // a value is either a bare classification string or { classification, reason?, source?, date? }
+  const compiled = Object.entries(annotations).map(([pattern, raw]) => ({
+    pattern,
+    classification: typeof raw === "string" ? raw : raw?.classification,
+    re: globToRegex(pattern),
+  }));
+  if (!compiled.length) return [];
+  const matches = [];
+  for (const file of fileSet) {
+    const hit = compiled.find((c) => c.re.test(file));
+    if (hit) matches.push({ file, classification: hit.classification, pattern: hit.pattern });
+  }
+  return matches;
+}
+
+/**
+ * Classifies generated-file status for EVERY file in the project, not just
+ * unreachable ones — a bundler output is generated regardless of whether
+ * something else in the project happens to import/require it. This is what
+ * lets modernize.js exclude a real, reachable bundle (e.g. one loaded by an
+ * Electron main process) from its scan, not just orphan-cluster.
+ * `annotations` adds user-asserted "generated" classifications on top of the
+ * detected ones, labeled as such.
+ */
+export function detectGeneratedFiles(rootDir, fileSet, pkg, annotations = {}) {
+  const bundlerOutputs = [...detectBundlerOutputs(pkg), ...detectConfigBundlerOutputs(rootDir)];
+  const annotated = new Map(
+    applyAnnotations(fileSet, annotations)
+      .filter((a) => a.classification === "generated")
+      .map((a) => [a.file, a.pattern]),
+  );
+  const generated = [];
+  for (const file of fileSet) {
+    if (annotated.has(file)) {
+      generated.push({ file, reason: `user annotation in .mapdrc ("${annotated.get(file)}": "generated")` });
+      continue;
+    }
+    const result = isGeneratedArtifact(rootDir, file, bundlerOutputs);
+    if (result.generated) generated.push({ file, reason: result.reason });
+  }
+  return generated;
+}
+
+/**
+ * The single entry point graph.js calls: classifies every file that ISN'T
+ * already statically reachable (not in `covered`) and isn't a test file (the
+ * two categories graph.js already computes) into: generated artifact,
+ * dynamically-loaded/unverifiable, user-asserted intentional-dormant,
+ * heuristic-unverified (parsed by a heuristic language adapter, so orphan
+ * status structurally cannot be asserted), or truly orphaned. Every
+ * non-orphan classification carries its evidence (the exact file/line or
+ * annotation that justified excluding it) — never a bare, unexplained
+ * exclusion. `generatedFiles` is detectGeneratedFiles' project-wide result,
+ * passed in so it's computed once.
+ */
+export function classifyUncoveredFiles(rootDir, files, fileSet, uncovered, generatedFiles, annotations = {}) {
+  const generatedSet = new Set(generatedFiles.map((g) => g.file));
+  const generatedReasons = new Map(generatedFiles.map((g) => [g.file, g.reason]));
+  const parserKindByFile = new Map(files.map((f) => [f.file.split(path.sep).join("/"), f.parserKind ?? "ast"]));
+
+  const dynamicRefs = [
+    ...detectDynamicDirectoryReferences(rootDir, files, fileSet),
+    ...detectDynamicImportPrefixes(rootDir, files, fileSet),
+    ...detectTestGlobDirectories(rootDir, fileSet),
+  ];
+  const dynamicDirs = new Map(); // dir -> evidence[]
+  for (const ref of dynamicRefs) {
+    if (!dynamicDirs.has(ref.dir)) dynamicDirs.set(ref.dir, []);
+    dynamicDirs.get(ref.dir).push(ref);
+  }
+  // file-level dynamic references: import.meta.glob matches and Worker URLs
+  // name EXACT files (verified to exist), not just a directory
+  const dynamicFiles = new Map(); // file -> evidence[]
+  for (const ref of [...detectImportMetaGlobs(rootDir, files, fileSet), ...detectWorkerUrls(rootDir, files, fileSet)]) {
+    if (!dynamicFiles.has(ref.file)) dynamicFiles.set(ref.file, []);
+    dynamicFiles.get(ref.file).push(ref);
+  }
+  const isUnderDynamicDir = (file) => {
+    if (dynamicFiles.has(file)) return dynamicFiles.get(file);
+    for (const [dir, evidence] of dynamicDirs) if (file === dir || file.startsWith(`${dir}/`)) return evidence;
+    return null;
+  };
+  const annotated = applyAnnotations(fileSet, annotations);
+  const annotatedDynamic = new Map(annotated.filter((a) => a.classification === "dynamically-loaded").map((a) => [a.file, a.pattern]));
+  const annotatedDormant = new Map(annotated.filter((a) => a.classification === "intentional-dormant").map((a) => [a.file, a.pattern]));
+
+  const generatedArtifacts = [];
+  const dynamicallyLoaded = [];
+  const intentionalDormant = [];
+  const heuristicUnverified = [];
+  const trulyOrphaned = [];
+
+  for (const file of uncovered) {
+    if (generatedSet.has(file)) { generatedArtifacts.push({ file, reason: generatedReasons.get(file) }); continue; }
+    if (annotatedDormant.has(file)) {
+      intentionalDormant.push({ file, evidence: [{ userAnnotation: `.mapdrc "${annotatedDormant.get(file)}": "intentional-dormant"` }] });
+      continue;
+    }
+    if (annotatedDynamic.has(file)) {
+      dynamicallyLoaded.push({ file, evidence: [{ userAnnotation: `.mapdrc "${annotatedDynamic.get(file)}": "dynamically-loaded"` }] });
+      continue;
+    }
+    const evidence = isUnderDynamicDir(file);
+    if (evidence) { dynamicallyLoaded.push({ file, evidence }); continue; }
+    if (parserKindByFile.get(file) === "heuristic") {
+      // heuristic import tracing is partial by construction — "no edge found"
+      // is not evidence of death, so these are disclosed as unverifiable,
+      // never asserted orphaned
+      heuristicUnverified.push({ file, reason: "parsed by heuristic language adapter — import tracing is partial, orphan status cannot be asserted" });
+      continue;
+    }
+    trulyOrphaned.push(file);
+  }
+
+  return { generatedArtifacts, dynamicallyLoaded, intentionalDormant, heuristicUnverified, trulyOrphaned: trulyOrphaned.sort() };
+}