feat(cache): migrate canonical cache directory

.github/workflows/ci.yml

@@ -41,13 +41,14 @@ jobs:
       - name: Test
         run: pnpm test
 
-      # Coverage is best-effort: vitest v3 + v8 provider has a known worker
-      # timeout bug (onTaskUpdate) on CI runners. Tests pass above; coverage
-      # collection may timeout without affecting correctness.
+      # Coverage is best-effort: vitest v3 + v8 provider can hang after tests
+      # pass on CI runners. The blocking Test step above proves correctness;
+      # this step is bounded so coverage cannot block the release gate.
       - name: Coverage
         if: matrix.node-version == 22
         continue-on-error: true
-        run: pnpm vitest run --coverage --pool forks --no-file-parallelism
+        timeout-minutes: 4
+        run: timeout 180s pnpm vitest run --coverage --pool forks --no-file-parallelism || true
 
       - name: Upload coverage
         if: matrix.node-version == 22 && always()

.gitignore

@@ -12,6 +12,7 @@ test-results/
 scripts/
 
 # analysis + coverage artifacts
+.codebase-intelligence/
 .code-visualizer/
 coverage/
 

README.md

@@ -58,7 +58,7 @@ claude mcp add -s user -t stdio codebase-intelligence -- npx -y codebase-intelli
 
 - **18 CLI commands** for architecture analysis, dependency impact, 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 `.code-visualizer/` for fast repeat queries
+- **Auto-cached index** in `.codebase-intelligence/` for fast repeat queries
 - **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 and symbols
@@ -121,7 +121,7 @@ codebase-intelligence <command> <path> [options]
 | `--metric <m>` | Select ranking metric for `hotspots` |
 | `--scope <s>` | Select git diff scope for `changes`: `staged`, `unstaged`, `all` |
 
-The scanner always excludes common generated and agent-workspace directories such as `.code-visualizer/`, `.next/`, `dist/`, `coverage/`, `.worktrees/`, and `.claude/worktrees/`.
+The scanner always excludes common generated and agent-workspace directories such as `.codebase-intelligence/`, legacy `.code-visualizer/`, `.next/`, `dist/`, `coverage/`, `.worktrees/`, and `.claude/worktrees/`.
 
 For full command details, see [docs/cli-reference.md](docs/cli-reference.md).
 

docs/architecture.md

@@ -43,7 +43,8 @@ src/
   search/index.ts      <- BM25 search engine
   process/index.ts     <- Entry point detection + call chain tracing
   community/index.ts   <- Louvain clustering
-  persistence/index.ts <- Graph export/import to .code-visualizer/
+  persistence/index.ts <- Graph export/import to .codebase-intelligence/
+  persistence/index-dir.ts <- Canonical cache path + legacy .code-visualizer/ migration
   persistence/cache-key.ts <- Cache signature from HEAD, worktree content, CLI version, parser settings
   install/index.ts     <- Agent adoption: managed-block engine + per-agent file targets + skill
   server/graph-store.ts <- Global graph state (shared by CLI + MCP)
@@ -80,7 +81,7 @@ startMcpServer(codebaseGraph)
 - **Dead export detection**: Cross-references parsed exports against edge symbol lists. May miss `import *` or re-exports (known limitation).
 - **Graceful degradation**: Non-git dirs get churn=0, no-test codebases get coverage=false. Never crashes.
 - **Built-in scanner excludes**: Generated indexes, build outputs, coverage, framework caches, and agent worktrees are skipped before TypeScript program creation.
-- **Graph persistence**: CLI commands always cache the graph index to `.code-visualizer/`. Cache reuse requires matching HEAD, dirty/untracked file-content fingerprint, CLI version, and parser cache settings. MCP mode (`codebase-intelligence <path>`) requires `--index` to persist the cache.
+- **Graph persistence**: CLI commands always cache the graph index to `.codebase-intelligence/`. A legacy `.code-visualizer/` cache is migrated when canonical cache is absent. Cache reuse requires matching HEAD, dirty/untracked file-content fingerprint, CLI version, and parser cache settings. MCP mode (`codebase-intelligence <path>`) requires `--index` to persist the cache.
 
 ## Adding a New Metric
 

docs/cli-reference.md

@@ -1,6 +1,6 @@
 # CLI Reference
 
-18 commands for terminal and CI use. The 16 analysis commands have full parity with MCP tools and auto-cache the index to `.code-visualizer/`; `check` runs the rules gate; `init` sets up agent adoption.
+18 commands for terminal and CI use. The 16 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
 
@@ -196,7 +196,7 @@ preselected). Non-interactively (or with `--yes`/`--json`) it defaults to those
 The global skill is never installed unless `--skill` is passed.
 
 ```bash
-codebase-intelligence init [path] [--agents <list>] [--all] [--skill] [--yes] [--json]
+codebase-intelligence init [path] [--agents <list>] [--all] [--skill] [--gitignore] [--yes] [--json]
 ```
 
 **Output:** per-file actions (created / updated / unchanged) and skill install status.
@@ -227,13 +227,14 @@ codebase-intelligence init [path] [--agents <list>] [--all] [--skill] [--yes] [-
 | `--agents <list>` | init | Comma-separated agents, non-interactive (default: agents,claude) |
 | `--all` | init | Target every agent (non-interactive) |
 | `--skill` | init | Also install the global Claude skill (opt-in) |
+| `--gitignore` | init | Add `.codebase-intelligence/` to `.gitignore` idempotently |
 | `-y, --yes` | init | Accept defaults without prompting |
 
 ## Behavior
 
-**Auto-caching:** First CLI invocation parses the codebase and saves the index to `.code-visualizer/`. Subsequent commands use the cache only when `git HEAD`, dirty/untracked file contents under the analyzed path, the CLI version, and parser cache settings match. Add `.code-visualizer/` to `.gitignore`.
+**Auto-caching:** First CLI invocation parses the codebase and saves the index to `.codebase-intelligence/`. Subsequent commands use the cache only when `git HEAD`, dirty/untracked file contents under the analyzed path, the CLI version, and parser cache settings match. Legacy `.code-visualizer/` is migrated when `.codebase-intelligence/` is absent. Add `.codebase-intelligence/` to `.gitignore` manually or run `codebase-intelligence init --gitignore`.
 
-**Default scanner excludes:** The parser always skips `.git`, `node_modules`, `.code-visualizer`, `.next`, `dist`, `coverage`, `.turbo`, `.cache`, `.worktrees`, and `.claude/worktrees`, even if the target repo has no matching `.gitignore` entry.
+**Default scanner excludes:** The parser always skips `.git`, `node_modules`, `.codebase-intelligence`, legacy `.code-visualizer`, `.next`, `dist`, `coverage`, `.turbo`, `.cache`, `.worktrees`, and `.claude/worktrees`, even if the target repo has no matching `.gitignore` entry.
 
 **Large repo mode:** Repos above 1500 TypeScript files use a lightweight AST parser by default to avoid TypeScript program OOM. File/import/export/dependency metrics remain available; type-resolved call graph details are reduced. Set `CBI_FULL_PROGRAM_FILE_LIMIT=<n>` to tune the cutoff.
 
@@ -245,7 +246,7 @@ codebase-intelligence init [path] [--agents <list>] [--all] [--skill] [--yes] [-
 - `2` — bad args or usage error
 
 **MCP mode:** Running `codebase-intelligence <path>` without a subcommand starts the MCP stdio server (backward compatible). MCP-specific flags:
-- `--index` — persist graph index to `.code-visualizer/` (CLI auto-caches, MCP requires this flag)
+- `--index` — persist graph index to `.codebase-intelligence/` (CLI auto-caches, MCP requires this flag)
 - `--status` — print index status and exit
-- `--clean` — remove `.code-visualizer/` index and exit
+- `--clean` — remove `.codebase-intelligence/` and legacy `.code-visualizer/` indexes and exit
 - `--force` — re-index even if the cache signature matches

llms-full.txt

@@ -44,7 +44,8 @@ src/
   search/index.ts      <- BM25 search engine
   process/index.ts     <- Entry point detection + call chain tracing
   community/index.ts   <- Louvain clustering
-  persistence/index.ts <- Graph export/import to .code-visualizer/
+  persistence/index.ts <- Graph export/import to .codebase-intelligence/
+  persistence/index-dir.ts <- Canonical cache path + legacy .code-visualizer/ migration
   persistence/cache-key.ts <- Cache signature from HEAD, worktree content, CLI version, parser settings
   server/graph-store.ts <- Global graph state (shared by CLI + MCP)
   cli.ts               <- Entry point, CLI commands + MCP fallback
@@ -73,7 +74,7 @@ analyzeGraph(builtGraph, parsedFiles)
 - **Batch git churn**: Single `git log --all --name-only` call, parsed for all files. Avoids O(n) subprocess spawning.
 - **Dead export detection**: Cross-references parsed exports against edge symbol lists. May miss `import *` or re-exports.
 - **Graceful degradation**: Non-git dirs get churn=0, no-test codebases get coverage=false. Never crashes.
-- **Auto-caching**: CLI commands always cache the graph index to `.code-visualizer/`. MCP mode requires `--index` to persist.
+- **Auto-caching**: CLI commands always cache the graph index to `.codebase-intelligence/`. MCP mode requires `--index` to persist. Legacy `.code-visualizer/` is migrated when canonical cache is absent.
 
 ---
 
@@ -403,7 +404,7 @@ Community-detected file clusters (Louvain algorithm).
 
 ### init
 ```bash
-codebase-intelligence init [path] [--agents <list>] [--all] [--skill] [--yes] [--json]
+codebase-intelligence init [path] [--agents <list>] [--all] [--skill] [--gitignore] [--yes] [--json]
 ```
 Set up AI agents to use codebase-intelligence. Writes an idempotent, marked
 instruction block ("query CI before grep/read") into each selected agent's repo file —
@@ -424,8 +425,8 @@ Gate modes: all, new-only. Returns pass/warn/fail verdict, findings, and summary
 
 ## Global Behavior
 
-- **Auto-caching**: First run parses and saves index to `.code-visualizer/`. Subsequent runs use cache only when HEAD, dirty/untracked file contents under the analyzed path, CLI version, and parser cache settings match.
-- **Default scanner excludes**: `.git`, `node_modules`, `.code-visualizer`, `.next`, `dist`, `coverage`, `.turbo`, `.cache`, `.worktrees`, and `.claude/worktrees`.
+- **Auto-caching**: First run parses and saves index to `.codebase-intelligence/`. Subsequent runs use cache only when HEAD, dirty/untracked file contents under the analyzed path, CLI version, and parser cache settings match. Legacy `.code-visualizer/` is migrated when canonical cache is absent.
+- **Default scanner excludes**: `.git`, `node_modules`, `.codebase-intelligence`, legacy `.code-visualizer`, `.next`, `dist`, `coverage`, `.turbo`, `.cache`, `.worktrees`, and `.claude/worktrees`.
 - **Monorepo imports**: Root tsconfig path aliases and local package.json package names resolve to source files before graph construction.
 - **Large repo mode**: Above 1500 TypeScript files, use AST-only extraction to avoid TypeScript program OOM. Override with `CBI_FULL_PROGRAM_FILE_LIMIT`.
 - **Real-repo verification**: `pnpm verify:cli-real` runs the default matrix. `pnpm verify:cli-real:heavy` sets `CBI_REAL_PROFILE=heavy` and verifies large `/home/ubuntu` repos with minimum file/dependency thresholds.

llms.txt

@@ -41,6 +41,7 @@ codebase-intelligence init .                         # make AI agents use CI
 
 ## Behavior Notes
 
+- CLI analysis commands cache to `.codebase-intelligence/`; legacy `.code-visualizer/` is migration input only. Run `codebase-intelligence init --gitignore` to ignore the canonical cache directory.
 - `overview --json` includes `analysis.mode`, `analysis.callGraphPrecision`, and `analysis.fullProgramFileLimit`.
 - Repos above the full-program file limit use AST-only extraction; dependency metrics remain available, call graph precision becomes syntax-only.
 

package.json

@@ -12,7 +12,7 @@
     "build": "tsc -p tsconfig.build.json",
     "dev": "tsx src/cli.ts",
     "start": "node dist/cli.js",
-    "test": "pnpm build && vitest run --pool forks --no-file-parallelism",
+    "test": "pnpm build && vitest run --pool threads --no-file-parallelism",
     "test:coverage": "pnpm build && vitest run --coverage --pool threads --no-file-parallelism --exclude 'tests/*.e2e.test.ts'",
     "verify:cli-real": "pnpm build && node tools/verify-cli-real-codebases.mjs",
     "verify:cli-real:heavy": "pnpm build && CBI_REAL_PROFILE=heavy node tools/verify-cli-real-codebases.mjs",