ameba-integration — Skillopedia

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 t…

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

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

)\n\nif [ -z \"$STAGED_FILES\" ]; then\n echo \"No Crystal files staged, skipping Ameba\"\n exit 0\nfi\n\n# Run Ameba on staged files\necho \"$STAGED_FILES\" | xargs ameba\n\n# Capture exit code\nAMEBA_EXIT=$?\n\nif [ $AMEBA_EXIT -ne 0 ]; then\n echo \"❌ Ameba found issues. Please fix them before committing.\"\n echo \"Run 'ameba --fix' to auto-correct some issues.\"\n exit 1\nfi\n\necho \"✅ Ameba checks passed\"\nexit 0\n```\n\nMake it executable:\n\n```bash\nchmod +x .git/hooks/pre-commit\n```\n\n### Advanced Pre-Commit Hook\n\n```bash\n#!/bin/sh\n# Advanced pre-commit hook with auto-fix option\n\necho \"Running Ameba on staged files...\"\n\nSTAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\\.cr

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

)\n\nif [ -z \"$STAGED_FILES\" ]; then\n exit 0\nfi\n\n# Run Ameba\necho \"$STAGED_FILES\" | xargs ameba\nAMEBA_EXIT=$?\n\nif [ $AMEBA_EXIT -ne 0 ]; then\n echo \"\"\n echo \"❌ Ameba found issues.\"\n echo \"\"\n read -p \"Would you like to auto-fix correctable issues? (y/n) \" -n 1 -r\n echo\n\n if [[ $REPLY =~ ^[Yy]$ ]]; then\n echo \"Running ameba --fix...\"\n echo \"$STAGED_FILES\" | xargs ameba --fix\n\n # Re-add fixed files\n echo \"$STAGED_FILES\" | xargs git add\n\n echo \"✅ Auto-fixed issues and re-staged files\"\n echo \"⚠️ Please review the changes before committing again\"\n exit 1 # Exit to allow review\n else\n echo \"Please fix issues manually before committing\"\n exit 1\n fi\nfi\n\necho \"✅ Ameba checks passed\"\nexit 0\n```\n\n### Pre-Commit Framework Integration\n\nUsing the [pre-commit](https://pre-commit.com/) framework:\n\nCreate `.pre-commit-config.yaml`:\n\n```yaml\n# .pre-commit-config.yaml\nrepos:\n - repo: local\n hooks:\n - id: ameba\n name: Ameba (Crystal Linter)\n entry: ameba\n language: system\n files: \\.cr$\n pass_filenames: true\n\n - repo: local\n hooks:\n - id: crystal-format\n name: Crystal Format\n entry: crystal tool format\n language: system\n files: \\.cr$\n pass_filenames: true\n```\n\nInstall and use:\n\n```bash\n# Install pre-commit\npip install pre-commit # or brew install pre-commit\n\n# Install hooks\npre-commit install\n\n# Run manually\npre-commit run --all-files\n\n# Run on specific files\npre-commit run --files src/user.cr\n```\n\n### Pre-Commit Configuration Options\n\n```yaml\n# .pre-commit-config.yaml with options\nrepos:\n - repo: local\n hooks:\n - id: ameba\n name: Ameba\n entry: ameba\n language: system\n files: \\.cr$\n pass_filenames: true\n\n - id: ameba-strict\n name: Ameba (Strict)\n entry: ameba --fail-level convention\n language: system\n files: ^src/.*\\.cr$ # Only src directory\n pass_filenames: true\n\n - id: ameba-autofix\n name: Ameba Auto-fix\n entry: ameba --fix\n language: system\n files: \\.cr$\n pass_filenames: true\n```\n\n## GitHub Actions Integration\n\n### Basic GitHub Actions Workflow\n\nCreate `.github/workflows/ameba.yml`:\n\n```yaml\nname: Ameba\nuser-invocable: false\n\non:\n push:\n branches: [ main, develop ]\n pull_request:\n branches: [ main, develop ]\n\njobs:\n lint:\n runs-on: ubuntu-latest\n\n steps:\n - name: Checkout code\n uses: actions/checkout@v4\n\n - name: Install Crystal\n uses: crystal-lang/install-crystal@v1\n with:\n crystal: latest\n\n - name: Install dependencies\n run: shards install\n\n - name: Run Ameba\n uses: crystal-ameba/[email protected]\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n```\n\n### Advanced GitHub Actions Configuration\n\n```yaml\nname: Code Quality\nuser-invocable: false\n\non:\n push:\n branches: [ main ]\n pull_request:\n types: [ opened, synchronize, reopened ]\n\njobs:\n ameba:\n name: Ameba Linting\n runs-on: ubuntu-latest\n\n steps:\n - name: Checkout code\n uses: actions/checkout@v4\n with:\n fetch-depth: 0 # Full history for better analysis\n\n - name: Install Crystal\n uses: crystal-lang/install-crystal@v1\n with:\n crystal: 1.11.0 # Pin version for consistency\n\n - name: Cache shards\n uses: actions/cache@v3\n with:\n path: lib\n key: ${{ runner.os }}-shards-${{ hashFiles('shard.lock') }}\n restore-keys: |\n ${{ runner.os }}-shards-\n\n - name: Install dependencies\n run: shards install\n\n - name: Run Ameba\n uses: crystal-ameba/[email protected]\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n\n - name: Upload Ameba results\n if: always()\n uses: actions/upload-artifact@v3\n with:\n name: ameba-results\n path: ameba-results.json\n```\n\n### Matrix Testing Across Crystal Versions\n\n```yaml\nname: Quality Across Versions\nuser-invocable: false\n\non: [push, pull_request]\n\njobs:\n ameba:\n strategy:\n matrix:\n crystal: [1.10.0, 1.11.0, latest]\n os: [ubuntu-latest, macos-latest]\n\n runs-on: ${{ matrix.os }}\n\n steps:\n - uses: actions/checkout@v4\n\n - name: Install Crystal ${{ matrix.crystal }}\n uses: crystal-lang/install-crystal@v1\n with:\n crystal: ${{ matrix.crystal }}\n\n - name: Install dependencies\n run: shards install\n\n - name: Run Ameba\n run: |\n crystal run bin/ameba.cr -- --format json > ameba-results.json\n\n - name: Check results\n run: |\n if [ $(jq '.summary.issues_count' ameba-results.json) -gt 0 ]; then\n echo \"❌ Found issues\"\n jq '.summary' ameba-results.json\n exit 1\n fi\n```\n\n### Pull Request Review Integration\n\n```yaml\nname: PR Code Review\nuser-invocable: false\n\non:\n pull_request:\n types: [ opened, synchronize ]\n\njobs:\n review:\n runs-on: ubuntu-latest\n\n permissions:\n contents: read\n pull-requests: write\n\n steps:\n - uses: actions/checkout@v4\n with:\n fetch-depth: 0\n\n - name: Install Crystal\n uses: crystal-lang/install-crystal@v1\n\n - name: Install dependencies\n run: shards install\n\n - name: Get changed files\n id: changed-files\n uses: tj-actions/changed-files@v40\n with:\n files: |\n **/*.cr\n\n - name: Run Ameba on changed files\n if: steps.changed-files.outputs.any_changed == 'true'\n run: |\n echo \"${{ steps.changed-files.outputs.all_changed_files }}\" | \\\n xargs ameba --format json > ameba-results.json\n\n - name: Comment PR\n if: steps.changed-files.outputs.any_changed == 'true'\n uses: actions/github-script@v7\n with:\n script: |\n const fs = require('fs');\n const results = JSON.parse(fs.readFileSync('ameba-results.json', 'utf8'));\n\n if (results.summary.issues_count > 0) {\n const body = `## Ameba Report\n\n Found ${results.summary.issues_count} issue(s):\n\n ${results.sources.flatMap(s =>\n s.issues.map(i =>\n \\`- \\${s.path}:\\${i.location.line}:\\${i.location.column} - \\${i.rule.name}: \\${i.message}\\`\n )\n ).join('\\\\n')}`;\n\n await github.rest.issues.createComment({\n owner: context.repo.owner,\n repo: context.repo.repo,\n issue_number: context.issue.number,\n body: body\n });\n }\n```\n\n## CI/CD Pipeline Integration\n\n### GitLab CI/CD\n\n```yaml\n# .gitlab-ci.yml\nstages:\n - quality\n - test\n - build\n\nameba:\n stage: quality\n image: crystallang/crystal:latest\n\n before_script:\n - shards install\n\n script:\n - crystal run bin/ameba.cr -- --format junit > ameba-results.xml\n\n artifacts:\n reports:\n junit: ameba-results.xml\n paths:\n - ameba-results.xml\n when: always\n expire_in: 1 week\n\n rules:\n - if: '$CI_PIPELINE_SOURCE == \"merge_request_event\"'\n - if: '$CI_COMMIT_BRANCH == \"main\"'\n\nameba-strict:\n extends: ameba\n script:\n - crystal run bin/ameba.cr -- --fail-level convention\n only:\n - main\n```\n\n### CircleCI\n\n```yaml\n# .circleci/config.yml\nversion: 2.1\n\norbs:\n crystal: manastech/[email protected]\n\njobs:\n ameba:\n executor:\n name: crystal/default\n tag: \"1.11\"\n\n steps:\n - checkout\n\n - restore_cache:\n keys:\n - shards-v1-{{ checksum \"shard.lock\" }}\n - shards-v1-\n\n - run:\n name: Install dependencies\n command: shards install\n\n - save_cache:\n key: shards-v1-{{ checksum \"shard.lock\" }}\n paths:\n - lib\n\n - run:\n name: Run Ameba\n command: |\n crystal run bin/ameba.cr -- --format junit > ameba-results.xml\n\n - store_test_results:\n path: ameba-results.xml\n\n - store_artifacts:\n path: ameba-results.xml\n\nworkflows:\n version: 2\n quality:\n jobs:\n - ameba\n```\n\n### Jenkins Pipeline\n\n```groovy\n// Jenkinsfile\npipeline {\n agent {\n docker {\n image 'crystallang/crystal:latest'\n }\n }\n\n stages {\n stage('Setup') {\n steps {\n sh 'shards install'\n }\n }\n\n stage('Ameba') {\n steps {\n sh '''\n crystal run bin/ameba.cr -- --format junit > ameba-results.xml || true\n '''\n }\n post {\n always {\n junit 'ameba-results.xml'\n }\n }\n }\n\n stage('Ameba Strict') {\n when {\n branch 'main'\n }\n steps {\n sh 'crystal run bin/ameba.cr -- --fail-level error'\n }\n }\n }\n\n post {\n failure {\n emailext(\n subject: \"Ameba Failures in ${env.JOB_NAME}\",\n body: \"Check console output at ${env.BUILD_URL}\",\n to: \"${env.CHANGE_AUTHOR_EMAIL}\"\n )\n }\n }\n}\n```\n\n### Travis CI\n\n```yaml\n# .travis.yml\nlanguage: crystal\n\ncrystal:\n - latest\n - 1.11.0\n\ninstall:\n - shards install\n\nscript:\n - crystal spec\n - crystal run bin/ameba.cr -- --fail-level warning\n\ncache:\n directories:\n - lib\n\nnotifications:\n email:\n on_success: never\n on_failure: change\n```\n\n## Editor Integration\n\n### VS Code\n\nInstall the Crystal Language extension and configure:\n\n```json\n// .vscode/settings.json\n{\n \"crystal-lang.server\": \"crystalline\",\n \"crystal-lang.problems\": \"build\",\n\n // Run Ameba on save\n \"emeraldwalk.runonsave\": {\n \"commands\": [\n {\n \"match\": \"\\\\.cr$\",\n \"cmd\": \"ameba ${file}\"\n }\n ]\n },\n\n // Format on save\n \"editor.formatOnSave\": true,\n \"[crystal]\": {\n \"editor.defaultFormatter\": \"crystal-lang-tools.crystal-lang\"\n }\n}\n```\n\nCreate `.vscode/tasks.json`:\n\n```json\n{\n \"version\": \"2.0.0\",\n \"tasks\": [\n {\n \"label\": \"Ameba\",\n \"type\": \"shell\",\n \"command\": \"ameba\",\n \"problemMatcher\": {\n \"owner\": \"crystal\",\n \"fileLocation\": [\"relative\", \"${workspaceFolder}\"],\n \"pattern\": {\n \"regexp\": \"^(.+):(\\\\d+):(\\\\d+):\\\\s+(.+):\\\\s+(.+)$\",\n \"file\": 1,\n \"line\": 2,\n \"column\": 3,\n \"severity\": 4,\n \"message\": 5\n }\n },\n \"group\": {\n \"kind\": \"build\",\n \"isDefault\": true\n }\n },\n {\n \"label\": \"Ameba Fix\",\n \"type\": \"shell\",\n \"command\": \"ameba --fix\",\n \"group\": \"build\"\n }\n ]\n}\n```\n\n### Vim/Neovim\n\nUsing ALE (Asynchronous Lint Engine):\n\n```vim\n\" .vimrc or init.vim\nlet g:ale_linters = {\n\\ 'crystal': ['ameba', 'crystal'],\n\\}\n\nlet g:ale_fixers = {\n\\ 'crystal': ['ameba'],\n\\}\n\n\" Enable auto-fixing on save\nlet g:ale_fix_on_save = 1\n\n\" Ameba options\nlet g:ale_crystal_ameba_executable = 'ameba'\n```\n\n### Emacs\n\n```elisp\n;; .emacs or init.el\n(require 'flycheck)\n\n(flycheck-define-checker crystal-ameba\n \"Crystal linter using Ameba.\"\n :command (\"ameba\" \"--format\" \"flycheck\" source)\n :error-patterns\n ((error line-start (file-name) \":\" line \":\" column \": E: \" (message) line-end)\n (warning line-start (file-name) \":\" line \":\" column \": W: \" (message) line-end)\n (info line-start (file-name) \":\" line \":\" column \": I: \" (message) line-end))\n :modes crystal-mode)\n\n(add-to-list 'flycheck-checkers 'crystal-ameba)\n```\n\n## Quality Gates and Policies\n\n### Fail-Fast Strategy\n\n```bash\n#!/bin/bash\n# scripts/quality-gate.sh\n\necho \"Running quality gates...\"\n\n# Gate 1: Critical errors only\necho \"Gate 1: Critical errors\"\nameba --only Lint/Syntax,Lint/UnreachableCode --fail-level error\nif [ $? -ne 0 ]; then\n echo \"❌ Critical errors found\"\n exit 1\nfi\n\n# Gate 2: All errors\necho \"Gate 2: All errors\"\nameba --fail-level error\nif [ $? -ne 0 ]; then\n echo \"❌ Errors found\"\n exit 1\nfi\n\n# Gate 3: Warnings (non-blocking for now)\necho \"Gate 3: Warnings (informational)\"\nameba --fail-level warning || echo \"⚠️ Warnings found (not blocking)\"\n\necho \"✅ All quality gates passed\"\n```\n\n### Progressive Strictness\n\n```yaml\n# .github/workflows/quality-gates.yml\nname: Quality Gates\nuser-invocable: false\n\non: [push, pull_request]\n\njobs:\n critical:\n name: Critical Issues\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: crystal-lang/install-crystal@v1\n - run: shards install\n - name: Check critical\n run: ameba --only Lint/Syntax --fail-level error\n\n errors:\n name: All Errors\n needs: critical\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: crystal-lang/install-crystal@v1\n - run: shards install\n - name: Check errors\n run: ameba --fail-level error\n\n warnings:\n name: Warnings (Main Only)\n needs: errors\n if: github.ref == 'refs/heads/main'\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: crystal-lang/install-crystal@v1\n - run: shards install\n - name: Check warnings\n run: ameba --fail-level warning\n```\n\n### Ratcheting (Prevent New Issues)\n\n```bash\n#!/bin/bash\n# scripts/ameba-ratchet.sh\n# Only fail on new issues, not existing ones\n\n# Get baseline issue count (from main branch)\ngit fetch origin main\nBASELINE=$(git show origin/main:.ameba-baseline.json 2>/dev/null || echo '{\"count\": 0}')\nBASELINE_COUNT=$(echo \"$BASELINE\" | jq '.count')\n\n# Run Ameba and count current issues\nameba --format json > current-results.json\nCURRENT_COUNT=$(jq '.summary.issues_count' current-results.json)\n\necho \"Baseline issues: $BASELINE_COUNT\"\necho \"Current issues: $CURRENT_COUNT\"\n\nif [ \"$CURRENT_COUNT\" -gt \"$BASELINE_COUNT\" ]; then\n echo \"❌ New issues introduced ($((CURRENT_COUNT - BASELINE_COUNT)) new issues)\"\n exit 1\nfi\n\nif [ \"$CURRENT_COUNT\" -lt \"$BASELINE_COUNT\" ]; then\n echo \"✅ Issues reduced! ($((BASELINE_COUNT - CURRENT_COUNT)) fewer issues)\"\nfi\n\necho \"✅ No new issues\"\n```\n\n## Reporting and Monitoring\n\n### Generate HTML Reports\n\n```bash\n#!/bin/bash\n# scripts/generate-report.sh\n\nameba --format json > ameba-results.json\n\n# Convert to HTML using jq and template\ncat > ameba-report.html \u003c\u003c'EOF'\n\u003c!DOCTYPE html>\n\u003chtml>\n\u003chead>\n \u003ctitle>Ameba Report\u003c/title>\n \u003cstyle>\n body { font-family: Arial, sans-serif; margin: 20px; }\n .summary { background: #f0f0f0; padding: 20px; margin-bottom: 20px; }\n .issue { border-left: 3px solid red; padding: 10px; margin: 10px 0; }\n .error { border-color: #d32f2f; }\n .warning { border-color: #f57c00; }\n .convention { border-color: #fbc02d; }\n \u003c/style>\n\u003c/head>\n\u003cbody>\n \u003ch1>Ameba Code Quality Report\u003c/h1>\n \u003cdiv class=\"summary\">\nEOF\n\njq -r '.summary | \"\n \u003ch2>Summary\u003c/h2>\n \u003cp>Total Issues: \\(.issues_count)\u003c/p>\n \u003cp>Files Analyzed: \\(.target_sources_count)\u003c/p>\n\"' ameba-results.json >> ameba-report.html\n\necho '\u003ch2>Issues\u003c/h2>' >> ameba-report.html\n\njq -r '.sources[] | select(.issues | length > 0) | .path as $path | .issues[] | \"\n \u003cdiv class=\\\"issue \\(.rule.severity | ascii_downcase)\\\">\n \u003cstrong>\\($path):\\(.location.line):\\(.location.column)\u003c/strong>\u003cbr>\n \\(.rule.name): \\(.message)\n \u003c/div>\n\"' ameba-results.json >> ameba-report.html\n\necho '\u003c/body>\u003c/html>' >> ameba-report.html\n\necho \"Report generated: ameba-report.html\"\n```\n\n### Metrics Tracking\n\n```bash\n#!/bin/bash\n# scripts/track-metrics.sh\n# Track Ameba metrics over time\n\nTIMESTAMP=$(date +%Y-%m-%d)\nameba --format json > \"metrics/ameba-$TIMESTAMP.json\"\n\n# Extract key metrics\njq '{\n date: \"'$TIMESTAMP'\",\n issues: .summary.issues_count,\n files: .summary.target_sources_count,\n errors: [.sources[].issues[] | select(.rule.severity == \"Error\")] | length,\n warnings: [.sources[].issues[] | select(.rule.severity == \"Warning\")] | length\n}' \"metrics/ameba-$TIMESTAMP.json\" >> metrics/history.jsonl\n\n# Generate trend chart (requires gnuplot or similar)\necho \"Metrics tracked for $TIMESTAMP\"\n```\n\n## When to Use This Skill\n\nUse the ameba-integration skill when:\n\n- Setting up CI/CD pipelines for Crystal projects\n- Implementing automated code review processes\n- Establishing quality gates for deployments\n- Configuring pre-commit hooks for team development\n- Integrating static analysis into GitHub Actions\n- Creating automated PR review workflows\n- Setting up editor integrations for real-time feedback\n- Implementing progressive quality improvements (ratcheting)\n- Generating code quality reports for stakeholders\n- Migrating from manual code review to automated checks\n- Establishing coding standards enforcement\n- Onboarding new team members with automated feedback\n\n## Best Practices\n\n1. **Start with CI/CD** - Implement in CI pipeline first before local hooks\n2. **Use caching** - Cache dependencies and Ameba results for faster builds\n3. **Fail appropriately** - Use `--fail-level` to match pipeline requirements\n4. **Provide feedback** - Generate reports and comments on PRs\n5. **Make it fast** - Only check changed files in pre-commit hooks\n6. **Allow bypass** - Provide `--no-verify` option for emergencies\n7. **Progressive enforcement** - Start permissive, increase strictness over time\n8. **Monitor metrics** - Track issues over time to measure improvement\n9. **Separate concerns** - Different rules/severity for different environments\n10. **Document process** - Clear instructions for team on running locally\n11. **Use artifacts** - Store results for later analysis and trending\n12. **Auto-fix when possible** - Offer automatic fixes in interactive environments\n13. **Pin versions** - Use specific Ameba versions in CI for consistency\n14. **Handle failures gracefully** - Provide helpful error messages\n15. **Keep it maintained** - Regularly update integrations and configurations\n\n## Common Pitfalls\n\n1. **Blocking all commits** - Too strict pre-commit hooks frustrate developers\n2. **No caching** - Slow CI builds from re-downloading dependencies every time\n3. **Analyzing generated files** - Wasting time on auto-generated code\n4. **Not pinning versions** - Different Ameba versions produce different results\n5. **Missing changed files detection** - Running on entire codebase in every PR\n6. **No failure context** - Cryptic error messages without guidance\n7. **Inconsistent configuration** - Different settings locally vs CI\n8. **Long feedback loops** - Developers find out about issues too late\n9. **No auto-fix option** - Manual fixes for correctable issues\n10. **Silent failures** - CI passes but Ameba didn't actually run\n11. **Excessive notifications** - Spamming team with every minor issue\n12. **No bypass mechanism** - Can't commit urgent fixes when needed\n13. **Ignoring performance** - CI timeout from slow analysis\n14. **Not using parallel jobs** - Sequential execution slows down pipeline\n15. **Missing test coverage** - Not verifying integration actually works\n\n## Resources\n\n- [Crystal Ameba GitHub Action](https://github.com/crystal-ameba/github-action)\n- [Ameba GitHub Repository](https://github.com/crystal-ameba/ameba)\n- [Pre-commit Framework](https://pre-commit.com/)\n- [GitHub Actions Documentation](https://docs.github.com/en/actions)\n- [GitLab CI/CD Documentation](https://docs.gitlab.com/ee/ci/)\n- [CircleCI Documentation](https://circleci.com/docs/)\n- [Jenkins Pipeline Documentation](https://www.jenkins.io/doc/book/pipeline/)\n---","attachment_filenames":[],"attachments":[],"content_json":{"type":"doc","content":[{"type":"heading","attrs":{"level":1},"content":[{"text":"Ameba Integration","type":"text"}]},{"type":"paragraph","content":[{"text":"Integrate Ameba into your development workflow for automated Crystal code quality checks in CI/CD pipelines, pre-commit hooks, and code review processes.","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Integration Overview","type":"text"}]},{"type":"paragraph","content":[{"text":"Ameba can be integrated at multiple points in your development workflow:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Pre-commit hooks","type":"text","marks":[{"type":"strong"}]},{"text":" - Catch issues before they're committed","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CI/CD pipelines","type":"text","marks":[{"type":"strong"}]},{"text":" - Enforce quality gates in automated builds","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"GitHub Actions","type":"text","marks":[{"type":"strong"}]},{"text":" - Automated PR reviews and status checks","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Editor integration","type":"text","marks":[{"type":"strong"}]},{"text":" - Real-time feedback while coding","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Code review","type":"text","marks":[{"type":"strong"}]},{"text":" - Automated comments on pull requests","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Pre-push hooks","type":"text","marks":[{"type":"strong"}]},{"text":" - Final check before pushing to remote","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Command-Line Usage","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Basic Commands","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Run Ameba on entire project\nameba\n\n# Run on specific files\nameba src/models/user.cr\n\n# Run on specific directories\nameba src/services/\n\n# Run with specific configuration\nameba --config .ameba.custom.yml\n\n# Generate default configuration\nameba --gen-config\n\n# Auto-fix correctable issues\nameba --fix\n\n# Only check specific rules\nameba --only Style/RedundantReturn\n\n# Exclude specific rules\nameba --except Style/LargeNumbers\n\n# Format output\nameba --format json\nameba --format junit\nameba --format flycheck\n\n# Explain issues at specific location\nameba --explain src/models/user.cr:10:5\n\n# Run with all output\nameba --all\n\n# Fail silently on no issues\nameba --silent","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Output Formats","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Default: Human-readable\nameba\n# Output:\n# src/user.cr:10:5: Style/RedundantReturn: Redundant return detected\n\n# JSON format (for parsing)\nameba --format json\n# Output: {\"sources\": [...], \"summary\": {...}}\n\n# JUnit XML (for CI integration)\nameba --format junit > ameba-results.xml\n\n# Flycheck format (for Emacs)\nameba --format flycheck","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Advanced Usage","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Check only changed files (git)\ngit diff --name-only --diff-filter=ACM | grep '\\.cr

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

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

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

| xargs ameba\n\n# Run with parallel processing (if available)\nameba --parallel\n\n# Set exit code based on severity\nameba --fail-level error # Only fail on errors\nameba --fail-level warning # Fail on warnings and errors\nameba --fail-level convention # Fail on everything\n\n# Generate formatted report\nameba --format json | jq '.summary'","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Pre-Commit Hooks","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Git Hook Setup","type":"text"}]},{"type":"paragraph","content":[{"text":"Create ","type":"text"},{"text":".git/hooks/pre-commit","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"#!/bin/sh\n# .git/hooks/pre-commit - Run Ameba on staged Crystal files\n\necho \"Running Ameba on staged files...\"\n\n# Get staged Crystal files\nSTAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\\.cr

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

)\n\nif [ -z \"$STAGED_FILES\" ]; then\n echo \"No Crystal files staged, skipping Ameba\"\n exit 0\nfi\n\n# Run Ameba on staged files\necho \"$STAGED_FILES\" | xargs ameba\n\n# Capture exit code\nAMEBA_EXIT=$?\n\nif [ $AMEBA_EXIT -ne 0 ]; then\n echo \"❌ Ameba found issues. Please fix them before committing.\"\n echo \"Run 'ameba --fix' to auto-correct some issues.\"\n exit 1\nfi\n\necho \"✅ Ameba checks passed\"\nexit 0","type":"text"}]},{"type":"paragraph","content":[{"text":"Make it executable:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"chmod +x .git/hooks/pre-commit","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Advanced Pre-Commit Hook","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"#!/bin/sh\n# Advanced pre-commit hook with auto-fix option\n\necho \"Running Ameba on staged files...\"\n\nSTAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\\.cr

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.

)\n\nif [ -z \"$STAGED_FILES\" ]; then\n exit 0\nfi\n\n# Run Ameba\necho \"$STAGED_FILES\" | xargs ameba\nAMEBA_EXIT=$?\n\nif [ $AMEBA_EXIT -ne 0 ]; then\n echo \"\"\n echo \"❌ Ameba found issues.\"\n echo \"\"\n read -p \"Would you like to auto-fix correctable issues? (y/n) \" -n 1 -r\n echo\n\n if [[ $REPLY =~ ^[Yy]$ ]]; then\n echo \"Running ameba --fix...\"\n echo \"$STAGED_FILES\" | xargs ameba --fix\n\n # Re-add fixed files\n echo \"$STAGED_FILES\" | xargs git add\n\n echo \"✅ Auto-fixed issues and re-staged files\"\n echo \"⚠️ Please review the changes before committing again\"\n exit 1 # Exit to allow review\n else\n echo \"Please fix issues manually before committing\"\n exit 1\n fi\nfi\n\necho \"✅ Ameba checks passed\"\nexit 0","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Pre-Commit Framework Integration","type":"text"}]},{"type":"paragraph","content":[{"text":"Using the ","type":"text"},{"text":"pre-commit","type":"text","marks":[{"type":"link","attrs":{"href":"https://pre-commit.com/","title":null}}]},{"text":" framework:","type":"text"}]},{"type":"paragraph","content":[{"text":"Create ","type":"text"},{"text":".pre-commit-config.yaml","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"# .pre-commit-config.yaml\nrepos:\n - repo: local\n hooks:\n - id: ameba\n name: Ameba (Crystal Linter)\n entry: ameba\n language: system\n files: \\.cr$\n pass_filenames: true\n\n - repo: local\n hooks:\n - id: crystal-format\n name: Crystal Format\n entry: crystal tool format\n language: system\n files: \\.cr$\n pass_filenames: true","type":"text"}]},{"type":"paragraph","content":[{"text":"Install and use:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"# Install pre-commit\npip install pre-commit # or brew install pre-commit\n\n# Install hooks\npre-commit install\n\n# Run manually\npre-commit run --all-files\n\n# Run on specific files\npre-commit run --files src/user.cr","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Pre-Commit Configuration Options","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"# .pre-commit-config.yaml with options\nrepos:\n - repo: local\n hooks:\n - id: ameba\n name: Ameba\n entry: ameba\n language: system\n files: \\.cr$\n pass_filenames: true\n\n - id: ameba-strict\n name: Ameba (Strict)\n entry: ameba --fail-level convention\n language: system\n files: ^src/.*\\.cr$ # Only src directory\n pass_filenames: true\n\n - id: ameba-autofix\n name: Ameba Auto-fix\n entry: ameba --fix\n language: system\n files: \\.cr$\n pass_filenames: true","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"GitHub Actions Integration","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Basic GitHub Actions Workflow","type":"text"}]},{"type":"paragraph","content":[{"text":"Create ","type":"text"},{"text":".github/workflows/ameba.yml","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"name: Ameba\nuser-invocable: false\n\non:\n push:\n branches: [ main, develop ]\n pull_request:\n branches: [ main, develop ]\n\njobs:\n lint:\n runs-on: ubuntu-latest\n\n steps:\n - name: Checkout code\n uses: actions/checkout@v4\n\n - name: Install Crystal\n uses: crystal-lang/install-crystal@v1\n with:\n crystal: latest\n\n - name: Install dependencies\n run: shards install\n\n - name: Run Ameba\n uses: crystal-ameba/[email protected]\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Advanced GitHub Actions Configuration","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"name: Code Quality\nuser-invocable: false\n\non:\n push:\n branches: [ main ]\n pull_request:\n types: [ opened, synchronize, reopened ]\n\njobs:\n ameba:\n name: Ameba Linting\n runs-on: ubuntu-latest\n\n steps:\n - name: Checkout code\n uses: actions/checkout@v4\n with:\n fetch-depth: 0 # Full history for better analysis\n\n - name: Install Crystal\n uses: crystal-lang/install-crystal@v1\n with:\n crystal: 1.11.0 # Pin version for consistency\n\n - name: Cache shards\n uses: actions/cache@v3\n with:\n path: lib\n key: ${{ runner.os }}-shards-${{ hashFiles('shard.lock') }}\n restore-keys: |\n ${{ runner.os }}-shards-\n\n - name: Install dependencies\n run: shards install\n\n - name: Run Ameba\n uses: crystal-ameba/[email protected]\n env:\n GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}\n\n - name: Upload Ameba results\n if: always()\n uses: actions/upload-artifact@v3\n with:\n name: ameba-results\n path: ameba-results.json","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Matrix Testing Across Crystal Versions","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"name: Quality Across Versions\nuser-invocable: false\n\non: [push, pull_request]\n\njobs:\n ameba:\n strategy:\n matrix:\n crystal: [1.10.0, 1.11.0, latest]\n os: [ubuntu-latest, macos-latest]\n\n runs-on: ${{ matrix.os }}\n\n steps:\n - uses: actions/checkout@v4\n\n - name: Install Crystal ${{ matrix.crystal }}\n uses: crystal-lang/install-crystal@v1\n with:\n crystal: ${{ matrix.crystal }}\n\n - name: Install dependencies\n run: shards install\n\n - name: Run Ameba\n run: |\n crystal run bin/ameba.cr -- --format json > ameba-results.json\n\n - name: Check results\n run: |\n if [ $(jq '.summary.issues_count' ameba-results.json) -gt 0 ]; then\n echo \"❌ Found issues\"\n jq '.summary' ameba-results.json\n exit 1\n fi","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Pull Request Review Integration","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"name: PR Code Review\nuser-invocable: false\n\non:\n pull_request:\n types: [ opened, synchronize ]\n\njobs:\n review:\n runs-on: ubuntu-latest\n\n permissions:\n contents: read\n pull-requests: write\n\n steps:\n - uses: actions/checkout@v4\n with:\n fetch-depth: 0\n\n - name: Install Crystal\n uses: crystal-lang/install-crystal@v1\n\n - name: Install dependencies\n run: shards install\n\n - name: Get changed files\n id: changed-files\n uses: tj-actions/changed-files@v40\n with:\n files: |\n **/*.cr\n\n - name: Run Ameba on changed files\n if: steps.changed-files.outputs.any_changed == 'true'\n run: |\n echo \"${{ steps.changed-files.outputs.all_changed_files }}\" | \\\n xargs ameba --format json > ameba-results.json\n\n - name: Comment PR\n if: steps.changed-files.outputs.any_changed == 'true'\n uses: actions/github-script@v7\n with:\n script: |\n const fs = require('fs');\n const results = JSON.parse(fs.readFileSync('ameba-results.json', 'utf8'));\n\n if (results.summary.issues_count > 0) {\n const body = `## Ameba Report\n\n Found ${results.summary.issues_count} issue(s):\n\n ${results.sources.flatMap(s =>\n s.issues.map(i =>\n \\`- \\${s.path}:\\${i.location.line}:\\${i.location.column} - \\${i.rule.name}: \\${i.message}\\`\n )\n ).join('\\\\n')}`;\n\n await github.rest.issues.createComment({\n owner: context.repo.owner,\n repo: context.repo.repo,\n issue_number: context.issue.number,\n body: body\n });\n }","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"CI/CD Pipeline Integration","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"GitLab CI/CD","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"# .gitlab-ci.yml\nstages:\n - quality\n - test\n - build\n\nameba:\n stage: quality\n image: crystallang/crystal:latest\n\n before_script:\n - shards install\n\n script:\n - crystal run bin/ameba.cr -- --format junit > ameba-results.xml\n\n artifacts:\n reports:\n junit: ameba-results.xml\n paths:\n - ameba-results.xml\n when: always\n expire_in: 1 week\n\n rules:\n - if: '$CI_PIPELINE_SOURCE == \"merge_request_event\"'\n - if: '$CI_COMMIT_BRANCH == \"main\"'\n\nameba-strict:\n extends: ameba\n script:\n - crystal run bin/ameba.cr -- --fail-level convention\n only:\n - main","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"CircleCI","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"# .circleci/config.yml\nversion: 2.1\n\norbs:\n crystal: manastech/[email protected]\n\njobs:\n ameba:\n executor:\n name: crystal/default\n tag: \"1.11\"\n\n steps:\n - checkout\n\n - restore_cache:\n keys:\n - shards-v1-{{ checksum \"shard.lock\" }}\n - shards-v1-\n\n - run:\n name: Install dependencies\n command: shards install\n\n - save_cache:\n key: shards-v1-{{ checksum \"shard.lock\" }}\n paths:\n - lib\n\n - run:\n name: Run Ameba\n command: |\n crystal run bin/ameba.cr -- --format junit > ameba-results.xml\n\n - store_test_results:\n path: ameba-results.xml\n\n - store_artifacts:\n path: ameba-results.xml\n\nworkflows:\n version: 2\n quality:\n jobs:\n - ameba","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Jenkins Pipeline","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"groovy"},"content":[{"text":"// Jenkinsfile\npipeline {\n agent {\n docker {\n image 'crystallang/crystal:latest'\n }\n }\n\n stages {\n stage('Setup') {\n steps {\n sh 'shards install'\n }\n }\n\n stage('Ameba') {\n steps {\n sh '''\n crystal run bin/ameba.cr -- --format junit > ameba-results.xml || true\n '''\n }\n post {\n always {\n junit 'ameba-results.xml'\n }\n }\n }\n\n stage('Ameba Strict') {\n when {\n branch 'main'\n }\n steps {\n sh 'crystal run bin/ameba.cr -- --fail-level error'\n }\n }\n }\n\n post {\n failure {\n emailext(\n subject: \"Ameba Failures in ${env.JOB_NAME}\",\n body: \"Check console output at ${env.BUILD_URL}\",\n to: \"${env.CHANGE_AUTHOR_EMAIL}\"\n )\n }\n }\n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Travis CI","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"# .travis.yml\nlanguage: crystal\n\ncrystal:\n - latest\n - 1.11.0\n\ninstall:\n - shards install\n\nscript:\n - crystal spec\n - crystal run bin/ameba.cr -- --fail-level warning\n\ncache:\n directories:\n - lib\n\nnotifications:\n email:\n on_success: never\n on_failure: change","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Editor Integration","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"VS Code","type":"text"}]},{"type":"paragraph","content":[{"text":"Install the Crystal Language extension and configure:","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"// .vscode/settings.json\n{\n \"crystal-lang.server\": \"crystalline\",\n \"crystal-lang.problems\": \"build\",\n\n // Run Ameba on save\n \"emeraldwalk.runonsave\": {\n \"commands\": [\n {\n \"match\": \"\\\\.cr$\",\n \"cmd\": \"ameba ${file}\"\n }\n ]\n },\n\n // Format on save\n \"editor.formatOnSave\": true,\n \"[crystal]\": {\n \"editor.defaultFormatter\": \"crystal-lang-tools.crystal-lang\"\n }\n}","type":"text"}]},{"type":"paragraph","content":[{"text":"Create ","type":"text"},{"text":".vscode/tasks.json","type":"text","marks":[{"type":"code_inline"}]},{"text":":","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"json"},"content":[{"text":"{\n \"version\": \"2.0.0\",\n \"tasks\": [\n {\n \"label\": \"Ameba\",\n \"type\": \"shell\",\n \"command\": \"ameba\",\n \"problemMatcher\": {\n \"owner\": \"crystal\",\n \"fileLocation\": [\"relative\", \"${workspaceFolder}\"],\n \"pattern\": {\n \"regexp\": \"^(.+):(\\\\d+):(\\\\d+):\\\\s+(.+):\\\\s+(.+)$\",\n \"file\": 1,\n \"line\": 2,\n \"column\": 3,\n \"severity\": 4,\n \"message\": 5\n }\n },\n \"group\": {\n \"kind\": \"build\",\n \"isDefault\": true\n }\n },\n {\n \"label\": \"Ameba Fix\",\n \"type\": \"shell\",\n \"command\": \"ameba --fix\",\n \"group\": \"build\"\n }\n ]\n}","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Vim/Neovim","type":"text"}]},{"type":"paragraph","content":[{"text":"Using ALE (Asynchronous Lint Engine):","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"vim"},"content":[{"text":"\" .vimrc or init.vim\nlet g:ale_linters = {\n\\ 'crystal': ['ameba', 'crystal'],\n\\}\n\nlet g:ale_fixers = {\n\\ 'crystal': ['ameba'],\n\\}\n\n\" Enable auto-fixing on save\nlet g:ale_fix_on_save = 1\n\n\" Ameba options\nlet g:ale_crystal_ameba_executable = 'ameba'","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Emacs","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"elisp"},"content":[{"text":";; .emacs or init.el\n(require 'flycheck)\n\n(flycheck-define-checker crystal-ameba\n \"Crystal linter using Ameba.\"\n :command (\"ameba\" \"--format\" \"flycheck\" source)\n :error-patterns\n ((error line-start (file-name) \":\" line \":\" column \": E: \" (message) line-end)\n (warning line-start (file-name) \":\" line \":\" column \": W: \" (message) line-end)\n (info line-start (file-name) \":\" line \":\" column \": I: \" (message) line-end))\n :modes crystal-mode)\n\n(add-to-list 'flycheck-checkers 'crystal-ameba)","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Quality Gates and Policies","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Fail-Fast Strategy","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"#!/bin/bash\n# scripts/quality-gate.sh\n\necho \"Running quality gates...\"\n\n# Gate 1: Critical errors only\necho \"Gate 1: Critical errors\"\nameba --only Lint/Syntax,Lint/UnreachableCode --fail-level error\nif [ $? -ne 0 ]; then\n echo \"❌ Critical errors found\"\n exit 1\nfi\n\n# Gate 2: All errors\necho \"Gate 2: All errors\"\nameba --fail-level error\nif [ $? -ne 0 ]; then\n echo \"❌ Errors found\"\n exit 1\nfi\n\n# Gate 3: Warnings (non-blocking for now)\necho \"Gate 3: Warnings (informational)\"\nameba --fail-level warning || echo \"⚠️ Warnings found (not blocking)\"\n\necho \"✅ All quality gates passed\"","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Progressive Strictness","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"yaml"},"content":[{"text":"# .github/workflows/quality-gates.yml\nname: Quality Gates\nuser-invocable: false\n\non: [push, pull_request]\n\njobs:\n critical:\n name: Critical Issues\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: crystal-lang/install-crystal@v1\n - run: shards install\n - name: Check critical\n run: ameba --only Lint/Syntax --fail-level error\n\n errors:\n name: All Errors\n needs: critical\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: crystal-lang/install-crystal@v1\n - run: shards install\n - name: Check errors\n run: ameba --fail-level error\n\n warnings:\n name: Warnings (Main Only)\n needs: errors\n if: github.ref == 'refs/heads/main'\n runs-on: ubuntu-latest\n steps:\n - uses: actions/checkout@v4\n - uses: crystal-lang/install-crystal@v1\n - run: shards install\n - name: Check warnings\n run: ameba --fail-level warning","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Ratcheting (Prevent New Issues)","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"#!/bin/bash\n# scripts/ameba-ratchet.sh\n# Only fail on new issues, not existing ones\n\n# Get baseline issue count (from main branch)\ngit fetch origin main\nBASELINE=$(git show origin/main:.ameba-baseline.json 2>/dev/null || echo '{\"count\": 0}')\nBASELINE_COUNT=$(echo \"$BASELINE\" | jq '.count')\n\n# Run Ameba and count current issues\nameba --format json > current-results.json\nCURRENT_COUNT=$(jq '.summary.issues_count' current-results.json)\n\necho \"Baseline issues: $BASELINE_COUNT\"\necho \"Current issues: $CURRENT_COUNT\"\n\nif [ \"$CURRENT_COUNT\" -gt \"$BASELINE_COUNT\" ]; then\n echo \"❌ New issues introduced ($((CURRENT_COUNT - BASELINE_COUNT)) new issues)\"\n exit 1\nfi\n\nif [ \"$CURRENT_COUNT\" -lt \"$BASELINE_COUNT\" ]; then\n echo \"✅ Issues reduced! ($((BASELINE_COUNT - CURRENT_COUNT)) fewer issues)\"\nfi\n\necho \"✅ No new issues\"","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Reporting and Monitoring","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Generate HTML Reports","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"#!/bin/bash\n# scripts/generate-report.sh\n\nameba --format json > ameba-results.json\n\n# Convert to HTML using jq and template\ncat > ameba-report.html \u003c\u003c'EOF'\n\u003c!DOCTYPE html>\n\u003chtml>\n\u003chead>\n \u003ctitle>Ameba Report\u003c/title>\n \u003cstyle>\n body { font-family: Arial, sans-serif; margin: 20px; }\n .summary { background: #f0f0f0; padding: 20px; margin-bottom: 20px; }\n .issue { border-left: 3px solid red; padding: 10px; margin: 10px 0; }\n .error { border-color: #d32f2f; }\n .warning { border-color: #f57c00; }\n .convention { border-color: #fbc02d; }\n \u003c/style>\n\u003c/head>\n\u003cbody>\n \u003ch1>Ameba Code Quality Report\u003c/h1>\n \u003cdiv class=\"summary\">\nEOF\n\njq -r '.summary | \"\n \u003ch2>Summary\u003c/h2>\n \u003cp>Total Issues: \\(.issues_count)\u003c/p>\n \u003cp>Files Analyzed: \\(.target_sources_count)\u003c/p>\n\"' ameba-results.json >> ameba-report.html\n\necho '\u003ch2>Issues\u003c/h2>' >> ameba-report.html\n\njq -r '.sources[] | select(.issues | length > 0) | .path as $path | .issues[] | \"\n \u003cdiv class=\\\"issue \\(.rule.severity | ascii_downcase)\\\">\n \u003cstrong>\\($path):\\(.location.line):\\(.location.column)\u003c/strong>\u003cbr>\n \\(.rule.name): \\(.message)\n \u003c/div>\n\"' ameba-results.json >> ameba-report.html\n\necho '\u003c/body>\u003c/html>' >> ameba-report.html\n\necho \"Report generated: ameba-report.html\"","type":"text"}]},{"type":"heading","attrs":{"level":3},"content":[{"text":"Metrics Tracking","type":"text"}]},{"type":"code_block","attrs":{"wrap":false,"language":"bash"},"content":[{"text":"#!/bin/bash\n# scripts/track-metrics.sh\n# Track Ameba metrics over time\n\nTIMESTAMP=$(date +%Y-%m-%d)\nameba --format json > \"metrics/ameba-$TIMESTAMP.json\"\n\n# Extract key metrics\njq '{\n date: \"'$TIMESTAMP'\",\n issues: .summary.issues_count,\n files: .summary.target_sources_count,\n errors: [.sources[].issues[] | select(.rule.severity == \"Error\")] | length,\n warnings: [.sources[].issues[] | select(.rule.severity == \"Warning\")] | length\n}' \"metrics/ameba-$TIMESTAMP.json\" >> metrics/history.jsonl\n\n# Generate trend chart (requires gnuplot or similar)\necho \"Metrics tracked for $TIMESTAMP\"","type":"text"}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"When to Use This Skill","type":"text"}]},{"type":"paragraph","content":[{"text":"Use the ameba-integration skill when:","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Setting up CI/CD pipelines for Crystal projects","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Implementing automated code review processes","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Establishing quality gates for deployments","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Configuring pre-commit hooks for team development","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Integrating static analysis into GitHub Actions","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Creating automated PR review workflows","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Setting up editor integrations for real-time feedback","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Implementing progressive quality improvements (ratcheting)","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Generating code quality reports for stakeholders","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Migrating from manual code review to automated checks","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Establishing coding standards enforcement","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Onboarding new team members with automated feedback","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Best Practices","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Start with CI/CD","type":"text","marks":[{"type":"strong"}]},{"text":" - Implement in CI pipeline first before local hooks","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use caching","type":"text","marks":[{"type":"strong"}]},{"text":" - Cache dependencies and Ameba results for faster builds","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Fail appropriately","type":"text","marks":[{"type":"strong"}]},{"text":" - Use ","type":"text"},{"text":"--fail-level","type":"text","marks":[{"type":"code_inline"}]},{"text":" to match pipeline requirements","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Provide feedback","type":"text","marks":[{"type":"strong"}]},{"text":" - Generate reports and comments on PRs","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Make it fast","type":"text","marks":[{"type":"strong"}]},{"text":" - Only check changed files in pre-commit hooks","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Allow bypass","type":"text","marks":[{"type":"strong"}]},{"text":" - Provide ","type":"text"},{"text":"--no-verify","type":"text","marks":[{"type":"code_inline"}]},{"text":" option for emergencies","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Progressive enforcement","type":"text","marks":[{"type":"strong"}]},{"text":" - Start permissive, increase strictness over time","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Monitor metrics","type":"text","marks":[{"type":"strong"}]},{"text":" - Track issues over time to measure improvement","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Separate concerns","type":"text","marks":[{"type":"strong"}]},{"text":" - Different rules/severity for different environments","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Document process","type":"text","marks":[{"type":"strong"}]},{"text":" - Clear instructions for team on running locally","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Use artifacts","type":"text","marks":[{"type":"strong"}]},{"text":" - Store results for later analysis and trending","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Auto-fix when possible","type":"text","marks":[{"type":"strong"}]},{"text":" - Offer automatic fixes in interactive environments","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Pin versions","type":"text","marks":[{"type":"strong"}]},{"text":" - Use specific Ameba versions in CI for consistency","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Handle failures gracefully","type":"text","marks":[{"type":"strong"}]},{"text":" - Provide helpful error messages","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Keep it maintained","type":"text","marks":[{"type":"strong"}]},{"text":" - Regularly update integrations and configurations","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Common Pitfalls","type":"text"}]},{"type":"ordered_list","attrs":{"order":1,"listStyle":"number"},"content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Blocking all commits","type":"text","marks":[{"type":"strong"}]},{"text":" - Too strict pre-commit hooks frustrate developers","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No caching","type":"text","marks":[{"type":"strong"}]},{"text":" - Slow CI builds from re-downloading dependencies every time","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Analyzing generated files","type":"text","marks":[{"type":"strong"}]},{"text":" - Wasting time on auto-generated code","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Not pinning versions","type":"text","marks":[{"type":"strong"}]},{"text":" - Different Ameba versions produce different results","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Missing changed files detection","type":"text","marks":[{"type":"strong"}]},{"text":" - Running on entire codebase in every PR","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No failure context","type":"text","marks":[{"type":"strong"}]},{"text":" - Cryptic error messages without guidance","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Inconsistent configuration","type":"text","marks":[{"type":"strong"}]},{"text":" - Different settings locally vs CI","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Long feedback loops","type":"text","marks":[{"type":"strong"}]},{"text":" - Developers find out about issues too late","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No auto-fix option","type":"text","marks":[{"type":"strong"}]},{"text":" - Manual fixes for correctable issues","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Silent failures","type":"text","marks":[{"type":"strong"}]},{"text":" - CI passes but Ameba didn't actually run","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Excessive notifications","type":"text","marks":[{"type":"strong"}]},{"text":" - Spamming team with every minor issue","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"No bypass mechanism","type":"text","marks":[{"type":"strong"}]},{"text":" - Can't commit urgent fixes when needed","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Ignoring performance","type":"text","marks":[{"type":"strong"}]},{"text":" - CI timeout from slow analysis","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Not using parallel jobs","type":"text","marks":[{"type":"strong"}]},{"text":" - Sequential execution slows down pipeline","type":"text"}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Missing test coverage","type":"text","marks":[{"type":"strong"}]},{"text":" - Not verifying integration actually works","type":"text"}]}]}]},{"type":"heading","attrs":{"level":2},"content":[{"text":"Resources","type":"text"}]},{"type":"bullet_list","content":[{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Crystal Ameba GitHub Action","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/crystal-ameba/github-action","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Ameba GitHub Repository","type":"text","marks":[{"type":"link","attrs":{"href":"https://github.com/crystal-ameba/ameba","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Pre-commit Framework","type":"text","marks":[{"type":"link","attrs":{"href":"https://pre-commit.com/","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"GitHub Actions Documentation","type":"text","marks":[{"type":"link","attrs":{"href":"https://docs.github.com/en/actions","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"GitLab CI/CD Documentation","type":"text","marks":[{"type":"link","attrs":{"href":"https://docs.gitlab.com/ee/ci/","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"CircleCI Documentation","type":"text","marks":[{"type":"link","attrs":{"href":"https://circleci.com/docs/","title":null}}]}]}]},{"type":"list_item","content":[{"type":"paragraph","content":[{"text":"Jenkins Pipeline Documentation","type":"text","marks":[{"type":"link","attrs":{"href":"https://www.jenkins.io/doc/book/pipeline/","title":null}}]}]}]}]},{"type":"hr","attrs":{"markup":"---"}}]},"metadata":{"date":"2026-06-05","name":"ameba-integration","author":"@skillopedia","source":{"stars":163,"repo_name":"han","origin_url":"https://github.com/thebushidocollective/han/blob/HEAD/plugins/validation/ameba/skills/ameba-integration/SKILL.md","repo_owner":"thebushidocollective","body_sha256":"312983bcc20c0f5e346e70c2d28c9eea2384c096d6ba0f68786121eafa0f3881","cluster_key":"9019b1018def14b7c324dd9c67250bb3a8cb0916931b318c06281c4ccd316170","clean_bundle":{"format":"clean-skill-bundle-v1","source":"thebushidocollective/han/plugins/validation/ameba/skills/ameba-integration/SKILL.md","bundle_sha256":"31bafc1146e4df957f7f945236b14b3aef1168baa3826bbfde41ccbeaeef4c6a","attachment_count":0,"text_attachments":0,"binary_attachments":0},"cluster_size":1,"skill_md_path":"plugins/validation/ameba/skills/ameba-integration/SKILL.md","import_metadata":{"date":"2026-06-05","author":"@skillopedia","version":"v1","category":"devops-infrastructure","category_label":"DevOps"},"exact_dupes_collapsed_into_this":0},"version":"v1","category":"devops-infrastructure","import_tag":"clean-skills-v1","description":"Use when integrating Ameba into development workflows including CI/CD pipelines, pre-commit hooks, GitHub Actions, and automated code review processes.","allowed-tools":["Bash","Read"],"user-invocable":false}},"renderedAt":1782987571494}

Important: agents should read /llm.txt, /llms.txt, or /.well-known/skills.json to discover the public Skillopedia API.