Krater — Trace the Impact of a Variable, Not Just Its References

Krater is a semantic impact analyzer for TypeScript and React codebases.

Instead of showing you every reference of a symbol, Krater answers a more useful question:

“If I change this value, what actually gets affected?”

It does this by combining:

• TypeScript language intelligence (via VS Code)
• AST-aware semantic rules
• A bounded, explainable traversal engine

Why Krater Exists

Modern TypeScript + React codebases are full of patterns like:

const user = useUserStore(s => s.user);
return user?.profile?.name;

Traditional “Find All References” will:

• show everything
• mix reads, writes, JSX, props, effects
• give no sense of impact

Krater focuses on value flow, not textual references.

Quickstart

1. Place cursor on a variable / symbol
2. Run “krater: Estimate Impact” (command palette or editor right‑click)
3. Explore impacted files in the Krater side panel
4. Click any node to understand why it’s impacted and trace the path back to the root

Tip: If you want smaller / faster graphs, tune krater.maxDepth, krater.maxFiles, krater.maxHits, and krater.maxSeconds in settings.

What Krater Does (Conceptually)

Krater builds a directed graph where:

• Nodes = meaningful symbol instances
• Edges = semantic propagation (assign, return, etc.)

Example:

store.user
   └── assign → user
          └── return → profileName

This lets you:

• understand why a file is affected
• see how a value travels
• stop traversal once meaning is lost

TypeScript- and React-Specific by Design

Krater is not a generic static analysis tool.

It is intentionally opinionated:

Supported today

• TypeScript (.ts)
• TypeScript React (.tsx)
• Common React patterns:
  • hooks
  • store selectors
  • JSX usage
  • optional chaining
  • assignments & returns

Explicitly not supported (yet)

• JavaScript without types
• Python / Java / other languages
• Arbitrary CFG / full data-flow analysis
• Runtime execution tracing

This focus allows Krater to be:

• fast
• predictable
• explainable

How Krater Is Structured (High Level)

Krater is built with strict boundaries:

1. Engine (VS Code–dependent)

• Talks to VS Code APIs
• Resolves references & definitions
• Controls traversal limits
• Records the trace graph

VS Code exists only here

2. Rulesets (Language-specific, no VS Code)

• Operate on neutral types (Doc, Loc, Pos)
• Use AST to decide:
  • should this reference propagate?
  • how should it propagate?
• Encapsulate language semantics

Examples:

• TsRuleset — TypeScript semantics
• TsxRuleset — React / JSX guards

3. View Providers

• Render results as:
  • tree view
  • list view
• Allow “explain this path” interactions

What Makes Krater Different

Krater is closer to:

• blast radius analysis
• semantic tracing
• “why did this break?”

Than to traditional navigation tools.

Bounded by Design

Krater always runs with limits:

• max depth
• max hits
• max files
• max time

This is intentional.

Krater prefers:

A small, explainable graph over An exhaustive, noisy one

Current Status

• ✅ Stable for TypeScript & React codebases
• ✅ Engine and rulesets cleanly separated
• ⚠️ Ruleset coverage improving
• 🚧 More React-specific rules planned

Non-Goals (Important)

Krater does not aim to:

• replace compilers
• perform full data-flow analysis
• execute code
• understand runtime values

It is a developer-experience tool, not a verifier.

Who Krater Is For

• Senior engineers navigating large TS/React codebases
• Architects assessing change impact
• Anyone who has ever asked:

  “Why is this file affected by my change?”

Philosophy

Contain complexity.
Make meaning explicit.
Stop when semantics stop.