💥 impact-scope

See the blast radius of your code changes

Import graph analysis and risk scoring for code reviews and PRs.

Import Graph + Risk Scoring + CI Gates

Quick Start | Features

Why This Exists

Code review tools show you what changed, but not what those changes will break. impact-scope scans your TypeScript/JavaScript project, builds an import dependency graph, and shows exactly which files are transitively affected when you touch a file. It assigns a risk score from 0 to 100 based on impact depth, affected file count, test coverage gaps, and change size -- so reviewers can prioritize attention on the changes that actually matter.

Requirements

• Node.js >= 18.0.0
• Git installed and available in PATH
• A TypeScript or JavaScript project with relative imports

Quick Start

As a CLI tool

# Install globally
npm install -g impact-scope

# Analyze the impact of your latest commit
impact-scope analyze

# Analyze changes against a specific base ref
impact-scope analyze --base main

# Check impact of changing a specific file
impact-scope check src/utils/math.ts

# View import graph statistics
impact-scope graph

As a library

npm install impact-scope

import {
  parseDiff,
  buildImportGraph,
  analyzeImpact,
  buildRiskReport,
  formatTerminal,
} from 'impact-scope';
import { execSync } from 'child_process';

// Get diff from git
const diffOutput = execSync('git diff HEAD~1', { encoding: 'utf-8' });

const graph = buildImportGraph('.');
const changedFiles = parseDiff(diffOutput);
const affected = analyzeImpact(changedFiles, graph, '.');
const report = buildRiskReport(changedFiles, affected);
console.log(formatTerminal(report));

CLI Commands

impact-scope analyze

Analyze the impact of code changes from a git diff.

| Option | Default | Description | |--------|---------|-------------| | --base <ref> | HEAD~1 | Base git ref for diff | | --threshold <n> | 50 | Risk score threshold for CI mode | | --format <type> | terminal | Output format: terminal, json, ci | | --root <path> | . | Project root directory |

impact-scope graph

Show import graph statistics (file count, edge count, most-imported files).

| Option | Default | Description | |--------|---------|-------------| | --root <path> | . | Project root directory |

impact-scope check <file>

Check the blast radius of changing a specific file without needing a diff.

| Option | Default | Description | |--------|---------|-------------| | --format <type> | terminal | Output format: terminal, json | | --root <path> | . | Project root directory |

Example Output

Terminal format

============================================================
  IMPACT SCOPE ANALYSIS
============================================================

  Risk Score: 42/100 (MEDIUM)
  [#########################---------------]

  Changed files:  1
  Affected files: 3
  Untested:       1

  Changed Files:
    +2 / -1  src/utils/math.ts

  Affected Files (by depth):
      depth 1: src/components/calculator.ts (add, multiply) [tested]
      depth 1: src/utils/index.ts (*) [tested]
      depth 2: src/app.ts [UNTESTED]

  Untested Affected Files:
    ! src/app.ts

============================================================

JSON format

{
  "score": 42,
  "level": "medium",
  "changedFiles": [
    { "path": "src/utils/math.ts", "additions": 2, "deletions": 1, "hunks": [{ "startLine": 1, "endLine": 6 }] }
  ],
  "affectedFiles": [
    { "filePath": "src/components/calculator.ts", "depth": 1, "affectedSymbols": ["add", "multiply"], "hasTests": true },
    { "filePath": "src/utils/index.ts", "depth": 1, "affectedSymbols": ["*"], "hasTests": true },
    { "filePath": "src/app.ts", "depth": 2, "affectedSymbols": [], "hasTests": false }
  ],
  "untestedAffected": ["src/app.ts"],
  "summary": "Risk Score: 42/100 (MEDIUM) | 1 changed file(s), 3 affected file(s), 1 untested, 3 line(s) changed",
  "details": [
    "--- Changed Files ---",
    "  src/utils/math.ts (+2/-1)",
    "--- Affected Files ---",
    "  depth=1 src/components/calculator.ts [tested]",
    "  depth=1 src/utils/index.ts [tested]",
    "    depth=2 src/app.ts [UNTESTED]",
    "--- Untested Affected Files ---",
    "  ! src/app.ts"
  ]
}

CI format

impact-scope: PASS
score: 42/100 (medium)
threshold: 50
changed: 1 files
affected: 3 files
untested: 1 files

How It Works

git diff --> parseDiff --> changedFiles
                              |
project root --> buildImportGraph --> importGraph
                                          |
changedFiles + importGraph --> analyzeImpact --> affectedFiles
                                                     |
changedFiles + affectedFiles --> buildRiskReport --> RiskReport
                                                        |
                                              formatTerminal / formatJSON / formatCI

Risk Scoring

The risk score (0-100) is computed from four weighted factors:

| Factor | Weight | Description | |--------|--------|-------------| | Affected file count | 30% | Number of transitively affected files (caps at 20) | | Max depth | 20% | Deepest level in the impact chain (caps at 5) | | Untested ratio | 30% | Fraction of affected files lacking test coverage | | Change size | 20% | Total lines added + deleted (caps at 500) |

Risk levels: low (0-25), medium (26-50), high (51-75), critical (76-100).

How Risk Scoring Works

The risk score quantifies how dangerous a set of code changes is to your project. Here is exactly how each factor is computed:

1. Affected File Count (30% weight) impact-scope walks the reverse import graph using BFS. Starting from each changed file, it finds every file that transitively depends on it. The raw count is divided by a cap of 20 files. If a utility module is imported by 15 files, changing it yields 15/20 = 0.75 for this factor.

2. Max Depth (20% weight) Depth measures how far the impact ripples through the dependency chain. A change affecting only direct importers has depth 1. If those importers are themselves imported, depth grows. The cap is 5 levels. Depth 3 yields 3/5 = 0.6.

3. Untested Ratio (30% weight) For each affected file, impact-scope checks whether a corresponding test file exists (e.g., src/foo.ts -> tests/foo.test.ts) or whether any test file in the import graph imports it. The ratio of untested affected files drives this factor. If 4 of 10 affected files lack tests: 4/10 = 0.4.

4. Change Size (20% weight) Total lines added + deleted across all changed files, capped at 500. A 60-line change yields 60/500 = 0.12.

Final score: (factor1 * 0.3 + factor2 * 0.2 + factor3 * 0.3 + factor4 * 0.2) * 100, rounded and clamped to [0, 100].

You can override the default weights by passing a custom ScoringWeights object to computeRiskScore() or buildRiskReport().

Understanding the Impact Graph

The import graph is a directed graph where each node is a source file and each edge represents an import statement:

math.ts  <--  calculator.ts  <--  app.ts
   |               ^
   v               |
format.ts --> index.ts

How the graph is built:

1. collectSourceFiles() recursively scans the project root for .ts, .tsx, .js, and .jsx files, skipping node_modules, dist, and .git directories.
2. extractImports() reads each file and uses regex patterns to extract five types of import/export statements:
   • import { x } from './path' (named imports)
   • import x from './path' (default imports)
   • import * as x from './path' (namespace imports)
   • export { x } from './path' (re-exports)
   • export * from './path' (star re-exports)
3. resolveImportPath() resolves relative import specifiers to actual file paths, trying each extension and index file resolution.

How impact is analyzed:

1. getReverseGraph() inverts the edges so each file maps to its importers.
2. analyzeImpact() runs BFS from each changed file through the reverse graph, recording the depth at which each affected file is reached.
3. Files at depth 0 (the changed files themselves) are excluded from the results.

Limitations:

• Only relative imports are resolved. Path aliases (@/utils/math) and bare module specifiers (lodash) are not tracked.
• Dynamic import() expressions are not detected.
• TypeScript paths configuration in tsconfig.json is not read.

GitHub Actions Integration

Add this workflow to .github/workflows/impact-scope.yml to run impact analysis on every PR:

name: Impact Scope Analysis
on:
  pull_request:
    branches: [main]
jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - run: npm run build
      - name: Run impact analysis
        run: npx impact-scope analyze --base origin/main --format ci --threshold 50

Integration Patterns

Danger.js

// dangerfile.ts
import { execSync } from 'child_process';

const output = execSync(
  'npx impact-scope analyze --base origin/main --format json',
  { encoding: 'utf-8' }
);
const report = JSON.parse(output);

if (report.score > 50) {
  warn(`Impact scope risk score: ${report.score}/100 (${report.level})`);
}
if (report.untestedAffected.length > 0) {
  const files = report.untestedAffected.map((f: string) => `- \`${f}\``).join('\n');
  warn(`Untested affected files:\n${files}`);
}
message(`**Impact Analysis:** ${report.summary}`);

GitHub PR Comment via Actions

- name: Run impact analysis
  id: impact
  run: |
    OUTPUT=$(npx impact-scope analyze --base origin/main --format json)
    echo "report<<EOF" >> $GITHUB_OUTPUT
    echo "$OUTPUT" >> $GITHUB_OUTPUT
    echo "EOF" >> $GITHUB_OUTPUT
  continue-on-error: true

- name: Comment PR
  uses: actions/github-script@v7
  with:
    script: |
      const report = JSON.parse(`${{ steps.impact.outputs.report }}`);
      const body = [
        '## Impact Scope Analysis',
        `**Risk Score:** ${report.score}/100 (${report.level.toUpperCase()})`,
        `**Changed:** ${report.changedFiles.length} files | **Affected:** ${report.affectedFiles.length} files | **Untested:** ${report.untestedAffected.length}`,
        '',
        report.untestedAffected.length > 0
          ? '### Untested Affected Files\n' + report.untestedAffected.map(f => `- \`${f}\``).join('\n')
          : '',
      ].filter(Boolean).join('\n');
      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body
      });

Programmatic API

import {
  parseDiff,
  buildImportGraph,
  analyzeImpact,
  buildRiskReport,
  formatTerminal,
  formatJSON,
  formatCI,
} from 'impact-scope';
import type { RiskReport } from 'impact-scope';

function analyzeChanges(diffOutput: string, projectRoot: string): RiskReport {
  const changed = parseDiff(diffOutput);
  const graph = buildImportGraph(projectRoot);
  const affected = analyzeImpact(changed, graph, projectRoot);
  return buildRiskReport(changed, affected);
}

// Render the report
const report = analyzeChanges(diffOutput, '.');
console.log(formatTerminal(report));            // colored terminal output
console.log(formatJSON(report));                // JSON string
const { output, exitCode } = formatCI(report, 50); // CI with threshold

API Reference

| Function | Description | |----------|-------------| | parseDiff(diffOutput) | Parse unified diff string into ChangedFile[] | | buildImportGraph(rootDir) | Scan project and build ImportGraph | | analyzeImpact(changed, graph, root) | Find transitively affected files via BFS | | analyzeFileImpact(filePath, graph, root) | Shorthand for single-file impact check | | computeRiskScore(changed, affected, weights?) | Compute 0-100 risk score | | getRiskLevel(score) | Map score to 'low'/'medium'/'high'/'critical' | | buildRiskReport(changed, affected, weights?) | Build complete RiskReport | | formatTerminal(report) | Render colored terminal output | | formatJSON(report) | Render as formatted JSON string | | formatCI(report, threshold) | Render CI output with { output, exitCode } | | checkTestCoverage(file, root, graph) | Check if a file has test coverage | | isTestFile(filePath) | Check if a path looks like a test file | | findTestFiles(graph) | Find all test files in the graph | | getReverseGraph(graph) | Get reverse dependency map |

Error classes: ImpactScopeError, DiffParseError, GraphBuildError, AnalysisError

Types: ChangedFile, ImportEdge, ImportGraph, ImpactNode, RiskReport, ScoringWeights

FAQ / Troubleshooting

"Error: Command failed: git diff HEAD~1"

No previous commit to diff against. Use --base to specify a valid ref:

impact-scope analyze --base main

"File not found in project"

The check command only works with files in the import graph (.ts, .tsx, .js, .jsx). Ensure:

• The file path is relative to the project root
• The file has a supported extension
• Use --root if running from outside the project directory

No affected files are found

This can happen when:

• The changed file is not imported by any other file (leaf/entry point)
• The project uses non-relative imports (path aliases) which are not yet resolved
• The changed file is not a .ts/.tsx/.js/.jsx file

License

MIT