Codexqa Code Reviewer

AI Code Reviewer

Graph-first code review via CodexQA CLI only. Collect a JSON evidence pack, then reason from those artifacts. Applies to every language / polyglot monorepo.

CLI: {baseDir}/scripts/collect-pr-evidence.sh (and full-repo / adhoc variants). Runtime pack: /.codexqa-review// → review-conclusion.json + REVIEW-REPORT.html.

Install: Prefer npx skills add openqa-cn/codexqa --skill codexqa-code-reviewer. Do not copy into a skills library manually until the user names the install target.

README.md / README.zh-CN.md / HOW_IT_WORKS.md / KNOWN_LIMITATIONS.md (and their .zh-CN twins) are human-facing. Do not load them at runtime.

Boundaries

| Need | Skill | |---|---| | Graph-evidence pack → bilingual HTML CR (REVIEW-REPORT.html) | this skill (codexqa-code-reviewer) | | SAST + Agent LLM Detection → report_scan.* | codexqa-defect-analyzer | | Symbol-graph change impact, callers, test gaps | codexqa-code-analyzer | | Exception RCA from stacks/logs on top of CLI analysis | codexqa-rootcause-analyzer |

Prerequisites

| Dependency | Why | |---|---| | codexqa (Node ≥ 18) | Sole primary analysis backend. Resolve it with the Preflight gate below, not with command -v on the default PATH. npm i -g @openqa-cn/codexqa only when that probe prints nothing. | | jq | Evidence JSON / HTML render | | bash 3.2+ | Collect / validate / render scripts (macOS OK) | | Python 3.10+ (scripts/acr-python) | Local derive-* helpers / validate-skill gate | | Semgrep, Bandit, gosec, gitleaks, osv-scanner, ruff, eslint | Deterministic SAST. If any binary is missing, install it before collect (scripts/lib/install-sast-tools.sh) |

Local skill gate (Eval substitute when skill-up is missing):

./scripts/validate-skill.sh

Preflight gate

Run this once in the current shell before any later step. Collect, SAST install, index, validate, review, merge, and render stay blocked until codexqa_cli_path has actually executed here and its stdout is known. Intending to preflight later does not open those steps. A second probe is needed only after an install that can change PATH.

A bare command -v codexqa or which codexqa is not this gate. The CLI is an npm global. Its bin directory comes from prefix in ~/.npmrc, $npm_config_prefix, and npm prefix -g, and that directory is often missing from the default PATH. A failed lookup means this shell has not been probed, not that the CLI is absent. Installing from that failure reinstalls a CLI that is already there.

source scripts/lib/codexqa-preflight.sh
codexqa_cli_path
command -v jq >/dev/null
codexqa --version

Keep source and codexqa_cli_path in this shell. $(codexqa_cli_path) drops the PATH update. Do not hardcode the prefix.

• Printed path: the CLI is installed. Do not run npm i -g. Record the path and the version. If the user asked for the latest release, compare that version with npm view @openqa-cn/codexqa version only after this probe, and upgrade only when they differ. Source the preflight again after an upgrade.
• Empty stdout: the CLI is absent. Only then npm i -g @openqa-cn/codexqa (Node ≥ 18). Source the preflight again. If codexqa_cli_path is still empty, stop with missing_gate: missing_codexqa_engine.
• jq missing stops the same way. Do not switch the engine to grep or a language-native SAST.

Quick start

Task progress:
- [ ] 1. Preflight gate in this shell (source + codexqa_cli_path). Steps 1b–6 stay blocked until this has run once.
- [ ] 1b. Install every missing SAST tool (mandatory — do not scan with status=missing)
- [ ] 2. Collect evidence pack → OUT_DIR
- [ ] 3. Validate (auto unless --skip-validate)
- [ ] 4. Lock primary_language / review_language_focus
- [ ] 5. Review from `29-judgment-packet.json` only (do not reopen `01`–`28`, diffs, or git)
- [ ] 5b. Agent LLM judgment pass + dedupe merge (`merge-llm-findings.py`)
- [ ] 6. Write findings in review-conclusion.json + render (`seal-conclusion.py` fills the skeleton)

# Step 1 — required before every command below. See Preflight gate.
source scripts/lib/codexqa-preflight.sh
codexqa_cli_path

# Step 1b — only after codexqa_cli_path has printed a path.
# Mandatory when any of semgrep / bandit / gosec / gitleaks / osv-scanner / ruff / eslint is missing.
./scripts/lib/install-sast-tools.sh

# PR / diff (default). derive-sast.sh runs the installer again before the scan.
./scripts/collect-pr-evidence.sh --repo /path/to/repo --diff-base origin/main

# Full-repo (optional)
./scripts/collect-fullrepo-evidence.sh --repo /path/to/repo

# Adhoc / single-file (no PR diff-base)
./scripts/collect-adhoc-evidence.sh --file /path/to/Foo.java

# After review reasoning:
./scripts/render-review-html.sh --dir 

Default OUT_DIR: /.codexqa-review// with runtime manifest.json (+ 09-language-profile.json). templates/evidence-manifest.json is schema-only — never written by collectors.

Hard constraints (CodexQA mandate)

1. CLI only — call codexqa after the Preflight gate, which builds PATH. Never vendor / unzip / import @openqa-cn/codexqa. A default-PATH miss is not a missing CLI.
2. Evidence files first — the CodexQA evidence pack is a hard prerequisite (前置必要条件).

Impact, callers, entries, coverage must cite artifact fields.

1. No invented graph — missing facts → confidence: UNKNOWN. Never fake green from test/ paths.
2. PR gates — need code identity (REPO) + reviewable change (--diff-base). Else status: blocked.
3. Human merge decision — actionable review only; never auto-approve.
4. No alternate primary backend — forbid git-diff-only, grep-only “call graph”, or language SAST

(SpotBugs/ESLint/mypy/…) as the sole engine. derive-sast.sh may run Semgrep, Bandit, gosec, gitleaks, osv-scanner, ruff, and eslint as a secondary deterministic pass (23-sast-signals.json). Missing/invalid pack → missing_gate: missing_codexqa_engine (or specific gate).

1. Primary language gate — read 09-language-profile.json / manifest.primary_language /

review_language_focus before findings; apply [references/review-dimensions.md](references/review-dimensions.md) ([references/language-profile.md](references/language-profile.md)). Override with --primary-lang only when detection is wrong. Label uncertainty for reflection / dynamic dispatch / cross-language FFI — do not leave CodexQA.

Modes

| Mode | When | Script | |---|---|---| | PR/diff (default) | Branch/PR vs base | scripts/collect-pr-evidence.sh | | Full-repo (optional) | Health / architecture / hotspots | scripts/collect-fullrepo-evidence.sh | | Adhoc (single-file) | Upload one/few files without PR | scripts/collect-adhoc-evidence.sh |

Full-repo deliverables: hotspot modules (ranked by edges-in, not from_count), layering drift (入口 → 应用 → 领域 → 存储), entry concentration, hardening backlog P0/P1/P2. Never invent PR change_status. No product scorecard / 产品评测打分.

Adhoc: bootstraps a mini git repo when --repo is omitted so CodexQA index gates pass; validate with --mode adhoc.

Capability → pack map

| Capability | Pack evidence | |---|---| | Change localization | 03-change-groups / 05-changed-symbols / diffs/*.diff.json | | PR review digest | 26-review-digest.json (commits behind/ahead, three-dot file classes vs two-dot drift, deduped disposition: report lines). Superseded by 29-judgment-packet.json when that file exists. | | Judgment packet | 29-judgment-packet.json (the only file the judgment pass opens: dimension cards, prdelta report rows, suspect slices, one inlined copy of each read group). 30-conclusion-skeleton.json is sealed into the conclusion at render. | | Design fit | 10-design-fit-signals.json (path + package/import layers, import_cross_layer, dead_nested_symbols confirmed via empty edges-in; full: imports/ + on-disk fallback) | | Complexity | 11-complexity-signals.json (method LOC / decisions / nesting / YAGNI hints) | | Dependencies | 12-dependency-signals.json (manifest/lock SNAPSHOT, lock drift, license clues, local audit) | | Privacy | 13-privacy-signals.json (PII fields, log exposure, retention gaps, consent/transfer clues) | | Resilience | 14-resilience-signals.json (timeout, retry, swallow, partial fail, idempotency/compensation) — signal hits → findings hard gate | | Change / rollout | 15-rollout-signals.json (migration, dual-write, flags, compat window, breaking announce, rollback) | | Observability | 16-observability-signals.json (catch without log/metric/trace) | | Contract | 17-contract-signals.json (breaking hints, XSS/HTML sinks, public-sig volume) | | Maintainability | 18-maintainability-signals.json (TODO/FIXME, magic numbers, long files) | | Performance | 21-performance-signals.json (hot path, N+1, unbounded allocation) | | Agent LLM judgment | 22-llm-judgment.json (host-agent semantic CR + dedupe merge vs heuristic findings) | | Deterministic SAST | 23-sast-signals.json (per hit disposition: report / drop / suspect; class policy allow / suppressobvious / dedupe_loci) | | Annotation callbacks | 19-annotation-edges.json (Spring/Resilience4j synthetic callers when edges-in empty) | | Risk tier (blast-radius triage) | 20-risk-tier.json (T0–T3 from paths + tags + sensitive + rollout surfaces; auth/pay/migration/IaC → T0) | | Blast radius | impact/*/edges-in.json / reach-in.json (PR + full-repo top hotspots) | | Entry / flow | 07-tags.json + impact/*/paths/ | | Test gaps | tested_count + tests-reach.json (not test directory / test path names) | | Sensitive paths | 06-sensitive-hits.json + callers | | Hot-but-thin | 08-hot-but-thin.json | | Full-repo architecture | stats / summary / imports/ + Design fit signals | | Primary language | 09-language-profile.json + manifest stamps |

Workflow detail

1. Preflight

This step is the Preflight gate. In a shell where codexqa_cli_path has not yet been executed, stop. Do not start 1b, collect, index, or review from a command -v miss.

source scripts/lib/codexqa-preflight.sh
codexqa_cli_path
command -v jq >/dev/null
codexqa --version

SAST install is step 1b and starts only after that probe has printed a path (or an install from empty stdout has been probed again):

./scripts/lib/install-sast-tools.sh

Per-tool commands (the installer runs these only when that binary is missing):

| Tool | Install command | |---|---| | semgrep | python3 -m pip install --user --break-system-packages 'semgrep>=1.80' | | bandit | python3 -m pip install --user --break-system-packages bandit | | ruff | python3 -m pip install --user --break-system-packages ruff | | eslint | npm install -g eslint | | gitleaks | go install github.com/gitleaks/gitleaks/v8@latest | | gosec | go install github.com/securego/gosec/v2/cmd/gosec@latest | | osv-scanner | go install github.com/google/osv-scanner/cmd/osv-scanner@latest |

codexqa-preflight.sh, install-sast-tools.sh, and derive-sast.sh all source scripts/lib/sast-tool-path.sh and call sast_refresh_path. That is the only PATH policy. It prepends a directory when the directory contains the CodexQA CLI, a SAST binary, or the runtime that installs it. Do not hardcode install prefixes. codexqa_cli_path prints the resolved CLI. npm bins (codexqa, eslint) come from the prefix in ~/.npmrc, $npm_config_prefix, and npm prefix -g (/bin on Unix; the prefix directory itself on Windows, where the file is eslint.cmd). pip bins (semgrep, bandit, ruff) come from each Python's sysconfig scripts path (bin on Unix, Scripts on Windows). Go bins (gitleaks, gosec, osv-scanner) come from $GOBIN, $GOPATH, and go env (Windows lists split on ;); if go is not on PATH it is found with brew --prefix, asdf where, or a depth-capped search for go or go.exe, then go env supplies the bin dir. Lookup also accepts .exe, .cmd, and .bat. Node shims come from $NVM_DIR, $VOLTA_HOME, $FNM_DIR, and $ASDF_DATA_DIR. A gitleaks / gosec / osv-scanner file that fails --version is moved aside so a truncated download is not treated as installed. The GitHub release download runs only when no go binary runs, or go install still leaves that tool missing. Do not set CODEXQA_SAST_SKIP_INSTALL=1 on a real review.

PR: REPO + DIFF_BASE. Full-repo: REPO only. Prefer absolute repo paths.

2. Collect

Blocked until the Preflight gate has run once in this shell. Shared helpers: scripts/lib/codexqa-preflight.sh. Options: --full, --primary-lang , --skip-index, --skip-validate, --out DIR. PR collect writes 26-review-digest.json after the signal files. Judgment reads that digest for commits behind/ahead, file-class counts, report rows, and dimension cards. Full path lists stay in 26-review-digest-detail.json. Do not recompute the split with git or open every signal file for the dimension verdict. Residual reading opens each 24-coverage-ledger.json read_groups entry once and still writes one closure row per pending symbol. Non-source files are not residual symbols. Byte-identical copies are scanned once; findings keep every path. Files whose bytes differ are both scanned.

3. Validate

./scripts/validate-evidence.sh --dir  --mode pr   # or --mode full

Fails: missing CodexQA provenance; empty change-groups; all change_status=default; lang_stats present but primary_language null. Legacy packs may WARN and still pass.

stubs≥20 (numeric or {total:N}) → cap edge/reach findings at UNKNOWN; do not treat from_count as real fan-in — prefer edges-in callers.

4. Review from artifacts

1. Read [prompts/pr-diff-review.md](prompts/pr-diff-review.md) or

[prompts/full-repo-review.md](prompts/full-repo-review.md).

1. Confirm manifest.engine is codexqa (or legacy codexqa in commands). Else blocked.
2. Lock language from manifest.json + 09-language-profile.json.
3. For top risks: diffs/, impact//, paths/, then tags / hot-but-thin / sensitive.
4. Mermaid from [references/mermaid-evidence.md](references/mermaid-evidence.md).
5. Detection rules live on the owner dimension card (index:

[references/dimension-registry.md](references/dimension-registry.md)). Build and extend them only with [references/rule-construction.md](references/rule-construction.md): a rule is a relation plus role-shaped variants, one hit does not close the family, and a hard-gate row is a visible finding. Pattern-class defects with disposition: report are filed from 23-sast-signals.json. drop is discarded. Only suspects[] go to the SAST suspect channel. allow records a scanner gap and does not rescan that class. CodexQA stays the primary engine.

1. Agent LLM judgment (order 16): follow [prompts/llm-judgment-pass.md](prompts/llm-judgment-pass.md).

SAST suspects, business logic, and semantic candidates are separate prompts. The residual read visits every pending symbol in 24-coverage-ledger.json; scanner hits do not dequeue it. The host embedded model reviews those packets, then scripts/lib/merge-llm-findings.py dedupes p0/p1/p2 against heuristic findings (22-llm-judgment.json).

5. Deliver

1. Optional chat notes: [templates/review-report.md](templates/review-report.md)
2. Required: /review-conclusion.json from

[templates/review-conclusion.json](templates/review-conclusion.json)

1. Required: ./scripts/render-review-html.sh --dir → REVIEW-REPORT.html

Render runs scripts/lib/validate-conclusion.py first and refuses the HTML when any gate fails:

• Every disposition: report row's line is on some finding. A sentence that

says another card covers a defect must name a line that a finding lists.

• Each test_oracle_inventory row has oracle.unsafe_pass,

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: openqa-cn
• Source: openqa-cn/codexqa
• License: Apache-2.0
• Homepage: https://openqa.cn

Install and usage instructions live in the source repository linked above.