AI-Assisted Codacy Fix Playbook¶

Practical workflow for using Claude Code (or any AI coding assistant) to fix Codacy findings in risk order — dangerous first, minimal diffs, stable tests.

Goal¶

Fix Codacy findings ranked by risk, focusing on dangerous, complex, and out-of-pattern issues while keeping CI green.

Scope¶

Source: Codacy issues
Output: ranked fix queue → batched patches → targeted regression checks → changelog
Constraint: verify every finding against current code before changing anything

Accessing Codacy Issues¶

Browser-like user agent required for both HTML and API:

UA="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36"

# HTML dashboard
curl -sS -L -A "$UA" \
  "https://app.codacy.com/gh/YaoYinYing/REvoDesign/issues/current" \
  -o /tmp/codacy_issues.html

For automation, use the Codacy v3 API with cursor pagination:

UA="Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36"
out=/tmp/codacy_issues_all.ndjson
: > "$out"
cursor=""
while :; do
  if [ -n "$cursor" ]; then
    url="https://app.codacy.com/api/v3/analysis/organizations/gh/YaoYinYing/repositories/REvoDesign/issues/search?limit=100&cursor=$cursor"
  else
    url="https://app.codacy.com/api/v3/analysis/organizations/gh/YaoYinYing/repositories/REvoDesign/issues/search?limit=100"
  fi
  curl -sS -L -A "$UA" -H "content-type: application/json" "$url" --data-binary '{}' -o /tmp/codacy_page.json || exit 1
  jq -c '.data[]' /tmp/codacy_page.json >> "$out"
  next=$(jq -r '.pagination.cursor // empty' /tmp/codacy_page.json)
  [ -z "$next" ] && break
  [ "$next" = "$cursor" ] && break
  cursor="$next"
done
jq -s '{data: ., total: length}' "$out" > /tmp/codacy_issues_all.json

Payload Fields for Ranking¶

Field	Purpose
`issueId`	Unique identifier
`filePath`	Affected source file
`lineNumber`	Line anchor
`message`	Human-readable description
`patternInfo.id`	Rule identifier
`patternInfo.category`	`Security`, `ErrorProne`, `BestPractice`, `Complexity`, `CodeStyle`, `UnusedCode`
`patternInfo.severityLevel`	`High`, `Warning`, `Info`
`toolInfo.name`	Tool that raised it (e.g., `Prospector`, `Lizard`, `ShellCheck`)
`commitInfo.sha`	Commit where the finding was introduced

Classification Model¶

Classify each issue on three axes:

1) Danger¶

Level	Meaning
D0 Critical	Security or destructive behavior (command injection, credential leakage, unsafe path traversal)
D1 High	Runtime failures, invalid API behavior, concurrency hazards
D2 Medium	Reliability/perf issues, likely wrong edge-case behavior
D3 Low	Style/maintainability only

2) Complexity¶

Level	Meaning
C0	Single-file local fix
C1	2–3 file flow changes
C2	Cross-module/runtime interactions (Docker, auth, async worker)
C3	Architecture-level shifts

3) Out-of-Pattern¶

Flag if code conflicts with project conventions:

Auth flow differs from server-wide behavior
Path handling bypasses safety helpers
Shell invocation bypasses existing hardened patterns
Docker/env wiring uses inconsistent variable names

Priority Scoring¶

Deterministic scoring to build the fix queue:

Factor	Points
Severity: `High`	+5
Severity: `Warning`	+3
Severity: `Info`	+1
Category: `Security`	+5
Category: `ErrorProne`	+4
Category: `BestPractice`	+2
Category: `Complexity`	+2
Category: `UnusedCode`	+1
Category: `CodeStyle`	+0
Externally exposed (HTTP/API/Docker)	+3
CI-flaky or test-blocking	+2
Out-of-pattern	+2

Sort descending, then batch by root cause family.

Batch Strategy¶

Keep batches small and cohesive (5–12 issues):

Shell/script safety and command execution
Server auth/session/logout behavior
File/path/delete safety
Docker/env consistency
Frontend API contract consistency
Test harness determinism and CI parity

Fix Workflow (Repeatable)¶

Fetch and snapshot Codacy issues
Deduplicate by root cause and file/line family
Verify each finding against current code — skip stale/false positives
Implement minimal fix
Add targeted tests for behavior and regression
Run make clean before test validation
Run make kw-test PYTEST_KW='<keyword>' — focused first, then broader
Update CHANGELOG.md
Record residual risk and follow-ups

Verification Commands¶

make clean
conda run -n REvoDesignTestFlight make kw-test PYTEST_KW='single keywords'
conda run -n REvoDesignTestFlight make kw-test PYTEST_KW='"keywordA or keywordB"'

For server/Docker/auth changes, include integration keywords from tests/server/test_pssm_gremlin.py where applicable.

High-Value Fix Patterns¶

Convert unsafe eval or fragile pipeline composition to explicit argument-safe execution
Guard deletion by strict base-path validation before filesystem removal
Align Docker/env variable names across compose, runtime, and scripts
Replace brittle browser-auth logout loops with deterministic server/client handoff
Avoid root-like defaults; require explicit non-root identity in runner/server paths
Preserve distinctions in API return values ([] vs None) where semantics matter
Escape user/version strings before regex-oriented shell tools (e.g., sed)

CI Drift Handling¶

If local tests pass but GitHub Actions fail:

Reproduce with nearest keyword subset
Inspect startup/readiness paths first (auth, networking, container health)
Improve diagnostics in failing harness code
Stabilize readiness checks with explicit liveness + authenticated probes
Re-run focused keywords before broader reruns

Tracking Template¶

Use this table in PR bodies:

Codacy ID	Rule	Danger	Complexity	Out-of-Pattern	Files	Fix	Validation
...	`patternInfo.id`	D1	C1	yes/no	`path`	one-line	`kw-test ...`

Anti-Patterns¶

Blindly fixing by tool severity without runtime verification
Large mixed-risk diffs across unrelated subsystems
Editing tests to match broken behavior
Skipping changelog/docs for behavior-impacting fixes
Claiming CI parity without reproducing representative keywords

Definition of Done¶

A batch is done only when all are true:

Every selected finding is fixed or explicitly deferred with reason
Targeted tests pass from clean workspace (make clean first)
No new auth/runtime regressions
CHANGELOG.md updated
Notes are sufficient for a follow-up reviewer to audit quickly

Quick Snapshot Commands¶

jq '.total' /tmp/codacy_issues_all.json
jq -r '.data[].patternInfo.category' /tmp/codacy_issues_all.json | sort | uniq -c | sort -nr
jq -r '.data[].patternInfo.severityLevel' /tmp/codacy_issues_all.json | sort | uniq -c | sort -nr
jq -r '.data[] | [.issueId,.patternInfo.id,.patternInfo.category,.patternInfo.severityLevel,.filePath,.lineNumber] | @tsv' \
  /tmp/codacy_issues_all.json > /tmp/codacy_issues_flat.tsv