# Code Impact Radius

> Use BEFORE any rename, refactor, type-shape change, deletion, or "what depends on X" question in a TypeScript / TSX codebase. Returns every place a symbol is defined, read, written, called, instantiated, imported, re-exported, plus its transitive callers up to a configurable depth. Far cheaper than grep+read because it queries a typed reference index built from the TypeScript Compiler — no false…

- **Type:** Skill
- **Install:** `agentstack add skill-faris-alanazi-code-impact-radius-code-impact-radius`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Faris-Alanazi](https://agentstack.voostack.com/s/faris-alanazi)
- **Installs:** 0
- **Category:** [Developer Tools](https://agentstack.voostack.com/c/developer-tools)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Faris-Alanazi](https://github.com/Faris-Alanazi)
- **Source:** https://github.com/Faris-Alanazi/code-impact-radius
- **Website:** https://github.com/Faris-Alanazi/code-impact-radius

## Install

```sh
agentstack add skill-faris-alanazi-code-impact-radius-code-impact-radius
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Code Impact Radius

The structured replacement for `grep -r ` followed by reading every match.

## When to invoke

Whenever you (or the user) is about to:

- Rename a function, variable, class, type, interface, or enum
- Change the shape of a type or function signature
- Move or delete a file / module / barrel export
- Audit who depends on a particular symbol (security review, deprecation, refactor planning)
- Decide whether a change is "safe to do alone" or "needs coordinated rollout"
- Answer "what calls X", "where is X used", "who imports X", "blast radius of X"

This is the right tool whenever the question is **"what connects to this symbol?"**

## How to invoke

```bash
node ~/.claude/skills/code-impact-radius/src/cli.js  --project  --json
```

Or — if you want pretty terminal output instead of JSON:

```bash
node ~/.claude/skills/code-impact-radius/src/cli.js  --project  --pretty
```

JSON is the default when stdout is not a TTY (so AI agents always get JSON).

### Options

| Flag | What it does |
|---|---|
| `--project ` | Project root containing `tsconfig.json` (default: `cwd`) |
| `--depth ` | Transitive caller depth (default `2`, max `10`) |
| `--kind ` | Filter declaration kind: `variable` `function` `class` `method` `interface` `type` `enum` |
| `--at :` | Disambiguate when the name has multiple declarations |
| `--include-tests` | Include `*.test.ts` / `*.spec.ts` in references (default: skip) |
| `--max-sites ` | Truncate `references.sites` to first N entries |
| `--json` / `--pretty` | Force output mode |
| `--mermaid` | Emit a Mermaid flowchart diagram (paste into a Markdown ` ```mermaid ` block — GitHub, GitLab, VS Code, Obsidian, Notion render natively). |

### Exit codes

| Code | Meaning |
|---|---|
| 0 | Success — exactly one match, OR ambiguous list with N candidates |
| 1 | CLI usage error / runtime error |
| 2 | Symbol name not found |

## Reading the JSON output

```jsonc
{
  "query":             // what was asked
  "matched":           // how many declarations matched the name
  "candidates":        // disambiguation list (only when matched > 1 or 0)
  "symbol": {
    "name":            // canonical name
    "kind":            // function | class | variable | ...
    "definition": {
      "file": "...", "line": 42, "column": 17,
      "snippet": "export function formatPrice..."
    }
  },
  "references": {
    "totalCount": 14,
    "byKind": {
      "definition": 1,
      "call": 8,
      "import": 3,
      "reExport": 1,
      "read": 1,
      "instantiation": 0,
      "jsx": 0,
      "type": 0,
      "write": 0
    },
    "sites": [
      { "file": "...", "line": 18, "kind": "call", "snippet": "formatPrice(price, locale)", "parentKind": "CallExpression" }
    ],
    "truncated": 0
  },
  "imports": {
    "exportedFrom": "src/lib/utils.ts",
    "importedBy":     // every file that imports this symbol
    "reExportedFrom": // every barrel that re-exports it
  },
  "transitiveCallers": {
    "depth": 2,
    "callers": [
      { "depth": 1, "file": "...", "line": 18, "function": "PriceTag",     "functionKind": "FunctionDeclaration" },
      { "depth": 2, "file": "...", "line": 87, "function": "CheckoutPage", "functionKind": "FunctionDeclaration" }
    ]
  },
  "warnings": []
}
```

## Disambiguation flow

If `matched > 1`, the tool returns `candidates` and asks for a `--at :` to pick one:

```bash
$ code-impact-radius id --project ./app --json
# matched: 3, symbol: null, candidates: [{file, line, kind} × 3]

$ code-impact-radius id --project ./app --at src/ambig.ts:11 --json
# matched: 1, symbol: { ... }
```

## Decision-flow guidance for blast-radius checks

Use this output to drive a structured impact table:

1. **Definition** — read the file at `symbol.definition.file:line` to see the contract you're about to change.
2. **References by kind** — every `call`, `instantiation`, `jsx`, `read`, `write` site is a potential breakage.
3. **Imports** — every `imports.importedBy` entry needs updating if you rename the symbol.
4. **Re-exports** — barrels in `imports.reExportedFrom` need updating too.
5. **Transitive callers** — depth 2-3 catches most "indirect callers" that grep would miss.

Then build the impact table (`file:line | usage | status: todo/done/verified-unaffected`) and tick each row off as you go.

## What this tool does NOT cover

- **String literals** — i18n keys (`t('home.title')`), SQL fragments, env-var names, URL paths. Use grep for those.
- **Dynamic imports** — `import('./mod')` calls aren't traced.
- **Cross-language** — TypeScript / TSX only. Python / Rust / Go / SQL stay grep territory.

For string-literal scans, run grep alongside this tool. The two together cover the full surface.

## Performance

Cold-load on a ~200 TS/TSX file project: ~1.5s per query. ~700-file projects: ~5-8s. The TypeScript compiler initializes once per CLI invocation, so repeated queries in one session each pay that cost.

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Faris-Alanazi](https://github.com/Faris-Alanazi)
- **Source:** [Faris-Alanazi/code-impact-radius](https://github.com/Faris-Alanazi/code-impact-radius)
- **License:** MIT
- **Homepage:** https://github.com/Faris-Alanazi/code-impact-radius

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-faris-alanazi-code-impact-radius-code-impact-radius
- Seller: https://agentstack.voostack.com/s/faris-alanazi
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.