Skip to content

Commit 4949b73

Browse files
bntvllntbntvllnt
committed
docs: rewrite README for open source best practices
Add badges, TOC, features summary, architecture diagram, contributing section. Add LICENSE file. Add repository/bugs/homepage to package.json.
1 parent 870f996 commit 4949b73

2 files changed

Lines changed: 146 additions & 90 deletions

File tree

‎README.md‎

Lines changed: 138 additions & 90 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,63 @@
1+
<div align="center">
2+
13
# codebase-visualizer
24

3-
3D interactive codebase visualization for TypeScript projects. Parses your codebase, builds a dependency graph, computes architectural metrics, and serves an interactive 3D map in your browser. Also works as an MCP server for LLM-assisted code understanding.
5+
**3D interactive codebase visualization for TypeScript projects.**
6+
7+
Parse your codebase, build a dependency graph, compute architectural metrics, and explore it all in an interactive 3D map. Also works as an MCP server for LLM-assisted code understanding.
8+
9+
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
10+
[![Node](https://img.shields.io/badge/Node-%3E%3D18-brightgreen)](https://nodejs.org)
11+
[![TypeScript](https://img.shields.io/badge/TypeScript-strict-blue)](https://www.typescriptlang.org)
12+
13+
</div>
14+
15+
---
416

517
## Screenshots
618

7-
Galaxy view — 3D force-directed graph with module clouds and group legend:
19+
| Galaxy View | Module View | Forces View |
20+
|:-----------:|:-----------:|:-----------:|
21+
| ![Galaxy](docs/screenshot-galaxy.png) | ![Module](docs/screenshot-module.png) | ![Forces](docs/screenshot-forces.png) |
22+
| 3D force graph, module clouds, group legend | File clusters by directory, labeled clouds | Centrifuge: tension, bridges, candidates |
23+
24+
## Quick Start
25+
26+
```bash
27+
npx codebase-visualizer ./src
28+
```
29+
30+
That's it. Opens a 3D map at `http://localhost:3333`.
831

9-
![Galaxy View](docs/screenshot-galaxy.png)
32+
## Table of Contents
1033

11-
Module view — files clustered by directory with labeled cloud spheres:
34+
- [Features](#features)
35+
- [Installation](#installation)
36+
- [Usage](#usage)
37+
- [MCP Integration](#mcp-integration)
38+
- [Browser Views](#browser-views)
39+
- [Metrics](#metrics)
40+
- [REST API](#rest-api)
41+
- [Architecture](#architecture)
42+
- [Requirements](#requirements)
43+
- [Limitations](#limitations)
44+
- [Contributing](#contributing)
45+
- [License](#license)
1246

13-
![Module View](docs/screenshot-module.png)
47+
## Features
1448

15-
Forces view — centrifuge analysis showing tension, bridges, and extraction candidates:
49+
- **8 interactive 3D views** — Galaxy, Dependency Flow, Hotspot, Focus, Module, Forces, Churn, Coverage
50+
- **11 architectural metrics** — PageRank, betweenness, coupling, cohesion, tension, churn, complexity, blast radius, dead exports, test coverage, escape velocity
51+
- **3D module clouds** — transparent spheres group files by directory with Phong shading and zoom-based fade
52+
- **MCP server** — 8 tools for LLM-assisted code understanding (Claude Code, Cursor, VS Code)
53+
- **REST API** — 9 endpoints for programmatic access
54+
- **Search** — find any file and fly the camera to it
55+
- **Detail panel** — click any node for full metrics
56+
- **Configurable** — node size, link color, physics, cloud opacity
1657

17-
![Forces View](docs/screenshot-forces.png)
58+
## Installation
1859

19-
## Install
60+
Run directly with npx (no install needed):
2061

2162
```bash
2263
npx codebase-visualizer ./src
@@ -39,26 +80,23 @@ npx codebase-visualizer ./src
3980
# => 3D map ready at http://localhost:3333
4081
```
4182

42-
Opens an interactive 3D force-directed graph in your browser with 8 views, 3D module clouds, a group legend, search, detail panel, and configurable settings.
43-
44-
### MCP Mode (for LLMs)
83+
### MCP Mode
4584

4685
```bash
4786
npx codebase-visualizer --mcp ./src
4887
```
4988

50-
Starts a stdio MCP server exposing 8 tools for LLM-assisted code understanding. No browser, no HTTP.
89+
Starts a stdio MCP server. No browser, no HTTP.
5190

52-
### CLI Options
91+
### Options
5392

54-
```
55-
codebase-visualizer <path> # Parse and visualize
56-
--mcp # MCP stdio mode (no browser)
57-
--port <number> # Web server port (default: 3333)
58-
--help # Show help
59-
```
93+
| Flag | Description | Default |
94+
|------|-------------|---------|
95+
| `<path>` | Path to TypeScript codebase | required |
96+
| `--mcp` | MCP stdio mode | off |
97+
| `--port <n>` | Web server port | `3333` |
6098

61-
## MCP Setup
99+
## MCP Integration
62100

63101
### Claude Code
64102

@@ -90,97 +128,92 @@ Add to `.cursor/mcp.json` or `.vscode/mcp.json`:
90128
}
91129
```
92130

93-
## MCP Tools
131+
### MCP Tools
94132

95-
| Tool | Purpose |
96-
|------|---------|
133+
| Tool | What it does |
134+
|------|--------------|
97135
| `codebase_overview` | High-level architecture: modules, entry points, key metrics |
98136
| `file_context` | Everything about one file: exports, imports, dependents, metrics |
99137
| `get_dependents` | Blast radius: what breaks if you change this file |
100-
| `find_hotspots` | Ranked problem files by any metric (coupling, pagerank, churn, complexity, blast_radius, coverage...) |
101-
| `get_module_structure` | Module map with cross-deps, cohesion scores, circular deps |
102-
| `analyze_forces` | Centrifuge analysis: cohesion, tension files, bridges, extraction candidates |
103-
| `find_dead_exports` | Unused exports across the codebase — code that can be safely removed |
104-
| `get_groups` | Top-level directory groups with aggregate metrics: files, LOC, importance, coupling |
105-
106-
## Browser Features
107-
108-
### 8 Views
109-
110-
| # | View | What It Shows |
111-
|---|------|---------------|
112-
| 1 | **Galaxy** (default) | 3D force-directed graph. Color = module, size = PageRank importance |
113-
| 2 | **Dependency Flow** | DAG layout (top-to-bottom). Circular deps in red |
114-
| 3 | **Hotspot** | Health coloring: green (healthy) to red (high coupling). Size = LOC |
115-
| 4 | **Focus** | Click a node to see its 2-hop neighborhood. Everything else fades |
116-
| 5 | **Module** | Files cluster by directory. Cross-module edges in yellow |
117-
| 6 | **Forces** | Centrifuge analysis: tension (yellow), bridges (cyan), junk drawers (red), extraction candidates (green) |
118-
| 7 | **Churn** | Git commit frequency heatmap. Red = frequently changed files |
119-
| 8 | **Coverage** | Test coverage: green = has tests, red = untested |
120-
121-
### 3D Module Clouds
122-
123-
Transparent 3D spheres group files by top-level directory with:
124-
- Phong shading + wireframe overlay for depth perception
125-
- Zoom-based opacity fade (clouds disappear when camera is close)
126-
- Smart grouping: `src/components/ui/` becomes "components", `convex/agents/eval/` becomes "convex"
127-
- Dynamic threshold based on project size
128-
129-
Toggle via Settings > "Module Clouds" checkbox.
138+
| `find_hotspots` | Ranked problem files by any metric |
139+
| `get_module_structure` | Module map with cross-deps, cohesion, circular deps |
140+
| `analyze_forces` | Centrifuge analysis: tension, bridges, extraction candidates |
141+
| `find_dead_exports` | Unused exports that can be safely removed |
142+
| `get_groups` | Top-level directory groups with aggregate metrics |
143+
144+
## Browser Views
145+
146+
| View | What it shows |
147+
|------|---------------|
148+
| **Galaxy** | 3D force-directed graph. Color = module, size = PageRank |
149+
| **Dep Flow** | DAG layout (top-to-bottom). Circular deps in red |
150+
| **Hotspot** | Health heatmap: green (healthy) to red (high coupling) |
151+
| **Focus** | Click a node to see its 2-hop neighborhood |
152+
| **Module** | Files cluster by directory. Cross-module edges in yellow |
153+
| **Forces** | Centrifuge: tension (yellow), bridges (cyan), extraction (green) |
154+
| **Churn** | Git commit frequency heatmap |
155+
| **Coverage** | Test coverage: green = tested, red = untested |
156+
157+
### Module Clouds
158+
159+
Transparent 3D spheres group files by top-level directory:
160+
161+
- Phong shading + wireframe for depth perception
162+
- Zoom-based opacity fade
163+
- Smart grouping: `src/components/ui/` becomes "components"
164+
- Toggle via Settings > "Module Clouds"
130165

131166
### Group Legend
132167

133-
Bottom-left legend shows:
134-
- View-specific color coding
135-
- When clouds are enabled: color swatch + group name + file count + importance percentage for each group (up to 8 groups, sorted by PageRank)
168+
Bottom-left legend shows view-specific color coding. When clouds are enabled, adds color swatch + group name + file count + importance % for up to 8 groups sorted by PageRank.
136169

137-
### Other UI
170+
## Metrics
138171

139-
- **Search**: find any file by name, fly camera to it
140-
- **Detail Panel**: click any node to see full metrics — PageRank, coupling, fan-in/out, complexity, blast radius, dead exports, test coverage
141-
- **Settings Panel**: configure node opacity/size, link color/width, physics charge/distance, cloud opacity
142-
- **Project Bar**: project name, file/function/dependency counts, circular dep count, tension file count
172+
| Metric | What it reveals |
173+
|--------|-----------------|
174+
| **PageRank** | Most-referenced files (importance) |
175+
| **Betweenness** | Bridge files between disconnected modules |
176+
| **Coupling** | How tangled a file is (fan-out / total connections) |
177+
| **Cohesion** | Does a module belong together? (internal / total deps) |
178+
| **Tension** | Is a file torn between modules? (entropy of cross-module pulls) |
179+
| **Escape Velocity** | Should this module be its own package? |
180+
| **Churn** | Git commit frequency |
181+
| **Complexity** | Average cyclomatic complexity of exports |
182+
| **Blast Radius** | Transitive dependents affected by a change |
183+
| **Dead Exports** | Unused exports (safe to remove) |
184+
| **Test Coverage** | Whether a test file exists for each source file |
143185

144186
## REST API
145187

146188
| Endpoint | Returns |
147189
|----------|---------|
148-
| `GET /api/graph` | All nodes (with metrics) + edges + stats |
149-
| `GET /api/groups` | Group metrics sorted by importance (name, files, LOC, importance, fanIn, fanOut, color) |
150-
| `GET /api/forces` | Force analysis (cohesion, tension, bridges, extraction candidates) |
190+
| `GET /api/graph` | All nodes + edges + stats |
191+
| `GET /api/groups` | Group metrics sorted by importance |
192+
| `GET /api/forces` | Force analysis (cohesion, tension, bridges) |
151193
| `GET /api/modules` | Module-level metrics |
152194
| `GET /api/hotspots?metric=coupling&limit=10` | Ranked hotspot files |
153195
| `GET /api/file/<path>` | Single file details + metrics |
154196
| `GET /api/meta` | Project name |
155197
| `GET /api/ping` | Health check |
156198
| `POST /api/mcp` | MCP tool invocation (web mode) |
157199

158-
## Metrics
159-
160-
| Metric | What It Reveals |
161-
|--------|-----------------|
162-
| **PageRank** | Most-referenced files (importance) |
163-
| **Betweenness** | Bridge files connecting otherwise-disconnected modules |
164-
| **Coupling** | How tangled a file is (fan-out / total connections) |
165-
| **Cohesion** | Does a module belong together? (internal / total deps) |
166-
| **Tension** | Is a file torn between modules? (entropy of cross-module pulls) |
167-
| **Escape Velocity** | Should this module be its own package? (high external use, low internal deps) |
168-
| **Churn** | Git commit frequency (files that change often) |
169-
| **Cyclomatic Complexity** | Average complexity of exported functions |
170-
| **Blast Radius** | Transitive dependents affected if this file changes |
171-
| **Dead Exports** | Unused exports (code that can be safely removed) |
172-
| **Test Coverage** | Whether a test file exists for each source file |
173-
174-
## How It Works
200+
## Architecture
175201

176202
```
177-
Parse (TS Compiler API) -> Build Graph (graphology) -> Analyze (metrics) -> Serve (Next.js + 3d-force-graph)
203+
codebase-visualizer <path>
204+
|
205+
v
206+
+---------+ +---------+ +----------+ +---------+
207+
| Parser | --> | Graph | --> | Analyzer | --> | Server |
208+
| TS AST | | grapho- | | metrics | | Next.js |
209+
| | | logy | | | | or MCP |
210+
+---------+ +---------+ +----------+ +---------+
178211
```
179212

180-
1. **Parser** extracts files, exported functions, and import relationships using the TypeScript Compiler API. Resolves tsconfig path aliases (`@/` imports), respects `.gitignore`, detects test file associations.
181-
2. **Graph builder** creates nodes (files + functions) and edges (import deps + test associations) using graphology. Detects circular dependencies via iterative DFS.
182-
3. **Analyzer** computes PageRank, betweenness centrality, coupling, cohesion, tension, escape velocity, churn, complexity, blast radius, dead exports, test coverage, and group-level aggregations.
183-
4. **Server** serves the 3D visualization via Next.js (browser mode) or exposes graph queries via MCP stdio (LLM mode).
213+
1. **Parser** — extracts files, functions, and imports via the TypeScript Compiler API. Resolves path aliases, respects `.gitignore`, detects test associations.
214+
2. **Graph** — builds nodes and edges with [graphology](https://graphology.github.io/). Detects circular deps via iterative DFS.
215+
3. **Analyzer** — computes all 11 metrics plus group-level aggregations.
216+
4. **Server** — serves the 3D visualization via [Next.js](https://nextjs.org/) + [3d-force-graph](https://github.com/vasturiano/3d-force-graph), or exposes queries via MCP stdio.
184217

185218
## Requirements
186219

@@ -189,11 +222,26 @@ Parse (TS Compiler API) -> Build Graph (graphology) -> Analyze (metrics) -> Serv
189222

190223
## Limitations
191224

192-
- TypeScript only (no JavaScript CommonJS, Python, Go, etc.)
225+
- TypeScript only (no JS CommonJS, Python, Go, etc.)
193226
- Static analysis only (no runtime/dynamic imports)
194-
- File-level + exported function-level granularity (no internal function calls)
195-
- Client-side 3D rendering requires WebGL
227+
- File + exported function granularity (no internal function calls)
228+
- Client-side 3D requires WebGL
229+
230+
## Contributing
231+
232+
Contributions are welcome. Please open an issue first to discuss what you'd like to change.
233+
234+
```bash
235+
git clone https://github.com/bntvllnt/codebase-visualizer.git
236+
cd codebase-visualizer
237+
pnpm install
238+
pnpm dev # tsx watch mode
239+
pnpm test # vitest
240+
pnpm lint # eslint
241+
pnpm typecheck # tsc --noEmit
242+
pnpm build # production build
243+
```
196244

197245
## License
198246

199-
MIT
247+
[MIT](LICENSE)

‎package.json‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,6 +35,14 @@
3535
],
3636
"author": "bntvllnt",
3737
"license": "MIT",
38+
"repository": {
39+
"type": "git",
40+
"url": "git+https://github.com/bntvllnt/codebase-visualizer.git"
41+
},
42+
"bugs": {
43+
"url": "https://github.com/bntvllnt/codebase-visualizer/issues"
44+
},
45+
"homepage": "https://github.com/bntvllnt/codebase-visualizer#readme",
3846
"dependencies": {
3947
"3d-force-graph": "^1.79.1",
4048
"@modelcontextprotocol/sdk": "^1.0.0",

0 commit comments

Comments
 (0)