[kklimuk]

🤖 docx-cli triage

What was wrong

On a Word-saved file, comments add wrote the comment into comments.xml but added nothing to commentsIds.xml or commentsExtended.xml, and comments delete never removed the commentsIds entry. Word then reports unreadable content, and its repair renumbers every comment. Repro on tests/fixtures/academic-paper.docx (44/44/44 comment/id/ext entries):

$ docx comments add ap.docx --at p3 --text "New one"   → comments=45 commentsIds=44 commentsExtended=44
$ docx comments delete ap.docx --at c0                → comments=44 commentsIds=44 commentsExtended=43
$ docx validate ap.docx                               → valid — 11 parts checked

What changed

• CommentsView now also loads and writes commentsIds.xml and commentsExtensible.xml. Every comment it appends (add, reply, audit comment) gets an entry in each sidecar the package already has: a w15:commentEx done="0", a w16cid:commentId with a newly minted unique durableId, and a w16cex:commentExtensible with that durableId and dateUtc. delete (including the reply cascade) removes all three.
• A sidecar that is missing is not created, so files docx-cli produces itself come out the same as before.
• raw part replace/edit now refuses the two parts the view owns now (otherwise the view would overwrite the raw change on save).
• Regression tests in tests/cli/comments.test.ts, plus one sentence in REFERENCE.md.

Verification

• After the fix, same repro: add → 45/45/45, reply → 46/46/46, delete c0 → 45/45/45, delete c44 (and its reply) → 43/43/43. validate passes.
• The new test fails on main and passes with the fix.
• bun run check ✅ bun run test:unit ✅ (1911 tests; the pre-commit hook also ran 1939 across 59 files)
• /simplify: the three sidecar reads now run in parallel. /code-review xhigh: the forked run reviewed a different checkout, not this diff, so I did the correctness pass by hand. No changes from it.
• Not checked in Word or LibreOffice here (not available). The reporter's attachment couldn't be downloaded through the proxy, so I built my own fixture.

Decisions for you

• A docx comments rebuild-parts FILE verb (the reporter suggested it) to repair files already written by ≤0.28.0, which have stale side parts. Not built.
• Should validate flag side parts that are out of step with comments.xml? That is tracked separately in feat(validate): report cross-part comment inconsistencies, not only per-part schema errors #34.
• No LibreOffice fixture added: fixture builders start from docx create, which never writes these sidecars. Do you want a Word-shaped fixture checked in (e.g. the reporter's)?

Fixes #33

Action needed: approve/merge — PR ready for your review; check it opens without a repair prompt in Word if you can.

---

Generated by Claude Code