weavatrix 0.1.4 → 0.2.0

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

@@ -20,6 +20,10 @@ import {
 } from "./internal-audit.collect.js";
 import { entryFiles, computeReachability } from "./internal-audit.reach.js";
 import { createRepoBoundary } from "../repo-path.js";
+import { PATH_CLASS_NAMES, createPathClassifier, hasPathClass } from "../path-classification.js";
+import { packageReachability } from "./package-reachability.js";
+
+const LOWER_SEVERITY = { critical: "high", high: "medium", medium: "low", low: "info", info: "info" };
 
 // Run the internal audit. graph is optional (loaded from the repo's central graph.json when absent);
 // advisoryStorePath overrides the default ~/.weavatrix/advisories.json (tests use a scratch path).
@@ -41,19 +45,38 @@ export async function runInternalAudit(repoPath, { graph, advisoryStorePath, ski
   // Graphs can be stale or miss a helper file; text fallbacks must scan the real repo tree too.
   const sources = collectSourceTexts(repoPath, graph);
   const nonRuntimeRoots = collectNonRuntimeRoots(repoPath, rules);
+  const pathClassifier = createPathClassifier(repoPath);
+  const pathClassifications = new Map();
+  const classifyPath = (file) => {
+    const normalized = String(file || "").replace(/\\/g, "/");
+    if (!pathClassifications.has(normalized)) {
+      pathClassifications.set(normalized, pathClassifier.explain(normalized, { content: sources.get(normalized) }));
+    }
+    return pathClassifications.get(normalized);
+  };
+  const isNonProductPath = (file) => {
+    const info = classifyPath(file);
+    return info.excluded || hasPathClass(info, "test", "e2e", "generated", "mock", "story", "docs", "benchmark", "temp");
+  };
 
+  const conventionEvidence = [];
   const entries = entryFiles(graph, packageScopes, dynamicTargets, {
     declaredEntries: rules.entrypoints || rules.entries || [],
     sources,
+    conventionEvidence,
   });
   for (const file of sources.keys()) {
     if (nonRuntimeRoots.some((root) => file === root || file.startsWith(`${root}/`))) entries.add(file);
+    if (isNonProductPath(file)) entries.add(file);
   }
   const dead = computeDead(graph, sources, { entrySet: entries });
   const unusedExports = computeUnusedExports(graph, sources, { dynamicTargets, entrySet: entries });
   const reachable = computeReachability(graph, entries);
   const configTexts = collectConfigTexts(repoPath);
-  const dep = computeScopedDepFindings({ externalImports, packageScopes, workspacePkgNames: workspacePkgNames(repoPath, pkg), configTexts, nonRuntimeRoots });
+  const dep = computeScopedDepFindings({
+    externalImports, packageScopes, workspacePkgNames: workspacePkgNames(repoPath, pkg), configTexts,
+    nonRuntimeRoots, sourceFiles: [...sources.keys()],
+  });
   // non-npm ecosystems: Go (go.mod) + Python (requirements/pyproject/Pipfile) — same findings shape
   const goModText = readRepoText(boundary, "go.mod");
   const goDep = computeGoDepFindings({ externalImports, goMod: goModText != null ? parseGoMod(goModText) : null, nonRuntimeRoots });
@@ -82,7 +105,8 @@ export async function runInternalAudit(repoPath, { graph, advisoryStorePath, ski
   // orphan ∩ dead-file → one finding: keep the stronger unused-file, drop the duplicate orphan
   const deadFileSet = new Set(dead.deadFiles.map((f) => f.file));
   for (const f of structure.findings) if (!(f.rule === "orphan-file" && deadFileSet.has(f.file))) findings.push(f);
-  for (const f of dead.deadFiles) {
+  const actionableDeadFiles = dead.deadFiles.filter((f) => !isNonProductPath(f.file));
+  for (const f of actionableDeadFiles) {
     if (entries.has(f.file) || dynamicTargets.has(f.file) || TEST_FILE_RE.test(f.file)) continue;
     findings.push(makeFinding({
       category: "unused",
@@ -99,7 +123,7 @@ export async function runInternalAudit(repoPath, { graph, advisoryStorePath, ski
   }
   let unusedExportCount = 0;
   for (const s of unusedExports) {
-    if (s.test) continue; // exports from test files are runner-visible noise
+    if (s.test || isNonProductPath(s.file)) continue; // convention/generated surfaces are externally consumed or non-product noise
     if (/(^|\/)[^/]*\.config\.[a-z0-9]+$|(^|\/)\.[^/]+rc(\.[a-z]+)?$/i.test(s.file)) continue; // config exports are consumed by their tool
     findings.push(makeFinding({
       category: "unused",
@@ -122,7 +146,7 @@ export async function runInternalAudit(repoPath, { graph, advisoryStorePath, ski
   let installedCount = 0;
   let inst = { installed: [], drift: [] };
   const checks = {
-    osv: { status: "NOT_CHECKED", detail: "Advisory cache was never refreshed for this repository. The refresh_advisories tool belongs to the optional online capability group: enable that group in the MCP registration, then call the tool explicitly to opt in to sending pinned package names and versions to OSV.dev." },
+    osv: { status: "NOT_CHECKED", detail: "Advisory cache was never refreshed for this repository. Enable the osv profile (or advisories capability), then call refresh_advisories explicitly to opt in to sending pinned package names and versions to OSV.dev." },
     malware: { status: skipMalwareScan ? "NOT_CHECKED" : "PENDING", detail: skipMalwareScan ? "Installed-package malware scan is opt-in and was not requested." : "" },
   };
   try {
@@ -140,7 +164,7 @@ export async function runInternalAudit(repoPath, { graph, advisoryStorePath, ski
       const coverage = typeof repoStamp === "object" && Number.isFinite(repoStamp.queried)
         ? ` (${repoStamp.queried_ok ?? repoStamp.queried}/${repoStamp.queried} package versions queried successfully)`
         : "";
-      const drift = fingerprintMatches ? "" : " Dependency versions changed, or this is a legacy stamp without a package fingerprint; enable the optional online capability group and call refresh_advisories for complete coverage.";
+      const drift = fingerprintMatches ? "" : " Dependency versions changed, or this is a legacy stamp without a package fingerprint; enable the osv profile (or advisories capability) and call refresh_advisories for complete coverage.";
       checks.osv = {
         status,
         detail: `${status === "PARTIAL" ? "Partially matched" : "Matched"} installed packages against the cached OSV snapshot from ${advisoryDbDate}${coverage}.${drift}`,
@@ -148,16 +172,25 @@ export async function runInternalAudit(repoPath, { graph, advisoryStorePath, ski
       };
       for (const h of matchAdvisories(inst.installed, (eco, name) => queryStore(store, eco, name))) {
         const mal = h.adv.kind === "malicious";
+        const reachability = packageReachability(externalImports, h.pkg.name, { isNonProductPath });
+        const observedInProduct = reachability.state === "DIRECT_RUNTIME_IMPORT";
+        const reachabilityDetail = observedInProduct
+          ? ` Graph reachability: directly imported by product code in ${reachability.directRuntimeImports} callsite(s) across ${reachability.files.length} file(s).`
+          : ` Graph reachability: ${reachability.state}; ${reachability.note}`;
         findings.push(makeFinding({
           category: mal ? "malware" : "vulnerability",
           rule: mal ? "malicious-package" : "known-vuln",
-          severity: mal ? "critical" : h.adv.severity,
-          confidence: h.confidence,
+          severity: mal || observedInProduct ? (mal ? "critical" : h.adv.severity) : LOWER_SEVERITY[h.adv.severity] || h.adv.severity,
+          confidence: mal || observedInProduct ? h.confidence : "low",
           title: `${mal ? "Known-malicious package" : `Known vulnerability (${h.adv.id})`}: ${h.pkg.name}@${h.pkg.version}`,
-          detail: `${h.adv.summary || h.adv.id}${h.adv.fixedIn.length ? ` Fixed in: ${h.adv.fixedIn.join(", ")}.` : mal ? " Remove this package immediately and rotate any secrets it could reach." : ""} (matched by ${h.matchedBy}${h.adv.aliases.length ? `; aliases ${h.adv.aliases.join(", ")}` : ""})`,
+          detail: `${h.adv.summary || h.adv.id}${h.adv.fixedIn.length ? ` Fixed in: ${h.adv.fixedIn.join(", ")}.` : mal ? " Remove this package immediately and rotate any secrets it could reach." : ""} (matched by ${h.matchedBy}${h.adv.aliases.length ? `; aliases ${h.adv.aliases.join(", ")}` : ""}).${reachabilityDetail}`,
           package: h.pkg.name,
           version: h.pkg.version,
-          evidence: [{ file: h.adv.url, line: 0, snippet: `installed via ${h.pkg.source}${h.pkg.dev ? " (dev)" : ""}` }],
+          reachability,
+          evidence: [
+            { file: h.adv.url, line: 0, snippet: `installed via ${h.pkg.source}${h.pkg.dev ? " (dev)" : ""}` },
+            ...reachability.evidence.slice(0, 5).map((item) => ({file: item.file, line: item.line, snippet: `${item.typeOnly ? "type-only " : ""}${item.kind}`})),
+          ],
           source: "osv",
           fixHint: mal ? `npm uninstall ${h.pkg.name} + audit what it touched` : h.adv.fixedIn.length ? `upgrade ${h.pkg.name} to ${h.adv.fixedIn[h.adv.fixedIn.length - 1]}+` : "no fixed version published — consider replacing the package",
         }));
@@ -234,10 +267,25 @@ export async function runInternalAudit(repoPath, { graph, advisoryStorePath, ski
       packageScopes: packageScopes.length,
       managedPythonDependencies: managedPython.length,
       nonRuntimeRoots,
+      pathClassifications: Object.fromEntries(PATH_CLASS_NAMES.map((name) => [
+        name,
+        [...pathClassifications.values()].filter((info) => info.classes.includes(name)).length,
+      ])),
+      pathClassificationExcluded: [...pathClassifications.values()].filter((info) => info.excluded).length,
+      conventionEntrypoints: conventionEvidence.length,
     },
     summary: summarizeFindings(sorted),
     findings: sorted,
-    deadReport: { deadSymbols: dead.deadSymbols.length, deadFiles: dead.deadFiles.length, unusedExports: unusedExportCount },
+    deadReport: {
+      deadSymbols: dead.deadSymbols.filter((symbol) => !isNonProductPath(symbol.file)).length,
+      deadFiles: actionableDeadFiles.length,
+      unusedExports: unusedExportCount,
+    },
+    conventionReachability: {
+      count: conventionEvidence.length,
+      entries: conventionEvidence.slice(0, 100),
+      truncated: conventionEvidence.length > 100,
+    },
     structureReport: structure.stats,
     checks,
     malwareScan,

package/src/analysis/java-source.js

@@ -0,0 +1,36 @@
+// Replace Java comments and string/char literal contents with spaces while preserving length and
+// newlines. Regex-based signal extractors can then trust match positions without accepting examples
+// from comments, docs, or string constants as executable annotations.
+export function maskJavaNonCode(source) {
+  const text = String(source || "");
+  const chars = [...text];
+  let state = "code";
+  let escaped = false;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    const next = text[i + 1];
+    if (state === "code") {
+      if (ch === "/" && next === "/") { chars[i] = chars[i + 1] = " "; i++; state = "line"; }
+      else if (ch === "/" && next === "*") { chars[i] = chars[i + 1] = " "; i++; state = "block"; }
+      else if (ch === '"') { chars[i] = " "; state = "string"; escaped = false; }
+      else if (ch === "'") { chars[i] = " "; state = "char"; escaped = false; }
+      continue;
+    }
+    if (state === "line") {
+      if (ch === "\n" || ch === "\r") state = "code";
+      else chars[i] = " ";
+      continue;
+    }
+    if (state === "block") {
+      if (ch === "*" && next === "/") { chars[i] = chars[i + 1] = " "; i++; state = "code"; }
+      else if (ch !== "\n" && ch !== "\r") chars[i] = " ";
+      continue;
+    }
+    if (ch === "\n" || ch === "\r") { escaped = false; continue; }
+    chars[i] = " ";
+    if (escaped) escaped = false;
+    else if (ch === "\\") escaped = true;
+    else if ((state === "string" && ch === '"') || (state === "char" && ch === "'")) state = "code";
+  }
+  return chars.join("");
+}

package/src/analysis/package-reachability.js

@@ -0,0 +1,39 @@
+// Package-level reachability: correlate a dependency finding with the graph's external imports.
+// This is intentionally not function-level exploitability analysis. It only states whether product
+// code imports the package and preserves unknown as unknown.
+export const PACKAGE_REACHABILITY_V = 1
+
+export function packageReachability(externalImports, packageName, {isNonProductPath = () => false} = {}) {
+    const imports = (Array.isArray(externalImports) ? externalImports : [])
+        .filter((item) => item?.pkg === packageName && item.builtin !== true)
+        .map((item) => ({
+            file: String(item.file || '').replace(/\\/g, '/'),
+            line: Number.isInteger(item.line) ? item.line : 0,
+            kind: String(item.kind || 'import'),
+            typeOnly: item.typeOnly === true,
+            dynamic: item.dynamic === true,
+        }))
+        .filter((item) => item.file)
+    const product = imports.filter((item) => !isNonProductPath(item.file))
+    const runtime = product.filter((item) => !item.typeOnly)
+    const state = runtime.length
+        ? 'DIRECT_RUNTIME_IMPORT'
+        : product.length
+            ? 'TYPE_ONLY_IMPORT'
+            : imports.length
+                ? 'NON_PRODUCT_IMPORT_ONLY'
+                : 'NOT_OBSERVED_IN_GRAPH'
+    return {
+        packageReachabilityV: PACKAGE_REACHABILITY_V,
+        level: 'package-import',
+        state,
+        directRuntimeImports: runtime.length,
+        directProductImports: product.length,
+        observedImports: imports.length,
+        files: [...new Set((runtime.length ? runtime : product.length ? product : imports).map((item) => item.file))].sort().slice(0, 20),
+        evidence: (runtime.length ? runtime : product.length ? product : imports).slice(0, 10),
+        note: state === 'NOT_OBSERVED_IN_GRAPH'
+            ? 'No static import was observed; implicit, dynamic, plugin and transitive runtime use remain unknown.'
+            : 'Package-level static import evidence; this does not prove vulnerable-function reachability.',
+    }
+}

package/src/analysis/static-test-reachability.js

@@ -0,0 +1,133 @@
+// A deliberately weaker fallback than real coverage: follow runtime graph edges out of test files
+// and report nearest test paths. This is evidence of static reachability only; it never claims a line,
+// branch or symbol executed. The traversal is bounded for large repositories.
+import { createPathClassifier, hasPathClass } from "../path-classification.js";
+import { isStructuralRelation } from "../graph/relations.js";
+
+const MAX_TEST_FILES = 250;
+const MAX_NEAREST_TESTS = 3;
+const MAX_DEPTH = 10;
+const MAX_STATES = 100_000;
+
+const normalize = (value) => String(value || "").replace(/\\/g, "/").replace(/^\.\//, "");
+const endpoint = (value) => String(value && typeof value === "object" ? value.id : value || "");
+const confidenceScore = (value) => {
+  const normalized = String(value || "").toUpperCase();
+  if (["EXTRACTED", "EXACT", "HIGH"].includes(normalized)) return 3;
+  if (["INFERRED", "MEDIUM"].includes(normalized)) return 2;
+  return 1;
+};
+const confidenceLabel = (score) => score >= 3 ? "HIGH" : score >= 2 ? "MEDIUM" : "LOW";
+const pathInScope = (path, prefix) => !prefix || path === prefix || path.startsWith(`${prefix}/`);
+
+export function computeStaticTestReachability(graph, {
+  repoRoot = null,
+  path = "",
+  maxDepth = MAX_DEPTH,
+  maxStates = MAX_STATES,
+  maxTests = MAX_TEST_FILES,
+  maxNearestTests = MAX_NEAREST_TESTS,
+} = {}) {
+  const nodes = graph?.nodes || [];
+  const links = graph?.links || [];
+  const classifier = createPathClassifier(repoRoot);
+  const classificationCache = new Map();
+  const classify = (file) => {
+    const normalized = normalize(file);
+    if (!classificationCache.has(normalized)) classificationCache.set(normalized, classifier.explain(normalized, { content: "" }));
+    return classificationCache.get(normalized);
+  };
+  const isTest = (file) => hasPathClass(classify(file), "test", "e2e");
+  const isProduct = (file) => {
+    const info = classify(file);
+    return !info.excluded && !hasPathClass(info, "test", "e2e", "generated", "mock", "story", "docs", "benchmark", "temp");
+  };
+
+  const idToFile = new Map();
+  const files = new Set();
+  for (const node of nodes) {
+    const file = normalize(node?.source_file || (!String(node?.id || "").includes("#") ? node?.id : ""));
+    if (!file) continue;
+    idToFile.set(String(node.id), file);
+    files.add(file);
+  }
+
+  // Collapse symbol/file edges to directed file dependencies. Multiple symbol edges retain the best
+  // confidence for the same hop; compile-time-only and ownership relations never imply test reach.
+  const adjacency = new Map();
+  for (const link of links) {
+    if (!link || link.typeOnly === true || link.compileOnly === true || isStructuralRelation(link.relation)) continue;
+    const from = idToFile.get(endpoint(link.source));
+    const to = idToFile.get(endpoint(link.target));
+    if (!from || !to || from === to) continue;
+    if (!adjacency.has(from)) adjacency.set(from, new Map());
+    const score = confidenceScore(link.confidence);
+    const previous = adjacency.get(from).get(to);
+    if (!previous || score > previous.score) adjacency.get(from).set(to, { score, relation: link.relation || "dependency" });
+  }
+
+  const allTests = [...files].filter(isTest).sort((a, b) => a.localeCompare(b));
+  const testLimit = Math.max(0, Math.min(MAX_TEST_FILES, Number(maxTests) || MAX_TEST_FILES));
+  const tests = allTests.slice(0, testLimit);
+  const scope = normalize(path).replace(/\/+$/, "");
+  const productFiles = [...files].filter(isProduct).filter((file) => pathInScope(file, scope)).sort((a, b) => a.localeCompare(b));
+  const productSet = new Set(productFiles);
+  const nearest = new Map();
+  const queue = tests.map((test) => ({ file: test, test, distance: 0, score: 3, path: [test] }));
+  const seen = new Map(tests.map((test) => [`${test}\0${test}`, 0]));
+  let cursor = 0;
+  let traversedStates = 0;
+  const depthLimit = Math.max(1, Math.min(MAX_DEPTH, Number(maxDepth) || MAX_DEPTH));
+  const stateLimit = Math.max(100, Math.min(MAX_STATES, Number(maxStates) || MAX_STATES));
+  const nearestLimit = Math.max(1, Math.min(MAX_NEAREST_TESTS, Number(maxNearestTests) || MAX_NEAREST_TESTS));
+
+  while (cursor < queue.length && traversedStates < stateLimit) {
+    const current = queue[cursor++];
+    traversedStates++;
+    if (current.distance >= depthLimit) continue;
+    for (const [next, edge] of adjacency.get(current.file) || []) {
+      const distance = current.distance + 1;
+      const score = Math.min(current.score, edge.score);
+      const key = `${current.test}\0${next}`;
+      if ((seen.get(key) ?? Infinity) <= distance) continue;
+      seen.set(key, distance);
+      const record = { test: current.test, distance, score, confidence: confidenceLabel(score), path: [...current.path, next] };
+      if (productSet.has(next)) {
+        const records = nearest.get(next) || [];
+        records.push(record);
+        records.sort((a, b) => a.distance - b.distance || b.score - a.score || a.test.localeCompare(b.test));
+        if (records.length > nearestLimit) records.length = nearestLimit;
+        nearest.set(next, records);
+      }
+      // Once enough nearer test paths meet at the same file, a longer test prefix cannot become a
+      // nearest path downstream because every continuation from this point is shared.
+      const records = nearest.get(next);
+      if (records?.length >= nearestLimit && !records.some((item) => item.test === current.test) && distance > records[records.length - 1].distance) continue;
+      queue.push({ file: next, test: current.test, distance, score, path: record.path });
+    }
+  }
+
+  const reachable = productFiles
+    .filter((file) => nearest.has(file))
+    .map((file) => ({ file, nearestTests: nearest.get(file) }))
+    .sort((a, b) => a.nearestTests[0].distance - b.nearestTests[0].distance || a.file.localeCompare(b.file));
+  const unreachable = productFiles.filter((file) => !nearest.has(file));
+  return {
+    kind: "staticTestReachability",
+    actualCoverage: "NOT_AVAILABLE",
+    testFiles: tests.length,
+    totalTestFiles: allTests.length,
+    productFiles: productFiles.length,
+    reachableFiles: reachable.length,
+    unreachableFiles: unreachable.length,
+    reachable,
+    unreachable,
+    bounds: {
+      maxDepth: depthLimit,
+      maxStates: stateLimit,
+      traversedStates,
+      maxTests: testLimit,
+      truncated: allTests.length > tests.length || (cursor < queue.length && traversedStates >= stateLimit),
+    },
+  };
+}

package/src/build-graph.js

@@ -6,11 +6,15 @@
 // the ENTIRE app froze on big repos. The worker writes graph.json itself and returns only counts +
 // summaries. If the worker can't even start (exotic packaging), we fall back to the in-process build
 // rather than lose the feature.
-import { existsSync, writeFileSync, mkdirSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, readFileSync, mkdirSync } from "node:fs";
+import { join, resolve } from "node:path";
 import { Worker } from "node:worker_threads";
 import { childProcessEnv } from "./child-env.js";
-import { graphOutDirForRepo, repoTopFolders, summarizeCommunities, summarizeHotspots, filterGraphForMode, filterGraphByScope } from "./graph/layout.js";
+import { graphHomeDir, graphOutDirForRepo, graphStorageKey, repoTopFolders, summarizeCommunities, summarizeHotspots, filterGraphForMode, filterGraphByScope } from "./graph/layout.js";
+import { registerRepository } from "./graph/repo-registry.js";
+import { refreshGraphIncrementally, snapshotRepository } from "./graph/incremental-refresh.js";
+import { atomicWriteFileSync, withFileLock } from "./graph/file-lock.js";
+import { repositoryFreshnessProbe, stampRepositoryFreshness } from "./graph/freshness-probe.js";
 
 // The worker path deadlocks web-tree-sitter's WASM in Electron's worker threads (fine in plain Node) — off
 // until that's Electron-safe. In-process + event-loop yielding keeps the window responsive without it.
@@ -54,23 +58,66 @@ function buildGraphInWorker(payload) {
 
 async function buildAndWriteInProcess(repoPath, { mode, scope, graphJson, central }) {
   const { buildInternalGraph } = await import("./graph/internal-builder.js");
-  let graph = await buildInternalGraph(repoPath);
+  // Capture the cheap Git state on both sides of the authoritative build. Only an unchanged pair is
+  // safe to persist: if the working tree moves while parsing, the next process must take the slow path.
+  const probeBefore = scope ? null : repositoryFreshnessProbe(repoPath);
+  let graph;
+  let refresh = null;
+  if (mode === "full" && !scope && existsSync(graphJson)) {
+    try {
+      const existing = JSON.parse(readFileSync(graphJson, "utf8"));
+      if (existing.graphBuildMode === "full" && !existing.graphBuildScope) {
+        refresh = await refreshGraphIncrementally(repoPath, existing, { buildGraph: buildInternalGraph });
+        graph = refresh.graph;
+      }
+    } catch { /* malformed/legacy graph: the safe path below is a full rebuild */ }
+  }
+  if (!graph && mode !== "full" && !scope && existsSync(graphJson)) {
+    try {
+      const existing = JSON.parse(readFileSync(graphJson, "utf8"));
+      if (existing.graphBuildMode === mode && existing.graphRevision) {
+        const snapshot = snapshotRepository(repoPath);
+        if (snapshot.revision === existing.graphRevision) {
+          graph = existing;
+          refresh = { kind: "none", changedFiles: [], reason: "content-unchanged", revision: snapshot.revision };
+        }
+      }
+    } catch { /* malformed/legacy filtered graph: rebuild below */ }
+  }
+  if (!graph) {
+    graph = await buildInternalGraph(repoPath);
+    refresh = { kind: "full", changedFiles: [], reason: "full-build-requested", revision: graph.graphRevision };
+  }
   // mode (no-tests/tests-only) + path-scope reuse the same pure filters graph-builder used.
-  if (mode === "no-tests" || mode === "tests-only") graph = filterGraphForMode(graph, mode);
+  if (mode === "no-tests" || mode === "tests-only") graph = filterGraphForMode(graph, mode, { repoRoot: repoPath });
   if (scope) graph = filterGraphByScope(graph, scope);
-  mkdirSync(central, { recursive: true });
-  writeFileSync(graphJson, JSON.stringify(graph), "utf8");
+  graph.graphBuildMode = mode;
+  graph.graphBuildScope = scope || "";
+  const probeAfter = scope ? null : repositoryFreshnessProbe(repoPath);
+  const stableProbe = probeBefore && probeAfter === probeBefore ? probeAfter : null;
+  const freshnessMetadataChanged = stampRepositoryFreshness(graph, stableProbe, mode);
+  // Auto-refresh runs before every graph/health call. A no-op must not serialize and rewrite a
+  // multi-megabyte graph merely to answer that nothing changed (or manufacture a newer mtime).
+  // A one-time metadata-only write is intentional for legacy graphs so the next MCP process can use
+  // the persisted probe instead of repeating a full repository snapshot.
+  if (refresh?.kind !== "none" || freshnessMetadataChanged) {
+    mkdirSync(central, { recursive: true });
+    atomicWriteFileSync(graphJson, JSON.stringify(graph), "utf8");
+  }
   return {
     nodes: graph.nodes.length,
     links: graph.links.length,
     communities: summarizeCommunities(graphJson),
     hotspots: summarizeHotspots(graphJson),
+    refresh,
   };
 }
 
-export async function buildGraphForRepo(repoPath, { mode = "full", scope = "", outDir } = {}) {
+export async function buildGraphForRepo(repoPath, { mode = "full", scope = "", outDir, graphHome } = {}) {
   if (!existsSync(repoPath)) return { ok: false, error: "Repo path not found", builder: "internal" };
-  const central = outDir || graphOutDirForRepo(repoPath);
+  const registryHome = graphHome || graphHomeDir();
+  const canonicalDir = graphHome ? join(registryHome, graphStorageKey(repoPath)) : graphOutDirForRepo(repoPath);
+  const central = outDir || canonicalDir;
   const graphJson = join(central, "graph.json");
   try {
     // In-process is the ONLY path now. The worker (buildGraphInWorker) hung web-tree-sitter's WASM inside an
@@ -78,12 +125,23 @@ export async function buildGraphForRepo(repoPath, { mode = "full", scope = "", o
     // in ~3s on the main thread (and in a plain-Node worker). buildInternalGraph now YIELDS the event loop
     // between file chunks, so the main-thread parse no longer freezes the window — the reason the worker was
     // introduced. buildGraphInWorker/USE_BUILD_WORKER are kept for a future Electron-safe re-enable.
-    const built = USE_BUILD_WORKER
-      ? await buildGraphInWorker({ repoPath, mode, scope, graphJson, central }).catch((e) => {
+    const build = () => USE_BUILD_WORKER
+      ? buildGraphInWorker({ repoPath, mode, scope, graphJson, central }).catch((e) => {
           if (e && e.workerStartFailed) return buildAndWriteInProcess(repoPath, { mode, scope, graphJson, central });
           throw e;
         })
-      : await buildAndWriteInProcess(repoPath, { mode, scope, graphJson, central });
+      : buildAndWriteInProcess(repoPath, { mode, scope, graphJson, central });
+    // Canonical graphs are shared by all local MCP clients. Serialize the complete read/refresh/write
+    // transaction so an older process cannot overwrite a newer incremental result.
+    const canonical = !scope && resolve(central) === resolve(canonicalDir);
+    const built = canonical
+      ? await withFileLock(join(central, ".graph.lock"), build, { timeoutMs: 5 * 60_000, staleMs: 10 * 60_000 })
+      : await build();
+    // Scoped builds are disposable diagnostics under modules/<scope>; registering one would retarget
+    // list_known_repos and cross-repo analysis away from the complete canonical graph.
+    if (canonical) {
+      registerRepository({ repoPath, graphDir: central, graphHome: registryHome });
+    }
     return {
       ok: true,
       builder: "internal",
@@ -95,7 +153,8 @@ export async function buildGraphForRepo(repoPath, { mode = "full", scope = "", o
       graphDir: central,
       communities: built.communities,
       hotspots: built.hotspots,
-      log: `built-in builder: ${built.nodes} nodes, ${built.links} links`
+      refresh: built.refresh,
+      log: `built-in builder: ${built.nodes} nodes, ${built.links} links (${built.refresh?.kind || "full"}: ${built.refresh?.reason || "build"})`
     };
   } catch (error) {
     return { ok: false, error: `graph build failed: ${error.message}`, builder: "internal" };

package/src/graph/build-worker.js

@@ -5,18 +5,17 @@
 // result object crosses back (never the graph itself — structured-cloning a huge graph would stall
 // the main thread again).
 import { parentPort, workerData } from "node:worker_threads";
-import { writeFileSync, mkdirSync } from "node:fs";
 import { buildInternalGraph } from "./internal-builder.js";
 import { filterGraphForMode, filterGraphByScope, summarizeCommunities, summarizeHotspots } from "./layout.js";
+import { atomicWriteFileSync } from "./file-lock.js";
 
 (async () => {
   const { repoPath, mode, scope, graphJson, central } = workerData || {};
   try {
     let graph = await buildInternalGraph(repoPath);
-    if (mode === "no-tests" || mode === "tests-only") graph = filterGraphForMode(graph, mode);
+    if (mode === "no-tests" || mode === "tests-only") graph = filterGraphForMode(graph, mode, { repoRoot: repoPath });
     if (scope) graph = filterGraphByScope(graph, scope);
-    mkdirSync(central, { recursive: true });
-    writeFileSync(graphJson, JSON.stringify(graph), "utf8");
+    atomicWriteFileSync(graphJson, JSON.stringify(graph), "utf8");
     parentPort.postMessage({
       ok: true,
       nodes: graph.nodes.length,