weavatrix 0.1.3 → 0.2.0

package/src/mcp/tools-graph.mjs

@@ -3,20 +3,24 @@
 // 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'
 
+const compileKind = (edge) => edge?.typeOnly === true ? 'type-only' : edge?.compileOnly === true ? 'compile-only' : null
+
 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 = {}
     let typeOnlyEdges = 0
+    let compileOnlyEdges = 0
     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
         if (e.typeOnly === true) typeOnlyEdges++
+        if (e.compileOnly === true) compileOnlyEdges++
     }
     const comm = new Map()
     for (const n of g.nodes) {
@@ -35,7 +39,8 @@ export function tGraphStats(g, ctx) {
         ctx?.repoRoot ? `- Repo: ${ctx.repoRoot}` : null,
         `- Nodes: ${g.nodes.length} (${files} files, ${symbols} symbols)`,
         `- Edges: ${g.links.length}`,
-        g.edgeTypesV ? `- Typed-edge metadata: v${g.edgeTypesV} (${typeOnlyEdges} type-only edges)` : `- Typed-edge metadata: unavailable (rebuild_graph with Weavatrix 0.1.3+)`,
+        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(', ')})`,
@@ -54,10 +59,12 @@ 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)
-            .map((e) => `  ${dir === 'out' ? '→' : '←'} ${e.relation || 'rel'}  ${labelOf(g, e.id)}  [${e.id}]`)
+            .map((e) => `  ${dir === 'out' ? '→' : '←'} ${compileKind(e) ? `${compileKind(e)} ` : ''}${e.relation || 'rel'}  ${labelOf(g, e.id)}  [${e.id}]`)
             .join('\n') || '  (none)'
     return [
         note,
@@ -66,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,
@@ -80,10 +87,10 @@ export function tGetNode(g, {label} = {}, ctx) {
 function dedupeEdges(list) {
     const grouped = new Map()
     for (const e of list) {
-        const key = `${e.relation || 'rel'}|${e.typeOnly === true ? 'type' : 'runtime'}|${e.id}`
+        const key = `${e.relation || 'rel'}|${compileKind(e) || 'runtime'}|${e.id}`
         const cur = grouped.get(key)
         if (cur) cur.count += 1
-        else grouped.set(key, {id: e.id, relation: e.relation, typeOnly: e.typeOnly === true, count: 1})
+        else grouped.set(key, {id: e.id, relation: e.relation, typeOnly: e.typeOnly === true, compileOnly: e.compileOnly === true, count: 1})
     }
     return [...grouped.values()]
 }
@@ -102,7 +109,7 @@ export function tGetNeighbors(g, {label, relation_filter} = {}, ctx) {
     const outs = dedupeEdges(outsRaw)
     const ins = dedupeEdges(insRaw)
     const line = (e, dir) =>
-        `  ${dir === 'out' ? '→' : '←'} ${e.typeOnly ? 'type-only ' : ''}${e.relation || 'rel'}  ${labelOf(g, e.id)}  [${e.id}]${e.count > 1 ? `  (${e.count} sites)` : ''}`
+        `  ${dir === 'out' ? '→' : '←'} ${compileKind(e) ? `${compileKind(e)} ` : ''}${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)`,
@@ -114,55 +121,8 @@ export function tGetNeighbors(g, {label, relation_filter} = {}, ctx) {
     ].filter(Boolean).join('\n')
 }
 
-export function tGodNodes(g, {top_n = 10} = {}) {
-    const n = Math.max(1, Math.min(100, Number(top_n) || 10))
-    const scored = g.nodes
-        .map((node) => {
-            const outs = connList(g.out.get(String(node.id)))
-            const ins = connList(g.inn.get(String(node.id)))
-            const outIds = new Set(outs.map((e) => String(e.id)))
-            const inIds = new Set(ins.map((e) => String(e.id)))
-            const allIds = new Set([...outIds, ...inIds])
-            const runtimeIds = new Set([...outs, ...ins].filter((e) => e.typeOnly !== true).map((e) => String(e.id)))
-            const compileOnlyIds = new Set([...outs, ...ins].filter((e) => e.typeOnly === true).map((e) => String(e.id)))
-            for (const id of runtimeIds) compileOnlyIds.delete(id)
-            const occurrences = outs.length + ins.length
-            return {
-                node,
-                deg: allIds.size,
-                runtime: runtimeIds.size,
-                compileOnly: compileOnlyIds.size,
-                out: outIds.size,
-                in: inIds.size,
-                occurrences,
-            }
-        })
-        .filter((entry) => entry.deg > 0)
-        .sort((a, b) => b.runtime - a.runtime || b.deg - a.deg || b.occurrences - a.occurrences)
-    const ranked = scored.slice(0, n)
-    const rankedIds = new Set(ranked.map((entry) => String(entry.node.id)))
-    // Unique neighbors measure coupling, but a large component repeatedly calling the same helper (for
-    // example i18n) can still be a valuable complexity hotspot. Preserve that second lens explicitly
-    // instead of letting repeated sites inflate the coupling rank.
-    const occurrenceHotspots = scored
-        .filter((entry) => !rankedIds.has(String(entry.node.id)))
-        .filter((entry) => entry.occurrences >= 20 && entry.occurrences - entry.deg >= 10)
-        .sort((a, b) => (b.occurrences - b.deg) - (a.occurrences - a.deg) || b.occurrences - a.occurrences)
-        .slice(0, Math.min(5, n))
-    return [
-        `Top ${ranked.length} connectivity hubs (ranked by unique runtime call/import/reference neighbors; structural containment excluded):`,
-        ...ranked.map(
-            (r, i) =>
-                `${String(i + 1).padStart(2)}. ${r.node.label ?? r.node.id}  (${r.deg} unique: ${r.runtime} runtime, ${r.compileOnly} compile-only; out ${r.out}, in ${r.in}; ${r.occurrences} edge occurrence${r.occurrences === 1 ? '' : 's'})  [${r.node.id}]`
-        ),
-        `Repeated call sites affect the occurrence count, not the connectivity rank; compile-only neighbors are secondary to runtime coupling.`,
-        occurrenceHotspots.length ? `` : null,
-        occurrenceHotspots.length ? `High occurrence hotspots outside the connectivity rank (repeated call/reference sites; complexity signal, not broader coupling):` : null,
-        ...occurrenceHotspots.map((r) =>
-            `  ${r.node.label ?? r.node.id}  (${r.occurrences} occurrences across ${r.deg} unique neighbors; ${r.occurrences - r.deg} repeats)  [${r.node.id}]`
-        ),
-    ].filter((line) => line != null).join('\n')
-}
+export {tGodNodes} from './tools-graph-hubs.mjs'
+
 
 export function tGetCommunity(g, {community_id} = {}) {
     const groups = new Map()
@@ -194,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
@@ -204,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}))
@@ -217,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})
             }
         }
@@ -229,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)
@@ -246,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
 }