codeflowmap 0.1.0

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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Brian Mangano
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md ADDED
@@ -0,0 +1,137 @@
1
+ # code-mapper
2
+
3
+ Map your codebase's **dependencies** and **data flows** (writes / reads / auth) into an
4
+ Obsidian-linkable Markdown vault, with a web UI to navigate and highlight paths.
5
+
6
+ > Open source (MIT). Hybrid architecture: deterministic static analysis builds the graph,
7
+ > an open-weight LLM adds the semantic layer.
8
+ >
9
+ > ⚠️ **Early / experimental** — interfaces and output format may change.
10
+
11
+ ## Why this exists
12
+
13
+ I wanted to get better at reading code I didn't write. Two kinds, really. The first: understanding the code an LLM wrote for me. Generating it is the fast part. Getting across what it actually did (what it touched, what it reads and writes, whether the auth path is where I think it is) was the gap I needed to fix. This tool is my way of improving the verification step. Generate, then graph it and see what's really there.
14
+
15
+ 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.
16
+
17
+ 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.
18
+
19
+
20
+ ## Requirements
21
+
22
+ - [Bun](https://bun.sh) ≥ 1.0 — the runtime (the tool uses Bun's built-in server).
23
+ - *(optional, for the annotation layer)* a local [Ollama](https://ollama.com) install, or a
24
+ Mistral / OpenAI API key. The graph itself needs no model.
25
+
26
+ ## Install
27
+
28
+ No clone needed:
29
+
30
+ ```bash
31
+ bunx codeflowmap serve # opens http://localhost:4321
32
+ ```
33
+
34
+ Then, in the browser: **Browse** to a repo → **Scan** → explore. Optionally paste a Mistral API
35
+ key and click **Annotate** for the semantic layer. (See [Usage](#usage) for the full walkthrough.)
36
+
37
+ ## How it works
38
+
39
+ ```
40
+ AST / static analysis → import graph + function-level call graph (deterministic, no tokens)
41
+ ↓
42
+ LLM annotation → writes / reads / auth / flows (provider-agnostic; default: local Ollama)
43
+ ↓
44
+ Markdown vault → one .md per file, [[wikilinks]] = real edges (link into Obsidian)
45
+ ↓
46
+ Web UI → Files / Functions views, highlight up/downstream paths, filter by flow
47
+ ```
48
+
49
+ ## Status
50
+
51
+ | Phase | What | State |
52
+ |-------|------|-------|
53
+ | 1 | Core graph (TS/JS via ts-morph) → `graph.json` + Obsidian vault | ✅ |
54
+ | 2 | Tree-sitter Python extractor (imports + symbols, AST-accurate) | ✅ |
55
+ | 3 | LLM annotation pass (provider-agnostic, local-first via Ollama) | ✅ |
56
+ | 4 | Vite + React web UI over `graph.json` | ✅ |
57
+ | 5 | Function-level call graph for TS/JS (`Functions` view) | ✅ |
58
+
59
+ Python currently contributes import edges + symbols; function-level call edges are TS/JS only.
60
+
61
+ ## Usage
62
+
63
+ Everything runs from the browser. The only command is launching the UI (`bunx codeflowmap serve`,
64
+ or `bun run codemap serve` from a source checkout). Then, in the browser:
65
+
66
+ 1. **Scan** — click **Browse…** to pick a folder (or type/paste a path; `~` works), then **Scan**.
67
+ The import graph, call graph, and Obsidian vault are written to `<repo>/.codemap`.
68
+ 2. **Explore** — toggle **Files / Functions**, click a node to highlight its up/downstream (or
69
+ caller/callee) paths, search, and filter by data-flow type.
70
+ 3. **Annotate** *(optional)* — paste a **Mistral API key**, click **Annotate** to add the semantic
71
+ layer (summary + writes/reads/auth/flows). The key is held in memory and sent only to your local
72
+ server, which calls Mistral and writes the result back to the vault — never stored in the browser
73
+ or on disk.
74
+
75
+ Open the same `.codemap/` folder as an Obsidian vault for the graph view + backlinks.
76
+ Add `.codemap/` to your `.gitignore` if you don't want it sent to the cloud...
77
+
78
+ ### Scriptable / CI (optional)
79
+
80
+ The same operations are plain CLI commands, for automation or a local-model workflow:
81
+
82
+ ```bash
83
+ bun run codemap scan ./repo -o .codemap # graph + vault, deterministic, no tokens
84
+ ollama pull qwen2.5-coder:7b # one-time, ~4.7 GB
85
+ bun run codemap annotate -o .codemap # local Ollama (default)
86
+ bun run codemap annotate -o .codemap -p mistral # Mistral API (needs CODEMAP_API_KEY)
87
+ ```
88
+
89
+ ### Annotation providers
90
+
91
+ Annotation hits a real model. Configured by flags or environment; secrets are **read only** from
92
+ the environment and are never written to the vault, `graph.json`, the cache, or logs.
93
+
94
+ > ⚠️ **Data egress:** annotating sends the **full contents of every scanned file** to the
95
+ > configured provider. With `mistral` / `openai` (or any remote `--base-url`) that means your
96
+ > source code leaves the machine and is processed by a third party — do not annotate
97
+ > proprietary or sensitive code against a remote provider without authorization. For a fully
98
+ > local workflow that sends nothing off-box, use the default `ollama` provider.
99
+
100
+ | Provider | Endpoint | Default model | Key |
101
+ |----------|----------|---------------|-----|
102
+ | `ollama` (default) | `http://localhost:11434/v1` | `qwen2.5-coder:7b` | none (local) |
103
+ | `mistral` | `https://api.mistral.ai/v1` | `devstral-small-2512` | `CODEMAP_API_KEY` / `MISTRAL_API_KEY` |
104
+ | `openai` | `https://api.openai.com/v1` | `gpt-4o-mini` | `CODEMAP_API_KEY` / `OPENAI_API_KEY` |
105
+
106
+ Env overrides: `CODEMAP_PROVIDER`, `CODEMAP_MODEL`, `CODEMAP_BASE_URL`, `CODEMAP_API_KEY`.
107
+ Any OpenAI-compatible endpoint works via `--base-url`. Annotations are cached by file-content
108
+ hash under `.codemap/.cache`, so re-runs only re-send changed files.
109
+
110
+ **Model sizing:** `qwen2.5-coder:7b` (~4.7 GB, Apache-2.0) is the default because it runs on a
111
+ 16 GB laptop and the per-file task doesn't need more. For higher-quality summaries on a 32 GB+
112
+ machine, use `-m devstral` (24B). For 8 GB, `-m qwen2.5-coder:3b`.
113
+
114
+ ## Design notes
115
+
116
+ - **Graph edges are never inferred by the LLM** — imports come from real module resolution and
117
+ call edges from symbol resolution (TypeScript Compiler API), so they're exact, free, and
118
+ CI-reproducible. The LLM only adds the semantic layer.
119
+ - **The LLM is provider-agnostic** behind one `Annotator` interface. Default is local, open-weight
120
+ **Qwen2.5-Coder 7B** (Apache-2.0) via Ollama; Mistral / OpenAI / any OpenAI-compatible endpoint
121
+ are drop-in alternatives via `--provider` / `--base-url`.
122
+
123
+ ## Development
124
+
125
+ ```bash
126
+ git clone https://github.com/man-consult/code-mapper.git && cd code-mapper
127
+ bun install
128
+ bun run codemap serve # runs from source; rebuilds the UI on first run
129
+ ```
130
+
131
+ Monorepo layout (Bun workspaces): `packages/core` (graph extraction), `packages/annotate`
132
+ (LLM layer), `packages/cli` (the `serve` command), `packages/web` (Cytoscape UI).
133
+ `bun run build:pkg` assembles the publishable `code-mapper` package into `pkg/`.
134
+
135
+ ## License
136
+
137
+ [MIT](LICENSE) © 2026 Brian Mangano