Technical walkthrough

From a Git comparison to an impact map

PatchRipple starts with two exact revisions and builds a bounded static graph of files that may be related to a change. The report keeps the evidence and uncertainty visible so a reviewer can decide what deserves attention.

This page describes the tool's static scope. A candidate is a review lead, not proof of runtime impact, test coverage, or safety.

1. Choose the two revisions

The CLI accepts full Git commit IDs for the base and head. It reads Git objects in the target repository and writes a new report directory outside that repository. The GitHub Action workflow obtains and checks the pull request's exact base and head objects on its runner; it does not check out the PR head or run scripts from the target repository.

node dist/cli.cjs analyze \
  --repo /path/to/target \
  --base BASE_COMMIT --head HEAD_COMMIT \
  --repository https://github.com/owner/repo \
  --out /path/outside/target

The output is a self-contained set of index.html, graph.json, graph.svg, and metadata.json files. Open the HTML locally; it has no external assets or data fetches.

2. Resolve static relationships

PatchRipple reads supported JavaScript, TypeScript, and Python import forms from both revisions. Its bounded resolver follows literal imports, re-exports, documented local TypeScript path settings, declared workspaces, and a limited static subset of package exports. It does not execute configuration, install target dependencies, or ask a build system to infer a graph.

The comparison walks backward from changed paths to potential importers. It can also surface tests from import evidence or documented adjacent-name conventions, and owner labels from the supported subset of CODEOWNERS rules.

3. Inspect the evidence

Base and head controls keep revision-specific relationships separate.
Runtime and type-only edges can be filtered independently.
Search keeps nearby chain context visible; selecting a file shows its relationships, owners, test reasons, and exact-revision links when available.
Warnings identify unresolved imports, unsupported configuration, parser uncertainty, and resource limits.

Related-test labels describe why a file was suggested. They do not mean the test was run. The graph and its ceilings bound what was inspected; a small graph is not proof that no other runtime dependency exists.

4. Keep the report in context

The CLI can produce the bundle locally. In the sample pull-request workflow, the Action runs with read-only repository permission and uploads the generated bundle as a GitHub Actions artifact. That artifact can contain repository paths and CODEOWNERS labels, so use the repository's normal access controls before sharing it. PatchRipple does not post comments or change the pull request.

Current release state: the interactive report here is synthetic, with fictional repository names and commit IDs. The GitHub Action has not been released or listed in Marketplace yet; the sample workflow intentionally contains a commit placeholder.

Try it

Explore the synthetic report · Follow the guided demo · Read the trial steps · View the source repository