feat: comment extraction for DOCX and PPTX

[andrewjradcliffe]

Summary

Adds opt-in extraction of document comments for DOCX and PPTX. When enabled,
a # Comments section is appended to the end of the converted output, capturing
the commenter, the comment body, and the source the comment is attached to.

Exposed two ways:

• Library: a new ConversionOptions.extract_comments: bool (default false).
• CLI: a new --extract-comments flag.

The flag is a no-op for formats without comments, so it is always safe to pass.

Motivation

Comments carry review context — questions, decisions, action items — that is
otherwise lost on conversion. For LLM consumption (this crate's target), that
context is often as valuable as the body text. The feature is opt-in so default
output stays clean and existing behavior is unchanged.

Output format

The appended section uses a fixed, flat structure (global 1‑based index in order
of appearance):

# Comments

## 1
- **author**: Jane Smith (2024-01-15T09:30:00Z)
- **comment**: Please revise this paragraph.
- **source**: the quick brown fox

## 2
- **author**: Unknown
- **comment**: (reply) Agreed.
- **source**: jumped over

The section is appended to both markdown (formatted, above) and
plain_text (the same layout with all Markdown markers stripped:
Comments / 1 / author: / comment: / source:), consistent with the
crate's dual-output principle. With zero comments, the section is omitted
entirely.

Behavior

Common

• author renders as Name (date); the date is emitted verbatim (no parsing)
  and omitted when absent (no empty parentheses). A missing author becomes
  Unknown.
• The comment body is flattened to a single line (ASCII whitespace collapsed;
  meaningful non-ASCII spaces such as NBSP/ideographic space are preserved).
• Replies are flattened and prefixed with (reply).
• Malformed or unresolved comment data is skipped with a ConversionWarning
  (best-effort), so it surfaces on stderr and trips --strict.

DOCX

• Reads word/comments.xml for author/date/body and word/commentsExtended.xml
  for reply threading.
• The commented-on source is the text inside the commentRangeStart …
  commentRangeEnd span, scanned across the body and any headers, footers,
  footnotes, and endnotes. Ordered by first anchor appearance in a fixed part
  sequence (body → headers → footers → footnotes → endnotes); comments with no
  anchor are appended last. Source is collapsed to one line and capped at 200
  characters.

PPTX

• Supports both the legacy (commentAuthors.xml + comments/comment*.xml) and
  modern (authors.xml + comments/modernComment_*.xml, threaded) schemes.
• PPTX comments are anchored to a point, not a text span, so the source is the
  slide label (Slide N: Title, or Slide N when the slide is untitled).

Key changes

• src/converter/comments.rs (new): the Comment model, normalization helpers
  (collapse_ws, cap_text, format_author), and the # Comments Markdown /
  plain-text renderers (append_comments).
• src/converter/docx.rs: comment parsing (comments.xml,
  commentsExtended.xml, range collection across content parts) and assembly,
  wired into convert_inner.
• src/converter/pptx.rs: legacy + modern comment/author parsers and per-slide
  collection, wired into convert_inner.
• src/converter/ooxml_utils.rs: a shared attr_value_unescaped helper that
  XML-unescapes attribute values by local name.
• src/zip_utils.rs: read_zip_text_lossy for best-effort reads of optional
  sub-parts.
• src/converter/mod.rs, src/lib.rs, src/runner.rs: the
  extract_comments option, the async append sites, and the CLI flag.
• README.md, TECH_SPEC.md: documentation of the option, flag, output format,
  and per-format caveats.

convert_inner now returns the collected comments alongside the existing result
and pending-image data; the section is appended after image-placeholder
resolution in both the sync and async paths, so it never interferes with image
description.

Robustness (review hardening)

A follow-up commit addresses correctness/robustness issues found in review, each
with a regression test:

• Self-closing text elements (<w:t/>, <p:text/>, <a:t/>) no longer leak
  stray text into comment bodies.
• DOCX source no longer leaks past its range: range markers are honored even
  inside skipped mc:Choice branches, text is captured only inside a run, and
  each range's source is byte-bounded so a malformed unclosed range cannot
  absorb the rest of the part.
• DOCX w14:paraId is taken only from top-level paragraphs, so a comment ending
  in a table doesn't break reply detection.
• A PPTX slide carrying both legacy and modern comment parts no longer
  double-reports (modern is preferred).
• A multi-line PPTX slide title no longer breaks the single-line source item.
• Author/date attributes are XML-unescaped (R&D → R&D), matching body
  handling.
• A malformed (non-UTF-8) comment sub-part degrades gracefully instead of
  aborting the whole conversion.

Testing

• Unit tests for every parser and helper (the comment model, range collection,
  author/reply parsing, edge cases) plus end-to-end tests through the public
  convert_bytes API for DOCX and PPTX, and CLI tests for the flag.
• Full verification: cargo test (all unit + integration suites), cargo clippy -- -D warnings, cargo fmt --check, cargo doc --no-deps (zero warnings),
  the async and async-gemini feature checks, the WASM target checks, and
  cargo build --release — all green.

Notes / limitations

• The modern-PPTX comment schema is implemented from the MS-PPTX/ECMA-376
  specification and validated against synthetic fixtures; comment parsing is
  best-effort.
• source truncation is on a Unicode scalar boundary (panic-safe); multi-scalar
  grapheme clusters (e.g. flag/ZWJ emoji) may be split in the truncated tail.
• No new runtime dependencies; the feature is pure Rust and WASM-compatible.