brainclaw 1.24.0 → 1.25.0

package/dist/core/code-map/export.js

@@ -0,0 +1,212 @@
+/**
+ * Bounded Code Map subgraph export. Mermaid is rendered from this module's JSON
+ * model; it never takes a second, potentially different graph traversal.
+ */
+import path from 'node:path';
+import { withCoarse } from './freshness.js';
+import { listShards, readManifest } from './store.js';
+/** Absolute traversal and response ceilings: a whole-graph export is impossible. */
+export const CODE_EXPORT_MAX_DEPTH = 4;
+export const CODE_EXPORT_NODE_CAP = 100;
+export const CODE_EXPORT_EDGE_CAP = 200;
+/** Low-confidence extracted data is never included by default or opt-out. */
+export const CODE_EXPORT_MIN_CONFIDENCE = 0.5;
+function clampInteger(value, fallback, min, max) {
+    if (value === undefined || !Number.isFinite(value))
+        return fallback;
+    return Math.min(Math.max(Math.floor(value), min), max);
+}
+function clampConfidence(value) {
+    if (value === undefined || !Number.isFinite(value))
+        return CODE_EXPORT_MIN_CONFIDENCE;
+    return Math.min(Math.max(value, CODE_EXPORT_MIN_CONFIDENCE), 1);
+}
+function normalizePath(value) {
+    return value.replace(/\\/g, '/');
+}
+function normalizeDirection(value) {
+    return value === 'outgoing' || value === 'incoming' || value === 'both' ? value : 'both';
+}
+function normalizeFormat(value) {
+    return value === 'mermaid' || value === 'json' ? value : 'json';
+}
+function normalizeTargetKind(value, target) {
+    return value === 'symbol' || value === 'file' ? value : inferTargetKind(target);
+}
+function inferTargetKind(target) {
+    return /[\\/]/.test(target)
+        || /\.(?:[cm]?[jt]sx?|py|php|java|go|rs|cs|rb|c|cc|cpp|cxx|h|hpp)$/i.test(target)
+        ? 'file'
+        : 'symbol';
+}
+/** No selector may address the project root itself or escape it. */
+function normalizeFileTarget(target, projectRoot) {
+    const root = path.resolve(projectRoot);
+    const absolute = path.resolve(root, target);
+    const relative = path.relative(root, absolute);
+    if (!relative || relative === '.' || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+        return null;
+    return normalizePath(relative);
+}
+function compareNodes(a, b) {
+    const as = a.span;
+    const bs = b.span;
+    return a.path.localeCompare(b.path)
+        || (as?.start_line ?? -1) - (bs?.start_line ?? -1)
+        || (as?.start_col ?? -1) - (bs?.start_col ?? -1)
+        || a.kind.localeCompare(b.kind)
+        || a.name.localeCompare(b.name)
+        || a.id.localeCompare(b.id);
+}
+function compareEdges(a, b) {
+    return a.from.localeCompare(b.from)
+        || a.to.localeCompare(b.to)
+        || a.kind.localeCompare(b.kind)
+        || (a.source?.path ?? '').localeCompare(b.source?.path ?? '')
+        || (a.source?.line ?? -1) - (b.source?.line ?? -1)
+        || a.id.localeCompare(b.id);
+}
+function graphNode(node) {
+    return { id: node.id, kind: node.kind, subtype: node.subtype ?? null, lang: node.lang, name: node.name, path: node.path,
+        span: node.span ?? null, exported: node.exported, confidence: node.confidence };
+}
+function graphEdge(edge) {
+    return { id: edge.id, from: edge.from, to: edge.to, kind: edge.kind, confidence: edge.confidence, source: edge.source ?? null };
+}
+function matchesRoot(node, target, targetKind, normalizedPath) {
+    return targetKind === 'file'
+        ? node.kind === 'file' && normalizedPath !== null && normalizePath(node.path) === normalizedPath
+        : node.kind === 'symbol' && node.name === target;
+}
+function usableEdge(edge, nodes, minConfidence) {
+    return edge.confidence >= minConfidence
+        && (nodes.get(edge.from)?.confidence ?? -Infinity) >= minConfidence
+        && (nodes.get(edge.to)?.confidence ?? -Infinity) >= minConfidence;
+}
+function touches(edge, nodeId, direction) {
+    return ((direction === 'outgoing' || direction === 'both') && edge.from === nodeId)
+        || ((direction === 'incoming' || direction === 'both') && edge.to === nodeId);
+}
+function neighbor(edge, nodeId) {
+    return edge.from === nodeId ? edge.to : edge.from;
+}
+function emptyOutput(target, targetKind, limits, freshness, format) {
+    const graph = {
+        target, target_kind: targetKind, root_node_ids: [], nodes: [], edges: [], limits,
+        truncated: { roots: false, nodes: false, edges: false, depth: false }, freshness_badge: freshness,
+    };
+    return format === 'mermaid' ? { ...graph, format, mermaid: toMermaid(graph) } : { ...graph, format };
+}
+/**
+ * Select a deterministic, confidence-filtered neighborhood from persisted shards.
+ * No refresh, parse, inference, service call, or unbounded response occurs here.
+ */
+export function exportSubgraph(targetInput, options, ctx) {
+    const target = targetInput.trim();
+    const targetKind = normalizeTargetKind(options?.targetKind, target);
+    const format = normalizeFormat(options?.format);
+    const limits = {
+        direction: normalizeDirection(options?.direction),
+        max_depth: clampInteger(options?.depth, 1, 0, CODE_EXPORT_MAX_DEPTH),
+        max_nodes: clampInteger(options?.maxNodes, CODE_EXPORT_NODE_CAP, 1, CODE_EXPORT_NODE_CAP),
+        max_edges: clampInteger(options?.maxEdges, CODE_EXPORT_EDGE_CAP, 0, CODE_EXPORT_EDGE_CAP),
+        min_confidence: clampConfidence(options?.minConfidence),
+    };
+    const manifest = readManifest(ctx.cwd, ctx.preferredDirName);
+    const missing = withCoarse({ status: 'missing_index', details: { hint: 'run refresh' } });
+    if (!manifest || manifest.freshness.status === 'missing_index' || !target)
+        return emptyOutput(target, targetKind, limits, missing, format);
+    const targetPath = targetKind === 'file' ? normalizeFileTarget(target, manifest.project_root) : null;
+    if (targetKind === 'file' && !targetPath) {
+        return emptyOutput(target, targetKind, limits, withCoarse({
+            status: manifest.freshness.status, details: { invalid_target: 'file path must be inside the indexed project' },
+        }), format);
+    }
+    const allNodes = new Map();
+    const allEdges = new Map();
+    for (const shard of listShards(ctx.cwd, ctx.preferredDirName).sort((a, b) => a.path.localeCompare(b.path) || a.file_id.localeCompare(b.file_id))) {
+        for (const node of shard.nodes)
+            if (!allNodes.has(node.id))
+                allNodes.set(node.id, node);
+        for (const edge of shard.edges)
+            if (!allEdges.has(edge.id))
+                allEdges.set(edge.id, edge);
+    }
+    const nodes = new Map([...allNodes.entries()].filter(([, node]) => node.confidence >= limits.min_confidence));
+    const edges = [...allEdges.values()].filter((edge) => usableEdge(edge, nodes, limits.min_confidence)).sort(compareEdges);
+    const roots = [...nodes.values()].filter((node) => matchesRoot(node, target, targetKind, targetPath)).sort(compareNodes);
+    const selected = new Set();
+    const rootNodeIds = [];
+    let rootsTruncated = false;
+    for (const root of roots) {
+        if (selected.size >= limits.max_nodes) {
+            rootsTruncated = true;
+            break;
+        }
+        selected.add(root.id);
+        rootNodeIds.push(root.id);
+    }
+    const selectedEdges = new Map();
+    const visited = new Set(rootNodeIds);
+    let nodesTruncated = false;
+    let edgesTruncated = false;
+    let depthTruncated = false;
+    let frontier = [...rootNodeIds];
+    for (let currentDepth = 0; frontier.length > 0; currentDepth++) {
+        const next = new Set();
+        frontier.sort((a, b) => compareNodes(nodes.get(a), nodes.get(b)));
+        for (const nodeId of frontier) {
+            const incident = edges.filter((edge) => touches(edge, nodeId, limits.direction));
+            if (currentDepth >= limits.max_depth) {
+                if (incident.some((edge) => !selectedEdges.has(edge.id)))
+                    depthTruncated = true;
+                continue;
+            }
+            for (const edge of incident) {
+                const adjacent = neighbor(edge, nodeId);
+                if (!selected.has(adjacent) && selected.size >= limits.max_nodes) {
+                    nodesTruncated = true;
+                    continue;
+                }
+                if (selectedEdges.size >= limits.max_edges && !selectedEdges.has(edge.id)) {
+                    edgesTruncated = true;
+                    continue;
+                }
+                selected.add(adjacent);
+                selectedEdges.set(edge.id, edge);
+                if (!visited.has(adjacent)) {
+                    visited.add(adjacent);
+                    next.add(adjacent);
+                }
+            }
+        }
+        frontier = [...next];
+    }
+    const graph = {
+        target, target_kind: targetKind, root_node_ids: rootNodeIds,
+        nodes: [...selected].map((id) => nodes.get(id)).filter((node) => node !== undefined).sort(compareNodes).map(graphNode),
+        edges: [...selectedEdges.values()].sort(compareEdges).map(graphEdge),
+        limits, truncated: { roots: rootsTruncated, nodes: nodesTruncated, edges: edgesTruncated, depth: depthTruncated },
+        freshness_badge: withCoarse({ status: manifest.freshness.status,
+            details: { stale_file_count: manifest.freshness.stale_file_count, partial_reason: manifest.freshness.partial_reason } }),
+    };
+    return format === 'mermaid' ? { ...graph, format, mermaid: toMermaid(graph) } : { ...graph, format };
+}
+function mermaidLabel(node) {
+    return JSON.stringify(`${node.name} (${node.kind})`.replace(/[\r\n]/g, ' '));
+}
+/** Deterministic textual projection of a graph already selected by exportSubgraph. */
+export function toMermaid(graph) {
+    const ids = new Map(graph.nodes.map((node, index) => [node.id, `n${index}`]));
+    const lines = ['flowchart TD'];
+    for (const node of graph.nodes)
+        lines.push(`  ${ids.get(node.id)}[${mermaidLabel(node)}]`);
+    for (const edge of graph.edges) {
+        const from = ids.get(edge.from);
+        const to = ids.get(edge.to);
+        if (from && to)
+            lines.push(`  ${from} -->|${edge.kind} · ${edge.confidence}| ${to}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=export.js.map

package/dist/core/code-map/freshness.js

@@ -8,7 +8,7 @@
  *    extractor_config + the active language set + (P1a) the registry's
  *    `configHashInputs()` (provider versions + every query-asset hash). Changing
  *    ignore rules, size caps, supported extensions, query budget, active langs, a
- *    provider version, OR a tags/imports `.scm` => stale_extractor.
+ *    provider version, query assets, OR local resolver config => stale_extractor.
  *    NOTE: grammar/engine hashes are deliberately NOT folded in (spec §6.2):
  *    stale_grammar (changed parse binary) is kept separable from stale_extractor.
  *  - `shardFreshnessStatus` — classify a stored shard against the current
@@ -69,11 +69,12 @@ function stableStringify(value) {
  * (dec#109 P0#3). Optional + omitted-vs-undefined hash the same so legacy callers
  * (config-only) keep a stable hash for that input combination.
  */
-export function computeExtractorConfigHash(config, activeLanguages, registryInputs) {
+export function computeExtractorConfigHash(config, activeLanguages, registryInputs, resolverConfigFingerprint) {
     const payload = {
         extractor_config: config,
         active_languages: [...activeLanguages].sort(),
         registry: registryInputs ?? null,
+        resolver_config: resolverConfigFingerprint ?? null,
     };
     return `sha256:${crypto.createHash('sha256').update(stableStringify(payload)).digest('hex')}`;
 }

package/dist/core/code-map/impact.js

@@ -0,0 +1,377 @@
+/**
+ * Bounded, explainable Code Map impact analysis.
+ *
+ * This module deliberately traverses only the persisted P1c resolution graph
+ * through P1d's reverse ResolutionIndex. It neither reparses files nor infers
+ * import edges from a naming convention. Naming is limited to a clearly marked,
+ * low-confidence test suggestion after resolved test imports have been reported.
+ */
+import path from 'node:path';
+import { fileId } from './ids.js';
+import { readManifest, readResolutionIndex, readShard, readSymbolsIndex, } from './store.js';
+import { deriveBadge, isTestPath, makeLazyChecker, newAccumulator, validateStoreEntry, } from './query.js';
+/** Direct results and each optional transitive layer are independently bounded. */
+export const IMPACT_DEPENDENT_CAP = 100;
+/** A depth of one is direct only; transitives require an explicit depth of two or more. */
+export const IMPACT_MAX_DEPTH = 4;
+export const IMPACT_NAMING_SUGGESTION_CONFIDENCE = 0.25;
+function normalizeIdentifier(value) {
+    return value.toLowerCase().replace(/[^a-z0-9]+/g, '');
+}
+function looksLikePathTarget(target) {
+    return /[\\/]/.test(target) || /\.(?:[cm]?[jt]sx?|py|php|java|go|rs|cs|rb|c|cc|cpp|cxx|h|hpp)$/i.test(target);
+}
+function normalizePathTarget(target, projectRoot) {
+    const root = path.resolve(projectRoot);
+    const absolute = path.resolve(root, target);
+    const relative = path.relative(root, absolute);
+    if (!relative || relative === '.' || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        return null;
+    }
+    return relative.replace(/\\/g, '/');
+}
+function entriesForToken(index, target) {
+    const normalizedTarget = normalizeIdentifier(target);
+    if (!normalizedTarget)
+        return [];
+    const seen = new Set();
+    const candidates = [];
+    for (const entries of Object.values(index.entries)) {
+        for (const entry of entries) {
+            if (seen.has(entry.node_id))
+                continue;
+            const normalizedName = normalizeIdentifier(entry.name);
+            if (normalizedName === normalizedTarget || normalizedName.includes(normalizedTarget)) {
+                seen.add(entry.node_id);
+                candidates.push(entry);
+            }
+        }
+    }
+    const exact = candidates.filter((entry) => normalizeIdentifier(entry.name) === normalizedTarget);
+    return (exact.length > 0 ? exact : candidates).sort((a, b) => a.path.localeCompare(b.path) || a.name.localeCompare(b.name) || a.node_id.localeCompare(b.node_id));
+}
+function entriesForPath(index, target) {
+    const normalizedTarget = target.replace(/\\/g, '/');
+    const seen = new Set();
+    const entries = [];
+    for (const bucket of Object.values(index.entries)) {
+        for (const entry of bucket) {
+            const candidatePath = entry.path.replace(/\\/g, '/');
+            if ((candidatePath === normalizedTarget || candidatePath.endsWith(`/${normalizedTarget}`)) && !seen.has(entry.node_id)) {
+                seen.add(entry.node_id);
+                entries.push(entry);
+            }
+        }
+    }
+    return entries.sort((a, b) => a.path.localeCompare(b.path) || a.name.localeCompare(b.name));
+}
+function asDefinition(entry) {
+    return {
+        node_id: entry.node_id,
+        name: entry.name,
+        kind: 'symbol',
+        subtype: entry.subtype ?? null,
+        path: entry.path,
+        file_id: entry.file_id,
+        span: null,
+        confidence: entry.score_hint,
+    };
+}
+function fallbackReasons(entry, kind) {
+    const indexed = entry.reasons.filter((reason) => reason.kind === kind);
+    if (indexed.length > 0)
+        return indexed;
+    // Existing P1d indexes (written before P3) still have a compact aggregate.
+    // Preserve their factual resolution evidence rather than manufacturing a guess.
+    return [{
+            kind,
+            ...(entry.module ? { module: entry.module } : {}),
+            imported: entry.imported,
+            ...(typeof entry.confidence === 'number' ? { confidence: entry.confidence } : {}),
+        }];
+}
+function causeKey(cause) {
+    return [
+        cause.kind,
+        cause.module ?? '',
+        cause.imported.join('\u0000'),
+        String(cause.confidence ?? ''),
+        String(cause.source_line ?? ''),
+        cause.target.kind,
+        cause.target.path,
+        cause.target.node_id ?? '',
+    ].join('\u0001');
+}
+function compareCause(a, b) {
+    return a.kind.localeCompare(b.kind)
+        || a.target.path.localeCompare(b.target.path)
+        || (a.target.node_id ?? '').localeCompare(b.target.node_id ?? '')
+        || (a.module ?? '').localeCompare(b.module ?? '')
+        || (a.source_line ?? -1) - (b.source_line ?? -1)
+        || a.imported.join('\u0000').localeCompare(b.imported.join('\u0000'))
+        || (a.confidence ?? -1) - (b.confidence ?? -1);
+}
+function addRelation(rows, entry, depth, target, kind) {
+    const current = rows.get(entry.path) ?? {
+        path: entry.path,
+        file_id: entry.file_id,
+        depth,
+        causes: [],
+        causeKeys: new Set(),
+    };
+    current.depth = Math.min(current.depth, depth);
+    for (const reason of fallbackReasons(entry, kind)) {
+        const cause = {
+            kind: reason.kind,
+            ...(reason.module ? { module: reason.module } : {}),
+            imported: [...reason.imported],
+            ...(typeof reason.confidence === 'number' ? { confidence: reason.confidence } : {}),
+            ...(reason.source_line !== undefined ? { source_line: reason.source_line } : {}),
+            target,
+        };
+        const key = causeKey(cause);
+        if (!current.causeKeys.has(key)) {
+            current.causeKeys.add(key);
+            current.causes.push(cause);
+        }
+    }
+    current.causes.sort(compareCause);
+    rows.set(entry.path, current);
+}
+function publicRelation(row) {
+    return {
+        path: row.path,
+        file_id: row.file_id,
+        depth: row.depth,
+        causes: row.causes,
+    };
+}
+function relationConfidence(row) {
+    return row.causes.reduce((best, cause) => Math.max(best, cause.confidence ?? 0), 0);
+}
+function testStem(filePath) {
+    const base = filePath.replace(/\\/g, '/').split('/').pop() ?? filePath;
+    return normalizeIdentifier(base
+        .replace(/\.[^.]+$/, '')
+        .replace(/(?:[._-](?:test|spec)|(?:test|spec)s?)$/i, '')
+        .replace(/^(?:test|spec)[_-]/i, ''));
+}
+function clampDepth(depth) {
+    if (depth === undefined || !Number.isFinite(depth))
+        return 1;
+    return Math.min(Math.max(Math.floor(depth), 1), IMPACT_MAX_DEPTH);
+}
+function clampLimit(limit) {
+    if (limit === undefined || !Number.isFinite(limit))
+        return IMPACT_DEPENDENT_CAP;
+    return Math.min(Math.max(Math.floor(limit), 0), IMPACT_DEPENDENT_CAP);
+}
+/**
+ * Read a bounded blast radius from existing resolved imports. A direct relation
+ * is distance 1. Supplying depth=2 (or more) opts into transitively importing
+ * files; depth is clamped to {@link IMPACT_MAX_DEPTH}.
+ */
+export function impact(target, options, ctx) {
+    const symbolsIndex = readSymbolsIndex(ctx.cwd, ctx.preferredDirName);
+    const manifest = readManifest(ctx.cwd, ctx.preferredDirName);
+    const maxDepth = clampDepth(options?.depth);
+    const limit = clampLimit(options?.limit);
+    const checker = makeLazyChecker();
+    const acc = newAccumulator();
+    const empty = (freshness) => ({
+        target,
+        definition: { match_kind: 'none', entries: [] },
+        direct_dependents: [],
+        transitive_dependents: [],
+        tests_for: [],
+        risk: {
+            score: 0,
+            formula: 'direct_dependents + transitive_dependents',
+            counters: {
+                definitions: 0,
+                direct_dependents: 0,
+                transitive_dependents: 0,
+                resolved_test_files: 0,
+                suggested_test_files: 0,
+                max_depth_returned: 0,
+            },
+        },
+        limits: {
+            max_depth: maxDepth,
+            max_dependents_per_section: limit,
+            direct_truncated: false,
+            transitive_truncated: false,
+        },
+        freshness_badge: freshness,
+    });
+    if (!symbolsIndex || !manifest) {
+        return empty({ status: 'missing_index', coarse: 'missing', details: { hint: 'run refresh' } });
+    }
+    let matchKind = 'none';
+    let rawDefinitions = [];
+    if (looksLikePathTarget(target)) {
+        const safePath = normalizePathTarget(target, manifest.project_root);
+        if (safePath) {
+            const symbols = entriesForPath(symbolsIndex, safePath);
+            rawDefinitions = symbols.map(asDefinition);
+            if (rawDefinitions.length > 0) {
+                matchKind = 'path';
+            }
+            else {
+                const shard = readShard(fileId(manifest.project_id, safePath), ctx.cwd, ctx.preferredDirName);
+                const fileNode = shard?.nodes.find((node) => node.kind === 'file');
+                if (shard && fileNode) {
+                    rawDefinitions = [{
+                            node_id: fileNode.id,
+                            name: fileNode.name,
+                            kind: 'file',
+                            subtype: null,
+                            path: shard.path,
+                            file_id: shard.file_id,
+                            span: null,
+                            confidence: fileNode.confidence,
+                        }];
+                    matchKind = 'path';
+                }
+            }
+        }
+    }
+    else {
+        const symbols = entriesForToken(symbolsIndex, target);
+        rawDefinitions = symbols.map(asDefinition);
+        if (rawDefinitions.length > 0) {
+            matchKind = rawDefinitions.every((entry) => normalizeIdentifier(entry.name) === normalizeIdentifier(target)) ? 'exact' : 'fuzzy';
+        }
+    }
+    const definitions = rawDefinitions
+        .filter((entry) => validateStoreEntry({ path: entry.path, file_id: entry.file_id }, checker, acc, ctx.cwd, ctx.preferredDirName))
+        .map((entry) => {
+        // SymbolIndexEntry intentionally stores only a ranking hint. The shard is
+        // the authoritative persisted source for the definition span/confidence.
+        const node = readShard(entry.file_id, ctx.cwd, ctx.preferredDirName)?.nodes.find((candidate) => candidate.id === entry.node_id);
+        return node ? { ...entry, span: node.span ?? null, confidence: node.confidence } : entry;
+    });
+    const definitionByNodeId = new Map(definitions.filter((entry) => entry.kind === 'symbol').map((entry) => [entry.node_id, entry]));
+    const definitionPaths = new Set(definitions.map((entry) => entry.path));
+    const resolution = readResolutionIndex(ctx.cwd, ctx.preferredDirName);
+    const directRows = new Map();
+    if (resolution) {
+        for (const definition of definitionByNodeId.values()) {
+            for (const dependent of resolution.dependents_by_symbol[definition.node_id] ?? []) {
+                addRelation(directRows, dependent, 1, {
+                    kind: 'symbol', path: definition.path, node_id: definition.node_id, name: definition.name,
+                }, 'imports_symbol');
+            }
+        }
+        for (const definitionPath of definitionPaths) {
+            for (const dependent of resolution.dependents_by_file[definitionPath] ?? []) {
+                addRelation(directRows, dependent, 1, { kind: 'file', path: definitionPath }, 'resolves_to');
+            }
+        }
+    }
+    const sortedDirect = [...directRows.values()].sort((a, b) => a.path.localeCompare(b.path));
+    const directCandidates = sortedDirect.slice(0, limit);
+    const direct = directCandidates
+        .filter((row) => validateStoreEntry(row, checker, acc, ctx.cwd, ctx.preferredDirName))
+        .map(publicRelation);
+    const transitive = [];
+    let transitiveTruncated = false;
+    if (resolution && maxDepth > 1 && limit > 0) {
+        const visited = new Set([...definitionPaths, ...direct.map((row) => row.path)]);
+        const queue = direct.map((row) => ({ path: row.path, depth: 1 }));
+        for (let offset = 0; offset < queue.length; offset++) {
+            const current = queue[offset];
+            if (current.depth >= maxDepth)
+                continue;
+            for (const dependent of resolution.dependents_by_file[current.path] ?? []) {
+                if (visited.has(dependent.path))
+                    continue;
+                visited.add(dependent.path);
+                if (transitive.length >= limit) {
+                    transitiveTruncated = true;
+                    continue;
+                }
+                const rowMap = new Map();
+                addRelation(rowMap, dependent, current.depth + 1, { kind: 'file', path: current.path }, 'resolves_to');
+                const row = rowMap.get(dependent.path);
+                if (!validateStoreEntry(row, checker, acc, ctx.cwd, ctx.preferredDirName))
+                    continue;
+                const output = publicRelation(row);
+                transitive.push(output);
+                queue.push({ path: output.path, depth: output.depth });
+            }
+        }
+    }
+    transitive.sort((a, b) => a.depth - b.depth || a.path.localeCompare(b.path));
+    const confirmedTests = [...direct, ...transitive]
+        .filter((row) => isTestPath(row.path))
+        .map((row) => ({
+        path: row.path,
+        file_id: row.file_id,
+        relation: 'resolved_import',
+        confidence: relationConfidence(row),
+        depth: row.depth,
+        causes: row.causes,
+        reason: `resolved import at graph depth ${row.depth}`,
+    }));
+    const confirmedPaths = new Set(confirmedTests.map((test) => test.path));
+    const targetNames = new Set([
+        ...definitions.map((definition) => normalizeIdentifier(definition.name)),
+        ...definitions.map((definition) => testStem(definition.path)),
+    ].filter(Boolean));
+    const suggestions = new Map();
+    if (targetNames.size > 0) {
+        const seenFiles = new Map();
+        for (const entries of Object.values(symbolsIndex.entries)) {
+            for (const entry of entries)
+                if (!seenFiles.has(entry.path))
+                    seenFiles.set(entry.path, entry.file_id);
+        }
+        for (const [testPath, testFileId] of seenFiles) {
+            if (suggestions.size >= limit || confirmedPaths.has(testPath) || !isTestPath(testPath))
+                continue;
+            if (!targetNames.has(testStem(testPath)))
+                continue;
+            if (!validateStoreEntry({ path: testPath, file_id: testFileId }, checker, acc, ctx.cwd, ctx.preferredDirName))
+                continue;
+            suggestions.set(testPath, {
+                path: testPath,
+                file_id: testFileId,
+                relation: 'naming_convention_suggestion',
+                confidence: IMPACT_NAMING_SUGGESTION_CONFIDENCE,
+                reason: 'filename convention matches the target; no resolved import proves this relationship',
+            });
+        }
+    }
+    const testsFor = [...confirmedTests, ...suggestions.values()].sort((a, b) => a.relation.localeCompare(b.relation) || a.path.localeCompare(b.path));
+    const maxDepthReturned = Math.max(0, ...direct.map((row) => row.depth), ...transitive.map((row) => row.depth));
+    const risk = {
+        score: direct.length + transitive.length,
+        formula: 'direct_dependents + transitive_dependents',
+        counters: {
+            definitions: definitions.length,
+            direct_dependents: direct.length,
+            transitive_dependents: transitive.length,
+            resolved_test_files: confirmedTests.length,
+            suggested_test_files: suggestions.size,
+            max_depth_returned: maxDepthReturned,
+        },
+    };
+    const freshnessBadge = deriveBadge(manifest.freshness.status, acc, checker.exhausted, definitions.length > 0 || direct.length > 0 || transitive.length > 0, definitions.length === 0);
+    return {
+        target,
+        definition: { match_kind: definitions.length > 0 ? matchKind : 'none', entries: definitions },
+        direct_dependents: direct,
+        transitive_dependents: transitive,
+        tests_for: testsFor,
+        risk,
+        limits: {
+            max_depth: maxDepth,
+            max_dependents_per_section: limit,
+            direct_truncated: sortedDirect.length > limit,
+            transitive_truncated: transitiveTruncated,
+        },
+        freshness_badge: freshnessBadge,
+    };
+}
+//# sourceMappingURL=impact.js.map

package/dist/core/code-map/indexes.js

@@ -130,7 +130,7 @@ export function buildResolutionIndex(projectId, shards) {
     // target key -> (importer path -> merged entry)
     const byFile = new Map();
     const bySymbol = new Map();
-    const addDependent = (bucket, targetKey, importerPath, importerFileId, module, imported, confidence) => {
+    const addDependent = (bucket, targetKey, importerPath, importerFileId, module, imported, confidence, kind, sourceLine) => {
         const perImporter = bucket.get(targetKey) ?? new Map();
         const prev = perImporter.get(importerPath);
         if (!prev) {
@@ -140,6 +140,7 @@ export function buildResolutionIndex(projectId, shards) {
                 module,
                 imported: [...new Set(imported)].sort(),
                 confidence,
+                reasons: [],
             });
         }
         else {
@@ -154,6 +155,29 @@ export function buildResolutionIndex(projectId, shards) {
                 prev.confidence = typeof prev.confidence === 'number' ? Math.max(prev.confidence, confidence) : confidence;
             }
         }
+        const current = perImporter.get(importerPath);
+        const reason = {
+            kind,
+            ...(module ? { module } : {}),
+            imported: [...new Set(imported)].sort(),
+            ...(typeof confidence === 'number' ? { confidence } : {}),
+            ...(sourceLine !== undefined ? { source_line: sourceLine } : {}),
+        };
+        // Multiple module nodes can resolve to one target from one importer. Keep
+        // every concrete cause, deduping an identical extractor edge defensively.
+        if (!current.reasons.some((existing) => existing.kind === reason.kind
+            && existing.module === reason.module
+            && existing.confidence === reason.confidence
+            && existing.source_line === reason.source_line
+            && existing.imported.length === reason.imported.length
+            && existing.imported.every((name, index) => name === reason.imported[index]))) {
+            current.reasons.push(reason);
+            current.reasons.sort((a, b) => a.kind.localeCompare(b.kind)
+                || (a.module ?? '').localeCompare(b.module ?? '')
+                || (a.source_line ?? -1) - (b.source_line ?? -1)
+                || a.imported.join('\0').localeCompare(b.imported.join('\0'))
+                || (a.confidence ?? -1) - (b.confidence ?? -1));
+        }
         bucket.set(targetKey, perImporter);
     };
     const ordered = [...shards].sort((a, b) => a.path.localeCompare(b.path));
@@ -172,10 +196,10 @@ export function buildResolutionIndex(projectId, shards) {
                 const targetPath = fileNodeIdToPath.get(e.to);
                 if (!targetPath)
                     continue; // target id not an indexed file (defensive)
-                addDependent(byFile, targetPath, shard.path, shard.file_id, mod?.name, mod?.imported ?? [], e.confidence);
+                addDependent(byFile, targetPath, shard.path, shard.file_id, mod?.name, mod?.imported ?? [], e.confidence, 'resolves_to', e.source?.line);
             }
             else {
-                addDependent(bySymbol, e.to, shard.path, shard.file_id, mod?.name, mod?.imported ?? [], e.confidence);
+                addDependent(bySymbol, e.to, shard.path, shard.file_id, mod?.name, mod?.imported ?? [], e.confidence, 'imports_symbol', e.source?.line);
             }
         }
     }