weavatrix 0.1.3 → 0.2.0

package/src/mcp/evidence-snapshot.package-graph.mjs

@@ -0,0 +1,249 @@
+import {createHash} from 'node:crypto'
+import {readFileSync, statSync} from 'node:fs'
+import {createRepoBoundary} from '../repo-path.js'
+import {CAPS, STATE, compareText, safeToken} from './evidence-snapshot.common.mjs'
+
+const LOCKFILES = ['npm-shrinkwrap.json', 'package-lock.json']
+const MAX_LOCKFILE_BYTES = 64 * 1024 * 1024
+const MAX_PACKAGE_RECORDS = 50_000
+const MAX_DEPENDENCY_DECLARATIONS = 200_000
+const PACKAGE_NAME = /^(?:@[a-z0-9._-]+\/)?[a-z0-9][a-z0-9._-]*$/i
+const PACKAGE_VERSION = /^[A-Za-z0-9][A-Za-z0-9._+~-]*$/
+
+const packageVersion = (value) => {
+    const version = safeToken(value, 128)
+    return version && PACKAGE_VERSION.test(version) ? version : null
+}
+
+const emptyCount = () => ({total: 0, returned: 0, truncated: false})
+const emptyDeclarations = () => ({total: 0, resolved: 0, unresolved: 0, local: 0, optionalMissing: 0})
+
+function emptyGraph(state, reason, extras = {}) {
+    return {
+        state,
+        ecosystem: 'npm',
+        root: '(root)',
+        ...extras,
+        completeness: {
+            nodes: emptyCount(),
+            edges: emptyCount(),
+            declarations: emptyDeclarations(),
+            reasons: reason ? [reason] : [],
+        },
+        nodes: [],
+        edges: [],
+    }
+}
+
+function normalizeLockPath(value) {
+    if (typeof value !== 'string' || value.length > 4096 || /[\u0000-\u001f\u007f]/.test(value)) return null
+    const raw = value.replace(/\\/g, '/')
+    if (/^(?:[a-z][a-z0-9+.-]*:|\/)/i.test(raw)) return null
+    const normalized = raw.replace(/\/$/, '')
+    if (normalized === '') return ''
+    const parts = normalized.split('/')
+    return parts.every((part) => part && part !== '.' && part !== '..') ? normalized : null
+}
+
+function packageNameFromPath(packagePath) {
+    const match = packagePath.match(/(?:^|\/)node_modules\/((?:@[^/]+\/)?[^/]+)$/)
+    const name = match?.[1]
+    return name && name.length <= 256 && PACKAGE_NAME.test(name) ? name : null
+}
+
+function packageId(name, version, packagePath) {
+    const location = createHash('sha256').update(packagePath).digest('hex').slice(0, 12)
+    return `npm:${name}@${version}:${location}`
+}
+
+function parentInstallPath(packagePath) {
+    const marker = packagePath.lastIndexOf('/node_modules/')
+    return marker >= 0 ? packagePath.slice(0, marker) : ''
+}
+
+function dependencyDeclarations(record) {
+    const declarations = new Map()
+    const add = (values, kind, replace = false) => {
+        if (!values || typeof values !== 'object' || Array.isArray(values)) return
+        for (const name of Object.keys(values)) {
+            if (name.length > 256 || !PACKAGE_NAME.test(name)) continue
+            if (replace || !declarations.has(name)) declarations.set(name, kind)
+        }
+    }
+    add(record?.dependencies, 'runtime')
+    add(record?.devDependencies, 'dev')
+    add(record?.optionalDependencies, 'optional', true)
+    if (record?.peerDependencies && typeof record.peerDependencies === 'object' && !Array.isArray(record.peerDependencies)) {
+        for (const name of Object.keys(record.peerDependencies)) {
+            if (name.length > 256 || !PACKAGE_NAME.test(name) || declarations.has(name)) continue
+            const optional = record?.peerDependenciesMeta?.[name]?.optional === true
+            declarations.set(name, optional ? 'optional-peer' : 'peer')
+        }
+    }
+    return [...declarations].map(([name, kind]) => ({name, kind}))
+        .sort((a, b) => compareText(a.name, b.name) || compareText(a.kind, b.kind))
+}
+
+function resolveDependency(sourcePath, name, records, externalNodes) {
+    let cursor = sourcePath
+    const seen = new Set()
+    while (!seen.has(cursor)) {
+        seen.add(cursor)
+        const candidate = cursor ? `${cursor}/node_modules/${name}` : `node_modules/${name}`
+        const record = records.get(candidate)
+        if (record) {
+            if (record.link === true) return {kind: 'local'}
+            const node = externalNodes.get(candidate)
+            return node ? {kind: 'external', node} : {kind: 'unresolved'}
+        }
+        if (!cursor) break
+        cursor = parentInstallPath(cursor)
+    }
+    return {kind: 'unresolved'}
+}
+
+function parseLock(lock, lockfile) {
+    const lockfileVersion = Number(lock?.lockfileVersion || 0)
+    const extras = {lockfile, lockfileVersion: Number.isFinite(lockfileVersion) ? Math.trunc(lockfileVersion) : 0}
+    if (![2, 3].includes(lockfileVersion) || !lock?.packages || typeof lock.packages !== 'object' || Array.isArray(lock.packages)) {
+        return emptyGraph(STATE.PARTIAL, 'PACKAGE_LOCK_V2_V3_REQUIRED', extras)
+    }
+
+    const allKeys = Object.keys(lock.packages).sort(compareText)
+    const selectedKeys = allKeys.slice(0, MAX_PACKAGE_RECORDS)
+    const reasons = []
+    if (selectedKeys.length < allKeys.length) reasons.push('LOCKFILE_PACKAGE_RECORD_LIMIT_REACHED')
+
+    const records = new Map()
+    let invalidRecords = 0
+    for (const rawPath of selectedKeys) {
+        const packagePath = normalizeLockPath(rawPath)
+        const record = lock.packages[rawPath]
+        if (packagePath == null || !record || typeof record !== 'object' || Array.isArray(record)) {
+            invalidRecords++
+            continue
+        }
+        const insideNodeModules = packagePath.startsWith('node_modules/') || packagePath.includes('/node_modules/')
+        if (insideNodeModules && !packageNameFromPath(packagePath)) {
+            invalidRecords++
+            continue
+        }
+        if (records.has(packagePath)) {
+            invalidRecords++
+            continue
+        }
+        records.set(packagePath, record)
+    }
+    if (invalidRecords > 0) reasons.push('INVALID_LOCKFILE_PACKAGE_RECORDS')
+
+    const externalNodes = new Map()
+    let invalidPackageVersions = 0
+    for (const [packagePath, record] of records) {
+        const name = packageNameFromPath(packagePath)
+        const version = packageVersion(record.version)
+        if (!name || record.link === true) continue
+        if (!version) { invalidPackageVersions++; continue }
+        externalNodes.set(packagePath, {
+            id: packageId(name, version, packagePath),
+            name,
+            version,
+            direct: false,
+            dev: record.dev === true || record.devOptional === true,
+            optional: record.optional === true || record.devOptional === true,
+            peer: record.peer === true,
+        })
+    }
+    if (invalidPackageVersions > 0) reasons.push('INVALID_LOCKFILE_PACKAGE_VERSIONS')
+
+    const edgeMap = new Map()
+    const declarations = emptyDeclarations()
+    let declarationLimitReached = false
+    const sources = [...records].filter(([packagePath]) =>
+        packageNameFromPath(packagePath) == null || externalNodes.has(packagePath))
+        .sort(([a], [b]) => compareText(a, b))
+
+    outer: for (const [sourcePath, record] of sources) {
+        const sourceNode = externalNodes.get(sourcePath)
+        const sourceId = sourceNode?.id || '(root)'
+        for (const declaration of dependencyDeclarations(record)) {
+            if (declarations.total >= MAX_DEPENDENCY_DECLARATIONS) {
+                declarationLimitReached = true
+                break outer
+            }
+            declarations.total++
+            const resolved = resolveDependency(sourcePath, declaration.name, records, externalNodes)
+            if (resolved.kind === 'local') {
+                declarations.local++
+                continue
+            }
+            if (resolved.kind !== 'external') {
+                if (declaration.kind === 'optional' || declaration.kind === 'optional-peer') declarations.optionalMissing++
+                else declarations.unresolved++
+                continue
+            }
+            declarations.resolved++
+            if (sourceId === '(root)') resolved.node.direct = true
+            if (sourceId === resolved.node.id) continue
+            const edge = {from: sourceId, to: resolved.node.id, kind: declaration.kind}
+            edgeMap.set(`${edge.from}\0${edge.to}\0${edge.kind}`, edge)
+        }
+    }
+    if (declarationLimitReached) reasons.push('LOCKFILE_DEPENDENCY_DECLARATION_LIMIT_REACHED')
+    if (declarations.unresolved > 0) reasons.push('UNRESOLVED_LOCKFILE_DEPENDENCIES')
+
+    const allNodes = [...externalNodes.values()].sort((a, b) =>
+        Number(b.direct) - Number(a.direct) || compareText(a.name, b.name) ||
+        compareText(a.version, b.version) || compareText(a.id, b.id))
+    const nodes = allNodes.slice(0, CAPS.packageGraphNodes)
+    const nodeIds = new Set(nodes.map((node) => node.id))
+    const allEdges = [...edgeMap.values()].sort((a, b) =>
+        compareText(a.from, b.from) || compareText(a.to, b.to) || compareText(a.kind, b.kind))
+    const eligibleEdges = allEdges.filter((edge) =>
+        (edge.from === '(root)' || nodeIds.has(edge.from)) && nodeIds.has(edge.to))
+    const edges = eligibleEdges.slice(0, CAPS.packageGraphEdges)
+    const nodesTruncated = nodes.length < allNodes.length
+    const edgesTruncated = edges.length < allEdges.length
+    if (nodesTruncated) reasons.push('PACKAGE_NODE_LIMIT_REACHED')
+    if (edgesTruncated) reasons.push('PACKAGE_EDGE_LIMIT_REACHED')
+
+    return {
+        state: reasons.length ? STATE.PARTIAL : STATE.COMPLETE,
+        ecosystem: 'npm',
+        lockfile,
+        lockfileVersion,
+        root: '(root)',
+        completeness: {
+            nodes: {total: allNodes.length, returned: nodes.length, truncated: nodesTruncated},
+            edges: {total: allEdges.length, returned: edges.length, truncated: edgesTruncated},
+            declarations,
+            reasons: [...new Set(reasons)].sort(compareText),
+        },
+        nodes,
+        edges,
+    }
+}
+
+export function buildPackageDependencyGraph(repoRoot) {
+    const boundary = createRepoBoundary(repoRoot)
+    if (!boundary.root) return emptyGraph(STATE.ERROR, 'INVALID_REPOSITORY_ROOT')
+
+    let selected = null
+    for (const lockfile of LOCKFILES) {
+        const resolved = boundary.resolve(lockfile)
+        if (resolved.ok) {
+            selected = {lockfile, path: resolved.path}
+            break
+        }
+    }
+    if (!selected) return emptyGraph(STATE.NOT_APPLICABLE, 'PACKAGE_LOCK_V2_V3_NOT_FOUND')
+
+    try {
+        if (statSync(selected.path).size > MAX_LOCKFILE_BYTES) {
+            return emptyGraph(STATE.ERROR, 'PACKAGE_LOCK_SIZE_LIMIT_REACHED', {lockfile: selected.lockfile})
+        }
+        const lock = JSON.parse(readFileSync(selected.path, 'utf8'))
+        return parseLock(lock, selected.lockfile)
+    } catch {
+        return emptyGraph(STATE.ERROR, 'PACKAGE_LOCK_READ_ERROR', {lockfile: selected.lockfile})
+    }
+}

package/src/mcp/evidence-snapshot.structure.mjs

@@ -0,0 +1,81 @@
+import {createHash} from 'node:crypto'
+import {readFileSync} from 'node:fs'
+import {buildFileImportGraph, checkBoundaries, findSccs, representativeCycle} from '../analysis/dep-rules.js'
+import {createRepoBoundary} from '../repo-path.js'
+import {CAPS, bounded, compareText, repoRelativePath, safeToken} from './evidence-snapshot.common.mjs'
+
+const MAX_CYCLE_MEMBERS = 200
+const SEVERITIES = new Set(['critical', 'high', 'medium', 'low', 'info'])
+const hash = (value) => createHash('sha256').update(value).digest('hex').slice(0, 24)
+
+function sortedSccs(adjacency) {
+    return findSccs(adjacency)
+        .map((members) => members.map((member) => repoRelativePath(member)).filter(Boolean).sort(compareText))
+        .filter((members) => members.length > 1)
+        .sort((a, b) => b.length - a.length || compareText(a.join('\0'), b.join('\0')))
+}
+
+function cycleFact(kind, adjacency, members) {
+    const representative = representativeCycle(adjacency, members).map((member) => repoRelativePath(member)).filter(Boolean)
+    return {
+        id: hash(`${kind}\0${members.join('\0')}`),
+        kind,
+        size: members.length,
+        members: members.slice(0, MAX_CYCLE_MEMBERS),
+        membersTruncated: members.length > MAX_CYCLE_MEMBERS,
+        representativePath: representative.slice(0, MAX_CYCLE_MEMBERS + 1),
+    }
+}
+
+function readRules(repoRoot) {
+    try {
+        const boundary = createRepoBoundary(repoRoot)
+        const resolved = boundary.resolve('.weavatrix-deps.json')
+        if (!resolved.ok) return {rules: {}, state: 'NOT_APPLICABLE'}
+        const parsed = JSON.parse(readFileSync(resolved.path, 'utf8'))
+        const hasRules = Array.isArray(parsed?.forbidden) && parsed.forbidden.length > 0 ||
+            Array.isArray(parsed?.allowedOnly) && parsed.allowedOnly.length > 0
+        return {rules: parsed && typeof parsed === 'object' ? parsed : {}, state: hasRules ? 'COMPLETE' : 'NOT_APPLICABLE'}
+    } catch {
+        return {rules: {}, state: 'ERROR'}
+    }
+}
+
+function boundaryFact(value) {
+    const from = repoRelativePath(value?.from), to = repoRelativePath(value?.to)
+    if (!from || !to || !['forbidden', 'allowedOnly'].includes(value?.kind)) return null
+    const name = safeToken(value?.name, 96)
+    return {
+        kind: value.kind,
+        ruleId: name || hash(String(value?.name || 'unnamed-rule')),
+        severity: SEVERITIES.has(value?.severity) ? value.severity : 'medium',
+        from,
+        to,
+    }
+}
+
+export function buildStructureEvidence(graph, repoRoot) {
+    try {
+        const imports = buildFileImportGraph(graph)
+        const runtimeSccs = sortedSccs(imports.runtimeAdj)
+        const runtimeKeys = new Set(runtimeSccs.map((members) => members.join('\0')))
+        const compileSccs = sortedSccs(imports.allAdj).filter((members) => !runtimeKeys.has(members.join('\0')))
+        const allCycles = [
+            ...runtimeSccs.map((members) => cycleFact('runtime', imports.runtimeAdj, members)),
+            ...compileSccs.map((members) => cycleFact('compile-time', imports.allAdj, members)),
+        ].sort((a, b) => a.kind === b.kind ? b.size - a.size || compareText(a.id, b.id) : a.kind === 'runtime' ? -1 : 1)
+        const cycles = bounded(allCycles, CAPS.architectureFindings)
+        const rules = readRules(repoRoot)
+        const allBoundaries = checkBoundaries(imports.runtimeEdges, rules.rules)
+            .map(boundaryFact).filter(Boolean)
+            .sort((a, b) => compareText(a.ruleId, b.ruleId) || compareText(a.from, b.from) || compareText(a.to, b.to))
+        const boundaries = bounded(allBoundaries, CAPS.architectureFindings)
+        return {state: 'COMPLETE', rulesState: rules.state, cycles, boundaries}
+    } catch {
+        return {
+            state: 'ERROR', rulesState: 'ERROR',
+            cycles: {items: [], completeness: {total: 0, returned: 0, truncated: false}},
+            boundaries: {items: [], completeness: {total: 0, returned: 0, truncated: false}},
+        }
+    }
+}

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,8 +37,12 @@ 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} : {}),
+            ...(e.barrelProxy === true ? {barrelProxy: true} : {}),
+            ...(e.semanticOrigin === true ? {semanticOrigin: true} : {}),
+            ...(typeof e.viaBarrel === 'string' ? {viaBarrel: e.viaBarrel} : {}),
         }
         push(out, s, {id: t, ...metadata})
         push(inn, t, {id: s, ...metadata})
@@ -47,19 +51,31 @@ export function loadGraph(path) {
         nodes, links, byId, byLabel, out, inn,
         repoBoundaryV: Number(raw.repoBoundaryV) || 0,
         edgeTypesV: Number(raw.edgeTypesV) || 0,
+        barrelResolutionV: Number(raw.barrelResolutionV) || 0,
+        extractorSchemaV: Number(raw.extractorSchemaV) || 0,
+        extImportsV: Number(raw.extImportsV) || 0,
+        complexityV: Number(raw.complexityV) || 0,
+        graphBuildMode: ['full', 'no-tests', 'tests-only'].includes(raw.graphBuildMode) ? raw.graphBuildMode : 'full',
+        graphBuildScope: typeof raw.graphBuildScope === 'string' ? raw.graphBuildScope : null,
+        graphRevision: typeof raw.graphRevision === 'string' ? raw.graphRevision : null,
+        repositoryFreshnessProbeV: Number(raw.repositoryFreshnessProbeV) || 0,
+        repositoryFreshnessBuilderSchemaV: Number(raw.repositoryFreshnessBuilderSchemaV) || 0,
+        repositoryFreshnessBuilderVersion: typeof raw.repositoryFreshnessBuilderVersion === 'string' ? raw.repositoryFreshnessBuilderVersion : null,
+        repositoryFreshnessProbe: typeof raw.repositoryFreshnessProbe === 'string' ? raw.repositoryFreshnessProbe : null,
+        repositoryFreshnessMode: typeof raw.repositoryFreshnessMode === 'string' ? raw.repositoryFreshnessMode : null,
     }
 }
 
 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) && e.barrelProxy !== true)
+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).
@@ -100,28 +116,97 @@ export function ambiguityNote(query, info) {
 const bestByDegree = (g, list) =>
     list.reduce((best, n) => (degreeOf(g, n.id) > degreeOf(g, best.id) ? n : best), list[0])
 
-// seeds for traversal/search: rank substring/token matches by degree
+const QUERY_STOP = new Set('a an and are around architecture code do does explain find for from how in is me of or project repository show the through to trace what where which with'.split(' '))
+const QUERY_INTENTS = [
+    ['bootstrap', ['bootstrap', 'startup', 'entrypoint', 'entry', 'main', 'root', 'app', 'index']],
+    ['auth', ['auth', 'authentication', 'authorization', 'login', 'session', 'authgate']],
+    ['routing', ['routing', 'router', 'routes', 'route', 'navigation']],
+    ['layout', ['layout', 'layouts', 'shell']],
+    ['api', ['api', 'apis', 'endpoint', 'endpoints', 'client']],
+    ['state', ['state', 'store', 'stores', 'reducer', 'context']],
+]
+const INTENT_BY_TERM = new Map(QUERY_INTENTS.flatMap(([id, terms]) => terms.map((term) => [term, {id, terms}])))
+const wordsOf = (value) => String(value ?? '').replace(/([a-z0-9])([A-Z])/g, '$1 $2').toLowerCase().split(/[^a-z0-9_]+/).filter(Boolean)
+const normPath = (value) => String(value ?? '').replace(/\\/g, '/').replace(/^\.\//, '').toLowerCase()
+
+function queryConcepts(query) {
+    const seen = new Set()
+    const concepts = []
+    for (const raw of wordsOf(query)) {
+        if (raw.length < 2 || QUERY_STOP.has(raw)) continue
+        const intent = INTENT_BY_TERM.get(raw)
+        const id = intent?.id || raw
+        if (seen.has(id)) continue
+        seen.add(id)
+        concepts.push({id, raw, terms: intent ? [raw, ...intent.terms.filter((term) => term !== raw)] : [raw]})
+    }
+    return concepts
+}
+
+function conceptScore(g, node, concept) {
+    const id = normPath(node.id)
+    const label = String(node.label ?? '').toLowerCase()
+    const source = normPath(node.source_file)
+    const stem = (label.split('/').pop() || '').replace(/\.[^.]+$/, '')
+    const words = new Set(wordsOf(`${node.id} ${node.label ?? ''} ${node.source_file ?? ''}`))
+    const segments = new Set(source.split('/').flatMap((part) => wordsOf(part.replace(/\.[^.]+$/, ''))))
+    let match = 0
+    concept.terms.forEach((term, index) => {
+        const primary = index === 0
+        if (label === term || stem === term) match = Math.max(match, primary ? 60 : 42)
+        else if (segments.has(term)) match = Math.max(match, primary ? 48 : 36)
+        else if (words.has(term)) match = Math.max(match, primary ? 36 : 25)
+        else if (term.length >= 4 && (id.includes(term) || label.includes(term))) match = Math.max(match, primary ? 12 : 7)
+    })
+    if (!match) return 0
+    const fileNode = !isSymbol(node.id)
+    const depth = source ? source.split('/').length : 9
+    const entryBoost = concept.id === 'bootstrap' && /^(bootstrap|main|app|index|root)$/.test(stem) ? 10 : 0
+    return match + (fileNode ? 7 : 0) + Math.max(0, 4 - depth) + entryBoost + Math.min(2, degreeOf(g, node.id) / 40)
+}
+
+// Natural-language graph search keeps one strong candidate per concept before filling by aggregate
+// score. This prevents a broad architecture question from spending every seed on one dense API area.
 export function findSeeds(g, query, limit = 8) {
-    const q = String(query ?? '').trim().toLowerCase()
-    if (!q) return []
-    const tokens = q.split(/[^a-z0-9_]+/i).filter((t) => t.length > 1)
-    const scored = []
-    for (const n of g.nodes) {
-        const hay = `${String(n.id)} ${String(n.label ?? '')} ${String(n.source_file ?? '')}`.toLowerCase()
-        let score = 0
-        if (hay.includes(q)) score += 5
-        for (const t of tokens) if (hay.includes(t)) score += 1
-        if (score > 0) scored.push({n, score: score + Math.min(3, degreeOf(g, n.id) / 20)})
+    const concepts = queryConcepts(query)
+    if (!concepts.length || limit <= 0) return []
+    const rows = g.nodes.map((node) => {
+        const scores = concepts.map((concept) => conceptScore(g, node, concept))
+        return {node, scores, total: Math.max(...scores) + scores.reduce((sum, score) => sum + score, 0) / 10}
+    })
+    const chosen = []
+    const used = new Set()
+    for (let index = 0; index < concepts.length && chosen.length < limit; index++) {
+        const best = rows.filter((row) => !used.has(String(row.node.id)) && row.scores[index] > 0)
+            .sort((a, b) => b.scores[index] - a.scores[index] || String(a.node.id).localeCompare(String(b.node.id)))[0]
+        if (best) { chosen.push(best.node); used.add(String(best.node.id)) }
+    }
+    rows.filter((row) => row.total > 0 && !used.has(String(row.node.id)))
+        .sort((a, b) => b.total - a.total || String(a.node.id).localeCompare(String(b.node.id)))
+        .slice(0, Math.max(0, limit - chosen.length))
+        .forEach((row) => chosen.push(row.node))
+    return chosen
+}
+
+export function resolveSeedFiles(g, requested, limit = 12) {
+    const files = Array.isArray(requested) ? requested.slice(0, limit) : []
+    const seeds = []
+    const missing = []
+    for (const raw of files) {
+        const wanted = normPath(raw)
+        const node = g.nodes.find((candidate) => !isSymbol(candidate.id)
+            && (normPath(candidate.id) === wanted || normPath(candidate.source_file) === wanted))
+        if (!node) missing.push(String(raw))
+        else if (!seeds.some((seed) => String(seed.id) === String(node.id))) seeds.push(node)
     }
-    scored.sort((a, b) => b.score - a.score)
-    return scored.slice(0, limit).map((s) => s.n)
+    return {seeds, missing}
 }
 
 // undirected adjacency for reachability (query/shortest path)
 export function undirectedNeighbors(g, id) {
     const seen = new Map()
-    for (const e of g.out.get(id) || []) seen.set(e.id, e.relation)
-    for (const e of g.inn.get(id) || []) if (!seen.has(e.id)) seen.set(e.id, e.relation)
+    for (const e of g.out.get(id) || []) if (e.barrelProxy !== true) seen.set(e.id, e.relation)
+    for (const e of g.inn.get(id) || []) if (e.barrelProxy !== true && !seen.has(e.id)) seen.set(e.id, e.relation)
     return seen
 }
 
@@ -203,164 +288,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'