CLAUDE.md git:20260828.23479a6A

Immutable. This exact content is served forever at /api/v1/blob/5a8a25fb3355ab76.

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Commands

```bash
# Build
npm run build          # Bundle extension via esbuild + copy WASM files to dist/wasm/
npm run build:cli      # Build CLI only
npm run watch          # Rebuild on change

# Test
npm test               # All tests (Vitest)
npm run test:unit      # Unit tests only
npm run test:cli       # CLI tests
npm run test:coverage  # Coverage report (V8)
npm run test:watch     # Watch mode
npx vitest run tests/path/to/foo.test.ts  # Single test file

# E2E (real VS Code Electron instance)
npm run test:vscode      # E2E from source
npm run test:vscode:vsix # E2E from packaged .vsix

# Lint / Types
npm run lint           # ESLint check
npm run lint:fix       # ESLint auto-fix
npm run check:types    # TypeScript strict check

# Package
npm run package        # Build .vsix
npm run package:verify # Verify no .map files in package

# dependencies
npm audit
npm audit fix
cve-lite --verbose # use npm install -g cve-lite to install cve-lite
```

Requires Node.js ≥22. No native compilation needed — Tree-sitter uses WASM.

## Architecture

VS Code extension + standalone CLI + MCP server for AI-friendly dependency visualization.

### Four-Layer Structure

1. **`analyzer/`** — Pure Node.js. **NO vscode imports**. Core analysis: Spider (file-level regex import parsing), SymbolAnalyzer (ts-morph AST), LspCallHierarchyAnalyzer (VS Code LSP), PathResolver, caching.
   - `analyzer/callgraph/` — Live Call Graph: GraphExtractor (Tree-sitter queries), CallGraphIndexer (sql.js SQLite), CallGraphQuery (BFS), cycleUtils.

2. **`extension/`** — VS Code host. GraphProvider orchestrates 8+ services in `extension/services/`: BackgroundIndexingManager, CallGraphViewService, CommandRegistrationService, EditorEventsService, GraphViewService, SymbolViewService, WebviewMessageRouter, etc.

3. **`mcp/`** — MCP server (stdio transport). **NO vscode imports**. 23 tools (`McpToolName` in `src/mcp/types.ts`) for LLM clients (Copilot, Claude, Cursor). Standalone Node.js process. Includes `review_pr` — deterministic local Git-diff review (also exposed via CLI as `graph-it review-pr` and as a reusable GitHub Action `.github/actions/graph-it-review-gate`).

4. **`webview/`** — React 19 browser context. ReactFlow for file/symbol graphs (`webview/components/reactflow/`), Cytoscape.js for live call graph (`webview/components/cytoscape/`). Entry points: `webview/index.tsx` → `dist/webview.js` and `webview/callgraph/index.tsx` → `dist/callgraph.js`.

**`shared/`** — Types, message protocol (extension ↔ webview), path utilities, constants.

### Dual Bundles

- `dist/extension.js` — VS Code extension
- `dist/graph-it.js` — Standalone CLI
- `dist/webview.js` — File/symbol graph React app
- `dist/callgraph.js` — Call graph panel React app

### Message Protocol

Extension ↔ Webview uses typed messages defined in `src/shared/types.ts`. Always update both sides when adding new messages.

## Critical Rules

**No vscode imports** in `analyzer/` or `mcp/` — these run outside VS Code context.

**No .map files in .vsix** — enforced by `npm run package:verify`. Verify: `npx vsce ls | grep "\.map$"` must return empty.

**Cross-platform paths** — use `normalizePath()` from `src/shared/path.ts` before storing paths in Sets/Maps. Never assume case-sensitive filesystem.

**React: no callback props in useMemo/useCallback deps** — causes re-render cascades. Use `useRef` to hold callbacks, omit from deps arrays.

**ReverseIndex lazy cleanup** — never delete empty maps immediately in `removeDependenciesFromSource()`. Empty maps are cleaned up lazily during queries to avoid race conditions during file re-analysis; see `tests/analyzer/ReverseIndexBugFix.test.ts`.

**Structured errors** — throw `SpiderError` with `SpiderErrorCode` enum (not raw `Error`) for anything callers need to branch on (e.g. `FILE_NOT_FOUND`, `PARSE_ERROR`).

**sql.js WASM for Live Call Graph** — `dist/wasm/sqljs.wasm` must ship in the `.vsix`; verify with `npx vsce ls | grep sqljs.wasm` after touching `esbuild.js` or call-graph deps.

## Adding a Feature — Recipes

- **New webview message**: add type to `src/shared/types.ts` → add handler in the relevant `extension/services/*` → register in `WebviewMessageRouter` → call `vscode.postMessage()` from React.
- **New MCP tool**: add name to `McpToolName` in `src/mcp/types.ts` → Zod param schema + result type → register in `src/mcp/mcpServer.ts` with a WHEN/WHY/WHAT description → handle in `src/mcp/McpWorker.ts` switch → test via `node scripts/test-mcp.js`.

## Codebase Exploration

For broad tasks spanning multiple folders, bootstrap with:
```bash
graph-it architecture --format toon
```
Returns a TOON-format token-optimized snapshot (`nodes`, `edges`, `nodeCount`, `edgeCount`). Then use targeted MCP tools (`generate_codemap`, `query_call_graph`, `analyze_file_logic`) on specific files/symbols.

For natural language questions about the codebase:
```bash
graph-it query "how does Spider crawl files" --format text
graph-it query "what calls CallGraphIndexer" --depth 3
```
Requires `ANTHROPIC_API_KEY` (uses `claude-haiku-4-5`) or `OPENAI_API_KEY` + `OPENAI_BASE_URL` + `OPENAI_MODEL`. Falls back to heuristic analysis when no key is set (stderr warning).

## Key Docs

- `.github/copilot-instructions.md` — Full dev guide (603 lines): architecture, patterns, WASM, packaging, E2E setup
- `docs/architecture/codemaps/architecture.md` — 5-layer diagram, 50+ components
- `docs/development/CODING_STANDARDS.md` — TypeScript conventions
- `DEVELOPMENT.md` — Setup and testing details

## graphify

This project has a knowledge graph at graphify-out/ with god nodes, community structure, and cross-file relationships.

Rules:
- For codebase questions, first run `graphify query "<question>"` when graphify-out/graph.json exists. Use `graphify path "<A>" "<B>"` for relationships and `graphify explain "<concept>"` for focused concepts. These return a scoped subgraph, usually much smaller than GRAPH_REPORT.md or raw grep output.
- If graphify-out/wiki/index.md exists, use it for broad navigation instead of raw source browsing.
- Read graphify-out/GRAPH_REPORT.md only for broad architecture review or when query/path/explain do not surface enough context.
- After modifying code, run `graphify update .` to keep the graph current (AST-only, no API cost).