SuperAPI AI 工具集

rails-audit-thoughtbot

编程与开发

查看项目

更新于 10-16 07:30

技能介绍

用途

Rails Audit Skill 用于对 Ruby on Rails 应用执行全面的代码审计,审计依据是 thoughtbot 的 Ruby Science 与 Testing Rails 最佳实践,并特别强调使用普通 Ruby 对象(PORO)而非 Service Object。当用户请求代码审计时使用该技能。

审计范围

审计可运行于两种模式:

  • 全应用审计:分析整个 Rails 应用。
  • 定向审计:仅分析指定的文件或目录。

执行流程

第 1 步:确定审计范围

询问用户或从请求中推断:全审计分析所有 app/、spec/ 或 test/、config/、db/、lib/;定向审计仅分析指定路径。

第 2 步:收集可选指标(SimpleCov + RubyCritic)

通过一次 AskUserQuestion 同时询问两个问题,让用户一次决定:是否在审计前收集自动化指标。选项包括:SimpleCov(运行测试套件以捕获实际代码覆盖率百分比)、RubyCritic(分析代码复杂度、重复和代码异味,不运行测试)。推荐两者都选以获得最全面的审计。可选答案为“两者都要(推荐)”“仅 SimpleCov”“仅 RubyCritic”“都跳过”。

根据用户选择,使用 Task 工具并行启动接受的子代理。两者可同时运行,因为 SimpleCov 会修改测试辅助文件,而 RubyCritic 只读取源文件,二者不冲突。

SimpleCov 子代理(若接受):读取 agents/simplecov_agent.md 并遵循其中所有步骤,审计范围为第 1 步确定的 SCOPE,按该文件指定的输出格式返回覆盖率数据。

RubyCritic 子代理(若接受):读取 agents/rubycritic_agent.md 并遵循其中所有步骤,审计范围为第 1 步确定的 SCOPE,按该文件指定的输出格式返回代码质量数据。

两个代理完成后清理:若 SimpleCov 运行过,执行 rm -rf coverage/;若 RubyCritic 运行过,执行 rm -rf tmp/rubycritic/。

响应解读:COVERAGE_FAILED / RUBYCRITIC_FAILED 表示该工具无数据,使用估算模式(SimpleCov)或省略该部分(RubyCritic),并在报告中注明失败原因。COVERAGE_DATA 解析并保留在上下文中供第 4、5 步使用(总体覆盖率、按目录细分、覆盖率最低文件、零覆盖率文件)。RUBYCRITIC_DATA 解析并保留在上下文中供第 4、5 步使用(总体评分、按目录评级、评级最差文件、主要代码异味、最复杂文件)。

第 3 步:加载参考材料

分析前读取相关参考文件:references/code_smells.md(要识别的代码异味模式)、references/testing_guidelines.md(测试最佳实践)、references/poro_patterns.md(PORO 与 ActiveModel 模式)、references/security_checklist.md(安全漏洞模式)、references/rails_antipatterns.md(Rails 特有反模式,包括外部服务、迁移、性能)。

第 4 步:按类别分析代码

按以下顺序分析:

  1. 测试覆盖与质量:若第 2 步收集了 SimpleCov 数据,使用实际覆盖率百分比而非估算;交叉引用每文件 SimpleCov 数据,0% 覆盖率文件视为“缺少测试”;检查缺失的测试文件;识别未测试的公共方法;审查测试结构(Four Phase Test);检查测试反模式。

  2. 安全漏洞:SQL 注入风险、批量赋值漏洞、XSS 漏洞、认证/授权问题、敏感数据暴露。

  3. 模型与数据库:胖模型检测、缺失验证、N+1 查询风险、回调复杂度、迪米特法则违规(窥探式模型);若收集了 RubyCritic 数据,标记评级为 D/F 或高复杂度的模型。

  4. 控制器:胖控制器检测、控制器中的业务逻辑、缺失强参数、响应处理、单体控制器(非 RESTful 动作、动作数超过 7 个)、臃肿会话(存储对象而非 ID);若收集了 RubyCritic 数据,标记评级为 D/F 或高复杂度的控制器。

  5. 代码设计与架构:Service Object 建议重构为 PORO、大类、长方法、特性依恋、迪米特法则违规、单一职责违规;若收集了 RubyCritic 数据,将 D/F 评级文件和高复杂度文件与人工代码审查发现交叉引用。

  6. 视图与展示器:视图中逻辑(PHPitis)、缺少用于 DRY 的部分模板、辅助方法复杂度、视图中的查询逻辑。

  7. 外部服务与错误处理:发射后不管(HTTP 调用缺少异常处理)、迟缓服务(缺少超时、本应后台化的同步调用)、裸 rescue 语句、静默失败(保存而不检查返回值)。

  8. 数据库与迁移:混乱迁移(模型引用、缺少 down 方法)、外键/多态关联/唯一性验证缺少索引、性能反模式(Ruby 迭代 vs SQL 查询)、无事务的批量操作。

第 5 步:生成审计报告

在项目根目录创建 RAILS_AUDIT_REPORT.md,结构定义于 references/report_template.md。若第 2 步收集了 SimpleCov 覆盖率数据,使用报告模板中 Testing 部分的 SimpleCov 变体;无覆盖率数据时使用估算变体。若第 2b 步收集了 RubyCritic 数据,使用报告模板中的 RubyCritic 变体包含代码质量指标部分;无 RubyCritic 数据时使用不可用变体。

严重程度定义

  • Critical:安全漏洞、数据丢失风险、破坏生产的问题。
  • High:性能问题、关键路径缺少测试、重大代码异味。
  • Medium:代码异味、约定违规、可维护性问题。
  • Low:风格问题、小改进、建议。

关键检测模式

Service Object → PORO 重构:当发现 app/services/ 中的类时,识别命名为 *Service、*Manager、*Handler 的类,以及只有 .call 或 .perform 方法的类,建议重命名为领域名词并包含 ActiveModel::Model。

胖模型检测:模型超过 200 行、超过 15 个公共方法、多个不相关职责,建议使用组合提取为 PORO。

胖控制器检测:动作超过 15 行、业务逻辑(非请求/响应处理)、多个实例变量赋值,建议提取为表单对象或领域模型。

缺失测试检测:对 app/ 中每个 Ruby 文件,检查对应的 _spec.rb 或 _test.rb,检查已测试的公共方法,报告未测试的文件和方法。

分析命令

使用 Claude Code 内置工具而非 shell 命令,它们更快、正确处理权限并提供更好输出:

  • 按类型查找 Ruby 文件:使用 Glob 工具,模式如 app/models//*.rb、app/controllers//.rb、app/services/**/.rb。
  • 查找测试文件:使用 Glob,模式 spec//*_spec.rb 或 test//*_test.rb。
  • 搜索代码模式:使用 Grep 工具(例如搜索 rescue\s*$、.save\b、params.permit!)。
  • 读取并统计文件行数:使用 Read 工具检查文件,从输出统计行数。
  • 查找长文件:使用 Glob 列出所有 app/**/*.rb 文件,然后 Read 每个文件检查行数。

报告输出

始终将审计报告保存到项目根目录的 RAILS_AUDIT_REPORT.md 并呈现给用户。