pi-impact-analyzer

If I change this symbol, what else could break?

🚀 What's New in v0.3.0

Passive mode — No configuration required! The extension now works out-of-the-box:

• ✅ Auto-indexes your project on session start
• ✅ Indexes files when Pi reads them
• ✅ Caches graph to disk for faster startup
• ✅ Auto-analyzes when you mention code changes
• ✅ Integrates with pi-smart-reader for optimized workflows

Problem Statement

When an AI agent modifies a function or class, it often lacks visibility into the full blast radius of that change. This leads to:

• Silent Breakage: Changes that compile but cause runtime failures in distant parts of the codebase
• Missed Call Sites: Modifying a function signature without updating all callers
• Test Gaps: Not knowing which test files need updating after a change
• Cascade Failures: A single change triggering a chain of regressions

Solution

pi-impact-analyzer provides AST-based dependency tracing that answers: "If I change this symbol, what else could break?"

The tool builds a call graph from the entire project using tree-sitter, then performs reverse-dependency traversal to identify all affected files and functions.

Key Features

🔍 Symbol Impact Analysis

Given a symbol name (function, class, method), return:

• All direct callers across the project
• All transitive callers (callers of callers)
• Risk score based on dependency depth and fan-in

📁 File Impact Analysis

Given a file path, return:

• All files that import from this file
• All transitive dependents
• Affected test files

📝 Diff Impact Analysis

Given a git diff (staged, unstaged, or raw content), return:

• Which symbols were modified (based on changed line ranges)
• The combined blast radius of all changes
• Affected test files and recommended test suites

⚡ Passive Mode (v0.3.0+)

No configuration required! The extension automatically:

• Auto-indexes your project on session start
• Indexes files when Pi reads them
• Caches graph to disk for faster startup
• Auto-analyzes when you mention code changes
• Emits events for integration with other tools

📊 Risk Scoring

Assigns risk scores to symbols based on:

• Fan-in: Number of direct callers (higher = riskier)
• Depth: Transitive dependency depth (deeper = more cascade risk)
• Centrality: PageRank-style importance in the call graph

🎯 Orphan Detection

Find symbols that are defined but never called, indicating dead code.

🌐 Language Support

• TypeScript (.ts)
• TypeScript with JSX (.tsx — React, JSX elements, generics)
• JavaScript (.js, .jsx, .mjs, .cjs)

Installation

pi install npm:pi-impact-analyzer

Usage Guide

Passive Mode (Recommended)

Just install and use! The extension automatically:

1. Indexes your project when Pi starts
2. Indexes files as Pi reads them
3. Analyzes impact when you mention code changes
4. Provides recommendations for affected files

No commands needed — it just works!

Active Tool

For explicit analysis, use the impact_analyze tool:

Before modifying a function

{
  "tool": "impact_analyze",
  "input": {
    "type": "symbol",
    "target": "processPayment",
    "options": { "maxDepth": 5, "format": "table" }
  }
}

Result: A table showing all affected symbols, their files, depth, and risk scores.

After making changes

Check the impact of your diff before committing:

{
  "tool": "impact_analyze",
  "input": {
    "type": "diff",
    "target": "unstaged",
    "options": { "format": "markdown" }
  }
}

Output Formats

Table format (human-readable):

Impact Analysis for: processPayment
==================================================

Summary:
  Total affected: 12
  Direct dependents: 4
  Transitive dependents: 8
  Test files: 3
  Risk score: 85.42

Affected Symbols:
--------------------------------------------------
  handleCheckout                    checkout.ts      depth:1 risk:85.4
  processOrder                      orders.ts        depth:2 risk:62.1
  sendConfirmationEmail             notifications.ts depth:3 risk:43.2

Markdown format (for documentation):

## Impact Analysis: `processPayment`

### Summary
| Metric | Value |
|--------|-------|
| Total affected | 12 |
| Direct dependents | 4 |
| Risk score | 85.42 |

JSON format (for programmatic use):

{
  "target": "processPayment",
  "type": "symbol",
  "summary": {
    "totalAffected": 12,
    "directDependents": 4,
    "transitiveDependents": 8,
    "testFiles": 3,
    "riskScore": 85.42
  },
  "affected": [...],
  "recommendations": [...]
}

Performance

| Metric | Value | |--------|-------| | Graph Build | 1ms/file | | Incremental Index | 21ms | | Impact Analysis | 0.01ms/symbol | | Throughput | 1988 files/second | | Hash Performance | 0.0166ms/hash |

Programmatic API

For use outside the Pi tool system, import the library directly:

import { 
  TreeSitterParser, 
  GraphBuilder, 
  ImpactAnalyzer,
  autoIndex,
  indexFile,
  getIndexingStatus
} from "pi-impact-analyzer";

// Initialize parser
const parser = new TreeSitterParser();
await parser.initialize();

// Build graph from project
const builder = new GraphBuilder(parser);
const files = scanProject("./src");
builder.build(files.map(p => ({ path: p, content: fs.readFileSync(p, "utf-8") })));

// Analyze impact
const analyzer = new ImpactAnalyzer(builder.getGraph());
const result = analyzer.analyzeSymbol("myFunction");
console.log(result.summary);

// Passive mode functions
await autoIndex(); // Auto-index current directory
await indexFile("path/to/file.ts", content); // Index single file
const status = getIndexingStatus(); // Get indexing status

Configuration

The extension works with sensible defaults. To customize:

import { updateConfig, getConfig } from "pi-impact-analyzer";

// Update configuration
updateConfig({
  autoIndex: true,
  cacheEnabled: true,
  cacheTTL: 300000, // 5 minutes
  debug: false,
});

// Get current config
console.log(getConfig());

Integration with pi-smart-reader

pi-impact-analyzer emits impact_detected events that pi-smart-reader listens to. When impact analysis is performed:

1. pi-impact-analyzer analyzes the symbol/file
2. Emits impact_detected event with affected files
3. pi-smart-reader pre-generates skeletons for affected files
4. Context is optimized for faster access

This integration happens automatically — no configuration needed!

Technical Architecture

• Engine: Powered by tree-sitter (WASM) for high-performance, language-aware parsing
• Graph Construction: Builds a complete call graph with import resolution
• Traversal: BFS reverse-dependency traversal for impact analysis
• Risk Scoring: Combines fan-in, depth, and PageRank centrality
• Auto-Indexing: Recursive filesystem scanner respecting common ignore patterns
• Caching: Disk-based graph caching with file hash tracking

Compatibility

• Languages: TypeScript (.ts), TypeScript+JSX (.tsx), JavaScript (.js, .jsx, .mjs, .cjs)
• Platforms: Node.js 18+ (runs as a Pi extension)
• Pi: Built for the Pi coding agent ecosystem

Contributing

Contributions are welcome. We are seeking support for:

• Additional language bindings (Python, Go, Rust)
• Incremental graph updates for real-time analysis
• Performance benchmarks at 10K+ files

Please follow the standard Pull Request process: Fork, Branch, Commit, and PR.

License

Distributed under the MIT License. See the LICENSE file for more information.

Acknowledgments

• Pi — The AI coding agent
• tree-sitter — Parser generator toolkit
• impact-graph — Inspiration for risk scoring
• codegraph — Inspiration for import resolution