weavatrix 0.2.3 → 0.2.5

package/src/mcp/tools-health.mjs

@@ -1,7 +1,7 @@
 // Health tools: clone detection, the internal audit, community/module overviews, coverage mapping
 // and the HTTP endpoint inventory. Hot-reloadable (re-imported by catalog.mjs on change).
 import {spawnSync} from 'node:child_process'
-import {degreeOf, rawGraph} from './graph-context.mjs'
+import {degreeOf, rawGraph, effectiveRawGraph} from './graph-context.mjs'
 import {computeDuplicates} from '../analysis/duplicates.js'
 import {runInternalAudit} from '../analysis/internal-audit.js'
 import {classifyChangeImpact} from '../analysis/change-classification.js'
@@ -11,14 +11,16 @@ import {summarizeCommunities, aggregateGraph} from '../analysis/graph-analysis.j
 import {detectEndpoints} from '../analysis/endpoints.js'
 import {computeStaticTestReachability} from '../analysis/static-test-reachability.js'
 import {computeDeadCodeReview} from '../analysis/dead-code-review.js'
+import {computeHotPathReview} from '../analysis/hot-path-review.js'
 import {collectNonRuntimeRoots, collectPackageScopes, collectSourceTexts, readRepoJson} from '../analysis/internal-audit.collect.js'
 import {entryFiles} from '../analysis/internal-audit.reach.js'
 import {buildInternalGraph} from '../graph/internal-builder.js'
 import {resolveGitCommit, withGitRefCheckout} from '../analysis/git-ref-graph.js'
 import {childProcessEnv} from '../child-env.js'
 import {toolResult} from './tool-result.mjs'
-import {createPathClassifier} from '../path-classification.js'
+import {createPathClassifier, hasPathClass} from '../path-classification.js'
 import {createRepoBoundary} from '../repo-path.js'
+import {filterGraphForMode} from '../graph/graph-filter.js'
 
 const NON_PRODUCT_DUPLICATE_CLASSES = new Set(['generated', 'mock', 'story', 'docs', 'benchmark', 'temp'])
 const fragmentEligible = (fragment, {tokMin, skipTests, includeClassified}) => {
@@ -52,7 +54,7 @@ function groupClones(data, {simMin, tokMin, mode, skipTests, includeClassified})
 export function tFindDuplicates(g, args, ctx) {
     if (!ctx.repoRoot) return 'Duplicate scan needs the repo root (not provided to this server).'
     const simMin = Math.min(100, Math.max(50, Number(args.min_similarity) || 80))
-    const tokMin = Math.min(400, Math.max(30, Number(args.min_tokens) || 50))
+    const tokMin = Math.min(400, Math.max(12, Number(args.min_tokens) || 50))
     const mode = args.mode === 'strict' ? 'strict' : 'renamed'
     const skipTests = args.include_tests ? false : true
     const includeClassified = args.include_classified === true || args.include_non_product === true
@@ -60,7 +62,7 @@ export function tFindDuplicates(g, args, ctx) {
     // semantic mode: same-name symbols across files, ranked by size — LOW similarity is the signal
     // (same name, drifted behavior). Token-clone pairing is skipped entirely.
     if (args.mode === 'semantic') {
-        const data = computeDuplicates(ctx.repoRoot, ctx.graphPath, {nameTwins: true})
+        const data = computeDuplicates(ctx.repoRoot, ctx.graphPath, {nameTwins: true, minTokens: tokMin})
         const frags = data.frags
         const candidates = []
         for (const twin of data.nameTwins || []) {
@@ -95,13 +97,14 @@ export function tFindDuplicates(g, args, ctx) {
         })
         return `Found ${candidates.length} actionable same-name pair(s) across files (semantic mode; one closest clone and/or farthest collision per name). Top ${top.length}:\n\n${lines.join('\n\n')}\n\nThese are review candidates, not automatic refactors. Use read_source on both sites before changing code.`
     }
-    const data = computeDuplicates(ctx.repoRoot, ctx.graphPath, {includeStrings})
+    const data = computeDuplicates(ctx.repoRoot, ctx.graphPath, {includeStrings, minTokens: tokMin})
     const groups = groupClones(data, {simMin, tokMin, mode, skipTests, includeClassified})
+    const smallPolicy = tokMin < 30 ? ' Small fragments below 30 tokens require at least 95% similarity and two shared bounded fingerprints.' : ''
     const suppressed = data.frags.filter((fragment) => !fragmentEligible(fragment, {tokMin, skipTests, includeClassified})).length
     const suppressionNote = suppressed && !includeClassified
         ? ` ${suppressed} fragment(s) classified as tests/e2e/generated/mock/story/docs/benchmark/temp or matched by .weavatrix.json exclude were suppressed; pass include_classified:true (and include_tests:true for tests) to inspect them explicitly.`
         : ''
-    if (!groups.length) return `No clones at ≥${simMin}% similarity / ≥${tokMin} tokens (${mode} mode). Try lowering the thresholds.${suppressionNote}`
+    if (!groups.length) return `No clones at ≥${simMin}% similarity / ≥${tokMin} tokens (${mode} mode). Try lowering the thresholds.${smallPolicy}${suppressionNote}`
     const top = groups.slice(0, Math.min(30, Math.max(1, Number(args.top_n) || 15)))
     const lines = top.map((grp, k) => {
         const isStr = grp.members.some((f) => f.kind === 'string')
@@ -109,7 +112,7 @@ export function tFindDuplicates(g, args, ctx) {
         const sites = grp.members.slice(0, 8).map((f) => `     ${f.file}:${f.start}-${f.end}`)
         return [head, ...sites].join('\n')
     })
-    return `Found ${groups.length} clone group(s) (${mode} mode, ≥${simMin}%, ≥${tokMin} tok${includeStrings ? ', incl. large string literals' : ''}). Top ${top.length}:\n\n${lines.join('\n\n')}\n\nUse read_source on any two sites to compare, then extract shared logic.${suppressionNote}`
+    return `Found ${groups.length} clone group(s) (${mode} mode, ≥${simMin}%, ≥${tokMin} tok${includeStrings ? ', incl. large string literals' : ''}). Top ${top.length}:\n\n${lines.join('\n\n')}\n\nUse read_source on any two sites to compare, then extract shared logic.${smallPolicy}${suppressionNote}`
 }
 
 // Focused dead-code review queue. Unlike the broad run_audit surface, this includes functions and
@@ -117,7 +120,7 @@ export function tFindDuplicates(g, args, ctx) {
 // candidates. It never returns an automatic-delete verdict.
 export function tFindDeadCode(g, args, ctx) {
     if (!ctx.repoRoot) return 'Dead-code review needs the repo root (not provided to this server).'
-    const graph = rawGraph(ctx)
+    const graph = effectiveRawGraph(ctx)
     const boundary = createRepoBoundary(ctx.repoRoot)
     const pkg = readRepoJson(boundary, 'package.json') || {}
     const rules = readRepoJson(boundary, '.weavatrix-deps.json') || {}
@@ -226,10 +229,12 @@ const formatOrdinaryAudit = (audit, args, findings = audit.findings, heading = n
     const summary = summarizeFindings(findings)
     const sev = summary.bySeverity
     const bycat = summary.byCategory
+    const deps = audit.dependencyReport || {}
     return [
         heading,
         `Internal audit of ${audit.repo} (${audit.scanned.files} files, ${audit.scanned.symbols} symbols, ${audit.scanned.externalImports} external imports; malware scan: ${audit.scanned.malwareScanMode}).`,
         ...auditConventionLines(audit),
+        `Dependency manifests: ${deps.status || 'UNKNOWN'} — checked ${deps.declared ?? audit.scanned.manifestDeps ?? 0} declared package(s) against ${deps.importRecords ?? audit.scanned.externalImports ?? 0} external import record(s); unused ${deps.unused ?? 'unknown'}, missing ${deps.missing ?? 'unknown'}, duplicate declarations ${deps.duplicateDeclarations ?? 'unknown'}.`,
         `Scoped severity: critical ${sev.critical}, high ${sev.high}, medium ${sev.medium}, low ${sev.low}, info ${sev.info}. Scoped categories: unused ${bycat.unused}, structure ${bycat.structure}, vulnerability ${bycat.vulnerability}, malware ${bycat.malware}.`,
         `Repository-level ${auditChecksLine(audit)}`,
         '',
@@ -323,7 +328,12 @@ async function runAuditWithBaseline(args, ctx, currentGraph) {
     }
 
     const baseline = await withGitRefCheckout(ctx.repoRoot, resolved.commit, async (checkout) => {
-        const graph = await buildInternalGraph(checkout)
+        let graph = await buildInternalGraph(checkout)
+        const currentMode = ['full', 'no-tests', 'tests-only'].includes(currentGraph?.graphBuildMode)
+            ? currentGraph.graphBuildMode : 'full'
+        if (currentMode !== 'full') graph = filterGraphForMode(graph, currentMode, {repoRoot: checkout})
+        graph.graphBuildMode = currentMode
+        graph.graphBuildScope = ''
         return runInternalAudit(checkout, {graph, skipMalwareScan: true})
     })
     if (!baseline.ok || !baseline.value?.ok) {
@@ -385,7 +395,7 @@ export async function tRunAudit(g, args, ctx) {
     if (!ctx.repoRoot) return 'Audit needs the repo root (not provided to this server).'
     if (args.base_ref) return runAuditWithBaseline(args, ctx, rawGraph(ctx))
     const audit = await runInternalAudit(ctx.repoRoot, {
-        graph: rawGraph(ctx),
+        graph: effectiveRawGraph(ctx),
         skipMalwareScan: !args.include_malware_scan, // greps installed packages — slow, so opt-in
     })
     if (!audit.ok) return `Audit failed: ${audit.error}`
@@ -412,11 +422,13 @@ export async function tRunAudit(g, args, ctx) {
     const shown = filtered.slice(0, max)
     const sev = audit.summary.bySeverity
     const bycat = audit.summary.byCategory
+    const deps = audit.dependencyReport || {}
     const check = (name, state) => `${name} ${state?.status || 'ERROR'}${state?.detail ? ` — ${state.detail}` : ''}`
     return [
         `Internal audit of ${audit.repo} (${audit.scanned.files} files, ${audit.scanned.symbols} symbols, ${audit.scanned.externalImports} external imports; malware scan: ${audit.scanned.malwareScanMode}).`,
         `Severity: critical ${sev.critical}, high ${sev.high}, medium ${sev.medium}, low ${sev.low}, info ${sev.info}. Categories: unused ${bycat.unused}, structure ${bycat.structure}, vulnerability ${bycat.vulnerability}, malware ${bycat.malware}.`,
         `Structure: ${audit.structureReport?.runtimeCycles ?? audit.structureReport?.cycles ?? 0} runtime cycle(s), ${audit.structureReport?.compileTimeCouplings ?? audit.structureReport?.typeCouplings ?? 0} compile-time coupling group(s), ${audit.structureReport?.orphans ?? 0} orphan(s); import edges: ${audit.structureReport?.runtimeImportEdges ?? audit.structureReport?.importEdges ?? 0} runtime + ${audit.structureReport?.typeOnlyImportEdges ?? 0} type-only + ${audit.structureReport?.compileOnlyImportEdges ?? 0} compile-only. Dead: ${audit.deadReport.deadFiles} file(s), ${audit.deadReport.unusedExports} unused export(s).`,
+        `Dependency manifests: ${deps.status || 'UNKNOWN'} — checked ${deps.declared ?? audit.scanned.manifestDeps ?? 0} declared package(s) against ${deps.importRecords ?? audit.scanned.externalImports ?? 0} external import record(s); unused ${deps.unused ?? 'unknown'}, missing ${deps.missing ?? 'unknown'}, duplicate declarations ${deps.duplicateDeclarations ?? 'unknown'}.`,
         ...auditConventionLines(audit),
         `Checks: ${check('OSV', audit.checks?.osv)}; ${check('malware', audit.checks?.malware)}. A NOT_CHECKED/PARTIAL/ERROR check is incomplete or unknown, never a clean zero.`,
         ``,
@@ -440,7 +452,36 @@ export function tListCommunities(g, args, ctx) {
 // Folder-level architecture map: modules (top-two path segments) with file/symbol counts and the
 // strongest module→module dependencies. Pure graph aggregation — no filesystem reads.
 export function tModuleMap(g, args, ctx) {
-    const agg = aggregateGraph(rawGraph(ctx), null)
+    const graph = rawGraph(ctx)
+    const testsOnly = graph.graphBuildMode === 'tests-only'
+    const includeNonProduct = args.include_non_product === true || testsOnly
+    const classifier = createPathClassifier(ctx?.repoRoot || null)
+    const nonProductFiles = new Set()
+    const classifiedFiles = new Set()
+    if (!includeNonProduct) {
+        for (const node of graph.nodes || []) {
+            if (!node?.source_file) continue
+            const sourceFile = String(node.source_file)
+            if (classifiedFiles.has(sourceFile)) continue
+            classifiedFiles.add(sourceFile)
+            const explanation = classifier.explain(sourceFile)
+            if (explanation.excluded || hasPathClass(explanation, 'test', 'e2e', 'generated', 'mock', 'story', 'docs', 'benchmark', 'temp')) {
+                nonProductFiles.add(sourceFile)
+            }
+        }
+    }
+    const visibleGraph = includeNonProduct || nonProductFiles.size === 0 ? graph : (() => {
+        const keep = new Set((graph.nodes || [])
+            .filter((node) => !node?.source_file || !nonProductFiles.has(String(node.source_file)))
+            .map((node) => String(node.id)))
+        const endpoint = (value) => String(value && typeof value === 'object' ? value.id : value)
+        return {
+            ...graph,
+            nodes: (graph.nodes || []).filter((node) => keep.has(String(node.id))),
+            links: (graph.links || []).filter((link) => keep.has(endpoint(link.source)) && keep.has(endpoint(link.target))),
+        }
+    })()
+    const agg = aggregateGraph(visibleGraph, null)
     const topN = Math.max(1, Math.min(60, Number(args.top_n) || 25))
     const mods = agg.modules.slice(0, topN)
     const edges = agg.moduleEdges.slice(0, Math.min(50, topN * 2))
@@ -458,6 +499,11 @@ export function tModuleMap(g, args, ctx) {
     collectCompileEdges(agg.compileOnlyModuleEdges, 'compileOnly')
     const compiled = [...compileEdges.values()].sort((a, b) => b.count - a.count).slice(0, Math.min(50, topN * 2))
     return [
+        testsOnly
+            ? 'Scope: tests-only graph; classified test/e2e/fixture surfaces are retained automatically.'
+            : includeNonProduct
+            ? 'Scope: all indexed files, including classified non-product surfaces.'
+            : `Scope: production-only (default); excluded ${nonProductFiles.size} classified test/fixture/benchmark/generated/docs file(s). Pass include_non_product:true for the complete graph.`,
         `Module map: ${agg.totals.files} files in ${agg.modules.length} folder-modules, ${agg.totals.moduleEdges} runtime module dependencies and ${agg.totals.compileTimeModuleEdges || 0} compile-time dependencies (${agg.totals.typeOnlyModuleEdges || 0} type-only, ${agg.totals.compileOnlyModuleEdges || 0} compile-only). Top ${mods.length}:`,
         ...mods.map((m) => `  ${m.name} — ${m.fileCount} files, ${m.symbolCount} symbols`),
         ``,
@@ -469,6 +515,61 @@ export function tModuleMap(g, args, ctx) {
     ].filter((line) => line != null).join('\n')
 }
 
+// Parser-backed local cost review. This keeps syntax, graph coupling and measured/static test
+// evidence as separate fields so callers cannot mistake a ranking heuristic for profiler output.
+export function tHotPathReview(g, args, ctx) {
+    const review = computeHotPathReview(rawGraph(ctx), {
+        repoRoot: ctx?.repoRoot || null,
+        path: args.path,
+        includeTests: args.include_tests === true,
+        includeClassified: args.include_classified === true,
+        topN: args.top_n,
+        cyclomaticThreshold: args.cyclomatic_threshold,
+        callThreshold: args.call_threshold,
+        loopDepthThreshold: args.loop_depth_threshold,
+        timeRankThreshold: args.time_rank_threshold,
+        minScore: args.min_score,
+    })
+    if (!review.ok) return toolResult(`Hot-path review refused: ${review.error}.`, review)
+    const pct = (value) => typeof value === 'number' ? `${Math.round(value * 100)}%` : String(value || 'NOT_AVAILABLE')
+    const coverageLine = review.coverage.actualCoverage === 'AVAILABLE'
+        ? `Measured coverage: ${review.coverage.measuredFiles} file(s) from ${review.coverage.sources.join(', ') || 'coverage report'}.`
+        : review.coverage.staticReachability
+            ? `actualCoverage: NOT_AVAILABLE; static test reachability ${review.coverage.staticReachability.reachableFiles}/${review.coverage.staticReachability.productFiles} product file(s).`
+            : 'actualCoverage: NOT_AVAILABLE; no measured or static test evidence was available.'
+    const text = [
+        `Local hot-path review: ${review.candidateSymbols} candidate(s) from ${review.analyzedSymbols} analyzed symbol(s); showing ${review.hotspots.length}.`,
+        `Thresholds: time rank >=${review.thresholds.timeRank}, cyclomatic >=${review.thresholds.cyclomatic}, calls >=${review.thresholds.calls}, loop depth >=${review.thresholds.loopDepth}, score >=${review.thresholds.minScore}.`,
+        coverageLine,
+        'Local syntax cost and graph coupling are separate. Scores are review priority, not measured runtime.',
+        '',
+        ...(review.hotspots.length ? review.hotspots.flatMap((item, index) => {
+            const tests = item.testEvidence.actualCoverage === 'NOT_AVAILABLE'
+                ? item.testEvidence.staticReachable ? `static-test d${item.testEvidence.distance}` : 'no-static-test-path'
+                : `coverage ${pct(item.testEvidence.actualCoverage)}`
+            const pointer = `${item.file}${item.startLine ? `:${item.startLine}${item.endLine > item.startLine ? `-${item.endLine}` : ''}` : ''}`
+            const evidence = item.sourceEvidence.length
+                ? `\n       evidence: ${item.sourceEvidence.map((entry) => `${entry.kind}@L${entry.line || '?'}${entry.detail ? ` (${entry.detail})` : ''}`).join('; ')}`
+                : ''
+            return [
+                `  ${String(index + 1).padStart(2)}. score ${String(item.score).padStart(5)}  syntax ${String(item.localSyntax.score).padStart(5)}  graph ${String(item.graphRisk.score).padStart(5)}  ${item.confidence}`,
+                `      ${item.label}  (${pointer}; fan-in ${item.graphRisk.fanIn}, fan-out ${item.graphRisk.fanOut}; ${tests})`,
+                `       ${item.reasons.slice(0, 5).join('; ')}${evidence}`,
+            ]
+        }) : ['  (none at the selected thresholds)']),
+        review.bounds.truncated ? `... +${review.bounds.totalCandidates - review.bounds.returned} more (raise top_n, min_score, or narrow path).` : null,
+        '',
+        'Caveat: no interprocedural Big-O, recursion-bound, CFG, dead-store or taint-flow claim is made.',
+    ].filter((line) => line != null).join('\n')
+    return toolResult(text, review, {
+        completeness: {
+            symbols: 'COMPLETE_FOR_INDEXED_GRAPH',
+            output: review.bounds.truncated ? 'BOUNDED' : 'COMPLETE',
+            coverage: review.coverage.actualCoverage,
+        },
+    })
+}
+
 // Coverage × graph: map an EXISTING coverage report (istanbul/lcov/coverage.py/Go — read offline,
 // tests are never executed here) onto files and symbols, then rank refactor risk as
 // connectivity × uncovered share. Pairs with get_dependents: many dependents + low coverage ⇒ write

package/src/mcp/tools-impact.mjs

@@ -31,9 +31,11 @@ function reverseReach(g, seeds, maxDepth) {
             }
             const depthKey = compileOnly ? 'compileDepth' : 'runtimeDepth'
             const relationKey = compileOnly ? 'compileRelation' : 'runtimeRelation'
+            const provenanceKey = compileOnly ? 'compileProvenance' : 'runtimeProvenance'
             if (entry[depthKey] != null && entry[depthKey] <= depth) continue
             entry[depthKey] = depth
             entry[relationKey] = e.relation || 'rel'
+            entry[provenanceKey] = e.provenance || 'UNKNOWN'
             states.set(id, entry)
             frontier.push({id, depth, compileOnly})
         }
@@ -43,6 +45,7 @@ function reverseReach(g, seeds, maxDepth) {
         depth: entry.runtimeDepth ?? entry.compileDepth ?? 0,
         compileOnly: entry.runtimeDepth == null,
         relation: entry.runtimeDepth != null ? entry.runtimeRelation : entry.compileRelation,
+        provenance: entry.runtimeDepth != null ? entry.runtimeProvenance : entry.compileProvenance,
     }]))
 }
 
@@ -56,7 +59,7 @@ const impactKind = (entry) => {
 // Transitive blast-radius: who is affected if this node changes. Walks REVERSE dependency edges
 // (calls/imports/inherits — not structural `contains`) out to `depth`. For a symbol, also seeds its
 // containing file, because importers depend on the file rather than the individual symbol.
-export function tGetDependents(g, {label, depth = 3, max_nodes = 40} = {}) {
+export function tGetDependents(g, {label, depth = 3, max_nodes = 40, include_container_importers = false} = {}) {
     const info = resolveNodeInfo(g, label)
     const n = info.node
     if (!n) return `No node found matching "${label}".`
@@ -66,7 +69,7 @@ export function tGetDependents(g, {label, depth = 3, max_nodes = 40} = {}) {
     const id = String(n.id)
     const seeds = new Set([id])
     let containingFile = null
-    if (isSymbol(id)) {
+    if (include_container_importers === true && isSymbol(id)) {
         const container = (g.inn.get(id) || []).find((e) => e.relation === 'contains')
         if (container) {
             containingFile = String(container.id)
@@ -85,18 +88,22 @@ export function tGetDependents(g, {label, depth = 3, max_nodes = 40} = {}) {
     return [
         note,
         `Dependents of ${n.label ?? id} (reverse calls/imports/inherits, depth ≤${maxDepth}): ${ranked.length} found (${runtimeCount} runtime, ${compileCount} compile-time-only), showing ${shown.length} by proximity + connectivity.`,
-        containingFile ? `Includes importers of its containing file ${labelOf(g, containingFile)}.` : null,
-        ...shown.map((r) => `  [d${r.d} ${impactKind(r.entry)}] ${r.entry.relation || 'rel'}  ${labelOf(g, r.id)}  (deg ${r.deg})  [${r.id}]`),
+        containingFile ? `Includes importers of its containing file ${labelOf(g, containingFile)} by explicit request.` : null,
+        ...shown.map((r) => `  [d${r.d} ${impactKind(r.entry)}] ${r.entry.relation || 'rel'} [${r.entry.provenance || 'UNKNOWN'}]  ${labelOf(g, r.id)}  (deg ${r.deg})  [${r.id}]`),
     ].filter(Boolean).join('\n')
 }
 
 // Re-query the last rebuild's before/after pair (graph.prev.json vs graph.json), optionally scoped.
 export async function tGraphDiff(g, args, ctx) {
+    const current = rawGraph(ctx)
+    const currentMode = ['full', 'no-tests', 'tests-only'].includes(current?.graphBuildMode)
+        ? current.graphBuildMode
+        : 'full'
     let prev
     let baselineLabel = 'previous rebuild state'
     if (args.base_ref) {
         if (!ctx.repoRoot) return 'A Git-ref graph diff needs the active repository root.'
-        const built = await buildGraphAtGitRef(ctx.repoRoot, args.base_ref)
+        const built = await buildGraphAtGitRef(ctx.repoRoot, args.base_ref, {mode: currentMode})
         if (!built.ok) return `Could not build the baseline graph: ${built.error}`
         prev = built.graph
         baselineLabel = `${built.ref} (${built.commit.slice(0, 12)})`
@@ -106,7 +113,17 @@ export async function tGraphDiff(g, args, ctx) {
             return `No previous graph state at ${prevPath} — pass base_ref (for example HEAD~1 or main), or run rebuild_graph to save one automatically.`
         }
     }
-    const current = rawGraph(ctx)
+    if (!args.base_ref) {
+        const previousMode = ['full', 'no-tests', 'tests-only'].includes(prev?.graphBuildMode)
+            ? prev.graphBuildMode
+            : 'full'
+        if (previousMode !== currentMode) {
+            return [
+                `Graph diff unavailable: previous graph mode is ${previousMode}, current graph mode is ${currentMode}.`,
+                'Those node/edge universes are not comparable. Run rebuild_graph once more in the same mode, or pass base_ref to build a mode-matched immutable baseline.',
+            ].join('\n')
+        }
+    }
     const filter = args.path ? String(args.path).replace(/\\/g, '/') : null
     const scope = (graph) => filter ? {
         nodes: (graph.nodes || []).filter((n) => String(n.id).startsWith(filter)),
@@ -118,6 +135,7 @@ export async function tGraphDiff(g, args, ctx) {
     } : graph
     return [
         `Graph diff (${baselineLabel} → current)${filter ? `, scoped to ${filter}` : ''}:`,
+        `Build mode: ${currentMode}`,
         formatGraphDiff(diffGraphs(scope(prev), scope(current)))
     ].join('\n')
 }

package/src/mcp/tools-source.mjs

@@ -0,0 +1,237 @@
+import {readFileSync, statSync} from 'node:fs'
+import {resolveRepoPath} from '../repo-path.js'
+import {isStructuralRelation} from '../graph/relations.js'
+import {querySymbolPrecision} from '../precision/symbol-query.js'
+import {toolResult} from './tool-result.mjs'
+import {degreeOf, isSymbol, labelOf, resolveNodeInfo} from './graph-context.mjs'
+
+const MAX_EXCERPT_CHARS = 4_000
+const MAX_LOCATION_SAMPLES = 5
+const MAX_GRAPH_OCCURRENCES = 100
+
+const boundedInteger = (value, fallback, minimum, maximum) => {
+    const number = Number(value)
+    return Math.max(minimum, Math.min(maximum, Number.isFinite(number) ? Math.floor(number) : fallback))
+}
+
+const sourceLine = (node) => {
+    const match = /L(\d+)/.exec(String(node?.source_location || ''))
+    return match ? Number(match[1]) : 1
+}
+
+function candidateNodes(g, query, limit = 20) {
+    const text = String(query || '').trim().toLowerCase()
+    if (!text) return []
+    const exact = g.byLabel.get(text)
+    const nodes = exact?.length ? exact : g.nodes.filter((node) =>
+        String(node.id).toLowerCase().includes(text) || String(node.label || '').toLowerCase().includes(text))
+    return nodes.slice(0, limit).map((node) => ({id: String(node.id), label: String(node.label || node.id), file: node.source_file || null}))
+}
+
+function excerpt(repoRoot, file, focusLine, contextLines) {
+    const resolved = resolveRepoPath(repoRoot, file)
+    if (!resolved.ok) return null
+    let size
+    try { size = statSync(resolved.path).size } catch { return null }
+    if (size > 2 * 1024 * 1024) return null
+    let lines
+    try { lines = readFileSync(resolved.path, 'utf8').split(/\r?\n/) } catch { return null }
+    const focus = Math.max(1, Math.min(lines.length, Number(focusLine) || 1))
+    const startLine = Math.max(1, focus - contextLines)
+    const endLine = Math.min(lines.length, focus + contextLines)
+    const rawText = lines.slice(startLine - 1, endLine).join('\n')
+    return {
+        file,
+        focusLine: focus,
+        startLine,
+        endLine,
+        text: rawText.length > MAX_EXCERPT_CHARS ? `${rawText.slice(0, MAX_EXCERPT_CHARS)}\n… [excerpt truncated]` : rawText,
+        truncated: rawText.length > MAX_EXCERPT_CHARS,
+    }
+}
+
+function reverseImpact(g, targetId, depth = 3, cap = 40) {
+    const seen = new Map([[targetId, 0]])
+    const queue = [targetId]
+    for (let cursor = 0; cursor < queue.length; cursor++) {
+        const current = queue[cursor]
+        const currentDepth = seen.get(current)
+        if (currentDepth >= depth) continue
+        for (const edge of g.inn.get(current) || []) {
+            if (isStructuralRelation(edge.relation) || edge.barrelProxy === true) continue
+            const id = String(edge.id)
+            if (seen.has(id)) continue
+            seen.set(id, currentDepth + 1)
+            queue.push(id)
+        }
+    }
+    return [...seen.entries()]
+        .filter(([id]) => id !== targetId)
+        .map(([id, distance]) => ({id, label: labelOf(g, id), distance, degree: degreeOf(g, id)}))
+        .sort((left, right) => left.distance - right.distance || right.degree - left.degree)
+        .slice(0, cap)
+}
+
+function graphOccurrences(g, targetId) {
+    const all = (g.inn.get(targetId) || [])
+        .filter((edge) => !isStructuralRelation(edge.relation) && edge.barrelProxy !== true)
+        .map((edge) => ({
+            source: String(edge.id),
+            label: labelOf(g, edge.id),
+            relation: edge.relation || 'references',
+            provenance: edge.provenance || 'UNKNOWN',
+            ...(Number.isInteger(edge.line) ? {line: edge.line} : {}),
+            ...(edge.typeOnly === true ? {typeOnly: true} : {}),
+            ...(edge.compileOnly === true ? {compileOnly: true} : {}),
+        }))
+    return {total: all.length, shown: all.slice(0, MAX_GRAPH_OCCURRENCES)}
+}
+
+function groupLocations(g, locations, cap) {
+    const groups = new Map()
+    for (const location of locations) {
+        const source = String(location.source || location.file || '')
+        if (!source) continue
+        const node = g.byId.get(source)
+        const file = String(location.file || node?.source_file || (isSymbol(source) ? source.split('#')[0] : source))
+        let group = groups.get(source)
+        if (!group) {
+            group = {id: source, label: String(node?.label || source), file, count: 0, classifications: {}, locations: []}
+            groups.set(source, group)
+        }
+        group.count++
+        const classification = String(location.classification || 'unknown')
+        group.classifications[classification] = (group.classifications[classification] || 0) + 1
+        if (group.locations.length < MAX_LOCATION_SAMPLES) group.locations.push({
+          line: location.line,
+          character: location.character,
+          ...(Number.isInteger(location.endLine) ? {endLine: location.endLine} : {}),
+          ...(Number.isInteger(location.endCharacter) ? {endCharacter: location.endCharacter} : {}),
+          classification,
+        })
+    }
+    const all = [...groups.values()].sort((left, right) => right.count - left.count || left.file.localeCompare(right.file) || left.id.localeCompare(right.id))
+    return {all, shown: all.slice(0, cap)}
+}
+
+function textFor(result) {
+    if (result.status === 'NOT_FOUND') return `No symbol found matching "${result.query}".`
+    if (result.status === 'AMBIGUOUS') return [
+        `Symbol "${result.query}" is ambiguous (${result.candidates.length} candidate(s) shown). Supply an exact node ID:`,
+        ...result.candidates.map((candidate) => `  ${candidate.label}  [${candidate.id}]`),
+    ].join('\n')
+    const definition = result.definition
+    const lines = [
+        `Symbol inspection: ${definition.label}  [${definition.id}]`,
+        `Definition: ${definition.file}:${definition.line}`,
+        `Evidence: ${result.evidence.state}${result.evidence.cached ? ' (cache hit)' : ''}; ${result.exact.occurrences} exact reference occurrence(s) in ${result.exact.files} file(s) / ${result.exact.containers} container(s).`,
+        `Graph: ${result.graph.occurrenceTotal} direct occurrence edge(s) (${result.graph.occurrences.length} shown); ${result.graph.impact.length} dependent(s) shown.`,
+    ]
+    if (result.evidence.reason) lines.push(`Completeness: ${result.evidence.reason}`)
+    if (result.exact.zeroReferences) lines.push('Exact result: zero non-declaration references in the completely covered project universe.')
+    if (result.exact.groups.length) {
+        lines.push('Reference containers:')
+        for (const group of result.exact.groups) lines.push(`  ${group.count} site(s)  ${group.label}  [${group.id}]`)
+    }
+    if (result.source.definition) {
+        const source = result.source.definition
+        lines.push('', `Definition source (${source.file}:${source.startLine}-${source.endLine}):`, source.text)
+    }
+    for (const source of result.source.callers) {
+        lines.push('', `Caller source (${source.file}:${source.startLine}-${source.endLine}, focus ${source.focusLine}):`, source.text)
+    }
+    return lines.join('\n')
+}
+
+export async function tInspectSymbol(g, args = {}, ctx = {}) {
+    const query = String(args.label || '').trim()
+    const info = resolveNodeInfo(g, query)
+    if (!info.node) return toolResult(textFor({status: 'NOT_FOUND', query}), {status: 'NOT_FOUND', query})
+    if (info.matches > 1 && !g.byId.has(query)) {
+        const result = {status: 'AMBIGUOUS', query, candidates: candidateNodes(g, query)}
+        return toolResult(textFor(result), result, {completeness: {status: 'blocked', reason: 'ambiguous symbol'}})
+    }
+    const node = info.node
+    const targetId = String(node.id)
+    if (!isSymbol(targetId)) {
+        const result = {status: 'UNSUPPORTED', query, candidates: [{id: targetId, label: node.label || targetId, file: node.source_file || targetId}]}
+        return toolResult('inspect_symbol requires a symbol node, not a file node.', result)
+    }
+    const maxReferences = boundedInteger(args.max_references, 1_000, 1, 5_000)
+    const maxContainers = boundedInteger(args.max_containers, 15, 1, 50)
+    const contextLines = boundedInteger(args.context_lines, 8, 0, 40)
+    const timeoutMs = boundedInteger(args.timeout_ms, 30_000, 1_000, 60_000)
+    const precision = ['auto', 'graph', 'lsp'].includes(args.precision) ? args.precision : 'auto'
+    const shouldQuery = precision === 'lsp' || (precision === 'auto' && g.graphPrecisionMode !== 'off')
+    let overlay = null
+    let cached = false
+    let elapsedMs = 0
+    let queryError = null
+    if (shouldQuery) {
+        try {
+            const queryResult = await querySymbolPrecision({repoRoot: ctx.repoRoot, graphPath: ctx.graphPath, targetId, maxReferences, timeoutMs})
+            overlay = queryResult.overlay
+            cached = queryResult.cached
+            elapsedMs = queryResult.elapsedMs
+        } catch (error) {
+            queryError = error?.message || 'exact symbol query failed'
+        }
+    }
+    const locations = Array.isArray(overlay?.locations) ? overlay.locations : []
+    const grouped = groupLocations(g, locations, maxContainers)
+    const files = new Set(locations.map((location) => String(location.file || '')).filter(Boolean))
+    let state = 'GRAPH_ONLY'
+    if (overlay?.state === 'COMPLETE') state = 'EXACT'
+    else if (overlay?.state === 'PARTIAL') state = 'PARTIAL'
+    else if (overlay?.state === 'OFF') state = 'OFF'
+    else if (shouldQuery) state = 'UNAVAILABLE'
+    const reason = queryError || overlay?.reason || (shouldQuery ? null : 'semantic precision was not requested')
+    const graphRefs = graphOccurrences(g, targetId)
+    const impact = reverseImpact(g, targetId)
+    const definition = {
+        id: targetId,
+        label: String(node.label || targetId),
+        kind: String(node.symbol_kind || 'symbol'),
+        file: String(node.source_file || targetId.split('#')[0]),
+        line: sourceLine(node),
+        ...(node.source_range ? {range: node.source_range} : {}),
+        ...(node.complexity ? {complexity: node.complexity} : {}),
+    }
+    const definitionSource = excerpt(ctx.repoRoot, definition.file, definition.line, contextLines)
+    const callerSources = grouped.shown.slice(0, 5).map((group) => excerpt(ctx.repoRoot, group.file, group.locations[0]?.line || 1, contextLines)).filter(Boolean)
+    const result = {
+        status: 'OK',
+        definition,
+        evidence: {state, cached, elapsedMs, reason, provider: overlay?.engines?.[0]?.provider || null},
+        exact: {
+            occurrences: locations.length,
+            occurrencesWithDefinition: locations.length + 1,
+            files: files.size,
+            containers: grouped.all.length,
+            groups: grouped.shown,
+            zeroReferences: overlay?.noReferenceSymbols?.includes(targetId) === true,
+            capped: overlay?.coverage?.truncated === true || grouped.all.length > grouped.shown.length,
+        },
+        graph: {
+            occurrences: graphRefs.shown,
+            occurrenceTotal: graphRefs.total,
+            occurrencesCapped: graphRefs.total > graphRefs.shown.length,
+            impact,
+        },
+        source: {definition: definitionSource, callers: callerSources},
+    }
+    const warnings = state === 'PARTIAL' || state === 'UNAVAILABLE'
+        ? [{code: 'SYMBOL_PRECISION_INCOMPLETE', message: reason || `semantic precision is ${state.toLowerCase()}`}]
+        : []
+    return toolResult(textFor(result), result, {
+        warnings,
+        completeness: {
+            status: state === 'EXACT' && !result.exact.capped ? 'complete' : state.toLowerCase(),
+            referenceLimit: maxReferences,
+            containerLimit: maxContainers,
+            returnedContainers: grouped.shown.length,
+            locationSamplesPerContainer: MAX_LOCATION_SAMPLES,
+            graphOccurrenceLimit: MAX_GRAPH_OCCURRENCES,
+        },
+    })
+}