brainclaw 1.24.0 → 1.25.0

package/dist/cli/register-code-map.js

@@ -3,12 +3,19 @@ export function registerCodeMapCommands(program) {
     // --- code-map ---
     program
         .command('code-map <subcommand> [args...]')
-        .description('Query the per-project Code Map (status, refresh, find, brief)')
+        .description('Query the per-project Code Map (status, refresh, find, brief, impact, export, outline)')
         .option('--json', 'Output as JSON')
         .option('--all', 'For refresh: enumerate all supported files (full refresh)')
         .option('--changed', 'For refresh: only changed files (default)')
         .option('--cascade', 'For refresh/status in a multi-project workspace: cascade across every nested project (each gets its own store; the root store is scoped to files no child owns)')
-        .option('--limit <n>', 'Max results for find/brief', (v) => parseInt(v, 10))
+        .option('--limit <n>', 'Max results for find/brief/impact/outline', (v) => parseInt(v, 10))
+        .option('--depth <n>', 'For impact/export: maximum graph depth (export is hard-capped at 4)', (v) => parseInt(v, 10))
+        .option('--direction <direction>', 'For export: outgoing, incoming, or both')
+        .option('--format <format>', 'For export: json (default) or mermaid')
+        .option('--max-nodes <n>', 'For export: maximum nodes (hard-capped at 100)', (v) => parseInt(v, 10))
+        .option('--max-edges <n>', 'For export: maximum edges (hard-capped at 200)', (v) => parseInt(v, 10))
+        .option('--min-confidence <n>', 'For export: persisted confidence floor (minimum 0.5)', (v) => parseFloat(v))
+        .option('--target-kind <kind>', 'For export: symbol or file (auto-detected by default)')
         .action((subcommand, args, options) => {
         void runCodeMap(subcommand, args, options).catch((err) => {
             console.error(`Error: ${err instanceof Error ? err.message : String(err)}`);

package/dist/commands/code-map.js

@@ -1,12 +1,12 @@
 /**
  * `brainclaw code-map <subcommand>` — CLI surface over the Code Map backend
  * (spec §9). Mirrors plan-resource.ts: a switch over the subcommand delegating
- * to a JsonlBackend (status | refresh | find | brief). The backend owns all
+ * to a JsonlBackend (status | refresh | find | brief | impact | export | outline). The backend owns
  * query logic; this file only adapts it to argv + stdout (text or --json), and
  * every output carries the freshness_badge.
  */
 import { JsonlBackend } from '../core/code-map/backend.js';
-const KNOWN_SUBCOMMANDS = new Set(['status', 'refresh', 'find', 'brief']);
+const KNOWN_SUBCOMMANDS = new Set(['status', 'refresh', 'find', 'brief', 'impact', 'export', 'outline']);
 function backend() {
     return new JsonlBackend();
 }
@@ -57,6 +57,49 @@ export async function runCodeMap(subcommand, args, options = {}) {
         printBrief(result, options);
         return;
     }
+    if (normalized === 'impact') {
+        const target = args.join(' ').trim();
+        if (!target) {
+            console.error('Error: code-map impact requires <symbol-or-path>.');
+            console.error('  Usage: brainclaw code-map impact <symbol-or-path> [--depth 2]');
+            process.exit(1);
+        }
+        const result = await be.impact({ target, depth: options.depth, limit: options.limit, cwd });
+        printImpact(result, options);
+        return;
+    }
+    if (normalized === 'export') {
+        const target = args.join(' ').trim();
+        if (!target) {
+            console.error('Error: code-map export requires <symbol-or-path>.');
+            console.error('  Usage: brainclaw code-map export <symbol-or-path> [--direction both] [--depth 1] [--max-nodes 100] [--max-edges 200]');
+            process.exit(1);
+        }
+        const result = await be.exportGraph({
+            target,
+            targetKind: options.targetKind,
+            direction: options.direction,
+            depth: options.depth,
+            maxNodes: options.maxNodes,
+            maxEdges: options.maxEdges,
+            minConfidence: options.minConfidence,
+            format: options.format,
+            cwd,
+        });
+        printExport(result, options);
+        return;
+    }
+    if (normalized === 'outline') {
+        const target = args.join(' ').trim();
+        if (!target) {
+            console.error('Error: code-map outline requires <file>.');
+            console.error('  Usage: brainclaw code-map outline <file>');
+            process.exit(1);
+        }
+        const result = await be.outline({ path: target, limit: options.limit, cwd });
+        printOutline(result, options);
+        return;
+    }
     console.error(`Error: unknown code-map subcommand "${subcommand}".`);
     console.error(`  Available: ${[...KNOWN_SUBCOMMANDS].join(', ')}`);
     process.exit(1);
@@ -144,4 +187,78 @@ function printBrief(result, options) {
         }
     }
 }
+function printImpact(result, options) {
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    const cause = (row) => row.causes.map((item) => `${item.kind}${item.module ? ` ${item.module}` : ''}${item.source_line ? `:${item.source_line}` : ''}`).join(', ');
+    console.log(`Code Map impact: "${result.target}"`);
+    console.log(`  ${badgeLine(result.freshness_badge)}`);
+    console.log(`  Definition: ${result.definition.entries.length} (${result.definition.match_kind})`);
+    for (const entry of result.definition.entries)
+        console.log(`    ${entry.name} — ${entry.path}`);
+    console.log(`  Direct dependents: ${result.direct_dependents.length}${result.limits.direct_truncated ? '+' : ''}`);
+    for (const dependent of result.direct_dependents)
+        console.log(`    ${dependent.path} — ${cause(dependent)}`);
+    if (result.limits.max_depth > 1) {
+        console.log(`  Transitive dependents: ${result.transitive_dependents.length}${result.limits.transitive_truncated ? '+' : ''}`);
+        for (const dependent of result.transitive_dependents)
+            console.log(`    [depth ${dependent.depth}] ${dependent.path} — ${cause(dependent)}`);
+    }
+    console.log(`  Tests: ${result.risk.counters.resolved_test_files} resolved, ${result.risk.counters.suggested_test_files} naming suggestion(s)`);
+    for (const test of result.tests_for)
+        console.log(`    [${test.relation}, confidence=${test.confidence}] ${test.path} — ${test.reason}`);
+    console.log(`  Risk: ${result.risk.score} (${result.risk.formula}; direct=${result.risk.counters.direct_dependents}, transitive=${result.risk.counters.transitive_dependents})`);
+}
+function printExport(result, options) {
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(`Code Map export: "${result.target}" (${result.target_kind})`);
+    console.log(`  ${badgeLine(result.freshness_badge)}`);
+    console.log(`  Roots: ${result.root_node_ids.length}; nodes=${result.nodes.length}/${result.limits.max_nodes}; edges=${result.edges.length}/${result.limits.max_edges}; depth=${result.limits.max_depth}; direction=${result.limits.direction}; min-confidence=${result.limits.min_confidence}`);
+    const truncation = Object.entries(result.truncated).filter(([, value]) => value).map(([key]) => key);
+    if (truncation.length > 0)
+        console.log(`  Truncated: ${truncation.join(', ')}`);
+    if (result.format === 'mermaid' && result.mermaid) {
+        console.log(result.mermaid);
+        return;
+    }
+    for (const edge of result.edges) {
+        const source = edge.source ? ` @ ${edge.source.path}${edge.source.line === null || edge.source.line === undefined ? '' : `:${edge.source.line}`}` : '';
+        console.log(`  ${edge.from} -[${edge.kind}, confidence=${edge.confidence}${source}]-> ${edge.to}`);
+    }
+}
+function printOutline(result, options) {
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(`Code Map outline: "${result.path}"`);
+    console.log(`  Index:    ${result.index_status}`);
+    console.log(`  ${badgeLine(result.freshness_badge)}`);
+    if (!result.file_indexed) {
+        console.log('  Symbols:  (file not indexed)');
+        return;
+    }
+    console.log(`  Parse:    ${result.parse_status}`);
+    if (result.symbols.length === 0) {
+        console.log('  Symbols:  (none)');
+    }
+    else {
+        for (const symbol of result.symbols) {
+            const subtype = symbol.subtype ? ` ${symbol.subtype}` : '';
+            const span = symbol.span ? `${symbol.span.start_line}:${symbol.span.start_col}` : 'unknown';
+            const exported = symbol.exported ? ' export' : '';
+            console.log(`  [${span}] ${symbol.kind}${subtype} ${symbol.name}${exported} confidence=${symbol.confidence}`);
+        }
+    }
+    if (result.truncated)
+        console.log(`  … ${result.symbol_count - result.symbols.length} more indexed symbol(s)`);
+    if (result.diagnostics.length > 0) {
+        console.log(`  Diagnostics: ${result.diagnostics.length}${result.diagnostics_truncated ? '+' : ''}`);
+    }
+}
 //# sourceMappingURL=code-map.js.map

package/dist/commands/mcp-catalog.js

@@ -409,6 +409,52 @@ export const MCP_READ_TOOLS = [
             required: ['target'],
         },
     },
+    {
+        name: 'bclaw_code_impact',
+        description: 'Explain a symbol or source file\'s local blast radius from existing resolved imports: definition, direct dependents with edge causes, optional bounded transitives, affected test files, low-confidence naming suggestions kept separate, and a count-based risk score. Read-only; never refreshes.',
+        annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'auto' },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                target: { type: 'string', description: 'Symbol name or source-file path whose impact to inspect.' },
+                depth: { type: 'number', description: 'Maximum graph depth. 1 (default) returns direct dependents only; 2+ opts into transitives. Clamped to 4.' },
+                limit: { type: 'number', description: 'Maximum rows in each dependent section and in naming suggestions. Clamped to 100.' },
+            },
+            required: ['target'],
+        },
+    },
+    {
+        name: 'bclaw_code_export',
+        description: 'Export a compact, deterministic, confidence-filtered local Code Map subgraph around one symbol or file. Requires a target; defaults to one hop and hard caps nodes (100), edges (200), and depth (4), so it never exports a whole graph. JSON retains every edge kind, source, and confidence. format="mermaid" adds a projection of the same JSON nodes/edges. Read-only; never refreshes or calls an external service.',
+        annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'auto' },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                target: { type: 'string', description: 'Symbol name or source-file path around which to export a local subgraph.' },
+                targetKind: { type: 'string', enum: ['symbol', 'file'], description: 'Optional explicit target kind; otherwise a source path is detected safely.' },
+                direction: { type: 'string', enum: ['outgoing', 'incoming', 'both'], description: 'Which edge direction(s) to follow. Default: both.' },
+                depth: { type: 'number', description: 'Maximum graph distance from the root(s). Default 1; clamped to 0..4.' },
+                maxNodes: { type: 'number', description: 'Maximum nodes returned. Default 100; hard-capped at 100.' },
+                maxEdges: { type: 'number', description: 'Maximum edges returned. Default 200; hard-capped at 200.' },
+                minConfidence: { type: 'number', description: 'Persisted confidence threshold for nodes and relationships. Default/minimum 0.5.' },
+                format: { type: 'string', enum: ['json', 'mermaid'], description: 'Default json; mermaid adds a projection derived from the same bounded graph.' },
+            },
+            required: ['target'],
+        },
+    },
+    {
+        name: 'bclaw_code_outline',
+        description: 'Return a bounded source-ordered outline for one indexed file: symbol name, kind, subtype, span, exported flag, and persisted confidence. Read-only: it reads the existing file shard only, never parses or refreshes. `index_status` distinguishes a missing index, a file not indexed, and an indexed file with zero symbols.',
+        annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'auto' },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Workspace-relative source file path (for example `src/app/App.tsx`).' },
+                limit: { type: 'number', description: 'Maximum symbols to return; clamped to the hard cap of 200.' },
+            },
+            required: ['path'],
+        },
+    },
 ];
 const MCP_WRITE_TOOLS = [
     {

package/dist/commands/mcp.js

@@ -1089,8 +1089,8 @@ async function _executeMcpToolCallInner(payload) {
         }
         // Code Map tools (spec §9). These delegate to the async JsonlBackend, so
         // they are handled here rather than via the synchronous read-tool path.
-        // status/find/brief are reads; refresh is a write (prompt approval).
-        if (name === 'bclaw_code_status' || name === 'bclaw_code_find' || name === 'bclaw_code_brief' || name === 'bclaw_code_refresh') {
+        // status/find/brief/impact/export/outline are reads; refresh is a write (prompt approval).
+        if (name === 'bclaw_code_status' || name === 'bclaw_code_find' || name === 'bclaw_code_brief' || name === 'bclaw_code_impact' || name === 'bclaw_code_export' || name === 'bclaw_code_outline' || name === 'bclaw_code_refresh') {
             const { JsonlBackend } = await import('../core/code-map/backend.js');
             const be = new JsonlBackend();
             if (name === 'bclaw_code_status') {
@@ -1127,6 +1127,58 @@ async function _executeMcpToolCallInner(payload) {
                     }),
                 };
             }
+            // bclaw_code_export
+            if (name === 'bclaw_code_export') {
+                const target = typeof args.target === 'string' ? args.target : '';
+                if (!target.trim()) {
+                    return { response: createToolErrorResponse('validation_error', 'bclaw_code_export requires a non-empty target.') };
+                }
+                const targetKind = args.targetKind === 'symbol' || args.targetKind === 'file' ? args.targetKind : undefined;
+                const direction = args.direction === 'outgoing' || args.direction === 'incoming' || args.direction === 'both' ? args.direction : undefined;
+                const depth = typeof args.depth === 'number' ? args.depth : undefined;
+                const maxNodes = typeof args.maxNodes === 'number' ? args.maxNodes : undefined;
+                const maxEdges = typeof args.maxEdges === 'number' ? args.maxEdges : undefined;
+                const minConfidence = typeof args.minConfidence === 'number' ? args.minConfidence : undefined;
+                const format = args.format === 'mermaid' ? 'mermaid' : args.format === 'json' ? 'json' : undefined;
+                const result = await be.exportGraph({ target, targetKind, direction, depth, maxNodes, maxEdges, minConfidence, format, cwd });
+                return {
+                    response: toolResponse({
+                        content: [{ type: 'text', text: `Code Map export "${result.target}": ${result.nodes.length} node(s), ${result.edges.length} edge(s), depth=${result.limits.max_depth}, freshness=${result.freshness_badge.status}` }],
+                        structuredContent: { ...result, freshness_badge: result.freshness_badge },
+                    }),
+                };
+            }
+            // bclaw_code_impact
+            if (name === 'bclaw_code_impact') {
+                const target = typeof args.target === 'string' ? args.target : '';
+                if (!target.trim()) {
+                    return { response: createToolErrorResponse('validation_error', 'bclaw_code_impact requires a non-empty target.') };
+                }
+                const depth = typeof args.depth === 'number' ? args.depth : undefined;
+                const limit = typeof args.limit === 'number' ? args.limit : undefined;
+                const result = await be.impact({ target, depth, limit, cwd });
+                return {
+                    response: toolResponse({
+                        content: [{ type: 'text', text: `Code Map impact "${result.target}": ${result.risk.counters.direct_dependents} direct, ${result.risk.counters.transitive_dependents} transitive dependent(s), risk=${result.risk.score}, freshness=${result.freshness_badge.status}` }],
+                        structuredContent: { ...result, freshness_badge: result.freshness_badge },
+                    }),
+                };
+            }
+            // bclaw_code_outline
+            if (name === 'bclaw_code_outline') {
+                const outlinePath = typeof args.path === 'string' ? args.path : '';
+                if (!outlinePath.trim()) {
+                    return { response: createToolErrorResponse('validation_error', 'bclaw_code_outline requires a non-empty path.') };
+                }
+                const limit = typeof args.limit === 'number' ? args.limit : undefined;
+                const result = await be.outline({ path: outlinePath, limit, cwd });
+                return {
+                    response: toolResponse({
+                        content: [{ type: 'text', text: `Code Map outline "${result.path}": ${result.symbols.length}/${result.symbol_count} symbol(s), index=${result.index_status}, freshness=${result.freshness_badge.status}` }],
+                        structuredContent: { ...result, freshness_badge: result.freshness_badge },
+                    }),
+                };
+            }
             // bclaw_code_brief
             const target = typeof args.target === 'string' ? args.target : '';
             if (!target.trim()) {

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

@@ -10,21 +10,70 @@
  */
 import { execFileSync } from 'node:child_process';
 import path from 'node:path';
-import { readManifest, storeExists } from './store.js';
+import { readManifest, readShard, storeExists } from './store.js';
 import { refresh as runRefresh } from './refresh.js';
 import { applyGitHeadDrift, withCoarse } from './freshness.js';
 import { brief as runBrief, find as runFind } from './query.js';
+import { impact as runImpact } from './impact.js';
+import { exportSubgraph } from './export.js';
+import { fileId } from './ids.js';
 import { resolveTraversal, aggregateFind, aggregateBrief } from './aggregate.js';
 import { defaultMemoryReader } from './memory-reader.js';
 import { listNestedProjects, refreshWorkspaceCascade } from './cascade.js';
 import { loadConfig } from '../config.js';
 /** spec §9 caps the brief reading list at 12 files. */
 export const BRIEF_FILE_CAP = 12;
+/**
+ * Agent-facing file outline (P2b). The symbol count is deliberately bounded:
+ * an outline is a navigation aid, not a replacement for opening a generated
+ * source file. `symbol_count` always records the complete indexed count.
+ */
+export const OUTLINE_SYMBOL_CAP = 200;
+/** Diagnostics are useful context, but unbounded provider facts are not. */
+export const OUTLINE_DIAGNOSTIC_CAP = 20;
 function badge(status, details = {}) {
     // pln#601 — stamp the coarse rollup at construction so every backend-built badge
     // (status, missing_index fallbacks, find/brief base) carries it uniformly.
     return withCoarse({ status, details });
 }
+/**
+ * Convert a user path into the POSIX project-relative identity used by shards.
+ * This is pure path arithmetic: outline must not stat, parse, or otherwise touch
+ * the live source file on its read path.
+ */
+function normalizeOutlinePath(requestedPath, projectRoot) {
+    const root = path.resolve(projectRoot);
+    const absolute = path.resolve(root, requestedPath);
+    const relative = path.relative(root, absolute);
+    if (!relative || relative === '.' || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        return null;
+    }
+    return relative.replace(/\\/g, '/');
+}
+function outlineLimit(limit) {
+    if (limit === undefined || !Number.isFinite(limit))
+        return OUTLINE_SYMBOL_CAP;
+    return Math.min(Math.max(Math.floor(limit), 0), OUTLINE_SYMBOL_CAP);
+}
+function compareOutlineSymbols(a, b) {
+    // Symbols normally always have spans. Keep malformed/legacy span-less nodes
+    // deterministic and at the end instead of trusting shard append order.
+    const as = a.span;
+    const bs = b.span;
+    if (as && bs) {
+        return as.start_line - bs.start_line
+            || as.start_col - bs.start_col
+            || as.end_line - bs.end_line
+            || as.end_col - bs.end_col
+            || a.name.localeCompare(b.name)
+            || a.node_id.localeCompare(b.node_id);
+    }
+    if (as)
+        return -1;
+    if (bs)
+        return 1;
+    return a.name.localeCompare(b.name) || a.node_id.localeCompare(b.node_id);
+}
 /**
  * Read the working tree's current commit at `root` (read-path git-HEAD drift,
  * trp_42688015). Returns null on any failure or a non-git project (also detached
@@ -244,6 +293,114 @@ export class JsonlBackend {
             freshness_badge: this.withHeadDrift(base, manifest, input.cwd),
         };
     }
+    /**
+     * Explain a target's resolved blast radius. Unlike brief(), this deliberately
+     * stays store-local: impact only traverses persisted P1c/P1d edges and reports
+     * their concrete causes, with an opt-in bounded transitive walk.
+     */
+    async impact(input) {
+        const ctx = this.queryContext(input);
+        const out = runImpact(input.target, { depth: input.depth, limit: input.limit }, ctx);
+        const manifest = readManifest(input.cwd, input.preferredDirName);
+        const base = badge(out.freshness_badge.status, out.freshness_badge.details);
+        return {
+            ...out,
+            freshness_badge: this.withHeadDrift(base, manifest, input.cwd),
+        };
+    }
+    /**
+     * Export only a caller-selected, hard-bounded local graph. This stays
+     * store-local even at a multi-project root: implicit workspace graph dumps
+     * are intentionally unsupported.
+     */
+    async exportGraph(input) {
+        const ctx = this.queryContext(input);
+        const out = exportSubgraph(input.target, input, ctx);
+        const manifest = readManifest(input.cwd, input.preferredDirName);
+        const base = badge(out.freshness_badge.status, out.freshness_badge.details);
+        return {
+            ...out,
+            freshness_badge: this.withHeadDrift(base, manifest, input.cwd),
+        };
+    }
+    /**
+     * Return an indexed file's symbols in source order. This reads exactly one
+     * manifest and one deterministic shard; it never calls refresh, extractor, or
+     * the lazy live-file validator, so the response is a snapshot of the index.
+     */
+    async outline(input) {
+        const cwd = input.cwd ?? process.cwd();
+        const manifest = readManifest(input.cwd, input.preferredDirName);
+        const root = manifest?.project_root ?? cwd;
+        const normalizedPath = normalizeOutlinePath(input.path.trim(), root) ?? input.path.trim().replace(/\\/g, '/');
+        const missing = () => ({
+            path: normalizedPath,
+            index_status: 'missing_index',
+            file_indexed: false,
+            parse_status: null,
+            symbol_count: 0,
+            symbols: [],
+            truncated: false,
+            diagnostics: [],
+            diagnostics_truncated: false,
+            freshness_badge: badge('missing_index', { hint: 'run refresh' }),
+        });
+        if (!manifest || manifest.freshness.status === 'missing_index')
+            return missing();
+        const freshnessBadge = this.withHeadDrift(badge(manifest.freshness.status, {
+            stale_file_count: manifest.freshness.stale_file_count,
+            partial_reason: manifest.freshness.partial_reason,
+        }), manifest, input.cwd);
+        const safePath = normalizeOutlinePath(input.path.trim(), root);
+        if (!safePath) {
+            return {
+                ...missing(),
+                index_status: 'file_not_indexed',
+                freshness_badge: freshnessBadge,
+            };
+        }
+        const shard = readShard(fileId(manifest.project_id, safePath), input.cwd, input.preferredDirName);
+        if (!shard || shard.path !== safePath) {
+            return {
+                path: safePath,
+                index_status: 'file_not_indexed',
+                file_indexed: false,
+                parse_status: null,
+                symbol_count: 0,
+                symbols: [],
+                truncated: false,
+                diagnostics: [],
+                diagnostics_truncated: false,
+                freshness_badge: freshnessBadge,
+            };
+        }
+        const allSymbols = shard.nodes
+            .filter((node) => node.kind === 'symbol')
+            .map((node) => ({
+            node_id: node.id,
+            name: node.name,
+            kind: node.kind,
+            subtype: node.subtype ?? null,
+            span: node.span ?? null,
+            exported: node.exported,
+            confidence: node.confidence,
+        }))
+            .sort(compareOutlineSymbols);
+        const limit = outlineLimit(input.limit);
+        const diagnostics = shard.diagnostics.slice(0, OUTLINE_DIAGNOSTIC_CAP);
+        return {
+            path: safePath,
+            index_status: 'indexed',
+            file_indexed: true,
+            parse_status: shard.parse_status,
+            symbol_count: allSymbols.length,
+            symbols: allSymbols.slice(0, limit).map(({ node_id: _nodeId, ...symbol }) => symbol),
+            truncated: allSymbols.length > limit,
+            diagnostics,
+            diagnostics_truncated: shard.diagnostics.length > diagnostics.length,
+            freshness_badge: freshnessBadge,
+        };
+    }
     /**
      * Annotate a read badge with git-HEAD drift vs the commit the index was built
      * against (`manifest.git.head`). trp_42688015 — a branch switch (whole-tree move)