omen

复杂度分为两种：

• 圈复杂度统计代码中不同执行路径的数量。每个 if、for、while 或 switch 都会创建一条新路径。圈复杂度为 10 的函数意味着有 10 种不同的执行方式。数值越高，需要覆盖所有场景的测试用例就越多。

• 认知复杂度衡量代码对人类而言有多难读。它对深层嵌套的代码（例如 for 中的 if，再嵌套在另一个 if 中）比结构扁平的代码惩罚更重。两个函数的圈复杂度可能相同，但嵌套更深的函数认知复杂度会更高，因为更难理清代码的执行过程。

**为何重要：**研究表明，复杂代码更容易出现 Bug，也需要更长时间修复。McCabe 于 1976 年发表的原始论文发现，复杂度超过 10 的函数维护起来要困难得多。SonarSource 的认知复杂度则在此基础上进一步衡量那些真正让开发者困惑的因素。

提示

将每个函数的圈复杂度控制在 10 以下，认知复杂度控制在 15 以下。

开发者写下 TODO: fix this later 或 HACK: this is terrible but works 时，就产生了技术债务，也承认了这一点。Omen 会查找这些注释并按类型分组：

重要原因：Potdar and Shihab 2014 年的研究发现，SATD 注释往往会在代码库中保留数年。保留时间越长，就越难修复，因为人们会忘记上下文。Maldonado and Shihab（2015）指出，设计债务是最常见、也最危险的类型。

提示

每周检查 SATD。如果某个 TODO 已存在超过 6 个月，就修复或删除它。

SATD 是开发者选择保留的债务；存根则是从未完成的工作——也就是 Agent 或人类在任务中途留下的内容。Omen 通过 tree-sitter AST 分析查找存根（绝不进行纯字符串匹配，因此包含触发词的字符串字面量绝不会被误报），并按模式类型分组：

omen stubs

# Fail CI if any stub is found
omen stubs --gate error

# Only fail on high-severity stubs (todo!()-style idioms), warn on the rest
omen stubs --gate error --gate-severity high
omen stubs --gate warn

**重要原因：**看起来完整的未完成工作（可以编译，也已提交）比明显缺失的代码更危险——在它于生产环境中被调用之前，没有任何迹象表明需要处理。存根与 SATD 一样，会计入综合健康评分中的债务部分，因此未解决的存根会像未解决的 TODO 一样拉低代码库评分。

提示

在 CI 中添加 omen stubs --gate error，以阻止留下 todo!() 或 NotImplementedError 的合并。

死代码包括：

• 从未调用的函数
• 已赋值但从未使用的变量
• 从未实例化的类
• return 语句之后永远无法执行的代码

**重要原因：**死代码不只是杂乱无用。它会让新开发者误以为它必定很重要。它会增加构建时间和二进制文件大小。最糟糕的是，它可能掩盖 bug——如果有人以为死代码会运行而去“修复”它，就白费了时间。Romano et al.（2020）发现，死代码是其他代码质量问题的有力预测指标。

提示

删除死代码。借助版本控制，需要时随时可以恢复。

变更频率分析会检查你的 git 历史记录并统计：

• 每个文件被修改的次数

• 添加和删除的行数

• 一起发生变化的文件 高频变更的文件称为“热点”——它们一直在被修改，这可能意味着它们：

• 是系统的核心部分（所有人都需要修改它们）

• 设计不佳（需要不断修复缺陷）

• 缺少良好的抽象（功能不断被添加进去）

为什么重要：Nagappan 和 Ball 于 2005 年在 Microsoft 开展的研究发现，代码变更量是最有力的缺陷预测指标之一。频繁变更的文件往往包含更多缺陷。结合复杂度数据，变更量可以帮助你找出既复杂又经常修改的文件——也就是风险最高的代码。

提示

如果文件的变更量高且复杂度高，应优先对其进行重构。

克隆分为三种类型：

**为什么重要：**在一份副本中修复缺陷后，还得记得修复所有其他副本。Juergens 等人（2009）发现，克隆代码的缺陷明显更多，因为修复无法一致地应用。克隆越多，在更新时漏掉某一份的可能性就越大。

提示

任何复制超过两次的代码都应该考虑提取为共享函数。目标是将重复率控制在 5% 以下。

Omen 使用 PMAT 加权指标，结合多种信号来预测缺陷概率：

• 过程指标（变更频率、所有权分散程度）
• 度量指标（圈复杂度／认知复杂度）
• 年龄（代码年龄和稳定性）
• 总计大小（代码行数）

每个文件都会获得一个 0% 到 100% 的风险评分。

**为什么重要：**你无法对所有内容进行同等程度的审查。Menzies 等人（2007）表明，缺陷预测可以帮助团队将测试和代码审查重点放在最有可能存在问题的文件上。Rahman 等人（2014）发现，即使是简单模型，在查找缺陷方面也优于随机选择文件。

提示

应优先审查缺陷概率 >70% 的文件。

即时（JIT）缺陷预测会分析近期提交，在风险变更造成问题之前识别出来。与文件级预测不同，JIT 在提交级别运行，使用 Kamei 等人（2013）提出的变更范围因素，并结合软件工程研究文献中的文件级风险信号。

变更范围因素（占评分的 75%）：

使用 Kamei 的中位数逻辑回归系数进行加权（跨项目的相对排序）：

文件级风险信号（占评分的 25%）：

代码所有权分散度的计算方式为 1 - max_author_percentage：没有任何一位作者占主导地位的文件，风险评分会更高。这符合 Bird 等人的研究发现：集中的代码所有权（明确的主要作者）与较少缺陷相关，而分散的代码所有权则与更多缺陷相关。

基于百分位数的风险分类：

风险级别采用基于百分位数的阈值，遵循 JIT 缺陷预测最佳实践。提交不会使用固定阈值，而是根据代码库自身的分布进行排序：

这种方法符合缺陷预测研究中的 80/20 法则：约 20% 的代码变更包含约 80% 的缺陷。无论代码库的特征如何，它都能确保结果具有可操作性——规范管理的代码库阈值较低，而变更频繁的代码库阈值较高。

重要性： Kamei et al. (2013) 证明，JIT 预测能够在提交时发现高风险变更，避免 Bug 扩散。他们考虑工作量的方案采用排序而非固定阈值，将有限的审查资源集中在风险最高的约 20% 提交上。Zeng et al. (2021) 表明，简单的 JIT 模型准确率可与深度学习相当（约 65%），且更易解释。

提示

合并 PR 前运行 omen changes，找出需要额外审查的提交。

JIT 分析会检查单个提交，而差异分析则会评估整个分支相对于目标分支的累计变更。这让审查者在深入代码审查前，能够快速评估风险。

用法：

# Compare current branch against main
omen diff --target main

# Compare against a specific commit
omen diff --target abc123

# Output as markdown for PR comments
omen -f markdown diff --target main

风险因素：

差异分析器使用与 omen changes 相同的、基于研究的权重模型（见上文），结合变更范围因素与文件级信号：

风险评分解读：

输出示例：

Branch Diff Risk Analysis
==========================

Source:   feature/new-api
Target:   main
Base:     abc123def

Risk Score: 0.31 (MEDIUM)

Changes:
  Lines Added:    530
  Lines Deleted:  39
  Files Modified: 3
  Commits:        1

Risk Factors:
  entropy:              0.023
  lines_added:          0.140
  lines_deleted:        0.008
  num_files:            0.014
  commits:              0.007
  file_churn:           0.080
  file_complexity:      0.045
  ownership_diffusion:  0.000

File Risk:
  max_complexity:       6.78
  max_churn:            1.00
  ownership_diffusion:  0.00

注意事项：

• 新增行数多、删除行数少 - 新功能，需要全面审查
• 新增和删除数量均衡 - 重构，验证行为未发生变化
• 代码净减少 - 清理／简化，通常是积极变化
• 熵高 - 变更分散，检查是否包含无关修改
• 文件数量多 - 影响范围广，确保进行集成测试
• file_churn 高 - 修改了历史上经常变动的不稳定文件
• ownership_diffusion 高 - 被修改的文件没有明确负责人；确保有人负责审查

CI/CD 集成：

# Add to GitHub Actions workflow
- name: PR Risk Assessment
  run: |
    omen -f markdown diff --target ${{ github.base_ref }} >> $GITHUB_STEP_SUMMARY

重要性： 代码审查时间有限。差异分析有助于审查者优先分配注意力——仅修改 10 行的低风险 PR，相比涉及 17 个文件的中风险 PR，需要的审查力度更小。熵指标对于发现捆绑无关变更的 PR 尤其有用，因为这类 PR 更难审查，也更容易引入 Bug。

提示

创建 PR 前运行 omen diff，了解审查者会如何看待你的变更。考虑将高风险 PR 拆分为更小、更聚焦的变更。

TDG 将多个指标合并为一个分数（范围为 0–100，越高越好）：

重要性： 技术债就像金融债务——少量尚可，过多则会造成严重问题。Cunningham 于 1992 年提出了这一术语，而 Kruchten 等人（2012）则对如何衡量和管理技术债进行了规范化。TDG 提供一个单一数值，供你跟踪其随时间的变化并比较不同文件。

提示

在添加新功能前，修复评分低于 70 的文件。跟踪 TDG 平均值的变化趋势——它应该上升，而不是下降。

Omen 会构建一张图，展示哪些文件导入了哪些其他文件，然后计算：

• PageRank：哪些文件最“核心”（有许多内容依赖它们）
• 介数中心性：哪些文件是代码库不同部分之间的“桥梁”
• 耦合度：模块之间的相互关联程度

**重要性：**高耦合代码很脆弱——修改一个文件可能会导致许多其他文件出问题。Parnas 于 1972 年发表的模块化论文指出，良好的软件设计会尽量减少模块之间的依赖关系。依赖关系图能显示架构中哪些部分清晰，哪些部分错综复杂。

提示

PageRank 高的文件应当特别稳定并经过充分测试。可以考虑拆分那些到处都充当“桥梁”的文件。

热点是指既复杂又经常修改的文件。简单的文件经常变更，通常没什么问题——它很容易处理。复杂的文件很少变更，也可以应对——你可以不去碰它。但复杂的文件不断变更？那就是 Bug 容易滋生的地方。

Omen 使用变更频率和复杂度归一化值的几何平均数计算热点分数：

hotspot = sqrt(churn_percentile * complexity_percentile)

这两个因素都使用经验累积分布函数（CDF）对照行业基准进行归一化，因此分数可在不同项目之间进行比较：

• 变更频率百分位 - 此文件的提交次数在典型开源软件项目中的排名
• 复杂度百分位 - 平均认知复杂度相对于行业基准的排名

重要性： Adam Tornhill 的《Your Code as a Crime Scene》将热点分析作为寻找影响最大的重构目标的一种方法。他的研究表明，少数文件（通常占 4-8%）包含了大多数 Bug。Graves 等人（2000）和 Nagappan 等人（2005）证明，相对代码变更频率是缺陷的有力预测指标。

提示

从排名前三的热点开始重构。降低高变更频率文件的复杂度，投资回报率最高。

如果两个文件总是在同一次提交中变更，它们就存在时间耦合。这通常揭示了：

• 隐藏依赖关系，无法从导入语句中看出
• 逻辑耦合，即一个文件的变更需要另一个文件随之变更
• 意外耦合，由复制粘贴或不一致的抽象导致

Omen 会分析 Git 历史，找出一同变更的文件对：

提示

如果两个文件的时间耦合度超过 50%，但不存在导入关系，可以考虑提取一个共享模块，或将它们合并。

公交车因子提出的问题是：“在有多少人被公交车撞到后，这段代码会变得无法维护？”公交车因子低，意味着知识集中在少数人手中。

Omen 使用 git blame 计算：

• 主要所有者 - 编写大部分代码的人
• 所有权比例 - 一个人拥有的代码百分比
• 贡献者数量 - 修改过该文件的人数
• 公交车因子 - 主要贡献者人数（贡献代码超过 5%）

重要性：Bird 等人（2011） 发现，相比所有权明确的代码，有许多小贡献者参与的代码存在更多缺陷；但由单个人拥有的代码会带来组织风险。最佳状态是每个模块有 2-4 位重要贡献者。Nagappan 等人（2008） 指出，组织指标（如所有权）比单独的代码指标更能预测缺陷。

提示

所有权比例超过 80% 且由单人拥有的文件应做好知识传递文档。关键文件应至少有 2 人了解。

Chidamber-Kemerer（CK）指标套件用于衡量面向对象设计质量：

LCOM（内聚性缺乏） 尤为重要。LCOM 较低意味着类中的方法使用相似的实例变量——该类的职责明确。LCOM 较高意味着该类承担了互不相关的工作，可能应该拆分。

重要性：Chidamber 和 Kemerer 1994 年的论文 奠定了这些指标作为面向对象质量度量基础的地位。Basili 等人（1996） 通过实证验证了这些指标，发现 WMC 和 CBO 与缺陷倾向有很强的相关性。这些指标被引用数千次，至今仍是面向对象设计分析的标准。

代码库映射提供代码库中重要符号的精简摘要，并使用 PageRank 按结构重要性排序。这项功能专为大模型的上下文窗口设计——最重要的函数和类型会优先显示。

对于每个符号，映射包含：

• 名称和类型（函数、类、方法、接口）
• 文件位置和行号
• 用于快速了解的签名
• 基于依赖该符号的其他符号数量计算的 PageRank 分数
• 显示依赖关系的入度/出度

**为何重要：**大模型的上下文窗口有限。将整个文件塞进去，会把令牌浪费在不太重要的代码上。PageRank 由 Brin 和 Page 于 1998 年提出，可识别图中结构上重要的节点。应用于代码时，它能找出对理解代码库最关键的符号。

**可扩展性：**Omen 使用稀疏幂迭代算法计算 PageRank，计算量随边数 O(E) 线性增长，而非随节点数 O(V^2) 二次增长。因此，它可以在 30 秒内快速分析包含 25,000 多个符号的大型单体代码库。

输出示例：

# Repository Map (Top 20 symbols by PageRank)

## parser.ParseFile (function) - pkg/parser/parser.go:45
  PageRank: 0.0823 | In: 12 | Out: 5
  func ParseFile(path string) (*Result, error)

## models.TdgScore (struct) - pkg/models/tdg.go:28
  PageRank: 0.0651 | In: 8 | Out: 3
  type TdgScore struct

提示

使用 omen repomap --top 50 查看排名最高的 50 个符号，或使用 omen context --max-tokens 8000 获取更广泛的 Agent 上下文。

功能标志功能强大，但也暗藏风险。它们让你可以在不启用代码的情况下发布代码、运行 A/B 测试，并逐步推出功能。但标志会不断累积。2019 年那个“临时”标志至今仍在生产环境中运行。为期一周的实验添加的标志，现在已经成了关键基础设施。

Omen 可检测常见提供商的功能标志用法：

你可以通过在 omen.toml 配置中添加自定义 tree-sitter 查询，来支持其他提供商。

对于每个标志，Omen 会报告：

• 标志键 - 代码中使用的标识符
• 提供商 - 使用的 SDK
• 引用位置 - 检查该标志的所有位置
• 陈旧情况 - 标志首次和最后一次修改的时间（基于 git 历史记录）

**自定义提供商：**对于内部功能标志系统，可在 omen.toml 中定义自定义 tree-sitter 查询：

[[feature_flags.custom_providers]]
name = "feature"
languages = ["ruby"]
query = '''
(call
  receiver: (constant) @receiver
  (#eq? @receiver "Feature")
  method: (identifier) @method
  (#match? @method "^(enabled\\?|get_feature_flag)$")
  arguments: (argument_list
    .
    (simple_symbol) @flag_key))
'''

为何重要：Meinicke 等人（2020）研究了开源项目中的功能标志，发现标志所有权（引入标志的开发者也负责移除它）与更短的标志生命周期相关，有助于控制技术债务。Rahman 等人（2018）研究了 Google Chrome 的 12,000 多个功能开关，发现它们虽然能支持快速发布和灵活部署，但也会带来技术债务和额外的维护负担。定期审查标志可以避免代码库变成充斥着未使用开关的迷宫。

Omen 会计算综合仓库健康评分（0-100），结合多个分析维度。这能快速概览代码库质量，并在 CI/CD 中设置质量门禁。

评分组成：

归一化理念：

每项指标都归一化到 0-100 的范围，分数越高始终越好。归一化函数遵循以下设计原则：

1. 公平 - 严重程度相近的不同指标会得到相近的分数
2. 经过校准 - 依据 SonarQube、CodeClimate 和 CISQ 的行业基准
3. 非线性 - 对轻微问题轻度扣分，对严重问题大幅扣分
4. 考虑严重程度 - 根据影响为事项加权，而不只是计数

例如，SATD（自认技术债务）采用按严重程度加权的评分：

• 严重（SECURITY、VULN）：权重为 4 倍
• 高（FIXME、BUG）：权重为 2 倍
• 中（HACK、REFACTOR）：权重为 1 倍
• 低（TODO、NOTE）：权重为 0.25 倍

这样可以避免低严重程度事项（如文档中的 TODO）不公平地拉低分数。

TDG（技术债务梯度）则通过分析每个文件的结构复杂度、语义复杂度、重复模式和耦合情况，提供互补视角。

用法：

# Compute repository score
omen score

# JSON output for CI integration
omen -f json score

调整阈值：

对于真实世界的代码库而言，达到 100 分几乎不可能。请根据代码库情况在 omen.toml 中设置切合实际的阈值：

[score]
fail_under = 70.0

运行 omen score 查看当前分数，然后将阈值设为略低于这些分数的值。随着时间推移逐步提高阈值。

使用 Lefthook 在提交时强制执行：

添加到 lefthook.yml：

pre-push:
  commands:
    omen-score:
      run: omen score

这样可以防止推送不符合质量阈值的代码。

重要性： 单一健康评分可用于设置质量门禁、跟踪长期趋势，并快速评估代码库。加权综合评分能确保关键问题（缺陷、复杂度）比表面问题产生更大影响。

提示

从可实现的阈值开始，随着代码库质量的提升逐步提高阈值。在遗留代码中，重复代码往往是最难改善的指标。

变异测试通过对代码进行小幅修改（变异），并检查测试是否失败，来衡量测试套件发现错误的能力。“被杀死”的变异体表示测试发现了错误；“存活”的变异体则表示错误可能漏过测试。

21 种变异算子：

功能：

• 并行执行 - 使用工作窃取的异步工作池，高效执行变异测试
• 等价变异体检测 - 基于 ML 的评分，用于识别语义等价的变异
• 覆盖率集成 - 解析 LLVM-cov、Istanbul、coverage.py 和 Go 覆盖率数据，以跳过未经测试的代码
• 增量模式 - 仅测试变更文件中的变异
• CI/CD 集成 - 质量门禁和 GitHub 集成

用法：

# Generate mutants (dry run) with default operators (CRR, ROR, AOR)
omen mutation --dry-run

# Run mutation testing with all operators
omen mutation --mode thorough

# Fast mode (excludes operators that produce more equivalent mutants)
omen mutation --mode fast

# Run with coverage data to skip untested code
omen mutation --coverage coverage.json

# Incremental mode for CI - only test changed files
omen mutation --incremental

# Control parallelism
omen mutation --jobs 8

# Output surviving mutants for investigation
omen mutation --output-survivors survivors.json

# Filter to specific files
omen mutation --glob "src/analyzers/*.rs"

# Analyze a dirty working tree (review the changes first)
omen mutation --allow-dirty

默认情况下，如果存在未提交的更改，变异测试将拒绝运行，以免在应用变异体时覆盖现有工作。只有在检查并保护好当前更改后，才使用 --allow-dirty。

基于 ML 的预测：

Omen 包含一个 ML 模型，它会从你的变异测试历史中学习，预测哪些变异体会存活。这可以实现两项优化：

1. 跳过显而易见的击杀项 - 不要浪费时间测试模型确信会被捕获的变异体
2. 更好地检测等价变异体 - 学习代码库中哪些模式会产生等价变异体

# Record results to history file for later training
omen mutation --record

# Train the model from accumulated history
omen mutation train

# Use trained model to skip high-confidence kills (saves time)
omen mutation --skip-predicted 0.95

# Use a custom model path
omen mutation --model path/to/model.json

训练工作流：

1. 收集数据：在代码库上运行 omen mutation --record。每个变异体的结果（击杀／存活）都会追加到 .omen/mutation-history.jsonl，并包含：

   • 变异体详情（运算符、位置、原始代码／变异后代码）
   • 源代码上下文（变异前后各 5 行）
   • 执行时间

2. 训练模型：运行 omen mutation train 训练预测器。模型会学习：

   • 代码库中针对各运算符的击杀率
   • 与存活相关的代码模式特征权重

3. 使用预测：后续运行会自动加载 .omen/mutation-model.json。使用 --skip-predicted 0.9 跳过预测击杀概率 >90% 的变异体。

CI 工作流示例：

# Weekly: full run with recording
omen mutation --record --mode thorough

# After accumulating history: train model
omen mutation train

# Daily CI: fast run using predictions
omen mutation --incremental --skip-predicted 0.95

说明

默认情况下，.omen/ 目录会被 gitignore。如果要在团队中共享训练好的模型，请从 .gitignore 中移除 .omen/mutation-model.json。

变异分数：

变异分数用于衡量测试套件的有效性：

mutation_score = killed_mutants / (total_mutants - equivalent_mutants)

**重要性：**代码覆盖率能告诉你测试期间运行了哪些代码，但不能说明测试是否真正验证了行为。如果缺少断言，一个函数即使达到 100% 覆盖率，变异分数也可能是 0%。Jia and Harman（2011） 表明，变异测试与故障检测高度相关。Papadakis et al.（2019） 证明，变异测试优于其他测试充分性标准。

提示

在 CI 中从 --mode fast 开始，以便快速获得反馈；定期运行 --mode thorough 进行全面分析。使用 --coverage，避免在未经测试的代码上浪费时间。

Omen 内置了一个 Model Context Protocol（MCP）服务，可将所有分析器作为工具提供给 Claude 等大模型使用。这样，AI 助手便能通过标准化的工具调用直接分析代码库。

可用工具：

• context - 面向 Agent 的仓库概览和导航提示
• outline - 低 Token 消耗的导入、类和函数概览
• complexity - 圈复杂度和认知复杂度
• satd - 自承认技术债检测
• stubs - 不完整／占位实现检测（只读；不会作为门禁）
• deadcode - 未使用的函数和变量
• churn - Git 文件变更频率
• clones - 代码克隆检测
• defect - 文件级缺陷概率（PMAT）
• changes - 提交级变更风险（JIT）
• diff - 分支差异风险分析
• tdg - 技术债梯度分数
• graph - 依赖关系图生成
• hotspot - 高变更频率与高复杂度文件
• temporal - 同时变更的文件
• ownership - 代码所有权和巴士因子
• cohesion - CK 面向对象指标
• repomap - 按 PageRank 排序的符号映射
• smells - 架构异味检测
• flags - 功能标志检测和过时状态检测
• score - 综合健康度评分（0-100）
• semantic_search - 自然语言代码搜索
• get_symbol - 获取一个符号的源代码、签名、位置、关系和复杂度
• impact - 传递调用方／被调用方影响范围分析
• semantic_search_hyde - HyDE 风格搜索（使用假设代码片段进行查询）

重要性： LLM 在使用结构化工具而非解析非结构化输出时效果最佳。MCP 为 Claude Desktop 和其他兼容的助手提供标准接口，而分页可确保大型结果不会超出上下文预算。

提示

将 omen 配置为 AI 助手中的 MCP 服务，即可使用自然语言查询，例如“查找最复杂的函数”或“显示技术债务热点”。