# pi-blast-radius

Predict what a code change might break — before it ships.

A [pi](https://pi.dev) package. Type `/blast-radius` in any git repository and
the agent traces references, gathers fragility signals, scores risk, and prints
a single markdown impact report. No dashboards, no graphs — just answers.

![pi-blast-radius demo](assets/demo.gif)

**[Documentation and demo](https://abrahamjeron.github.io/pi_blast_radius/)**
·
**[npm](https://www.npmjs.com/package/pi-blast-radius)**

---

## Why

Every change raises one question: _what is the blast radius?_ This package turns
your pi agent into an impact analyst. It runs `git diff`, greps for every
caller, import, and string reference, follows the dependency chain to closure,
and tells you what is likely to break and which tests to run.

## Install

Use pi's installer — not `npm i` — so the extension registers with pi.

```bash
# from npm
pi install npm:pi-blast-radius

# or from git
pi install git:github.com/abrahamjeron/pi_blast_radius

# try without installing
pi -e ./extensions/index.ts
```

Verify with `pi list`, then run `/blast-radius` inside a pi session.

## Usage

```text
/blast-radius                 analyze uncommitted and staged changes
/blast-radius HEAD~3          analyze the last 3 commits
/blast-radius <sha>           analyze a specific commit
/blast-radius <branch>        diff a branch against its base
```

## What you get

A single markdown report — impacted symbols ranked by risk, downstream and
cross-service risks, the exact tests to run, and an overall risk score.

```text
## Blast Radius Report
### Change Summary
### Impacted (ranked by risk)
| Symbol | File:Line | Type | Risk | Why |
### Downstream / Cross-service risks
### Tests to run
### Risk score: X/10
```

Node types: `direct`, `transitive`, `test`, `public-export`, `config`,
`cross-service`. Risk factors: fan-in, depth, exported or public surface, test
coverage, and churn history.

## How it works

The `/blast-radius` command sends a short task as the user turn and injects the
full analysis workflow into the system prompt for that turn. pi's agent loop
then runs it with the built-in `bash`, `grep`, and `read` tools and emits the
report. All the intelligence lives in the workflow prompt (`src/prompt.ts`);
there are no custom tools.

The analysis is read-only. The workflow forbids any mutation or network command
— no writes, no `rm`, `mv`, or redirects, no `git push` or `commit`, no `curl`.
It only inspects with `git diff`, `show`, `log`, `blame`, and `grep`.

## Development

```bash
git clone https://github.com/abrahamjeron/pi_blast_radius
cd pi_blast_radius
pi -e ./extensions/index.ts
```

Publishing is automated: merge to `main` with a bumped version in
`package.json` and the GitHub Actions workflow publishes to npm. Requires an
`NPM_TOKEN` repository secret.

## License

MIT