officefloor/ImpactGate

来源：https://github.com/officefloor/ImpactGate

impact-gate

测量并管控代码变更引入的结构退化。可作为独立CLI运行、作为git预提交钩子使用，或集成至GitHub、GitLab和Jenkins CI的插件中。

官网：https://impactgate.officefloor.net

结构退化是指在现有结构中不断累积的复杂性。一个“上帝方法“又长出分支，一个“上帝类“又新增方法。该门禁通过变更影响度量，将变更与基准（默认为main）进行评分比较：

impact = files_changed * Σ max(WMC_other, 1) * CC * Δlines      (统计所有变更函数)

WMC_other表示你正在编辑的容器中已有的复杂度，基于变更前的状态测量。因此引入全新文件或类的成本很低（原先无任何内容），而在本已复杂的类上继续堆积代码成本则很高——这正是退化信号。

关于公式背后的设计原理，请参阅OfficeFloor博客文章《测量变更的爆炸半径》(https://blog.officefloor.net/2026/08/measuring-blast-radius-of-change.html)。

当影响值过高时，门禁会要求简化变更或重构触及的代码。支持两种模式：警告（仅报告）或阻断（构建失败）。

安装

pip install impact-gate         # 安装 `impact-gate` 命令

或无需安装，直接通过发布的Docker镜像运行（内置git；将待评分仓库挂载至/repo）：

docker run --rm -v "$PWD:/repo" ghcr.io/officefloor/impact-gate \
  score --mode range --base origin/main

若需本地开发，可从检出代码安装：

python -m venv .venv && . .venv/bin/activate
pip install -e '.[dev]'         # 可编辑安装并包含测试依赖

使用方法

# 即将提交的变更（预提交）：暂存区 vs HEAD（默认模式）
impact-gate score

# 未提交的本地修改：工作树 vs HEAD
impact-gate score --mode worktree

# CI或PR审查：已提交分支 vs main（merge-base..HEAD）
impact-gate score --mode range --base origin/main --format json

# 设置阈值和执行策略（也可在.impact-gate.yml中配置）
impact-gate score --warn-at 50000 --block-at 200000 --enforcement block

退出代码说明：0表示通过或警告（允许变更），2表示被阻断（在--enforcement block模式下影响值过高），1表示使用或环境错误。

每份报告都会列出建议重构的文件，并按其影响占比排序。变更级的数字决定是否门禁；而文件级的排名则指出退化集中的位置——某个悄然膨胀为上帝类的文件会在阻断任何构建前先被标记出来。

源文件的差异行数若超过max_diff_lines（默认200，000行，可在度量配置中调整），通常是生成的代码转储或第三方依赖库。门禁会跳过此类文件，既避免数据失真也不拖慢评分过程，并在已跳过分类下列出，确保结果不会静默出错。

作为git预提交钩子使用

在CI之前对每个本地提交进行门禁检查：

# 安装 .git/hooks/pre-commit。每次提交时会对暂存变更评分
impact-gate install-hook

在.impact-gate.yml中设置enforcement: block时，影响值过高的提交将被阻止；设置为warn（或关闭）时则仅打印报告并继续提交。使用--force可覆盖已存在的预提交钩子。

若偏好pre-commit框架（https://pre-commit.com），本仓库提供了钩子定义——添加至.pre-commit-config.yaml即可：

repos:
  - repo: https://github.com/officefloor/ImpactGate
    rev: v0.3.0
    hooks:
      - id: impact-gate

基于分布曲线分级评分

原始阈值难以设定：不同语言和项目中典型变更的复杂度可能相差数个数量级。无需猜测具体数值，改为根据变更在分布中的百分位进行分级，并基于百分位实施门禁。

# 根据合并历史构建（或刷新）项目的影响分布
# 生成 .impact-gate-baseline.json。随分支推进可重复运行
impact-gate baseline --base-ref main

# 基于分级而非绝对数值进行门禁
impact-gate score --curve --warn-percentile 90 --block-percentile 98

分级综合了两类分布：

• 种子先验分布（工具内置）：基于20个开源仓库构建的各语言百分位表，未收录语言采用合并回退值；
• 项目基线：仓库自身从合并主线（仅统计已合并工作，不涉及进行中分支）提取的变更影响分布。

混合权重公式为 w = n / (n + K)，其中n是基线背后的已合并变更数，K（即curve_prior_weight，默认200）代表信任项目数据而非种子数据所需的历史深度。无基线文件的新仓库仅基于种子分布评分；深厚历史的项目则主要依赖自身数据。分级结果会随原始数值一同显示在各格式报告中。

通过.impact-gate.yml配置（仓库根目录）

warn_at: 50000          # 超过此影响值触发警告
block_at: 200000        # 超过此影响值触发阻断
enforcement: warn       # off、warn 或 block。建议先用 warn，准备就绪后切换为 block
tolerance: 1.0          # CI可调整的阈值乘数。大于1表示更宽松
# measure_config: .impact-measure.yml   # 可选：自定义忽略规则和语言配置

# 分级曲线（百分位门禁）。启用后 warn_at/block_at 将被忽略，改用以下百分位配置
curve_enabled: false           # 启用百分位分级替代绝对值
warn_percentile: 90            # 达到或超过此级别触发警告
block_percentile: 98           # 达到或超过此级别触发阻断
curve_prior_weight: 200        # 混合权重公式中的 K 值
baseline_file: .impact-gate-baseline.json   # 基线分布缓存路径

命令行参数会覆盖配置文件设置。CI作业可传递--tolerance或--warn-at参数，团队无需修改仓库即可调整容差。曲线相关参数同样支持命令行配置：--curve、--warn-percentile、--block-percentile、--baseline-file。

在GitHub Actions中使用

在仓库中添加工作流。该Action会对PR分支与基准分支进行评分，并生成摘要。必须设置fetch-depth: 0以确保基准分支和合并基点存在。

name: 变更影响分析
on: pull_request
permissions:
  contents: read
  pull-requests: write         # 允许Action在PR中发布评分评论
jobs:
  impact:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
        with:
          fetch-depth: 0
      - uses: officefloor/ImpactGate@v0
        with:
          enforcement: warn        # 准备就绪后改为 block
          # warn-at: 50000
          # block-at: 200000
          # tolerance: 1.0

评分结果将显示在作业摘要中，并以持久评论形式出现在PR中（每次运行更新同一评论）。在block模式下，影响值超过阻断阈值时作业将失败。在分支保护规则中将此检查设为必需即可实现合并门禁。评论功能需要pull-requests: write权限；若缺少此权限，运行仍会通过但会跳过评论。

在GitLab CI中使用

现成的作业配置位于ci/gitlab-ci.yml。复制至你的.gitlab-ci.yml，或远程引用：

include:
  - remote: 'https://raw.githubusercontent.com/officefloor/ImpactGate/v0/ci/gitlab-ci.yml'

该作业在合并请求流水线中运行，使用发布的Docker镜像对MR与其基准（$CI_MERGE_REQUEST_DIFF_BASE_SHA）进行评分。当设置了具有api范围的GITLAB_TOKEN变量时，会在MR中发布持久注释（每次运行更新同一注释）。缺少Token时仍会执行评分和门禁，仅跳过注释。在block执行模式下，影响值过高会导致作业失败；在合并请求设置中将其设为必需即可实现合并门禁。

在Jenkins中使用

流水线片段位于ci/Jenkinsfile。它会在配置了Docker的代理节点上运行Docker镜像，对变更与其目标分支（origin/${CHANGE_TARGET:-main}）进行评分，并归档报告。在block执行模式下，影响值过高会导致该阶段失败。将评分结果回传至PR/MR由你的SCM集成处理；若需使用工具本身发布评论，可在容器中运行impact-gate comment并配置提供商的Token和环境变量。

路线图

• 核心CLI。支持暂存区、工作树或范围模式评分。提供警告/阻断模式。支持文本、JSON、Markdown格式。已完成。
• GitHub Action。组合式操作、作业摘要报告和持久PR评论。已完成。
• 基线与分级曲线。impact-gate baseline分析项目历史；门禁系统融合种子语料库先验与项目自身分布，按百分位对变更分级（score --curve）。已完成。
• 分发。通过pip install impact-gate安装，提供适用于任意CI的ghcr.io/officefloor/impact-gate Docker镜像，以及版本标记的Action（@v0）。已完成。
• 更多CI插件。GitLab CI模板和Jenkins流水线片段，均封装Docker镜像（ci/gitlab-ci.yml、ci/Jenkinsfile）。GitLab支持发布持久MR注释。已完成。
• 钩子。impact-gate install-hook安装git预提交钩子，.pre-commit-hooks.yaml支持pre-commit框架。已完成。
• IDE集成。基于LSP的编辑器集成，编辑时提供实时复杂度监测。