Codacy Ruff

Co-authored by @valeriupredoi

This is the docker engine we use at Codacy to have Ruff support. You can also create a docker to integrate the tool and language of your choice! See the codacy-engine-scala-seed repository for more information.

Python compatibility

Ruff is compatible with Python 3.13

Usage

You can create the docker by doing:

docker build --no-cache -t codacy-ruff:latest .

The docker is ran with the following command:

docker run -it -v $srcDir:/src codacy-ruff:latest

Generate Docs

1. Update the version in requirements.txt

2. Run the DocGenerator to update all the patterns/descriptions and the patterns.xml (from all-patterns test)

   python<version> src/doc_generator.py

Test

We use the codacy-plugins-test to test our external tools integration. You can follow the instructions there to make sure your tool is working as expected.

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 Ruff version, but also 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 small Python wrapper (src/codacy_ruff.py) that packages Ruff — the Python linter/formatter — as a Docker image that Codacy's platform runs against a customer's source code. There is no sbt/Java tooling here; it's plain Python installed via pip inside an Alpine-based Docker image (see Dockerfile).

Like the Checkstyle/Java engines, this repo does use the rule-based Codacy "pattern" engine structure:

• docs/patterns.json — the full list of Ruff rules ("patterns") Codacy knows about, their category/severity, and which are enabled by default (see the enabled_rules allow-list in src/doc_generator.py). Generated file, do not hand-edit.
• docs/description/description.json + docs/description/*.md — human-readable titles/descriptions per pattern, used in the Codacy UI. Generated file, do not hand-edit.
• docs/multiple-tests/* — fixtures (all-patterns, with-config-file) used by codacy-plugins-test's multiple-tests mode to validate the engine actually produces the results it claims to on real code samples. all-patterns/patterns.xml is also regenerated by the doc generator.
• docs/tool-description.md — short blurb about the tool, hand-maintained.

Both generated JSON files above (plus the per-pattern markdown and all-patterns/patterns.xml) come from src/doc_generator.py. Unlike the Scala/Checkstyle generator, this one does not clone a git repo — it scrapes Ruff's live documentation site (https://docs.astral.sh/ruff/rules/) over HTTP with requests + BeautifulSoup, reading the version to stamp into patterns.json straight out of requirements.txt. This means the generator needs network access and the Python deps in requirements.txt installed, but no external git clone or pandoc.

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

File	What it controls	What to check
requirements.txt → ruff==<version>	Which Ruff release is bundled, packaged into the Docker image, and read by doc_generator.py to stamp docs/patterns.json's "version" field	Bump to the target version. This is the single source of truth for the Ruff version.
Dockerfile → FROM python:3.13-alpine3.XX	Base Python/Alpine image the engine runs on	Historically bumped alongside Ruff version bumps (Alpine point-release bumps), even though not strictly tied to Ruff. Check for a newer Alpine tag when bumping Ruff, and bump the Python minor version only if Ruff explicitly requires it.
.circleci/config.yml → codacy/base orb	Shared CircleCI steps (checkout, versioning, docker build/publish, tagging)	Check the latest published codacy/base orb version; historically bumped in the same commit as a Ruff version bump.
.circleci/config.yml → codacy/plugins-test orb	Runs codacy-plugins-test in CI after the image is built	Bump only if asked or if the plugins-test orb has a relevant fix; not bumped in the two most recent Ruff bumps inspected.
requirements.txt → jsonpickle, numpy, pytest, toml	Auxiliary Python deps used by the engine wrapper / test fixtures (e.g. NumPy-specific NPY rules need numpy installed so Ruff can resolve imports in fixtures)	Only bump if asked, or if pip install flags an incompatibility with the new Ruff version.

Look at recent bump commits for the shape of a typical diff: git log --oneline --all | grep -i bump, then git show <hash>. The two most recent examples (TCE-1367 Bump Ruff 0.12.7, TCE-1307 Bump Ruff 0.12.5) touch requirements.txt, Dockerfile (Alpine tag), .circleci/config.yml (codacy/base orb version), and the regenerated docs/patterns.json + affected docs/description/*.md files together. The 0.12.5 bump additionally touched docs/multiple-tests/all-patterns/patterns.xml and src/doc_generator.py itself (the enabled_rules/category maps needed updating for new rule codes) — expect this whenever Ruff adds/removes/renames rules between versions.

3. Step-by-step update procedure

1. Bump the version in requirements.txt (ruff==<new-version>). Bump .circleci/config.yml orbs and the Dockerfile base image tag only as scoped by the task (see table above).
2. Install deps locally: pip install -r requirements.txt.
3. Regenerate the docs. Requires network access (it scrapes https://docs.astral.sh/ruff/rules/ live):

   python src/doc_generator.py

   This rewrites docs/patterns.json, docs/description/description.json, docs/description/*.md, and docs/multiple-tests/all-patterns/patterns.xml. Review the diff carefully for:
   • New rule codes not yet present in the severity_mapping / category_mapping dicts at the top of src/doc_generator.py (they'll silently default to "Info" severity / "BestPractice" category if missing — add them explicitly if the new Ruff version introduces a new rule prefix).
   • Rules removed upstream (the generator already skips rules marked "removed" or "in preview" on the docs site, and prunes stale docs/description/*.md files whose pattern id is no longer active).
   • Whether any rule you rely on in enabled_rules was renamed (the pattern id includes the rule name, e.g. S310_suspicious-url-open-usage).
4. Build the Docker image (same as CI): docker build -t codacy-ruff:latest .
5. Sanity-check the image runs: docker run -it -v $srcDir:/src codacy-ruff:latest against a small sample directory.
6. Run codacy-plugins-test locally before pushing — clone https://github.com/codacy/codacy-plugins-test and run it against your local image tag. CI only runs the multiple-tests mode here (run_multiple_tests: true, run_json_tests: false, run_pattern_tests: false in .circleci/config.yml), so at minimum validate docs/multiple-tests/all-patterns and docs/multiple-tests/with-config-file produce the expected results.xml.
7. Iterate on failures, re-running the relevant test fixture after each fix.
8. Commit the version bump(s) together with the regenerated docs/ files (and any src/doc_generator.py mapping updates) in one change.
9. Push and open a PR. CI (.circleci/config.yml) runs codacy/checkout_and_version -> publish_docker_local (builds and saves the Docker image) -> plugins_test (multiple-tests only) -> codacy/publish_docker (master only) -> tag_version.
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 (the CircleCI job 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 doc-generator scrapes a live external site, so a transient network/HTML-structure failure there is a real possible cause of CI failure, not just code bugs — investigate the actual log before assuming it's your code. Only stop iterating when every check passes, or you hit a genuine product/infra decision that needs a human — in which case explain it in the PR rather than guessing.

4. Common failure modes and fixes

Symptom	Likely cause	Fix
A rule shows up with severity Info / category BestPractice unexpectedly after regenerating	New rule prefix not present in severity_mapping / category_mapping in src/doc_generator.py	Add the correct mapping entry for the new prefix and re-run the generator
multiple plugins-test fixture fails after a bump	Rule renamed/removed/added upstream, or an enabled_rules entry no longer matches the regenerated pattern id	Re-run src/doc_generator.py; update enabled_rules and the fixture expectations (docs/multiple-tests/*/results.xml) to match verified-correct new output
doc_generator.py produces near-empty output or many "Failed to fetch" lines	Astral's docs site changed its HTML structure, or a network/timeout issue during scraping	Re-run once network is confirmed; if the site structure changed, update the scraping logic (fetch_pattern_description/extract_relevant_lines) in src/doc_generator.py
pip install -r requirements.txt fails on the new Ruff version	Ruff dropped support for the Python version in Dockerfile, or a pinned dependency conflicts	Check Ruff's release notes for minimum Python version; bump Dockerfile's Python tag only if required

5. Definition of done

• Ruff version bumped in requirements.txt, with .circleci/config.yml orbs and Dockerfile base image bumped only as scoped.
• docs/patterns.json, docs/description/*, and docs/multiple-tests/all-patterns/patterns.xml regenerated via src/doc_generator.py, with any new rule prefixes added to the mapping dicts and any renamed/removed rules reconciled against enabled_rules and test fixtures.
• Docker image builds successfully (docker build -t codacy-ruff:latest .).
• codacy-plugins-test multiple-tests pass locally against the freshly built image.
• After pushing and opening/updating the PR, every CI check on it is green. Poll gh pr checks <pr-url> and iterate on any failure (fetch the real CI log, fix, push, re-poll) until all pass — a passing local build is not sufficient, because CI depends on a live external scrape and its own container environment, both of which can differ from local runs (see step 10).

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:

• Identify new Static Analysis issues
• Commit and Pull Request Analysis with GitHub, BitBucket/Stash, GitLab (and also direct git repositories)
• Auto-comments on Commits and Pull Requests
• Integrations with Slack, HipChat, Jira, YouTrack
• Track issues in Code Style, Security, Error Proneness, Performance, Unused Code and other categories

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

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

Free for Open Source

Codacy is free for Open Source projects.