RepoRipple

RepoRipple

在合并前，了解代码变更可能造成的影响。

RepoRipple 是一款本地优先的变更影响分析工具，面向工程师和编码 Agent。它会根据代码仓库构建轻量级依赖关系图，读取当前 Git 差异，追踪反向依赖，推荐相关测试，并生成可用于代码评审的 Markdown 或 JSON 报告。

确定性分析无需 API 密钥、托管服务、上传源代码或集成框架。你也可以明确选择使用 OpenRouter 生成解释，将匿名化的证据转化为简短说明，而不会改变底层分析结果。

PyPI · 作品集案例研究 · MCP 配置 · v0.4.0 版本发布

为什么选择 RepoRipple？

代码图可以说明代码仓库各部分之间的联系。RepoRipple 将这张图用于你当前的变更：

• 哪些文件依赖我修改的代码？
• 影响范围会扩展多远？
• 哪些测试最相关？
• 我是否改动了身份验证、支付、部署或其他敏感区域？
• 是否应该阻止此拉取请求，要求进行额外评审？
• 我应该向编码 Agent 提供哪些结构化上下文？

安装并运行

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

# 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

无需安装即可运行一次：

uvx reporipple . --base origin/main

三种产品形式

形式	最适合的用途	输出
CLI	本地评审、脚本和 CI 门禁	Markdown 或 JSON 影响报告
GitHub Action	拉取请求证据和风险阈值	作业摘要、构建产物和可选的固定拉取请求评论
MCP 服务	Codex、OpenCode、Cursor、Claude Code 和 VS Code	类型化的 forecast_change 和 analyze_worktree 工具

GitHub Action

将 RepoRipple 添加到拉取请求工作流，即可生成 Markdown 和 JSON 影响报告，并将 Markdown 报告追加到 GitHub 作业摘要中：

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@6253b03f91e46c2f38fb2e05958dbc174d6a08d7 # v0.4.0
        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 }}

此 Action 接受 path、base、max-depth、fail-on 和 reports-directory。它会输出 markdown-report、json-report 和 risk-level。为确保构建可复现，请将 RepoRipple 固定到某个版本发布的提交 SHA，并设置 fetch-depth: 0，以便获取指定的基础版本。

本仓库自身的拉取请求工作流展示了一种可安全用于分支的评论设计。分析任务仅具有只读的内容访问权限。单独的任务仅在分支属于同一仓库时更新一条固定的 RepoRipple 评论；来自分叉仓库的拉取请求则仅在作业摘要和可下载的构建产物中保留报告，不会收到具有写入权限的令牌。

编码 Agent 工具（MCP）

RepoRipple 可以通过本地只读 MCP 服务，将相同的确定性分析提供给 Codex、OpenCode、Cursor、 Claude Code 和 VS Code。在源代码检出目录中：

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

无需克隆即可启动已发布的软件包：

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

该服务提供用于分析拟议编辑的 forecast_change，以及用于分析实际 Git 变更的 analyze_worktree。有关客户端专属的命令和配置，请参阅 MCP 设置指南。

架构指南介绍了 CLI、GitHub Action、 MCP 服务和可选解释层如何共用一个确定性分析引擎。

报告示例

# 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`

工作原理

1. 查找 Python、JavaScript 和 TypeScript 源文件。
2. 使用标准库 AST 提取 Python 导入，并使用专用解析器提取 JS/TS 导入。
3. 按确定性顺序解析 JS/TS 依赖：相对路径、最近的 tsconfig.json 或 jsconfig.json 中的 paths 映射、其 baseUrl，然后是根目录 package.json 中声明的 npm/Yarn 工作区 软件包。
4. 记录哪些 JS/TS 文件受项目配置和软件包清单管理。
5. 构建涵盖源代码和元数据的正向及反向依赖关系。
6. 从显式指定的基准版本或本地工作树中获取新增、修改、删除和重命名的文件。
7. 保留已删除和重命名文件变更前的源代码及解析器元数据，以便继续追踪其剩余的依赖项。
8. 按可配置的深度遍历依赖项。
9. 添加测试建议、文档提醒和确定性风险信号。

仅更改配置也会产生明确的影响范围。每个 JS/TS 源文件都会关联到最近的 tsconfig.json 或 jsconfig.json、该配置文件本地的 extends 链，以及最近的有效 package.json。当 Git 提供已删除或重命名的清单时，RepoRipple 会保留当前有效边界下方最近的历史软件包边界，作为第二个影响目标，同时不让它遮蔽该有效祖先。已删除的项目配置同样会保留为影响目标，但不能为当前代码树提供别名或 baseUrl，即使有效配置仍在 extends 中引用它也是如此。对于不带扩展名的 extends，优先使用有效的回退配置，同时将已删除的候选项保留为直接历史元数据。不会遍历已删除的配置链；这样可避免过时的历史数据占用本应留给有效依赖图的工作量。成功匹配的工作区导入还会关联到根工作区清单和被导入软件包的清单；无关的外部导入则不会关联。更改这些元数据中的任何一项时，会先报告直接受其管理或依赖它的源文件，再继续追踪其下游导入方。元数据不计入源文件清单，但其确定性关系会计入报告中的图边数量。

工作区解析在本地进行，并考虑源代码。RepoRipple 会将导入匹配到 package.json 中明确声明的工作区，遵守其公开导出边界，并跟踪解析到仓库内源文件的入口点。工作区 glob 支持递归模式、有限范围内的花括号备选项和范围，以及排除项。条件导出会区分 ES 模块和 CommonJS 入口点：.mts/.mjs 使用 import 配置，.cts/.cjs 使用 require 配置；对于无法明确判断的 TypeScript/JavaScript 文件，则会谨慎地同时检查两者。RepoRipple 还会保留在语法或 default 回退条件之前声明的适用自定义条件，避免遗漏浏览器、平台或仅限源代码的依赖关系。 自定义条件的评估不会假设只有一组运行时条件。因此，嵌套或重复的自定义条件可能会产生保守的额外边，这些边不会被任何单一运行时选中；影响分析倾向于保留这种明显的过度近似，而不是默默漏掉依赖项。

RepoRipple 不会检查已安装的 node_modules、联系注册表或运行包管理器。目前不会解析 pnpm-workspace.yaml、外部包，以及仅以被忽略或缺失的构建产物形式存在的工作区入口点。超出解析器固定安全预算的异常工作区 glob 集合会直接失败关闭，而不会消耗无上限的扫描时间。当前限制为：512 个有效模式、唯一模式合计 2,048 个路径组件、原始模式总计 64 KiB，以及大括号展开后 256 KiB。项目配置遍历限制为 16 层、每次根解析最多加载 64 个配置节点，以及每个源文件最多 64 个配置元数据依赖项。一次仓库扫描最多存储 100,000 个唯一的源文件到元数据关系。扫描警告会指出超出的每项限制；已完成的顶层配置解析会被重用，但不会绕过 extends 遍历中的循环或深度检查。在每个源文件的元数据上限内，已加载的有效配置路径优先；其次是已跳过的有效目标，直接的历史目标则使用剩余容量。对 tsconfig.json、jsconfig.json 和包清单的更改既会被标记为配置风险，也会沿其管理或依赖的 JS/TS 文件追踪。已删除或重命名的元数据会使用与已删除源文件相同的有界内存 Git 覆盖层。对于原地编辑工作区清单、并完全移除旧包名的情况，RepoRipple 仍可报告由该包拥有的文件，但如果不再进行一次完整历史扫描，就无法还原引用该已移除名称的导入方。

核心有意避免 LLM 评分。结果始终可复现、私密、快速，并且适用于 CI。可在 JSON 输出之上叠加可选的 AI 解释，而不让正确性依赖模型。

可选的 OpenRouter 说明

AI 说明默认关闭，只有使用 --explain 才会启用。即使 OpenRouter 不可用或返回无效响应，确定性风险级别、证据、报告以及 --fail-on 退出状态仍具有权威性。

请先检查将离开你设备的确切请求正文，其中不包含密钥：

reporipple /path/to/repository --base main --explain-preview

预览不会读取 API 密钥，也不会发起网络请求。确认载荷无误后，通过环境变量提供密钥，并明确请求生成说明：

export OPENROUTER_API_KEY="your-key"
reporipple /path/to/repository --base main --explain

没有命令行密钥选项，RepoRipple 也不会从文件读取密钥。此集成仅使用 Python 标准库，并对每个请求应用以下所有控制措施：

• 不会传输仓库名称、路径、源代码、差异、扫描器警告文本和用户标识符。
• 文件和风险信号会转换为不透明的证据 ID，例如 E001；返回的 ID 会经过架构验证，并在本地映射回标签。
• 响应必须符合严格的 JSON Schema；未知证据 ID 或额外字段都会被拒绝。
• OpenRouter 路由要求零数据保留（zdr: true）、拒绝数据收集，并且只选择支持所有请求参数的提供方。
• 提供方价格上限为每百万输入 token $0.25、每百万输出 token $1，响应上限为 450 个 token。
• 请求超时时间为 10 秒；收到明确可重试的 HTTP 响应后，最多重试一次；网络超时情况不明确时不会重试。
• Markdown 和 JSON 输出中会包含 token 用量和报告的请求成本。

固定的默认模型为 openai/gpt-6-luna。可通过 --explain-model 或 REPORIPPLE_OPENROUTER_MODEL 覆盖；隐私、架构和价格控制仍是强制要求。隐私 筛选可能会减少可用提供方的数量；如果没有符合条件的提供方满足这些要求，请求将以失败关闭。OpenRouter 的 ZDR 政策可防止符合条件的提供方在处理后保留提示词和响应；但这并不意味着请求始终留在你的设备上。请参阅 OpenRouter 的 结构化输出、 ZDR 控制和 提供方路由控制。

CLI 参考

reporipple [PATH]
  --version             show the installed RepoRipple version and exit
  --base REVISION       compare REVISION...HEAD
  --changed PATH        analyze an explicit path; repeat as needed
  --max-depth N         reverse dependency traversal depth (default: 4)
  --format markdown|json
  --output FILE
  --fail-on medium|high
  --explain             request an optional privacy-filtered OpenRouter explanation
  --explain-preview     show the exact sanitized request without sending it
  --explain-model NAME  use a pinned provider/model slug for either explanation mode

reporipple mcp
  --root PATH            restrict tool access to PATH and its descendants

未提供基准或明确路径时，RepoRipple 会分析已暂存、未暂存和未跟踪的文件。在干净的检出状态下，它会回退到最新提交。

--explain 和 --explain-preview 不能同时使用。使用 JSON 输出时，任一标志都会返回一个包含 deterministic_report 以及说明或预览的包装对象；普通 JSON 输出保持不变。

支持的分析

能力	状态
Python 绝对导入和相对导入	支持
JavaScript/TypeScript 相对导入	支持
JavaScript/TypeScript paths 和 baseUrl 别名	支持
npm/Yarn package.json 工作区包导入	支持
配置和包清单变更影响	支持
已删除和已重命名的源文件	支持
反向依赖路径	支持
测试文件建议	支持
Markdown 和 JSON 报告	支持
基于风险的 CI 退出码	支持
面向编码 Agent 的 MCP 工具	支持
经隐私筛选的 OpenRouter 说明	可选
pnpm-workspace.yaml 和外部包解析	不支持
Go、Rust 和 Java 导入	计划支持
GitHub 拉取请求报告和评论	支持

开发

uv venv --python 3.12
uv pip install --python .venv/bin/python -e ".[dev]"
.venv/bin/ruff check .
.venv/bin/pytest
uv build

隐私与安全

RepoRipple 的确定性分析在本地运行，不会传输仓库内容。它通过参数数组而非 Shell 调用 Git，并且只读取常见生成目录和依赖目录之外受支持的非符号链接源文件。MCP 服务会将每个仓库请求限制在其配置的 --root 范围内，并且只提供只读工具。只有在指定 --explain 时才会访问网络；--explain-preview 完全在本地运行，因此可以先审核出站请求正文。

许可证

MIT