Fix docstring drift Copilot caught on PR #1068

[ptr727]

Follow-up to #1067/#1069, prompted by Copilot's round on the develop -> main promotion PR (#1068).

Copilot flagged two real docstring/comment inaccuracies:

• The status docstring's cr_outside_diff paragraph claimed it prints only once CodeRabbit has raised a finding, but digest() also prints it (as cr_outside_diff=0+) once the reviews window is truncated, regardless of what's currently visible.
• TestOtherReviewers' docstring claimed "identity and commit only", contradicting its own rate-limit-marker tests, which read comment/review body content.

local-strict-review against this diff (dispatched before this push) caught three follow-on issues in that same rewrite (a garden-path modifier, a reword that read as the opposite of what it meant, and a comment trim from the same review round that had dropped load-bearing rationale), all fixed. All covered by the existing 306-test suite passing unchanged.

All local gates pass: ruff check/format, mypy, the full scripts/tests suite, prose_lint.py --diff, repo_gate.py --check eol.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • CodeRabbit findings are now reported when the review window is truncated, even if no visible findings were detected.
  • Truncated results display the count as 0+ when applicable, making incomplete review results clearer.

• Documentation

  • Clarified Qodo parser behavior and automated review-bot coverage.
  • Documented which review checks apply to different automated reviewers without changing parsing behavior.

[qodo-code-review]

PR Summary by Qodo

Clarify review-status and reviewer-test documentation

📝 Documentation🕐 Less than 10 minutes

AI Description

• Correct cr_outside_diff documentation for findings and truncated review windows.
• Clarify reviewer test scope and preserve rationale behind Qodo parsing patterns.

Diagram

graph TD
Reviews["Review window"] --> Digest["digest()"] --> Status["Status docs"]
Qodo["Qodo comments"] --> Patterns["Qodo patterns"] --> Digest
Tests["Reviewer tests"] -.-> Digest

Loading

High-Level Assessment

Correcting the existing docstrings and preserving concise, load-bearing regex rationale is the appropriate approach. Logic and tests should remain unchanged because the existing suite already covers the documented behavior.

Files changed (2) +14 / -17

Documentation (2) +14 / -17

pr_review.pyAlign status and Qodo parser documentation with behavior+9/-13

Align status and Qodo parser documentation with behavior

• Corrects the 'cr_outside_diff' description to include output caused by a truncated reviews window. Condenses Qodo regex comments while retaining the structural-match, badge-glyph, and ASCII-escape rationale needed to prevent known false positives.

scripts/pr_review.py

test_pr_review.pyClarify non-Copilot reviewer test coverage+5/-4

Clarify non-Copilot reviewer test coverage

• Revises 'TestOtherReviewers' documentation to include structural rate-limit marker parsing and direct free-text finding coverage to the dedicated CodeRabbit and Qodo test classes. No assertions or test behavior change.

scripts/tests/test_pr_review.py

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 0bb7d326-17d5-4315-bc7e-01e52b36ea42

📥 Commits

Reviewing files that changed from the base of the PR and between d2edf62 and ef4048e.

📒 Files selected for processing (1)

• scripts/pr_review.py

Included review availability: Your plan provides up to 10 included reviews per hour; 3 remain after this review.

---

📝 Walkthrough

Walkthrough

The review digest now reports possible unread CodeRabbit outside-diff findings when the review window is truncated. Qodo parser documentation and reviewer test-scope documentation were clarified without changing parser patterns.

Changes

Review reporting and documentation

Layer / File(s)	Summary
Truncated outside-diff reporting scripts/pr_review.py	The digest displays 0+ when the review window is truncated and no visible CodeRabbit outside-diff finding exists.
Parser and reviewer test documentation scripts/pr_review.py, scripts/tests/test_pr_review.py	The documentation clarifies Qodo heading, finding, and badge parsing, plus the scope of bot and Copilot-specific tests. Existing Qodo regex behavior remains unchanged.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Merge Risk:⚪ Minimal · up to ef404

This change corrects inaccurate documentation and comments without changing product behavior; all listed checks pass, and no actionable merge-blocking risk remains.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the pull request's main change: correcting documentation and comment inaccuracies identified during review of PR #1068, including a Copilot finding.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 2 files.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix-pr1068-docstring-drift

---

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

🟡 Changes recommended

A couple of updated docstrings still misstate the actual behavior/shape of the underlying helpers and output conditions.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

This PR updates Python docstrings and inline comments to reflect the current behavior of scripts/pr_review.py and its test suite, addressing docstring drift identified during prior promotion-PR review automation.

Changes:

• Refines TestOtherReviewers documentation to describe what the class actually validates (threads, head presence, and structural rate-limit markers).
• Updates scripts/pr_review.py’s status help text to describe when cr_outside_diff is printed, including the truncated-reviews case.
• Trims and tightens explanatory comments around Qodo parsing regexes while keeping the rationale for badge parsing and ASCII-safe glyph escaping.

File summaries

File	Description
scripts/tests/test_pr_review.py	Updates TestOtherReviewers docstring to align with what the tests cover.
scripts/pr_review.py	Adjusts status docstring wording for cr_outside_diff printing behavior and refines Qodo-regex commentary.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🔵 Needs a closer look

One newly edited comment (QODO_FINDING) is still ambiguous about matching a numeric prefix (regex \\d+\\.) versus the literal text N., which risks reintroducing the doc/comment drift this PR is addressing.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

scripts/pr_review.py:224

• The comment for QODO_FINDING says it matches headings starting with N., which can read as the literal letter N rather than “a number”. Since the regex is \d+\., reword the comment to show an example like 1. to avoid future doc/comment drift.

# Only the numbered heading counts as a finding, told apart from Qodo's own nested sub-summaries by starting with `N.`

• Files reviewed: 2/2 changed files
• Comments generated: 0 new
• Review effort level: Lite

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0)📘 Rule violations (0)📜 Skill insights (0)

1. Wrapped status docstring sentence✗ Dismissed📜 Skill insight✧ Quality

Description

The revised status docstring wraps the sentence beginning since an older round could then across
lines 70-71, creating a mid-sentence line break. This violates the requirement that structured
multi-line prose use one complete sentence per line.

Code

scripts/pr_review.py[R70-71]

+ round, or once the reviews window is truncated, since an older round could then+ still carry one unseen (`cr_outside_diff=0+`). Stays silent otherwise, on an

Relevance

●●● Strong

Recent accepted prose-style fixes support enforcing one-sentence-per-line wrapping in
scripts/pr_review.py.

PR-#991

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The added text at lines 70-71 continues one sentence across a line boundary: line 70 ends with
then and line 71 completes the sentence. This directly matches the checklist's prohibited
mid-sentence wrapping pattern.

scripts/pr_review.py[70-71]
Skill: comment-and-doc-style

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution
## Issue description
The `status` docstring contains a sentence split across two lines at `since an older round could then`.
## Issue Context
Comments and documentation must contain exactly one sentence per line, without mid-sentence wrapping.
## Fix Focus Areas
- scripts/pr_review.py[70-71]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

2. Wrapped reviewer docstring sentence✗ Dismissed📜 Skill insight✧ Quality

Description

The new TestOtherReviewers docstring wraps the sentence beginning generalized past Copilot
across lines 588-589 and also wraps the next sentence across lines 590-591. These mid-sentence line
breaks violate the one-sentence-per-line documentation rule.

Code

scripts/tests/test_pr_review.py[R588-589]

+ """Thread resolution, head-presence, and the rate-limit marker's own structural pattern,+ generalized past Copilot to the other review bots this repository has trialed. Free-text

Relevance

●● Moderate

A close precedent rejected this exact style rule in test docstrings, despite recent accepted prose
fixes elsewhere.

PR-#959
PR-#991

ⓘ Recommendations generated based on similar findings in past PRs

Evidence

The added docstring line 588 ends with a comma and line 589 continues the same sentence; line 590
similarly continues into line 591. The changed prose therefore contains prohibited mid-sentence
wrapping.

scripts/tests/test_pr_review.py[588-591]
Skill: comment-and-doc-style

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution
## Issue description
The `TestOtherReviewers` docstring contains mid-sentence line wraps in its rewritten summary.
## Issue Context
Each sentence in multi-line comments and documentation must occupy one line; reflow the prose without changing its meaning.
## Fix Focus Areas
- scripts/tests/test_pr_review.py[588-591]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

✅ Compliance rules (platform): 71 rules

✅ Skills: 5 invoked

comment-and-doc-style

dotnet-codestyle

python-codestyle

shell-codestyle

workflow-ci-contract

Review mode: 🚀 Fast: This is a localized, low-risk documentation/comment correction with no runtime behavior or contract changes; the accompanying test edit only updates its docstring.

Tip of the day

💡 Did you know, you can group findings by type and pick your Finding display, from Minimal to Full

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[ptr727]

Answering Copilot's suppressed finding (comment-only, no thread): "Previously missed (1) — QODO_FINDING's comment reads N. as the literal letter N." Fixed in ef4048e: reworded to spell out the constraint with an example (1., 2., ...) instead of a placeholder letter.

[Copilot]

🟢 Approval recommended

The changes are documentation/comment-only adjustments that match the verified implementation and test structure, with no behavioral modifications.

Review details

• Files reviewed: 2/2 changed files
• Comments generated: 0 new
• Review effort level: Lite