.agents/skills/codacy-audit/SKILL.md
Drives Codacy Cloud for netdata/netdata:
git push. Collapses the "push -> wait minutes -> see findings -> fix -> push again" loop into one push.<repo>/.local/audits/codacy/.This skill is the fourth in the static-analysis triage family in this repo:
coverity-audit/, sonarqube-audit/, graphql-audit/, codacy-audit/. Same shape, same conventions, same artifact directory.
If you (the assistant) discover a new pattern, gotcha, working flow, correction, or any operational knowledge while running this skill -- update this SKILL.md AND commit it BEFORE proceeding. Knowledge that isn't committed is lost.
Examples worth capturing:
Each concrete question that requires non-trivial analysis (multiple wrapper calls, jq pipelines, cross-referencing other skills) MUST become a how-to under how-tos/<slug>.md AND get an entry in how-tos/INDEX.md BEFORE the task is reported complete. Skipping this means the next assistant repeats the analysis from scratch.
In scope:
codacy-analysis-cli (auto-detects local binary, falls back to docker).Out of scope until a real use case creates a GitHub issue or branch-local SOW:
| Key | Required for |
|---|---|
CODACY_TOKEN | Account API token, header api-token: <value>. Required by pr-issues.sh and any wrapper that calls _codacyaudit_run. NOT required by analyze-local.sh (the CLI runs anonymously). |
CODACY_HOST | Defaults to https://api.codacy.com. Override only if Codacy moves the API host. |
CODACY_PROVIDER | Defaults to gh (GitHub). |
CODACY_ORG | Defaults to netdata. |
CODACY_REPO | Defaults to netdata. |
All values live in <repo>/.env (gitignored). See <repo>/.agents/ENV.md for setup (where each value comes from, sample formats, common mistakes).
| Script | Purpose |
|---|---|
_lib.sh | Helpers (codacyaudit_* prefix). Token-safe; ships codacyaudit_selftest_no_token_leak. |
analyze-local.sh | Run codacy-analysis-cli locally; auto-pick local-binary or docker; write JSON dump under .local/audits/codacy/. |
pr-issues.sh | Fetch all Codacy issues for a PR via the v3 API; cluster summary on stdout; full JSON dump on disk. |
$ .agents/skills/codacy-audit/scripts/analyze-local.sh
[analyze-local] runner=docker format=json dir=<repo>
[analyze-local] wrote 0 finding(s) to <repo>/.local/audits/codacy/local-<ts>.json
Run this before git push. If it returns 0 findings, the Codacy gate on the PR will be green (modulo Codacy server-side patterns the local CLI doesn't bundle). If it returns findings, fix them locally first.
Operational gotcha: when the Dockerized Codacy CLI fails before a tool can emit
results, the output file may have a .json suffix but contain tool-runner logs
instead of JSON. Always verify with jq empty <dump> before treating a local
dump as finding evidence. If GitHub check-run annotations are empty too, use
pr-issues.sh with CODACY_TOKEN; without that token, record the evidence gap
and re-check after the next push.
One common local cause is gitignored generated output with restrictive file
permissions. For example, if local scratch output under .local/ contains files
not readable by the Docker container, Codacy logs Could not read file messages
and the saved .json dump is plain text. Fix or move the local generated output
before trusting local analyzer output.
Operational gotcha: the public Codacy v3 analysis endpoint can expose PR issue
details even when GitHub check-run annotations are empty and no CODACY_TOKEN
is available:
curl -fsS \
"https://api.codacy.com/api/v3/analysis/organizations/gh/netdata/repositories/netdata/pull-requests/<PR>/issues?limit=100"
Filter for .data[] | select(.deltaType == "Added") to identify the issues
that still block the PR. Treat commitInfo fields as sensitive operational
metadata; do not copy names or email addresses into committed artifacts.
Operational gotcha: Codacy's PR issue API can lag behind the GitHub check-run
after a new push. If pr-issues.sh still reports findings but the Codacy
check-run for the current head SHA is green, inspect .commitIssue.commitInfo.sha
in the dump. Findings anchored to an older commit are stale cache and should not
be treated as current-head blockers.
To restrict to a single tool (matches what Codacy reported on a CI run):
$ .agents/skills/codacy-audit/scripts/analyze-local.sh --tool markdownlint
$ .agents/skills/codacy-audit/scripts/pr-issues.sh 22423
[pr-issues] fetching issues for PR #22423 ...
[pr-issues] wrote 0 issue(s) to <repo>/.local/audits/codacy/pr-22423-<ts>.json
No issues on PR #22423.
For a PR with findings, the script emits a clustered TSV summary. Default grouping is --by pattern; switch to --by tool, --by severity, --by file, or --by category for other angles. The JSON dump under .local/audits/codacy/ carries the full issue payload for follow-up jq queries.
Operational note: large Codacy PR issue arrays must be passed to jq via a
temporary file and --slurpfile, not --argjson, because shell argument-size
limits can fail before jq starts.
This skill follows <repo>/.agents/sensitive-data-discipline.md:
<repo>/src/...).CODACY_TOKEN: NEVER literal in any committed file; ALWAYS via ${CODACY_TOKEN} and the _lib.sh wrappers.<repo>/.local/audits/codacy/..agents/skills/coverity-audit/ -- Coverity Scan (same triage shape)..agents/skills/sonarqube-audit/ -- SonarCloud (same triage shape)..agents/skills/graphql-audit/ -- GitHub Code Scanning / CodeQL (same triage shape).Before trusting wrappers in a long-running session, run the self-test:
$ source .agents/skills/codacy-audit/scripts/_lib.sh
$ codacyaudit_load_env
$ codacyaudit_selftest_no_token_leak
PASS: codacyaudit_selftest_no_token_leak
The self-test sets CODACY_TOKEN to a sentinel UUID, drives every public wrapper, captures stdout, and asserts the sentinel never appears. Run after editing _lib.sh or any wrapper.