Codacy Ameba

CircleCI Codacy Badge Docker Image Version

Tooling & Docker Definition for running Ameba on Codacy

Implements the Tool Developer Guide

Usage

Build the docker image

docker build -t codacy-ameba .

Run on a project

docker run --rm -v $srcDir:/src codacy-ameba

Regenerate docs folder:

shards install
crystal src/generate.cr

Testing

Run regular unit tests: crystal spec

Run Codacy Plugin Tests against the docker image:

docker build -t codacy-ameba .

codacy-plugins-test pattern codacy-ameba
codacy-plugins-test json codacy-ameba
codacy-plugins-test multiple codacy-ameba

Agent Playbook: Updating This Repository End-to-End

This section is written for an AI coding agent (or a human) tasked with updating this repo — most commonly bumping the wrapped Ameba version, but also Crystal runtime / base image / orb bumps. Follow it top to bottom; it tells you what to change, how to regenerate derived files, how to test locally, and how to interpret CI so you can iterate on failures without guessing.

1. What this repository is

This is a Codacy engine: a thin Crystal wrapper (src/codacy-ameba.cr, src/codacy-ameba/*.cr — config parsing, running, and formatting) that packages Ameba, a static code analyzer for Crystal, as a Docker image Codacy's platform can run against a customer's source code. Ameba is pulled in as a normal Crystal shard dependency (source, not a prebuilt binary), so its rules are available directly to the wrapper at compile/run time. The docs/ directory is not just documentation — it is machine-consumed configuration:

All three generated artifacts above come from src/generate.cr, which calls Codacy::Ameba.generate (defined using src/codacy-ameba/generate/markdown.cr, patterns_json.cr, description_json.cr, and defaults.cr). This generator loads ::Ameba::Config.load.rules directly from the Ameba shard that is installed via shards install — it does not clone or scrape an external repo, so no network access beyond shards install is needed to regenerate docs, but the Ameba version installed by shards.yml/shard.lock must already be the target version before you run it.

2. Files that encode versions — check all of these on every update

| File | What it controls | What to check | |---|---|---| | shard.yml → dependencies.ameba.version | Which Ameba release is bundled | Bump to the target Ameba version/tag. | | shard.lock → shards.ameba.version | Locked resolved Ameba version | Regenerated by shards install/shards update ameba, but verify it matches shard.yml. | | shard.yml → crystal: | Minimum Crystal compiler version this shard targets | Bump if the new Ameba version requires a newer Crystal. | | Dockerfile → FROM crystallang/crystal:<version>-alpine (builder stage) | Crystal toolchain used to build the binary | Keep in sync with shard.yml's crystal: line. | | Dockerfile → FROM alpine:<version> (runtime stage) | Runtime OS the packaged binary runs on | Bump only if required by the new Crystal/Ameba version. | | .circleci/config.yml → codacy/base orb | Shared CircleCI steps (checkout, versioning, publish) | Check the latest published version. | | .circleci/config.yml → codacy/plugins-test orb | Runs codacy-plugins-test in CI | Check the latest published version. | | .circleci/config.yml → unit_test job's docker: image: crystallang/crystal:<version> | Crystal image used to run crystal spec in CI | Keep in sync with the Dockerfile builder stage. |

3. Step-by-step update procedure

  1. Bump the version(s) as scoped by the task (shard.yml, and Dockerfile/CircleCI image tags if the Crystal version also needs to move).
  2. Install dependencies with shards install (this updates shard.lock to match shard.yml).
  3. Regenerate the docs: crystal src/generate.cr. Review the diff in docs/patterns.json and docs/description/* for new/removed/renamed rules — Ameba upgrades have historically renamed rule categories (e.g. Style_TypeNames.md → Naming_TypeNames.md), which also requires removing/updating the now-stale files under docs/tests/ that reference removed or renamed rules.
  4. Run the unit test suite: crystal spec.
  5. Build the Docker image: docker build -t codacy-ameba ..
  6. Run codacy-plugins-test locally before pushing — against the freshly built image: 
    codacy-plugins-test pattern codacy-ameba
codacy-plugins-test json codacy-ameba
codacy-plugins-test multiple codacy-ameba
  7. Iterate on failures, re-running only the relevant test command after each fix.
  8. Commit the version bump(s) together with any regenerated docs/ files in one change.
  9. Push and open a PR.
  10. Poll the PR's real CI checks until they all pass — local validation is NOT the finish line. After every push, run gh pr checks <pr-url> and keep re-polling (short sleep while any check is pending) until all checks finish. If a check fails, fetch its actual log (don't guess), find the true root cause, fix it, push again (never --no-verify, never force-push), and re-poll. Repeat until every check is green. The CI environment's toolchain can differ from your local one, so a clean local run does not guarantee CI passes. Only stop iterating when every check passes, or you hit a genuine product/infra decision that needs a human.

4. Common failure modes and fixes

| Symptom | Likely cause | Fix | |---|---|---| | docs/tests/*.cr fixture no longer triggers any pattern, or codacy-plugins-test pattern/multiple fails after a version bump | Ameba renamed, split, or removed a rule between versions | Regenerate docs (step 3), diff docs/patterns.json for the rule's new name/category, update or delete the corresponding fixture and description file. | | crystal spec or shards build fails after bumping shard.yml's ameba: version | The new Crystal minimum required by Ameba is higher than the one currently pinned | Bump crystal: in shard.yml and the crystallang/crystal image tags in Dockerfile and .circleci/config.yml together. |

5. Definition of done

What is Codacy

Codacy is an Automated Code Review Tool that monitors your technical debt, helps you improve your code quality, teaches best practices to your developers, and helps you save time in Code Reviews.

Among Codacy’s features

Codacy also helps keep track of Code Coverage, Code Duplication, and Code Complexity.

Codacy supports PHP, Python, Ruby, Java, JavaScript, and Scala, among others.

Contributing

  1. Fork it (https://github.com/codacy/codacy-ameba/fork)
  2. Create your feature branch (git checkout -b my-new-feature)
  3. Commit your changes (git commit -am 'Add some feature')
  4. Push to the branch (git push origin my-new-feature)
  5. Create a new Pull Request

Contributors