npm - codeblast - Versions diffs - 0.3.2 → 0.3.4 - Mend

codeblast 0.3.2 → 0.3.4

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.

Files changed (5) hide show

package/README.md CHANGED Viewed

@@ -1,4 +1,4 @@
-**codeblast** is a deterministic code-graph CLI for TypeScript and Python repositories that tells developers and AI agents what breaks before a change is merged.
+**codeblast** is the pre-merge blast-radius check for TypeScript monorepos and AI coding agents. It tells you what to review, which tests to run, and when the graph is incomplete — with a source line for every reported edge.
 <p align="center">
   <img src="assets/readme/hero.svg" width="100%" alt="codeblast — deterministic code graph: know what breaks before you merge"/>
@@ -15,6 +15,29 @@
   <img src="https://img.shields.io/badge/license-MIT-8b949e?style=flat-square" alt="MIT"/>
 </p>
+## Get value in one pull request
+Copy this workflow into `.github/workflows/codeblast.yml`:
+```yaml
+name: codeblast
+on: pull_request
+permissions:
+  contents: read
+  pull-requests: write
+jobs:
+  codeblast:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with: { fetch-depth: 0 }
+      - uses: alloevil/codeblast@v0.3.3
+```
+On a structural PR, codeblast posts a bounded review decision, affected tests, `file:line` evidence,
+and explicit blind-spot warnings. On a docs-only or otherwise irrelevant PR, it stays silent. It runs
+locally in the runner; source is not uploaded to a codeblast service.
 ## What it is
 **codeblast parses your repository into a deterministic code graph and answers the three most expensive questions around any code change:**
@@ -49,7 +72,7 @@ Built for humans (CLI / interactive HTML / PR comments) and for AI agents ([SKIL
 ```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
-                              # npm serves 0.3.1
+                              # npm serves 0.3.3
 # Install as an agent skill (Claude Code, Codex, Cursor, and 14 more harnesses)
 npx skills add alloevil/codeblast
@@ -57,28 +80,28 @@ npx skills add alloevil/codeblast
 ### As a GitHub Action (one line)
+The smallest useful installation is a PR workflow. Pin the release tag, or pin the commit when your
+repository requires immutable third-party actions:
 ```yaml
-# .github/workflows/codeblast.yml
 name: codeblast
 on: pull_request
 permissions:
   contents: read
   pull-requests: write
 jobs:
-  analyze:
+  codeblast:
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
-        with: { fetch-depth: 0 }      # the analyzer compares base and head commits
-      - uses: alloevil/codeblast@v0.3.1
+        with: { fetch-depth: 0 }
+      - uses: alloevil/codeblast@v0.3.3
 ```
-The action builds the analyzer from the ref you pinned (not from npm, which can lag),
-posts one sticky comment per PR and updates it in place, and stays silent when the diff
-has no structural change. Inputs: `base`, `head`, `repo-url`, `comment` (set to `false`
-to only produce the file); outputs: `has_comment`, `comment_path`. If you prefer to own
-the commenting step, copy [`.github/workflows-template/codeblast.yml`](.github/workflows-template/codeblast.yml)
-instead — it runs the same command with `npx`.
+The action builds the analyzer from the ref you pinned, posts one sticky comment per PR, and stays
+silent when the diff has no structural change. For the full input/output contract, use the
+[workflow template](.github/workflows-template/codeblast.yml).
 ## Why not yet another LLM diagram tool
@@ -122,6 +145,19 @@ codeblast cochange <repo> graph.db
 ```
 ### PR bot (runs in CI, stays quiet by default)
+### Reproducible PR cases
+These are not synthetic diagrams; each case is a committed replay or pilot artifact:
+| Case | Run it | Reviewer takeaway |
+|---|---|---|
+| Function-body behavior change | `codeblast pr-comment <repo> <base> <head>` | A symbol can keep the same shape while its callers still need review. |
+| Exported signature change | `codeblast check-change <repo> <base> <head> --json` | API contraction or signature changes route to targeted review or review. |
+| Incomplete static graph | `codeblast impact <db> <symbol> --json` | `warnings` and `blind_spot_count` prevent an apparently complete answer. |
+The self-pilot record is [`eval/pilot-2026-09-24.json`](eval/pilot-2026-09-24.json): the published
+package indexed this repository with 0 extraction failures and returned separate review-first and test
+guidance. It is evidence that the workflow runs, not a claim of universal accuracy.
 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**.
@@ -129,6 +165,48 @@ Replayed against 50 real commits: 42 correctly stayed silent. Comment usefulness
 four review rounds — rounds 1–3 independent blind review, round 4 by the current model — scored 25% / 75% / 57% / 20% useful, against 7/8 = 87.5% when the
 authoring agent rated its own comments; both numbers and the fixes that followed each round are logged in
 [intent.md](intent.md).
+## Evidence you can rerun
+The headline promise is bounded: TypeScript, within the statically analyzable scope, and measured by
+mutation testing against the real test suite. The committed runs are inspectable under [`eval/`](eval/)
+and every published figure has a machine-readable receipt in [`docs/claims.json`](docs/claims.json).
+| Scenario | Evidence | What it proves |
+|---|---|---|
+| tRPC, 30 injected mutations | [`mutation-2026-08-28-trpc-n30.json`](eval/mutation-2026-08-28-trpc-n30.json) | 28/28 killed mutants recalled; 2 were not killed by the suite |
+| graphql-tools, Jest | [`mutation-2026-09-07-graphql-tools-n10.json`](eval/mutation-2026-09-07-graphql-tools-n10.json) | 10/10 killed mutants recalled across a second workspace layout |
+| Real package pilot | [`pilot-2026-09-24.json`](eval/pilot-2026-09-24.json) | 32 files indexed, 0 extraction failures, guidance separated from repository-wide blind spots |
+The pilot is not a benchmark and does not establish a universal accuracy rate. It is a reproducible
+smoke run of the published package against this repository.
+### A reviewer's decision, not a diagram
+For agents and CI, `check-change --json` returns a routing decision plus evidence:
+```json
+{
+  "decision": "targeted-review",
+  "risk": "medium",
+  "affected_test_files": 3,
+  "blind_spot_count": 0,
+  "graph_health": {"warnings": []}
+}
+```
+### What the numbers do and do not mean
+The 28/28 and 10/10 figures are mutation-testing recall on two pinned repositories. They mean every
+test file that failed for each killed mutation was present in the predicted set **within the measured
+static-analysis boundary**. They do not mean codeblast catches every production regression, understands
+dynamic runtime behavior, or provides function-level guarantees for Python.
+The conservative import/file channel is deliberately retained: a controlled call-only ablation reached
+better precision but recalled only 2/14 killed mutations. Treat `call` items as the first reading list,
+the complete result as the test safety net, and every blind spot as an explicit limit.
+`review` means inspect before merge; it does not mean the tool has proven the change unsafe. A nonzero
+graph failure or an incomplete impact result is a reason to stop and inspect, not a reason to hide the
+uncertainty.
 ## The precision promise (bounded, and evidence-backed)
@@ -174,13 +252,22 @@ safe to merge. `review` is required when API surface contracts, removed symbols,
 results are detected.
 ## For AI agents
-```
+```text
 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
+after editing:   check-change repo base head --json → risk, graph health, affected tests and warnings
 ```
-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).
+The full contract and interpretation discipline (including “never pretend the impact list is complete”)
+is in [SKILL.md](SKILL.md). Agent conventions: [AGENTS.md](AGENTS.md).
+## Help improve the reviewer
+Found a false positive, missed impact, noisy comment, or wrong silence decision? Open a
+[privacy-safe bot feedback issue](https://github.com/alloevil/codeblast/issues/new?template=bot-feedback.yml).
+Share the public PR URL and a redacted explanation; never paste source code, secrets, private diffs,
+or full repository contents. Reproducible benchmark results and pilot evidence belong in [`eval/`](eval/),
+not in issue comments.
 ## FAQ

package/README.zh-CN.md CHANGED Viewed

@@ -33,7 +33,7 @@
 ```bash
 npx codeblast demo            # 给当前仓库建图、跑一次 impact 查询、导出架构图
 npm i -g codeblast            # 或全局安装；需要 Node ≥ 22.13（内置 sqlite）或 Bun
-                              # npm 上的版本是 0.3.1，与本仓库一致
+                              # npm 上的版本是 0.3.3，与本仓库一致
 # 作为 agent skill 安装（Claude Code、Codex、Cursor 等）
 npx skills add alloevil/codeblast

package/SKILL.md CHANGED Viewed

@@ -9,18 +9,79 @@ Three deterministic queries over a graph built by `tsc` (TypeScript, function-le
 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 |
+| About to edit an exported symbol | `codeblast impact <db> "<symbol>" --json` | `guidance.review_first`, `guidance.run_tests`, conservative items and warnings |
 | Finished a multi-file change; verifying scope | `codeblast change <repo> HEAD~1 HEAD --json` | Symbols and dependency edges added / removed / renamed |
+| Need one merge-safety decision | `codeblast check-change <repo> <base> <head> --json` | Risk, decision, graph health, affected tests and recommended actions |
 | 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).
+Recommended agent loop:
+```text
+1. index the repository and check `failures == 0`
+2. before editing: read `impact --json` and start with `guidance.review_first`
+3. make the change
+4. run `check-change --json` against base and head
+5. run distinct files from `guidance.run_tests` / `affected_test_files`
+6. report `warnings`, blind spots, and every `via_file:via_line` evidence location
+```
+Never turn a `safe-to-review` routing result into “safe to merge”; the command routes attention and
+`check-change --json` has `schema_version: "1"` and `engine_version`. Its exit codes are stable:
+- `0`: analysis completed with no high-risk or graph-health warning;
+- `1`: analysis completed but routes the change to review (`high` risk or incomplete graph);
+- `2`: command, repository, worktree, or graph construction error.
+`impact --json` also has `schema_version: "1"`; every guidance array is de-duplicated and sorted for
+stable agent diffs. Treat the schema version as a compatibility boundary, not as a prose suggestion.
+Machine-readable compatibility contract:
+```text
+impact --json: schema_version=1, guidance arrays sorted and de-duplicated
+check-change --json: schema_version=1, engine_version, decision, risk, graph_health
+exit 0: result complete and no high-risk routing
+exit 1: result complete but review routing is required
+exit 2: analysis or repository error; do not consume the result as evidence
+```
+When a future schema version appears, stop and read its contract before making decisions from fields
+that are not explicitly understood. Do not silently fall back to prose parsing.
+The formal schemas are committed at [`eval/check-change.schema.json`](eval/check-change.schema.json)
+and [`eval/impact.schema.json`](eval/impact.schema.json). Version policy: within schema version `1`,
+new optional fields may be added, but existing field meanings, enum values, array ordering, and exit
+codes remain stable. A breaking field removal, type change, or enum change requires a new schema
+version and an explicit migration note. Consumers must reject unknown schema versions rather than
+guessing.
+The supported agent-facing artifacts are the two version-one JSON contracts and the smoke command:
+`bun run agent-smoke` (or `node eval/agent-workflow-smoke.mjs` after building). A consumer integration
+should fail closed when the schema version is unknown, and should preserve the complete JSON artifact
+alongside its human summary for later review.
+Continuous evolution outputs:
+```bash
+bun run release-smoke          # package install and executable surface
+bun run agent-smoke            # end-to-end safety JSON contract
+bun run pilot-summary          # committed pilot graph/impact summary
+bun run guidance-stability     # deterministic guidance sample
+bun run validate-compatibility # compatibility sample boundary check
+```
+Each command should either produce a small machine-readable result or fail. Keep the result with the
+release or compatibility evidence; a green test suite without a current evidence sample is not a
+complete evolution cycle.
+tests. The graph health and warning fields are part of the contract.
 ## Interpretation rules — read before running
 These are the mistakes an agent makes with this tool. Each one has produced a wrong answer in practice.

package/dist/bin.js CHANGED Viewed

@@ -238,15 +238,30 @@ class Extractor {
   rel(fileName) {
     return path.relative(this.rootDir, fileName);
   }
+  safeSymbolAt(node) {
+    try {
+      return this.checker.getSymbolAtLocation(node);
+    } catch {
+      return;
+    }
+  }
+  safeAliased(symbol) {
+    if (!(symbol.flags & ts.SymbolFlags.Alias))
+      return symbol;
+    try {
+      return this.checker.getAliasedSymbol(symbol);
+    } catch {
+      return symbol;
+    }
+  }
   collectImplementers() {
     for (const sf of this.sourceFiles()) {
       const visit = (node) => {
         if (ts.isClassDeclaration(node) && node.heritageClauses) {
           for (const clause of node.heritageClauses) {
             for (const typeNode of clause.types) {
-              let sym = this.checker.getSymbolAtLocation(typeNode.expression);
-              if (sym && sym.flags & ts.SymbolFlags.Alias)
-                sym = this.checker.getAliasedSymbol(sym);
+              const raw = this.safeSymbolAt(typeNode.expression);
+              const sym = raw ? this.safeAliased(raw) : undefined;
               const decl = sym?.declarations?.[0];
               if (!decl)
                 continue;
@@ -289,18 +304,27 @@ class Extractor {
       if (ts.isImportDeclaration(stmt) || ts.isExportDeclaration(stmt)) {
         const spec = stmt.moduleSpecifier;
         if (spec && ts.isStringLiteral(spec)) {
-          const resolved = this.resolveModule(spec.text, sf.fileName);
+          let resolved;
+          try {
+            resolved = this.resolveModule(spec.text, sf.fileName);
+          } catch {
+            blindSpots.push({ file: relPath, line: lineOf(stmt), reason: `module resolution failed: ${spec.text}`, src_file: relPath });
+          }
           if (!resolved) {
-            for (const entry of this.externalReentry(spec.text, sf.fileName)) {
-              edges.push({
-                src: relPath,
-                dst: this.rel(entry),
-                kind: "imports",
-                file: relPath,
-                line: lineOf(stmt),
-                confidence: "conservative",
-                src_file: relPath
-              });
+            try {
+              for (const entry of this.externalReentry(spec.text, sf.fileName)) {
+                edges.push({
+                  src: relPath,
+                  dst: this.rel(entry),
+                  kind: "imports",
+                  file: relPath,
+                  line: lineOf(stmt),
+                  confidence: "conservative",
+                  src_file: relPath
+                });
+              }
+            } catch {
+              blindSpots.push({ file: relPath, line: lineOf(stmt), reason: `external reentry resolution failed: ${spec.text}`, src_file: relPath });
             }
           } else {
             edges.push({
@@ -429,9 +453,8 @@ class Extractor {
           for (const clause of node.heritageClauses) {
             const ek = clause.token === ts.SyntaxKind.ImplementsKeyword ? "implements" : "extends";
             for (const t of clause.types) {
-              let sym = this.checker.getSymbolAtLocation(t.expression);
-              if (sym && sym.flags & ts.SymbolFlags.Alias)
-                sym = this.checker.getAliasedSymbol(sym);
+              const raw = this.safeSymbolAt(t.expression);
+              const sym = raw ? this.safeAliased(raw) : undefined;
               const decl = sym?.declarations?.[0];
               const dst = decl ? this.nodeIdOfDecl(decl) : undefined;
               if (dst)
@@ -489,9 +512,8 @@ class Extractor {
   }
   resolveCall(call, caller, relPath, line, edges, blindSpots) {
     const expr = call.expression;
-    let sym = this.checker.getSymbolAtLocation(expr);
-    if (sym && sym.flags & ts.SymbolFlags.Alias)
-      sym = this.checker.getAliasedSymbol(sym);
+    const raw = this.safeSymbolAt(expr);
+    const sym = raw ? this.safeAliased(raw) : undefined;
     const decl = sym?.valueDeclaration ?? sym?.declarations?.[0];
     if (!decl) {
       const structural = ts.isElementAccessExpression(expr) || ts.isPropertyAccessExpression(expr) && ["call", "apply", "bind"].includes(expr.name.text);
@@ -709,7 +731,11 @@ function indexProgram(extractor) {
     } catch (err) {
       failures++;
       seenFiles.delete(relPath);
-      console.error(`EXTRACT FAILED ${relPath}: ${err instanceof Error ? err.message : err}`);
+      const detail = err instanceof Error ? `${err.name}: ${err.message}${err.stack ? `
+${err.stack.split(`
+`).slice(1, 12).join(`
+`)}` : ""}` : String(err);
+      console.error(`EXTRACT FAILED ${relPath}: ${detail}`);
     }
   }
 }
@@ -873,6 +899,13 @@ var init_cli = __esm(() => {
     if (pyFiles > 0)
       console.error(`python files ingested: ${pyFiles}`);
   }
+  if (failures === 0) {
+    const stale = db.prepare("SELECT path FROM files").all().filter((row) => !seenFiles.has(row.path));
+    transaction(db, () => {
+      for (const row of stale)
+        invalidateFile(db, row.path);
+    })();
+  }
   dt = ((performance.now() - t0) / 1000).toFixed(1);
   console.log(JSON.stringify({
     db: dbPath,
@@ -1131,16 +1164,17 @@ var init_impact_cli = __esm(() => {
   result = impact(db2, targetId, maxNodes);
   ms = (performance.now() - t02).toFixed(0);
   if (process.argv.includes("--json")) {
+    const uniqueSorted = (values) => [...new Set(values)].sort((a, b) => a.localeCompare(b));
     const guidance = {
-      review_first: result.items.filter((it) => it.channel === "call" && it.level !== "tests").map((it) => it.id),
-      run_tests: result.items.filter((it) => it.level === "tests").map((it) => it.file),
-      conservative: result.items.filter((it) => it.channel === "file" && it.level !== "tests").map((it) => it.id),
+      review_first: uniqueSorted(result.items.filter((it) => it.channel === "call" && it.level !== "tests").map((it) => it.id)),
+      run_tests: uniqueSorted(result.items.filter((it) => it.level === "tests").map((it) => it.file)),
+      conservative: uniqueSorted(result.items.filter((it) => it.channel === "file" && it.level !== "tests").map((it) => it.id)),
       warnings: [
         ...result.truncated ? ["impact_truncated_run_full_test_suite"] : [],
         ...result.blind_spot_count > 0 ? ["blind_spots_may_underestimate_impact"] : []
       ]
     };
-    process.stdout.write(JSON.stringify({ ...result, guidance }) + `
+    process.stdout.write(JSON.stringify({ schema_version: "1", ...result, guidance }) + `
 `);
     db2.close();
     process.exitCode = 0;
@@ -2006,7 +2040,7 @@ function bodySignalCount(bodyChanged, diffLineCount, hasCallImpact) {
   return n;
 }
 function coreNamedCount(diff, prodNodesAdded) {
-  return diff.edgesAdded.filter((e) => !AUX_RE.test(e.file)).length + prodNodesAdded.filter((n) => !AUX_RE.test(n.file)).length + diff.renamed.filter((r) => !AUX_RE.test(r.file)).length + diff.visibilityChanged.filter((v) => !AUX_RE.test(v.file)).length + diff.signatureChanged.filter((s) => !AUX_RE.test(s.file)).length;
+  return diff.edgesAdded.filter((e) => !AUX_RE.test(e.file)).length + diff.edgesRemoved.filter((e) => !AUX_RE.test(e.file)).length + prodNodesAdded.filter((n) => !AUX_RE.test(n.file)).length + diff.nodesRemoved.filter((n) => !AUX_RE.test(n.file) && !TEST_RE3.test(n.file)).length + diff.renamed.filter((r) => !AUX_RE.test(r.file)).length + diff.visibilityChanged.filter((v) => !AUX_RE.test(v.file)).length + diff.signatureChanged.filter((s) => !AUX_RE.test(s.file)).length;
 }
 var TEST_RE3, AUX_RE, BIG_DIFF_LINES = 40;
 var init_pr_silence = __esm(() => {
@@ -2019,6 +2053,7 @@ function reviewDecision(input) {
   const { diff, prodNodesAdded, bodyChanged, affectedTests, truncated, blindSpotCount } = input;
   const apiContractions = diff.visibilityChanged.filter((v) => !v.nowExported).length;
   const apiChanges = apiContractions + diff.signatureChanged.length;
+  const renames = diff.renamed.length;
   const removals = diff.nodesRemoved.length;
   const behaviorChanges = bodyChanged.length;
   const reasons = [];
@@ -2026,7 +2061,7 @@ function reviewDecision(input) {
   let risk = "low";
   if (apiContractions > 0 || removals > 0 || truncated)
     risk = "high";
-  else if (apiChanges > 0 || behaviorChanges > 0 || affectedTests > 0 || blindSpotCount > 0)
+  else if (apiChanges > 0 || renames > 0 || behaviorChanges > 0 || affectedTests > 0 || blindSpotCount > 0)
     risk = "medium";
   if (apiContractions > 0)
     reasons.push(`${apiContractions} exported symbol${apiContractions === 1 ? " is" : "s are"} no longer public`);
@@ -2034,10 +2069,10 @@ function reviewDecision(input) {
     reasons.push(`${removals} symbol${removals === 1 ? " was" : "s were"} removed`);
   if (diff.signatureChanged.length > 0)
     reasons.push(`${diff.signatureChanged.length} exported signature${diff.signatureChanged.length === 1 ? " changed" : "s changed"}`);
+  if (renames > 0)
+    reasons.push(`${renames} symbol${renames === 1 ? " was" : "s were"} renamed`);
   if (behaviorChanges > 0)
     reasons.push(`${behaviorChanges} function bod${behaviorChanges === 1 ? "y" : "ies"} changed`);
-  if (affectedTests > 0)
-    reasons.push(`${affectedTests} test file${affectedTests === 1 ? " is" : "s are"} in the predicted impact set`);
   if (truncated)
     reasons.push("the impact set exceeded the reporting limit");
   if (blindSpotCount > 0)
@@ -2100,7 +2135,7 @@ var args3, repo2, baseSha, headSha, urlFlag, repoUrl2, dbPathA = "/tmp/codeblast
   const wrap = s.kind === "interface" || s.kind === "const" ? (t) => t : (t) => `(${t})`;
   const what = s.kind === "interface" ? "成员变化" : s.kind === "const" ? "类型变化" : "";
   return `- \`${s.name}\`${what ? ` ${what}` : ""}: \`${wrap(clip(s.from))}\` → \`${wrap(clip(s.to))}\` （${link(s.file, s.line)}）`;
-}, apiSig, testSig, uncovered, impactRows, affectedTestCount = 0, anyImpactTruncated = false, totalBlindSpots = 0, prodNodesAdded, diffLineCount, bodySignal, coreNamed, decision;
+}, apiSig, testSig, uncovered, impactRows, affectedTestCount = 0, anyImpactTruncated = false, totalBlindSpots = 0, prodNodesAdded, diffLineCount, bodySignal, coreNamed, changedFiles, changedTests, testedBodySignal, decision;
 var init_pr_comment = __esm(async () => {
   init_db();
   init_proc();
@@ -2170,7 +2205,9 @@ var init_pr_comment = __esm(async () => {
   if (diff2.renamed.length > 0) {
     lines3.push(`### 重命名`, ``);
     for (const r of diff2.renamed.slice(0, 10)) {
-      lines3.push(`- \`${r.from}\` → \`${r.to}\` (${r.kind})`);
+      const targetName = r.to.includes("#") ? r.to.split("#").pop() : r.to;
+      const target = dbB2.prepare("SELECT line FROM nodes WHERE file = ? AND name = ? ORDER BY line LIMIT 1").get(r.file, targetName);
+      lines3.push(`- \`${r.from}\` → \`${r.to}\` (${r.kind})${target ? ` （${link(r.file, target.line)}）` : ""}`);
     }
     if (diff2.renamed.length > 10)
       lines3.push(`- …及另外 ${diff2.renamed.length - 10} 项`);
@@ -2242,7 +2279,11 @@ var init_pr_comment = __esm(async () => {
     }
   });
   coreNamed = coreNamedCount(diff2, prodNodesAdded);
-  if (coreNamed + bodySignal === 0)
+  changedFiles = spawnSync(["git", "diff", "--name-only", baseSha, headSha], { cwd: repo2 }).stdout.split(`
+`).filter(Boolean);
+  changedTests = changedFiles.some((file) => TEST_RE3.test(file));
+  testedBodySignal = bodyChanged.length > 0 && changedTests ? 1 : 0;
+  if (coreNamed + bodySignal + testedBodySignal === 0)
     process.exit(0);
   if (bodyChanged.length > 0) {
     const rows = [];
@@ -2280,6 +2321,7 @@ var init_pr_comment = __esm(async () => {
 // src/check-change.ts
 var exports_check_change = {};
 import fs8 from "node:fs";
+import path3 from "node:path";
 function buildGraphAt3(ref, db) {
   const wt = `/tmp/codeblast-check-${ref.replace(/[^\w]/g, "_")}`;
   spawnSync(["git", "worktree", "remove", "--force", wt], { cwd: repo3 });
@@ -2294,12 +2336,33 @@ function buildGraphAt3(ref, db) {
     spawnSync(["git", "worktree", "remove", "--force", wt], { cwd: repo3 });
   }
 }
-var repo3, baseSha2, headSha2, dbAPath = "/tmp/codeblast-check-base.db", dbBPath = "/tmp/codeblast-check-head.db", dbA3, dbB3, diff3, prodNodesAdded2, bodyChanged2, total3, affectedTests = 0, truncated = false, blindSpots = 0, diffLineCount2, decision2, output;
+var SCHEMA_VERSION = "1", EXIT_OK = 0, EXIT_REVIEW = 1, EXIT_ERROR = 2, readVersion = () => {
+  try {
+    const parsed = JSON.parse(fs8.readFileSync(path3.join(import.meta.dirname, "..", "package.json"), "utf8"));
+    if (parsed && typeof parsed === "object" && "version" in parsed && typeof parsed.version === "string")
+      return parsed.version;
+  } catch {}
+  return "unknown";
+}, ENGINE_VERSION, repo3, baseSha2, headSha2, dbAPath = "/tmp/codeblast-check-base.db", dbBPath = "/tmp/codeblast-check-head.db", dbA3, dbB3, graphHealth = (db) => ({
+  files: Number(db.prepare("SELECT COUNT(*) c FROM files").get().c),
+  nodes: Number(db.prepare("SELECT COUNT(*) c FROM nodes").get().c),
+  edges: Number(db.prepare("SELECT COUNT(*) c FROM edges").get().c),
+  blind_spots: Number(db.prepare("SELECT COUNT(*) c FROM blind_spots").get().c)
+}), healthBase, healthHead, diff3, healthWarnings, prodNodesAdded2, total3, affectedTests = 0, truncated = false, blindSpots = 0, bodyChanged2, structuralIds2, diffText, currentFile = "", diffLineCount2, changedFiles2, auxOnly, decision2, output;
 var init_check_change = __esm(() => {
   init_db();
   init_proc();
   init_impact();
   init_pr_silence();
+  ENGINE_VERSION = readVersion();
+  process.on("uncaughtException", (error) => {
+    console.error(`check-change analysis error: ${error instanceof Error ? error.message : error}`);
+    process.exitCode = EXIT_ERROR;
+  });
+  process.on("unhandledRejection", (reason) => {
+    console.error(`check-change analysis error: ${reason instanceof Error ? reason.message : reason}`);
+    process.exitCode = EXIT_ERROR;
+  });
   [repo3, baseSha2, headSha2] = process.argv.slice(2);
   if (!repo3 || !baseSha2 || !headSha2) {
     console.error("usage: codeblast check-change <repo> <base-sha> <head-sha> --json");
@@ -2312,9 +2375,14 @@ var init_check_change = __esm(() => {
   buildGraphAt3(headSha2, dbBPath);
   dbA3 = openDatabase(dbAPath, { readonly: true });
   dbB3 = openDatabase(dbBPath, { readonly: true });
+  healthBase = graphHealth(dbA3);
+  healthHead = graphHealth(dbB3);
   diff3 = graphDiff(dbA3, dbB3);
+  healthWarnings = [
+    ...healthHead.files === 0 || healthHead.nodes === 0 ? ["graph_empty"] : [],
+    ...healthHead.nodes < healthBase.nodes / 2 ? ["graph_node_count_dropped_sharply"] : []
+  ];
   prodNodesAdded2 = diff3.nodesAdded.filter((n) => !TEST_RE3.test(n.file));
-  bodyChanged2 = [];
   total3 = structuralTotal(diff3);
   for (const node of [...diff3.nodesAdded, ...diff3.renamed.map((r) => ({ id: `${r.file}#${r.to}`, kind: r.kind, name: r.to, file: r.file, line: 0 }))].slice(0, 15)) {
     try {
@@ -2324,13 +2392,48 @@ var init_check_change = __esm(() => {
       blindSpots += result.blind_spot_count;
     } catch {}
   }
+  bodyChanged2 = [];
+  structuralIds2 = new Set([
+    ...diff3.nodesAdded.map((node) => node.id),
+    ...diff3.renamed.map((rename) => `${rename.file}#${rename.to}`)
+  ]);
+  diffText = spawnSync(["git", "diff", "--unified=0", baseSha2, headSha2, "--", "*.ts", "*.tsx"], { cwd: repo3 }).stdout;
+  for (const line of diffText.split(`
+`)) {
+    const file = line.match(/^\+\+\+ b\/(.+)$/);
+    if (file) {
+      currentFile = file[1];
+      continue;
+    }
+    const hunk = line.match(/^@@ -\d+(?:,\d+)? \+(\d+)/);
+    if (!hunk || !currentFile || TEST_RE3.test(currentFile) || AUX_RE.test(currentFile))
+      continue;
+    const row = dbB3.prepare("SELECT id, name, kind, file, line FROM nodes WHERE file = ? AND kind IN ('function','method') AND line <= ? AND end_line >= ? ORDER BY (end_line - line) ASC LIMIT 1").get(currentFile, Number(hunk[1]), Number(hunk[1]));
+    if (row && !structuralIds2.has(row.id) && !bodyChanged2.some((item) => item.id === row.id))
+      bodyChanged2.push(row);
+  }
   diffLineCount2 = spawnSync(["git", "diff", "--numstat", baseSha2, headSha2], { cwd: repo3 }).stdout.split(`
 `).reduce((sum, line) => {
     const match = line.match(/^(\d+)\t(\d+)\t/);
     return sum + (match ? Number(match[1]) + Number(match[2]) : 0);
   }, 0);
+  changedFiles2 = spawnSync(["git", "diff", "--name-only", baseSha2, headSha2], { cwd: repo3 }).stdout.split(`
+`).filter(Boolean);
+  auxOnly = changedFiles2.length > 0 && changedFiles2.every((file) => AUX_RE.test(file));
   decision2 = reviewDecision({ diff: diff3, prodNodesAdded: prodNodesAdded2, bodyChanged: bodyChanged2, affectedTests, truncated, blindSpotCount: blindSpots });
+  if (healthWarnings.length > 0) {
+    decision2.risk = "high";
+    decision2.reasons.push(...healthWarnings);
+    decision2.recommendedActions.unshift("Rebuild or inspect the graph before relying on this decision.");
+  } else if (auxOnly) {
+    decision2.risk = "low";
+    decision2.summary = "Low structural risk: only auxiliary-directory changes were found.";
+    decision2.reasons = ["only auxiliary-directory changes were found"];
+    decision2.recommendedActions = ["No code review signal; inspect the auxiliary change directly if needed."];
+  }
   output = {
+    schema_version: SCHEMA_VERSION,
+    engine_version: ENGINE_VERSION,
     range: `${baseSha2}..${headSha2}`,
     decision: decision2.risk === "high" ? "review" : decision2.risk === "medium" ? "targeted-review" : "safe-to-review",
     risk: decision2.risk,
@@ -2340,23 +2443,25 @@ var init_check_change = __esm(() => {
     structural_changes: total3,
     affected_test_files: affectedTests,
     blind_spot_count: blindSpots,
+    graph_health: { base: healthBase, head: healthHead, warnings: healthWarnings },
     truncated,
     signals: {
       core_named: coreNamedCount(diff3, prodNodesAdded2),
       body: bodySignalCount(bodyChanged2, diffLineCount2, () => false),
-      aux_only: total3 > 0 && coreNamedCount(diff3, prodNodesAdded2) === 0 && bodyChanged2.length === 0
+      aux_only: auxOnly
     },
     diff: diff3
   };
   console.log(JSON.stringify(output));
   dbA3.close();
   dbB3.close();
+  process.exitCode = healthWarnings.length > 0 || decision2.risk === "high" ? EXIT_REVIEW : EXIT_OK;
 });
 // src/demo.ts
 var exports_demo = {};
 import fs9 from "node:fs";
-import path3 from "node:path";
+import path4 from "node:path";
 var repo4, db6 = "/tmp/codeblast-demo.db", out = "/tmp/codeblast-demo-arch.html", run = (label, args) => {
   console.log(`
 \x1B[36m▸ ${label}\x1B[0m`);
@@ -2377,7 +2482,7 @@ var repo4, db6 = "/tmp/codeblast-demo.db", out = "/tmp/codeblast-demo-arch.html"
 var init_demo = __esm(() => {
   init_db();
   init_proc();
-  repo4 = path3.resolve(process.argv[2] ?? path3.join(import.meta.dirname, ".."));
+  repo4 = path4.resolve(process.argv[2] ?? path4.join(import.meta.dirname, ".."));
   console.log(`codeblast demo — target: ${repo4}`);
   for (const s of ["", "-wal", "-shm"])
     fs9.rmSync(db6 + s, { force: true });
@@ -2501,15 +2606,12 @@ usage: codeblast <command> [args]
   archmap   <graph.db> --out arch.html          interactive architecture map
             [--impact <sym>] [--diff <base.db>]   ...with impact / change overlay
             [--repo-url <url>]                    names the page and its JSON-LD (already used above)
-            [--site-url <base>] [--og-image <u>]  canonical/og for the published page (optional)
-  mermaid   <graph.db>                          module map as mermaid
-  cochange  <repo> <graph.db>                   mine git history coupling
   pr-comment <repo> <base-sha> <head-sha>       PR review comment (silent if no change)
   check-change <repo> <base-sha> <head-sha>     machine-readable merge safety decision
   demo      [repo]                              build + query + map in one shot
 docs: https://github.com/alloevil/codeblast · demos: https://alloevil.github.io/codeblast/`);
-  process.exit(cmd2 && !ROUTES[cmd2] ? 1 : 0);
+  process.exit(cmd2 === "--help" || cmd2 === "-h" || !cmd2 ? 0 : 1);
 }
 process.argv.splice(2, 1);
 await ROUTES[cmd2]();

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "codeblast",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Know what breaks before you merge — mutation-tested code graph with architecture, change & impact maps. Evidence on every edge. For humans and AI agents.",
   "keywords": [
     "impact-analysis",
@@ -26,7 +26,7 @@
   },
   "type": "module",
   "bin": {
-    "codeblast": "./dist/bin.js"
+    "codeblast": "dist/bin.js"
   },
   "files": [
     "dist",
@@ -38,8 +38,14 @@
     "build": "bun build src/bin.ts --target=node --outdir=dist --entry-naming=bin.js --external typescript --external @dagrejs/dagre && cp src/archmap-client.js src/py_extract.py dist/",
     "prepack": "bun run build",
     "typecheck": "tsc -p .",
-    "test": "bun test",
-    "demo": "bun src/bin.ts demo",
+    "agent-smoke": "bun run build && node eval/agent-workflow-smoke.mjs",
+    "guidance-stability": "node eval/guidance-stability.mjs",
+    "incremental-equivalence": "bun run build && node eval/incremental-equivalence.mjs",
+    "offline-replay": "bun run build && node eval/offline-replay.mjs",
+    "pilot-summary": "node eval/pilot-summary.mjs",
+    "release-smoke": "node eval/release-smoke.mjs",
+    "validate-compatibility": "node eval/validate-compatibility.mjs",
+    "validate-safety": "node eval/validate-safety.mjs",
     "verify": "python3 eval/mutation_check.py"
   },
   "engines": {
@@ -52,5 +58,11 @@
   "devDependencies": {
     "@types/node": "^26.4.0",
     "bun-types": "^1.4.0"
-  }
+  },
+  "main": "index.js",
+  "directories": {
+    "doc": "docs",
+    "test": "test"
+  },
+  "author": ""
 }