weavatrix 0.1.4 → 0.2.0

package/src/mcp/tools-graph.mjs

@@ -3,7 +3,7 @@
 // staleness probe in graph-context. Hot-reloadable (re-imported by catalog.mjs on change).
 import {
     isSymbol, degreeOf, labelOf, connList,
-    resolveNodeInfo, resolveNode, ambiguityNote, findSeeds, undirectedNeighbors,
+    resolveNodeInfo, resolveNode, ambiguityNote, findSeeds, resolveSeedFiles, undirectedNeighbors,
     graphStaleness, fileStalenessNote,
 } from './graph-context.mjs'
 
@@ -40,6 +40,7 @@ export function tGraphStats(g, ctx) {
         `- Nodes: ${g.nodes.length} (${files} files, ${symbols} symbols)`,
         `- Edges: ${g.links.length}`,
         g.edgeTypesV ? `- Typed-edge metadata: v${g.edgeTypesV} (${typeOnlyEdges} type-only, ${compileOnlyEdges} compile-only edges)` : `- Typed-edge metadata: unavailable (rebuild_graph required)`,
+        g.barrelResolutionV ? `- Barrel resolution: v${g.barrelResolutionV} (semantic tools look through JS/TS re-export facades)` : `- Barrel resolution: unavailable (rebuild_graph required for JS/TS barrel transparency)`,
         `- Relations: ${fmt(relCount)}`,
         Object.keys(confCount).length ? `- Confidence: ${fmt(confCount)}` : null,
         `- Communities: ${comm.size} (top by size: ${topComm.map(([c, n]) => `#${c}=${n}`).join(', ')})`,
@@ -58,6 +59,8 @@ export function tGetNode(g, {label} = {}, ctx) {
     const drift = ctx ? fileStalenessNote(ctx, n.source_file || (isSymbol(id) ? id.split('#')[0] : id)) : null
     const outs = g.out.get(id) || []
     const ins = g.inn.get(id) || []
+    const semanticOuts = connList(outs)
+    const semanticIns = connList(ins)
     const sample = (list, dir) =>
         list
             .slice(0, 12)
@@ -70,7 +73,7 @@ export function tGetNode(g, {label} = {}, ctx) {
         `- kind: ${isSymbol(id) ? 'symbol' : 'file'}${n.file_type ? ` (${n.file_type})` : ''}`,
         n.source_file ? `- source: ${n.source_file}${n.source_location ? ` ${n.source_location}` : ''}` : null,
         n.community != null ? `- community: ${n.community}` : null,
-        `- degree: ${outs.length + ins.length} (out ${outs.length}, in ${ins.length})`,
+        `- semantic degree: ${semanticOuts.length + semanticIns.length} (out ${semanticOuts.length}, in ${semanticIns.length})${outs.length + ins.length !== semanticOuts.length + semanticIns.length ? `; ${outs.length + ins.length} physical/structural edges retained` : ''}`,
         `Outgoing:\n${sample(outs, 'out')}`,
         `Incoming:\n${sample(ins, 'in')}`,
         drift,
@@ -151,8 +154,14 @@ export function tGetCommunity(g, {community_id} = {}) {
 // A plain BFS/DFS flood dumps every reached node (thousands on a real graph) at near-zero signal.
 // Instead: traverse to record reach + distance-from-seed, then show only the closest, most-connected
 // slice as a coherent subgraph (edges kept only among shown nodes). Honest about what was trimmed.
-export function tQueryGraph(g, {question, mode = 'bfs', depth = 3, context_filter, token_budget = 2000} = {}) {
-    const seeds = findSeeds(g, question, 6)
+export function tQueryGraph(g, {question, mode = 'bfs', depth = 3, context_filter, seed_files, augment_seeds = false, token_budget = 2000} = {}) {
+    const pinned = resolveSeedFiles(g, seed_files)
+    // Exact seed files are a control surface, not a hint: by default they disable fuzzy keyword seeds.
+    // Callers can opt back into augmentation when they explicitly want both behaviors.
+    const automatic = pinned.seeds.length && augment_seeds !== true
+        ? []
+        : findSeeds(g, question, Math.max(0, 8 - pinned.seeds.length))
+    const seeds = [...pinned.seeds, ...automatic.filter((node) => !pinned.seeds.some((seed) => String(seed.id) === String(node.id)))]
     if (!seeds.length) return `No nodes matched "${question}".`
     const maxDepth = Math.max(1, Math.min(6, Number(depth) || 3))
     const ctx = Array.isArray(context_filter) && context_filter.length ? new Set(context_filter.map((c) => String(c).toLowerCase())) : null
@@ -161,7 +170,6 @@ export function tQueryGraph(g, {question, mode = 'bfs', depth = 3, context_filte
     // node budget scales gently with the token budget; edges follow the surviving nodes.
     const nodeBudget = Math.max(20, Math.min(120, Math.round((Number(token_budget) || 2000) / 40)))
     const depthOf = new Map() // id -> shortest distance from any seed
-    const edges = []
     const start = seeds.map((s) => String(s.id))
     if (mode === 'dfs') {
         const stack = start.map((id) => ({id, d: 0}))
@@ -174,7 +182,6 @@ export function tQueryGraph(g, {question, mode = 'bfs', depth = 3, context_filte
             if (d >= maxDepth) continue
             for (const [nid, rel] of undirectedNeighbors(g, id)) {
                 if (!relOk(rel)) continue
-                edges.push([id, rel, nid])
                 if (!seen.has(nid)) stack.push({id: nid, d: d + 1})
             }
         }
@@ -186,7 +193,6 @@ export function tQueryGraph(g, {question, mode = 'bfs', depth = 3, context_filte
             for (const id of frontier)
                 for (const [nid, rel] of undirectedNeighbors(g, id)) {
                     if (!relOk(rel)) continue
-                    edges.push([id, rel, nid])
                     if (!depthOf.has(nid)) {
                         depthOf.set(nid, d + 1)
                         next.push(nid)
@@ -203,24 +209,29 @@ export function tQueryGraph(g, {question, mode = 'bfs', depth = 3, context_filte
     const shownIds = new Set(shown.map((n) => n.id))
     const edgeSeen = new Set()
     const shownEdges = []
-    for (const [s, r, t] of edges) {
-        if (!shownIds.has(s) || !shownIds.has(t)) continue
-        const key = `${s}|${r}|${t}`
-        if (edgeSeen.has(key)) continue
-        edgeSeen.add(key)
-        shownEdges.push([s, r, t])
+    for (const source of shownIds) {
+        for (const edge of g.out.get(source) || []) {
+            const target = String(edge.id)
+            if (edge.barrelProxy === true || !shownIds.has(target) || !relOk(edge.relation)) continue
+            const key = `${source}|${edge.relation}|${target}`
+            if (edgeSeen.has(key)) continue
+            edgeSeen.add(key)
+            shownEdges.push([source, edge.relation, target])
+            if (shownEdges.length >= 160) break
+        }
         if (shownEdges.length >= 160) break
     }
     const head = [
         `Query: "${question}" (${mode}, depth ${maxDepth}${ctx ? `, context ${[...ctx].join('/')}` : ''})`,
         `Seeds: ${seeds.map((s) => s.label ?? s.id).join(', ')}`,
+        pinned.missing.length ? `Unresolved pinned seed files: ${pinned.missing.join(', ')}` : null,
         `Reached ${depthOf.size} nodes; showing ${shown.length} closest by proximity + connectivity, ${shownEdges.length} edges among them.`,
         ``,
         `Nodes:`,
     ]
     const nodeLines = shown.map((n) => `  [d${n.d}] ${labelOf(g, n.id)}  (deg ${n.deg})  [${n.id}]`)
     const edgeLines = ['', 'Edges:', ...shownEdges.map(([s, r, t]) => `  ${labelOf(g, s)} --${r || 'rel'}--> ${labelOf(g, t)}`)]
-    let text = [...head, ...nodeLines, ...edgeLines].join('\n')
+    let text = [...head.filter(Boolean), ...nodeLines, ...edgeLines].join('\n')
     if (text.length > charBudget) text = text.slice(0, charBudget) + `\n... (truncated to ~${token_budget} tokens)`
     return text
 }

package/src/mcp/tools-health.mjs

@@ -1,15 +1,38 @@
 // 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 {computeDuplicates} from '../analysis/duplicates.js'
 import {runInternalAudit} from '../analysis/internal-audit.js'
+import {classifyChangeImpact} from '../analysis/change-classification.js'
+import {compareAuditDebt, normalizeAuditScopeFiles, scopeAuditFindings} from '../analysis/audit-debt.js'
+import {summarizeFindings} from '../analysis/findings.js'
 import {summarizeCommunities, aggregateGraph} from '../analysis/graph-analysis.js'
 import {detectEndpoints} from '../analysis/endpoints.js'
+import {computeStaticTestReachability} from '../analysis/static-test-reachability.js'
+import {computeDeadCodeReview} from '../analysis/dead-code-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 {createRepoBoundary} from '../repo-path.js'
+
+const NON_PRODUCT_DUPLICATE_CLASSES = new Set(['generated', 'mock', 'story', 'docs', 'benchmark', 'temp'])
+const fragmentEligible = (fragment, {tokMin, skipTests, includeClassified}) => {
+    if (fragment.n < tokMin) return false
+    const classes = new Set(fragment.classes || [])
+    if (skipTests && (fragment.test || classes.has('test') || classes.has('e2e'))) return false
+    if (!includeClassified && (fragment.excluded || [...classes].some((name) => NON_PRODUCT_DUPLICATE_CLASSES.has(name)))) return false
+    return true
+}
 
 // Group clone pairs into union-find families.
-function groupClones(data, {simMin, tokMin, mode, skipTests}) {
+function groupClones(data, {simMin, tokMin, mode, skipTests, includeClassified}) {
     const frags = data.frags || []
-    const elig = (i) => frags[i].n >= tokMin && (!skipTests || !frags[i].test)
+    const elig = (i) => fragmentEligible(frags[i], {tokMin, skipTests, includeClassified})
     const pairs = (data.modes?.[mode] || []).filter(([i, j, s]) => s >= simMin && elig(i) && elig(j))
     const parent = new Map()
     const find = (x) => { let r = x; while (parent.has(r) && parent.get(r) !== r) r = parent.get(r); return r }
@@ -32,6 +55,7 @@ export function tFindDuplicates(g, args, ctx) {
     const tokMin = Math.min(400, Math.max(30, 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
     const includeStrings = !!args.include_strings
     // 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.
@@ -40,7 +64,7 @@ export function tFindDuplicates(g, args, ctx) {
         const frags = data.frags
         const candidates = []
         for (const twin of data.nameTwins || []) {
-            const allowed = new Set(twin.members.filter((i) => (!skipTests || !frags[i].test) && frags[i].n >= tokMin))
+            const allowed = new Set(twin.members.filter((i) => fragmentEligible(frags[i], {tokMin, skipTests, includeClassified})))
             const pairs = (twin.pairs || []).filter((p) => allowed.has(p.a) && allowed.has(p.b))
             if (!pairs.length) continue
             const closest = pairs.slice().sort((a, b) => b.similarity - a.similarity)[0]
@@ -72,8 +96,12 @@ 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 groups = groupClones(data, {simMin, tokMin, mode, skipTests})
-    if (!groups.length) return `No clones at ≥${simMin}% similarity / ≥${tokMin} tokens (${mode} mode). Try lowering the thresholds.`
+    const groups = groupClones(data, {simMin, tokMin, mode, skipTests, includeClassified})
+    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}`
     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')
@@ -81,21 +109,300 @@ 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.`
+    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}`
+}
+
+// Focused dead-code review queue. Unlike the broad run_audit surface, this includes functions and
+// methods with bounded source-free evidence, and explicitly demotes framework/dynamic/public API
+// 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 boundary = createRepoBoundary(ctx.repoRoot)
+    const pkg = readRepoJson(boundary, 'package.json') || {}
+    const rules = readRepoJson(boundary, '.weavatrix-deps.json') || {}
+    const sources = collectSourceTexts(ctx.repoRoot, graph)
+    const dynamicTargets = new Set((graph.externalImports || [])
+        .filter((entry) => entry?.dynamic && entry?.target)
+        .map((entry) => String(entry.target).replace(/\\/g, '/')))
+    const frameworkEvidence = []
+    const entries = entryFiles(graph, collectPackageScopes(ctx.repoRoot, pkg), dynamicTargets, {
+        declaredEntries: rules.entrypoints || rules.entries || [],
+        sources,
+        conventionEvidence: frameworkEvidence,
+    })
+    for (const root of collectNonRuntimeRoots(ctx.repoRoot, rules)) {
+        for (const file of sources.keys()) if (file === root || file.startsWith(`${root}/`)) entries.add(file)
+    }
+
+    const review = computeDeadCodeReview(graph, sources, {
+        entrySet: entries,
+        dynamicTargets,
+        frameworkEvidence,
+        pathClassifier: createPathClassifier(ctx.repoRoot),
+        includeTests: args.include_tests === true,
+        includeClassified: args.include_classified === true,
+        minConfidence: args.min_confidence,
+        path: args.path,
+        kinds: args.kinds,
+    })
+    const max = Math.max(1, Math.min(100, Number(args.top_n) || 30))
+    const shown = review.candidates.slice(0, max)
+    const counts = review.totals.byConfidence
+    const suppression = Object.entries(review.suppressed)
+        .filter(([, count]) => count)
+        .map(([name, count]) => `${name} ${count}`)
+        .join(', ')
+    const lines = shown.map((candidate, index) => {
+        const subject = candidate.kind === 'file'
+            ? candidate.file
+            : `${candidate.owner ? `${candidate.owner}.` : ''}${candidate.symbol || candidate.id}`
+        const where = `${candidate.file}${candidate.line ? `:${candidate.line}` : ''}`
+        return [
+            `${index + 1}. [${candidate.confidence}/${candidate.classification}] ${subject} (${where})`,
+            `     evidence: ${candidate.evidence.map((item) => item.fact).join(' ')}`,
+            candidate.caveats.length ? `     caution: ${candidate.caveats.join(' ')}` : null,
+        ].filter(Boolean).join('\n')
+    })
+    const text = [
+        `Dead-code review: ${shown.length} of ${review.candidates.length} candidate(s) shown (high ${counts.high}, medium ${counts.medium}, low ${counts.low}).`,
+        `Verdict: REVIEW_REQUIRED. This is static evidence, never permission to auto-delete or bulk-delete.`,
+        suppression ? `Suppressed by current filters: ${suppression}.` : null,
+        review.suppressed.confidence ? 'Use min_confidence=low only when public/framework/dynamic candidates need explicit review.' : null,
+        '',
+        ...(lines.length ? lines : ['No candidates matched the current production/path/kind/confidence filters.']),
+        '',
+        'Before removal: read_source, get_dependents, exact search, framework/config/manifest inspection, and the repository tests.',
+    ].filter((line) => line != null).join('\n')
+    return toolResult(text, {
+        status: 'COMPLETE',
+        verdict: 'REVIEW_REQUIRED',
+        candidates: shown,
+        totals: review.totals,
+        suppressed: review.suppressed,
+        repoSignals: review.repoSignals,
+        policy: review.policy,
+    }, {
+        warnings: review.warnings,
+        page: {shown: shown.length, total: review.candidates.length, capped: shown.length < review.candidates.length},
+        completeness: {status: 'COMPLETE'},
+    })
 }
 
 const SEVERITY_RANK = {critical: 0, high: 1, medium: 2, low: 3, info: 4}
 
+export function formatAuditFinding(f) {
+    const where = f.file ? `  (${f.file}${f.symbol ? ` ${f.symbol}` : ''})` : f.package ? `  (pkg ${f.package}${f.version ? `@${f.version}` : ''}${f.manifest ? `; ${f.manifest}` : ''})` : ''
+    return `  [${f.severity}/${f.confidence || '?'}] ${f.rule}: ${f.title}${where}${f.reason ? `\n      reason: ${f.reason}` : ''}${f.cycleRoute ? `\n      route: ${f.cycleRoute}` : ''}${f.fixHint ? `\n      fix: ${f.fixHint}` : ''}`
+}
+
+const auditFilter = (audit, args, findings = audit.findings) => {
+    const minSev = SEVERITY_RANK[args.min_severity] ?? 4
+    const category = args.category ? String(args.category) : null
+    return findings
+        .filter((finding) => (SEVERITY_RANK[finding.severity] ?? 4) <= minSev)
+        .filter((finding) => !category || finding.category === category)
+}
+
+const auditChecksLine = (audit) => {
+    const check = (name, state) => `${name} ${state?.status || 'ERROR'}${state?.detail ? ` — ${state.detail}` : ''}`
+    return `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.`
+}
+
+const auditConventionLines = (audit) => {
+    const entries = audit.conventionReachability?.entries || []
+    if (!entries.length) return []
+    return [
+        `Convention reachability: ${audit.conventionReachability.count} framework-managed file(s) are external entry points, not orphan/dead findings${audit.conventionReachability.truncated ? ' (evidence capped)' : ''}:`,
+        ...entries.slice(0, 5).map((entry) => `  [${entry.confidence}] ${entry.file} — ${entry.marker}: ${entry.reason}`),
+        audit.conventionReachability.count > 5 ? `  … +${audit.conventionReachability.count - 5} more in bounded JSON result data` : null,
+    ].filter((line) => line != null)
+}
+
+const formatOrdinaryAudit = (audit, args, findings = audit.findings, heading = null) => {
+    const max = Math.max(1, Math.min(100, Number(args.max_findings) || 30))
+    const filtered = auditFilter(audit, args, findings)
+    const shown = filtered.slice(0, max)
+    const summary = summarizeFindings(findings)
+    const sev = summary.bySeverity
+    const bycat = summary.byCategory
+    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),
+        `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)}`,
+        '',
+        `Showing ${shown.length} of ${filtered.length} finding(s)${args.category ? ` in category "${args.category}"` : ''}${args.min_severity ? ` at ≥${args.min_severity}` : ''}:`,
+        ...shown.map(formatAuditFinding),
+        filtered.length > shown.length ? `  … +${filtered.length - shown.length} more (raise max_findings or filter by category/min_severity)` : null,
+    ].filter((line) => line != null).join('\n')
+}
+
+const gitUntracked = (repoRoot) => {
+    const result = spawnSync('git', ['-C', repoRoot, 'ls-files', '--others', '--exclude-standard'], {
+        encoding: 'utf8', timeout: 8000, maxBuffer: 2 * 1024 * 1024, env: childProcessEnv(), windowsHide: true,
+    })
+    if (result.status !== 0) return {
+        ok: false,
+        files: [],
+        error: String(result.stderr || result.error?.message || 'git ls-files failed').trim(),
+    }
+    return {
+        ok: true,
+        files: String(result.stdout || '').split(/\r?\n/).map((line) => line.trim()).filter(Boolean),
+        error: null,
+    }
+}
+
+const pathsFromClassification = (classification) => [...new Set(classification.files
+    .flatMap((file) => [file.oldPath, file.newPath])
+    .filter((file) => file && file !== '(diff unavailable)'))]
+    .sort((left, right) => left.localeCompare(right))
+
+const formatDebtFinding = (finding, state) => `  [${state}] ${formatAuditFinding(finding).trimStart()}`
+
+async function runAuditWithBaseline(args, ctx, currentGraph) {
+    const resolved = resolveGitCommit(ctx.repoRoot, args.base_ref)
+    if (!resolved.ok) return toolResult(`Audit baseline unavailable: ${resolved.error}.`, {
+        status: 'INVALID', comparison: {status: 'UNAVAILABLE', reason: resolved.error}, findings: [],
+    }, {completeness: {status: 'PARTIAL', reason: resolved.error}})
+
+    let currentAudit
+    try {
+        currentAudit = await runInternalAudit(ctx.repoRoot, {
+            graph: currentGraph,
+            skipMalwareScan: !args.include_malware_scan,
+        })
+    } catch (error) {
+        const reason = error instanceof Error ? error.message : String(error)
+        return toolResult(`Audit failed while building the current graph: ${reason}`, {
+            status: 'ERROR', comparison: {status: 'UNAVAILABLE', reason}, findings: [],
+        }, {completeness: {status: 'PARTIAL', reason}})
+    }
+    if (!currentAudit.ok) return toolResult(`Audit failed: ${currentAudit.error}`, {
+        status: 'ERROR', comparison: {status: 'UNAVAILABLE', reason: currentAudit.error}, findings: [],
+    }, {completeness: {status: 'PARTIAL', reason: currentAudit.error}})
+
+    const normalized = normalizeAuditScopeFiles(args.changed_files)
+    if (!normalized.ok) return toolResult(`Audit scope invalid: ${normalized.error}.`, {
+        status: 'INVALID', comparison: {status: 'UNAVAILABLE', reason: normalized.error}, findings: [],
+    }, {completeness: {status: 'PARTIAL', reason: normalized.error}})
+    let changedFiles = normalized.files
+    let completeChangeSet = false
+    let scopeSource = 'explicit changed_files'
+    let changeEvidence = null
+    if (changedFiles == null) {
+        completeChangeSet = true
+        const untracked = gitUntracked(ctx.repoRoot)
+        if (!untracked.ok) {
+            return toolResult(`Audit comparison stopped: untracked-file discovery failed (${untracked.error}). Pass changed_files explicitly to establish the scope.`, {
+                status: 'PARTIAL', comparison: {status: 'UNAVAILABLE', reason: untracked.error}, findings: [],
+            }, {completeness: {status: 'PARTIAL', reason: untracked.error}})
+        }
+        changeEvidence = classifyChangeImpact({
+            repoRoot: ctx.repoRoot,
+            graph: currentGraph,
+            base: resolved.commit,
+            files: untracked.files,
+        })
+        if (!changeEvidence.ok || changeEvidence.bounds?.truncated) {
+            const reason = changeEvidence.reasons.join(' ')
+            return toolResult(`Audit comparison stopped: changed-file derivation against ${resolved.ref} was incomplete. ${reason} Pass changed_files explicitly to establish a complete scope.`, {
+                status: 'PARTIAL', comparison: {status: 'UNAVAILABLE', reason}, findings: [], changeEvidence,
+            }, {completeness: {status: 'PARTIAL', reason}})
+        }
+        changedFiles = pathsFromClassification(changeEvidence)
+        if (changedFiles.length > 500) {
+            const reason = `derived changed-file scope contains ${changedFiles.length} files, above the 500-file comparison bound`
+            return toolResult(`Audit comparison stopped: ${reason}. Pass a narrower explicit changed_files scope.`, {
+                status: 'PARTIAL', comparison: {status: 'UNAVAILABLE', reason}, findings: [], changeEvidence,
+            }, {completeness: {status: 'PARTIAL', reason}})
+        }
+        scopeSource = `git diff ${resolved.commit.slice(0, 12)}…working-tree`
+    }
+
+    const baseline = await withGitRefCheckout(ctx.repoRoot, resolved.commit, async (checkout) => {
+        const graph = await buildInternalGraph(checkout)
+        return runInternalAudit(checkout, {graph, skipMalwareScan: true})
+    })
+    if (!baseline.ok || !baseline.value?.ok) {
+        const reason = baseline.error || baseline.value?.error || 'baseline audit failed'
+        return toolResult(`Audit baseline unavailable: ${reason}.`, {
+            status: 'ERROR', comparison: {status: 'UNAVAILABLE', reason}, findings: [],
+        }, {completeness: {status: 'PARTIAL', reason}})
+    }
+
+    const comparison = compareAuditDebt(currentAudit, baseline.value, changedFiles, {completeChangeSet})
+    const mode = ['new', 'existing', 'all'].includes(args.debt) ? args.debt : 'new'
+    const selectedRaw = mode === 'new' ? comparison.new : mode === 'existing' ? comparison.existing : comparison.all
+    const selected = auditFilter(currentAudit, args, selectedRaw)
+    const max = Math.max(1, Math.min(100, Number(args.max_findings) || 30))
+    const shown = selected.slice(0, max)
+    const optional = comparison.optional.checks.map((check) => `${check.name.toUpperCase()} UNCOMPARABLE (current ${check.current}; baseline ${check.baseline})`).join('; ')
+    const stateOf = (finding) => mode === 'all' ? finding.debtState : mode
+    const fixedShown = auditFilter(baseline.value, args, comparison.fixed).slice(0, Math.min(10, max))
+    const text = [
+        `${mode.toUpperCase()} DEBT — deterministic internal audit vs ${resolved.ref} (${resolved.commit.slice(0, 12)})`,
+        `Changed scope: ${changedFiles.length} file(s) from ${scopeSource}${changedFiles.length ? ` — ${changedFiles.slice(0, 12).join(', ')}${changedFiles.length > 12 ? ', …' : ''}` : ' — working tree matches the baseline'}.`,
+        `Scope comparison: ${comparison.totals.scope.new} new, ${comparison.totals.scope.existing} existing, ${comparison.totals.scope.fixed} fixed deterministic finding(s). Repository totals: ${comparison.totals.repository.new} new, ${comparison.totals.repository.existing} existing, ${comparison.totals.repository.fixed} fixed.`,
+        `Optional checks: ${optional}. Supply-chain findings are not assigned new/existing/fixed state from a source-only checkout.`,
+        '',
+        `Showing ${shown.length} of ${selected.length} ${mode} finding(s) after filters:`,
+        ...shown.map((finding) => formatDebtFinding(finding, stateOf(finding))),
+        selected.length > shown.length ? `  … +${selected.length - shown.length} more` : null,
+        '',
+        `Fixed in this changed scope: ${comparison.fixed.length}${fixedShown.length ? ' (sample below)' : ''}.`,
+        ...fixedShown.map((finding) => formatDebtFinding(finding, 'fixed')),
+    ].filter((line) => line != null).join('\n')
+    return toolResult(text, {
+        status: 'COMPLETE',
+        mode: 'baseline-comparison',
+        debt: mode,
+        baseline: {ref: resolved.ref, commit: resolved.commit},
+        scope: {files: changedFiles, source: scopeSource},
+        comparison: {
+            status: 'COMPLETE',
+            scope: comparison.scope,
+            totals: comparison.totals,
+            new: comparison.new,
+            existing: comparison.existing,
+            fixed: comparison.fixed,
+            optional: comparison.optional,
+        },
+        findings: selected,
+        changeEvidence,
+    }, {
+        page: {shown: shown.length, total: selected.length, capped: shown.length < selected.length},
+        completeness: {status: 'COMPLETE'},
+    })
+}
+
 // Full internal health audit: dead code + unused exports, dependency findings (npm/go/py missing &
 // unused deps), structure (import cycles / orphans / boundary rules), supply-chain (offline OSV
 // advisories, typosquat, lockfile drift), optional malware heuristics.
 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),
         skipMalwareScan: !args.include_malware_scan, // greps installed packages — slow, so opt-in
     })
     if (!audit.ok) return `Audit failed: ${audit.error}`
+    if (Array.isArray(args.changed_files)) {
+        const normalized = normalizeAuditScopeFiles(args.changed_files)
+        if (!normalized.ok) return `Changed-scope audit invalid: ${normalized.error}.`
+        const scoped = scopeAuditFindings(audit.findings, normalized.files)
+        const text = formatOrdinaryAudit(audit, args, scoped,
+            `CHANGED-SCOPE ONLY — ${normalized.files.length} explicitly supplied file(s); no baseline was provided, so these findings are not classified as new, existing, or fixed.`)
+        return toolResult(text, {
+            status: 'COMPLETE',
+            mode: 'changed-scope',
+            scope: {files: normalized.files, source: 'explicit changed_files'},
+            comparison: {status: 'UNAVAILABLE', reason: 'base_ref was not provided; changed-scope is not a new-debt claim'},
+            findings: auditFilter(audit, args, scoped),
+        }, {completeness: {status: 'COMPLETE'}})
+    }
     const minSev = SEVERITY_RANK[args.min_severity] ?? 4
     const cat = args.category ? String(args.category) : null
     const max = Math.max(1, Math.min(100, Number(args.max_findings) || 30))
@@ -105,19 +412,16 @@ export async function tRunAudit(g, args, ctx) {
     const shown = filtered.slice(0, max)
     const sev = audit.summary.bySeverity
     const bycat = audit.summary.byCategory
-    const line = (f) => {
-        const where = f.file ? `  (${f.file}${f.symbol ? ` ${f.symbol}` : ''})` : f.package ? `  (pkg ${f.package}${f.version ? `@${f.version}` : ''}${f.manifest ? `; ${f.manifest}` : ''})` : ''
-        return `  [${f.severity}/${f.confidence || '?'}] ${f.rule}: ${f.title}${where}${f.fixHint ? `\n      fix: ${f.fixHint}` : ''}`
-    }
     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).`,
+        ...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.`,
         ``,
         `Showing ${shown.length} of ${filtered.length} finding(s)${cat ? ` in category "${cat}"` : ''}${args.min_severity ? ` at ≥${args.min_severity}` : ''}:`,
-        ...shown.map(line),
+        ...shown.map(formatAuditFinding),
         filtered.length > shown.length ? `  … +${filtered.length - shown.length} more (raise max_findings or filter by category/min_severity)` : null,
     ].filter((x) => x != null).join('\n')
 }
@@ -177,14 +481,32 @@ export function tCoverageMap(g, args, ctx) {
     const allFiles = agg.modules.flatMap((m) => m.files.filter((f) => inScope(f.path)))
     const measured = allFiles.filter((f) => f.coverage != null)
     if (!measured.length) {
+        const fallback = computeStaticTestReachability(rawGraph(ctx), {repoRoot: ctx.repoRoot, path: pathFilter || ''})
+        const topN = Math.max(1, Math.min(50, Number(args.top_n) || 15))
+        const reachable = fallback.reachable.slice(0, topN)
+        const unreachable = fallback.unreachable.slice(0, topN)
         return [
-            `No coverage report found${pathFilter ? ` for ${pathFilter}` : ''} — this tool reads existing reports, it does not run tests.`,
+            `Static test reachability${pathFilter ? ` for ${pathFilter}` : ''}: ${fallback.reachableFiles}/${fallback.productFiles} product file(s) have a runtime graph path from ${fallback.testFiles} indexed test file(s).`,
+            `actualCoverage: ${fallback.actualCoverage}. This is NOT coverage: imports/calls only show that a test can statically reach a file, never that a line, branch or symbol executed.`,
+            fallback.bounds.truncated ? `Traversal was bounded/truncated (${fallback.bounds.traversedStates}/${fallback.bounds.maxStates} states, depth ≤${fallback.bounds.maxDepth}, ${fallback.testFiles}/${fallback.totalTestFiles} test files).` : `Traversal: ${fallback.bounds.traversedStates} bounded state(s), depth ≤${fallback.bounds.maxDepth}.`,
+            '',
+            'Nearest runtime paths from tests:',
+            ...(reachable.length ? reachable.map((entry) => {
+                const nearest = entry.nearestTests[0]
+                return `  ${nearest.confidence.padStart(6)}  d${nearest.distance}  ${entry.file}  ← ${nearest.test}\n          path: ${nearest.path.join(' → ')}`
+            }) : ['  (none)']),
+            '',
+            `No runtime path from an indexed test (${fallback.unreachableFiles}; not proof of no tests):`,
+            ...(unreachable.length ? unreachable.map((file) => `  ${file}`) : ['  (none)']),
+            fallback.unreachableFiles > unreachable.length ? `  … +${fallback.unreachableFiles - unreachable.length} more (raise top_n or narrow path)` : null,
+            '',
+            'No coverage report found — generate one for measured coverage:',
             'Generate one with the repo\'s own test runner, then call coverage_map again:',
             '  JS/TS:  npx vitest run --coverage   (or jest --coverage)',
             '  Python: pytest --cov --cov-report=json',
             '  Go:     go test ./... -coverprofile=coverage.out',
             'Read locations: coverage/coverage-summary.json, coverage/coverage-final.json, (coverage/)lcov.info, coverage.json, coverage.out.',
-        ].join('\n')
+        ].filter((line) => line != null).join('\n')
     }
     const pctStr = (v) => (v == null ? 'n/a' : `${Math.round(v * 100)}%`)
     const sources = [...new Set(measured.map((f) => f.coverageSource).filter(Boolean))]
@@ -225,7 +547,7 @@ export function tCoverageMap(g, args, ctx) {
     ].join('\n')
 }
 
-// HTTP endpoint inventory: Express/Fastify/Nest/Flask/FastAPI/Go-mux style route definitions.
+// HTTP endpoint inventory: Express/Fastify/Nest/Flask/FastAPI/Go/Rust/Spring route definitions.
 export function tListEndpoints(g, args, ctx) {
     if (!ctx.repoRoot) return 'Endpoint detection needs the repo root (not provided to this server).'
     const graph = rawGraph(ctx)

package/src/mcp/tools-history.mjs

@@ -0,0 +1,22 @@
+// Behavioral architecture evidence from bounded, local git history.
+import {analyzeGitHistory, formatGitHistoryAnalytics} from '../analysis/git-history.js'
+import {toolResult} from './tool-result.mjs'
+
+export async function tGitHistory(g, args, ctx) {
+    if (!ctx?.repoRoot) return toolResult('Git history intelligence is unavailable: no repository root is active.', {status: 'unavailable'})
+    const result = await analyzeGitHistory({
+        repoRoot: ctx.repoRoot,
+        graph: g,
+        months: args.months,
+        maxCommits: args.max_commits,
+        maxPairs: args.max_pairs,
+        minPairCount: args.min_pair_count,
+    })
+    return toolResult(formatGitHistoryAnalytics(result, {topN: args.top_n}), result, {
+        completeness: {
+            status: result.status,
+            complete: result.completeness?.complete === true,
+            reasons: result.completeness?.reasons || [],
+        },
+    })
+}