docs(cli-reference): list the manifest status values in the status field - #1587
Conversation
The status field table listed only success / completed_with_warnings / completed_with_errors / skipped. Those four are the pre-manifest path; every review run that produced a manifest reports the manifest's terminal state instead (complete / partial / failed / skipped), so the documented enum was missing the values an actual run emits. Document both paths and note that skipped also covers the no-supported-files case. Synced across all five locales.
|
✅ OpenCodeReview: Review skipped: no items were selected. |
lizhengfeng101
left a comment
There was a problem hiding this comment.
Reviewed against the code and the fix itself looks accurate: cmd/opencodereview/output.go:385-401 sets payload.Status = string(manifest.TerminalState) whenever a manifest is present, completed_with_warnings/completed_with_errors are only reachable in the manifest == nil branch, the terminal states in internal/session/manifest.go:166-169 are exactly complete/partial/failed/skipped, and outputJSONNoFiles emits skipped for the no-supported-files case. So the old enum really would make a validating consumer reject a successful run's "complete".
One wording concern, with a suggestion on each of the five locale files: "pre-manifest path" is internal jargon that is not defined anywhere in the docs, so a reader still cannot tell which set of values their run emits. The payload embeds the manifest field itself (json:"manifest,omitempty"), and ocr review nearly always produces one — the nil-manifest branch is only reachable on manifest construction failure or the scan path (see the RunManifest comment in internal/agent/agent.go). Keying the row on the observable presence of the manifest field makes it self-contained and jq-verifiable.
Non-blocking follow-up: the canonical JSON example above this table (all five locales) still shows "status": "success" with no manifest field, which is the rare path for a real review run. Worth considering in a separate PR.
Disclosure: I used an AI assistant to help draft this review; the code references above were verified against the repository.
Co-authored-by: Kite <254839944+lizhengfeng101@users.noreply.github.com>
Summary
Follow-up to #850. lizhengfeng101 closed that PR on direction grounds but noted the accuracy fixes found there were worth carrying forward as a small focused PR. This is the one of the four that is still wrong on
main.The
statusfield table in the CLI reference listed onlysuccess,completed_with_warnings,completed_with_errors, andskipped. Those four values are the pre-manifest path (outputJSON/outputJSONNoFiles). Everyreviewrun that produces a run manifest takes a different branch instead —cmd/opencodereview/output.go:386setspayload.Status = string(manifest.TerminalState)— andinternal/session/manifest.go:166defines those states ascomplete,partial,failed, andskipped. So the documented enum was missing exactly the values a realocr review --format jsonrun emits, and a consumer validating against the documented set would reject a successful run's"complete".The change documents both paths, keeps
skippedlisted once with a note that it covers both the no-items-selected manifest state and the no-supported-files case (outputJSONNoFiles), and syncs the row across all five locales (en,ja,ko,ru,zh) — the same pattern used by #1555.The other three corrections from #850
Checked against
main; all three are already correct in the docs, so there is nothing to carry over:retry_codesonly accepts 4xx —pages/src/content/docs/en/configuration.md:277already says "Only 4xx HTTP status codes are accepted" and that 5xx cannot be added. MatchessanitizeRetryCodesininternal/llm/resolver.go:970, which errors on anything outside 400–499 and warns on 408/409/429.ocr session commentsuses--json—cli-reference.md:442already documentsocr session comments --json <session-id>. Matches the flag registration incmd/opencodereview/session_cmd.go:207.faq.md:234spells out that partial failures exit 0. MatchesreviewResultErrorincmd/opencodereview/review_cmd.go:326.Verification
make english-check— exit 0, "No unapproved non-English text in 635 scanned source files."pages/vitest and typecheck were not run:pages/node_modulesis absent in this checkout and I did not install dependencies. The change is Markdown table prose only — no.ts/.tsxand no anchors or cross-references touched — so it is outside those suites' coverage. Flagging it as unverified rather than claiming a pass.Disclosure: I used an AI assistant to draft this PR description and to locate the source lines; every claim above was verified by reading the referenced code and running
english-checkmyself.