codeblast 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 codeblast contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,117 @@
+<p align="center">
+  <img src="assets/readme/hero.svg" width="100%" alt="codeblast — deterministic code graph: know what breaks before you merge"/>
+</p>
+
+<p align="center">
+  <b>English</b> | <a href="README.zh-CN.md">简体中文</a>
+</p>
+
+<p align="center">
+  <a href="#the-three-queries"><img src="https://img.shields.io/badge/TypeScript-function--level-3178c6?style=flat-square" alt="TypeScript function-level"/></a>
+  <a href="#the-precision-promise-bounded-and-evidence-backed"><img src="https://img.shields.io/badge/recall-28%2F28_%3D_100%25-3fb950?style=flat-square" alt="mutation-tested recall 100%"/></a>
+  <a href="SKILL.md"><img src="https://img.shields.io/badge/Agent-Skill-7c3aed?style=flat-square" alt="agent skill"/></a>
+  <img src="https://img.shields.io/badge/license-MIT-8b949e?style=flat-square" alt="MIT"/>
+</p>
+
+**codeblast parses your repository into a deterministic code graph and answers the three most expensive questions around any code change:**
+> 🔗 **[Live interactive demo](https://alloevil.github.io/codeblast/)** — real architecture maps of tRPC / Tabby / sgp, with three-level drill-down
+
+| | Question | Command |
+|---|---|---|
+| 🎯 | **What breaks if I change this?** | `impact` — direct / transitive / affected-tests, in three tiers |
+| 🔍 | **What did this PR structurally change?** | `change` — symbols and dependency edges added, removed, renamed |
+| 🗺️ | **What does this project look like?** | `archmap` — collapsible module map + circular-dependency detection |
+
+Built for humans (CLI / interactive HTML / PR comments) and for AI agents ([SKILL.md](SKILL.md)) — one graph, two front-ends.
+<table>
+  <tr>
+    <td width="50%">
+      <a href="https://alloevil.github.io/codeblast/trpc-impact-demo.html">
+        <img src="assets/readme/impact-overlay.png" alt="Impact blast radius painted on the tRPC architecture map: red = direct callers, amber = affected tests, purple = transitive"/>
+      </a>
+      <p align="center"><sub><b>Impact overlay</b> — blast radius on the map (tRPC · <a href="https://alloevil.github.io/codeblast/trpc-impact-demo.html">live ↗</a>)</sub></p>
+    </td>
+    <td width="50%">
+      <a href="https://alloevil.github.io/codeblast/tabby-arch.html">
+        <img src="assets/readme/arch-hover.png" alt="Tabby architecture map with hover highlighting: all edges into tabby-core lit up"/>
+      </a>
+      <p align="center"><sub><b>Architecture map</b> — hover lights the dependency fan-in (Tabby, 60k★ · <a href="https://alloevil.github.io/codeblast/tabby-arch.html">live ↗</a>)</sub></p>
+    </td>
+  </tr>
+</table>
+
+```bash
+npx codeblast demo            # build a graph of the current repo, run one impact query, emit the map
+npm i -g codeblast            # or install globally; needs Node ≥ 22.13 (built-in sqlite) or Bun
+
+# Install as an agent skill (Claude Code, Codex, Cursor, and 14 more harnesses)
+npx skills add alloevil/codeblast
+```
+
+## Why not yet another LLM diagram tool
+
+```
+LLM diagrams:  code → model reads it → hand-drawn graph → render     graph = the model's opinion, unverifiable
+codeblast:     code → deterministic tsc/AST parse → graph → project  graph = checkable facts
+```
+
+**Every node, every edge, every claim carries `file:line` evidence** you can open and verify.
+The LLM does exactly one job in the pipeline: giving modules human-readable names — node membership and edges always come from static analysis.
+
+## The three queries
+
+```bash
+# Build the graph: auto-detects TS monorepos / Python, hash-based incremental updates
+# (full build of tRPC, 950 files, in ~20s)
+codeblast index <repo> --db graph.db
+
+# ① Impact — check the blast radius before you change anything
+codeblast impact graph.db "createOrder" --json
+#    → direct list = callsites you must review; tests list = tests you must run
+#    → two channels: call-graph reachable (precision ~0.70, read first)
+#      + import reachable (conservative supplement, don't skip)
+
+# ② Change Map — structural diff between two refs
+codeblast change <repo> main~5 main --json
+#    → unexpected edges_added = a signal the change is out of scope
+
+# ③ Architecture Map — interactive HTML: module → file → symbol drill-down,
+#    symbols link to source lines
+codeblast archmap graph.db --out arch.html --repo-url <github-url>
+
+# Optional: mine git co-change coupling (protocol pairs, config + consumers —
+# edges static analysis can't see)
+codeblast cochange <repo> graph.db
+```
+
+### PR bot (runs in CI, stays quiet by default)
+
+Copy [`.github/workflows-template/codeblast.yml`](.github/workflows-template/codeblast.yml) into your repo (it runs `npx codeblast pr-comment`, no other setup):
+every PR gets an automatic comment with structural changes + blast radius + new symbols with no test coverage; **PRs with no structural change get zero comments**.
+Replayed against 50 real commits: 42 correctly stayed silent, 87.5% of comments were useful.
+
+## The precision promise (bounded, and evidence-backed)
+
+- **TypeScript at function level: zero missed impact within statically analyzable scope.** Verified by mutation testing:
+  inject mutations into a real repo → run the full test suite to get the ground-truth impact set → compare against predictions.
+  Current benchmark (tRPC, 950 files): **28/28 mutations, 100% recall**, average precision 0.36 — favoring
+  false positives over false negatives is a deliberate trade: in a controlled experiment, dropping the conservative edges
+  raises precision to 0.70 but recall collapses to 14%. Data lives in [`eval/`](eval/).
+- **Blind spots are explicitly flagged.** A blind spot is any call or import that static analysis cannot resolve to an in-repo target — dynamic calls, unresolved calls, failed external-dependency resolution, subprocess boundaries, test-framework globals — not just dynamic calls; each is recorded in `blind_spots` with an "impact may be underestimated" warning, never silently dropped.
+- **Python is file-level.** Dynamic typing makes function-level zero-miss guarantees impossible in principle, and we don't pretend otherwise.
+
+## For AI agents
+
+```
+before editing:  impact "symbol" --json    → callsite list into context, so nothing gets missed
+after editing:   change HEAD~1 HEAD --json → self-check for scope creep and accidental deletions
+```
+
+The full contract and interpretation discipline (including "never pretend the blind-spot list is complete") is in [SKILL.md](SKILL.md).
+Agent conventions: [AGENTS.md](AGENTS.md).
+
+## Status & roadmap
+
+M0 graph engine → M1 Impact → M3 architecture map → M4 graph diff + PR bot → M5 precision extensions — **all milestones accepted** (each with a reproducible acceptance script). Single source of truth for design and acceptance criteria: [intent.md](intent.md).
+
+MIT © 2026

package/README.zh-CN.md

@@ -0,0 +1,89 @@
+<p align="center">
+  <img src="assets/readme/hero.svg" width="100%" alt="codeblast — deterministic code graph: know what breaks before you merge"/>
+</p>
+
+<p align="center">
+  <a href="README.md">English</a> | <b>简体中文</b>
+</p>
+
+<p align="center">
+  <a href="#三个查询"><img src="https://img.shields.io/badge/TypeScript-函数级-3178c6?style=flat-square" alt="TypeScript function-level"/></a>
+  <a href="#精度承诺有边界有证据"><img src="https://img.shields.io/badge/recall-28%2F28_%3D_100%25-3fb950?style=flat-square" alt="mutation-tested recall 100%"/></a>
+  <a href="SKILL.md"><img src="https://img.shields.io/badge/Agent-Skill-7c3aed?style=flat-square" alt="agent skill"/></a>
+  <img src="https://img.shields.io/badge/license-MIT-8b949e?style=flat-square" alt="MIT"/>
+</p>
+
+**codeblast 把仓库解析成一份确定性代码图谱，回答改代码前后最贵的三个问题：**
+> 🔗 **[在线交互演示](https://alloevil.github.io/codeblast/)** — tRPC / Tabby / sgp 的实时架构图,点开即可三层下钻
+
+| | 问题 | 命令 |
+|---|---|---|
+| 🎯 | **改这个会炸哪里？** | `impact` — 直接/传递/受影响测试三级清单 |
+| 🔍 | **这个 PR 在结构上改了什么？** | `change` — 符号与依赖边的增删/重命名 |
+| 🗺️ | **这个项目长什么样？** | `archmap` — 模块折叠图 + 循环依赖检测 |
+
+给人看（CLI / 交互 HTML / PR 评论），也给 AI agent 用（[SKILL.md](SKILL.md)）——同一份图谱，两个出口。
+
+## 为什么不是又一个 LLM 画图工具
+
+```
+LLM 画图:    代码 → 模型阅读理解 → 手写图 → 渲染        图 = 模型的观点，无法核对
+codeblast:   代码 → tsc/AST 确定性解析 → 图谱 → 投影    图 = 可验证的事实
+```
+
+**每个节点、每条边、每句结论都带 `file:line` 证据**，可直接打开核对。
+LLM 在管线里只做一件事：给模块起人话名字——节点归属和边永远来自静态分析。
+
+## 三个查询
+
+```bash
+# 建图：TS monorepo / Python 自动识别，hash 增量更新（tRPC 950 文件全量 ~20s）
+codeblast index <repo> --db graph.db
+
+# ① Impact —— 改动前查影响半径
+codeblast impact graph.db "createOrder" --json
+#    → direct 清单 = 必须检查的 callsite；tests 清单 = 必须跑的测试
+#    → 双通道：调用链可达（精确率 ~0.70,优先看）+ import 可达（保守补充,勿跳过）
+
+# ② Change Map —— 两个 ref 之间的结构 diff
+codeblast change <repo> main~5 main --json
+#    → 意料之外的 edges_added = 改动越界信号
+
+# ③ Architecture Map —— 交互 HTML：模块→文件→符号三层下钻，符号跳源码行
+codeblast archmap graph.db --out arch.html --repo-url <github-url>
+
+# 可选：git 历史耦合挖掘（协议两端、配置与消费者——静态分析看不见的边）
+codeblast cochange <repo> graph.db
+```
+
+### PR bot（CI 内跑，宁静默不刷屏）
+
+复制 [`.github/workflows-template/codeblast.yml`](.github/workflows-template/codeblast.yml) 到目标仓库：
+每个 PR 自动评论结构变化 + 影响半径 + 无测试覆盖的新增符号；**无结构变化的 PR 零评论**。
+50 个真实提交回放：42 个正确静默、评论有效率 87.5%。
+
+## 精度承诺（有边界，有证据）
+
+- **TypeScript 函数级，静态可分析范围内零漏报。** 验收方法：变异测试对照
+  （真实仓库注入变异 → 全量测试得真实影响集 → 对比预测）。当前基准（tRPC，950 文件）：
+  **28/28 变异召回率 100%**，平均精确率 0.36——宁误报不漏报是刻意交换：
+  对照实验中砍掉保守边可将精确率提到 0.70，但召回率跌至 14%。数据在 [`eval/`](eval/)。
+- **盲区显式标注。** 盲区 = 静态无法解析到仓内目标的调用/导入（含动态调用、未解析调用、外部依赖解析失败、子进程边界、测试框架全局），并非只有动态调用；
+  一律记入 blind_spots 并提示"影响可能被低估"，绝不静默丢弃。
+- **Python 为文件级。** 动态类型使函数级零漏报原理性不成立，不假装做到。
+
+## 给 AI Agent 用
+
+```
+改前:  impact "symbol" --json   → callsite 清单进上下文，防漏改
+改后:  change HEAD~1 HEAD --json → 自查结构越界与意外删除
+```
+
+完整契约与解读纪律（含"禁止假装盲区清单完整"）见 [SKILL.md](SKILL.md)。
+Agent 规范另见 [AGENTS.md](AGENTS.md)。
+
+## 状态与路线
+
+M0 图谱引擎 → M1 Impact → M3 架构图 → M4 图 diff + PR bot → M5 精度扩展，**全部验收通过**（每项含可复现验收脚本）。方案与验收标准的单一事实源：[intent.md](intent.md)。
+
+MIT © 2026

package/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: codeblast
+description: Deterministic code-graph analysis for TypeScript and Python repositories. Use when the user asks what breaks if I change this, wants an impact analysis or blast radius before editing a symbol, asks for a repository architecture map grounded in real code, or wants to know what structurally changed between two git refs or in a PR. Unlike LLM-drawn diagrams, every node and edge is extracted by compiler-grade static analysis and carries file:line evidence; impact answers are conservative (no false negatives within the static analysis boundary; dynamic blind spots are explicitly reported, never silently dropped).
+---
+
+# codeblast — impact · change · architecture, with evidence on every edge
+
+Three deterministic queries over a graph built by `tsc` (TypeScript, function-level) and the
+Python AST (file-level with typed-call upgrades). Every result carries the `file:line` where the
+dependency actually occurs. The graph comes from the code, not from a model's reading of it.
+
+## When to run it
+
+| Situation | Command | What you get back |
+|---|---|---|
+| About to edit an exported symbol | `codeblast impact <db> "<symbol>" --json` | The callsites you must review and the tests you must run |
+| Finished a multi-file change; verifying scope | `codeblast change <repo> HEAD~1 HEAD --json` | Symbols and dependency edges added / removed / renamed |
+| Need to understand an unfamiliar repo | `codeblast archmap <db> --out arch.html` | Module → file → symbol map with cycle detection |
+| Reviewing a PR | `codeblast pr-comment <repo> <base> <head>` | Markdown review comment; empty output when nothing structural changed |
+
+Prerequisites: Node ≥ 22.13 or Bun ≥ 1.0 (`npx codeblast` works with no install); `python3` for Python
+repos; the target repo's dependencies installed (missing `node_modules` turns external calls into blind spots).
+
+## Interpretation rules — read before running
+
+These are the mistakes an agent makes with this tool. Each one has produced a wrong answer in practice.
+
+1. **Never present the impact list as complete when `blind_spot_count > 0`.** A blind spot is any call or
+   import static analysis could not resolve to an in-repo target: dynamic calls, unresolved calls, failed
+   external resolution, subprocess boundaries, test-framework globals. Say "impact may be underestimated".
+2. **Never drop the `file` channel to make the list shorter.** Items with `channel: "call"` are the
+   high-confidence core (measured precision ≈ 0.70). Items with `channel: "file"` reach the target only
+   through import / re-export edges. Cutting them raised precision but collapsed recall from 100% to 14%
+   in a controlled run — tests often call the target from inside anonymous callbacks the call graph
+   cannot see. Use `call` items as what to read first; use the full list as what to test.
+3. **Never claim function-level precision for Python.** Python is file-level with typed-call upgrades;
+   there is no zero-miss promise. Say so when reporting on a Python repo.
+4. **`truncated: true` means the impact is wide** (over `--max`, default 500). Recommend the full test
+   suite; do not enumerate a partial list as if it were the whole.
+5. **`co_change_hints` are not impact.** They are files that historically changed together with the
+   target but have no static edge (protocol pairs, config + consumer). Report them as "historically
+   co-changed, worth a look", never as "affected".
+6. **Cite `via_file:via_line`** when you tell the user something depends on the target. That is the
+   real location of the dependency and can be opened to check.
+7. **This is not a diagram generator.** `archmap` outputs facts for navigation. For a presentation
+   diagram, feed its JSON to a rendering tool; do not ask codeblast to make it pretty.
+
+## 1. Build the graph (required first; incremental afterwards)
+
+```bash
+codeblast index <repo-root> --db /tmp/graph.db
+```
+
+Auto-discovers every package `tsconfig.json` in a monorepo and ingests Python via AST. Re-running only
+processes files whose content hash changed. Stdout is one JSON object:
+
+```json
+{ "db": "...", "seconds": 19.4, "tsconfigs": 12, "files_indexed": 950, "files_skipped": 0,
+  "nodes": 14200, "edges": 31800, "blind_spots": 412, "failures": 0 }
+```
+
+Non-zero exit with `failures > 0` means the graph is incomplete — do not query it; report the failure.
+
+## 2. Impact — what breaks if I change this
+
+```bash
+codeblast impact /tmp/graph.db "<symbol-name | full-id | file-path>" --json [--max 500]
+```
+
+Target forms: a bare symbol name (if ambiguous, the command lists candidates and exits 1 — pick the
+full id and re-run), a full id `path/to/file.ts#Symbol` or `path/to/file.ts#Class.method`, or a file
+path relative to the repo root.
+
+Output (`--json`):
+
+```ts
+{
+  target: string;                 // resolved full id
+  truncated: boolean;             // hit --max; impact is wide
+  blind_spot_count: number;       // unresolved calls/imports in the target's file (rule 1)
+  items: Array<{
+    id: string; name: string; kind: string; file: string; line: number;
+    level: "direct" | "indirect" | "tests";   // 1 hop | 2+ hops | a test that reaches the target
+    hops: number;
+    confidence: "exact" | "conservative";     // weakest edge on the path; conservative = interface fan-out etc.
+    channel: "call" | "file";                 // rule 2
+    named_miss?: boolean;                     // file channel only: an import on the path did not name the target
+    via_file: string; via_line: number;       // where the dependency occurs (rule 6)
+  }>;
+  co_change_hints: Array<{ file: string; co_commits: number; evidence: string }>;  // rule 5
+}
+```
+
+How to use it: `items.filter(level === "direct")` is the callsite checklist. `items.filter(level ===
+"tests")` de-duplicated by `file` is the test set to run. Test-directory fixtures are included
+conservatively; estimate test cost by distinct files, not item count.
+
+`co_change_hints` is populated only after `codeblast cochange <repo> /tmp/graph.db` (optional).
+
+## 3. Change — what structurally changed between two refs
+
+```bash
+codeblast change <repo-root> <ref-a> <ref-b> --json
+codeblast change --dbs <a.db> <b.db> --json        # two graphs already built
+```
+
+Output when nothing structural changed: `{ "range": "...", "structural_changes": 0 }`. Otherwise:
+
+```ts
+{
+  range: string; structural_changes: number;
+  nodes_added: Node[]; nodes_removed: Node[];          // Node = { id, kind, name, file, line }
+  renamed: Array<{ from, to, file, kind }>;             // matched rename, not counted as add + remove
+  edges_added: Edge[]; edges_removed: Edge[];           // Edge = { src, dst, kind, file, line }
+  modules: Record<string, { added, removed, renamed, edgesIn, edgesOut }>;
+  impact: Array<{ symbol, kind, impact_nodes, affected_tests, truncated }>;   // per added/renamed symbol
+}
+```
+
+Self-check after an edit: an unexpected entry in `edges_added` is a new dependency the task did not call
+for; a non-empty `nodes_removed` under a "pure refactor" means something was dropped.
+
+## 4. Architecture map
+
+```bash
+codeblast mermaid /tmp/graph.db                                   # Mermaid, for PR descriptions / docs
+codeblast archmap /tmp/graph.db --out arch.html --repo-url <github-blob-url>   # interactive HTML
+codeblast archmap head.db --impact "<symbol>" --out impact.html   # blast radius painted on the map
+codeblast archmap head.db --diff base.db --out change.html        # structural diff painted on the map
+```
+
+Modules collapse by top-level directory; circular dependencies are drawn as red dashed edges; each
+module shows its blind-spot count. The HTML drills module → file → symbol, and symbols link to source
+lines when `--repo-url` is given. `--overlay codeblast.overlay.json` renames / merges / hides modules
+(the file is meant to be committed; the map's ✎ mode generates it).
+
+## 5. PR comment (CI)
+
+```bash
+codeblast pr-comment <repo> <base-sha> <head-sha> [--repo-url <url>]
+```
+
+Exit 0 with empty stdout when there is nothing structural to say — the workflow template in
+`.github/workflows-template/codeblast.yml` posts a sticky comment only when stdout is non-empty.
+Replayed over 50 real commits: 42 stayed silent, 87.5% of the comments posted were judged useful.
+
+## Precision, stated
+
+- TypeScript, function level: **zero missed impact within statically analyzable scope**, checked by
+  mutation testing (inject a fault, run the real test suite, compare failing tests to the prediction).
+  tRPC benchmark, 950 files: 28/28 mutations recalled, precision 0.36 overall / ≈ 0.70 on the call channel.
+  The weekly acceptance workflow re-runs this and opens an issue if recall drops below 100%.
+- Conservative edges over-approximate on purpose (an interface method call fans out to every implementer).
+- Python: file-level; typed calls (`b = Builder(); b.method()`, annotated parameters) are function-level;
+  untyped attribute chains fall back to file level and are recorded as blind spots.