Skip to content

docs(cli-reference): list the manifest status values in the status field - #1587

Merged
lizhengfeng101 merged 2 commits into
alibaba:mainfrom
ydflow:docs/skill-accuracy-fixes
Sep 28, 2026
Merged

lizhengfeng101 merged 2 commits into
alibaba:mainfrom
ydflow:docs/skill-accuracy-fixes

Conversation

@ydflow

@ydflow ydflow commented Sep 28, 2026

Copy link
Copy Markdown
Contributor

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 status field table in the CLI reference listed only success, completed_with_warnings, completed_with_errors, and skipped. Those four values are the pre-manifest path (outputJSON / outputJSONNoFiles). Every review run that produces a run manifest takes a different branch instead — cmd/opencodereview/output.go:386 sets payload.Status = string(manifest.TerminalState) — and internal/session/manifest.go:166 defines those states as complete, partial, failed, and skipped. So the documented enum was missing exactly the values a real ocr review --format json run emits, and a consumer validating against the documented set would reject a successful run's "complete".

The change documents both paths, keeps skipped listed 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_codes only accepts 4xx — pages/src/content/docs/en/configuration.md:277 already says "Only 4xx HTTP status codes are accepted" and that 5xx cannot be added. Matches sanitizeRetryCodes in internal/llm/resolver.go:970, which errors on anything outside 400–499 and warns on 408/409/429.
  • ocr session comments uses --json — cli-reference.md:442 already documents ocr session comments --json <session-id>. Matches the flag registration in cmd/opencodereview/session_cmd.go:207.
  • Exit-code semantics — the exit-codes section already states non-zero only on fatal error, and faq.md:234 spells out that partial failures exit 0. Matches reviewResultError in cmd/opencodereview/review_cmd.go:326.

Verification

  • make english-check — exit 0, "No unapproved non-English text in 635 scanned source files."
  • Confirmed LF line endings (no CRLF) and UTF-8 on all five files, per the AGENTS.md line-ending rule.
  • Confirmed the replaced rows keep the table structure: each is a 3-cell row, identical pipe count across all five locales.
  • pages/ vitest and typecheck were not run: pages/node_modules is absent in this checkout and I did not install dependencies. The change is Markdown table prose only — no .ts/.tsx and 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-check myself.

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.
@github-actions

Copy link
Copy Markdown
Contributor

✅ OpenCodeReview: Review skipped: no items were selected.

@lizhengfeng101 lizhengfeng101 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread pages/src/content/docs/en/cli-reference.md Outdated
Comment thread pages/src/content/docs/zh/cli-reference.md Outdated
Comment thread pages/src/content/docs/ja/cli-reference.md Outdated
Comment thread pages/src/content/docs/ko/cli-reference.md Outdated
Comment thread pages/src/content/docs/ru/cli-reference.md Outdated
Co-authored-by: Kite <254839944+lizhengfeng101@users.noreply.github.com>

@lizhengfeng101 lizhengfeng101 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@lizhengfeng101
lizhengfeng101 merged commit 1af527d into alibaba:main Sep 28, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants