weavatrix 0.1.2 → 0.1.3

package/src/analysis/dep-rules.js

@@ -18,21 +18,44 @@ const dirOf = (f) => (f.includes("/") ? f.slice(0, f.lastIndexOf("/")) : "");
 
 // File-level import adjacency. Go same-directory edges are excluded: a Go package IS the directory, the
 // compiler forbids real cross-package cycles, and our suffix-fallback Go resolution could fake them.
-export function buildFileImportGraph(graph) {
+export function buildFileImportGraph(graph, { includeTypeOnly = false } = {}) {
   const fileIds = new Set();
   for (const n of graph.nodes || []) if (!String(n.id).includes("#")) fileIds.add(String(n.id));
-  const adj = new Map();
+  const runtimeAdj = new Map();       // runtime/value imports only
+  const allAdj = new Map();           // runtime + type-only, used to describe architectural coupling
   const edges = [];
+  const allEdges = [];
+  const typeOnlyEdges = [];
+  const runtimeSeen = new Set(), allSeen = new Set(), typeSeen = new Set();
+  const add = (map, a, b) => {
+    let set = map.get(a);
+    if (!set) map.set(a, (set = new Set()));
+    set.add(b);
+  };
   for (const l of graph.links || []) {
     if (l.relation !== "imports" && l.relation !== "re_exports") continue;
     const a = ep(l.source), b = ep(l.target);
     if (!fileIds.has(a) || !fileIds.has(b) || a === b) continue;
     if (a.endsWith(".go") && b.endsWith(".go") && dirOf(a) === dirOf(b)) continue;
-    let set = adj.get(a);
-    if (!set) adj.set(a, (set = new Set()));
-    if (!set.has(b)) { set.add(b); edges.push([a, b]); }
+    const key = `${a}\0${b}`;
+    if (!allSeen.has(key)) { allSeen.add(key); add(allAdj, a, b); allEdges.push([a, b]); }
+    if (l.typeOnly === true) {
+      if (!typeSeen.has(key)) { typeSeen.add(key); typeOnlyEdges.push([a, b]); }
+      continue;
+    }
+    if (!runtimeSeen.has(key)) { runtimeSeen.add(key); add(runtimeAdj, a, b); edges.push([a, b]); }
   }
-  return { fileIds, adj, edges };
+  const pureTypeOnlyEdges = typeOnlyEdges.filter(([a, b]) => !runtimeSeen.has(`${a}\0${b}`));
+  return {
+    fileIds,
+    adj: includeTypeOnly ? allAdj : runtimeAdj,
+    edges: includeTypeOnly ? allEdges : edges,
+    runtimeAdj,
+    runtimeEdges: edges,
+    allAdj,
+    allEdges,
+    typeOnlyEdges: pureTypeOnlyEdges,
+  };
 }
 
 // Iterative Tarjan (deep graphs must not blow the JS stack). Returns only non-trivial SCCs (size > 1).
@@ -147,7 +170,7 @@ const MAX_BOUNDARY_FINDINGS = 100;
 
 // Assemble everything into unified Findings. rules comes from the repo's .weavatrix-deps.json (optional).
 export function computeStructureFindings(graph, { rules = {}, entrySet = new Set(), externalImportFiles = new Set() } = {}) {
-  const { adj, edges } = buildFileImportGraph(graph);
+  const { adj, edges, allAdj, allEdges, typeOnlyEdges } = buildFileImportGraph(graph);
   const findings = [];
 
   const sccs = findSccs(adj).sort((a, b) => b.length - a.length);
@@ -167,6 +190,36 @@ export function computeStructureFindings(graph, { rules = {}, entrySet = new Set
       fixHint: "extract the shared code into a module both sides import, or invert the weaker dependency",
     }));
   }
+
+  // A TypeScript `import type` is erased before runtime. It can still reveal architectural coupling, but
+  // it cannot create an initialization-order/runtime cycle. Report SCCs that grow only because of type
+  // edges separately and at info severity so agents do not churn working code to fix a phantom hazard.
+  const runtimeKeys = new Set(sccs.map((s) => [...s].sort().join("\0")));
+  const allSccs = findSccs(allAdj).sort((a, b) => b.length - a.length);
+  const typeCouplings = allSccs.filter((s) => !runtimeKeys.has([...s].sort().join("\0")));
+  const edgeCountIn = (scc, list) => {
+    const inside = new Set(scc);
+    return list.reduce((n, [a, b]) => n + (inside.has(a) && inside.has(b) ? 1 : 0), 0);
+  };
+  for (const scc of typeCouplings.slice(0, MAX_CYCLE_FINDINGS)) {
+    const cycle = representativeCycle(allAdj, scc);
+    const runtimeInside = edgeCountIn(scc, edges);
+    const typeInside = edgeCountIn(scc, typeOnlyEdges);
+    const containsRuntimeCycle = sccs.some((runtime) => runtime.every((f) => scc.includes(f)));
+    findings.push(makeFinding({
+      category: "structure",
+      rule: "type-coupling",
+      severity: "info",
+      confidence: "high",
+      title: `${containsRuntimeCycle ? "Type imports expand dependency coupling" : "Type-induced dependency cycle (no runtime cycle)"}: ${scc.length} files`,
+      detail: `${cycle.join(" → ")}. This strongly-connected group needs type-only edges to close; it contains ${runtimeInside} runtime edge(s) and ${typeInside} type-only edge(s)${containsRuntimeCycle ? ", with a smaller runtime cycle reported separately" : ", while its runtime import graph is acyclic"}. Treat this as design coupling, not an initialization-order failure.`,
+      file: cycle[0],
+      graphNodeId: cycle[0],
+      evidence: cycle.map((f) => ({ file: f, line: 0, snippet: "" })),
+      source: "internal",
+      fixHint: "review the shared type ownership only if the coupling impedes changes; no runtime-cycle fix is required",
+    }));
+  }
   if (sccs.length > MAX_CYCLE_FINDINGS) {
     findings.push(makeFinding({
       category: "structure", rule: "circular-dep", severity: "info", confidence: "high",
@@ -190,6 +243,8 @@ export function computeStructureFindings(graph, { rules = {}, entrySet = new Set
     }));
   }
 
+  // Architecture boundaries describe executable dependencies by default. Type-only contract sharing is
+  // visible in typeCouplings above, but must not be presented as a runtime layer violation.
   const violations = checkBoundaries(edges, rules);
   for (const v of violations.slice(0, MAX_BOUNDARY_FINDINGS)) {
     findings.push(makeFinding({
@@ -216,6 +271,17 @@ export function computeStructureFindings(graph, { rules = {}, entrySet = new Set
 
   return {
     findings,
-    stats: { importEdges: edges.length, cycles: sccs.length, largestCycle: sccs[0]?.length || 0, orphans: findings.filter((f) => f.rule === "orphan-file").length, boundaryViolations: violations.length },
+    stats: {
+      importEdges: allEdges.length,
+      runtimeImportEdges: edges.length,
+      typeOnlyImportEdges: typeOnlyEdges.length,
+      cycles: sccs.length,
+      runtimeCycles: sccs.length,
+      largestCycle: sccs[0]?.length || 0,
+      typeCouplings: typeCouplings.length,
+      largestTypeCoupling: typeCouplings[0]?.length || 0,
+      orphans: findings.filter((f) => f.rule === "orphan-file").length,
+      boundaryViolations: violations.length,
+    },
   };
 }

package/src/analysis/duplicates.compute.js

@@ -1,9 +1,9 @@
 // duplicates.compute.js — fragment extraction, inverted-index pairing, and the computeDuplicates
 // pipeline (split from duplicates.js; see the facade there for the full algorithm overview).
-import { readFileSync, readdirSync } from "node:fs";
-import { join, extname } from "node:path";
+import { readFileSync } from "node:fs";
 import { isTestPath } from "../graph/graph-filter.js";
 import { createRepoBoundary } from "../repo-path.js";
+import { listRepoFiles } from "./internal-audit.collect.js";
 import { stripNonCode, bodyEndLineCount, tokenize, fingerprints, extractLargeStrings } from "./duplicates.tokenize.js";
 
 const FLOOR_TOKENS = 30;   // fragments below this never enter the index (UI slider min)
@@ -17,20 +17,7 @@ const WINDOW_EXTS = /\.(css|scss|sass|less|styl|html?|md|markdown|mdx|vue|svelte
 const WINDOW_LINES = 24;   // non-overlapping block size for windowed files
 // Asset files are DEDUP-ONLY — they are NOT put in the code graph (that would score md/css as fake
 // "methods" in Health and clutter the GUI board), so the clone scanner finds them by walking the repo.
-const WALK_SKIP = new Set(["node_modules", ".git", "dist", "build", "coverage", "vendor", "weavatrix-graphs", ".next", "out", "__pycache__", ".venv", "venv", "site-packages"]);
 const MAX_ASSET_FILES = 4000;
-function walkAssets(root, dir, acc, depth) {
-  if (depth > 40 || acc.length >= MAX_ASSET_FILES) return acc;
-  let entries; try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return acc; }
-  for (const e of entries) {
-    if (acc.length >= MAX_ASSET_FILES) break;
-    if (e.name.startsWith(".") || WALK_SKIP.has(e.name)) continue;
-    const full = join(dir, e.name);
-    if (e.isDirectory()) walkAssets(root, full, acc, depth + 1);
-    else if (WINDOW_EXTS.test(e.name)) acc.push(full.slice(root.length + 1).replace(/\\/g, "/"));
-  }
-  return acc;
-}
 // Fingerprints shared by MORE than this many fragments are ubiquitous boilerplate and are excluded
 // from BOTH the shared count AND the union (so jaccard stays honest — see pairsForMode). Set well
 // above realistic clone multiplicity: N byte-identical copies each put all their fingerprints in
@@ -55,7 +42,7 @@ function computeNameTwins(frags) {
   frags.forEach((f, i) => {
     if (f.kind === "string") return;
     const name = String(f.label || "").trim().replace(/\(\)$/, "");
-    if (name.length < 5 || !/^[A-Za-z_$][\w$]*$/.test(name) || TWIN_STOP.has(name.toLowerCase())) return;
+    if (name.length < 5 || !/^[A-Za-z_$][\w$]*$/.test(name) || TWIN_STOP.has(name.toLowerCase()) || /^do_(?:get|post|put|patch|delete|head|options)$/i.test(name)) return;
     const key = name.toLowerCase();
     let a = byName.get(key); if (!a) byName.set(key, (a = []));
     a.push(i);
@@ -66,15 +53,18 @@ function computeNameTwins(frags) {
     const files = new Set(idxs.map((i) => frags[i].file));
     if (files.size < 2 || idxs.length > 12) continue; // single-file overloads / framework-name explosions
     let simMin = 1, simMax = 0;
+    const pairs = [];
     for (let a = 0; a < idxs.length; a++) for (let b = a + 1; b < idxs.length; b++) {
       if (frags[idxs[a]].file === frags[idxs[b]].file) continue;
       const s = jac(frags[idxs[a]].fp.renamed, frags[idxs[b]].fp.renamed);
       if (s < simMin) simMin = s;
       if (s > simMax) simMax = s;
+      pairs.push({ a: idxs[a], b: idxs[b], similarity: Math.round(s * 100) });
     }
     out.push({
       label: String(frags[idxs[0]].label || "").replace(/\(\)$/, ""), members: idxs, files: files.size,
       simMin: Math.round(simMin * 100), simMax: Math.round(simMax * 100),
+      pairs,
       tokens: idxs.reduce((n, i) => n + frags[i].n, 0),
     });
   }
@@ -130,11 +120,14 @@ export function computeDuplicates(repoPath, graphJsonPath, opts = {}) {
   // total symbol nodes in the graph — 0 means a file-only graph (built by an older builder before
   // symbol extraction, or a stale graph): clone detection has nothing to work with, and the UI must
   // say "rebuild the graph" instead of the misleading "no clones at these thresholds".
+  const repoFiles = listRepoFiles(repoPath);
+  const allowedFiles = new Set(repoFiles);
   let graphSymbols = 0;
-  for (const arr of byFile.values()) graphSymbols += arr.length;
+  for (const [file, arr] of byFile) if (allowedFiles.has(file)) graphSymbols += arr.length;
   const frags = [];
   const boundary = createRepoBoundary(repoPath);
   for (const [file, syms] of byFile) {
+    if (!allowedFiles.has(file)) continue;
     const resolved = boundary.resolve(file);
     if (!resolved.ok) continue;
     const full = resolved.path;
@@ -195,7 +188,8 @@ export function computeDuplicates(repoPath, graphJsonPath, opts = {}) {
   // ---- windowed fragments for symbol-less file types (CSS/HTML/MD/…), found by walking the repo (NOT the
   // graph — assets are dedup-only). Each file is sliced into WINDOW_LINES blocks and fingerprinted.
   const symFiles = new Set(byFile.keys());
-  for (const file of walkAssets(repoPath, repoPath, [], 0)) {
+  const assetFiles = repoFiles.filter((file) => WINDOW_EXTS.test(file)).slice(0, MAX_ASSET_FILES);
+  for (const file of assetFiles) {
     if (symFiles.has(file)) continue;
     const resolved = boundary.resolve(file);
     if (!resolved.ok) continue;

package/src/analysis/endpoints.js

@@ -44,9 +44,27 @@ function handlerName(expr) {
 // endpoints (handler "operation", {id} params). These keys never appear in a real route/handler table.
 const OPENAPI_BLOCK = /\boperationId\b|\bresponses\s*:|\brequestBody\b|\bschemaRef\b|\boperation\s*\(|\bsummary\s*:/;
 
-const looksLikePath = (p) => typeof p === "string" && /^\/[\w\-./:{}*$]*$/.test(p) && !p.includes("://");
+const looksLikePath = (p) => typeof p === "string" && /^\/[\w\-./:{}*$?]*$/.test(p) && !p.includes("://");
 const cleanPath = (p) => String(p || "").replace(/\/+$/, "") || "/";
 
+export function nextRoutePath(file) {
+  const parts = String(file || "").replace(/\\/g, "/").split("/").filter(Boolean);
+  if (!/^route\.[cm]?[jt]s$/i.test(parts.at(-1) || "")) return "";
+  const appAt = parts.lastIndexOf("app");
+  if (appAt < 0) return "";
+  const route = [];
+  for (let segment of parts.slice(appAt + 1, -1)) {
+    if (!segment || /^\([^)]*\)$/.test(segment) || segment.startsWith("@")) continue; // route groups / parallel slots
+    segment = segment.replace(/^\((?:\.{1,3})\)/, "");                    // intercepting-route marker
+    let m;
+    if ((m = /^\[\[\.\.\.([^\]]+)\]\]$/.exec(segment))) segment = `*${m[1]}?`;
+    else if ((m = /^\[\.\.\.([^\]]+)\]$/.exec(segment))) segment = `*${m[1]}`;
+    else if ((m = /^\[([^\]]+)\]$/.exec(segment))) segment = `:${m[1]}`;
+    if (segment) route.push(segment);
+  }
+  return `/${route.join("/")}`;
+}
+
 export function extractEndpointsFromText(text, file) {
   const out = [];
   const py = /\.py$/i.test(file);
@@ -58,6 +76,31 @@ export function extractEndpointsFromText(text, file) {
     out.push({ method: m, path: p, handler: handlerName(expr), file, line: lineAt(text, idx) });
   };
 
+  // Next.js App Router: the filesystem provides the path and exported HTTP-method functions provide the
+  // verbs. No literal route string exists in route.ts, so generic Express/FastAPI regexes cannot see it.
+  const nextPath = nextRoutePath(file);
+  if (nextPath) {
+    const seen = new Set();
+    const direct = /\bexport\s+(?:(?:async|declare)\s+)*(?:function\s+|(?:const|let|var)\s+)(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS)\b/g;
+    let nm;
+    while ((nm = direct.exec(text))) {
+      const method = nm[1].toUpperCase();
+      if (!seen.has(method)) { seen.add(method); add(method, nextPath, method, nm.index); }
+    }
+    const lists = /\bexport\s*\{([^}]+)\}/g;
+    let lm;
+    while ((lm = lists.exec(text))) {
+      for (const item of lm[1].split(",")) {
+        const mm = /^\s*([A-Za-z_$][\w$]*)(?:\s+as\s+(GET|POST|PUT|PATCH|DELETE|HEAD|OPTIONS))?\s*$/.exec(item);
+        if (!mm) continue;
+        if (!mm[2] && !HTTP_METHODS.has(mm[1])) continue;
+        const method = String(mm[2] || mm[1]).toUpperCase();
+        if (!HTTP_METHODS.has(method)) continue;
+        if (!seen.has(method)) { seen.add(method); add(method, nextPath, mm[1], lm.index); }
+      }
+    }
+  }
+
   // ---- object routes: "/path": { GET: fn, POST: fn2 }  or  "/path": handler --------------------
   // find each  "…": {  or  "…": expr,  where the key looks like a path
   const objKeyRe = /(["'`])(\/[^"'`]*)\1\s*:\s*(\{)?/g;
@@ -132,7 +175,7 @@ export function detectEndpoints(repoPath, codeFiles) {
     const resolved = boundary.resolve(rel);
     if (!resolved.ok) continue;
     const text = safeRead(resolved.path);
-    if (!text || !/["'`]\/|\.(get|post|put|patch|delete)\s*\(|HandleFunc|@\w*\.?(get|post|put|patch|delete)/i.test(text)) continue;
+    if (!text || (!nextRoutePath(rel) && !/["'`]\/|\.(get|post|put|patch|delete)\s*\(|HandleFunc|@\w*\.?(get|post|put|patch|delete)/i.test(text))) continue;
     for (const e of extractEndpointsFromText(text, rel.replace(/\\/g, "/"))) {
       const key = `${e.method} ${normParamKey(e.path)}`;
       const prev = byKey.get(key);

package/src/analysis/graph-analysis.aggregate.js

@@ -100,21 +100,25 @@ export function aggregateGraph(graph, repoRoot) {
   for (const node of nodes) if (node.source_file) id2file.set(node.id, fileIdOf(node));
   const fileEdges = new Map(); // key → { count, rels:{relation→n} } so we can emit the DOMINANT relation (call/import/inherit)
   const moduleEdges = new Map();
+  const typeOnlyFileEdges = new Map();
+  const typeOnlyModuleEdges = new Map();
   for (const link of links) {
     if (link.relation === "contains") continue;
     const fromFile = id2file.get(endpoint(link.source));
     const toFile = id2file.get(endpoint(link.target));
     if (fromFile && toFile && fromFile !== toFile) {
       const key = `${fromFile} ${toFile}`;
-      let fe = fileEdges.get(key);
-      if (!fe) fileEdges.set(key, (fe = { count: 0, rels: {} }));
+      const targetFileEdges = link.typeOnly === true ? typeOnlyFileEdges : fileEdges;
+      let fe = targetFileEdges.get(key);
+      if (!fe) targetFileEdges.set(key, (fe = { count: 0, rels: {} }));
       fe.count++;
       if (link.relation) fe.rels[link.relation] = (fe.rels[link.relation] || 0) + 1;
       const fromMod = fileModule.get(fromFile);
       const toMod = fileModule.get(toFile);
       if (fromMod && toMod && fromMod !== toMod) {
         const mkey = `${fromMod} ${toMod}`;
-        moduleEdges.set(mkey, (moduleEdges.get(mkey) || 0) + 1);
+        const targetModuleEdges = link.typeOnly === true ? typeOnlyModuleEdges : moduleEdges;
+        targetModuleEdges.set(mkey, (targetModuleEdges.get(mkey) || 0) + 1);
       }
     }
   }
@@ -263,7 +267,9 @@ export function aggregateGraph(graph, repoRoot) {
       }))
       .sort((a, b) => b.fileCount - a.fileCount),
     moduleEdges: edgeList(moduleEdges),
+    typeOnlyModuleEdges: edgeList(typeOnlyModuleEdges),
     fileEdges: edgeList(fileEdges),
+    typeOnlyFileEdges: edgeList(typeOnlyFileEdges),
     symbols,
     symbolEdges,
     symbolRefs: [...new Set([...symbolLocalRefs.keys(), ...symbolExternalRefs.keys()])].map((id) => {
@@ -276,7 +282,9 @@ export function aggregateGraph(graph, repoRoot) {
       files: fileModule.size,
       nodes: nodes.filter((n) => n.file_type === "code").length,
       fileEdges: fileEdges.size,
+      typeOnlyFileEdges: typeOnlyFileEdges.size,
       moduleEdges: moduleEdges.size,
+      typeOnlyModuleEdges: typeOnlyModuleEdges.size,
       symbols: symbols.length,
       symbolEdges: symbolEdges.length
     }

package/src/analysis/internal-audit.collect.js

@@ -1,9 +1,11 @@
 // internal-audit.collect.js — filesystem collection helpers for the internal audit: source/config
 // text gathering, workspace package names, and the Python manifest reader. Split from internal-audit.js.
 import { readFileSync, readdirSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
+import { spawnSync } from "node:child_process";
 import { parseRequirementsNames, parsePyprojectDeps, parsePipfileDeps } from "./manifests.js";
 import { createRepoBoundary } from "../repo-path.js";
+import { childProcessEnv } from "../child-env.js";
 
 export const readText = (p) => { try { return readFileSync(p, "utf8"); } catch { return null; } };
 export const readJson = (p) => { try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; } };
@@ -18,10 +20,36 @@ export const readRepoJson = (boundary, relativePath) => {
 const SOURCE_EXT_RE = /\.(?:[cm]?[jt]sx?|py|go|vue|svelte)$/i;
 const SOURCE_SKIP_DIRS = new Set([
   ".git", ".hg", ".svn", "node_modules", "vendor", "dist", "build", "coverage", ".next", "out",
-  "weavatrix-graphs", "weavatrix-graphs", "__pycache__", ".venv", "venv", "env", ".tox", "site-packages",
+  "release", "weavatrix-graphs", "__pycache__", ".venv", "venv", "env", ".tox", "site-packages",
   ".mypy_cache", ".pytest_cache",
 ]);
 
+// One file universe for every filesystem-backed audit. In Git repos this exactly matches tracked files
+// plus untracked/non-ignored work, so release bundles and other .gitignore outputs cannot re-enter through
+// text/config/manifest fallback collectors after the graph builder correctly omitted them.
+export function listRepoFiles(repoRoot) {
+  try {
+    const r = spawnSync("git", ["-C", repoRoot, "ls-files", "--cached", "--others", "--exclude-standard", "-z"], {
+      encoding: "utf8", windowsHide: true, timeout: 15_000, maxBuffer: 32 * 1024 * 1024,
+      env: childProcessEnv(),
+    });
+    if (r.status === 0) return String(r.stdout || "").split("\0").filter(Boolean).map((f) => f.replace(/\\/g, "/"));
+  } catch { /* non-Git repo or git unavailable: use the bounded walker below */ }
+
+  const files = [];
+  const walk = (abs, parts = []) => {
+    let entries = [];
+    try { entries = readdirSync(abs, { withFileTypes: true }); } catch { return; }
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        if (!SOURCE_SKIP_DIRS.has(entry.name)) walk(join(abs, entry.name), [...parts, entry.name]);
+      } else if (entry.isFile()) files.push([...parts, entry.name].join("/"));
+    }
+  };
+  walk(repoRoot);
+  return files;
+}
+
 export function collectSourceTexts(repoRoot, graph) {
   const sources = new Map();
   const boundary = createRepoBoundary(repoRoot);
@@ -36,19 +64,7 @@ export function collectSourceTexts(repoRoot, graph) {
 
   for (const n of graph.nodes || []) add(n.source_file);
 
-  const walk = (abs, parts = []) => {
-    let entries = [];
-    try { entries = readdirSync(abs, { withFileTypes: true }); } catch { return; }
-    for (const entry of entries) {
-      if (entry.isDirectory()) {
-        if (!SOURCE_SKIP_DIRS.has(entry.name)) walk(join(abs, entry.name), [...parts, entry.name]);
-        continue;
-      }
-      if (!entry.isFile() || !SOURCE_EXT_RE.test(entry.name)) continue;
-      add([...parts, entry.name].join("/"));
-    }
-  };
-  walk(repoRoot);
+  for (const file of listRepoFiles(repoRoot)) if (SOURCE_EXT_RE.test(file)) add(file);
   return sources;
 }
 
@@ -62,7 +78,8 @@ const CONFIG_FILES = [
   "jest.config.js", "jest.config.ts", "jest.config.cjs", "jest.config.mjs",
   "vite.config.js", "vite.config.ts", "vite.config.mjs", "vitest.config.js", "vitest.config.ts",
   "webpack.config.js", "rollup.config.js", "esbuild.config.js",
-  "postcss.config.js", "postcss.config.cjs", "tailwind.config.js", "tailwind.config.ts",
+  "postcss.config.js", "postcss.config.cjs", "postcss.config.mjs", "postcss.config.ts",
+  "tailwind.config.js", "tailwind.config.cjs", "tailwind.config.mjs", "tailwind.config.ts",
   ".prettierrc", ".prettierrc.json", "prettier.config.js",
   "playwright.config.js", "playwright.config.ts", "cypress.config.js", "cypress.config.ts",
   "next.config.js", "next.config.mjs", "nuxt.config.ts", "svelte.config.js", "astro.config.mjs",
@@ -76,17 +93,96 @@ const CONFIG_FILES = [
 export function collectConfigTexts(repoRoot) {
   const map = new Map();
   const boundary = createRepoBoundary(repoRoot);
-  for (const f of CONFIG_FILES) { const t = readRepoText(boundary, f); if (t != null) map.set(f, t); }
+  const names = new Set(CONFIG_FILES.map((f) => f.toLowerCase()));
+  for (const f of listRepoFiles(repoRoot)) {
+    const base = f.slice(f.lastIndexOf("/") + 1).toLowerCase();
+    if (!names.has(base) && !/^\.github\/workflows\/.*\.ya?ml$/i.test(f)) continue;
+    const t = readRepoText(boundary, f);
+    if (t != null) map.set(f, t);
+  }
+  return map;
+}
+
+function readJsonc(text) {
+  if (text == null) return null;
   try {
-    const workflows = boundary.resolve(".github/workflows");
-    if (!workflows.ok) throw new Error("workflows directory is outside the repository");
-    for (const wf of readdirSync(workflows.path)) {
-      if (!/\.ya?ml$/i.test(wf)) continue;
-      const t = readRepoText(boundary, `.github/workflows/${wf}`);
-      if (t != null) map.set(`.github/workflows/${wf}`, t);
+    const input = String(text).replace(/^\uFEFF/, "");
+    let clean = "", inString = false, escaped = false;
+    for (let i = 0; i < input.length; i++) {
+      const ch = input[i], next = input[i + 1];
+      if (inString) {
+        clean += ch;
+        if (escaped) escaped = false;
+        else if (ch === "\\") escaped = true;
+        else if (ch === '"') inString = false;
+        continue;
+      }
+      if (ch === '"') { inString = true; clean += ch; continue; }
+      if (ch === "/" && next === "/") {
+        while (i < input.length && input[i] !== "\n") i++;
+        clean += "\n";
+        continue;
+      }
+      if (ch === "/" && next === "*") {
+        i += 2;
+        while (i < input.length && !(input[i] === "*" && input[i + 1] === "/")) i++;
+        i++;
+        continue;
+      }
+      clean += ch;
     }
-  } catch { /* no workflows */ }
-  return map;
+    clean = clean.replace(/,\s*([}\]])/g, "$1");
+    return JSON.parse(clean);
+  } catch { return null; }
+}
+
+const normRoot = (root) => {
+  const value = String(root || "").replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+|\/+$/g, "");
+  return value === "." ? "" : value;
+};
+const inScope = (file, root) => !root || file === root || file.startsWith(`${root}/`);
+
+function aliasesForScope(repoRoot, root, files, boundary, scopeRoots) {
+  const ownerOf = (file) => scopeRoots.find((candidate) => inScope(file, candidate)) ?? "";
+  const configs = files
+    .filter((f) => ownerOf(f) === root && /(^|\/)(?:tsconfig|jsconfig)(?:\.[^/]+)?\.json$/i.test(f))
+    .filter((f) => normRoot(dirname(f)) === root)
+    .sort((a, b) => Number(!/(^|\/)(?:tsconfig|jsconfig)\.json$/i.test(a)) - Number(!/(^|\/)(?:tsconfig|jsconfig)\.json$/i.test(b)) || a.localeCompare(b));
+  const aliases = new Map();
+  for (const config of configs) {
+    const cfg = readJsonc(readRepoText(boundary, config));
+    const paths = cfg?.compilerOptions?.paths || {};
+    for (const key of Object.keys(paths)) if (!aliases.has(key)) aliases.set(key, {
+      key,
+      prefix: String(key).replace(/\*.*$/, ""),
+      suffix: String(key).includes("*") ? String(key).slice(String(key).indexOf("*") + 1) : "",
+      config,
+    });
+  }
+  return [...aliases.values()];
+}
+
+// Every package.json defines a dependency scope. The nearest ancestor manifest owns an import, matching
+// npm workspace/package semantics. Aliases are collected from that scope's tsconfig/jsconfig so `@/*`
+// remains local rather than becoming a phantom npm package.
+export function collectPackageScopes(repoRoot, rootPkg = null) {
+  const boundary = createRepoBoundary(repoRoot);
+  const files = listRepoFiles(repoRoot);
+  const manifests = files.filter((f) => /(^|\/)package\.json$/i.test(f));
+  if (!manifests.includes("package.json") && rootPkg) manifests.unshift("package.json");
+  const uniqueManifests = [...new Set(manifests)];
+  const scopeRoots = uniqueManifests
+    .map((manifest) => manifest === "package.json" ? "" : normRoot(dirname(manifest)))
+    .sort((a, b) => b.length - a.length);
+  const scopes = [];
+  for (const manifest of uniqueManifests) {
+    const root = manifest === "package.json" ? "" : normRoot(dirname(manifest));
+    const pkg = manifest === "package.json" && rootPkg ? rootPkg : readRepoJson(boundary, manifest);
+    if (!pkg || typeof pkg !== "object") continue;
+    scopes.push({ root, manifest, pkg, aliases: aliasesForScope(repoRoot, root, files, boundary, scopeRoots) });
+  }
+  if (!scopes.some((s) => !s.root)) scopes.push({ root: "", manifest: "package.json", pkg: rootPkg || {}, aliases: aliasesForScope(repoRoot, "", files, boundary, [...scopeRoots, ""]) });
+  return scopes.sort((a, b) => b.root.length - a.root.length);
 }
 
 // Monorepo-local package names: "packages/*"-style workspace globs → each child's package.json name.
@@ -111,6 +207,7 @@ export function workspacePkgNames(repoRoot, pkg) {
       if (p && p.name) names.add(p.name);
     }
   }
+  for (const scope of collectPackageScopes(repoRoot, pkg)) if (scope.pkg?.name) names.add(scope.pkg.name);
   return names;
 }
 

package/src/analysis/internal-audit.reach.js

@@ -1,6 +1,7 @@
 // internal-audit.reach.js — entry-point discovery + file-level reachability BFS for the internal
 // audit. Split from internal-audit.js.
-import { ENTRY_FILE } from "./dead-check.js";
+import { posix } from "node:path";
+import { ENTRY_FILE, isFrameworkEntryFile } from "./dead-check.js";
 import { TEST_FILE_RE } from "./internal-audit.collect.js";
 
 const isFileNode = (n) => !String(n.id).includes("#");
@@ -8,20 +9,60 @@ const isFileNode = (n) => !String(n.id).includes("#");
 // Entry set for reachability: conventional entry names + package.json main/module/browser/bin/exports +
 // html pages (they root classic-script apps) + test files (the runner enters them) + root config files +
 // dynamic-import targets. Anything reachable from here is "used"; the rest corroborates unused-file.
-export function entryFiles(graph, pkg, dynamicTargets) {
+export function entryFiles(graph, pkgOrScopes, dynamicTargets = new Set(), { declaredEntries = [], sources = new Map() } = {}) {
   const entries = new Set();
-  const pkgEntries = [];
-  for (const k of ["main", "module", "browser"]) if (typeof pkg[k] === "string") pkgEntries.push(pkg[k]);
-  if (pkg.bin) pkgEntries.push(...(typeof pkg.bin === "string" ? [pkg.bin] : Object.values(pkg.bin)));
-  (function walkExports(e) {
-    if (typeof e === "string") pkgEntries.push(e);
-    else if (e && typeof e === "object") Object.values(e).forEach(walkExports);
-  })(pkg.exports);
-  const pe = new Set(pkgEntries.map((p) => String(p).replace(/^\.\//, "").replace(/\\/g, "/")));
+  const scopes = Array.isArray(pkgOrScopes)
+    ? pkgOrScopes
+    : [{ root: "", manifest: "package.json", pkg: pkgOrScopes || {} }];
+  const fileSet = new Set((graph.nodes || []).filter(isFileNode).map((n) => String(n.source_file || n.id).replace(/\\/g, "/")));
+  const pe = new Set();
+  const resolveEntry = (root, raw) => {
+    let p = String(raw || "").trim().replace(/^['"]|['"]$/g, "").replace(/^file:/, "").replace(/\\/g, "/");
+    if (!p || p.startsWith("-") || /^https?:/.test(p)) return "";
+    p = p.replace(/^\.\//, "");
+    const joined = posix.normalize(root ? posix.join(root, p) : p).replace(/^\.\//, "");
+    if (fileSet.has(joined)) return joined;
+    for (const ext of [".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx", ".py"]) if (fileSet.has(joined + ext)) return joined + ext;
+    return joined;
+  };
+  for (const scope of scopes) {
+    const pkg = scope.pkg || {};
+    const root = String(scope.root || "").replace(/\\/g, "/").replace(/^\/+|\/+$/g, "");
+    const pkgEntries = [];
+    for (const k of ["main", "module", "browser"]) if (typeof pkg[k] === "string") pkgEntries.push(pkg[k]);
+    if (pkg.bin) pkgEntries.push(...(typeof pkg.bin === "string" ? [pkg.bin] : Object.values(pkg.bin)));
+    (function walkExports(e) {
+      if (typeof e === "string") pkgEntries.push(e);
+      else if (e && typeof e === "object") Object.values(e).forEach(walkExports);
+    })(pkg.exports);
+    // Script commands are external entry surfaces. Extract only path-shaped source tokens; package names,
+    // flags and shell operators are intentionally ignored.
+    for (const script of Object.values(pkg.scripts || {})) {
+      const re = /(?:^|[\s'"=])((?:\.?\.?\/)?[\w@./-]+\.(?:[cm]?[jt]sx?|py|go))(?=$|[\s'";,)&|])/gi;
+      let m;
+      while ((m = re.exec(String(script)))) pkgEntries.push(m[1]);
+      const runner = /\b(?:node|bun|deno|tsx|ts-node|python\d*|electron)\s+(?!-)([\w@./\\-]+)/gi;
+      while ((m = runner.exec(String(script)))) if (/[./\\]/.test(m[1])) pkgEntries.push(m[1]);
+    }
+    for (const p of pkgEntries) pe.add(resolveEntry(root, p));
+  }
   for (const n of graph.nodes || []) {
     if (!isFileNode(n)) continue;
     const f = n.source_file;
-    if (ENTRY_FILE.test(f) || TEST_FILE_RE.test(f) || /\.html?$/i.test(f) || pe.has(f) || /(^|\/)[^/]*\.config\.[a-z]+$/i.test(f)) entries.add(f);
+    if (ENTRY_FILE.test(f) || isFrameworkEntryFile(f) || /\.d\.[cm]?ts$/i.test(f) || TEST_FILE_RE.test(f) || /\.html?$/i.test(f) || pe.has(f) || /(^|\/)[^/]*\.config\.[a-z]+$/i.test(f)) entries.add(f);
+  }
+  for (const raw of Array.isArray(declaredEntries) ? declaredEntries : [declaredEntries]) {
+    const resolved = resolveEntry("", raw);
+    if (resolved && fileSet.has(resolved)) entries.add(resolved);
+  }
+  // Bundled helper programs are often launched by filename (`resolveResource("worker.py")`) rather than
+  // imported. A quoted basename reference from another source file is enough to establish that a code file
+  // under resources/ is a runtime entry, without treating arbitrary prose/config files as roots.
+  for (const file of fileSet) {
+    if (!/(^|\/)resources\/.*\.(?:py|[cm]?[jt]s)$/i.test(file)) continue;
+    const base = posix.basename(file).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const quoted = new RegExp(`["'\x60]${base}["'\x60]`);
+    if ([...sources].some(([other, text]) => other !== file && quoted.test(String(text || "")))) entries.add(file);
   }
   for (const t of dynamicTargets) entries.add(t);
   return entries;