weavatrix 0.2.3 → 0.2.5

package/src/analysis/hot-path-review.js

@@ -0,0 +1,228 @@
+// Bounded local hot-path review over parser-derived complexity facts. This deliberately keeps
+// local syntax cost, graph coupling and test evidence separate: it is a review queue, not a runtime
+// profiler or an interprocedural Big-O proof.
+import {readCoverageForRepo, normalizeRepoParts} from './coverage-reports.js'
+import {computeStaticTestReachability} from './static-test-reachability.js'
+import {createPathClassifier, hasPathClass} from '../path-classification.js'
+import {isStructuralRelation} from '../graph/relations.js'
+
+const NON_PRODUCT = ['generated', 'mock', 'story', 'docs', 'benchmark', 'temp']
+const endpoint = (value) => String(value && typeof value === 'object' ? value.id : value || '')
+const normalize = (value) => String(value || '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/, '')
+const boundedInt = (value, fallback, min, max) => {
+    const number = Number(value)
+    return Number.isInteger(number) ? Math.max(min, Math.min(max, number)) : fallback
+}
+const round = (value) => Math.round(Number(value || 0) * 100) / 100
+const clamp = (value, min = 0, max = 100) => Math.max(min, Math.min(max, Number(value) || 0))
+
+function normalizeScope(value) {
+    const path = normalize(value)
+    if (!path) return {ok: true, path: ''}
+    if (path.includes('\0') || /^[a-z]:\//i.test(path) || path.startsWith('/') || path.split('/').includes('..')) {
+        return {ok: false, error: 'path must be repository-relative and cannot contain traversal segments'}
+    }
+    return {ok: true, path}
+}
+
+function coverageForRange(record, startLine, endLine) {
+    if (!record) return null
+    if (!(record.lines instanceof Map) || !record.lines.size) return Number.isFinite(record.pct) ? record.pct : null
+    let total = 0
+    let covered = 0
+    for (let line = Math.max(1, startLine); line <= Math.max(startLine, endLine); line++) {
+        if (!record.lines.has(line)) continue
+        total++
+        if (Number(record.lines.get(line)) > 0) covered++
+    }
+    return total ? covered / total : Number.isFinite(record.pct) ? record.pct : null
+}
+
+function graphRiskBySymbol(graph, symbolIds) {
+    const state = new Map([...symbolIds].map((id) => [id, {
+        incoming: 0, outgoing: 0, callers: new Set(), callees: new Set(),
+    }]))
+    for (const link of graph?.links || []) {
+        if (!link || link.typeOnly === true || link.compileOnly === true || link.barrelProxy === true || isStructuralRelation(link.relation)) continue
+        const source = endpoint(link.source)
+        const target = endpoint(link.target)
+        if (!source || !target || source === target) continue
+        if (state.has(source)) {
+            const item = state.get(source)
+            item.outgoing++
+            item.callees.add(target)
+        }
+        if (state.has(target)) {
+            const item = state.get(target)
+            item.incoming++
+            item.callers.add(source)
+        }
+    }
+    return new Map([...state].map(([id, item]) => [id, {
+        fanIn: item.callers.size,
+        fanOut: item.callees.size,
+        incomingEdges: item.incoming,
+        outgoingEdges: item.outgoing,
+    }]))
+}
+
+function localSyntaxScore(complexity, thresholds) {
+    const insideLoop = Number(complexity.allocationsInLoops || 0)
+        + Number(complexity.copiesInLoops || 0)
+        + Number(complexity.linearOpsInLoops || 0)
+        + Number(complexity.sortsInLoops || 0) * 2
+        + Number(complexity.recursionInLoops || 0) * 2
+    const score = Number(complexity.timeRank || 0) * 12
+        + Number(complexity.memoryRank || 0) * 5
+        + Math.min(18, Number(complexity.cyclomatic || 1) / thresholds.cyclomatic * 10)
+        + Math.min(12, Number(complexity.callCount || 0) / thresholds.calls * 6)
+        + Math.min(18, Number(complexity.maxLoopDepth || 0) * 5)
+        + Math.min(24, insideLoop * 5)
+        + (complexity.recursion ? 6 : 0)
+    return round(clamp(score))
+}
+
+function couplingScore(risk) {
+    return round(clamp(Math.log2(1 + risk.fanIn) * 20 + Math.log2(1 + risk.fanOut) * 10))
+}
+
+function reasonsFor(complexity, thresholds) {
+    const reasons = []
+    if (Number(complexity.timeRank || 0) >= thresholds.timeRank) reasons.push(String(complexity.timeLabel || `local time rank ${complexity.timeRank}`))
+    if (Number(complexity.cyclomatic || 0) >= thresholds.cyclomatic) reasons.push(`cyclomatic ${complexity.cyclomatic} >= ${thresholds.cyclomatic}`)
+    if (Number(complexity.callCount || 0) >= thresholds.calls) reasons.push(`${complexity.callCount} local call sites >= ${thresholds.calls}`)
+    if (Number(complexity.maxLoopDepth || 0) >= thresholds.loopDepth) reasons.push(`loop depth ${complexity.maxLoopDepth} >= ${thresholds.loopDepth}`)
+    if (complexity.allocationsInLoops) reasons.push(`${complexity.allocationsInLoops} allocation(s) inside iteration`)
+    if (complexity.copiesInLoops) reasons.push(`${complexity.copiesInLoops} copy/copies inside iteration`)
+    if (complexity.linearOpsInLoops) reasons.push(`${complexity.linearOpsInLoops} linear operation(s) inside iteration`)
+    if (complexity.sortsInLoops) reasons.push(`${complexity.sortsInLoops} sort(s) inside iteration`)
+    if (complexity.recursionInLoops) reasons.push(`${complexity.recursionInLoops} recursive call(s) inside iteration`)
+    if (complexity.recursion) reasons.push('direct recursion; bound remains unknown')
+    return [...new Set(reasons)].slice(0, 12)
+}
+
+export function computeHotPathReview(graph, options = {}) {
+    const scope = normalizeScope(options.path)
+    if (!scope.ok) return {ok: false, error: scope.error}
+    const thresholds = {
+        cyclomatic: boundedInt(options.cyclomaticThreshold, 8, 2, 1000),
+        calls: boundedInt(options.callThreshold, 12, 1, 10000),
+        loopDepth: boundedInt(options.loopDepthThreshold, 2, 1, 10),
+        timeRank: boundedInt(options.timeRankThreshold, 2, 0, 5),
+        minScore: boundedInt(options.minScore, 0, 0, 100),
+    }
+    const topN = boundedInt(options.topN, 20, 1, 100)
+    const classifier = createPathClassifier(options.repoRoot || null)
+    const knownFiles = [...new Set((graph?.nodes || []).map((node) => normalize(node?.source_file)).filter(Boolean))]
+    const measuredCoverage = options.repoRoot ? readCoverageForRepo(options.repoRoot, knownFiles) : new Map()
+    const coverageSources = [...new Set([...measuredCoverage.values()].map((item) => item?.source).filter(Boolean))].sort()
+    const staticTests = measuredCoverage.size || !options.repoRoot
+        ? null
+        : computeStaticTestReachability(graph, {repoRoot: options.repoRoot, path: scope.path})
+    const staticByFile = new Map((staticTests?.reachable || []).map((item) => [normalize(item.file), item]))
+
+    const eligible = []
+    const excluded = {tests: 0, classified: 0, outOfScope: 0}
+    for (const node of graph?.nodes || []) {
+        const complexity = node?.complexity
+        const file = normalize(node?.source_file)
+        if (!complexity || !file || !String(node?.id || '').includes('#')) continue
+        if (scope.path && file !== scope.path && !file.startsWith(`${scope.path}/`)) { excluded.outOfScope++; continue }
+        const classification = classifier.explain(file)
+        const test = hasPathClass(classification, 'test', 'e2e')
+        const classified = classification.excluded || hasPathClass(classification, ...NON_PRODUCT)
+        if (test && options.includeTests !== true) { excluded.tests++; continue }
+        if (classified && options.includeClassified !== true) { excluded.classified++; continue }
+        eligible.push({node, complexity, file, classification: test ? 'test' : classified ? 'classified' : 'production'})
+    }
+
+    const riskById = graphRiskBySymbol(graph, new Set(eligible.map(({node}) => String(node.id))))
+    const candidates = []
+    for (const entry of eligible) {
+        const {node, complexity, file} = entry
+        const reasons = reasonsFor(complexity, thresholds)
+        if (!reasons.length) continue
+        const risk = riskById.get(String(node.id)) || {fanIn: 0, fanOut: 0, incomingEdges: 0, outgoingEdges: 0}
+        const syntaxScore = localSyntaxScore(complexity, thresholds)
+        const graphScore = couplingScore(risk)
+        const startLine = Number(complexity.startLine) || Number(String(node.source_location || '').replace(/^L/, '')) || 0
+        const endLine = Number(complexity.endLine) || Number(String(node.source_end || '').replace(/^L/, '')) || startLine
+        const coverageRecord = measuredCoverage.get(normalizeRepoParts(file)) || null
+        const actualCoverage = coverageForRange(coverageRecord, startLine, endLine)
+        const nearest = staticByFile.get(file)?.nearestTests?.[0] || null
+        const coverageRisk = actualCoverage == null ? 0 : (1 - actualCoverage) * 100
+        const score = round(clamp(syntaxScore * 0.72 + graphScore * 0.2 + coverageRisk * 0.08))
+        if (score < thresholds.minScore) continue
+        const directHotEvidence = Array.isArray(complexity.hotEvidence) ? complexity.hotEvidence.slice(0, 12) : []
+        const confidence = directHotEvidence.length ? 'HIGH' : complexity.recursion ? 'LOW' : 'MEDIUM'
+        candidates.push({
+            id: String(node.id),
+            label: String(node.label || node.norm_label || node.id),
+            kind: String(node.symbol_kind || 'symbol'),
+            file,
+            startLine,
+            endLine,
+            classification: entry.classification,
+            score,
+            confidence,
+            localSyntax: {
+                score: syntaxScore,
+                timeRank: Number(complexity.timeRank || 0),
+                timeLabel: String(complexity.timeLabel || ''),
+                memoryRank: Number(complexity.memoryRank || 0),
+                memoryLabel: String(complexity.memoryLabel || ''),
+                cyclomatic: Number(complexity.cyclomatic || 0),
+                calls: Number(complexity.callCount || 0),
+                loops: Number(complexity.loops || 0),
+                maxLoopDepth: Number(complexity.maxLoopDepth || 0),
+                allocationsInLoops: Number(complexity.allocationsInLoops || 0),
+                copiesInLoops: Number(complexity.copiesInLoops || 0),
+                linearOpsInLoops: Number(complexity.linearOpsInLoops || 0),
+                sortsInLoops: Number(complexity.sortsInLoops || 0),
+                recursionInLoops: Number(complexity.recursionInLoops || 0),
+                recursion: complexity.recursion === true,
+            },
+            graphRisk: {...risk, score: graphScore},
+            testEvidence: actualCoverage != null
+                ? {actualCoverage, source: coverageRecord?.source || 'coverage report'}
+                : nearest
+                    ? {actualCoverage: 'NOT_AVAILABLE', staticReachable: true, nearestTest: nearest.test, distance: nearest.distance, confidence: nearest.confidence}
+                    : {actualCoverage: 'NOT_AVAILABLE', staticReachable: false},
+            reasons,
+            sourceEvidence: directHotEvidence,
+        })
+    }
+    candidates.sort((left, right) => right.score - left.score
+        || right.localSyntax.score - left.localSyntax.score
+        || right.graphRisk.fanIn - left.graphRisk.fanIn
+        || left.id.localeCompare(right.id))
+    const hotspots = candidates.slice(0, topN)
+    return {
+        ok: true,
+        modelVersion: 1,
+        complexityVersion: Number(graph?.complexityV) || 0,
+        scope: {
+            path: scope.path || null,
+            includeTests: options.includeTests === true,
+            includeClassified: options.includeClassified === true,
+        },
+        thresholds,
+        analyzedSymbols: eligible.length,
+        candidateSymbols: candidates.length,
+        coverage: measuredCoverage.size
+            ? {actualCoverage: 'AVAILABLE', measuredFiles: measuredCoverage.size, sources: coverageSources}
+            : {actualCoverage: 'NOT_AVAILABLE', staticReachability: staticTests ? {
+                reachableFiles: staticTests.reachableFiles,
+                productFiles: staticTests.productFiles,
+                truncated: staticTests.bounds.truncated,
+            } : null},
+        excluded,
+        hotspots,
+        bounds: {topN, returned: hotspots.length, totalCandidates: candidates.length, truncated: candidates.length > hotspots.length},
+        caveats: [
+            'Scores rank parser-derived local syntax cost; they are not profiler measurements.',
+            'Graph risk is reported separately and does not propagate loop complexity through callees.',
+            'Recursion bounds, CFG reachability, dead stores and taint flow are not inferred by this model.',
+        ],
+    }
+}

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

@@ -139,6 +139,21 @@ export async function runInternalAudit(repoPath, { graph, advisoryStorePath, ski
     }));
     unusedExportCount++;
   }
+  for (const symbol of dead.testOnlySymbols || []) {
+    if (isNonProductPath(symbol.file)) continue;
+    findings.push(makeFinding({
+      category: "unused",
+      rule: "test-only-symbol",
+      severity: "low",
+      confidence: symbol.publicApi ? "low" : "medium",
+      title: `Production symbol used only by tests: ${symbol.label}`,
+      detail: `${symbol.reason}. Static analysis cannot rule out external or reflective consumers, so review before removal.`,
+      file: symbol.file,
+      graphNodeId: symbol.id,
+      source: "internal",
+      fixHint: "verify production/config consumers, then keep as intentional test support or remove it together with obsolete tests",
+    }));
+  }
 
   // ---- supply-chain: installed packages × cached OSV advisories. 100% OFFLINE here — the cache is
   // refreshed only by the explicit repos:advisory-refresh action. Never blocks the rest of the audit.
@@ -247,6 +262,13 @@ export async function runInternalAudit(repoPath, { graph, advisoryStorePath, ski
   }
 
   const sorted = sortFindings(findings);
+  const dependencyFindings = sorted.filter((finding) => ["unused-dep", "missing-dep", "duplicate-dep"].includes(finding.rule));
+  const dependencyStatus = (graph.graphBuildMode && graph.graphBuildMode !== "full") || graph.graphBuildScope
+    ? "PARTIAL"
+    : "COMPLETE";
+  const importedPackages = new Set(externalImports
+    .filter((entry) => entry?.pkg && !entry.builtin && !entry.unresolved)
+    .map((entry) => `${entry.ecosystem || "npm"}:${entry.pkg}`));
   return {
     ok: true,
     engine: "internal",
@@ -276,10 +298,24 @@ export async function runInternalAudit(repoPath, { graph, advisoryStorePath, ski
     },
     summary: summarizeFindings(sorted),
     findings: sorted,
+    dependencyReport: {
+      status: dependencyStatus,
+      declared: dep.declared.size + goDep.declared.size + pyDep.declared.size,
+      importedPackages: importedPackages.size,
+      importRecords: externalImports.length,
+      unused: dependencyFindings.filter((finding) => finding.rule === "unused-dep").length,
+      missing: dependencyFindings.filter((finding) => finding.rule === "missing-dep").length,
+      duplicateDeclarations: dependencyFindings.filter((finding) => finding.rule === "duplicate-dep").length,
+      packageScopes: packageScopes.length,
+      reason: dependencyStatus === "COMPLETE"
+        ? "All discovered dependency manifests were compared with the complete indexed import set."
+        : "The dependency result is scoped to a partial graph and is not a repository-wide clean bill.",
+    },
     deadReport: {
       deadSymbols: dead.deadSymbols.filter((symbol) => !isNonProductPath(symbol.file)).length,
       deadFiles: actionableDeadFiles.length,
       unusedExports: unusedExportCount,
+      testOnlySymbols: (dead.testOnlySymbols || []).filter((symbol) => !isNonProductPath(symbol.file)).length,
     },
     conventionReachability: {
       count: conventionEvidence.length,

package/src/analysis/source-complexity.report.js

@@ -68,6 +68,11 @@ export function buildEvidence(stats) {
   if (stats.maxLoopDepth > 1) out.push(`loop depth ${stats.maxLoopDepth}`);
   if (stats.sorts) out.push(plural(stats.sorts, "sort", "sorts"));
   if (stats.spreadCopies) out.push(plural(stats.spreadCopies, "shallow copy", "shallow copies"));
+  if (stats.allocationsInLoops) out.push(`${plural(stats.allocationsInLoops, "allocation", "allocations")} inside iteration`);
+  if (stats.copiesInLoops) out.push(`${plural(stats.copiesInLoops, "copy", "copies")} inside iteration`);
+  if (stats.linearOpsInLoops) out.push(`${plural(stats.linearOpsInLoops, "linear operation", "linear operations")} inside iteration`);
+  if (stats.sortsInLoops) out.push(`${plural(stats.sortsInLoops, "sort", "sorts")} inside iteration`);
+  if (stats.recursionInLoops) out.push(`${plural(stats.recursionInLoops, "recursive call", "recursive calls")} inside iteration`);
   if (stats.branches) out.push(plural(stats.branches, "branch point", "branch points"));
   if (stats.awaits) out.push(plural(stats.awaits, "await boundary", "await boundaries"));
   if (stats.callCount) out.push(plural(stats.callCount, "call", "calls"));

package/src/analysis/source-complexity.walk.js

@@ -32,10 +32,23 @@ function createStats(parameters, family) {
     producerCalls: 0,
     recursion: false,
     maxSortLoopDepth: 0,
-    maxVariableAllocationDepth: 0
+    maxVariableAllocationDepth: 0,
+    allocationsInLoops: 0,
+    copiesInLoops: 0,
+    linearOpsInLoops: 0,
+    sortsInLoops: 0,
+    recursionInLoops: 0,
+    hotEvidence: []
   };
 }
 
+function recordHotEvidence(stats, node, kind, detail) {
+  if (stats.hotEvidence.length >= 24) return;
+  const line = node?.startPosition ? node.startPosition.row + 1 : 0;
+  if (stats.hotEvidence.some((item) => item.kind === kind && item.line === line)) return;
+  stats.hotEvidence.push({ kind, line, detail });
+}
+
 function shouldSkipNode(root, node, state) {
   if (sameNode(node, root)) return false;
   const type = String(node.type || "");
@@ -70,39 +83,74 @@ function recordBasicSignals(stats, node, facts) {
   if (RETURN_NODES.has(type)) stats.returns++;
   if (AWAIT_NODES.has(type)) { stats.awaits++; stats.asyncBoundaries++; }
   if (OBJECT_NODES.has(type)) stats.objectLiterals++;
-  if (FIXED_ALLOCATION_NODES.has(type)) stats.allocations++;
+  if (FIXED_ALLOCATION_NODES.has(type)) {
+    stats.allocations++;
+    if (currentDepth > 0) {
+      stats.allocationsInLoops++;
+      recordHotEvidence(stats, node, "allocation-in-loop", type);
+    }
+  }
   if (!VARIABLE_ALLOCATION_NODES.has(type)) return;
   stats.producerCalls++;
   stats.maxVariableAllocationDepth = Math.max(stats.maxVariableAllocationDepth, currentDepth + 1);
 }
 
-function recordSpread(stats, facts, parent) {
+function recordSpread(stats, node, facts, parent) {
   if (!SPREAD_NODES.has(facts.type) || /parameters|parameter_list/.test(String(parent?.type || ""))) return;
   stats.spreadCopies++;
   stats.linearOps++;
   stats.maxVariableAllocationDepth = Math.max(stats.maxVariableAllocationDepth, facts.currentDepth + 1);
+  if (facts.currentDepth > 0) {
+    stats.copiesInLoops++;
+    stats.linearOpsInLoops++;
+    recordHotEvidence(stats, node, "copy-in-loop", facts.type);
+  }
 }
 
-function recordCall(stats, facts, state, targetName) {
+function recordCall(stats, node, facts, state, targetName) {
   if (!facts.isCall) return;
   stats.callCount++;
   if (state.awaited || looksLikeIoCall(facts.nameAtCall)) stats.externalCalls++;
-  if (targetName && facts.normalizedCall === targetName) stats.recursion = true;
+  if (targetName && facts.normalizedCall === targetName) {
+    stats.recursion = true;
+    if (facts.currentDepth > 0) {
+      stats.recursionInLoops++;
+      recordHotEvidence(stats, node, "recursion-in-loop", facts.nameAtCall || targetName);
+    }
+  }
   if (facts.sortCall) {
     stats.sorts++;
     stats.maxSortLoopDepth = Math.max(stats.maxSortLoopDepth, facts.currentDepth);
-  } else if (LINEAR_CALLS.has(facts.normalizedCall) && !facts.iteratorCall) stats.linearOps++;
+    if (facts.currentDepth > 0) {
+      stats.sortsInLoops++;
+      recordHotEvidence(stats, node, "sort-in-loop", facts.nameAtCall || "sort");
+    }
+  } else if (LINEAR_CALLS.has(facts.normalizedCall) && !facts.iteratorCall) {
+    stats.linearOps++;
+    if (facts.currentDepth > 0) {
+      stats.linearOpsInLoops++;
+      recordHotEvidence(stats, node, "linear-scan-in-loop", facts.nameAtCall || "collection operation");
+    }
+  } else if (facts.iteratorCall && facts.currentDepth > 0) {
+    stats.linearOpsInLoops++;
+    recordHotEvidence(stats, node, "linear-scan-in-loop", facts.nameAtCall || "iterator");
+  }
   if (!facts.producerCall) return;
   stats.producerCalls++;
   stats.allocations++;
   stats.maxVariableAllocationDepth = Math.max(stats.maxVariableAllocationDepth, facts.currentDepth + 1);
+  if (facts.currentDepth > 0) {
+    stats.allocationsInLoops++;
+    recordHotEvidence(stats, node, "allocation-in-loop", facts.nameAtCall || "collection producer");
+  }
 }
 
-function recordLoop(stats, facts) {
+function recordLoop(stats, node, facts) {
   if (!facts.isLoop && !facts.iteratorCall) return facts.currentDepth;
   const nextDepth = facts.currentDepth + 1;
   stats.loops++;
   stats.maxLoopDepth = Math.max(stats.maxLoopDepth, nextDepth);
+  if (nextDepth > 1) recordHotEvidence(stats, node, "nested-iteration", `depth ${nextDepth}`);
   return nextDepth;
 }
 
@@ -121,9 +169,9 @@ function walkSyntax(root, node, state, context) {
   const callbackContext = state.callbackContext || ARGUMENT_NODES.has(String(parent?.type || ""));
   const facts = nodeFacts(node, state);
   recordBasicSignals(context.stats, node, facts);
-  recordSpread(context.stats, facts, parent);
-  recordCall(context.stats, facts, state, context.targetName);
-  const nextDepth = recordLoop(context.stats, facts);
+  recordSpread(context.stats, node, facts, parent);
+  recordCall(context.stats, node, facts, state, context.targetName);
+  const nextDepth = recordLoop(context.stats, node, facts);
   for (const child of children(node)) {
     const childIsArgs = ARGUMENT_NODES.has(String(child.type || ""));
     walkSyntax(root, child, {
@@ -165,6 +213,12 @@ export function analyzeSyntaxComplexity(root, { family = "", name = "" } = {}) {
     sorts: stats.sorts,
     linearOps: stats.linearOps,
     recursion: stats.recursion,
+    allocationsInLoops: stats.allocationsInLoops,
+    copiesInLoops: stats.copiesInLoops,
+    linearOpsInLoops: stats.linearOpsInLoops,
+    sortsInLoops: stats.sortsInLoops,
+    recursionInLoops: stats.recursionInLoops,
+    hotEvidence: stats.hotEvidence,
     ...labels,
     scope: "local",
     complexityScope: "local",

package/src/build-graph.js

@@ -14,7 +14,8 @@ import { graphHomeDir, graphOutDirForRepo, graphStorageKey, repoTopFolders, summ
 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";
+import { graphSchemaIsCurrent, repositoryFreshnessProbe, stampRepositoryFreshness } from "./graph/freshness-probe.js";
+import { buildLspPrecisionOverlay, invalidatePrecisionOverlay, precisionSummary } from "./precision/lsp-overlay.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.
@@ -26,6 +27,10 @@ const USE_BUILD_WORKER = false;
 // freeze the whole app on the main thread). 4 min is generous for very large repos.
 const BUILD_WORKER_TIMEOUT_MS = 4 * 60 * 1000;
 
+export function defaultPrecisionMode(env = process.env) {
+  return env?.WEAVATRIX_PRECISION === "off" ? "off" : "lsp";
+}
+
 function buildGraphInWorker(payload) {
   return new Promise((resolve, reject) => {
     let worker;
@@ -56,7 +61,7 @@ function buildGraphInWorker(payload) {
   });
 }
 
-async function buildAndWriteInProcess(repoPath, { mode, scope, graphJson, central }) {
+async function buildAndWriteInProcess(repoPath, { mode, scope, precision, graphJson, central }) {
   const { buildInternalGraph } = await import("./graph/internal-builder.js");
   // 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.
@@ -66,7 +71,7 @@ async function buildAndWriteInProcess(repoPath, { mode, scope, graphJson, centra
   if (mode === "full" && !scope && existsSync(graphJson)) {
     try {
       const existing = JSON.parse(readFileSync(graphJson, "utf8"));
-      if (existing.graphBuildMode === "full" && !existing.graphBuildScope) {
+      if (existing.graphBuildMode === "full" && !existing.graphBuildScope && graphSchemaIsCurrent(existing)) {
         refresh = await refreshGraphIncrementally(repoPath, existing, { buildGraph: buildInternalGraph });
         graph = refresh.graph;
       }
@@ -75,7 +80,7 @@ async function buildAndWriteInProcess(repoPath, { mode, scope, graphJson, centra
   if (!graph && mode !== "full" && !scope && existsSync(graphJson)) {
     try {
       const existing = JSON.parse(readFileSync(graphJson, "utf8"));
-      if (existing.graphBuildMode === mode && existing.graphRevision) {
+      if (existing.graphBuildMode === mode && existing.graphRevision && graphSchemaIsCurrent(existing)) {
         const snapshot = snapshotRepository(repoPath);
         if (snapshot.revision === existing.graphRevision) {
           graph = existing;
@@ -93,6 +98,9 @@ async function buildAndWriteInProcess(repoPath, { mode, scope, graphJson, centra
   if (scope) graph = filterGraphByScope(graph, scope);
   graph.graphBuildMode = mode;
   graph.graphBuildScope = scope || "";
+  const requestedPrecision = precision === "off" ? "off" : "lsp";
+  const precisionModeChanged = graph.graphPrecisionMode !== requestedPrecision;
+  graph.graphPrecisionMode = requestedPrecision;
   const probeAfter = scope ? null : repositoryFreshnessProbe(repoPath);
   const stableProbe = probeBefore && probeAfter === probeBefore ? probeAfter : null;
   const freshnessMetadataChanged = stampRepositoryFreshness(graph, stableProbe, mode);
@@ -100,20 +108,50 @@ async function buildAndWriteInProcess(repoPath, { mode, scope, graphJson, centra
   // 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) {
+  if (refresh?.kind !== "none" || freshnessMetadataChanged || precisionModeChanged) {
     mkdirSync(central, { recursive: true });
     atomicWriteFileSync(graphJson, JSON.stringify(graph), "utf8");
   }
+  mkdirSync(central, { recursive: true });
+  let precisionOverlay = await buildLspPrecisionOverlay({
+    repoRoot: repoPath,
+    graph,
+    graphPath: graphJson,
+    mode: requestedPrecision,
+  });
+  if (requestedPrecision === "lsp") {
+    try {
+      // LSP deliberately runs after graph serialization and can outlive the initial snapshot. A
+      // complete second content snapshot catches source/config add-delete races (including Git
+      // assume-unchanged paths) that a status-only token cannot prove away.
+      if (snapshotRepository(repoPath).revision !== graph.graphRevision) {
+        precisionOverlay = invalidatePrecisionOverlay(graphJson, graph);
+      }
+    } catch {
+      precisionOverlay = invalidatePrecisionOverlay(
+        graphJson,
+        graph,
+        "repository freshness could not be verified after semantic precision",
+      );
+    }
+  }
   return {
     nodes: graph.nodes.length,
     links: graph.links.length,
     communities: summarizeCommunities(graphJson),
     hotspots: summarizeHotspots(graphJson),
     refresh,
+    precision: precisionSummary(precisionOverlay),
   };
 }
 
-export async function buildGraphForRepo(repoPath, { mode = "full", scope = "", outDir, graphHome } = {}) {
+export async function buildGraphForRepo(repoPath, {
+  mode = "full",
+  scope = "",
+  precision = defaultPrecisionMode(),
+  outDir,
+  graphHome,
+} = {}) {
   if (!existsSync(repoPath)) return { ok: false, error: "Repo path not found", builder: "internal" };
   const registryHome = graphHome || graphHomeDir();
   const canonicalDir = graphHome ? join(registryHome, graphStorageKey(repoPath)) : graphOutDirForRepo(repoPath);
@@ -126,11 +164,11 @@ export async function buildGraphForRepo(repoPath, { mode = "full", scope = "", o
     // 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 build = () => USE_BUILD_WORKER
-      ? buildGraphInWorker({ repoPath, mode, scope, graphJson, central }).catch((e) => {
-          if (e && e.workerStartFailed) return buildAndWriteInProcess(repoPath, { mode, scope, graphJson, central });
+      ? buildGraphInWorker({ repoPath, mode, scope, precision, graphJson, central }).catch((e) => {
+          if (e && e.workerStartFailed) return buildAndWriteInProcess(repoPath, { mode, scope, precision, graphJson, central });
           throw e;
         })
-      : buildAndWriteInProcess(repoPath, { mode, scope, graphJson, central });
+      : buildAndWriteInProcess(repoPath, { mode, scope, precision, 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);
@@ -154,7 +192,8 @@ export async function buildGraphForRepo(repoPath, { mode = "full", scope = "", o
       communities: built.communities,
       hotspots: built.hotspots,
       refresh: built.refresh,
-      log: `built-in builder: ${built.nodes} nodes, ${built.links} links (${built.refresh?.kind || "full"}: ${built.refresh?.reason || "build"})`
+      precision: built.precision,
+      log: `built-in builder: ${built.nodes} nodes, ${built.links} static links (${built.refresh?.kind || "full"}: ${built.refresh?.reason || "build"}); semantic precision ${built.precision?.state || "UNAVAILABLE"}, ${built.precision?.verifiedEdges || 0} EXACT_LSP edge(s)`
     };
   } catch (error) {
     return { ok: false, error: `graph build failed: ${error.message}`, builder: "internal" };

package/src/graph/build-worker.js

@@ -8,20 +8,40 @@ import { parentPort, workerData } from "node:worker_threads";
 import { buildInternalGraph } from "./internal-builder.js";
 import { filterGraphForMode, filterGraphByScope, summarizeCommunities, summarizeHotspots } from "./layout.js";
 import { atomicWriteFileSync } from "./file-lock.js";
+import { snapshotRepository } from "./incremental-refresh.js";
+import { buildLspPrecisionOverlay, invalidatePrecisionOverlay, precisionSummary } from "../precision/lsp-overlay.js";
 
 (async () => {
-  const { repoPath, mode, scope, graphJson, central } = workerData || {};
+  const { repoPath, mode, scope, precision, graphJson, central } = workerData || {};
   try {
     let graph = await buildInternalGraph(repoPath);
     if (mode === "no-tests" || mode === "tests-only") graph = filterGraphForMode(graph, mode, { repoRoot: repoPath });
     if (scope) graph = filterGraphByScope(graph, scope);
+    graph.graphBuildMode = mode;
+    graph.graphBuildScope = scope || "";
+    graph.graphPrecisionMode = precision === "off" ? "off" : "lsp";
     atomicWriteFileSync(graphJson, JSON.stringify(graph), "utf8");
+    let overlay = await buildLspPrecisionOverlay({repoRoot: repoPath, graph, graphPath: graphJson, mode: graph.graphPrecisionMode});
+    if (graph.graphPrecisionMode === "lsp") {
+      try {
+        if (snapshotRepository(repoPath).revision !== graph.graphRevision) {
+          overlay = invalidatePrecisionOverlay(graphJson, graph);
+        }
+      } catch {
+        overlay = invalidatePrecisionOverlay(
+          graphJson,
+          graph,
+          "repository freshness could not be verified after semantic precision",
+        );
+      }
+    }
     parentPort.postMessage({
       ok: true,
       nodes: graph.nodes.length,
       links: graph.links.length,
       communities: summarizeCommunities(graphJson),
       hotspots: summarizeHotspots(graphJson),
+      precision: precisionSummary(overlay),
     });
   } catch (e) {
     parentPort.postMessage({ ok: false, error: (e && e.message) || String(e) });

package/src/graph/builder/lang-java.js

@@ -83,6 +83,7 @@ export default {
       const id = nodeIds.has(base) ? `${base}:c${nameNode.startPosition.column + 1}` : base;
       addSym(nameNode.text, lineOf(nameNode), callable, {
         ...extra,
+        selectionNode: nameNode,
         ...(id === base ? {} : { idSuffix: id.slice(base.length) }),
       });
       return nodeIds.has(id) ? id : null;

package/src/graph/builder/lang-js.js

@@ -93,6 +93,7 @@ export default {
       const exportStatement = !isMethod && exportStatementOf(cap.node);
       addSym(cap.node.text, cap.node.startPosition.row + 1, cap.name !== "class", {
         sourceNode: cap.node.parent,
+        selectionNode: cap.node,
         ...(exportStatement ? { exported: true } : {}),
         ...(isMethod ? methodMetadata(cap.node) : { symbolKind: cap.name === "class" ? "class" : "function", moduleDeclaration: isModuleDeclaration(cap.node) })
       });
@@ -111,6 +112,7 @@ export default {
       const exported = isExportedDecl(cap.node);
       addSym(nameNode.text, nameNode.startPosition.row + 1, !!(val && CALLABLE.test(val.type)), {
         sourceNode: val || cap.node,
+        selectionNode: nameNode,
         ...(exported ? { exported: true } : {}),
         symbolKind: "variable",
         moduleDeclaration: true
@@ -248,6 +250,28 @@ export default {
         local: typedDeclaration[2],
         typeOnly: typedDeclaration[1] !== "enum",
       });
+      const defaultValue = field(node, "value");
+      if (defaultValue?.type === "object") {
+        // Service facades commonly expose local helpers through `export default { getSchema,
+        // save: persist }`. Record the public member -> local binding instead of treating the
+        // object as an opaque default export.
+        recordJsExport({kind: "facade-root", exported: "default", local: "default", typeOnly: false});
+        for (const property of defaultValue.namedChildren || []) {
+          if (["shorthand_property_identifier", "shorthand_property_identifier_pattern"].includes(property.type)) {
+            recordJsExport({kind: "facade-member", member: property.text, local: property.text, typeOnly: false});
+            markExported(property.text);
+            continue;
+          }
+          if (property.type !== "pair") continue;
+          const key = field(property, "key");
+          const value = field(property, "value");
+          if (!key || value?.type !== "identifier") continue;
+          const member = key.text.replace(/^['"`]|['"`]$/g, "");
+          if (!/^[A-Za-z_$][\w$]*$/.test(member)) continue;
+          recordJsExport({kind: "facade-member", member, local: value.text, typeOnly: false});
+          markExported(value.text);
+        }
+      }
     }
 
     // ---- export markers beyond declarations: `export { a, b }`, `export default X`, CJS module.exports ----