名称: ameba-configuration 用户可调用: false 描述: 用于配置Crystal项目中的Ameba规则和设置，包括.ameba.yml设置、规则管理、严重级别和代码质量强制执行。允许的工具:

Bash
Read

Ameba配置

配置Ameba，Crystal的静态代码分析工具，以强制执行一致的代码风格和捕捉代码异味。

理解Ameba

Ameba是Crystal编程语言的静态代码分析工具，它：

强制执行一致的Crystal代码风格
捕捉代码异味和错误代码构造
提供可配置的规则，按类别组织
支持规则的内联禁用
为许多问题提供自动修正
与Crystal开发工作流无缝集成

核心配置文件: .ameba.yml

生成默认配置

# 生成具有所有默认值的新配置文件
ameba --gen-config

# 这会创建.ameba.yml，包含所有可用规则及其默认设置

基本配置结构

# .ameba.yml - 完整示例配置

# 全局源配置
Globs:
  - "**/*.cr"      # 包含所有Crystal文件
  - "**/*.ecr"     # 包含嵌入Crystal文件
  - "!lib"         # 排除依赖项

Excluded:
  - src/legacy/**  # 排除遗留代码
  - spec/fixtures/** # 排除测试夹具

# 规则类别和单个规则
Lint/UnusedArgument:
  Enabled: true
  Severity: Warning

Style/RedundantReturn:
  Enabled: true
  Severity: Convention

Performance/AnyInsteadOfEmpty:
  Enabled: true
  Severity: Warning

源文件配置

Globs: 定义要分析的内容

# 包含特定模式
Globs:
  - "**/*.cr"        # 所有Crystal源文件
  - "**/*.ecr"       # 所有嵌入Crystal模板
  - "!lib/**"        # 排除lib目录
  - "!vendor/**"     # 排除vendor目录

# 常见模式
# - "src/**/*.cr"    # 仅src目录
# - "spec/**/*.cr"   # 仅spec目录
# - "!**/*_test.cr"  # 排除测试文件

Excluded: 细粒度排除

# 全局排除（应用于所有规则）
Excluded:
  - src/compiler/**      # 排除特定目录
  - src/legacy/**
  - spec/fixtures/**
  - db/migrations/**     # 通常从风格检查中排除

# 真实世界示例
Globs:
  - "**/*.cr"
  - "!lib"

Excluded:
  - src/external/generated/**  # 生成代码
  - src/legacy/**              # 正在重构的遗留代码
  - spec/support/fixtures/**   # 测试数据

源配置示例

# 示例1: 标准Web应用程序
Globs:
  - "src/**/*.cr"
  - "spec/**/*.cr"
  - "!lib"

Excluded:
  - src/assets/**
  - spec/fixtures/**

# 示例2: 库/Shard
Globs:
  - "src/**/*.cr"
  - "spec/**/*.cr"
  - "examples/**/*.cr"
  - "!lib"

Excluded:
  - spec/support/**

# 示例3: 单体仓库
Globs:
  - "apps/**/src/**/*.cr"
  - "apps/**/spec/**/*.cr"
  - "packages/**/src/**/*.cr"
  - "!lib"
  - "!**/node_modules/**"

Excluded:
  - apps/legacy/**

规则类别

Lint规则（代码正确性）

Lint规则捕捉潜在错误和不正确代码：

# 未使用的变量和参数
Lint/UnusedArgument:
  Enabled: true
  Severity: Warning
  # 捕捉: def process(data, unused_param)

Lint/UselessAssign:
  Enabled: true
  Severity: Warning
  # 捕捉: x = 5; x = 10  # 第一次赋值从未使用

# 变量遮蔽
Lint/ShadowingOuterLocalVar:
  Enabled: true
  Severity: Warning
  # 捕捉: x = 1; proc { |x| x }  # x遮蔽外部x

# 不可达代码
Lint/UnreachableCode:
  Enabled: true
  Severity: Error
  # 捕捉: return x; do_something()  # 永不执行

# 语法问题
Lint/Syntax:
  Enabled: true
  Severity: Error
  # 捕捉编译前的语法错误

# 空块
Lint/EmptyBlock:
  Enabled: true
  Severity: Warning
  ExcludeEmptyBlocks: false
  # 捕捉: items.each { }

# 调试器语句
Lint/DebuggerStatement:
  Enabled: true
  Severity: Warning
  # 捕捉: debugger; pp value

Style规则（代码约定）

Style规则强制执行Crystal代码约定：

# 命名约定
Style/ConstantNames:
  Enabled: true
  Severity: Convention
  # 强制执行: CONSTANT_NAME 而非 Constant_Name

Style/MethodNames:
  Enabled: true
  Severity: Convention
  # 强制执行: method_name 而非 methodName

Style/TypeNames:
  Enabled: true
  Severity: Convention
  # 强制执行: ClassName 而非 Class_Name

# 谓词方法
Style/PredicateName:
  Enabled: true
  Severity: Convention
  # 强制执行: empty? 而非 is_empty

# 冗余代码
Style/RedundantReturn:
  Enabled: true
  Severity: Convention
  AllowMultipleReturnValues: true
  # 捕捉: def foo; return 42; end
  # 推荐: def foo; 42; end

Style/RedundantBegin:
  Enabled: true
  Severity: Convention
  # 捕捉: def foo; begin; 42; end; end
  # 推荐: def foo; 42; end

# 大数字
Style/LargeNumbers:
  Enabled: true
  Severity: Convention
  IntMinDigits: 5
  # 强制执行: 100_000 而非 100000

# 括号
Style/ParenthesesAroundCondition:
  Enabled: true
  Severity: Convention
  # 强制执行: if x > 5 而非 if (x > 5)

# 字符串字面量
Style/StringLiterals:
  Enabled: true
  Severity: Convention
  # 捕捉不一致的引号使用

# 变量名
Style/VariableNames:
  Enabled: true
  Severity: Convention
  # 强制执行: snake_case 而非 camelCase

Performance规则

Performance规则识别低效代码模式：

# 低效any?使用
Performance/AnyInsteadOfEmpty:
  Enabled: true
  Severity: Warning
  FilterFirstNegativeCondition: true
  # 捕捉: array.any?
  # 推荐: !array.empty?

# 过滤后的大小
Performance/SizeAfterFilter:
  Enabled: true
  Severity: Warning
  FilterNames: [select, reject]
  # 捕捉: items.select(&.active?).size
  # 推荐: items.count(&.active?)

# 映射后压缩
Performance/CompactAfterMap:
  Enabled: true
  Severity: Warning
  # 捕捉: items.map(&.value?).compact
  # 推荐: items.compact_map(&.value?)

# 映射后展平
Performance/FlattenAfterMap:
  Enabled: true
  Severity: Warning
  # 捕捉: items.map(&.children).flatten
  # 推荐: items.flat_map(&.children)

规则配置选项

每规则配置

# 启用/禁用单个规则
Style/LargeNumbers:
  Enabled: true  # 或false禁用

# 设置严重级别
Style/RedundantReturn:
  Enabled: true
  Severity: Warning  # Error, Warning, Convention

# 配置规则特定选项
Style/LargeNumbers:
  Enabled: true
  Severity: Convention
  IntMinDigits: 5    # 需要下划线的最小数字位数

Lint/UnusedArgument:
  Enabled: true
  IgnoreTypeDeclarations: false
  IgnoreParameterNames: []  # 忽略的参数名称

# 从特定规则排除文件
Style/RedundantBegin:
  Enabled: true
  Excluded:
    - src/server/processor.cr
    - src/server/api.cr

高级规则配置示例

# 自定义严重级别
Lint/UselessAssign:
  Enabled: true
  Severity: Error     # 设为错误，而非警告

Style/RedundantReturn:
  Enabled: true
  Severity: Convention
  AllowMultipleReturnValues: true  # 允许: return x, y

# 忽略特定参数模式
Lint/UnusedArgument:
  Enabled: true
  IgnoreParameterNames:
    - "_*"       # 忽略以下划线开头的参数
    - "unused_*" # 忽略以unused_为前缀的参数

# 配置数字格式
Style/LargeNumbers:
  Enabled: true
  IntMinDigits: 5    # 10000需要下划线
  # 1000可以，10000应为10_000

# 性能调优
Performance/SizeAfterFilter:
  Enabled: true
  FilterNames:
    - select
    - reject
    - filter

严重级别

理解严重性

# Error: 必须修复（通常阻止CI）
Lint/Syntax:
  Severity: Error

# Warning: 应该修复（重要问题）
Lint/UnusedArgument:
  Severity: Warning

# Convention: 风格偏好（较不关键）
Style/RedundantReturn:
  Severity: Convention

严重性配置策略

# 保守方法（CI友好）
# 只有错误阻止构建
Lint/Syntax:
  Severity: Error

Lint/UnreachableCode:
  Severity: Error

Style/RedundantReturn:
  Severity: Warning

Style/LargeNumbers:
  Severity: Convention

# 严格方法（强制执行所有内容）
# 所有问题视为错误
Lint/UnusedArgument:
  Severity: Error

Style/RedundantReturn:
  Severity: Error

Style/VariableNames:
  Severity: Error

# 渐进方法（逐渐增加严格性）
# 从警告开始，随时间变为错误
Lint/UselessAssign:
  Severity: Warning  # 清理后将变为Error

Style/RedundantBegin:
  Severity: Convention  # 团队适应后将变为Warning

内联规则控制

在代码中禁用规则

# 为单行禁用单个规则
time = Time.epoch(1483859302) # ameba:disable Style/LargeNumbers

# 为单行禁用多个规则
result = calculate() # ameba:disable Style/RedundantReturn, Lint/UselessAssign

# 禁用规则类别
# ameba:disable Style, Lint
def legacy_method
  # 具有已知问题的旧代码
end
# ameba:enable Style, Lint

# 为块禁用特定规则
# ameba:disable Style/RedundantBegin
def process
  begin
    perform_operation
  rescue
    handle_error
  end
end
# ameba:enable Style/RedundantBegin

# 常见模式
class LegacyService
  # ameba:disable Lint/UnusedArgument
  def process(data, context)
    # 目前只使用data
    data.process
  end
  # ameba:enable Lint/UnusedArgument
end

内联禁用最佳实践

# 良好 - 具体且临时
def parse_timestamp(value)
  Time.epoch(1483859302) # ameba:disable Style/LargeNumbers
end

# 良好 - 带解释
# 此API要求精确数字格式
# ameba:disable Style/LargeNumbers
LEGACY_TIMESTAMP = 1483859302
# ameba:enable Style/LargeNumbers

# 不佳 - 太宽泛
# ameba:disable Style
# 禁用所有风格规则 - 过于宽松
def messy_method
  # ...
end

# 不佳 - 从不重新启用
# ameba:disable Lint/UselessAssign
# 为文件其余部分禁用

# 良好 - 范围最小化
def external_api_call
  # ameba:disable Style/VariableNames
  responseData = call_api()  # 外部API使用camelCase
  # ameba:enable Style/VariableNames

  response_data = responseData  # 转换为Crystal约定
end

完整配置示例

最小配置（宽松）

# .ameba.yml - 新项目的最小设置
Globs:
  - "**/*.cr"
  - "!lib"

# 仅启用关键规则
Lint/Syntax:
  Enabled: true
  Severity: Error

Lint/UnreachableCode:
  Enabled: true
  Severity: Error

标准配置（平衡）

# .ameba.yml - 大多数项目的标准配置
Globs:
  - "**/*.cr"
  - "**/*.ecr"
  - "!lib"

Excluded:
  - spec/fixtures/**

# Lint规则（错误和警告）
Lint/Syntax:
  Enabled: true
  Severity: Error

Lint/UnusedArgument:
  Enabled: true
  Severity: Warning

Lint/UselessAssign:
  Enabled: true
  Severity: Warning

Lint/UnreachableCode:
  Enabled: true
  Severity: Error

# Style规则（约定）
Style/RedundantReturn:
  Enabled: true
  Severity: Convention

Style/RedundantBegin:
  Enabled: true
  Severity: Convention

Style/LargeNumbers:
  Enabled: true
  Severity: Convention
  IntMinDigits: 5

Style/VariableNames:
  Enabled: true
  Severity: Warning

# Performance规则
Performance/AnyInsteadOfEmpty:
  Enabled: true
  Severity: Warning

Performance/SizeAfterFilter:
  Enabled: true
  Severity: Warning

严格配置（全面）

# .ameba.yml - 生产代码的严格配置
Globs:
  - "src/**/*.cr"
  - "spec/**/*.cr"
  - "!lib"

Excluded:
  - spec/fixtures/**
  - spec/support/mocks/**

# 所有Lint规则启用为错误
Lint/Syntax:
  Enabled: true
  Severity: Error

Lint/UnusedArgument:
  Enabled: true
  Severity: Error

Lint/UselessAssign:
  Enabled: true
  Severity: Error

Lint/UnreachableCode:
  Enabled: true
  Severity: Error

Lint/ShadowingOuterLocalVar:
  Enabled: true
  Severity: Error

Lint/DebuggerStatement:
  Enabled: true
  Severity: Error

# Style规则作为警告或错误
Style/RedundantReturn:
  Enabled: true
  Severity: Error

Style/RedundantBegin:
  Enabled: true
  Severity: Error

Style/LargeNumbers:
  Enabled: true
  Severity: Error
  IntMinDigits: 4

Style/VariableNames:
  Enabled: true
  Severity: Error

Style/MethodNames:
  Enabled: true
  Severity: Error

Style/ConstantNames:
  Enabled: true
  Severity: Error

Style/PredicateName:
  Enabled: true
  Severity: Warning

# Performance规则作为警告
Performance/AnyInsteadOfEmpty:
  Enabled: true
  Severity: Warning

Performance/SizeAfterFilter:
  Enabled: true
  Severity: Warning

Performance/CompactAfterMap:
  Enabled: true
  Severity: Warning

Performance/FlattenAfterMap:
  Enabled: true
  Severity: Warning

何时使用此技能

使用ameba-configuration技能当：

为新Crystal项目设置Ameba
配置团队的代码质量标准
为CI/CD自定义规则严重级别
从分析中排除遗留代码或生成文件
排除规则冲突或误报
从一个Ameba版本迁移到另一个
建立项目特定编码标准
平衡代码质量和开发速度
将Ameba集成到现有Crystal项目
为多个项目创建配置模板

最佳实践

从生成配置开始 - 运行ameba --gen-config查看所有可用规则及其默认值
使用版本控制 - 提交.ameba.yml以便团队成员共享相同配置
增量启用 - 从宽松开始，随时间逐渐启用更多规则
设置适当严重性 - 对阻止问题使用Error，对重要问题使用Warning，对风格使用Convention
记录例外 - 添加注释解释为什么特定规则被禁用或配置不同
范围排除窄 - 排除特定文件/目录而非全局禁用规则
谨慎使用内联禁用 - 优先修复问题而非禁用规则；必要时要具体
审查生成配置 - 不要盲目使用默认配置；审查并为项目自定义
分离关注点 - 为不同类型问题（bug vs风格）使用不同严重级别
测试配置更改 - 在提交配置更改前本地运行ameba
保持配置可维护 - 将相关规则分组并使用注释解释部分
与团队标准对齐 - 配置应反映团队共识，而非个人偏好
定期更新 - 升级Ameba版本时审查和更新配置
使用规则特定排除 - 可能时从特定规则排除文件而非全局
监控误报 - 为代码库生成太多误报的规则进行调整

常见陷阱

初始太严格 - 在现有项目中以最大严重性启用所有规则会创建压倒性技术债务
永久太宽松 - 从不收紧规则意味着错过宝贵的代码质量改进
排除太广泛 - 使用Excluded: ["**/*"]击败静态分析目的
不一致严重性 - 混淆严重级别（使风格问题为错误，使bug为约定）
不使用版本控制 - 团队成员使用不同配置导致混淆
忽略升级指南 - 新Ameba版本可能更改规则名称或行为
不理解就禁用 - 关闭标志合法问题的规则
过度使用内联禁用 - 用ameba:disable注释乱撒代码而非修复问题
不排除生成代码 - 浪费时间分析自动生成文件
忘记ECR文件 - 不将**/*.ecr包含在Globs中用于Web应用程序
与格式化器冲突 - 启用与crystal tool format冲突的规则
缺少测试文件 - 不将spec/**/*.cr包含在Globs中
代码中全局禁用 - 在文件级别使用ameba:disable而不重新启用
不测试CI集成 - 配置在本地工作但在CI环境中失败
忽略性能影响 - 在不考虑大型代码库分析时间的情况下启用每个规则

Ameba配置Skill ameba-configuration