weavatrix 0.1.0

package/src/mcp/tools-actions.mjs

@@ -0,0 +1,132 @@
+// Action tools: rebuild the graph, retarget the server at another repo, list sibling repos with
+// built graphs — plus the 'online' capability group (the ONLY tools that ever touch the network).
+// Hot-reloadable (re-imported by catalog.mjs on change).
+import {readFileSync, writeFileSync, existsSync, readdirSync, statSync} from 'node:fs'
+import {join, dirname} from 'node:path'
+import {prevGraphPathFor, diffGraphs, formatGraphDiff} from './graph-context.mjs'
+import {buildGraphForRepo} from '../build-graph.js'
+import {graphOutDirForRepo} from '../graph/layout.js'
+import {refreshAdvisories, storeMeta, DEFAULT_STORE} from '../security/advisory-store.js'
+import {collectInstalled} from '../security/installed.js'
+
+export async function tRebuildGraph(g, args, ctx) {
+    if (!ctx.repoRoot) return 'Rebuild needs the repo root (not provided to this server).'
+    const mode = ['no-tests', 'tests-only', 'full'].includes(args.mode) ? args.mode : 'full'
+    // snapshot the outgoing state: bytes → graph.prev.json (for graph_diff later), struct → inline delta
+    let prevBytes = null
+    try { prevBytes = readFileSync(ctx.graphPath) } catch { /* first build — nothing to diff against */ }
+    const before = g?.nodes ? {nodes: g.nodes, links: g.links} : null
+    const res = await buildGraphForRepo(ctx.repoRoot, {mode, scope: args.scope || ''})
+    if (!res || !res.ok) return `Graph rebuild failed: ${(res && res.error) || 'unknown error'}`
+    if (prevBytes) { try { writeFileSync(prevGraphPathFor(ctx.graphPath), prevBytes) } catch { /* snapshot is best-effort */ } }
+    const fresh = ctx.reload() // refresh THIS server's in-memory graph so subsequent tool calls see the new graph
+    const delta = before && fresh ? formatGraphDiff(diffGraphs(before, fresh)) : null
+    return [
+        `Rebuilt the graph (${mode}${args.scope ? `, scope=${args.scope}` : ''}). ${res.log || ''}. In-memory graph reloaded — graph tools now reflect it.`,
+        delta
+    ].filter(Boolean).join('\n\n')
+}
+
+// Retarget this server at ANOTHER local repository at runtime — one weavatrix registration serves any
+// repo. Loads <parent>/weavatrix-graphs/<name>/graph.json (the central layout graphs
+// always live in), building it first when missing. On a failed load the previous repo stays active.
+export async function tOpenRepo(g, args, ctx) {
+    const repoPath = String(args.path || '').trim().replace(/[\\/]+$/, '')
+    if (!repoPath) return 'Provide "path" — an absolute path to a local repository folder.'
+    if (!existsSync(repoPath)) return `Path not found: ${repoPath}`
+    const graphPath = join(graphOutDirForRepo(repoPath), 'graph.json')
+    let built = false
+    if (!existsSync(graphPath)) {
+        if (args.build === false) return `No graph yet for ${repoPath} (expected at ${graphPath}). Re-call without build:false to build one — large repos can take minutes.`
+        const mode = ['no-tests', 'tests-only', 'full'].includes(args.mode) ? args.mode : 'full'
+        const res = await buildGraphForRepo(repoPath, {mode, scope: ''})
+        if (!res || !res.ok) return `Graph build failed for ${repoPath}: ${(res && res.error) || 'unknown error'}`
+        built = true
+    }
+    const prev = {graphPath: ctx.graphPath, repoRoot: ctx.repoRoot}
+    ctx.graphPath = graphPath
+    ctx.repoRoot = repoPath
+    const loaded = ctx.reload()
+    if (!loaded) {
+        ctx.graphPath = prev.graphPath
+        ctx.repoRoot = prev.repoRoot
+        ctx.reload()
+        return `Failed to load ${graphPath} — still targeting the previous repo (${prev.repoRoot || 'none'}).`
+    }
+    return `Opened ${repoPath}${built ? ' (graph built fresh)' : ''}: ${loaded.nodes.length} nodes / ${loaded.links.length} edges. All tools now target this repo.`
+}
+
+// Sibling repos that already have a built graph in the central weavatrix-graphs folder — open_repo candidates.
+export function tListKnownRepos(g, args, ctx) {
+    if (!ctx.repoRoot) return 'No repo root — cannot locate the central graphs folder.'
+    const parent = dirname(ctx.repoRoot)
+    const root = join(parent, 'weavatrix-graphs')
+    const norm = (p) => String(p).replace(/[\\/]+/g, '/').toLowerCase()
+    let entries = []
+    try { entries = readdirSync(root, {withFileTypes: true}) } catch { return `No central graphs folder at ${root}.` }
+    const rows = []
+    for (const entry of entries) {
+        if (!entry.isDirectory()) continue
+        const graphPath = join(root, entry.name, 'graph.json')
+        try {
+            const st = statSync(graphPath)
+            rows.push({name: entry.name, repoPath: join(parent, entry.name), builtAt: st.mtime.toISOString()})
+        } catch { /* no graph built for this entry */ }
+    }
+    if (!rows.length) return `No built graphs under ${root}.`
+    return [
+        `Repos with built graphs under ${root} (switch with open_repo):`,
+        ...rows.map((r) => `  ${norm(r.repoPath) === norm(ctx.repoRoot) ? '»' : ' '} ${r.name} — graph built ${r.builtAt}  (${r.repoPath})`),
+    ].join('\n')
+}
+
+// ---- online tools ('online' capability group) -----------------------------------------------------
+// Scans and graph queries stay 100% offline. These two run a network call ONLY when explicitly
+// invoked; registering the server with a caps list that omits 'online' removes them entirely.
+
+// Refresh the local OSV advisory store for the current repo's lockfile-pinned packages. What leaves
+// the machine: package names + versions (that is what an OSV query IS) — never source code.
+export async function tRefreshAdvisories(g, args, ctx) {
+    if (!ctx.repoRoot) return 'No repo root — cannot collect installed packages.'
+    const {installed} = collectInstalled(ctx.repoRoot)
+    if (!installed.length) return 'No pinned packages found in lockfiles (npm/yarn/pip/poetry/uv/go) — nothing to query.'
+    const res = await refreshAdvisories({installed, repoKey: ctx.repoRoot, timeoutMs: Number(args.timeout_ms) || undefined})
+    if (res.ok === false) return `Advisory refresh failed: ${res.error}`
+    const meta = storeMeta()
+    return [
+        `Advisory store refreshed from OSV.dev: ${res.queried} package versions queried, ${res.vulnerable} with known advisories (${res.fetched} advisory records fetched).`,
+        res.unsupported ? `${res.unsupported} packages skipped (ecosystem not OSV-queryable — npm/PyPI/Go only).` : null,
+        res.errors?.length ? `Partial: ${res.errors.length} request error(s), first: ${res.errors[0]}` : null,
+        `Store: ${DEFAULT_STORE} (${meta.advisoryCount} advisories, fetched ${meta.fetchedAt}). run_audit now reflects it — offline.`,
+    ].filter(Boolean).join('\n')
+}
+
+// Push the current graph.json to a user-configured endpoint (the weavatrix site's hosted graph view,
+// or any self-hosted collector). Off until WEAVATRIX_SYNC_URL is set. The payload is the graph only —
+// file paths, symbol names, and edges — never file contents.
+export async function tSyncGraph(g, args, ctx) {
+    const url = process.env.WEAVATRIX_SYNC_URL
+    if (!url) {
+        return 'Graph sync is not configured (optional feature). Set WEAVATRIX_SYNC_URL to the upload endpoint'
+            + ' (and WEAVATRIX_SYNC_TOKEN for bearer auth) in the MCP registration env, then call again.'
+    }
+    if (!g) return 'No graph loaded — build one first (open_repo / rebuild_graph).'
+    let body
+    try { body = readFileSync(ctx.graphPath, 'utf8') } catch (e) { return `Cannot read ${ctx.graphPath}: ${e.message}` }
+    const repoName = String(ctx.repoRoot || '').replace(/[\\/]+$/, '').split(/[\\/]/).pop() || 'repo'
+    try {
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                'x-weavatrix-repo': repoName,
+                ...(process.env.WEAVATRIX_SYNC_TOKEN ? {authorization: `Bearer ${process.env.WEAVATRIX_SYNC_TOKEN}`} : {}),
+            },
+            body,
+        })
+        if (!res.ok) return `Sync endpoint answered HTTP ${res.status} — graph NOT accepted.`
+        return `Graph for ${repoName} (${g.nodes.length} nodes / ${g.links.length} edges, ${Math.round(body.length / 1024)} KB) pushed to ${url}.`
+    } catch (e) {
+        return `Sync failed: ${e.message} — the graph stays local.`
+    }
+}

package/src/mcp/tools-graph.mjs

@@ -0,0 +1,274 @@
+// Graph query tools: stats, node lookup, neighbors, hubs, communities, exploratory traversal and
+// shortest path. Pure reads over the loaded graph — no filesystem or process access beyond the
+// staleness probe in graph-context. Hot-reloadable (re-imported by catalog.mjs on change).
+import {
+    isSymbol, degreeOf, labelOf, connList,
+    resolveNodeInfo, resolveNode, ambiguityNote, findSeeds, undirectedNeighbors,
+    graphStaleness, fileStalenessNote,
+} from './graph-context.mjs'
+
+export function tGraphStats(g, ctx) {
+    const files = g.nodes.filter((n) => !isSymbol(n.id)).length
+    const symbols = g.nodes.length - files
+    const relCount = {}
+    const confCount = {}
+    for (const e of g.links) {
+        relCount[e.relation ?? '?'] = (relCount[e.relation ?? '?'] || 0) + 1
+        if (e.confidence != null) confCount[e.confidence] = (confCount[e.confidence] || 0) + 1
+    }
+    const comm = new Map()
+    for (const n of g.nodes) {
+        const c = n.community ?? 'none'
+        comm.set(c, (comm.get(c) || 0) + 1)
+    }
+    const topComm = [...comm.entries()].sort((a, b) => b[1] - a[1]).slice(0, 8)
+    const fmt = (o) =>
+        Object.entries(o)
+            .sort((a, b) => b[1] - a[1])
+            .map(([k, v]) => `${k}: ${v}`)
+            .join(', ')
+    const freshness = ctx ? graphStaleness(ctx) : null
+    return [
+        `Graph summary`,
+        ctx?.repoRoot ? `- Repo: ${ctx.repoRoot}` : null,
+        `- Nodes: ${g.nodes.length} (${files} files, ${symbols} symbols)`,
+        `- Edges: ${g.links.length}`,
+        `- Relations: ${fmt(relCount)}`,
+        Object.keys(confCount).length ? `- Confidence: ${fmt(confCount)}` : null,
+        `- Communities: ${comm.size} (top by size: ${topComm.map(([c, n]) => `#${c}=${n}`).join(', ')})`,
+        freshness?.builtAt ? `- Built: ${freshness.builtAt.toISOString()}${freshness.headAt ? ` (repo HEAD committed ${freshness.headAt.toISOString()})` : ''}` : null,
+    ]
+        .filter(Boolean)
+        .join('\n')
+}
+
+export function tGetNode(g, {label} = {}, ctx) {
+    const info = resolveNodeInfo(g, label)
+    const n = info.node
+    if (!n) return `No node found matching "${label}".`
+    const note = ambiguityNote(label, info)
+    const id = String(n.id)
+    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 sample = (list, dir) =>
+        list
+            .slice(0, 12)
+            .map((e) => `  ${dir === 'out' ? '→' : '←'} ${e.relation || 'rel'}  ${labelOf(g, e.id)}  [${e.id}]`)
+            .join('\n') || '  (none)'
+    return [
+        note,
+        `Node: ${n.label ?? id}`,
+        `- id: ${id}`,
+        `- 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})`,
+        `Outgoing:\n${sample(outs, 'out')}`,
+        `Incoming:\n${sample(ins, 'in')}`,
+        drift,
+    ]
+        .filter(Boolean)
+        .join('\n')
+}
+
+// Collapse repeated edges to the same neighbor (one per call site in the graph) into `(N sites)` —
+// a hub function's caller list shrinks ~2-3x with no information loss.
+function dedupeEdges(list) {
+    const grouped = new Map()
+    for (const e of list) {
+        const key = `${e.relation || 'rel'}|${e.id}`
+        const cur = grouped.get(key)
+        if (cur) cur.count += 1
+        else grouped.set(key, {id: e.id, relation: e.relation, count: 1})
+    }
+    return [...grouped.values()]
+}
+
+export function tGetNeighbors(g, {label, relation_filter} = {}, ctx) {
+    const info = resolveNodeInfo(g, label)
+    const n = info.node
+    if (!n) return `No node found matching "${label}".`
+    const note = ambiguityNote(label, info)
+    const id = String(n.id)
+    const drift = ctx ? fileStalenessNote(ctx, n.source_file || (isSymbol(id) ? id.split('#')[0] : id)) : null
+    const rf = relation_filter ? String(relation_filter).toLowerCase() : null
+    const match = (e) => !rf || String(e.relation ?? '').toLowerCase() === rf
+    const outsRaw = (g.out.get(id) || []).filter(match)
+    const insRaw = (g.inn.get(id) || []).filter(match)
+    const outs = dedupeEdges(outsRaw)
+    const ins = dedupeEdges(insRaw)
+    const line = (e, dir) =>
+        `  ${dir === 'out' ? '→' : '←'} ${e.relation || 'rel'}  ${labelOf(g, e.id)}  [${e.id}]${e.count > 1 ? `  (${e.count} sites)` : ''}`
+    return [
+        note,
+        `Neighbors of ${n.label ?? id}${rf ? ` (relation=${rf})` : ''}: ${outs.length + ins.length} unique (${outsRaw.length + insRaw.length} edges)`,
+        `Outgoing (${outs.length}):`,
+        ...outs.slice(0, 60).map((e) => line(e, 'out')),
+        `Incoming (${ins.length}):`,
+        ...ins.slice(0, 60).map((e) => line(e, 'in')),
+        drift,
+    ].filter(Boolean).join('\n')
+}
+
+export function tGodNodes(g, {top_n = 10} = {}) {
+    const n = Math.max(1, Math.min(100, Number(top_n) || 10))
+    const ranked = g.nodes
+        .map((node) => {
+            const o = connList(g.out.get(String(node.id))).length
+            const i = connList(g.inn.get(String(node.id))).length
+            return {node, deg: o + i, out: o, in: i}
+        })
+        .sort((a, b) => b.deg - a.deg)
+        .slice(0, n)
+    return [
+        `Top ${n} most-connected nodes (call/import/reference edges, excluding structural containment):`,
+        ...ranked.map(
+            (r, i) =>
+                `${String(i + 1).padStart(2)}. ${r.node.label ?? r.node.id}  (${r.deg} edges: out ${r.out}, in ${r.in})  [${r.node.id}]`
+        ),
+    ].join('\n')
+}
+
+export function tGetCommunity(g, {community_id} = {}) {
+    const groups = new Map()
+    for (const node of g.nodes) {
+        const c = node.community
+        if (c == null) continue
+        if (!groups.has(c)) groups.set(c, [])
+        groups.get(c).push(node)
+    }
+    const ranked = [...groups.entries()].sort((a, b) => b[1].length - a[1].length) // 0-indexed by size
+    const idx = Number(community_id)
+    if (!Number.isInteger(idx) || idx < 0 || idx >= ranked.length)
+        return `Invalid community_id ${community_id}. Valid range 0..${ranked.length - 1} (0 = largest).`
+    const [rawId, members] = ranked[idx]
+    const files = members.filter((m) => !isSymbol(m.id))
+    return [
+        `Community #${idx} (raw id ${rawId}) — ${members.length} nodes, ${files.length} files:`,
+        ...members
+            .slice()
+            .sort((a, b) => degreeOf(g, b.id) - degreeOf(g, a.id))
+            .slice(0, 80)
+            .map((m) => `  ${m.label ?? m.id}  [${m.id}]`),
+        members.length > 80 ? `  … +${members.length - 80} more` : null,
+    ]
+        .filter(Boolean)
+        .join('\n')
+}
+
+// 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)
+    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
+    const relOk = (rel) => !ctx || ctx.has(String(rel ?? '').toLowerCase())
+    const charBudget = Math.max(400, (Number(token_budget) || 2000) * 4)
+    // 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}))
+        const seen = new Set()
+        while (stack.length) {
+            const {id, d} = stack.pop()
+            if (!depthOf.has(id) || d < depthOf.get(id)) depthOf.set(id, d)
+            if (seen.has(id)) continue
+            seen.add(id)
+            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})
+            }
+        }
+    } else {
+        let frontier = start.slice()
+        start.forEach((id) => depthOf.set(id, 0))
+        for (let d = 0; d < maxDepth && frontier.length; d++) {
+            const next = []
+            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)
+                    }
+                }
+            frontier = next
+        }
+    }
+    // rank reached nodes: seeds first, then by proximity (depth asc), then connectivity (degree desc)
+    const ranked = [...depthOf.entries()]
+        .map(([id, d]) => ({id, d, deg: degreeOf(g, id)}))
+        .sort((a, b) => a.d - b.d || b.deg - a.deg)
+    const shown = ranked.slice(0, nodeBudget)
+    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])
+        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(', ')}`,
+        `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')
+    if (text.length > charBudget) text = text.slice(0, charBudget) + `\n... (truncated to ~${token_budget} tokens)`
+    return text
+}
+
+export function tShortestPath(g, {source, target, max_hops = 8} = {}) {
+    const s = resolveNode(g, source)
+    const t = resolveNode(g, target)
+    if (!s) return `Source "${source}" not found.`
+    if (!t) return `Target "${target}" not found.`
+    const sid = String(s.id)
+    const tid = String(t.id)
+    if (sid === tid) return `Source and target are the same node: ${s.label ?? sid}.`
+    const cap = Math.max(1, Math.min(20, Number(max_hops) || 8))
+    const prev = new Map([[sid, null]])
+    const relTo = new Map()
+    let frontier = [sid]
+    let hops = 0
+    let found = false
+    while (frontier.length && hops < cap && !found) {
+        const next = []
+        for (const id of frontier) {
+            for (const [nid, rel] of undirectedNeighbors(g, id)) {
+                if (prev.has(nid)) continue
+                prev.set(nid, id)
+                relTo.set(nid, rel)
+                if (nid === tid) {
+                    found = true
+                    break
+                }
+                next.push(nid)
+            }
+            if (found) break
+        }
+        frontier = next
+        hops++
+    }
+    if (!prev.has(tid)) return `No path found between "${s.label ?? sid}" and "${t.label ?? tid}" within ${cap} hops.`
+    const path = []
+    for (let cur = tid; cur != null; cur = prev.get(cur)) path.unshift(cur)
+    const lines = path.map((id, i) => (i === 0 ? `  ${labelOf(g, id)}` : `  --${relTo.get(id) || 'rel'}--> ${labelOf(g, id)}`))
+    return [`Shortest path (${path.length - 1} hops): ${s.label ?? sid} → ${t.label ?? tid}`, ...lines].join('\n')
+}

package/src/mcp/tools-health.mjs

@@ -0,0 +1,209 @@
+// 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 {degreeOf, rawGraph} from './graph-context.mjs'
+import {computeDuplicates} from '../analysis/duplicates.js'
+import {runInternalAudit} from '../analysis/internal-audit.js'
+import {summarizeCommunities, aggregateGraph} from '../analysis/graph-analysis.js'
+import {detectEndpoints} from '../analysis/endpoints.js'
+
+// Group clone pairs into union-find families.
+function groupClones(data, {simMin, tokMin, mode, skipTests}) {
+    const frags = data.frags || []
+    const elig = (i) => frags[i].n >= tokMin && (!skipTests || !frags[i].test)
+    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 }
+    for (const [i, j] of pairs) { if (!parent.has(i)) parent.set(i, i); if (!parent.has(j)) parent.set(j, j); parent.set(find(i), find(j)) }
+    const groups = new Map()
+    for (const [i, j, s] of pairs) {
+        const r = find(i)
+        if (!groups.has(r)) groups.set(r, {members: new Set(), maxSim: 0})
+        const g = groups.get(r); g.members.add(i); g.members.add(j); g.maxSim = Math.max(g.maxSim, s)
+    }
+    return [...groups.values()].map((g) => {
+        const members = [...g.members].sort((a, b) => frags[b].n - frags[a].n)
+        return {members: members.map((i) => frags[i]), maxSim: g.maxSim, tokens: members.reduce((n, i) => n + frags[i].n, 0)}
+    }).sort((a, b) => b.tokens - a.tokens)
+}
+
+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 mode = args.mode === 'strict' ? 'strict' : 'renamed'
+    const skipTests = args.include_tests ? false : 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.
+    if (args.mode === 'semantic') {
+        const data = computeDuplicates(ctx.repoRoot, ctx.graphPath, {nameTwins: true})
+        const frags = data.frags
+        const groups = (data.nameTwins || [])
+            .map((t) => ({...t, members: t.members.filter((i) => (!skipTests || !frags[i].test) && frags[i].n >= tokMin)}))
+            .map((t) => ({...t, fileCount: new Set(t.members.map((i) => frags[i].file)).size}))
+            .filter((t) => t.members.length >= 2 && t.fileCount >= 2)
+        if (!groups.length) return 'No same-name symbol groups across files (semantic mode).'
+        const top = groups.slice(0, Math.min(30, Math.max(1, Number(args.top_n) || 15)))
+        const lines = top.map((t, k) => {
+            const verdict = t.simMax < 60 ? '  ⚠ DIVERGENT — same name, different bodies (drift hazard)' : t.simMin >= 90 ? '  near-identical — extract a shared module' : ''
+            const head = `${k + 1}. "${t.label}" — ${t.members.length} definitions in ${t.fileCount} files, similarity ${t.simMin}–${t.simMax}%${verdict}`
+            const sites = t.members.slice(0, 8).map((i) => `     ${frags[i].file}:${frags[i].start}-${frags[i].end}  (${frags[i].n} tok)`)
+            return [head, ...sites].join('\n')
+        })
+        return `Found ${groups.length} same-name symbol group(s) across files (semantic mode; similarity = renamed-token jaccard, LOW = divergent copies). Top ${top.length}:\n\n${lines.join('\n\n')}\n\nLow-similarity groups are the risky ones — same name, drifted behavior. read_source both sites to compare.`
+    }
+    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 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')
+        const head = `${k + 1}. ${grp.members.length}× "${grp.members[0].label}"${isStr ? ' [string literal]' : ''} — ≤${grp.maxSim}% similar, ${grp.tokens} duplicated tokens`
+        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.`
+}
+
+const SEVERITY_RANK = {critical: 0, high: 1, medium: 2, low: 3, info: 4}
+
+// 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).'
+    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}`
+    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))
+    const filtered = audit.findings
+        .filter((f) => (SEVERITY_RANK[f.severity] ?? 4) <= minSev)
+        .filter((f) => !cat || f.category === cat)
+    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}` : ''})` : ''
+        return `  [${f.severity}/${f.confidence || '?'}] ${f.rule}: ${f.title}${where}${f.fixHint ? `\n      fix: ${f.fixHint}` : ''}`
+    }
+    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?.cycles ?? 0} cycle(s), ${audit.structureReport?.orphans ?? 0} orphan(s). Dead: ${audit.deadReport.deadFiles} file(s), ${audit.deadReport.unusedExports} unused export(s).`,
+        audit.scanned.advisoryDbDate ? `Advisory DB: ${audit.scanned.advisoryDbDate}.` : 'Advisory DB: never refreshed for this repo — known-vuln matching skipped (see refresh_advisories).',
+        ``,
+        `Showing ${shown.length} of ${filtered.length} finding(s)${cat ? ` in category "${cat}"` : ''}${args.min_severity ? ` at ≥${args.min_severity}` : ''}:`,
+        ...shown.map(line),
+        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')
+}
+
+// Named module clusters: graph communities labeled by their dominant folder instead of bare numbers.
+export function tListCommunities(g, args, ctx) {
+    const max = Math.max(1, Math.min(100, Number(args.top_n) || 20))
+    const list = summarizeCommunities(ctx.graphPath, max)
+    if (!list.length) return 'No communities found in the graph.'
+    return [
+        `Communities, largest first (list position = community_id for get_community):`,
+        ...list.map((c, i) => `${String(i).padStart(3)}. ${c.name} — ${c.size} nodes (raw id ${c.id}; e.g. ${[...new Set(c.files)].join(', ')})`),
+    ].join('\n')
+}
+
+// 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 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))
+    return [
+        `Module map: ${agg.totals.files} files in ${agg.modules.length} folder-modules, ${agg.totals.moduleEdges} module edges. Top ${mods.length}:`,
+        ...mods.map((m) => `  ${m.name} — ${m.fileCount} files, ${m.symbolCount} symbols`),
+        ``,
+        `Strongest module dependencies:`,
+        ...edges.map((e) => `  ${e.from} → ${e.to}  (${e.count})`),
+    ].join('\n')
+}
+
+// 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
+// tests before changing. Coverage pcts in this layer are fractions (0..1).
+export function tCoverageMap(g, args, ctx) {
+    if (!ctx.repoRoot) return 'Coverage mapping needs the repo root (not provided to this server).'
+    const agg = aggregateGraph(rawGraph(ctx), ctx.repoRoot)
+    const pathFilter = args.path ? String(args.path).replace(/\\/g, '/').replace(/\/+$/, '') : null
+    const inScope = (p) => !pathFilter || p === pathFilter || String(p).startsWith(`${pathFilter}/`)
+    const allFiles = agg.modules.flatMap((m) => m.files.filter((f) => inScope(f.path)))
+    const measured = allFiles.filter((f) => f.coverage != null)
+    if (!measured.length) {
+        return [
+            `No coverage report found${pathFilter ? ` for ${pathFilter}` : ''} — this tool reads existing reports, it does not run tests.`,
+            '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')
+    }
+    const pctStr = (v) => (v == null ? 'n/a' : `${Math.round(v * 100)}%`)
+    const sources = [...new Set(measured.map((f) => f.coverageSource).filter(Boolean))]
+    const avg = measured.reduce((s, f) => s + f.coverage, 0) / measured.length
+    const rollup = agg.modules
+        .map((m) => {
+            const withCov = m.files.filter((f) => f.coverage != null && inScope(f.path))
+            if (!withCov.length) return null
+            return {
+                name: m.name,
+                measured: withCov.length,
+                total: m.files.filter((f) => inScope(f.path)).length,
+                avg: withCov.reduce((s, f) => s + f.coverage, 0) / withCov.length,
+            }
+        })
+        .filter(Boolean)
+        .sort((a, b) => a.avg - b.avg)
+    const topN = Math.max(1, Math.min(50, Number(args.top_n) || 15))
+    // risk = graph degree × uncovered share; only symbols below 80% matter
+    const risky = agg.symbols
+        .filter((s) => s.coverage != null && s.coverage < 0.8 && inScope(s.file))
+        .map((s) => ({...s, degree: degreeOf(g, s.id)}))
+        .filter((s) => s.degree > 0)
+        .sort((a, b) => b.degree * (1 - b.coverage) - a.degree * (1 - a.coverage))
+        .slice(0, topN)
+    return [
+        `Coverage map (${measured.length}/${allFiles.length} files measured, avg ${pctStr(avg)}; report: ${sources.join(', ') || 'unknown'}${pathFilter ? `; filter ${pathFilter}` : ''}).`,
+        ``,
+        `Modules by average coverage (worst first):`,
+        ...rollup.slice(0, 20).map((m) => `  ${pctStr(m.avg).padStart(5)}  ${m.name}  (${m.measured}/${m.total} files measured)`),
+        ``,
+        `Refactor-risk hotspots — connected symbols with low coverage (ranked by degree × uncovered):`,
+        ...(risky.length
+            ? risky.map((s) => `  ${pctStr(s.coverage).padStart(5)}  deg ${String(s.degree).padStart(3)}  ${s.label}  (${s.file}${s.line ? `:${s.line}` : ''})`)
+            : ['  (none — every connected symbol is ≥80% covered or unmeasured)']),
+        ``,
+        `Tip: before refactoring a hotspot, run get_dependents on it — low coverage × many dependents means write tests first.`,
+    ].join('\n')
+}
+
+// HTTP endpoint inventory: Express/Fastify/Nest/Flask/FastAPI/Go-mux style 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)
+    const codeFiles = [...new Set(
+        (graph.nodes || [])
+            .filter((n) => !String(n.id).includes('#') && n.source_file && n.file_type === 'code')
+            .map((n) => n.source_file)
+    )]
+    const eps = detectEndpoints(ctx.repoRoot, codeFiles)
+    if (!eps.length) return 'No HTTP endpoints detected in the indexed code files.'
+    const max = Math.max(1, Math.min(300, Number(args.max_results) || 100))
+    const shown = eps.slice(0, max)
+    return [
+        `${eps.length} endpoint(s) detected${eps.length > shown.length ? `, showing ${shown.length}` : ''}:`,
+        ...shown.map((e) => `  ${e.method.toUpperCase().padEnd(6)} ${e.path}${e.handler ? `  → ${e.handler}` : ''}  (${e.file}${e.line ? `:${e.line}` : ''})`),
+    ].join('\n')
+}