weavatrix 0.1.3 → 0.1.4

package/src/mcp/catalog.mjs

@@ -23,7 +23,7 @@ function buildTools({tg, ti, th, ta}) {
         {cap: 'graph', name: 'get_node', description: 'Get full details for a specific node by label or ID.', inputSchema: {type: 'object', properties: {label: {type: 'string', description: 'Node label or ID to look up'}}, required: ['label']}, run: (g, a, ctx) => tg.tGetNode(g, a, ctx)},
         {cap: 'graph', name: 'get_neighbors', description: 'Get all direct neighbors of a node with edge details (1 hop, call sites deduped). For transitive impact use get_dependents; for the impact of your current branch changes use change_impact.', inputSchema: {type: 'object', properties: {label: {type: 'string'}, relation_filter: {type: 'string', description: 'Optional: filter by relation type'}}, required: ['label']}, run: (g, a, ctx) => tg.tGetNeighbors(g, a, ctx)},
         {cap: 'graph', name: 'query_graph', description: 'Explore the graph around a concept (BFS/DFS). Returns a focused, ranked subgraph — the closest, most-connected nodes near the matched seeds, with edges among them — not the full flood; states how many nodes were reached vs shown.', inputSchema: {type: 'object', properties: {question: {type: 'string', description: 'Natural language question or keyword search'}, mode: {type: 'string', enum: ['bfs', 'dfs'], default: 'bfs'}, depth: {type: 'integer', default: 3}, context_filter: {type: 'array', items: {type: 'string'}}, token_budget: {type: 'integer', description: 'Higher budget shows more nodes/edges', default: 2000}}, required: ['question']}, run: (g, a) => tg.tQueryGraph(g, a)},
-        {cap: 'graph', name: 'god_nodes', description: 'Rank connectivity hubs by unique call/import/reference neighbors, excluding structural containment. Repeated call sites are reported separately and do not inflate the rank.', inputSchema: {type: 'object', properties: {top_n: {type: 'integer', default: 10}}}, run: (g, a) => tg.tGodNodes(g, a)},
+        {cap: 'graph', name: 'god_nodes', description: 'Rank connectivity hubs by unique call/import/reference neighbors, with class/method ownership reported separately from runtime connectivity. Repeated call sites do not inflate the rank.', inputSchema: {type: 'object', properties: {top_n: {type: 'integer', default: 10}}}, run: (g, a) => tg.tGodNodes(g, a)},
         {cap: 'graph', name: 'shortest_path', description: 'Find the shortest path between two concepts in the knowledge graph.', inputSchema: {type: 'object', properties: {source: {type: 'string'}, target: {type: 'string'}, max_hops: {type: 'integer', default: 8}}, required: ['source', 'target']}, run: (g, a) => tg.tShortestPath(g, a)},
         {cap: 'graph', name: 'get_dependents', description: 'Transitive blast-radius of ONE node: everything that calls/imports/inherits it, directly or through intermediaries (reverse edges, ranked by proximity then connectivity). For a symbol, also follows importers of its containing file. Use before refactoring; get_neighbors shows only 1 hop, change_impact covers your whole current diff at once.', inputSchema: {type: 'object', properties: {label: {type: 'string', description: 'Node label or ID'}, depth: {type: 'integer', description: 'Max reverse hops, default 3', default: 3}, max_nodes: {type: 'integer', description: 'Max dependents to list, default 40', default: 40}}, required: ['label']}, run: (g, a) => ti.tGetDependents(g, a)},
         {cap: 'graph', name: 'change_impact', description: 'Blast radius of a change: by default diffs branch commits + staged/unstaged/untracked work against a base ref (auto merge-base with origin/main|master), OR takes an explicit `files` list (e.g. a PR\'s changed files — assesses a NOT-checked-out PR). Maps changed files/symbols onto the graph and lists everything depending on them (reverse edges, ranked by proximity + connectivity) with test coverage attached — untested hotspots called out. Run before opening or reviewing a PR; drill down with get_dependents, coverage detail via coverage_map.', inputSchema: {type: 'object', properties: {base: {type: 'string', description: 'Base ref, e.g. origin/main or HEAD~1 (default: first existing of origin/HEAD, origin/main, origin/master, main, master)'}, files: {type: 'array', items: {type: 'string'}, description: 'Explicit repo-relative changed-file list — skips the local git diff; use for PRs that are not checked out'}, depth: {type: 'integer', description: 'Max reverse hops, default 2'}, max_nodes: {type: 'integer', description: 'Max impacted nodes to list, default 40'}}}, run: (g, a, ctx) => ti.tChangeImpact(g, a, ctx)},
@@ -34,14 +34,14 @@ function buildTools({tg, ti, th, ta}) {
         {cap: 'health', name: 'run_audit', description: 'Full internal health audit of the repo: dead code (unused files/exports), dependency health (missing/undeclared and unused npm/Go/Python deps), structure (import cycles, orphan files, boundary-rule violations), and offline supply-chain checks (known OSV vulnerabilities, typosquats, lockfile drift). Filter by category/severity. Malware heuristics are opt-in (slow).', inputSchema: {type: 'object', properties: {category: {type: 'string', enum: ['unused', 'structure', 'vulnerability', 'malware'], description: 'Only findings of this category'}, min_severity: {type: 'string', enum: ['critical', 'high', 'medium', 'low', 'info'], description: 'Minimum severity to include'}, max_findings: {type: 'integer', description: 'Max findings to list, default 30'}, include_malware_scan: {type: 'boolean', description: 'Also grep installed packages for malware heuristics (slow)', default: false}}}, run: (g, a, ctx) => th.tRunAudit(g, a, ctx)},
         {cap: 'health', name: 'coverage_map', description: 'Map an existing test-coverage report (istanbul/lcov/coverage.py/Go cover.out — read offline, never runs tests) onto the code graph: per-module coverage plus refactor-risk hotspots — well-connected symbols with low coverage, ranked by degree × uncovered. Pair with get_dependents: many dependents + low coverage ⇒ write tests before changing.', inputSchema: {type: 'object', properties: {top_n: {type: 'integer', description: 'Max risk hotspots to list, default 15'}, path: {type: 'string', description: 'Optional repo-relative path prefix filter, e.g. src/query'}}}, run: (g, a, ctx) => th.tCoverageMap(g, a, ctx)},
         {cap: 'graph', name: 'list_communities', description: 'List graph communities named by their dominant folder (largest first) with sample files — a readable module overview; feed the list position into get_community.', inputSchema: {type: 'object', properties: {top_n: {type: 'integer', description: 'Max communities to list, default 20'}}}, run: (g, a, ctx) => th.tListCommunities(g, a, ctx)},
-        {cap: 'graph', name: 'module_map', description: 'Folder-level architecture map: modules with file/symbol counts plus the strongest module→module dependency edges. Fast orientation before diving into files.', inputSchema: {type: 'object', properties: {top_n: {type: 'integer', description: 'Max modules to list, default 25'}}}, run: (g, a, ctx) => th.tModuleMap(g, a, ctx)},
-        {cap: 'source', name: 'list_endpoints', description: 'Inventory of HTTP endpoints defined in the repo (Express/Fastify/Nest/Flask/FastAPI/Go mux …): method, path, handler, and file:line, deduped across code and OpenAPI docs.', inputSchema: {type: 'object', properties: {max_results: {type: 'integer', description: 'Max endpoints to list, default 100'}}}, run: (g, a, ctx) => th.tListEndpoints(g, a, ctx)},
+        {cap: 'graph', name: 'module_map', description: 'Folder-level architecture map with file/symbol counts and strongest module dependencies, separating runtime, TypeScript type-only and language compile-only coupling.', inputSchema: {type: 'object', properties: {top_n: {type: 'integer', description: 'Max modules to list, default 25'}}}, run: (g, a, ctx) => th.tModuleMap(g, a, ctx)},
+        {cap: 'source', name: 'list_endpoints', description: 'Inventory of HTTP endpoints defined in the repo (Express/Fastify/Nest/Flask/FastAPI/Go mux/Rust axum and actix-web …): method, path, handler, and file:line.', inputSchema: {type: 'object', properties: {max_results: {type: 'integer', description: 'Max endpoints to list, default 100'}}}, run: (g, a, ctx) => th.tListEndpoints(g, a, ctx)},
         {cap: 'build', name: 'rebuild_graph', description: "Rebuild this repo's code graph from current source (weavatrix's own web-tree-sitter builder), reload it in-memory, and report the STRUCTURAL DELTA vs the previous state — new/removed module dependencies, cycle changes, newly orphaned symbols. The prior state is saved as graph.prev.json for graph_diff. Call after significant edits.", inputSchema: {type: 'object', properties: {mode: {type: 'string', enum: ['full', 'no-tests', 'tests-only'], default: 'full'}, scope: {type: 'string', description: 'optional path prefix to limit the graph'}}}, run: (g, a, ctx) => ta.tRebuildGraph(g, a, ctx)},
         {cap: 'graph', name: 'graph_diff', description: 'Structural diff of the last rebuild: previous graph state (graph.prev.json, saved by rebuild_graph) vs current — architecture drift (new module dependencies), broken or introduced import cycles, symbols that lost their last caller. The semantic complement to the textual git diff for validating a refactor.', inputSchema: {type: 'object', properties: {path: {type: 'string', description: 'Optional node-id/path prefix to scope the diff, e.g. src/query'}}}, run: (g, a, ctx) => ti.tGraphDiff(g, a, ctx)},
         {cap: 'retarget', name: 'open_repo', description: 'OFFLINE RETARGET: switch this server to another local Git repository, building its graph when missing. This explicit tool call changes the active repository boundary; pass build:false to probe without building. Omit the retarget capability at registration to pin one repository.', inputSchema: {type: 'object', properties: {path: {type: 'string', description: 'Absolute path to a Git working tree'}, build: {type: 'boolean', description: 'Build the graph when missing (default true)', default: true}, mode: {type: 'string', enum: ['full', 'no-tests', 'tests-only'], default: 'full'}}, required: ['path']}, run: (g, a, ctx) => ta.tOpenRepo(g, a, ctx)},
         {cap: 'retarget', name: 'list_known_repos', description: 'OFFLINE RETARGET: list sibling repositories with existing graphs that can be selected through open_repo.', inputSchema: {type: 'object', properties: {}}, run: (g, a, ctx) => ta.tListKnownRepos(g, a, ctx)},
         {cap: 'online', name: 'refresh_advisories', description: "ONLINE, explicit opt-in: refresh the local OSV advisory store for this repo's lockfile-pinned packages (npm/PyPI/Go). Sends package names + versions to OSV.dev — never automatic, never source code. Afterwards run_audit reads the refreshed store fully offline (~/.weavatrix/advisories.json).", inputSchema: {type: 'object', properties: {timeout_ms: {type: 'integer', description: 'Per-request timeout, default 20000'}}}, run: (g, a, ctx) => ta.tRefreshAdvisories(g, a, ctx)},
-        {cap: 'online', name: 'sync_graph', description: 'ONLINE, explicit opt-in, off until configured: send a versioned allowlist of graph metadata to an endpoint you configure (env WEAVATRIX_SYNC_URL, optional WEAVATRIX_SYNC_TOKEN bearer auth). Unknown graph fields are discarded and source file bodies are never read for sync. Rebuild graphs created before 0.1.3 once to add typed-edge metadata.', inputSchema: {type: 'object', properties: {}}, run: (g, a, ctx) => ta.tSyncGraph(g, a, ctx)},
+        {cap: 'online', name: 'sync_graph', description: 'ONLINE, explicit opt-in, off until configured: send a versioned allowlist of graph metadata to an endpoint you configure (env WEAVATRIX_SYNC_URL, optional WEAVATRIX_SYNC_TOKEN bearer auth). Unknown graph fields are discarded and source file bodies are never read for sync. Rebuild graphs created before 0.1.4 once to add edge metadata v2.', inputSchema: {type: 'object', properties: {}}, run: (g, a, ctx) => ta.tSyncGraph(g, a, ctx)},
     ]
 }
 

package/src/mcp/graph-context.mjs

@@ -6,8 +6,8 @@ import {readFileSync, statSync} from 'node:fs'
 import {join} from 'node:path'
 import {spawnSync} from 'node:child_process'
 import {childProcessEnv} from '../child-env.js'
-import {buildFileImportGraph, findSccs} from '../analysis/dep-rules.js'
 import {resolveRepoPath} from '../repo-path.js'
+import {isStructuralRelation} from '../graph/relations.js'
 
 // ---- graph load + indexes -----------------------------------------------------------------------
 export function loadGraph(path) {
@@ -37,6 +37,7 @@ export function loadGraph(path) {
             relation: e.relation,
             confidence: e.confidence,
             ...(e.typeOnly === true ? {typeOnly: true} : {}),
+            ...(e.compileOnly === true ? {compileOnly: true} : {}),
             ...(Number.isInteger(e.line) ? {line: e.line} : {}),
             ...(typeof e.specifier === 'string' ? {specifier: e.specifier} : {}),
         }
@@ -51,15 +52,15 @@ export function loadGraph(path) {
 }
 
 export const isSymbol = (id) => String(id).includes('#')
-export const degreeOf = (g, id) => (g.out.get(id)?.length || 0) + (g.inn.get(id)?.length || 0)
 export const labelOf = (g, id) => {
     const n = g.byId.get(String(id))
     return n ? String(n.label ?? n.id) : String(id)
 }
 
-// "connectivity" degree ignores structural `contains` (parent→symbol nesting) so god_nodes surfaces real
-// call/import/reference hubs, not just files that hold many symbols.
-export const connList = (list) => (list || []).filter((e) => e.relation !== 'contains')
+// Connectivity ignores structural file/symbol and class/method ownership, so runtime/compile-time
+// dependency ranks never treat nesting as a call or import.
+export const connList = (list) => (list || []).filter((e) => !isStructuralRelation(e.relation))
+export const degreeOf = (g, id) => connList(g.out.get(id)).length + connList(g.inn.get(id)).length
 export const uniqueConnCount = (list) => new Set(connList(list).map((e) => String(e.id))).size
 
 // Resolve a user-supplied "label" to a node: exact id → exact label → ci label → substring (best degree).
@@ -203,164 +204,4 @@ export function rawGraph(ctx) {
     return rawGraphCache.data
 }
 
-// ---- graph diff ----------------------------------------------------------------------------------
-// One previous state is enough (4-13 MB per repo — cheap): rebuild_graph snapshots the outgoing
-// graph.json as graph.prev.json and reports the structural delta inline, at the exact moment the fix
-// is being verified. graph_diff re-queries the same pair later. Raw node/edge dumps would be noise —
-// the signal is aggregated: module-dependency drift, cycle count changes, newly orphaned symbols.
-export const prevGraphPathFor = (graphPath) => String(graphPath).replace(/\.json$/, '.prev.json')
-export const edgeEndpoint = (v) => String(v && typeof v === 'object' ? v.id : v)
-export const fileOfId = (id) => { const s = String(id); const h = s.indexOf('#'); return h < 0 ? s : s.slice(0, h) }
-const folderOfFile = (file) => {
-    const dirs = String(file || '').split(/[\\/]/).filter(Boolean).slice(0, -1)
-    return dirs.length ? dirs.slice(0, 2).join('/') : '(root)'
-}
-
-// Works on anything with {nodes, links}: the raw graph.json shape and the loadGraph struct alike.
-export function diffGraphs(oldG, newG) {
-    const oldEdgeTypesV = Number(oldG.edgeTypesV) || 0
-    const newEdgeTypesV = Number(newG.edgeTypesV) || 0
-    const schemaMigration = oldEdgeTypesV !== newEdgeTypesV
-    const nodeIds = (graph) => new Set((graph.nodes || []).map((n) => String(n.id)))
-    const oldNodes = nodeIds(oldG)
-    const newNodes = nodeIds(newG)
-
-    const edgeKey = (l) => `${edgeEndpoint(l.source)}|${l.relation || ''}|${schemaMigration ? 'untyped' : l.typeOnly === true ? 'type' : 'runtime'}|${edgeEndpoint(l.target)}`
-    const edgeSet = (graph) => new Set((graph.links || []).map(edgeKey))
-    const oldEdges = edgeSet(oldG)
-    const newEdges = edgeSet(newG)
-
-    const moduleEdges = (graph, typeOnly) => {
-        const set = new Set()
-        for (const l of graph.links || []) {
-            if (l.relation === 'contains') continue
-            if ((l.typeOnly === true) !== typeOnly) continue
-            const a = folderOfFile(fileOfId(edgeEndpoint(l.source)))
-            const b = folderOfFile(fileOfId(edgeEndpoint(l.target)))
-            if (a !== b) set.add(`${a} → ${b}`)
-        }
-        return set
-    }
-    const combinedModuleEdges = (graph) => {
-        const set = new Set()
-        for (const l of graph.links || []) {
-            if (l.relation === 'contains') continue
-            const a = folderOfFile(fileOfId(edgeEndpoint(l.source)))
-            const b = folderOfFile(fileOfId(edgeEndpoint(l.target)))
-            if (a !== b) set.add(`${a} → ${b}`)
-        }
-        return set
-    }
-    const oldMods = schemaMigration ? combinedModuleEdges(oldG) : moduleEdges(oldG, false)
-    const newMods = schemaMigration ? combinedModuleEdges(newG) : moduleEdges(newG, false)
-    const oldTypeMods = schemaMigration ? new Set() : moduleEdges(oldG, true)
-    const newTypeMods = schemaMigration ? new Set() : moduleEdges(newG, true)
-
-    const incoming = (graph) => {
-        const m = new Map()
-        for (const l of graph.links || []) {
-            if (l.relation === 'contains') continue
-            const t = edgeEndpoint(l.target)
-            m.set(t, (m.get(t) || 0) + 1)
-        }
-        return m
-    }
-    const oldIn = incoming(oldG)
-    const newIn = incoming(newG)
-
-    const cycles = (graph, includeTypeOnly) => {
-        try {
-            const sccs = findSccs(buildFileImportGraph(graph, {includeTypeOnly}).adj)
-                .map((members) => members.map(String).sort())
-                .sort((a, b) => b.length - a.length || a.join('\n').localeCompare(b.join('\n')))
-            return {
-                count: sccs.length,
-                largest: sccs[0]?.length || 0,
-                groups: sccs,
-            }
-        } catch {
-            return null
-        }
-    }
-    const cycleDelta = (before, after) => {
-        if (!before || !after) return null
-        const key = (group) => group.join('|')
-        const beforeKeys = new Set(before.groups.map(key))
-        const afterKeys = new Set(after.groups.map(key))
-        const overlap = (a, b) => {
-            const bSet = new Set(b)
-            return a.reduce((n, member) => n + (bSet.has(member) ? 1 : 0), 0)
-        }
-        const unmatchedBefore = before.groups.filter((group) => !afterKeys.has(key(group)))
-        const unmatchedAfter = after.groups.filter((group) => !beforeKeys.has(key(group)))
-        const changed = unmatchedAfter.filter((group) => unmatchedBefore.some((old) => overlap(group, old) >= 2))
-        const introduced = unmatchedAfter.filter((group) => !unmatchedBefore.some((old) => overlap(group, old) >= 2))
-        const resolved = unmatchedBefore.filter((group) => !unmatchedAfter.some((next) => overlap(group, next) >= 2))
-        return {
-            before: before.count,
-            after: after.count,
-            largestBefore: before.largest,
-            largestAfter: after.largest,
-            introduced: introduced.map(key),
-            resolved: resolved.map(key),
-            membershipChanged: changed.length,
-        }
-    }
-
-    return {
-        schemaMigration: schemaMigration ? {from: oldEdgeTypesV, to: newEdgeTypesV} : null,
-        nodes: {
-            added: [...newNodes].filter((id) => !oldNodes.has(id)),
-            removed: [...oldNodes].filter((id) => !newNodes.has(id))
-        },
-        edges: {
-            added: [...newEdges].filter((k) => !oldEdges.has(k)).length,
-            removed: [...oldEdges].filter((k) => !newEdges.has(k)).length
-        },
-        moduleEdges: {
-            added: [...newMods].filter((k) => !oldMods.has(k)),
-            removed: [...oldMods].filter((k) => !newMods.has(k)),
-            typeAdded: [...newTypeMods].filter((k) => !oldTypeMods.has(k)),
-            typeRemoved: [...oldTypeMods].filter((k) => !newTypeMods.has(k)),
-        },
-        // survived the rebuild but lost every caller/importer — likely made dead by the change
-        orphaned: [...oldIn.keys()].filter((id) => newNodes.has(id) && !newIn.has(id)),
-        cycles: {
-            runtime: schemaMigration ? null : cycleDelta(cycles(oldG, false), cycles(newG, false)),
-            typeInclusive: schemaMigration ? null : cycleDelta(cycles(oldG, true), cycles(newG, true)),
-        }
-    }
-}
-
-export function formatGraphDiff(d) {
-    if (!d.nodes.added.length && !d.nodes.removed.length && !d.edges.added && !d.edges.removed) {
-        return d.schemaMigration
-            ? `Graph edge schema upgraded v${d.schemaMigration.from} → v${d.schemaMigration.to}; typed baseline established. Runtime/type cycle and module classifications are intentionally not compared on this rebuild.`
-            : 'No structural change between the two graph states.'
-    }
-    const cap = (list, n) => list.slice(0, n).map((x) => `  ${x}`).concat(list.length > n ? [`  … +${list.length - n} more`] : [])
-    const lines = [`Structural delta: nodes +${d.nodes.added.length}/−${d.nodes.removed.length}, edges +${d.edges.added}/−${d.edges.removed}.`]
-    if (d.schemaMigration) lines.push(`Graph edge schema upgraded v${d.schemaMigration.from} → v${d.schemaMigration.to}; runtime/type cycle and module classifications are intentionally not compared until the next rebuild.`)
-    const runtime = d.cycles?.runtime
-    if (runtime && (runtime.before !== runtime.after || runtime.largestBefore !== runtime.largestAfter || runtime.introduced.length || runtime.resolved.length || runtime.membershipChanged)) {
-        const changes = []
-        if (runtime.introduced.length) changes.push(`${runtime.introduced.length} genuinely new runtime SCC(s) — review`)
-        if (runtime.resolved.length) changes.push(`${runtime.resolved.length} runtime SCC(s) resolved`)
-        if (runtime.membershipChanged) changes.push(`${runtime.membershipChanged} SCC membership change(s)`)
-        const verdict = changes.length ? `; ${changes.join('; ')}` : ''
-        lines.push(`Runtime import cycles: count ${runtime.before} → ${runtime.after}, largest SCC ${runtime.largestBefore} → ${runtime.largestAfter}${verdict}.`)
-    }
-    const all = d.cycles?.typeInclusive
-    if (all && (all.before !== all.after || all.largestBefore !== all.largestAfter) &&
-        (!runtime || all.before !== runtime.before || all.after !== runtime.after || all.largestBefore !== runtime.largestBefore || all.largestAfter !== runtime.largestAfter)) {
-        lines.push(`Type-inclusive dependency SCCs: count ${all.before} → ${all.after}, largest ${all.largestBefore} → ${all.largestAfter} (compile-time coupling, not necessarily a runtime cycle).`)
-    }
-    if (d.moduleEdges.added.length) lines.push('NEW module dependencies (architecture drift — review):', ...cap(d.moduleEdges.added, 12))
-    if (d.moduleEdges.removed.length) lines.push('Removed module dependencies (decoupling confirmed):', ...cap(d.moduleEdges.removed, 12))
-    if (d.moduleEdges.typeAdded.length) lines.push('New type-only module dependencies (compile-time coupling):', ...cap(d.moduleEdges.typeAdded, 12))
-    if (d.moduleEdges.typeRemoved.length) lines.push('Removed type-only module dependencies:', ...cap(d.moduleEdges.typeRemoved, 12))
-    if (d.orphaned.length) lines.push('Symbols that lost their last caller/importer (now dead?):', ...cap(d.orphaned, 10))
-    if (d.nodes.added.length) lines.push('Added nodes:', ...cap(d.nodes.added, 12))
-    if (d.nodes.removed.length) lines.push('Removed nodes:', ...cap(d.nodes.removed, 12))
-    return lines.join('\n')
-}
+export {prevGraphPathFor, edgeEndpoint, fileOfId, diffGraphs, formatGraphDiff} from './graph-diff.mjs'

package/src/mcp/graph-diff.mjs

@@ -0,0 +1,163 @@
+// Structural graph delta helpers split from graph-context so the process-lifetime graph indexes stay small.
+import {buildFileImportGraph, findSccs} from '../analysis/dep-rules.js'
+import {folderModuleOf} from '../analysis/graph-analysis.aggregate.js'
+import {isStructuralRelation} from '../graph/relations.js'
+
+// ---- graph diff ----------------------------------------------------------------------------------
+// One previous state is enough (4-13 MB per repo — cheap): rebuild_graph snapshots the outgoing
+// graph.json as graph.prev.json and reports the structural delta inline, at the exact moment the fix
+// is being verified. graph_diff re-queries the same pair later. Raw node/edge dumps would be noise —
+// the signal is aggregated: module-dependency drift, cycle count changes, newly orphaned symbols.
+export const prevGraphPathFor = (graphPath) => String(graphPath).replace(/\.json$/, '.prev.json')
+export const edgeEndpoint = (v) => String(v && typeof v === 'object' ? v.id : v)
+export const fileOfId = (id) => { const s = String(id); const h = s.indexOf('#'); return h < 0 ? s : s.slice(0, h) }
+const folderOfFile = folderModuleOf
+
+// Works on anything with {nodes, links}: the raw graph.json shape and the loadGraph struct alike.
+export function diffGraphs(oldG, newG) {
+    const oldEdgeTypesV = Number(oldG.edgeTypesV) || 0
+    const newEdgeTypesV = Number(newG.edgeTypesV) || 0
+    const schemaMigration = oldEdgeTypesV !== newEdgeTypesV
+    const nodeIds = (graph) => new Set((graph.nodes || []).map((n) => String(n.id)))
+    const oldNodes = nodeIds(oldG)
+    const newNodes = nodeIds(newG)
+
+    const edgeClass = (l) => l.typeOnly === true ? 'type' : l.compileOnly === true ? 'compile' : 'runtime'
+    const edgeKey = (l) => `${edgeEndpoint(l.source)}|${l.relation || ''}|${schemaMigration ? 'untyped' : edgeClass(l)}|${edgeEndpoint(l.target)}`
+    const edgeSet = (graph) => new Set((graph.links || []).map(edgeKey))
+    const oldEdges = edgeSet(oldG)
+    const newEdges = edgeSet(newG)
+
+    const moduleEdges = (graph, classification) => {
+        const set = new Set()
+        for (const l of graph.links || []) {
+            if (isStructuralRelation(l.relation)) continue
+            if (edgeClass(l) !== classification) continue
+            const a = folderOfFile(fileOfId(edgeEndpoint(l.source)))
+            const b = folderOfFile(fileOfId(edgeEndpoint(l.target)))
+            if (a !== b) set.add(`${a} → ${b}`)
+        }
+        return set
+    }
+    // A parser/schema upgrade can discover edges that the old graph could not represent (Rust use/mod in
+    // edgeTypesV2). Do not call that architecture drift: establish a fresh classification baseline.
+    const oldMods = schemaMigration ? new Set() : moduleEdges(oldG, 'runtime')
+    const newMods = schemaMigration ? new Set() : moduleEdges(newG, 'runtime')
+    const oldTypeMods = schemaMigration ? new Set() : moduleEdges(oldG, 'type')
+    const newTypeMods = schemaMigration ? new Set() : moduleEdges(newG, 'type')
+    const oldCompileMods = schemaMigration ? new Set() : moduleEdges(oldG, 'compile')
+    const newCompileMods = schemaMigration ? new Set() : moduleEdges(newG, 'compile')
+
+    const incoming = (graph) => {
+        const m = new Map()
+        for (const l of graph.links || []) {
+            if (isStructuralRelation(l.relation)) continue
+            const t = edgeEndpoint(l.target)
+            m.set(t, (m.get(t) || 0) + 1)
+        }
+        return m
+    }
+    const oldIn = incoming(oldG)
+    const newIn = incoming(newG)
+
+    const cycles = (graph, includeTypeOnly) => {
+        try {
+            const sccs = findSccs(buildFileImportGraph(graph, {includeTypeOnly}).adj)
+                .map((members) => members.map(String).sort())
+                .sort((a, b) => b.length - a.length || a.join('\n').localeCompare(b.join('\n')))
+            return {
+                count: sccs.length,
+                largest: sccs[0]?.length || 0,
+                groups: sccs,
+            }
+        } catch {
+            return null
+        }
+    }
+    const cycleDelta = (before, after) => {
+        if (!before || !after) return null
+        const key = (group) => group.join('|')
+        const beforeKeys = new Set(before.groups.map(key))
+        const afterKeys = new Set(after.groups.map(key))
+        const overlap = (a, b) => {
+            const bSet = new Set(b)
+            return a.reduce((n, member) => n + (bSet.has(member) ? 1 : 0), 0)
+        }
+        const unmatchedBefore = before.groups.filter((group) => !afterKeys.has(key(group)))
+        const unmatchedAfter = after.groups.filter((group) => !beforeKeys.has(key(group)))
+        const changed = unmatchedAfter.filter((group) => unmatchedBefore.some((old) => overlap(group, old) >= 2))
+        const introduced = unmatchedAfter.filter((group) => !unmatchedBefore.some((old) => overlap(group, old) >= 2))
+        const resolved = unmatchedBefore.filter((group) => !unmatchedAfter.some((next) => overlap(group, next) >= 2))
+        return {
+            before: before.count,
+            after: after.count,
+            largestBefore: before.largest,
+            largestAfter: after.largest,
+            introduced: introduced.map(key),
+            resolved: resolved.map(key),
+            membershipChanged: changed.length,
+        }
+    }
+
+    return {
+        schemaMigration: schemaMigration ? {from: oldEdgeTypesV, to: newEdgeTypesV} : null,
+        nodes: {
+            added: [...newNodes].filter((id) => !oldNodes.has(id)),
+            removed: [...oldNodes].filter((id) => !newNodes.has(id))
+        },
+        edges: {
+            added: [...newEdges].filter((k) => !oldEdges.has(k)).length,
+            removed: [...oldEdges].filter((k) => !newEdges.has(k)).length
+        },
+        moduleEdges: {
+            added: [...newMods].filter((k) => !oldMods.has(k)),
+            removed: [...oldMods].filter((k) => !newMods.has(k)),
+            typeAdded: [...newTypeMods].filter((k) => !oldTypeMods.has(k)),
+            typeRemoved: [...oldTypeMods].filter((k) => !newTypeMods.has(k)),
+            compileAdded: [...newCompileMods].filter((k) => !oldCompileMods.has(k)),
+            compileRemoved: [...oldCompileMods].filter((k) => !newCompileMods.has(k)),
+        },
+        // survived the rebuild but lost every caller/importer — likely made dead by the change
+        orphaned: [...oldIn.keys()].filter((id) => newNodes.has(id) && !newIn.has(id)),
+        cycles: {
+            runtime: schemaMigration ? null : cycleDelta(cycles(oldG, false), cycles(newG, false)),
+            // Backward-compatible field name: since edgeTypesV 2 this includes typeOnly and compileOnly.
+            typeInclusive: schemaMigration ? null : cycleDelta(cycles(oldG, true), cycles(newG, true)),
+        }
+    }
+}
+
+export function formatGraphDiff(d) {
+    if (!d.nodes.added.length && !d.nodes.removed.length && !d.edges.added && !d.edges.removed) {
+        return d.schemaMigration
+            ? `Graph edge schema upgraded v${d.schemaMigration.from} → v${d.schemaMigration.to}; compile-time baseline established. Runtime/compile-time cycle and module classifications are intentionally not compared on this rebuild.`
+            : 'No structural change between the two graph states.'
+    }
+    const cap = (list, n) => list.slice(0, n).map((x) => `  ${x}`).concat(list.length > n ? [`  … +${list.length - n} more`] : [])
+    const lines = [`Structural delta: nodes +${d.nodes.added.length}/−${d.nodes.removed.length}, edges +${d.edges.added}/−${d.edges.removed}.`]
+    if (d.schemaMigration) lines.push(`Graph edge schema upgraded v${d.schemaMigration.from} → v${d.schemaMigration.to}; runtime/compile-time cycle and module classifications are intentionally not compared until the next rebuild.`)
+    const runtime = d.cycles?.runtime
+    if (runtime && (runtime.before !== runtime.after || runtime.largestBefore !== runtime.largestAfter || runtime.introduced.length || runtime.resolved.length || runtime.membershipChanged)) {
+        const changes = []
+        if (runtime.introduced.length) changes.push(`${runtime.introduced.length} genuinely new runtime SCC(s) — review`)
+        if (runtime.resolved.length) changes.push(`${runtime.resolved.length} runtime SCC(s) resolved`)
+        if (runtime.membershipChanged) changes.push(`${runtime.membershipChanged} SCC membership change(s)`)
+        const verdict = changes.length ? `; ${changes.join('; ')}` : ''
+        lines.push(`Runtime import cycles: count ${runtime.before} → ${runtime.after}, largest SCC ${runtime.largestBefore} → ${runtime.largestAfter}${verdict}.`)
+    }
+    const all = d.cycles?.typeInclusive
+    if (all && (all.before !== all.after || all.largestBefore !== all.largestAfter) &&
+        (!runtime || all.before !== runtime.before || all.after !== runtime.after || all.largestBefore !== runtime.largestBefore || all.largestAfter !== runtime.largestAfter)) {
+        lines.push(`Compile-time-inclusive dependency SCCs: count ${all.before} → ${all.after}, largest ${all.largestBefore} → ${all.largestAfter} (compile-time coupling, not necessarily a runtime cycle).`)
+    }
+    if (d.moduleEdges.added.length) lines.push('NEW module dependencies (architecture drift — review):', ...cap(d.moduleEdges.added, 12))
+    if (d.moduleEdges.removed.length) lines.push('Removed module dependencies (decoupling confirmed):', ...cap(d.moduleEdges.removed, 12))
+    if (d.moduleEdges.typeAdded.length) lines.push('New type-only module dependencies (compile-time coupling):', ...cap(d.moduleEdges.typeAdded, 12))
+    if (d.moduleEdges.typeRemoved.length) lines.push('Removed type-only module dependencies:', ...cap(d.moduleEdges.typeRemoved, 12))
+    if (d.moduleEdges.compileAdded.length) lines.push('New compile-only module dependencies (compile-time coupling):', ...cap(d.moduleEdges.compileAdded, 12))
+    if (d.moduleEdges.compileRemoved.length) lines.push('Removed compile-only module dependencies:', ...cap(d.moduleEdges.compileRemoved, 12))
+    if (d.orphaned.length) lines.push('Symbols that lost their last caller/importer (now dead?):', ...cap(d.orphaned, 10))
+    if (d.nodes.added.length) lines.push('Added nodes:', ...cap(d.nodes.added, 12))
+    if (d.nodes.removed.length) lines.push('Removed nodes:', ...cap(d.nodes.removed, 12))
+    return lines.join('\n')
+}

package/src/mcp/sync-payload.mjs

@@ -9,6 +9,27 @@ function metadataString(value, max = 4096) {
         : undefined;
 }
 
+// graph.json is derived data and may be edited independently of the repository. Never trust a path
+// merely because it occupies an allowlisted field: sync only accepts canonical-looking repo-relative
+// paths, on every host OS. Graph IDs append `#symbol@line`, so validate their file portion separately
+// while preserving the complete ID on the wire.
+function repoRelativePathString(value, max = 4096) {
+    const path = metadataString(value, max);
+    if (!path) return undefined;
+    if (/^(?:[a-z][a-z0-9+.-]*:|[\\/])/i.test(path)) return undefined; // URI, drive path, POSIX or UNC absolute
+    const segments = path.split(/[\\/]/);
+    if (segments.some((segment) => segment === '.' || segment === '..')) return undefined;
+    return path;
+}
+
+function graphIdString(value) {
+    const id = metadataString(value);
+    if (!id) return undefined;
+    const hash = id.indexOf('#');
+    const file = hash < 0 ? id : id.slice(0, hash);
+    return repoRelativePathString(file) ? id : undefined;
+}
+
 function finiteNumber(value) {
     return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
 }
@@ -37,12 +58,12 @@ function sanitizeComplexity(value) {
 
 function sanitizeNode(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
-    const id = metadataString(value.id);
+    const id = graphIdString(value.id);
     if (!id) return null;
     const out = {id};
     setIf(out, 'label', metadataString(value.label, 1024));
     setIf(out, 'file_type', metadataString(value.file_type, 32));
-    setIf(out, 'source_file', metadataString(value.source_file));
+    setIf(out, 'source_file', repoRelativePathString(value.source_file));
     const sourceLocation = metadataString(value.source_location, 32);
     const sourceEnd = metadataString(value.source_end, 32);
     if (sourceLocation && /^L\d+$/.test(sourceLocation)) out.source_location = sourceLocation;
@@ -57,13 +78,14 @@ function sanitizeNode(value) {
 
 function sanitizeLink(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
-    const source = metadataString(value.source);
-    const target = metadataString(value.target);
+    const source = graphIdString(value.source);
+    const target = graphIdString(value.target);
     if (!source || !target) return null;
     const out = {source, target};
     setIf(out, 'relation', metadataString(value.relation, 32));
     setIf(out, 'confidence', metadataString(value.confidence, 32));
     if (value.typeOnly === true) out.typeOnly = true;
+    if (value.compileOnly === true) out.compileOnly = true;
     const line = finiteNumber(value.line);
     if (line !== undefined && Number.isInteger(line) && line >= 0) out.line = line;
     setIf(out, 'specifier', metadataString(value.specifier));
@@ -72,7 +94,7 @@ function sanitizeLink(value) {
 
 function sanitizeExternalImport(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value)) return null;
-    const file = metadataString(value.file);
+    const file = repoRelativePathString(value.file);
     if (!file) return null;
     const out = {file};
     for (const key of ['spec', 'target']) setIf(out, key, metadataString(value[key]));
@@ -89,8 +111,8 @@ export function createSyncPayload(raw) {
     if (!raw || typeof raw !== 'object' || Array.isArray(raw) || raw.repoBoundaryV !== 1) {
         throw new Error('graph predates repository-boundary hardening');
     }
-    if (!Number.isInteger(raw.edgeTypesV) || raw.edgeTypesV < 1) {
-        throw new Error('graph predates typed import edges');
+    if (!Number.isInteger(raw.edgeTypesV) || raw.edgeTypesV < 2) {
+        throw new Error('graph predates compile-only edge metadata');
     }
     const nodes = Array.isArray(raw.nodes) ? raw.nodes.map(sanitizeNode).filter(Boolean) : [];
     const links = Array.isArray(raw.links) ? raw.links.map(sanitizeLink).filter(Boolean) : [];
@@ -100,7 +122,7 @@ export function createSyncPayload(raw) {
     return {
         syncPayloadV: 2,
         repoBoundaryV: 1,
-        edgeTypesV: 1,
+        edgeTypesV: 2,
         extImportsV: Number.isInteger(raw.extImportsV) ? raw.extImportsV : 0,
         complexityV: Number.isInteger(raw.complexityV) ? raw.complexityV : 0,
         nodes,

package/src/mcp/tools-actions.mjs

@@ -45,7 +45,7 @@ export async function tOpenRepo(g, args, ctx) {
     if (existsSync(graphPath)) {
         try {
             const saved = JSON.parse(readFileSync(graphPath, 'utf8'))
-            upgrade = !Number.isInteger(saved.edgeTypesV) || saved.edgeTypesV < 1
+            upgrade = !Number.isInteger(saved.edgeTypesV) || saved.edgeTypesV < 2
         } catch {
             upgrade = true
         }
@@ -53,7 +53,7 @@ export async function tOpenRepo(g, args, ctx) {
     if (!existsSync(graphPath) || upgrade) {
         if (args.build === false) {
             return upgrade
-                ? `The existing graph for ${repoPath} predates typed import edges. Re-call without build:false to upgrade it before switching.`
+                ? `The existing graph for ${repoPath} predates compile-only edge metadata (edge schema v2). Re-call without build:false to upgrade it before switching.`
                 : `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'
@@ -71,7 +71,7 @@ export async function tOpenRepo(g, args, ctx) {
         ctx.reload()
         return `Failed to load ${graphPath} — still targeting the previous repo (${prev.repoRoot || 'none'}).`
     }
-    const buildNote = built ? (upgrade ? ' (graph upgraded to typed import edges)' : ' (graph built fresh)') : ''
+    const buildNote = built ? (upgrade ? ' (graph upgraded to edge metadata v2)' : ' (graph built fresh)') : ''
     return `Opened ${repoPath}${buildNote}: ${loaded.nodes.length} nodes / ${loaded.links.length} edges. All tools now target this repo.`
 }
 

package/src/mcp/tools-graph-hubs.mjs

@@ -0,0 +1,58 @@
+// Connectivity-hub reporting, split from the general graph query tools.
+import {connList} from './graph-context.mjs'
+
+const isCompileTimeEdge = (edge) => edge?.typeOnly === true || edge?.compileOnly === true
+
+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 rawOuts = g.out.get(String(node.id)) || []
+            const rawIns = g.inn.get(String(node.id)) || []
+            const outs = connList(rawOuts)
+            const ins = connList(rawIns)
+            const ownedMethods = new Set(rawOuts.filter((e) => e.relation === 'method').map((e) => String(e.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) => !isCompileTimeEdge(e)).map((e) => String(e.id)))
+            const compileOnlyIds = new Set([...outs, ...ins].filter(isCompileTimeEdge).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,
+                ownedMethods: ownedMethods.size,
+            }
+        })
+        .filter((entry) => entry.deg > 0 || entry.ownedMethods > 0)
+        .sort((a, b) => b.runtime - a.runtime || b.deg - a.deg || b.ownedMethods - a.ownedMethods || 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 ownership shown separately):`,
+        ...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.ownedMethods ? `; owns ${r.ownedMethods} method${r.ownedMethods === 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')
+}