docs: name the stream the unclosed marker uses

[michen00]

What changes, and why

Three files claimed the unclosed-region warning is reported on stdout:

• mirrors/py/README.md:25 and mirrors/rs/README.md:29 — "A missing closing marker exempts the rest of the file and is reported on stdout."
• docs/rust-port-design.md:306 — "reports the unclosed marker on stdout"

Both implementations write it to stderr in the default mode. It reaches stdout only inside the warnings array under --json, and neither mirror's entry: passes --json — all four are --write or --fail-on-change — so the claim was wrong for every invocation those readmes document. Verified by running both binaries over a file with an opening marker and no closing one:

$ unwrap-markdown-prose-py unclosed.md 2>/dev/null      # stdout
$ unwrap-markdown-prose-py unclosed.md 2>&1 >/dev/null  # stderr
unclosed.md:1: unclosed unwrap-ignore-start, exempting the rest of the file

Byte-identical from the Rust binary.

README.md:279 names no stream and was already correct, so it is untouched. These three name stderr rather than copying that wording, because someone reading a mirror readme is deciding where to look for the message, and the --json alternative earns its clause. The design document settles the behaviour for both implementations, so it has to move with the two templates or it contradicts them.

Note for the release

Two of the three files are mirror templates, so make mirror-diff will disagree until a release regenerates the mirrors — the expected window, and the only route a template change has to a mirror. No CI job runs that target, and mirror-identity (which is not a required context) checks something else.

Corpus

The corpus is the specification, and both implementations answer to it. Tick what applies.

• This changes no behavior the corpus specifies.
• This changes what gets joined, and a case in corpus/ pins the new behavior. The case was written first and failed first.
• The change makes the tool join more than it did. The section above says what it will not eat.

The behaviour was already right in both implementations; only the description of it was wrong.

Checks

• make check passes, or make test does and this touches no Rust.

make tidy, and unwrap-markdown-prose-py --fail-on-change over all three files because tidy skips this repository's own hook. Markdown only — no Rust, no Python.

[qodo-code-review]

PR Summary by Qodo

Correct documented stream for unclosed-marker warnings

📝 Documentation 🕐 Less than 5 minutes

AI Description

• Correct unclosed-marker warning output from stdout to stderr in default mode.
• Document JSON warning behavior across mirror guides and the Rust design specification.

Diagram

graph TD
  A["Unclosed region"] --> B{"JSON enabled?"} -->|No| C["stderr warning"]
  B -->|Yes| D["warnings array"] --> E["stdout JSON"]

Loading

High-Level Assessment

The PR takes the appropriate approach by correcting both mirror templates and the shared design specification together. Changing implementation behavior or omitting stream details was unnecessary because both binaries already agree and the explicit routing helps users locate diagnostics.

Files changed (3) +3 / -3

Documentation (3) +3 / -3

rust-port-design.mdCorrect warning stream behavior in the Rust design +1/-1

Correct warning stream behavior in the Rust design

• Clarifies that unclosed-region warnings use stderr by default and the JSON warnings array on stdout under '--json'. This keeps the design specification aligned with both implementations.

docs/rust-port-design.md

README.mdDocument Python mirror warning destinations +1/-1

Document Python mirror warning destinations

• Corrects the default warning destination to stderr and documents the included filename and opening line. It also explains that JSON mode returns the warning through the stdout 'warnings' array.

mirrors/py/README.md

README.mdDocument Rust mirror warning destinations +1/-1

Document Rust mirror warning destinations

• Corrects the default warning destination to stderr and documents the included filename and opening line. It also explains that JSON mode returns the warning through the stdout 'warnings' array.

mirrors/rs/README.md

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 87.37%. Comparing base (1e9ac89) to head (8366ba5).

Additional details and impacted files

@@           Coverage Diff           @@
##             main      #33   +/-   ##
=======================================
  Coverage   87.37%   87.37%           
=======================================
  Files           3        3           
  Lines         689      689           
=======================================
  Hits          602      602           
  Misses         87       87           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (0)

Great, no issues found!

Qodo reviewed your code and found no material issues that require review

Tip of the day

💡 Did you know, you can add REVIEW.md to your repo root and Qodo follows it on every PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[Copilot]

🟢 Approval recommended

The changes are documentation-only and accurately reflect the verified stdout/stderr behavior in both implementations’ CLIs.

Pull request overview

This PR corrects documentation to match the tool’s actual behavior for reporting an unclosed unwrap-ignore-start marker: it is emitted to stderr in the default (non---json) mode, and only appears on stdout when using --json (inside the warnings array). This keeps the mirror READMEs and the Rust port design document aligned with both implementations’ CLI behavior.

Changes:

• Update both mirror READMEs to say the unclosed-region warning is reported on stderr, with a note about --json putting it on stdout in warnings.
• Update docs/rust-port-design.md to match the same stdout/stderr behavior statement.

File summaries

File	Description
mirrors/rs/README.md	Fixes the stream description for the unclosed-region warning and notes the --json stdout behavior.
mirrors/py/README.md	Same stream correction as the Rust mirror README, matching default vs --json behavior.
docs/rust-port-design.md	Aligns the design document’s statement with the implementations’ actual output streams.

Review details

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

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.