Turbocharge Claude Code, Cursor, Codex, Gemini & every coding agent: faster, cheaper, with contextual understanding specific to your codebase.
TypeScript ai-agentsanthropicclaude-codeclicode-graphcodexcontext-engineeringcursordeveloper-toolsgeminiknowledge-graphllmmcpmcp-serveropen-sourceopenaitree-sitter
/**
* CLI wiring for `graft blast` — the command a CI job runs on a pull request.
*
* Kept out of cli.ts (argument wiring only) so the diff → seeds → walk → render
* chain stays unit-testable without shelling out, matching `graph/traverse-cli.ts`.
*/
import { execFileSync } from "node:child_process";
import { basename, resolve } from "node:path";
import { contextDirFor } from "../context/node-file.js";
import { loadGraphCached } from "../graph/load.js";
import type { GraphV1 } from "../graph/types.js";
import { blastRadiusIn, type BlastReport } from "./blast.js";
import { changedFiles, refExists } from "./diff.js";
import { markdownReport, mermaidDiagram, textReport } from "./render.js";
import { cmd } from "../brand.js";
export type BlastFormat = "text" | "markdown" | "mermaid" | "json";
export interface BlastCliOptions {
/** Base ref to diff against (`origin/main`); omitted → working tree vs HEAD. */
base?: string;
/** Raw `--depth`: a positive integer, or `all`/`full`/`max`. Default 2. */
depth?: string;
format?: string;
/** Ask a model to name the clusters that have no concept name (one call, cached).
* Opt-in: a local `graft blast` must not need a key or a network round-trip. */
name?: boolean;
/** Write the interactive page for this radius here (one self-contained file). */
exportViz?: string;
/** Subtitle beside the repo name on the exported page, e.g. "PR #171". Same
* meaning as `graft viz --title`. Without it a reader of a published page has no
* way to tell which pull request they are looking at. */
title?: string;
/** Suggest who to tag, from git history over each area. On by default; `--no-owners`
* turns the whole layer off for a repo that would rather not name people. */
owners?: boolean;
/** The PR author: logins, names or emails to keep out of their own suggestions. */
prAuthor?: string[];
/** The top-level `--dir` override. */
globalDir?: string;
}
const DEFAULT_DEPTH = 2;
function resolveFormat(raw: string | undefined): BlastFormat {
if (raw === undefined) return "text";
if (raw === "text" || raw === "markdown" || raw === "mermaid" || raw === "json") return raw;
console.error(`✗ --format must be text, markdown, mermaid or json, got "${raw}"`);
process.exit(1);
}
/** Same grammar as `graft callers --depth`, so the two commands stay learnable together. */
function resolveDepth(raw: string | undefined): number {
if (raw === undefined) return DEFAULT_DEPTH;
if (/^(all|full|max)$/i.test(raw)) return Number.POSITIVE_INFINITY;
const d = Number(raw);
if (!Number.isFinite(d) || d < 1) {
console.error(`✗ --depth must be a positive number or "all", got "${raw}"`);
process.exit(1);
}
return Math.floor(d);
}
export async function runBlastCommand(dir: string, opts: BlastCliOptions): Promise<void> {
const root = resolve(dir);
const contextDir = contextDirFor(root, opts.globalDir);
const format = resolveFormat(opts.format);
const depth = resolveDepth(opts.depth);
const graph = loadGraphCached(contextDir);
if (!graph) {
console.error(`✗ no graph found at ${contextDir} — run \`${cmd("graft build")}\` first`);
process.exit(1);
}
// An unknown base is the most common CI misconfiguration by a distance: an
// `actions/checkout` without `fetch-depth: 0` leaves the base branch absent, and
// git's own message ("unknown revision or path not in the working tree") sends
// people looking for a typo instead of the checkout depth.
if (opts.base !== undefined && !refExists(root, opts.base)) {
console.error(
`✗ base ref "${opts.base}" is not in this checkout.\n` +
" In CI, fetch enough history for the merge base: actions/checkout with `fetch-depth: 0`.",
);
process.exit(1);
}
const diff = changedFiles(root, opts.base);
if (!diff) {
console.error(`✗ could not read a diff in ${root} — is this a git repository?`);
process.exit(1);
}
const report = blastRadiusIn(graph, contextDir, diff.files, diff.basis, depth);
if (opts.name) await nameClusters(graph, report, contextDir);
// After naming, never before: a reviewer's reason cites area LABELS, and the
// naming pass is what gives an area its final one.
if (opts.owners !== false) {
const { attachOwners, diffAuthors, localIdentity } = await import("./owners.js");
// Everyone who wrote a commit in this range, plus whatever the caller named.
// The range is the reliable half: CI knows the author's login but almost never
// their commit email, and the email is what git history is keyed on.
//
// With no --base there is no range — this is the local "what am I about to
// push" case — so the local git identity stands in for it. Without that, the
// one person certain to have written the change is the top name in its own
// list of who to ask about it.
const authors = opts.base === undefined ? localIdentity(root) : diffAuthors(root, opts.base);
attachOwners(root, report, { exclude: [...authors, ...(opts.prAuthor ?? [])] });
}
if (opts.exportViz) await exportRadius(report, contextDir, root, opts.exportViz, opts.title);
if (format === "json") {
console.log(JSON.stringify(report, null, 2));
return;
}
if (format === "mermaid") {
const diagram = mermaidDiagram(report);
// Exit 0 with a comment, not an error: "nothing depends on this diff" is a
// legitimate answer, and a CI step must not fail on it.
console.log(diagram ?? "%% no dependents to draw");
return;
}
process.stdout.write(format === "markdown" ? markdownReport(report, { root }) : textReport(report));
}
/**
* Name the clusters left on their symbol backstop, then report what it cost.
*
* The work lives in `name.ts` so the GitHub App runs the identical pass; all
* this adds is the `--name:` prefix a CLI note wants.
*/
async function nameClusters(graph: GraphV1, report: BlastReport, contextDir: string): Promise<void> {
const { nameReport } = await import("./name.js");
const { note } = await nameReport(graph, report, contextDir);
if (note) console.error(`• --name: ${note}`);
}
/**
* What to call the repository in the appbar.
*
* `basename(root)` is right for someone running this in their own clone, but CI
* checks a pull request out into a directory named for the job — ours is literally
* `pr` — which titled the published page "pr". The origin remote is the repository,
* so it wins when there is one; a detached tarball checkout still falls back.
*/
export function repoLabel(root: string): string {
try {
const url = execFileSync("git", ["-C", root, "remote", "get-url", "origin"], {
encoding: "utf8",
stdio: ["ignore", "pipe", "ignore"],
}).trim();
const name = url.replace(/\.git$/, "").split(/[/:]/).pop();
if (name) return name;
} catch {
// No remote, or no git at all: the directory name is the best guess left.
}
return basename(root);
}
/**
* Write the interactive page for this radius: the same viewer `graft viz` serves,
* with the blast graph as its Context tab.
*
* Done here rather than in `viz` because the radius is what a reviewer opened the
* link for, and only `blast` has it — `viz --export` on its own can offer the deep
* tier's concept map, which a PR build no longer produces.
*/
async function exportRadius(
report: BlastReport,
contextDir: string,
root: string,
outDir: string,
subtitle?: string,
): Promise<void> {
const { resolve: resolvePath } = await import("node:path");
const { fileURLToPath } = await import("node:url");
const { exportViz } = await import("../viz/export.js");
const { blastVizGraph } = await import("./viz.js");
const out = exportViz({
contextDir,
viewerDir: fileURLToPath(new URL("../viewer/", import.meta.url)), // prebuilt, ships in dist
outDir: resolvePath(outDir),
repoName: repoLabel(root),
subtitle,
contextGraph: blastVizGraph(report, { root }),
// Context alone: see VizExportOptions.tabs — the other two tabs are about the
// repository, and this page is about one pull request.
tabs: ["context"],
});
console.error(`• --export-viz: ${out.file} (${Math.round(out.bytes / 1024)} kB, ${out.contextNodes} areas, ${out.codeNodes} code nodes)`);
}