codeblast 0.3.1 → 0.3.2

package/README.md

@@ -49,7 +49,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.0; this checkout is 0.3.1 (unpublished)
+                              # npm serves 0.3.1
 
 # Install as an agent skill (Claude Code, Codex, Cursor, and 14 more harnesses)
 npx skills add alloevil/codeblast
@@ -113,7 +113,8 @@ codeblast change <repo> main~5 main --json
 
 # ③ 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>
+codeblast archmap graph.db --out arch.html --repo-url <github-url> \
+  --site-url https://example.github.io/repo --og-image <share-image-url>
 
 # Optional: mine git co-change coupling (protocol pairs, config + consumers —
 # edges static analysis can't see)
@@ -157,6 +158,20 @@ authoring agent rated its own comments; both numbers and the fixes that followed
 - **You want cross-service / cross-repo edges, or Java.** The graph model reserves the node types, v1 does not fill those edges, and Java is explicitly not implemented ([intent.md](intent.md)).
 - **You want the PR bot to replace a reviewer.** It is a structural-change signal whose usefulness measured between 20% and 75% depending on the review round.
 
+
+### Unified change safety check
+
+For agents and CI that need one decision instead of composing `change` and `impact`, run:
+
+```bash
+codeblast check-change <repo> <base-sha> <head-sha> --json
+```
+
+The output contains `decision` (`safe-to-review`, `targeted-review`, or `review`), `risk`, reasons,
+recommended actions, structural facts, predicted affected-test count, blind-spot count, truncation,
+and the complete graph diff. It is a conservative routing decision, not a claim that the change is
+safe to merge. `review` is required when API surface contracts, removed symbols, or incomplete impact
+results are detected.
 ## For AI agents
 
 ```
@@ -179,14 +194,16 @@ Agent conventions: [AGENTS.md](AGENTS.md).
 
 **Where are the numbers I can check?** Machine-readable claims with metric, method, repro command and evidence path are published at [claims.json](https://alloevil.github.io/codeblast/claims.json); the raw mutation and PR-replay runs are archived under [`eval/`](eval/) as records of runs that were made (the harness writes to `/tmp`, so the files are manual copies with no commit or version pin, and `mutation_check.py` picks candidates with `ORDER BY RANDOM()` — read them as archived runs, not as one-command regenerations), and the acceptance log with every downgrade and rejected optimization is [intent.md](intent.md).
 
+### PR bot feedback
+
+Feedback is intentionally issue-based and privacy-safe. Report only the public PR URL, the affected
+decision category, and a redacted explanation. Do not include source code, secrets, proprietary diffs,
+or full repository contents. The useful labels are false positive, missed impact, noise, incorrect
+silence, or incorrect recommendation. Feedback is qualitative calibration data; it is not telemetry
+and codeblast does not require access to customer repositories.
+
 ## Status & roadmap
 
 M0 graph engine → M1 Impact → M3 architecture map → M4 graph diff + PR bot → M5 precision extensions — **all shipped**; two acceptance steps were downgraded rather than passed (M2's verification method, and M3's original "10 minutes, 5 questions" test which was never run — ⚠️ in [intent.md](intent.md)), and the SemArc alignment check was dropped. Single source of truth for design and acceptance criteria: [intent.md](intent.md).
 
 MIT © 2026
-
----
-
-<p align="center">
-  <a href="https://github.com/oil-oil/beautify-github-readme"><img src="./assets/readme/made-with-beautify.svg" width="300" alt="README made with beautify-github-readme"></a>
-</p>

package/README.zh-CN.md

@@ -33,7 +33,7 @@
 ```bash
 npx codeblast demo            # 给当前仓库建图、跑一次 impact 查询、导出架构图
 npm i -g codeblast            # 或全局安装；需要 Node ≥ 22.13（内置 sqlite）或 Bun
-                              # npm 上的版本是 0.3.0；本仓库是 0.3.1（尚未发布）
+                              # npm 上的版本是 0.3.1，与本仓库一致
 
 # 作为 agent skill 安装（Claude Code、Codex、Cursor 等）
 npx skills add alloevil/codeblast
@@ -132,9 +132,3 @@ Agent 规范另见 [AGENTS.md](AGENTS.md)。
 M0 图谱引擎 → M1 Impact → M3 架构图 → M4 图 diff + PR bot → M5 精度扩展，**全部交付**；其中两项验收是降级而非通过（M2 的验证方式、M3 原定的"陌生工程师 10 分钟 5 问"从未执行——见 intent.md 的 ⚠️），SemArc 对齐检查已作废。方案与验收标准的单一事实源：[intent.md](intent.md)。
 
 MIT © 2026
-
----
-
-<p align="center">
-  <a href="https://github.com/oil-oil/beautify-github-readme"><img src="./assets/readme/made-with-beautify.svg" width="300" alt="README made with beautify-github-readme"></a>
-</p>

package/SKILL.md

@@ -53,8 +53,7 @@ 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 — this is a real run of
-`codeblast index` against [tRPC](https://github.com/trpc/trpc) at commit `66d0544` with codeblast 0.3.0
-(timing is machine-dependent; the counts are not):
+`codeblast index` against [tRPC](https://github.com/trpc/trpc) at commit `66d0544` with the historical codeblast 0.3.0 benchmark
 
 ```json
 { "db": "/tmp/graph.db", "seconds": 5.2, "tsconfigs": 34, "files_indexed": 957, "files_skipped": 0,
@@ -93,9 +92,21 @@ Output (`--json`):
     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
+  guidance: {
+    review_first: string[];  // call-channel non-test nodes
+    run_tests: string[];     // test file paths, de-duplicate before running
+    conservative: string[];  // non-test file-channel nodes; never discard
+    warnings: string[];      // truncation and blind-spot warnings
+  };
 }
 ```
 
+The `guidance` object is a convenience projection of `items`; it does not add analysis results.
+Use `review_first` for the initial callsite checklist, `run_tests` for the affected test files,
+and `conservative` as the import/re-export safety net. `warnings` is non-empty when the result is
+incomplete or the target file contains unresolved analysis. Always retain `via_file` and `via_line`
+when reporting a dependency.
+
 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.

package/dist/bin.js

@@ -1131,7 +1131,16 @@ var init_impact_cli = __esm(() => {
   result = impact(db2, targetId, maxNodes);
   ms = (performance.now() - t02).toFixed(0);
   if (process.argv.includes("--json")) {
-    process.stdout.write(JSON.stringify(result) + `
+    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),
+      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 }) + `
 `);
     db2.close();
     process.exitCode = 0;
@@ -1436,7 +1445,7 @@ async function layoutGraph(nodes, edges) {
     }))
   };
 }
-var CLIENT_JS, dbPath3, outFlag2, outPath2, overlayFlag, overlayPath, repoFlag, repoUrl, impactFlag, impactTarget, diffFlag, diffBase, db3, overlay, TEST_RE, moduleOf = (file) => {
+var CLIENT_JS, dbPath3, outFlag2, outPath2, overlayFlag, overlayPath, repoFlag, repoUrl, impactFlag, impactTarget, diffFlag, diffBase, siteFlag, siteUrl, ogImageFlag, ogImage, repoLabel, pageUrl, pageKind, pageTitle, pageDesc, escAttr = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;"), headMeta, db3, overlay, TEST_RE, moduleOf = (file) => {
   if (TEST_RE.test(file))
     return "tests";
   const ix = file.indexOf("/");
@@ -1460,6 +1469,51 @@ var init_archmap_html = __esm(async () => {
   impactTarget = impactFlag >= 0 ? process.argv[impactFlag + 1] : undefined;
   diffFlag = process.argv.indexOf("--diff");
   diffBase = diffFlag >= 0 ? process.argv[diffFlag + 1] : undefined;
+  siteFlag = process.argv.indexOf("--site-url");
+  siteUrl = siteFlag >= 0 ? process.argv[siteFlag + 1].replace(/\/+$/, "") : undefined;
+  ogImageFlag = process.argv.indexOf("--og-image");
+  ogImage = ogImageFlag >= 0 ? process.argv[ogImageFlag + 1] : undefined;
+  repoLabel = (() => {
+    const m = repoUrl?.match(/github\.com\/([^/]+\/[^/]+)/);
+    if (m)
+      return m[1].replace(/\.git$/, "");
+    const base = outPath2.split("/").pop() ?? outPath2;
+    return base.replace(/\.html$/, "");
+  })();
+  pageUrl = siteUrl ? `${siteUrl}/${outPath2.split("/").pop()}` : undefined;
+  pageKind = impactTarget ? "blast-radius map" : diffBase ? "change map" : "architecture map";
+  pageTitle = `${repoLabel} — ${pageKind}`;
+  pageDesc = `Interactive architecture map of ${repoLabel} generated by codeblast: a module-level` + ` dependency graph where hovering a node lights up its fan-in and clicking it shows its files,` + ` symbols and import edges.` + (impactTarget ? ` Includes the blast-radius overlay for ${impactTarget}.` : "") + (overlayPath ? " Includes the change overlay." : "");
+  headMeta = [
+    `<title>${escAttr(pageTitle)}</title>`,
+    `<meta name="description" content="${escAttr(pageDesc)}">`,
+    ...pageUrl ? [`<link rel="canonical" href="${escAttr(pageUrl)}">`] : [],
+    `<meta property="og:type" content="website">`,
+    `<meta property="og:title" content="${escAttr(pageTitle)}">`,
+    `<meta property="og:description" content="${escAttr(pageDesc)}">`,
+    ...pageUrl ? [`<meta property="og:url" content="${escAttr(pageUrl)}">`] : [],
+    `<meta property="og:site_name" content="codeblast">`,
+    ...ogImage ? [`<meta property="og:image" content="${escAttr(ogImage)}">`] : [],
+    `<meta name="twitter:card" content="${ogImage ? "summary_large_image" : "summary"}">`,
+    `<meta name="twitter:title" content="${escAttr(pageTitle)}">`,
+    `<meta name="twitter:description" content="${escAttr(pageDesc)}">`,
+    ...ogImage ? [`<meta name="twitter:image" content="${escAttr(ogImage)}">`] : [],
+    `<script type="application/ld+json">`,
+    JSON.stringify({
+      "@context": "https://schema.org",
+      "@type": "WebPage",
+      name: pageTitle,
+      description: pageDesc,
+      inLanguage: "zh-CN",
+      ...pageUrl ? { url: pageUrl } : {},
+      ...repoUrl ? {
+        isBasedOn: repoUrl,
+        about: { "@type": "SoftwareSourceCode", name: repoLabel, codeRepository: repoUrl }
+      } : {}
+    }, null, 2),
+    `</script>`
+  ].join(`
+`);
   if (!dbPath3) {
     console.error("usage: codeblast archmap <graph.db> --out arch.html");
     process.exit(1);
@@ -1629,10 +1683,10 @@ var init_archmap_html = __esm(async () => {
     fileEdges: importRows
   };
   html = `<!DOCTYPE html>
-<html lang="zh">
+<html lang="zh-CN">
 <head>
 <meta charset="utf-8">
-<title>codeblast · Architecture Map</title>
+${headMeta}
 <style>
   :root { --bg:#0d1117; --panel:#161b22; --border:#30363d; --fg:#e6edf3; --dim:#8b949e;
           --accent:#58a6ff; --warn:#f85149; --ok:#3fb950; }
@@ -1671,6 +1725,11 @@ var init_archmap_html = __esm(async () => {
   .edge.cyclic { stroke: var(--warn); stroke-dasharray: 5 3; stroke-width: 2;
     animation: cycflow 1.2s linear infinite; }
   @keyframes cycflow { to { stroke-dashoffset: -16; } }
+  /* 循环依赖用虚线静止表示即可 —— 虚线与颜色承载信息，流动只是让它更显眼。
+     reduced-motion 下停掉动画，而不是去掉虚线。 */
+  @media (prefers-reduced-motion: reduce) {
+    .edge.cyclic { animation: none; }
+  }
   .edge.hi { stroke: #d29922 !important; stroke-width: 2.6; stroke-opacity: 1; }
   .edge.dim { stroke-opacity: 0.1; }
   .edge.faint { stroke-opacity: 0.06; }
@@ -1955,6 +2014,54 @@ var init_pr_silence = __esm(() => {
   AUX_RE = /^(www|docs|examples)\//;
 });
 
+// src/pr-decision.ts
+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 removals = diff.nodesRemoved.length;
+  const behaviorChanges = bodyChanged.length;
+  const reasons = [];
+  const recommendedActions = [];
+  let risk = "low";
+  if (apiContractions > 0 || removals > 0 || truncated)
+    risk = "high";
+  else if (apiChanges > 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`);
+  if (removals > 0)
+    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 (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)
+    reasons.push(`${blindSpotCount} static-analysis blind spot${blindSpotCount === 1 ? "" : "s"} may hide impact`);
+  if (reasons.length === 0 && prodNodesAdded.length > 0)
+    reasons.push(`${prodNodesAdded.length} production symbol${prodNodesAdded.length === 1 ? " was" : "s were"} added`);
+  if (reasons.length === 0)
+    reasons.push("only low-risk structural additions were found");
+  if (apiChanges > 0 || removals > 0)
+    recommendedActions.push("Review the public API changes and migration impact.");
+  if (truncated)
+    recommendedActions.push("Run the full test suite; the reported impact list is truncated.");
+  else if (affectedTests > 0)
+    recommendedActions.push(`Run the ${affectedTests} predicted affected test file${affectedTests === 1 ? "" : "s"}.`);
+  if (blindSpotCount > 0)
+    recommendedActions.push("Inspect the reported blind spots before treating the impact set as complete.");
+  if (behaviorChanges > 0)
+    recommendedActions.push("Review the changed function bodies even where the exported shape is unchanged.");
+  if (recommendedActions.length === 0)
+    recommendedActions.push("Review the named structural additions; no existing API contraction was detected.");
+  const summary = risk === "high" ? "Review before merge: the change removes API surface, deletes symbols, or has an incomplete impact set." : risk === "medium" ? "Targeted review recommended: behavior, API shape, tests, or blind spots changed." : "Low structural risk: only additive changes with no predicted affected tests were found.";
+  return { risk, summary, reasons, recommendedActions };
+}
+
 // src/pr-comment.ts
 var exports_pr_comment = {};
 import fs7 from "node:fs";
@@ -1993,7 +2100,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, prodNodesAdded, diffLineCount, bodySignal, coreNamed;
+}, apiSig, testSig, uncovered, impactRows, affectedTestCount = 0, anyImpactTruncated = false, totalBlindSpots = 0, prodNodesAdded, diffLineCount, bodySignal, coreNamed, decision;
 var init_pr_comment = __esm(async () => {
   init_db();
   init_proc();
@@ -2106,6 +2213,9 @@ var init_pr_comment = __esm(async () => {
       const r = impact(dbB2, n.id, 2000);
       const callItems = r.items.filter((i) => i.channel === "call");
       const tests = callItems.filter((i) => i.level === "tests").length;
+      affectedTestCount += tests;
+      anyImpactTruncated ||= r.truncated;
+      totalBlindSpots += r.blind_spot_count;
       impactRows.push(`| \`${n.name}\` | ${n.kind} | ${callItems.length} | ${tests} | ${link(n.file, n.line)} |`);
       const blind = r.blind_spot_count > 0;
       if (tests === 0 && n.kind !== "interface" && n.kind !== "const") {
@@ -2153,16 +2263,101 @@ var init_pr_comment = __esm(async () => {
   if (total2 === 0 && bodyChanged.length > 0) {
     lines3[2] = `**无结构变更**,但有 ${bodyChanged.length} 个函数体内改动（见下）`;
   }
+  decision = reviewDecision({
+    diff: diff2,
+    prodNodesAdded,
+    bodyChanged,
+    affectedTests: affectedTestCount,
+    truncated: anyImpactTruncated,
+    blindSpotCount: totalBlindSpots
+  });
+  lines3.splice(3, 0, `> **Review decision · ${decision.risk.toUpperCase()}** — ${decision.summary}`, `> ${decision.reasons.join("; ")}.`, ``, `### Recommended checks`, ``, ...decision.recommendedActions.map((action) => `- ${action}`), ``);
   lines3.push(`<sub>由 [codeblast](https://github.com/alloevil/codeblast) 生成 · 每条结论基于静态分析,含证据链接 · 动态调用盲区不在本报告内 · 评论不准?[30 秒反馈](https://github.com/alloevil/codeblast/issues/new?template=bot-feedback.yml&title=${encodeURIComponent(`[feedback] ${baseSha.slice(0, 7)}..${headSha.slice(0, 7)}`)})</sub>`);
   console.log(lines3.join(`
 `));
 });
 
+// src/check-change.ts
+var exports_check_change = {};
+import fs8 from "node:fs";
+function buildGraphAt3(ref, db) {
+  const wt = `/tmp/codeblast-check-${ref.replace(/[^\w]/g, "_")}`;
+  spawnSync(["git", "worktree", "remove", "--force", wt], { cwd: repo3 });
+  const add = spawnSync(["git", "worktree", "add", "--detach", wt, ref], { cwd: repo3 });
+  if (add.exitCode !== 0)
+    throw new Error(add.stderr.slice(0, 300));
+  try {
+    const built = spawnSync(selfCommand("index", wt, "--db", db));
+    if (built.exitCode !== 0)
+      throw new Error(built.stderr.slice(0, 500));
+  } finally {
+    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 init_check_change = __esm(() => {
+  init_db();
+  init_proc();
+  init_impact();
+  init_pr_silence();
+  [repo3, baseSha2, headSha2] = process.argv.slice(2);
+  if (!repo3 || !baseSha2 || !headSha2) {
+    console.error("usage: codeblast check-change <repo> <base-sha> <head-sha> --json");
+    process.exit(1);
+  }
+  for (const f of [dbAPath, dbBPath])
+    for (const suffix of ["", "-wal", "-shm"])
+      fs8.rmSync(f + suffix, { force: true });
+  buildGraphAt3(baseSha2, dbAPath);
+  buildGraphAt3(headSha2, dbBPath);
+  dbA3 = openDatabase(dbAPath, { readonly: true });
+  dbB3 = openDatabase(dbBPath, { readonly: true });
+  diff3 = graphDiff(dbA3, dbB3);
+  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 {
+      const result = impact(dbB3, node.id, 2000);
+      affectedTests += new Set(result.items.filter((item) => item.level === "tests").map((item) => item.file)).size;
+      truncated ||= result.truncated;
+      blindSpots += result.blind_spot_count;
+    } catch {}
+  }
+  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);
+  decision2 = reviewDecision({ diff: diff3, prodNodesAdded: prodNodesAdded2, bodyChanged: bodyChanged2, affectedTests, truncated, blindSpotCount: blindSpots });
+  output = {
+    range: `${baseSha2}..${headSha2}`,
+    decision: decision2.risk === "high" ? "review" : decision2.risk === "medium" ? "targeted-review" : "safe-to-review",
+    risk: decision2.risk,
+    summary: decision2.summary,
+    reasons: decision2.reasons,
+    recommended_actions: decision2.recommendedActions,
+    structural_changes: total3,
+    affected_test_files: affectedTests,
+    blind_spot_count: blindSpots,
+    truncated,
+    signals: {
+      core_named: coreNamedCount(diff3, prodNodesAdded2),
+      body: bodySignalCount(bodyChanged2, diffLineCount2, () => false),
+      aux_only: total3 > 0 && coreNamedCount(diff3, prodNodesAdded2) === 0 && bodyChanged2.length === 0
+    },
+    diff: diff3
+  };
+  console.log(JSON.stringify(output));
+  dbA3.close();
+  dbB3.close();
+});
+
 // src/demo.ts
 var exports_demo = {};
-import fs8 from "node:fs";
+import fs9 from "node:fs";
 import path3 from "node:path";
-var repo3, db6 = "/tmp/codeblast-demo.db", out = "/tmp/codeblast-demo-arch.html", run = (label, args) => {
+var repo4, db6 = "/tmp/codeblast-demo.db", out = "/tmp/codeblast-demo-arch.html", run = (label, args) => {
   console.log(`
 \x1B[36m▸ ${label}\x1B[0m`);
   console.log(`  $ codeblast ${args.slice(2).join(" ")}`);
@@ -2182,12 +2377,12 @@ var repo3, db6 = "/tmp/codeblast-demo.db", out = "/tmp/codeblast-demo-arch.html"
 var init_demo = __esm(() => {
   init_db();
   init_proc();
-  repo3 = path3.resolve(process.argv[2] ?? path3.join(import.meta.dirname, ".."));
-  console.log(`codeblast demo — target: ${repo3}`);
+  repo4 = path3.resolve(process.argv[2] ?? path3.join(import.meta.dirname, ".."));
+  console.log(`codeblast demo — target: ${repo4}`);
   for (const s of ["", "-wal", "-shm"])
-    fs8.rmSync(db6 + s, { force: true });
-  run("1/4 build graph", selfCommand("index", repo3, "--db", db6));
-  run("2/4 incremental rerun (should skip everything)", selfCommand("index", repo3, "--db", db6));
+    fs9.rmSync(db6 + s, { force: true });
+  run("1/4 build graph", selfCommand("index", repo4, "--db", db6));
+  run("2/4 incremental rerun (should skip everything)", selfCommand("index", repo4, "--db", db6));
   conn = openDatabase(db6, { readonly: true });
   pick = conn.prepare(`SELECT n.id, COUNT(DISTINCT e.src) c FROM nodes n
    JOIN edges e ON e.dst = n.id AND e.kind = 'calls'
@@ -2212,7 +2407,7 @@ var init_demo = __esm(() => {
 
 // src/name-modules.ts
 var exports_name_modules = {};
-import fs9 from "node:fs";
+import fs10 from "node:fs";
 var dbPath6, overlayFlag2, overlayPath2, db7, TEST_RE4, files3, byModule, symStmt, evidence, prompt, cmd;
 var init_name_modules = __esm(async () => {
   init_db();
@@ -2250,7 +2445,7 @@ ${JSON.stringify(evidence, null, 1)}`;
   if (!cmd) {
     const applyFlag = process.argv.indexOf("--apply");
     if (applyFlag >= 0) {
-      const namesJson = JSON.parse(fs9.readFileSync(process.argv[applyFlag + 1], "utf8"));
+      const namesJson = JSON.parse(fs10.readFileSync(process.argv[applyFlag + 1], "utf8"));
       const overlay = await loadOverlay(overlayPath2);
       for (const [mod, v] of Object.entries(namesJson)) {
         const existing = overlay.modules[mod];
@@ -2259,7 +2454,7 @@ ${JSON.stringify(evidence, null, 1)}`;
         overlay.modules[mod] = { ...existing, name: `${v.name}`, ...v.desc ? {} : {} };
         overlay.modules[mod].desc = v.desc;
       }
-      fs9.writeFileSync(overlayPath2, JSON.stringify(overlay, null, 2));
+      fs10.writeFileSync(overlayPath2, JSON.stringify(overlay, null, 2));
       console.error(`overlay written: ${overlayPath2}`);
     } else {
       console.log(prompt);
@@ -2276,7 +2471,7 @@ ${JSON.stringify(evidence, null, 1)}`;
       overlay.modules[mod] = { ...overlay.modules[mod], name: v.name };
       overlay.modules[mod].desc = v.desc;
     }
-    fs9.writeFileSync(overlayPath2, JSON.stringify(overlay, null, 2));
+    fs10.writeFileSync(overlayPath2, JSON.stringify(overlay, null, 2));
     console.error(`overlay written: ${overlayPath2}`);
   }
 });
@@ -2290,6 +2485,7 @@ var ROUTES = {
   mermaid: () => Promise.resolve().then(() => (init_archmap(), exports_archmap)),
   cochange: () => Promise.resolve().then(() => (init_cochange(), exports_cochange)),
   "pr-comment": () => init_pr_comment().then(() => exports_pr_comment),
+  "check-change": () => Promise.resolve().then(() => (init_check_change(), exports_check_change)),
   demo: () => Promise.resolve().then(() => (init_demo(), exports_demo)),
   "name-modules": () => init_name_modules().then(() => exports_name_modules)
 };
@@ -2304,9 +2500,12 @@ usage: codeblast <command> [args]
   change    <repo> <ref-a> <ref-b> [--json]     structural diff between two refs
   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/`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codeblast",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "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",