ameba-integration

What this skill does

# Ameba Integration

Integrate Ameba into your development workflow for automated Crystal code quality checks in CI/CD pipelines, pre-commit hooks, and code review processes.

## Integration Overview

Ameba can be integrated at multiple points in your development workflow:

- **Pre-commit hooks** - Catch issues before they're committed
- **CI/CD pipelines** - Enforce quality gates in automated builds
- **GitHub Actions** - Automated PR reviews and status checks
- **Editor integration** - Real-time feedback while coding
- **Code review** - Automated comments on pull requests
- **Pre-push hooks** - Final check before pushing to remote

## Command-Line Usage

### Basic Commands

```bash
# Run Ameba on entire project
ameba

# Run on specific files
ameba src/models/user.cr

# Run on specific directories
ameba src/services/

# Run with specific configuration
ameba --config .ameba.custom.yml

# Generate default configuration
ameba --gen-config

# Auto-fix correctable issues
ameba --fix

# Only check specific rules
ameba --only Style/RedundantReturn

# Exclude specific rules
ameba --except Style/LargeNumbers

# Format output
ameba --format json
ameba --format junit
ameba --format flycheck

# Explain issues at specific location
ameba --explain src/models/user.cr:10:5

# Run with all output
ameba --all

# Fail silently on no issues
ameba --silent
```

### Output Formats

```bash
# Default: Human-readable
ameba
# Output:
# src/user.cr:10:5: Style/RedundantReturn: Redundant return detected

# JSON format (for parsing)
ameba --format json
# Output: {"sources": [...], "summary": {...}}

# JUnit XML (for CI integration)
ameba --format junit > ameba-results.xml

# Flycheck format (for Emacs)
ameba --format flycheck
```

### Advanced Usage

```bash
# Check only changed files (git)
git diff --name-only --diff-filter=ACM | grep '\.cr$' | xargs ameba

# Check only staged files
git diff --cached --name-only --diff-filter=ACM | grep '\.cr$' | xargs ameba

# Run with parallel processing (if available)
ameba --parallel

# Set exit code based on severity
ameba --fail-level error    # Only fail on errors
ameba --fail-level warning  # Fail on warnings and errors
ameba --fail-level convention  # Fail on everything

# Generate formatted report
ameba --format json | jq '.summary'
```

## Pre-Commit Hooks

### Git Hook Setup

Create `.git/hooks/pre-commit`:

```bash
#!/bin/sh
# .git/hooks/pre-commit - Run Ameba on staged Crystal files

echo "Running Ameba on staged files..."

# Get staged Crystal files
STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.cr$')

if [ -z "$STAGED_FILES" ]; then
  echo "No Crystal files staged, skipping Ameba"
  exit 0
fi

# Run Ameba on staged files
echo "$STAGED_FILES" | xargs ameba

# Capture exit code
AMEBA_EXIT=$?

if [ $AMEBA_EXIT -ne 0 ]; then
  echo "❌ Ameba found issues. Please fix them before committing."
  echo "Run 'ameba --fix' to auto-correct some issues."
  exit 1
fi

echo "✅ Ameba checks passed"
exit 0
```

Make it executable:

```bash
chmod +x .git/hooks/pre-commit
```

### Advanced Pre-Commit Hook

```bash
#!/bin/sh
# Advanced pre-commit hook with auto-fix option

echo "Running Ameba on staged files..."

STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.cr$')

if [ -z "$STAGED_FILES" ]; then
  exit 0
fi

# Run Ameba
echo "$STAGED_FILES" | xargs ameba
AMEBA_EXIT=$?

if [ $AMEBA_EXIT -ne 0 ]; then
  echo ""
  echo "❌ Ameba found issues."
  echo ""
  read -p "Would you like to auto-fix correctable issues? (y/n) " -n 1 -r
  echo

  if [[ $REPLY =~ ^[Yy]$ ]]; then
    echo "Running ameba --fix..."
    echo "$STAGED_FILES" | xargs ameba --fix

    # Re-add fixed files
    echo "$STAGED_FILES" | xargs git add

    echo "✅ Auto-fixed issues and re-staged files"
    echo "⚠️  Please review the changes before committing again"
    exit 1  # Exit to allow review
  else
    echo "Please fix issues manually before committing"
    exit 1
  fi
fi

echo "✅ Ameba checks passed"
exit 0
```

### Pre-Commit Framework Integration

Using the [pre-commit](https://pre-commit.com/) framework:

Create `.pre-commit-config.yaml`:

```yaml
# .pre-commit-config.yaml
repos:
  - repo: local
    hooks:
      - id: ameba
        name: Ameba (Crystal Linter)
        entry: ameba
        language: system
        files: \.cr$
        pass_filenames: true

  - repo: local
    hooks:
      - id: crystal-format
        name: Crystal Format
        entry: crystal tool format
        language: system
        files: \.cr$
        pass_filenames: true
```

Install and use:

```bash
# Install pre-commit
pip install pre-commit  # or brew install pre-commit

# Install hooks
pre-commit install

# Run manually
pre-commit run --all-files

# Run on specific files
pre-commit run --files src/user.cr
```

### Pre-Commit Configuration Options

```yaml
# .pre-commit-config.yaml with options
repos:
  - repo: local
    hooks:
      - id: ameba
        name: Ameba
        entry: ameba
        language: system
        files: \.cr$
        pass_filenames: true

      - id: ameba-strict
        name: Ameba (Strict)
        entry: ameba --fail-level convention
        language: system
        files: ^src/.*\.cr$  # Only src directory
        pass_filenames: true

      - id: ameba-autofix
        name: Ameba Auto-fix
        entry: ameba --fix
        language: system
        files: \.cr$
        pass_filenames: true
```

## GitHub Actions Integration

### Basic GitHub Actions Workflow

Create `.github/workflows/ameba.yml`:

```yaml
name: Ameba
user-invocable: false

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main, develop ]

jobs:
  lint:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Install Crystal
        uses: crystal-lang/install-crystal@v1
        with:
          crystal: latest

      - name: Install dependencies
        run: shards install

      - name: Run Ameba
        uses: crystal-ameba/[email protected]
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

### Advanced GitHub Actions Configuration

```yaml
name: Code Quality
user-invocable: false

on:
  push:
    branches: [ main ]
  pull_request:
    types: [ opened, synchronize, reopened ]

jobs:
  ameba:
    name: Ameba Linting
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@v4
        with:
          fetch-depth: 0  # Full history for better analysis

      - name: Install Crystal
        uses: crystal-lang/install-crystal@v1
        with:
          crystal: 1.11.0  # Pin version for consistency

      - name: Cache shards
        uses: actions/cache@v3
        with:
          path: lib
          key: ${{ runner.os }}-shards-${{ hashFiles('shard.lock') }}
          restore-keys: |
            ${{ runner.os }}-shards-

      - name: Install dependencies
        run: shards install

      - name: Run Ameba
        uses: crystal-ameba/[email protected]
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Upload Ameba results
        if: always()
        uses: actions/upload-artifact@v3
        with:
          name: ameba-results
          path: ameba-results.json
```

### Matrix Testing Across Crystal Versions

```yaml
name: Quality Across Versions
user-invocable: false

on: [push, pull_request]

jobs:
  ameba:
    strategy:
      matrix:
        crystal: [1.10.0, 1.11.0, latest]
        os: [ubuntu-latest, macos-latest]

    runs-on: ${{ matrix.os }}

    steps:
      - uses: actions/checkout@v4

      - name: Install Crystal ${{ matrix.crystal }}
        uses: crystal-lang/install-crystal@v1
        with:
          crystal: ${{ matrix.crystal }}

      - name: Install dependencies
        run: shards install

      - name: Run Ameba
        run: |
          crystal run bin/ameba.cr -- --format json > ameba-results.json

      - name: Check results
        run: |
          if [ $(jq