quality-gates

用途

Quality Gates 是一套质量门禁规范，目标是把所有机器可检查的项固化为每次变更都会执行的 CI 检查，并保证本地与 CI 使用同一套配置和命令。资料明确指出：只在有人记得时才运行的检查只是建议；检查失败时应改代码，而不是放宽检查。

核心原则

文档给出“最高指令”：绝不禁用、跳过或放宽检查来让它通过，没有例外、变通或捷径。

主要能力：八类门禁

Lint：零错误零警告，任何警告或错误即失败。
类型检查：严格模式、零错误，任何类型错误即失败。
测试与覆盖率：测试套件通过，覆盖率只升不降（棘轮），测试失败或覆盖率低于记录下限即失败。
构建：干净构建、零警告，非零退出码或任何警告即失败。
体积预算：打包产物或二进制在约定预算内，超预算即失败。
依赖审计：无已知高危或严重漏洞，存在未记录决策的高危或严重通告即失败。
复杂度：函数复杂度低于约定阈值，超出即失败。
死代码：无未使用的文件、导出或依赖，出现即失败。

使用方式

资料给出的流程包括：盘点项目现有脚本与配置，列出已配置哪些门禁及阈值；本地运行每个已配置门禁并记录输出与退出码；在代码中修复失败项；按表顺序逐个添加缺失门禁，每次提交一个，前一个变绿后再加下一个；让 CI 强制执行与本地相同的命令，并将任务设为必需状态检查；当有人要求放宽门禁时，带着证据提交用户决策，合理的规则修改需在配置中注明原因并作为公开评审的变更。

文档还提供了各门禁的具体命令示例：

Lint：eslint . --max-warnings 0 --report-unused-disable-directives；Python 用 ruff check ..。
类型：TypeScript 开启 "strict": true 等选项并运行 tsc --noEmit；Python 用 mypy --strict 或 pyright 严格模式。
覆盖率：Jest 的 coverageThreshold.global；Vitest 的 coverage.thresholds 及 autoUpdate: true；pytest 的 pytest --cov --cov-branch --cov-fail-under=<floor>。
体积：如 size-limit 在 package.json 中配置 path 与 limit。
依赖审计：npm 用 npm audit --audit-level=high，Python 用 pip-audit，Go 用 govulncheck ./...，Rust 用 cargo audit。
复杂度：ESLint complexity 规则设 max，或 Ruff 的 C901 与 lint.mccabe.max-complexity。
死代码：npx knip；Python 用 vulture <package> --min-confidence 80。

资料还包含一份 GitHub Actions 工作流示例，将 Lint、类型、测试覆盖率、构建、体积、依赖审计、死代码串成一个任务，并建议将其设为主分支的必需状态检查。

适用场景

新项目或新 CI 流水线搭建；提交、拉取请求或合并前在本地运行门禁并阅读输出；CI 或本地门禁失败时；任何人提议关闭规则、添加抑制注释、降低阈值或跳过 CI 时。资料同时指出不应跳过的情形：已有项目中不存在“跳过”，一次性试验项目中需与用户约定适用哪些门禁并说明。

限制与注意事项

资料要求：不得在门禁为红或跳过的情况下合并，不得将门禁标记为非必需以解除阻塞，不得让新门禁一落地就失败；未在本次会话运行过的门禁不得声称通过；不得凭记忆把工具名称、参数或版本写入项目配置，应查阅当前文档。覆盖率衡量的是执行到的代码而非检查强度，不能替代测试优先实践。依赖审计发现无修复版本时，需用户记录决策（接受至某日期、替换或移除功能），而非静默忽略。