docs(document-cli): correct stale outline heading-nesting claim for docx/odt - #1006
Merged
Merged
Conversation
Mearman
marked this pull request as ready for review
September 5, 2026 14:00
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
…editor-built documents buildOutline reads a paragraph's headingLevel off the group anchor a DocumentTree carries, and that signal round-trips correctly today for both formats: buildDocxPackage stamps w:outlineLvl and buildOdtPackage promotes a heading paragraph to a real text:h with text:outline-level. Pins the outline command's own nesting behaviour against a docx/odt built through this ecosystem's editor rather than authored by Word or LibreOffice, so a future regression in either writer's heading-signal stamping fails here rather than only in a real-world source document.
…ing-nesting claim buildDocxPackage started stamping w:outlineLvl and buildOdtPackage started promoting a heading paragraph to a real text:h shortly after this claim was written, but the outline command's own docs were never updated to match. Heading nesting through outline works for a docx/odt this ecosystem's own writers produce, not only for one authored by Word or LibreOffice.
…to the real setters The docx and odt heading-nesting test comments credited buildDocxPackage/buildOdtPackage with stamping w:outlineLvl and promoting a paragraph to text:h, but neither test exercises those functions -- both drive the editor's own createDocx()/createOdt() through DocxParagraph.headingLevel and OdtParagraph.headingLevel, which buildDocxPackage and buildOdtPackage each delegate to for the identical write. writeOdt itself, named in the odt comment, is never called by this ecosystem at all. The docx comment also narrated the bug report's own history (issue #961 already fixed by the time it was filed) rather than stating the invariant the test actually pins.
…ically createOdt sat ahead of createOds in the named-import list.
Mearman
force-pushed
the
fix/heading-level-stamped-on-docx-odt-write
branch
from
September 5, 2026 17:01
98529df to
0ccab7a
Compare
Mearman
enabled auto-merge (rebase)
September 5, 2026 17:02
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Fixes #961
Investigated whether the outline command still loses heading nesting for a docx/odt this ecosystem's own writers produce, per the README claim the issue quotes as its evidence. It doesn't reproduce:
buildDocxPackage(documents.js's edit/docx writer) has stampedw:outlineLvlsince c16d5f4, andbuildOdtPackage/odf.js'swriteOdthave promoted a heading paragraph to a realtext:hwithtext:outline-levelsince the #752/#780 fixes -- both predate this issue by roughly two weeks.document-outline.js'sbuildOutlinereads that signal correctly on both formats.Verified four ways: a docx and an odt built directly through documents.js's own editor API (
createDocx/createOdt, settingheadingLevelon a paragraph) both nest correctly throughdocument-cli outline, and so does a markdown source converted through the realconvertcommand to docx and to odt. Every path preserves "Top Heading > Body / Sub Heading > Body" nesting exactly.The issue's own evidence was the document-cli README's outline-command description, written 2026-08-19 when the gap was real, never updated once the docx (2026-08-21) and odt fixes landed. This PR corrects that stale claim and pins the now-correct behaviour with two new regression tests (docx and odt, each built through the ecosystem's own editor rather than authored by Word/LibreOffice) so a future regression in either writer's heading-signal stamping fails here.
No writer/reader code changed -- both
ooxml.js's and documents.js's own docx write paths, and both odf.js's and documents.js's own odt write paths, already stamp the signal correctly.