From 0272b1275c29ff861b75e73a30a5ae8e591b2457 Mon Sep 17 00:00:00 2001 From: Stefan Vacareanu Date: Wed, 29 Jul 2026 08:47:11 +0200 Subject: [PATCH 1/2] Add Agent Playbook section for automated updates --- README.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) diff --git a/README.md b/README.md index bcc1c8a..c80c74f 100644 --- a/README.md +++ b/README.md @@ -49,6 +49,69 @@ sbt "run multiple codacy-aligncheck:latest" To read more on how to build a wrapper for a tool like this one check the specification in the [Tool Developer Guide](https://github.com/codacy/codacy-engine-scala-seed/blob/master/README.md#how-to-integrate-an-external-analysis-tool-on-codacy) +## 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. Follow it top to bottom; it tells you what to change, 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 Scala wrapper (`src/main/scala/com/codacy/tools/aligncheck/*.scala`, built on `codacy-engine-scala-seed`) that packages [aligncheck](https://gitlab.com/opennota/check) — a small Go static-analysis tool that finds inefficiently packed/struct-aligned Go structs — as a Docker image Codacy's platform can run against a customer's source code. + +Unlike most Codacy engines, **aligncheck is not pinned to a specific released version**. The `Dockerfile` builds it with `go get -u gitlab.com/opennota/check/cmd/aligncheck`, which always fetches the latest commit on the upstream default branch at image-build time. There is no `aligncheckVersion` field anywhere to bump — "updating the wrapped tool" for this repo, in practice, means rebuilding the Docker image (which naturally pulls whatever is newest upstream) or bumping the Go/JRE base images. + +The `docs/` directory (`src/main/resources/docs/`) is machine-consumed configuration, but it is small and **hand-maintained, not generated** — there is no `DocGenerator` or similar source anywhere in this repo: + +- `docs/patterns.json` — the single pattern (`aligncheck`) Codacy knows about, its level/category, and whether it's enabled by default. Hand-edited. +- `docs/description/description.json` + `docs/description/aligncheck.md` — the UI title/description for that one pattern. Hand-edited. +- `docs/tool-description.md` — short blurb about the tool. Hand-edited. +- `docs/multiple-tests/{with-config,with-invalid-config,without-config}/` — fixtures (`patterns.xml`, `results.xml`, Go source samples) used by `codacy-plugins-test` to validate the engine's output against real code. + +### 2. Files that encode versions — check all of these on every update + +| File | What it controls | What to check | +|---|---|---| +| `Dockerfile` → `FROM golang:...` (builder stage) | Go toolchain used to build aligncheck itself | Bump if the Go toolchain is outdated or upstream aligncheck needs a newer Go to build. | +| `Dockerfile` → `RUN go get -u gitlab.com/opennota/check/cmd/aligncheck` | The aligncheck tool version | Nothing to "bump" here — this always fetches upstream's latest commit on rebuild. If upstream ever tags releases, consider pinning to a tag instead of `-u` on latest. | +| `Dockerfile` → `FROM amazoncorretto:...` (runtime stage) | JRE the Scala wrapper itself runs on | Bump when a newer Amazon Corretto 8 Alpine tag is available, or the wrapper needs a newer Java. | +| `build.sbt` → `codacy-engine-scala-seed` | Shared Codacy engine framework version | Bump to the latest published version when available. | +| `.circleci/config.yml` → `codacy/base` orb | Shared CircleCI steps (checkout, sbt, publish, tag) | Check the latest published version. | +| `.circleci/config.yml` → `codacy/plugins-test` orb | Runs `codacy-plugins-test` in CI | Same as above. | + +### 3. Step-by-step update procedure + +1. **Bump the version(s)** as scoped by the task (base images in `Dockerfile`, orb versions in `.circleci/config.yml`, or the seed library in `build.sbt`). +2. **There is no docs generator to re-run.** If the update changes what the tool reports (unlikely, since aligncheck has a single fixed pattern), manually update `docs/patterns.json` and `docs/description/*` and keep the `docs/multiple-tests/*` fixtures consistent. +3. **Compile, format-check, and unit-test** with `sbt "scalafmt::test; test:scalafmt::test; sbt:scalafmt::test; test"` (this mirrors the `check_format_and_test` CircleCI job). +4. **Build the Docker image**: + ```sh + sbt universal:stage + docker build -t codacy-aligncheck . + ``` +5. **Run `codacy-plugins-test` locally** before pushing — clone https://github.com/codacy/codacy-plugins-test and run, per this repo's own README: + ```sh + sbt "run json codacy-aligncheck:latest" + sbt "run pattern codacy-aligncheck:latest" + sbt "run multiple codacy-aligncheck:latest" + ``` +6. **Iterate on failures**, re-running only the relevant command after each fix. Note that because aligncheck is pulled at `latest` on every build, a locally-passing test run today is not a permanent guarantee — upstream aligncheck could change behavior on a future rebuild independent of anything in this repo. +7. **Commit** the version bump(s) in one change. +8. **Push and open a PR.** +9. **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 ` 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 + +- **Bumping the `golang` builder base image can break `go get -u`** if the new Go toolchain drops support for something upstream aligncheck relies on, or if Go module resolution behavior changes across major Go versions (this happened previously: bumping `golang:1.15.3-alpine3.12` → `golang:1.17.2-alpine3.14` required a follow-up fix to the `multiple-tests` fixtures, see commit `25efdd0`, "fix: Fix multiple tests after golang bump"). +- **CircleCI's `codacy/plugins-test` orb job (`run_multiple_tests: true`) exercises the `docs/multiple-tests/*` fixtures** — if a base image or Go version bump changes aligncheck's output formatting, these fixtures' `results.xml` will need to be regenerated/updated by hand. + +### 5. Definition of done + +- Version bump(s) reflected in the `Dockerfile` (builder and/or runtime base image) and/or `.circleci/config.yml` orbs and/or `build.sbt`, as scoped by the task. +- `docs/patterns.json`, `docs/description/*`, and `docs/multiple-tests/*` fixtures updated by hand if the change affects tool output (rare for this repo). +- `sbt` format-check and unit tests pass locally. +- Docker image builds successfully. +- `codacy-plugins-test` commands (`json`, `pattern`, `multiple`) all 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 ` and iterate on any failure until all pass. + ## Limitations This tool requires the usage of [codacy-analysis-cli](https://github.com/codacy/codacy-analysis-cli) to push the results. From b1195729842389d8565ee058aaf7dd84ba4e40c6 Mon Sep 17 00:00:00 2001 From: stefanvacareanu7 <91726880+stefanvacareanu7@users.noreply.github.com> Date: Thu, 30 Jul 2026 16:46:07 +0200 Subject: [PATCH 2/2] Update Codacy orbs to latest versions --- .circleci/config.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.circleci/config.yml b/.circleci/config.yml index f4c3dc8..0904775 100644 --- a/.circleci/config.yml +++ b/.circleci/config.yml @@ -1,8 +1,8 @@ version: 2.1 orbs: - codacy: codacy/base@5.1.2 - codacy_plugins_test: codacy/plugins-test@0.15.4 + codacy: codacy/base@13.1.1 + codacy_plugins_test: codacy/plugins-test@2.1.2 workflows: version: 2