Core Concepts

How Shimpilot works

Seven concepts make up the pipeline from an upstream API change to a reviewable pull request. Each is a real, distinct stage in the system — nothing here is a marketing simplification of a step that doesn't actually exist.

API Change Intelligence

The current Stripe adapter combines curated compatibility rules with scheduled checks of official stripe-node GitHub releases. Release requests use conditional HTTP headers (ETag / Last-Modified) and exponential backoff. Every detected change is normalized into a common shape, fingerprinted for deduplication, and classified by type, severity, and confidence. The provider model can represent OpenAPI diffs, but the live Stripe adapter does not yet ingest a Stripe OpenAPI feed.

Dependency Graph

Each connected repository is scanned with an AST parser (ts-morph) that resolves API client instances and every call site against them — provider, resource, operation, file, line, and enclosing function. This is deterministic static analysis, not a guess based on regex or string matching.

Impact Analysis

When a new change is detected, Shimpilot queries the dependency graph — by an indexed lookup on the affected provider, never a full re-scan of every repository — and classifies each match as directly affected, possibly affected, indirectly affected, not affected, or unknown, with an explanation and evidence trail for every verdict.

Risk Scoring

A deterministic formula combines whether the change is breaking, its severity, how many repositories and call sites it affects, how soon it takes effect, and how confident the impact classification is, into a score mapped to five risk levels: Informational, Low, Medium, High, and Critical. No part of this score comes from an AI model.

Migration Candidates

A confirmed, risk-scored impact becomes a migration candidate, which your organization's migration policy evaluates: automatically queue it, require human approval, restrict automation to low-risk or high-confidence cases only, or block automation entirely.

Validation

Before a pull request is opened, a generated patch runs through AST validation, a TypeScript typecheck, the repository's own test suite where available, and a rescan to confirm the original breaking pattern is actually gone. Any failure blocks the pull request.

Draft Pull Requests

A validated migration is committed to a new branch and opened as a Draft pull request, with the detected change, the affected call site, the risk assessment, and the validation results attached for your team to review.