RepoRipple

RepoRipple

Know what a code change can break before you merge it.

RepoRipple is a local-first change-impact analyzer for engineers and coding agents. It builds a lightweight dependency graph from a repository, reads the current Git diff, traces reverse dependencies, recommends relevant tests, and emits review-ready Markdown, JSON, or a standalone visual impact map.

The deterministic analyzer requires no API key, hosted service, source upload, or framework integration. An optional, explicitly requested OpenRouter explanation can turn its anonymized evidence into a short narrative without changing the underlying analysis.

PyPI · Portfolio case study · MCP setup · v0.6.0 release

Why RepoRipple?

Code graphs explain how a repository is connected. RepoRipple applies that graph to the change in front of you:

• Which files depend on the code I changed?
• How far does the blast radius travel?
• Which tests are most relevant?
• Did I touch authentication, payments, deployment, or another sensitive area?
• Should this pull request be blocked for additional review?
• What structured context should I give a coding agent?

Install and run

pip install reporipple

Analyze staged, unstaged, and untracked changes.

reporipple .

Compare a feature branch with main.

reporipple . --base origin/main

Generate machine-readable context for an agent or automation.

reporipple . --base origin/main --format json --output impact.json

Generate and open a self-contained visual blast-radius map.

reporipple . --base origin/main --format html --output impact.html --open

Create the Markdown, JSON, and visual reports together, then open the map.

reporipple . --base origin/main --format all --output reporipple-reports --open

Fail CI when a change reaches high risk.

reporipple . --base origin/main --fail-on high

Audit the exact anonymized OpenRouter request without sending it.

reporipple . --base origin/main --explain-preview

Run it once without installing:

uvx reporipple . --base origin/main

Three product surfaces

Visual impact map

--format html turns the same deterministic evidence into a portable review dashboard. The map lays out changed files, direct dependents, transitive dependents, and suggested tests from left to right, then keeps the complete review paths, risk signals, and verification list below it.

reporipple . --base origin/main --format html --output impact.html --open

Use --format all --output reporipple-reports to create impact.md, impact.json, and impact.html from one repository scan. Adding --open opens the HTML map after writing the bundle.

The report has no external scripts, fonts, analytics, or network requests. Repository source code is never embedded; only the file paths and evidence already present in the standard report appear. Large results keep the full review list while limiting the visual canvas to 80 nodes. See the impact-map guide or run the included deterministic demo with ./scripts/demo-impact-map.sh.

Watch the 22-second impact-map demo — a silent, 720p recording generated from the included checkout fixture.

GitHub Action

Add RepoRipple to a pull-request workflow to create impact reports and append the Markdown report to the GitHub job summary. This immutable v0.6.0 example produces Markdown, JSON, and visual HTML:

name: RepoRipple

on: pull_request:

permissions: contents: read

jobs: impact: runs-on: ubuntu-latest steps:

• uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: fetch-depth: 0 persist-credentials: false
• id: reporipple uses: adiarora06/RepoRipple@de0ba8ff4059928cdf59481d4fb77989da482735 # v0.6.0 release source with: base: ${{ github.event.pull_request.base.sha }}
• uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 with: name: reporipple-impact path: | ${{ steps.reporipple.outputs.markdown-report }} ${{ steps.reporipple.outputs.json-report }} ${{ steps.reporipple.outputs.html-report }}

The Action accepts path, base, max-depth, fail-on, and reports-directory. Version 0.6.0 outputs markdown-report, json-report, html-report, and risk-level. The example is pinned to the release source commit rather than a mutable tag. When upgrading, replace it with the commit SHA for the desired release. Use fetch-depth: 0 so the requested base revision is available.

This repository's own pull-request workflow demonstrates a fork-safe commenting design. Analysis runs with read-only contents access. A separate job updates one stable RepoRipple comment only for branches in the same repository; fork pull requests keep their report in the job summary and downloadable artifact without receiving a write-capable token.

Coding-agent tools (MCP)

RepoRipple can expose the same deterministic analysis to Codex, OpenCode, Cursor, Claude Code, and VS Code over a local, read-only MCP server. From a source checkout:

uv run reporipple mcp --root /path/to/allowed/workspace

Launch the published package without a clone:

uvx reporipple mcp --root /path/to/allowed/workspace

The server provides forecast_change for proposed edits and analyze_worktree for actual Git changes. See the MCP setup guide for client-specific commands and configuration.

The architecture guide explains how the CLI, GitHub Action, MCP server, and optional explanation layer share one deterministic analysis engine.

Example report

# RepoRipple impact report: checkout-service

Risk: high · Graph: 84 files / 137 dependency edges

Changed files

• src/billing/store.py

Impacted files

• src/billing/service.py — distance 1 via store.py → service.py
• src/api/checkout.py — distance 2 via store.py → service.py → checkout.py

Suggested verification

• tests/test_billing_service.py
• tests/test_checkout.py

How it works

1. Discovers Python, JavaScript, and TypeScript source files.
2. Extracts Python imports with the standard-library AST and JS/TS imports with a focused parser.
3. Resolves JS/TS dependencies in a deterministic order: relative paths, the nearest tsconfig.json or jsconfig.json paths mappings, its baseUrl, and then npm/Yarn workspace packages declared by the root package.json.
4. Records which JS/TS files are governed by project configuration and package manifests.
5. Builds forward and reverse dependency relationships across source and metadata.
6. Gets added, modified, deleted, and renamed files from an explicit base revision or the local worktree.
7. Retains pre-change source and resolver metadata for deleted and renamed files so their remaining dependents can still be traced.
8. Traverses dependents to a configurable depth.
9. Adds test recommendations, documentation reminders, and deterministic risk signals.

Configuration-only changes now produce a concrete blast radius. Each JS/TS source is linked to its nearest tsconfig.json or jsconfig.json, that configuration's local extends chain, and its nearest live package.json. When Git supplies a deleted or renamed manifest, RepoRipple retains the nearest historical package boundary below the current live boundary as a second impact target without letting it shadow that live ancestor. A deleted project config likewise remains an impact target but cannot supply aliases or baseUrl for the current tree, including when a live config still names it in extends. For extensionless extends, a live fallback is preferred while a deleted candidate remains direct historical metadata. Deleted config chains are not traversed; this prevents stale history from consuming work needed for the live graph. Successfully matched workspace imports are additionally linked to the root workspace manifest and the imported package's manifest; unrelated external imports are not. Changing any of that metadata reports directly governed or dependent source files first, then continues through their downstream importers. Metadata remains outside the source-file inventory, while its deterministic relationships are included in the reported graph edge count.

Workspace resolution is local and source-aware. RepoRipple matches imports to explicitly declared package.json workspaces by package name, respects their public export boundaries, and follows entry points that resolve to source files in the repository. Workspace globs support recursive patterns, bounded brace alternatives and ranges, and exclusions. Conditional exports distinguish ES module and CommonJS entry points: .mts/.mjs use the import profile, .cts/.cjs use the require profile, and ambiguous TypeScript/JavaScript files conservatively inspect both. RepoRipple also keeps applicable custom conditions declared before a syntax or default fallback so it does not silently miss browser, platform, or source-only dependency edges.

Custom conditions are evaluated without assuming one runtime condition set. Nested or repeated custom conditions can therefore produce conservative extra edges that no single runtime would select; impact analysis favors that visible over-approximation over silently missing a dependent.

RepoRipple does not inspect installed node_modules, contact a registry, or run a package manager. pnpm-workspace.yaml, external packages, and workspace entry points that exist only as ignored or missing build output are not currently resolved. Pathological workspace glob sets that exceed the resolver's fixed safety budgets fail closed instead of consuming unbounded scan time. The current limits are 512 effective patterns, 2,048 aggregate path components across unique patterns, 64 KiB of raw patterns, and 256 KiB after brace expansion. Project-config traversal is limited to 16 levels, 64 loaded config nodes per root resolution, and 64 config metadata dependencies per source. A repository scan stores at most 100,000 unique source-to-metadata relationships. Scan warnings identify every exceeded limit, and completed top-level config resolutions are reused without bypassing cycle or depth checks