@bugsbunnycodes1998/cartographer-core 0.1.4 → 0.1.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +139 -0
- package/package.json +3 -2
package/README.md
ADDED
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
# Cartographer
|
|
2
|
+
|
|
3
|
+
**See your code. Understand your architecture. Navigate with confidence.**
|
|
4
|
+
|
|
5
|
+
Point any codebase at Cartographer. Get an interactive, explorable 3D city where modules are neighborhoods, files are buildings, and dependencies are roads.
|
|
6
|
+
|
|
7
|
+
## Quick Start
|
|
8
|
+
|
|
9
|
+
```bash
|
|
10
|
+
npx @bugsbunnycodes1998/cartographer analyze https://github.com/expressjs/express --quick
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
This clones the repo, analyzes it, and opens a 3D city map in your browser at `http://localhost:3742`.
|
|
14
|
+
|
|
15
|
+
## Features
|
|
16
|
+
|
|
17
|
+
- **3D City Visualization** — modules as neighborhoods, files as buildings with glowing windows, dependencies as roads with flowing particles
|
|
18
|
+
- **Health Scoring** — composite 0-100 health per file (complexity, churn, test coverage, type safety). Buildings glow green (healthy) to red (critical)
|
|
19
|
+
- **AI Summaries** — OpenAI-powered hierarchical summaries at file, module, and system level
|
|
20
|
+
- **Git Archaeology** — churn analysis, bus factor, contributor mapping, evolution timeline
|
|
21
|
+
- **Guided Expeditions** — auto-generated tours: Grand Tour, Danger Zones, Request Lifecycle
|
|
22
|
+
- **Building Interiors** — zoom into a file to see functions as floors with call connections
|
|
23
|
+
- **Live Mode** — watch for file changes and update the city in real-time via WebSocket
|
|
24
|
+
- **Multi-Language** — TypeScript, JavaScript, Python, Rust, Go, Java
|
|
25
|
+
- **Cmd+K Search** — fuzzy search to fly to any file or module instantly
|
|
26
|
+
|
|
27
|
+
## Installation
|
|
28
|
+
|
|
29
|
+
```bash
|
|
30
|
+
npm install -g @bugsbunnycodes1998/cartographer
|
|
31
|
+
```
|
|
32
|
+
|
|
33
|
+
Requires Node.js 20+.
|
|
34
|
+
|
|
35
|
+
## Usage
|
|
36
|
+
|
|
37
|
+
### Analyze a GitHub repo
|
|
38
|
+
|
|
39
|
+
```bash
|
|
40
|
+
# Quick mode (structure only, instant)
|
|
41
|
+
cartographer analyze https://github.com/org/repo --quick
|
|
42
|
+
|
|
43
|
+
# With git history + health scoring
|
|
44
|
+
cartographer analyze https://github.com/org/repo --skip-llm
|
|
45
|
+
|
|
46
|
+
# Full analysis with AI summaries (requires OPENAI_API_KEY)
|
|
47
|
+
cartographer analyze https://github.com/org/repo
|
|
48
|
+
```
|
|
49
|
+
|
|
50
|
+
### Analyze a local project
|
|
51
|
+
|
|
52
|
+
```bash
|
|
53
|
+
cartographer analyze ./my-project
|
|
54
|
+
cartographer analyze . --quick
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
### Live mode (real-time updates)
|
|
58
|
+
|
|
59
|
+
```bash
|
|
60
|
+
cartographer live ./my-project
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
Edit files and watch the city update in your browser.
|
|
64
|
+
|
|
65
|
+
### Options
|
|
66
|
+
|
|
67
|
+
| Flag | Description |
|
|
68
|
+
|------|-------------|
|
|
69
|
+
| `--quick` | Structure only, no AI/git. Instant results |
|
|
70
|
+
| `--skip-git` | Skip git archaeology (churn, bus factor) |
|
|
71
|
+
| `--skip-llm` | Skip AI summaries (no OpenAI key needed) |
|
|
72
|
+
| `--root <dir>` | Scope analysis to a subdirectory |
|
|
73
|
+
| `--output <dir>` | Custom output directory |
|
|
74
|
+
| `--languages <list>` | Filter languages (e.g., `ts,py`) |
|
|
75
|
+
| `--no-serve` | Don't open the browser |
|
|
76
|
+
| `-p, --port <n>` | Custom port (default: 3742) |
|
|
77
|
+
|
|
78
|
+
### Environment Variables
|
|
79
|
+
|
|
80
|
+
| Variable | Description |
|
|
81
|
+
|----------|-------------|
|
|
82
|
+
| `OPENAI_API_KEY` | Required for AI summaries and custom expeditions |
|
|
83
|
+
| `CARTOGRAPHER_PORT` | Web UI port (default: 3742) |
|
|
84
|
+
|
|
85
|
+
## Navigating the City
|
|
86
|
+
|
|
87
|
+
| Action | How |
|
|
88
|
+
|--------|-----|
|
|
89
|
+
| **Pan** | Left-click drag |
|
|
90
|
+
| **Rotate** | Right-click drag |
|
|
91
|
+
| **Zoom** | Scroll wheel |
|
|
92
|
+
| **Select module** | Click a neighborhood |
|
|
93
|
+
| **Select file** | Click a building |
|
|
94
|
+
| **Enter building** | Click "Enter Building" in HUD |
|
|
95
|
+
| **Exit building** | Click "Exit Building" or Escape |
|
|
96
|
+
| **Search** | Cmd+K / Ctrl+K |
|
|
97
|
+
| **Back to overview** | Press Escape |
|
|
98
|
+
| **Expeditions** | Click "Expeditions" button |
|
|
99
|
+
|
|
100
|
+
## Visual Encoding
|
|
101
|
+
|
|
102
|
+
| Visual | Meaning |
|
|
103
|
+
|--------|---------|
|
|
104
|
+
| Building height | Lines of code |
|
|
105
|
+
| Building color (green) | Health 90-100 |
|
|
106
|
+
| Building color (blue) | Health 70-89 |
|
|
107
|
+
| Building color (amber) | Health 50-69 |
|
|
108
|
+
| Building color (orange) | Health 30-49 |
|
|
109
|
+
| Building color (red) | Health 0-29 |
|
|
110
|
+
| Road thickness | Coupling strength |
|
|
111
|
+
| Flowing particles | Data flow direction |
|
|
112
|
+
| Flame particles | High churn + low health |
|
|
113
|
+
| Gold shimmer | Excellent health (90+) |
|
|
114
|
+
| Warning icon | Bus factor = 1 |
|
|
115
|
+
|
|
116
|
+
## Supported Languages
|
|
117
|
+
|
|
118
|
+
| Language | Parsing | Imports | Modules |
|
|
119
|
+
|----------|---------|---------|---------|
|
|
120
|
+
| TypeScript | Full | Full | Barrel files, tsconfig paths |
|
|
121
|
+
| JavaScript | Full | Full | Barrel files |
|
|
122
|
+
| Python | Full | Full | `__init__.py` packages |
|
|
123
|
+
| Rust | Full | Full | `Cargo.toml`, `mod.rs` |
|
|
124
|
+
| Go | Full | Full | Directory packages, `go.mod` |
|
|
125
|
+
| Java | Full | Full | Maven/Gradle, package dirs |
|
|
126
|
+
|
|
127
|
+
## Development
|
|
128
|
+
|
|
129
|
+
```bash
|
|
130
|
+
git clone https://github.com/BugBunnyWanders/Cartographer.git
|
|
131
|
+
cd Cartographer
|
|
132
|
+
pnpm install
|
|
133
|
+
pnpm build
|
|
134
|
+
node packages/cli/dist/index.js analyze . --quick
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
## License
|
|
138
|
+
|
|
139
|
+
MIT
|