# codemap-3d

3D code structure visualizer — CLI + MCP server powered by tree-sitter.

Parses source code into a graph of symbols and relationships (functions, classes, imports, call sites) and renders an interactive 3D visualization using [3d-force-graph](https://github.com/vasturiano/3d-force-graph).

## Supported Languages

| Language             | Extensions                          |
|----------------------|-------------------------------------|
| JavaScript/TypeScript| `.js` `.mjs` `.cjs` `.jsx` `.ts` `.tsx` |
| Python               | `.py`                               |
| Go                   | `.go`                               |
| Java                 | `.java`                             |
| Kotlin               | `.kt` `.kts`                        |
| PHP                  | `.php`                              |
| Dart                 | `.dart`                             |

## Installation

```bash
# Clone and link globally
git clone <repo-url>
cd code-visualizer
npm install
npm run build
npm link

# Now available everywhere:
codemap <path>
```

### Development mode (no build needed)

```bash
npx tsx src/index.ts <path>
```

## Commands

### `codemap <path>` — Generate visualization

Analyzes a directory and generates a static 3D visualization.

```bash
codemap ./my-project
codemap ./my-project -t cyberpunk --open
codemap ./my-project -f json -o ./report
```

| Option              | Description                          | Default   |
|---------------------|--------------------------------------|-----------|
| `-o, --output <dir>`| Output directory                     | `output`  |
| `-f, --format <type>`| Output format: `html`, `json`       | `html`    |
| `-t, --theme <name>`| Theme: `clarity`, `cyberpunk`        | `clarity` |
| `--open`            | Auto-open in browser                 |           |
| `--no-files`        | Exclude file nodes from graph        |           |

**Interactive controls:**

- **Fuzzy search** — VS Code-style search with dropdown suggestions, keyboard navigation (arrow keys + enter), click to center camera on node
- **Filter buttons** — toggle Files, Classes, Functions, Methods visibility
- **Node click** — opens info panel with details, incoming/outgoing connections, and Center buttons to navigate to connected nodes
- **Export Graph** — download graph data as JSON
- **Graph summary** — sidebar showing node and edge counts

### `codemap blast <path>` — Blast radius visualization

Visualizes the blast radius of git changes on the current branch. Shows the same 3D graph with visual indicators for how close each node is to the changed code.

- Changed nodes: original color + red 2D ring outline + black center dot
- Nearby nodes: original color + fading red ring based on distance
- Unaffected nodes: faded when "Fade unaffected nodes" is enabled

```bash
codemap blast ./my-project
codemap blast ./my-project -b develop --open
codemap blast ./my-project -t cyberpunk -o ./blast-report
```

| Option              | Description                                  | Default      |
|---------------------|----------------------------------------------|--------------|
| `-o, --output <dir>`| Output directory                             | `output`     |
| `-t, --theme <name>`| Theme: `clarity`, `cyberpunk`                | `clarity`    |
| `-b, --base <branch>`| Base branch to diff against                 | auto-detect  |
| `--open`            | Auto-open in browser                         |              |
| `--no-files`        | Exclude file nodes from graph                |              |

**Interactive controls in the blast radius view:**

- **Changed Files panel** — expandable list of changed files; each file expands to show individual changed nodes (functions, classes, methods) with kind badges
- **Per-node filtering** — toggle individual files or nodes on/off to isolate specific changes; file checkbox shows indeterminate state when partially selected
- **Center button** — zoom the camera to any changed node; also available on connections in the info panel
- **Blast direction** — Incoming (default, shows callers/importers), Both, or Outgoing (shows callees/dependencies)
- **Max blast distance slider** — limit blast radius depth (1–10, default 3)
- **Fade unaffected nodes** — checkbox (on by default) to fade nodes and links outside the blast radius
- **Impact alert** — top bar indicator showing how many nodes are affected
- **Export Graph** — download graph + blast radius data as JSON
- **Fuzzy search** — same VS Code-style search as the explorer view, with center-on-click

### `codemap serve <path>` — Live dev server

Starts a dev server with file watching and live reload via WebSocket.

```bash
codemap serve ./my-project
codemap serve ./my-project -p 8080 --open
```

| Option              | Description                          | Default   |
|---------------------|--------------------------------------|-----------|
| `-p, --port <number>`| Server port                         | `3333`    |
| `-t, --theme <name>`| Theme: `clarity`, `cyberpunk`        | `clarity` |
| `--open`            | Auto-open in browser                 |           |

## MCP Server

codemap-3d exposes an MCP server for integration with AI tools (Claude, Cursor, etc.).

### Setup

```bash
node dist/server.js
```

Add to your MCP client config (e.g. Claude Desktop, Claude Code):

```json
{
  "mcpServers": {
    "codemap-3d": {
      "command": "node",
      "args": ["/path/to/code-visualizer/dist/server.js"]
    }
  }
}
```

### Tools

#### `generate_graph`

Parse a directory and return the full code structure graph as JSON.

| Parameter      | Type    | Required | Description                        |
|----------------|---------|----------|------------------------------------|
| `directory`    | string  | yes      | Absolute path to analyze           |
| `include_files`| boolean | no       | Include file nodes (default: true) |

**Returns:** Full graph with nodes (files, classes, functions, methods) and edges (calls, imports, contains).

#### `analyze_blast_radius`

Analyze the blast radius of git changes — returns structured JSON optimized for LLM consumption. Does not open a browser.

| Parameter      | Type    | Required | Description                                          |
|----------------|---------|----------|------------------------------------------------------|
| `directory`    | string  | yes      | Absolute path to git repository                      |
| `base_branch`  | string  | no       | Base branch to diff against (default: auto-detect)   |
| `max_distance` | number  | no       | Max blast radius depth, 1–20 (default: 3)            |
| `direction`    | string  | no       | `incoming`, `outgoing`, or `both` (default: incoming) |
| `include_files`| boolean | no       | Include file nodes (default: true)                   |

**Returns:**

```json
{
  "changed_files": [
    {
      "path": "src/utils/Mongo.ts",
      "changed_nodes": [
        { "id": "class:src/utils/Mongo.ts:Mongo", "name": "Mongo", "kind": "class" }
      ]
    }
  ],
  "blast_radius": {
    "direction": "incoming",
    "max_distance": 3,
    "total_changed": 2,
    "total_affected": 8
  },
  "affected_nodes": [
    { "id": "...", "name": "Mongo", "kind": "class", "file": "src/utils/Mongo.ts", "lines": "10-50", "blast_distance": 0, "is_changed": true },
    { "id": "...", "name": "UserService", "kind": "class", "file": "src/services/UserService.ts", "lines": "5-80", "blast_distance": 1, "is_changed": false }
  ],
  "graph_summary": { "files": 107, "classes": 46, "functions": 332, "call_edges": 427, "import_edges": 146 }
}
```

#### `visualize_blast_radius`

Same analysis as `analyze_blast_radius`, but also generates an interactive 3D HTML visualization and opens it in the browser.

| Parameter      | Type    | Required | Description                                          |
|----------------|---------|----------|------------------------------------------------------|
| `directory`    | string  | yes      | Absolute path to git repository                      |
| `base_branch`  | string  | no       | Base branch to diff against (default: auto-detect)   |
| `output_dir`   | string  | no       | Output directory for HTML (default: `<dir>/codemap-blast`) |
| `theme`        | string  | no       | `clarity` or `cyberpunk` (default: clarity)          |
| `include_files`| boolean | no       | Include file nodes (default: true)                   |

**Returns:** Summary JSON + opens interactive blast radius visualization in default browser.

#### `get_supported_languages`

List programming languages supported for code structure analysis. No parameters.

## Themes

- **clarity** — light, professional (grays, blues, greens)
- **cyberpunk** — dark, neon (cyan, lime, magenta on black)