weavatrix 0.1.3 → 0.2.0

package/src/analysis/dead-check.js

@@ -8,18 +8,25 @@
 import { readFileSync } from "node:fs";
 import { posix } from "node:path";
 import { createRepoBoundary } from "../repo-path.js";
+import { isStructuralRelation } from "../graph/relations.js";
+import { createPathClassifier, hasPathClass } from "../path-classification.js";
 
 const IDENT_RE = /[A-Za-z_$][\w$]*/g;
 const bareName = (label) => String(label || "").replace(/\s*\(.*$/, "").replace(/[()]/g, "").trim();
 // entry surfaces are never dead even with no inbound edge (framework/CLI/HTTP enter them externally).
 // Exported for internal-audit.js (reachability entry set) — keep the two in lockstep.
 export const ENTRY_FILE = /(^|[\\/])(index|main|app|server|cli|cmd|bootstrap|entry|run|__main__|manage|wsgi|asgi|setup|conftest)\.[a-z0-9]+$|(^|[\\/])(bin|cmd)[\\/]|(^|[\\/])main\.go$/i;
-const TEST_FILE = /(^|[\\/])[^\\/]*[._-](test|spec)\.[a-z0-9]+$|(^|[\\/])(test|tests|__tests__|spec)[\\/]/i;
+const defaultPathClassifier = createPathClassifier(null);
+const isTestFile = (file) => hasPathClass(defaultPathClassifier.explain(file), "test", "e2e");
 
 // Framework-owned entry modules are invoked by convention rather than a source import. Keep this narrow:
 // these are Next.js App/Pages Router surfaces and framework metadata files, not every file under `app/`.
 export const NEXT_ENTRY_FILE = /(^|\/)(?:src\/)?app\/(?:.*\/)?(?:page|layout|template|loading|error|global-error|not-found|default|route|robots|sitemap|manifest|opengraph-image|twitter-image|icon|apple-icon)\.[cm]?[jt]sx?$|(^|\/)(?:src\/)?pages\/(?!.*\/(?:components?|lib|utils?)\/).+\.[cm]?[jt]sx?$|(^|\/)(?:middleware|instrumentation)\.[cm]?[jt]s$/i;
-export const isFrameworkEntryFile = (file) => NEXT_ENTRY_FILE.test(String(file || "").replace(/\\/g, "/"));
+export const RUST_ENTRY_FILE = /(^|\/)(?:build\.rs|src\/(?:lib|main)\.rs)$/i;
+export const isFrameworkEntryFile = (file) => {
+  const normalized = String(file || "").replace(/\\/g, "/");
+  return NEXT_ENTRY_FILE.test(normalized) || RUST_ENTRY_FILE.test(normalized);
+};
 
 const lineOfNode = (n) => {
   const m = /@(\d+)$/.exec(String(n.id || "")) || /L(\d+)/.exec(String(n.source_location || ""));
@@ -93,7 +100,7 @@ export function computeDead(graph, sources, { entrySet = new Set() } = {}) {
   const nodes = graph.nodes || [], links = graph.links || [];
   const ep = (v) => (v && typeof v === "object" ? v.id : v);
   const inbound = new Set();
-  for (const l of links) if (l.relation !== "contains") inbound.add(ep(l.target));
+  for (const l of links) if (!isStructuralRelation(l.relation)) inbound.add(ep(l.target));
 
   // whole-repo identifier frequency: a symbol whose name appears MORE than once total (its definition + at least
   // one use, same-file OR cross-file) is referenced. Errs toward "alive" (common-named symbols never flagged).
@@ -139,7 +146,7 @@ export function computeDead(graph, sources, { entrySet = new Set() } = {}) {
   const deadSymbols = [];
   for (const n of symById.values()) {
     if (isReferenced(n)) continue;
-    const test = TEST_FILE.test(n.source_file);
+    const test = isTestFile(n.source_file);
     deadSymbols.push({ id: n.id, file: n.source_file, label: n.label, test, reason: "no inbound edge and name unreferenced outside its file" });
   }
   const deadSet = new Set(deadSymbols.map((s) => s.id));
@@ -168,7 +175,7 @@ export function computeUnusedExports(graph, sources, { dynamicTargets = new Set(
   const nodes = graph.nodes || [], links = graph.links || [];
   const ep = (v) => (v && typeof v === "object" ? v.id : v);
   const inbound = new Set();
-  for (const l of links) if (l.relation !== "contains") inbound.add(ep(l.target));
+  for (const l of links) if (!isStructuralRelation(l.relation)) inbound.add(ep(l.target));
 
   const namespaceConsumed = namespaceConsumedFiles(sources, graph);
   const candidates = [];
@@ -197,7 +204,7 @@ export function computeUnusedExports(graph, sources, { dynamicTargets = new Set(
   for (const { n, nm } of candidates) {
     const occ = occursIn.get(nm);
     if (occ && [...occ].some((f) => f !== n.source_file)) continue; // referenced beyond its own file → alive
-    out.push({ id: n.id, file: n.source_file, label: n.label, test: TEST_FILE.test(n.source_file), reason: "exported but never imported or referenced outside its own file" });
+    out.push({ id: n.id, file: n.source_file, label: n.label, test: isTestFile(n.source_file), reason: "exported but never imported or referenced outside its own file" });
   }
   return out;
 }

package/src/analysis/dead-code-review.js

@@ -0,0 +1,245 @@
+// Conservative, source-free review queue for statically unreferenced code. This deliberately builds
+// on computeDead instead of inventing a second liveness model. Candidates are evidence for review,
+// never deletion instructions: framework entry, dynamic loading, reflection and public API surfaces
+// lower confidence and remain explicit in the returned record.
+import { computeDead, isFrameworkEntryFile } from "./dead-check.js";
+import { createPathClassifier, hasPathClass } from "../path-classification.js";
+
+const CONFIDENCE_RANK = Object.freeze({ high: 0, medium: 1, low: 2 });
+const CLASSIFIED_NON_PRODUCT = Object.freeze(["generated", "mock", "story", "docs", "benchmark", "temp"]);
+const DYNAMIC_RE = /(?:\bimport\s*\(|\brequire\s*\(\s*(?!["'])|\bcreateRequire\s*\(|\b__import__\s*\(|\bimportlib\.|(?:^|[^\w.$])(?:eval|exec)\s*\()/m;
+const REFLECTION_RE = /(?:\b(?:Class\.forName|get(?:Declared)?Method|getattr|setattr|hasattr|Method\.Invoke|GetMethod|GetProcAddress|dlsym)\s*\(|\b(?:globals|locals)\s*\(\s*\)\s*\[|\breflect\.[A-Za-z_$][\w$]*\s*\()/i;
+
+const normalizedPath = (value) => String(value || "").replace(/\\/g, "/").replace(/^\.\//, "");
+const lineOf = (node) => {
+  const match = /@(\d+)$/.exec(String(node?.id || "")) || /L(\d+)/.exec(String(node?.source_location || ""));
+  return match ? Number(match[1]) : 0;
+};
+const bareLabel = (value) => String(value || "").replace(/\s*\(.*$/, "").replace(/[()]/g, "").trim();
+
+function kindOf(node) {
+  const symbolKind = String(node?.symbol_kind || "").toLowerCase();
+  if (symbolKind === "method" || symbolKind === "constructor") return "method";
+  if (["function", "function_definition", "func", "fn"].includes(symbolKind)) return "function";
+  // Old graphs may not retain symbol_kind. Only use call syntax as a compatibility fallback;
+  // member_of alone also describes fields and must never promote them to methods.
+  if (!symbolKind && /\([^)]*\)\s*$/.test(String(node?.label || ""))) return node?.member_of ? "method" : "function";
+  return "symbol";
+}
+
+function isPublicSurface(node) {
+  const visibility = String(node?.visibility || "").toLowerCase();
+  return node?.exported === true || visibility === "public" || visibility === "protected";
+}
+
+function pathAllowed(info, { includeTests, includeClassified }) {
+  if (!includeTests && hasPathClass(info, "test", "e2e")) return { ok: false, bucket: "tests" };
+  if (!includeClassified && (info?.excluded || hasPathClass(info, ...CLASSIFIED_NON_PRODUCT))) {
+    return { ok: false, bucket: "classified" };
+  }
+  return { ok: true };
+}
+
+function symbolCandidate(item, node, context) {
+  const file = normalizedPath(item.file);
+  const source = String(context.sources.get(file) || "");
+  const pathInfo = context.classify(file, source);
+  const publicSurface = isPublicSurface(node);
+  const externalEntry = context.entrySet.has(file) || isFrameworkEntryFile(file);
+  const framework = context.frameworkByFile.get(file) || null;
+  const dynamicFile = context.dynamicTargets.has(file) || DYNAMIC_RE.test(source);
+  const reflectionFile = REFLECTION_RE.test(source);
+  const kind = kindOf(node);
+  let confidence = (String(node?.visibility || "").toLowerCase() === "private" || (!publicSurface && ["method", "function"].includes(kind)))
+    ? "high" : "medium";
+  const caveats = [];
+
+  if (publicSurface) {
+    confidence = "low";
+    caveats.push("Public/exported APIs can be consumed by downstream packages, interfaces, reflection, dependency injection, templates, or configuration outside this repository.");
+  }
+  if (externalEntry || framework) {
+    confidence = "low";
+    caveats.push(framework?.reason || "This file is an externally entered or framework-owned surface; static inbound edges are not complete usage evidence.");
+  }
+  if (node?.decorated) {
+    confidence = "low";
+    caveats.push("Decorators/annotations can register this symbol without a direct caller.");
+  }
+  if (dynamicFile) {
+    confidence = "low";
+    caveats.push("The declaring file uses or is reached through dynamic loading, so the static graph can miss callers.");
+  }
+  if (reflectionFile || (publicSurface && context.repoSignals.reflection)) {
+    confidence = "low";
+    caveats.push("Reflection is present and may invoke names without a resolvable static edge.");
+  }
+
+  return {
+    id: String(item.id),
+    kind,
+    classification: publicSurface ? `public-${kind}` : kind === "method" ? "internal-method" : kind === "function" ? "internal-function" : "unreferenced-symbol",
+    file,
+    line: lineOf(node),
+    symbol: bareLabel(node?.label || item.label),
+    owner: node?.member_of || null,
+    symbolKind: node?.symbol_kind || null,
+    visibility: node?.visibility || (node?.exported ? "exported" : "internal"),
+    confidence,
+    reason: item.reason,
+    evidence: [
+      { kind: "graph", fact: "No inbound non-structural graph edge targets this symbol." },
+      { kind: "source-index", fact: "Its identifier has no second indexed occurrence that establishes a caller." },
+    ],
+    caveats,
+    publicApi: publicSurface,
+    externallyEnteredFile: externalEntry,
+    pathClasses: pathInfo.classes || [],
+    matchedPathRule: pathInfo.matchedRule || null,
+    reviewAction: "Confirm with read_source, get_dependents, exact search, framework/config inspection and tests; never auto-delete.",
+  };
+}
+
+function fileCandidate(item, symbols, context) {
+  const file = normalizedPath(item.file);
+  const source = String(context.sources.get(file) || "");
+  const pathInfo = context.classify(file, source);
+  const publicSymbols = symbols.filter((symbol) => symbol.publicApi);
+  const dynamicFile = context.dynamicTargets.has(file) || DYNAMIC_RE.test(source);
+  const reflectionFile = REFLECTION_RE.test(source);
+  // Whole-file liveness always remains at most medium: external launchers/manifests can exist outside
+  // the indexed import graph even when every internal symbol signal is otherwise strong.
+  let confidence = "medium";
+  const caveats = ["Files can be launched by scripts, plugins, manifests, framework conventions, generated consumers, or external tooling without an import edge."];
+  if (publicSymbols.length) {
+    confidence = "low";
+    caveats.push(`${publicSymbols.length} indexed public/exported symbol(s) may be consumed outside this repository.`);
+  }
+  if (dynamicFile) {
+    confidence = "low";
+    caveats.push("Dynamic loading is present in or targets this file.");
+  }
+  if (reflectionFile) {
+    confidence = "low";
+    caveats.push("Reflection is present in this file.");
+  }
+  return {
+    id: `file:${file}`,
+    kind: "file",
+    classification: "unreferenced-file",
+    file,
+    line: 1,
+    symbol: null,
+    owner: null,
+    symbolKind: null,
+    visibility: null,
+    confidence,
+    reason: item.reason,
+    evidence: [
+      { kind: "graph", fact: "No indexed module imports this file." },
+      { kind: "symbol-liveness", fact: "Every indexed symbol in the file is statically unreferenced." },
+    ],
+    caveats,
+    publicApi: publicSymbols.length > 0,
+    externallyEnteredFile: false,
+    pathClasses: pathInfo.classes || [],
+    matchedPathRule: pathInfo.matchedRule || null,
+    reviewAction: "Verify package scripts, manifests, framework discovery, dynamic loading and external consumers; never auto-delete.",
+  };
+}
+
+// Pure review model. Filesystem collection/entry inference stays in the MCP adapter so tests can pass
+// exact source maps and convention evidence without touching the working tree.
+export function computeDeadCodeReview(graph, sources, options = {}) {
+  const entrySet = options.entrySet instanceof Set ? options.entrySet : new Set(options.entrySet || []);
+  const dynamicTargets = options.dynamicTargets instanceof Set ? options.dynamicTargets : new Set(options.dynamicTargets || []);
+  const frameworkByFile = new Map((options.frameworkEvidence || []).map((entry) => [normalizedPath(entry.file), entry]));
+  const classifier = options.pathClassifier || createPathClassifier(null);
+  const classificationCache = new Map();
+  const classify = (file, source) => {
+    if (!classificationCache.has(file)) classificationCache.set(file, classifier.explain(file, { content: source }));
+    return classificationCache.get(file);
+  };
+  const repoSignals = {
+    dynamicLoading: (graph.externalImports || []).some((entry) => entry?.dynamic) || [...sources.values()].some((text) => DYNAMIC_RE.test(String(text || ""))),
+    reflection: [...sources.values()].some((text) => REFLECTION_RE.test(String(text || ""))),
+  };
+  const includeTests = options.includeTests === true;
+  const includeClassified = options.includeClassified === true;
+  const minConfidence = Object.hasOwn(CONFIDENCE_RANK, options.minConfidence) ? options.minConfidence : "medium";
+  const pathPrefix = normalizedPath(options.path || "").replace(/\/+$/, "");
+  const requestedKinds = new Set(Array.isArray(options.kinds) && options.kinds.length ? options.kinds : ["file", "function", "method", "symbol"]);
+  const context = { sources, entrySet, dynamicTargets, frameworkByFile, classify, repoSignals };
+  const dead = computeDead(graph, sources, { entrySet });
+  const nodesById = new Map((graph.nodes || []).map((node) => [String(node.id), node]));
+  const rawSymbols = dead.deadSymbols
+    .map((item) => ({ item, node: nodesById.get(String(item.id)) }))
+    .filter((entry) => entry.node)
+    .map(({ item, node }) => symbolCandidate(item, node, context));
+  const symbolsByFile = new Map();
+  for (const candidate of rawSymbols) {
+    if (!symbolsByFile.has(candidate.file)) symbolsByFile.set(candidate.file, []);
+    symbolsByFile.get(candidate.file).push(candidate);
+  }
+  const rawFiles = dead.deadFiles.map((item) => fileCandidate(item, symbolsByFile.get(normalizedPath(item.file)) || [], context));
+  const raw = [...rawSymbols, ...rawFiles];
+  const suppressed = { tests: 0, classified: 0, confidence: 0, path: 0, kind: 0 };
+  const candidates = [];
+  for (const candidate of raw) {
+    const info = classify(candidate.file, sources.get(candidate.file));
+    const allowed = pathAllowed(info, { includeTests, includeClassified });
+    if (!allowed.ok) { suppressed[allowed.bucket] += 1; continue; }
+    if (pathPrefix && candidate.file !== pathPrefix && !candidate.file.startsWith(`${pathPrefix}/`)) { suppressed.path += 1; continue; }
+    if (!requestedKinds.has(candidate.kind)) { suppressed.kind += 1; continue; }
+    if (CONFIDENCE_RANK[candidate.confidence] > CONFIDENCE_RANK[minConfidence]) { suppressed.confidence += 1; continue; }
+    candidates.push(candidate);
+  }
+  candidates.sort((left, right) =>
+    CONFIDENCE_RANK[left.confidence] - CONFIDENCE_RANK[right.confidence]
+    || left.file.localeCompare(right.file)
+    || left.line - right.line
+    || left.id.localeCompare(right.id));
+
+  const warnings = [{
+    code: "STATIC_LIVENESS_IS_NOT_RUNTIME_PROOF",
+    message: "No static reference is not proof of dead runtime code. Review every candidate; never bulk-delete or auto-delete.",
+  }];
+  if (repoSignals.dynamicLoading) warnings.push({
+    code: "DYNAMIC_LOADING_PRESENT",
+    message: "Dynamic loading exists in the repository; static callers may be incomplete.",
+  });
+  if (repoSignals.reflection) warnings.push({
+    code: "REFLECTION_PRESENT",
+    message: "Reflection-like APIs exist in the repository; public or name-addressed symbols may be invoked without graph edges.",
+  });
+  if (suppressed.confidence) warnings.push({
+    code: "LOW_CONFIDENCE_SUPPRESSED",
+    message: `${suppressed.confidence} low-confidence candidate(s), including public/framework-sensitive code, were suppressed; set min_confidence=low to review them explicitly.`,
+  });
+
+  return {
+    candidates,
+    warnings,
+    suppressed,
+    repoSignals,
+    totals: {
+      indexedSymbols: dead.stats.symbols,
+      indexedFiles: dead.stats.files,
+      rawDeadSymbols: rawSymbols.length,
+      rawDeadFiles: rawFiles.length,
+      reviewCandidates: candidates.length,
+      byConfidence: {
+        high: candidates.filter((candidate) => candidate.confidence === "high").length,
+        medium: candidates.filter((candidate) => candidate.confidence === "medium").length,
+        low: candidates.filter((candidate) => candidate.confidence === "low").length,
+      },
+    },
+    policy: {
+      verdict: "REVIEW_REQUIRED",
+      autoDelete: false,
+      minConfidence,
+      includeTests,
+      includeClassified,
+    },
+  };
+}

package/src/analysis/dep-check-ecosystems.js

@@ -0,0 +1,163 @@
+import { makeFinding } from "./findings.js";
+
+const TEST_PATH_RE = /(^|[/\\])(test|tests|__tests__|spec|e2e|__mocks__)([/\\]|$)|[._-](test|spec)\.[a-z0-9]+$|_test\.go$/i;
+const escRe = (s) => String(s).replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const mentioned = (blob, name) => new RegExp(`(^|[^\\w@.-])${escRe(name)}($|[^\\w.-])`).test(blob);
+
+// ---- Go: set math over ecosystem:"Go" externalImports vs go.mod requires ----
+// goMod = parseGoMod() output. Only DIRECT requires can be "unused" (indirect ones belong to `go mod
+// tidy`); replace targets and the own module never count. Missing = imported module with no require
+// prefix — rare in Go (builds fail), so it usually flags vendored/replaced setups: keep it medium.
+export function computeGoDepFindings({ externalImports = [], goMod = null, nonRuntimeRoots = [] } = {}) {
+  const findings = [];
+  if (!goMod || !goMod.module) return { findings, declared: new Set() };
+  const requires = goMod.requires || [];
+  const declared = new Set(requires.map((r) => r.path));
+  const replaced = new Set((goMod.replaces || []).map((r) => r.from));
+  const moduleOf = (spec) => { let best = ""; for (const p of declared) if ((spec === p || spec.startsWith(p + "/")) && p.length > best.length) best = p; return best; };
+
+  const usedModules = new Set();
+  const missing = new Map(); // pkg → { files:Set, lines:Map }
+  const inNonRuntimeRoot = (file) => (nonRuntimeRoots || []).some((root) => {
+    const f = String(file || "").replace(/\\/g, "/"), r = String(root || "").replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+|\/+$/g, "");
+    return !!r && (f === r || f.startsWith(`${r}/`));
+  });
+  for (const e of externalImports) {
+    if (e.ecosystem !== "Go" || e.builtin || e.unresolved || !e.pkg) continue;
+    const mod = moduleOf(e.spec || e.pkg) || (declared.has(e.pkg) ? e.pkg : "");
+    if (mod) { usedModules.add(mod); continue; }
+    let m = missing.get(e.pkg);
+    if (!m) missing.set(e.pkg, (m = { files: new Set(), lines: new Map() }));
+    m.files.add(e.file);
+    if (!m.lines.has(e.file)) m.lines.set(e.file, e.line || 0);
+  }
+
+  for (const r of requires) {
+    if (r.indirect || usedModules.has(r.path)) continue;
+    findings.push(makeFinding({
+      category: "unused",
+      rule: "unused-dep",
+      severity: "low",
+      confidence: "medium",
+      title: `Unused Go module: ${r.path}`,
+      reason: "A direct go.mod requirement has no matching recorded Go import; build-tagged usage remains possible.",
+      detail: `"${r.path}" is required (direct) in go.mod but no .go file imports it or any of its packages. Build-tag-guarded files can hide usage — confirm with \`go mod tidy\` before removing.`,
+      package: r.path,
+      version: r.version,
+      source: "internal",
+      fixHint: "go mod tidy (drops requires nothing imports)",
+    }));
+  }
+  for (const [pkg, use] of missing) {
+    if (replaced.has(pkg)) continue;
+    const files = [...use.files];
+    if (files.every(inNonRuntimeRoot)) continue;
+    findings.push(makeFinding({
+      category: "unused",
+      rule: "missing-dep",
+      severity: "medium",
+      confidence: "medium",
+      title: `Missing Go module: ${pkg}`,
+      reason: "A recorded Go import has no matching direct go.mod requirement or replace entry.",
+      detail: `"${pkg}" is imported by ${files.length} file(s) but go.mod has no matching require — a replace/workspace/vendor setup, or the module was never added.`,
+      package: pkg,
+      file: files[0],
+      line: use.lines.get(files[0]) || 0,
+      evidence: files.slice(0, 5).map((f) => ({ file: f, line: use.lines.get(f) || 0, snippet: "" })),
+      source: "internal",
+      fixHint: `go get ${pkg}`,
+    }));
+  }
+  return { findings, declared };
+}
+
+// ---- Python: ecosystem:"PyPI" externalImports vs requirements/pyproject/Pipfile ----
+// Import→dist naming is heuristic (yaml→PyYAML, python-X/X-python variants), so matching is GENEROUS for
+// suppression and every unused finding stays low-confidence. CLI-only tools (pytest, black, gunicorn …)
+// and stub/plugin conventions (types-*, *-stubs, pytest-*, flake8-*) are never flagged unused.
+const PY_TOOL_DISTS = new Set(("pytest tox nox black ruff flake8 pylint mypy pyright isort bandit coverage pre-commit pip setuptools wheel build twine poetry poetry-core " +
+  "pip-tools uv virtualenv pipenv gunicorn uwsgi supervisor ipython jupyter jupyterlab notebook ipykernel codecov autopep8 yapf commitizen detect-secrets safety pip-audit hatchling flit flit-core pdm").split(" "));
+const pyNorm = (n) => String(n || "").toLowerCase().replace(/[-_.]+/g, "-");
+
+export function computePyDepFindings({
+  externalImports = [], pyManifest = null, configTexts = new Map(),
+  managedDependencies = [], ignoredDependencies = [], nonRuntimeRoots = [],
+} = {}) {
+  const findings = [];
+  const deps = (pyManifest && pyManifest.deps) || [];
+  const present = !!(pyManifest && pyManifest.present);
+  const declared = new Set(deps.map((d) => pyNorm(d.name)));
+  const managed = new Set((managedDependencies || []).map(pyNorm));
+  const ignored = new Set((ignoredDependencies || []).map(pyNorm));
+  const inNonRuntimeRoot = (file) => (nonRuntimeRoots || []).some((root) => {
+    const f = String(file || "").replace(/\\/g, "/"), r = String(root || "").replace(/\\/g, "/").replace(/^\.\//, "").replace(/^\/+|\/+$/g, "");
+    return !!r && (f === r || f.startsWith(`${r}/`));
+  });
+  for (const name of managed) declared.add(name);
+
+  const used = new Map(); // top import → { dist, files:Set, lines:Map }
+  for (const e of externalImports) {
+    if (e.ecosystem !== "PyPI" || e.builtin || e.unresolved || !e.pkg) continue;
+    const top = String(e.spec || e.pkg).split(".")[0];
+    let u = used.get(top);
+    if (!u) used.set(top, (u = { dist: e.pkg, files: new Set(), lines: new Map() }));
+    u.files.add(e.file);
+    if (!u.lines.has(e.file)) u.lines.set(e.file, e.line || 0);
+  }
+  // generous match: does declared dist D cover import top t (dist guess g)?
+  const covers = (D, t, g) => {
+    const d = pyNorm(D), nt = pyNorm(t), ng = pyNorm(g);
+    return d === nt || d === ng || d === `python-${nt}` || d === `${nt}-python` || d === `${nt}-binary` || d.replace(/\d+$/, "") === nt.replace(/\d+$/, "");
+  };
+
+  const configBlob = [...configTexts.values()].join("\n");
+  if (present) {
+    for (const d of deps) {
+      const n = pyNorm(d.name);
+      if (managed.has(n) || ignored.has(n)) continue;
+      if (d.buildSystem || PY_TOOL_DISTS.has(n) || /^types-|-stubs$|^pytest-|^flake8-|^sphinx/.test(n)) continue;
+      let hit = false;
+      for (const [top, u] of used) if (covers(d.name, top, u.dist)) { hit = true; break; }
+      if (hit || mentioned(configBlob, d.name)) continue;
+      findings.push(makeFinding({
+        category: "unused",
+        rule: "unused-dep",
+        severity: d.dev ? "info" : "low",
+        confidence: "low",
+        title: `Unused Python dependency: ${d.name}`,
+        reason: "No recorded Python import maps to this declared distribution; import-to-distribution mapping and plugin loading are heuristic.",
+        detail: `"${d.name}" is declared but no .py file imports a module that maps to it. Import-name↔package-name mapping is heuristic and plugins/CLI tools load dynamically — review before removing.`,
+        package: d.name,
+        source: "internal",
+        fixHint: `remove "${d.name}" from the manifest after confirming nothing imports or shells out to it`,
+      }));
+    }
+  }
+  for (const [top, u] of used) {
+    if (ignored.has(pyNorm(top)) || ignored.has(pyNorm(u.dist)) || managed.has(pyNorm(top)) || managed.has(pyNorm(u.dist))) continue;
+    let hit = false;
+    for (const D of declared) if (covers(D, top, u.dist)) { hit = true; break; }
+    if (hit) continue;
+    const files = [...u.files];
+    if (files.every(inNonRuntimeRoot)) continue;
+    const testOnly = files.every((f) => TEST_PATH_RE.test(f));
+    findings.push(makeFinding({
+      category: "unused",
+      rule: "missing-dep",
+      severity: present ? (testOnly ? "low" : "medium") : "low",
+      confidence: present ? "medium" : "low",
+      title: `Missing Python dependency: ${u.dist}`,
+      reason: present
+        ? `A recorded Python import maps to "${u.dist}", but no declared distribution covers it.`
+        : `A recorded Python import maps to "${u.dist}", but no Python dependency manifest is present; a managed runtime may provide it.`,
+      detail: `"${top}" is imported by ${files.length} file(s) but ${present ? "no declared dependency provides it" : "the repo has no Python dependency manifest (requirements.txt / pyproject / Pipfile); a bundled or managed runtime may provide it"}${u.dist !== top ? ` (PyPI package is likely "${u.dist}")` : ""}.${present ? "" : " If this is intentional, declare it under python.managedDependencies in .weavatrix-deps.json."}`,
+      package: u.dist,
+      file: files[0],
+      line: u.lines.get(files[0]) || 0,
+      evidence: files.slice(0, 5).map((f) => ({ file: f, line: u.lines.get(f) || 0, snippet: "" })),
+      source: "internal",
+      fixHint: present ? `pip install ${u.dist}  (and add it to requirements.txt / pyproject)` : `add ${u.dist} to a Python manifest, or declare it as a managed runtime dependency`,
+    }));
+  }
+  return { findings, declared, managed };
+}