codeflowmap 0.1.1 → 0.1.2
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 +35 -5
- package/bin/code-mapper.js +623 -109
- package/package.json +2 -3
- package/web/assets/{index-C_ISsC7i.css → index-BkQ6cFaF.css} +1 -1
- package/web/assets/index-DUr1zMp_.js +330 -0
- package/web/graph.json +1 -1
- package/web/index.html +2 -2
- package/web/assets/index-6OE6CzFu.js +0 -330
package/README.md
CHANGED
|
@@ -17,7 +17,7 @@
|
|
|
17
17
|
|
|
18
18
|
<!-- Swap this for a real demo gif/png whenever you grab one (scan → graph → focus → annotate). -->
|
|
19
19
|
<p align="center">
|
|
20
|
-
<img src="assets/hero.svg" alt="codeflowmap: focus a file to see its callers (left), dependencies (right), and its writes / reads / auth" width="860">
|
|
20
|
+
<img src="https://raw.githubusercontent.com/man-consult/code-mapper/main/assets/hero.svg" alt="codeflowmap: focus a file to see its callers (left), dependencies (right), and its writes / reads / auth" width="860">
|
|
21
21
|
</p>
|
|
22
22
|
|
|
23
23
|
```bash
|
|
@@ -36,6 +36,8 @@ Firstly: understanding the code an LLM wrote for me. I pretty soon discovered th
|
|
|
36
36
|
|
|
37
37
|
The second is dropping into an unfamiliar repo and tracing how it stitches together, what calls what, where data gets written, which paths run through auth. Slow work, and easy to get wrong when it's not your local playground. This part is all about learning good patterns from people who know what they're doing.
|
|
38
38
|
|
|
39
|
+
The next challenge was knowing where to start, which I'd been answering with a second tool that worked in conjunction with the graph. So I folded it in, and now it'll generate a guided tour of the codebase to go with the graph.
|
|
40
|
+
|
|
39
41
|
It's experimental because it was built to be useful to me first, not to be a finished product. If it helps you better understand a codebase the same way, good.
|
|
40
42
|
|
|
41
43
|
---
|
|
@@ -45,10 +47,11 @@ It's experimental because it was built to be useful to me first, not to be a fin
|
|
|
45
47
|
| | |
|
|
46
48
|
|---|---|
|
|
47
49
|
| 🔗 **Exact dependency graph** | File-level imports resolved by the TypeScript compiler (aliases, barrels, index files) — not guessed. |
|
|
48
|
-
| 🔁 **Function-level call graph** | Who calls what, symbol to symbol. Toggle between the **Files** and **Functions** views. |
|
|
50
|
+
| 🔁 **Function-level call graph** | Who calls what, symbol to symbol, for TS/JS and Python. Toggle between the **Files** and **Functions** views. |
|
|
49
51
|
| 🧭 **Focus any node** | Click (or search) a file/function → a clean, directional view: callers on the left, dependencies on the right. Big neighbourhoods collapse by directory. |
|
|
50
52
|
| 🧠 **Semantic layer (optional)** | An LLM annotates each file: a summary plus **writes / reads / config / auth / flows** — the meaning the graph can't infer. |
|
|
51
53
|
| 🧾 **Flow-trace** | Aggregates the data footprint across a whole capability: *"this route writes these tables, reads these, is gated by this auth."* |
|
|
54
|
+
| 🧭 **Guided tour** *(new in 0.1.2)* | A suggested reading order for an unfamiliar repo, built from the import graph: foundations first, or entry points first. Step through it in the UI or read `TOUR.md`. |
|
|
52
55
|
| 📓 **Obsidian-linkable vault** | One `.md` per file with `[[wikilinks]]` that are real edges — open the output folder as an Obsidian vault for free. |
|
|
53
56
|
|
|
54
57
|
---
|
|
@@ -64,6 +67,7 @@ Then, in the browser:
|
|
|
64
67
|
1. **Scan** — click **Browse…** to pick a folder (or type/paste a path; `~` works), then **Scan**. The import graph, call graph, and Obsidian vault are written to `<repo>/.codemap`.
|
|
65
68
|
2. **Annotate** *(optional)* — add the semantic layer. Leave the key blank to run locally via **Ollama**, or paste an **API key** + base URL for any OpenAI-compatible provider (Mistral, OpenAI, …).
|
|
66
69
|
3. **Explore** — toggle **Files / Functions**, click a node to focus its neighbourhood and highlight up/downstream paths, search to jump anywhere, and filter by data-flow type.
|
|
70
|
+
4. **Take the tour** — open the **guided tour** panel to step through the repo in reading order, and flip between **foundations-first** and **entry-points-first**.
|
|
67
71
|
|
|
68
72
|
Open the same `.codemap/` folder as an Obsidian vault for the graph view + backlinks.
|
|
69
73
|
Add `.codemap/` to your `.gitignore` if you don't want it committed.
|
|
@@ -103,8 +107,12 @@ bun run codemap scan ./repo -o .codemap # graph + vault, deterministi
|
|
|
103
107
|
ollama pull qwen2.5-coder:7b # one-time, ~4.7 GB
|
|
104
108
|
bun run codemap annotate -o .codemap # local Ollama (default)
|
|
105
109
|
bun run codemap annotate -o .codemap -p mistral # Mistral API (needs CODEMAP_API_KEY)
|
|
110
|
+
bun run codemap onboard ./repo -o .codemap # guided reading order → .codemap/TOUR.md
|
|
111
|
+
bun run codemap onboard ./repo --order entrypoints # …or start from the entry points
|
|
106
112
|
```
|
|
107
113
|
|
|
114
|
+
From npm, swap `bun run codemap` for `bunx codeflowmap` (e.g. `bunx codeflowmap onboard ./repo`).
|
|
115
|
+
|
|
108
116
|
Annotations are cached by file-content hash under `.codemap/.cache`, so re-runs only re-send changed files.
|
|
109
117
|
|
|
110
118
|
</details>
|
|
@@ -139,9 +147,10 @@ Env overrides: `CODEMAP_PROVIDER`, `CODEMAP_MODEL`, `CODEMAP_BASE_URL`, `CODEMAP
|
|
|
139
147
|
| ✅ | Function-level call graph for TS/JS (**Functions** view) | done |
|
|
140
148
|
| ✅ | LLM annotation — provider-agnostic, local-first | done |
|
|
141
149
|
| ✅ | Web UI (Cytoscape): focus, directory grouping, flow-trace | done |
|
|
142
|
-
|
|
|
150
|
+
| ✅ | Function-level call edges for Python (resolved through imports) | done |
|
|
151
|
+
| ✅ | Guided tour / repo onboarding (`onboard` + web tour) | done |
|
|
143
152
|
|
|
144
|
-
> **Early / experimental** — interfaces and output format may change.
|
|
153
|
+
> **Early / experimental** — interfaces and output format may change. Function-level call edges now cover both TS/JS and Python; Python calls are resolved through imports (including packages under a source root such as `src/`) and verified against the target file's symbols.
|
|
145
154
|
|
|
146
155
|
---
|
|
147
156
|
|
|
@@ -153,10 +162,31 @@ bun install
|
|
|
153
162
|
bun run codemap serve # runs from source; builds the UI on first run
|
|
154
163
|
```
|
|
155
164
|
|
|
156
|
-
Monorepo (Bun workspaces): `packages/core` (graph extraction) · `packages/annotate` (LLM layer) · `packages/cli` (
|
|
165
|
+
Monorepo (Bun workspaces): `packages/core` (graph extraction) · `packages/annotate` (LLM layer) · `packages/cli` (`serve`, `scan`, `annotate`, `onboard`) · `packages/web` (Cytoscape UI). `bun run build:pkg` assembles the publishable npm package into `pkg/`.
|
|
157
166
|
|
|
158
167
|
---
|
|
159
168
|
|
|
160
169
|
## License
|
|
161
170
|
|
|
162
171
|
[MIT](LICENSE) © 2026 Brian Mangano
|
|
172
|
+
|
|
173
|
+
---
|
|
174
|
+
|
|
175
|
+
## Changelog
|
|
176
|
+
|
|
177
|
+
### 0.1.2
|
|
178
|
+
|
|
179
|
+
Folds in a guided reading order for dropping into an unfamiliar repo, built on the same dependency graph asked a different question. Python also gains function-level call edges.
|
|
180
|
+
|
|
181
|
+
- **Guided tour / repo onboarding.** `codemap onboard <dir>` writes a `TOUR.md` reading order, and the web UI gains a guided-tour panel that steps through the repo stop by stop. The order is derived from the import graph — cycles folded, dependencies introduced before the files that use them — with a **foundations-first ↔ entry-points-first** toggle for two ways to tell the story.
|
|
182
|
+
- **Python function-level call edges.** The **Functions** view now works for Python. Calls are resolved through imports and verified against the target file's declared symbols, so edges stay exact rather than guessed.
|
|
183
|
+
- **Python source-root import resolution.** Absolute imports for packages living under a source root (e.g. `backend/src/myapp/…`) now resolve by suffix-matching the scanned file set — fixing both import and call edges for "src layout" projects.
|
|
184
|
+
- **Housekeeping.** Fixed a few bugs, removed a couple of dependencies (`zod` is replaced by a small built-in check on model output, and `@types/cytoscape` is no longer needed), and bumped a few others to clear some security advisories. `bun audit` is now clean.
|
|
185
|
+
|
|
186
|
+
**NOTE** Repos analysed before 0.1.2 need a fresh scan to surface the Guided Tour and Python call edges as both come from static analysis. A re-scan rewrites graph.json and clears existing summaries, so re-run annotate afterwards to restore them (cached by file content, so it's cheap).
|
|
187
|
+
|
|
188
|
+
### 0.1.1
|
|
189
|
+
- Packaging and security hardening: the local server is loopback-only with a Host/Origin guard against DNS-rebinding and cross-origin requests.
|
|
190
|
+
|
|
191
|
+
### 0.1.0
|
|
192
|
+
- Initial release: deterministic import graph + function-level call graph (TS/JS) via the TypeScript compiler, tree-sitter Python extractor (imports + symbols), provider-agnostic LLM annotation (local-first), Cytoscape web UI, and Obsidian-linkable vault.
|