feat: add codebase map context packs

README.md

@@ -57,18 +57,19 @@ claude mcp add -s user -t stdio codebase-intelligence -- npx -y codebase-intelli
 
 ## Features
 
-- **20 CLI commands** for architecture analysis, dependency impact, duplicate families, Highways convergence, improvement opportunities, dead code detection, search, CI rules, and agent setup
+- **21 CLI commands** for architecture analysis, dependency impact, duplicate families, focused map/context packs, Highways convergence, improvement opportunities, dead code detection, search, CI rules, and agent setup
 - **Machine-readable JSON output** (`--json`) for automation and CI pipelines
 - **Auto-cached index** in `.codebase-intelligence/` for fast repeat queries
 - **Cache migration facts** in JSON (`cacheDir`, `legacyCacheDir`, `migrated`, `gitignoreUpdated`, `warnings[]`)
 - **11 architectural metrics** — PageRank, betweenness, coupling, cohesion, tension, churn, complexity, blast radius, dead exports, test coverage, escape velocity
 - **Symbol-level analysis** — callers/callees, symbol importance, impact blast radius
 - **BM25 search** — ranked keyword search across files, symbols, and type/shape facts
 - **Process tracing** — detect entry points and execution flows through the call graph
+- **Codebase maps + context packs** — focused file/symbol/test graph with deterministic evidence IDs and token-bounded context for agents
 - **Highways analysis** — find repeated routes that bypass canonical dataflow paths and synthesize safe proposed highways
 - **Community detection** — Louvain clustering for natural file groupings
 - **Agent adoption** — `init` writes per-agent instruction files + installs a skill so AI agents query CI before grep/read
-- **MCP parity (secondary)** — same analysis and rules gate available as 19 MCP tools, 2 prompts, and 3 resources
+- **MCP parity (secondary)** — same analysis and rules gate available as 22 MCP tools, 2 prompts, and 3 resources
 
 ## Installation
 
@@ -111,6 +112,7 @@ codebase-intelligence <command> <path> [options]
 | `impact` | Symbol-level blast radius |
 | `rename` | Reference discovery for rename planning |
 | `processes` | Entry-point execution flow tracing |
+| `map` | Focused codebase graph + token-bounded context pack |
 | `highways` | Repeated route convergence, canonical path opportunities, and synthesis proposals |
 | `clusters` | Community-detected file clusters |
 | `check` | Rules-engine gate for CI, including opt-in dead-code and dependency gates |
@@ -129,6 +131,9 @@ codebase-intelligence <command> <path> [options]
 | `--min-tokens <n>` | Minimum duplicate token size for `duplicates` |
 | `--skip-local` | Ignore duplicate families confined to one file |
 | `--trace <id>` | Return token evidence for one duplicate family |
+| `--focus <name>` | Focus `map` on one symbol, file, or scope |
+| `--context-budget <n>` | Bound `map` context pack size |
+| `--format <fmt>` | Export `map` as `markdown`, `json`, `dot`, or `graphml`; export `check` as `text`, `json`, or `sarif` |
 | `--operation <verb>` | Focus `highways` on one operation verb |
 | `--shape <name>` | Focus `highways` on one type/DTO shape |
 

docs/architecture.md

@@ -25,7 +25,7 @@ Core (shared computation)
   |     typed descriptors, input schemas, CLI/MCP adapters, result wrappers, text formatters
   v
 MCP (stdio)                    CLI (terminal/CI)
-  | 19 tools, 2 prompts,        | 20 commands with text + JSON
+  | 22 tools, 2 prompts,        | 21 commands with text + JSON
   | 3 resources for LLMs        | output for humans and CI
 ```
 
@@ -47,8 +47,9 @@ src/
   duplication/index.ts <- Duplicate family detection + trace evidence
   config/index.ts      <- Config discovery + zod validation
   rules/index.ts       <- Rules engine + registry (check command + MCP check tool)
+  map/index.ts         <- Focused codebase maps + token-bounded context packs
   highways/index.ts    <- Repeated route convergence + bypass/cowpath/synthesis evidence
-  mcp/index.ts         <- 19 MCP tools for LLM integration
+  mcp/index.ts         <- 22 MCP tools for LLM integration
   mcp/hints.ts         <- Operation-keyed next-step hints for MCP tool responses
   impact/index.ts      <- Symbol-level impact analysis + rename planning
   search/index.ts      <- BM25 search engine
@@ -83,7 +84,7 @@ analyzeGraph(builtGraph, parsedFiles)
      }
 
 startMcpServer(codebaseGraph)
-  -> stdio MCP server with 19 tools, 2 prompts, 3 resources
+  -> stdio MCP server with 22 tools, 2 prompts, 3 resources
 
 runOperation(operation, codebaseGraph, input, context)
   -> { ok: true, data } | { ok: false, error, data? }
@@ -98,6 +99,7 @@ runOperation(operation, codebaseGraph, input, context)
 - **Dead-code gates**: `check` can opt into unused-file, unused-type, unused-member, and dependency hygiene rules. These rules use graph metrics plus local TypeScript AST facts and emit confidence/evidence in JSON and SARIF; dependency hygiene is scoped to the nearest package/workspace manifest.
 - **Suppression hygiene**: `check` reports active and stale `ci-ignore-*` / `@expected-unused` suppressions, emits stale suppression findings via `no-stale-suppressions`, and treats `@public` exported type declarations as intentional public API while `@internal` stays checkable.
 - **Highways H1/H2**: `highways` / `analyze_highways` enumerates entry-to-sink call routes, groups repeated routes by operation/shape/sink, detects bypasses and cowpaths around an existing canonical node, and with `--propose` synthesizes a read-only proposed highway with name, file, signature, skeleton, reroute plan, cycle safety, evidence, blast radius, recommendations, and a context pack for agents.
+- **Codebase map context packs**: `map` / `get_codebase_map` builds deterministic file/symbol/test/scope graphs with stable evidence IDs. `get_scope_graph` and `get_context_pack` are MCP-only filtered views derived from the same result, so agents get compact context without a second analyzer path.
 - **Shared graph-load pipeline**: CLI commands and MCP stdio startup both use `src/graph-loader/` for path checks, legacy cache migration, cache reuse, parse/build/analyze, optional persistence, and stderr progress events.
 - **graphology**: In-memory graph with O(1) neighbor lookup. PageRank and betweenness computed via graphology-metrics.
 - **Batch git churn**: Single `git log --all --name-only` call, parsed for all files. Avoids O(n) subprocess spawning.

docs/cli-reference.md

@@ -1,6 +1,6 @@
 # CLI Reference
 
-20 commands for terminal and CI use. The 18 analysis commands have full parity with MCP tools and auto-cache the index to `.codebase-intelligence/`; `check` runs the rules gate; `init` sets up agent adoption.
+21 commands for terminal and CI use. The 19 analysis commands have full parity with MCP tools and auto-cache the index to `.codebase-intelligence/`; `check` runs the rules gate; `init` sets up agent adoption.
 
 ## Commands
 
@@ -168,6 +168,18 @@ codebase-intelligence processes <path> [--entry <name>] [--limit <n>] [--json] [
 
 **Output:** processes with entry point, steps, depth, modules touched.
 
+### map
+
+Focused codebase graph plus token-bounded context pack for agents.
+
+```bash
+codebase-intelligence map <path> [--focus <symbolOrFile>] [--scope <scope>] [--depth <n>] [--format <format>] [--context-budget <n>] [--json] [--force]
+```
+
+**Formats:** `markdown` (default), `json`, `dot`, `graphml`.
+
+**Output:** overview, focus node, nodes, edges, evidence, contextPack (ranked files, symbols, tests, token estimate/budget), and summary. JSON mode includes stable evidence IDs (`evidence-*`) and edge IDs (`edge-*`) for agent-safe references.
+
 ### highways
 
 Find repeated routes that should converge on one canonical operation path.
@@ -237,20 +249,22 @@ codebase-intelligence init [path] [--agents <list>] [--all] [--skill] [--gitigno
 | `--min-tokens <n>` | duplicates | Minimum function body token count (default: 30) |
 | `--skip-local` | duplicates | Ignore families confined to one file |
 | `--trace <id>` | duplicates, highways | Return evidence for one family/opportunity id |
-| `--scope <s>` | changes | Git diff scope: staged, unstaged, all |
-| `--depth <n>` | dependents | Max traversal depth (default: 2) |
+| `--scope <s>` | changes, map | Git diff scope for `changes`; directory/module scope for `map` |
+| `--depth <n>` | dependents, map | Max traversal depth |
 | `--cohesion <n>` | forces | Min cohesion threshold (default: 0.6) |
 | `--tension <n>` | forces | Min tension threshold (default: 0.3) |
 | `--escape <n>` | forces | Min escape velocity threshold (default: 0.5) |
 | `--module <m>` | dead-exports | Filter by module path |
 | `--entry <name>` | processes | Filter by entry point name |
+| `--focus <name>` | map | Focus on one symbol, file, or scope |
+| `--context-budget <n>` | map | Approximate token budget for context pack |
 | `--operation <verb>` | highways | Focus on one operation verb |
 | `--shape <name>` | highways | Focus on one type/DTO shape |
 | `--min-routes <n>` | highways | Minimum routes reaching a sink before reporting |
 | `--propose` | highways | Include reroute proposal metadata |
 | `--min-files <n>` | clusters | Min files per cluster |
 | `--no-dry-run` | rename | Actually perform the rename (default: dry run) |
-| `--format <fmt>` | check | Output format: text, json, sarif |
+| `--format <fmt>` | map, check | Map export: markdown, json, dot, graphml. Check output: text, json, sarif |
 | `--fail-on <severity>` | check | Severity that fails the gate: error, warn, never |
 | `--gate <mode>` | check | Gate mode: all, new-only |
 | `--base <ref>` | check | Base git ref for new-only gating |

docs/data-model.md

@@ -171,6 +171,72 @@ CacheFacts {
 }
 ```
 
+## Codebase Map Result
+
+`map --json`, MCP `get_codebase_map`, `get_scope_graph`, and `get_context_pack`
+return deterministic graph/context data with stable evidence IDs.
+
+```typescript
+CodebaseMapResult {
+  overview: {
+    focus?: string
+    scope?: string
+    depth: number
+    contextBudget: number
+    totalNodes: number
+    totalEdges: number
+    totalEvidence: number
+  }
+  focus?: CodebaseMapNode
+  nodes: CodebaseMapNode[]
+  edges: CodebaseMapEdge[]
+  evidence: CodebaseMapEvidence[]
+  contextPack: CodebaseContextPack
+  summary: string
+}
+
+CodebaseMapNode {
+  id: string
+  kind: "file" | "symbol" | "test" | "scope"
+  label: string
+  file?: string
+  symbol?: string
+  type?: string
+  loc?: number
+  module?: string
+  score: number
+  evidenceIds: string[]
+}
+
+CodebaseMapEdge {
+  id: string                 // edge-<stable hash>
+  kind: "calls" | "contains" | "imports" | "tests"
+  from: string
+  to: string
+  label: string
+  weight: number
+  evidenceIds: string[]
+}
+
+CodebaseMapEvidence {
+  id: string                 // evidence-<stable hash>
+  kind: "focus" | "metric" | "call" | "contains" | "import" | "test" | "scope"
+  summary: string
+  file?: string
+  symbol?: string
+}
+
+CodebaseContextPack {
+  tokenBudget: number
+  tokenEstimate: number
+  rankedFiles: Array<{ path: string; rank: number; reason: string; tokenEstimate: number; evidenceIds: string[] }>
+  rankedSymbols: Array<{ file: string; symbol: string; rank: number; reason: string; tokenEstimate: number; evidenceIds: string[] }>
+  tests: Array<{ path: string; covers: string; rank: number; reason: string; tokenEstimate: number; evidenceIds: string[] }>
+  evidenceIds: string[]
+  nextCommands: string[]
+}
+```
+
 ## Highways Result
 
 `highways --json` and MCP `analyze_highways` return deterministic route-convergence opportunities.

docs/mcp-tools.md

@@ -1,6 +1,6 @@
 # MCP Tools Reference
 
-19 tools available via MCP stdio.
+22 tools available via MCP stdio.
 
 Operation tools return JSON text payloads. Invalid operation inputs return `isError: true` with `{ "error": "..." }` using the same descriptor validation messages as CLI bad-argument exits.
 
@@ -169,7 +169,37 @@ Trace execution flows from entry points through the call graph.
 **Use when:** "How does this app start?" "Trace request flow." "What are the entry points?"
 **Not for:** Static file dependencies (use get_dependents).
 
-## 17. analyze_highways
+## 17. get_codebase_map
+
+Build a deterministic focused graph plus context pack.
+
+**Input:** `{ focus?: string, scope?: string, depth?: number, format?: "json" | "markdown" | "dot" | "graphml", contextBudget?: number }`
+**Returns:** overview, focus node, nodes, edges, evidence, contextPack, summary
+
+**Use when:** Preparing an LLM task context, visualizing symbol/file neighborhoods, or exporting a structured codebase map.
+**Not for:** Raw execution flow listing (use get_processes) or route convergence analysis (use analyze_highways).
+
+## 18. get_scope_graph
+
+File/scope/test view derived from `get_codebase_map`.
+
+**Input:** same as `get_codebase_map`
+**Returns:** overview, focus node, file/test/scope nodes, imports/tests edges, evidence, summary
+
+**Use when:** An agent needs topology without symbol-level detail.
+**Not for:** Full context selection (use get_context_pack).
+
+## 19. get_context_pack
+
+Token-bounded context pack derived from `get_codebase_map`.
+
+**Input:** same as `get_codebase_map`
+**Returns:** tokenBudget, tokenEstimate, rankedFiles, rankedSymbols, tests, evidenceIds, nextCommands
+
+**Use when:** Passing compact, ranked code context to an LLM.
+**Not for:** Visual graph export (use get_codebase_map).
+
+## 20. analyze_highways
 
 Detect repeated entry-to-sink routes that should converge on one canonical operation path.
 
@@ -179,7 +209,7 @@ Detect repeated entry-to-sink routes that should converge on one canonical opera
 **Use when:** Enforcing dataflow discipline, finding ad-hoc routes, or planning canonical shared paths.
 **Not for:** Raw execution flow listing (use get_processes).
 
-## 18. get_clusters
+## 21. get_clusters
 
 Community-detected clusters of related files.
 
@@ -189,7 +219,7 @@ Community-detected clusters of related files.
 **Use when:** "What files are related?" "Find natural groupings." Discovering emergent groupings that differ from directory structure.
 **Not for:** Directory-based modules (use get_module_structure).
 
-## 19. check
+## 22. check
 
 Run the configurable rules engine and gate on findings.
 
@@ -237,6 +267,9 @@ Rules: `no-comments` (off by default), `no-circular-deps` (error), `no-dead-expo
 | "What changed?" | `detect_changes` |
 | "Find all references to X" | `rename_symbol` |
 | "How does data flow through the app?" | `get_processes` |
+| "What context should I give an LLM for this task?" | `get_context_pack` |
+| "Show a focused codebase graph" | `get_codebase_map` |
+| "Show only file/scope topology" | `get_scope_graph` |
 | "Which routes bypass canonical dataflow?" | `analyze_highways` |
 | "What files naturally belong together?" | `get_clusters` |
 | "What are the main areas?" | `get_groups` |