codacy-issues-fetcher

name	codacy-issues-fetcher
description	Retrieve and format Codacy analysis issues by running `scripts/codacy_issues.py` in the ExStruct workspace. Use when users ask to inspect repository or pull-request Codacy findings, filter by severity, or produce structured issue output for review and fix planning.

Codacy Issues Fetcher

Run scripts/codacy_issues.py as the primary interface to Codacy issue retrieval. Avoid reimplementing API calls unless the script itself must be changed.

Workflow

1. Confirm prerequisites.

• Run from repository root so scripts/codacy_issues.py is reachable.
• Ensure CODACY_API_TOKEN is set and valid.
• Prefer explicit org and repo if user provides them; otherwise rely on Git origin auto-detection.

2. Choose scope and severity.

• Repository scope: omit --pr.
• Pull request scope: pass --pr <number>.
• Severity filter (--min-level): Error, High, Warning, Info.
• Provider (--provider): gh, gl, bb (default is effectively gh).

3. Run one of the command patterns.

# Repository issues (explicit target)
python scripts/codacy_issues.py <org> <repo> --provider gh --min-level Warning

# Pull request issues (explicit target)
python scripts/codacy_issues.py <org> <repo> --pr <number> --provider gh --min-level Warning

# Pull request issues (auto-detect org/repo from git origin)
python scripts/codacy_issues.py --pr <number> --min-level Warning

4. Parse output JSON and respond with actionable summary.

• Trust payload fields: scope, organization, repository, pullRequest, minLevel, total, issues.
• issues entries are formatted as: <level> | <file_path>:<line_no> | <rule> | <category> | <message>
• Report high-severity findings first, then summarize counts.

Error Handling

• HTTP 401 / Unauthorized: token invalid or missing permissions. Ask user to set or refresh CODACY_API_TOKEN.
• CODACY_API_TOKEN is not set: export the environment variable before retrying.
• Invalid --provider: use only gh, gl, or bb.
• Segment validation errors (Invalid org/repo/pr): sanitize input and rerun.

Output Policy

• Return concise triage-ready results, not raw command logs.
• Include the exact command you used when reproducibility matters.
• If no issues match the selected --min-level, state that explicitly.