ameba-configuration

What this skill does

# Ameba Configuration

Configure Ameba, the static code analysis tool for Crystal, to enforce consistent code style and catch code smells in your Crystal projects.

## Understanding Ameba

Ameba is a static code analysis tool for the Crystal programming language that:

- Enforces consistent Crystal code style
- Catches code smells and wrong code constructions
- Provides configurable rules organized into categories
- Supports inline disabling of rules
- Offers auto-correction for many issues
- Integrates seamlessly with Crystal development workflows

## Core Configuration File: .ameba.yml

### Generating Default Configuration

```bash
# Generate a new configuration file with all defaults
ameba --gen-config

# This creates .ameba.yml with all available rules and their default settings
```

### Basic Configuration Structure

```yaml
# .ameba.yml - Complete example configuration

# Global source configuration
Globs:
  - "**/*.cr"      # Include all Crystal files
  - "**/*.ecr"     # Include Embedded Crystal files
  - "!lib"         # Exclude dependencies

Excluded:
  - src/legacy/**  # Exclude legacy code
  - spec/fixtures/** # Exclude test fixtures

# Rule categories and individual rules
Lint/UnusedArgument:
  Enabled: true
  Severity: Warning

Style/RedundantReturn:
  Enabled: true
  Severity: Convention

Performance/AnyInsteadOfEmpty:
  Enabled: true
  Severity: Warning
```

## Source File Configuration

### Globs: Defining What to Analyze

```yaml
# Include specific patterns
Globs:
  - "**/*.cr"        # All Crystal source files
  - "**/*.ecr"       # All Embedded Crystal templates
  - "!lib/**"        # Exclude lib directory
  - "!vendor/**"     # Exclude vendor directory

# Common patterns
# - "src/**/*.cr"    # Only src directory
# - "spec/**/*.cr"   # Only spec directory
# - "!**/*_test.cr"  # Exclude test files
```

### Excluded: Fine-Grained Exclusions

```yaml
# Global exclusions (applied to all rules)
Excluded:
  - src/compiler/**      # Exclude specific directories
  - src/legacy/**
  - spec/fixtures/**
  - db/migrations/**     # Often excluded from style checks

# Real-world example
Globs:
  - "**/*.cr"
  - "!lib"

Excluded:
  - src/external/generated/**  # Generated code
  - src/legacy/**              # Legacy code being refactored
  - spec/support/fixtures/**   # Test data
```

### Source Configuration Examples

```yaml
# Example 1: Standard web application
Globs:
  - "src/**/*.cr"
  - "spec/**/*.cr"
  - "!lib"

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

# Example 2: Library/Shard
Globs:
  - "src/**/*.cr"
  - "spec/**/*.cr"
  - "examples/**/*.cr"
  - "!lib"

Excluded:
  - spec/support/**

# Example 3: Monorepo
Globs:
  - "apps/**/src/**/*.cr"
  - "apps/**/spec/**/*.cr"
  - "packages/**/src/**/*.cr"
  - "!lib"
  - "!**/node_modules/**"

Excluded:
  - apps/legacy/**
```

## Rule Categories

### Lint Rules (Code Correctness)

Lint rules catch potential bugs and incorrect code:

```yaml
# Unused variables and arguments
Lint/UnusedArgument:
  Enabled: true
  Severity: Warning
  # Catches: def process(data, unused_param)

Lint/UselessAssign:
  Enabled: true
  Severity: Warning
  # Catches: x = 5; x = 10  # First assignment never used

# Shadowed variables
Lint/ShadowingOuterLocalVar:
  Enabled: true
  Severity: Warning
  # Catches: x = 1; proc { |x| x }  # x shadows outer x

# Unreachable code
Lint/UnreachableCode:
  Enabled: true
  Severity: Error
  # Catches: return x; do_something()  # Never executes

# Syntax issues
Lint/Syntax:
  Enabled: true
  Severity: Error
  # Catches syntax errors before compilation

# Empty blocks
Lint/EmptyBlock:
  Enabled: true
  Severity: Warning
  ExcludeEmptyBlocks: false
  # Catches: items.each { }

# Debugger statements
Lint/DebuggerStatement:
  Enabled: true
  Severity: Warning
  # Catches: debugger; pp value
```

### Style Rules (Code Conventions)

Style rules enforce Crystal code conventions:

```yaml
# Naming conventions
Style/ConstantNames:
  Enabled: true
  Severity: Convention
  # Enforces: CONSTANT_NAME not Constant_Name

Style/MethodNames:
  Enabled: true
  Severity: Convention
  # Enforces: method_name not methodName

Style/TypeNames:
  Enabled: true
  Severity: Convention
  # Enforces: ClassName not Class_Name

# Predicate methods
Style/PredicateName:
  Enabled: true
  Severity: Convention
  # Enforces: empty? not is_empty

# Redundant code
Style/RedundantReturn:
  Enabled: true
  Severity: Convention
  AllowMultipleReturnValues: true
  # Catches: def foo; return 42; end
  # Prefers: def foo; 42; end

Style/RedundantBegin:
  Enabled: true
  Severity: Convention
  # Catches: def foo; begin; 42; end; end
  # Prefers: def foo; 42; end

# Large numbers
Style/LargeNumbers:
  Enabled: true
  Severity: Convention
  IntMinDigits: 5
  # Enforces: 100_000 not 100000

# Parentheses
Style/ParenthesesAroundCondition:
  Enabled: true
  Severity: Convention
  # Enforces: if x > 5 not if (x > 5)

# String literals
Style/StringLiterals:
  Enabled: true
  Severity: Convention
  # Catches inconsistent quote usage

# Variable names
Style/VariableNames:
  Enabled: true
  Severity: Convention
  # Enforces: snake_case not camelCase
```

### Performance Rules

Performance rules identify inefficient code patterns:

```yaml
# Inefficient any? usage
Performance/AnyInsteadOfEmpty:
  Enabled: true
  Severity: Warning
  FilterFirstNegativeCondition: true
  # Catches: array.any?
  # Prefers: !array.empty?

# Size after filter
Performance/SizeAfterFilter:
  Enabled: true
  Severity: Warning
  FilterNames: [select, reject]
  # Catches: items.select(&.active?).size
  # Prefers: items.count(&.active?)

# Compact after map
Performance/CompactAfterMap:
  Enabled: true
  Severity: Warning
  # Catches: items.map(&.value?).compact
  # Prefers: items.compact_map(&.value?)

# Flatten after map
Performance/FlattenAfterMap:
  Enabled: true
  Severity: Warning
  # Catches: items.map(&.children).flatten
  # Prefers: items.flat_map(&.children)
```

## Rule Configuration Options

### Per-Rule Configuration

```yaml
# Enable/disable individual rules
Style/LargeNumbers:
  Enabled: true  # or false to disable

# Set severity levels
Style/RedundantReturn:
  Enabled: true
  Severity: Warning  # Error, Warning, Convention

# Configure rule-specific options
Style/LargeNumbers:
  Enabled: true
  Severity: Convention
  IntMinDigits: 5    # Minimum digits before requiring underscores

Lint/UnusedArgument:
  Enabled: true
  IgnoreTypeDeclarations: false
  IgnoreParameterNames: []  # Parameter names to ignore

# Exclude files from specific rules
Style/RedundantBegin:
  Enabled: true
  Excluded:
    - src/server/processor.cr
    - src/server/api.cr
```

### Advanced Rule Configuration Examples

```yaml
# Custom severity levels
Lint/UselessAssign:
  Enabled: true
  Severity: Error     # Make this an error, not warning

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

# Ignore specific parameter patterns
Lint/UnusedArgument:
  Enabled: true
  IgnoreParameterNames:
    - "_*"       # Ignore params starting with underscore
    - "unused_*" # Ignore params prefixed with unused_

# Configure numeric formatting
Style/LargeNumbers:
  Enabled: true
  IntMinDigits: 5    # 10000 requires underscores
  # 1000 is fine, 10000 should be 10_000

# Performance tuning
Performance/SizeAfterFilter:
  Enabled: true
  FilterNames:
    - select
    - reject
    - filter
```

## Severity Levels

### Understanding Severity

```yaml
# Error: Must be fixed (blocks CI typically)
Lint/Syntax:
  Severity: Error

# Warning: Should be fixed (important issues)
Lint/UnusedArgument:
  Severity: Warning

# Convention: Style preference (less critical)
Style/RedundantReturn:
  Severity: Convention
```

### Severity Configuration Strategy

```yaml
# Conservative approach (CI-friendly)
# Only errors block builds
Lint/Syntax:
  Severity: Error

Lint/UnreachableCode:
  Severity: Error

Style/RedundantReturn:
  Severity: