@ansonlai/docx-redline-js 0.2.0 → 0.4.0

package/docs/VALIDATION.md

@@ -1,5 +1,8 @@
 # Validation
 
+This document is the release-validation reference. For the testing model and
+step-by-step instructions for adding cases, see [TESTING.md](./TESTING.md).
+
 This package works on OOXML strings and intentionally leaves `.docx` zip
 packaging to consumers (release *tooling* assembles minimal `.docx` fixtures
 with a script-local zip writer; the published library still has no zip
@@ -52,8 +55,7 @@ Writes to `tmp/validation-docx/`, per case:
 ## Word Differential Check (Windows, desktop Word)
 
 ```bash
-node scripts/export-validation-fixtures.mjs
-npm run smoke:word:diff
+npm run test:word
 ```
 
 For each fixture, desktop Word opens the `.docx`, confirms revisions are
@@ -62,6 +64,21 @@ expected modified text; then reopens and runs **RejectAllRevisions** and
 compares to the original text. This is the strongest check available: Word
 itself resolves the revisions this library generated.
 
+`npm run test:word` exports the current English legal/administrative task
+catalogue to `tmp/word-validation/` before running the differential. Expected
+text is compared exactly by default; only Word's paragraph terminators are
+normalized. The 33-case catalogue includes reliability regressions for literal
+dollar/escape content, inline assistant-like text, leading whitespace,
+multi-paragraph replacement, preserving prior revisions on no-op, and atomic
+batch rollback after a later target failure. It also verifies that a document
+with a near-limit prior revision ID produces safe low-range IDs, and exercises
+bookmark/hyperlink adjacency, mixed formatted runs, content controls, table
+cells, structural tabs, locked complex fields, comments, footnotes/endnotes,
+headers/footers, and external hyperlinks with explicit structural-preservation
+assertions. The
+lower-level `npm run smoke:word:diff` remains available for an
+already-exported fixture directory.
+
 The older `npm run smoke:word -- path/to/file.docx` open-only smoke check
 remains available for ad-hoc files.
 
@@ -102,3 +119,65 @@ A second independent OOXML consumer parsing the fixtures without error.
 
 The Word differential check stays manual because it requires desktop Word;
 run it before tagging a release.
+
+## JavaScript Coverage Baseline
+
+```bash
+npm run test:coverage
+```
+
+The command runs the complete JavaScript test suite under c8 and prints a
+per-file report. Coverage answers “which implementation paths did the automated
+JavaScript tests execute?” It does not prove that executed paths are correct,
+that generated OOXML opens in Word, or that the real-document corpus is broad
+enough. Treat it as a map for finding thinly tested code; Word, schema,
+LibreOffice, fuzz, and corpus checks provide different evidence.
+
+The initial Phase 7 baseline recorded on 2026-08-29 was:
+
+| Metric | Coverage |
+|---|---:|
+| Lines / statements | 79.57% |
+| Functions | 80.07% |
+| Branches | 69.22% |
+
+This is a visibility baseline, not a CI threshold. Notable opportunities from
+the baseline are `services/numbering-helpers.js` (23.55% lines),
+`orchestration/route-plan.js` (23.75%), and
+`orchestration/list-structural-fallback.js` (57.19%).
+
+The post-Phase-5 snapshot recorded on 2026-08-30 is 79.96% lines/statements,
+80.95% functions, and 69.52% branches. Preserve both snapshots so changes are
+visible over time rather than presenting coverage as a pass/fail quality score.
+
+## Pinned SuperDoc Corpus References
+
+The real-document lane uses explicitly selected references from
+[SuperDoc's docx-corpus](https://docxcorp.us/) (ODC-By 1.0). It does not consume
+a floating or bulk manifest. The reviewed reference set contains 10 English
+legal and 10 English administrative documents. Run the complete local lane on
+Windows with desktop Word installed:
+
+```bash
+npm run test:corpus:word
+```
+
+To fetch only particular reviewed sources:
+
+```bash
+npm run corpus:fetch:superdoc -- --id <pinned-sha256>
+```
+
+Valid IDs and provenance are recorded in
+`tests/corpus/superdoc-english-legal-administrative.json`. The fetcher refuses
+unknown IDs, verifies downloaded bytes against a separately pinned observed
+SHA-256, and writes `.docx` plus attribution metadata under
+`tmp/superdoc-corpus/`. The separate digest is intentional: on 2026-08-29 the
+service returned valid DOCX bytes that did not hash to its advertised corpus
+IDs. Deterministic reviewed operations live in
+`tests/corpus/superdoc-word-scenarios.json`.
+
+The corpus suite replaces only `word/document.xml`, proves that the uncompressed
+bytes of every untouched package part remain identical, opens each result in
+Word without a repair dialog, and checks both Accept All and Reject All. Do not
+commit downloaded documents.

package/docs/WORD-MANUAL-REVIEW.md

@@ -0,0 +1,138 @@
+# Microsoft Word Manual Review
+
+This checklist is the human visual companion to `npm run test:word` and
+`npm run test:corpus:word`. The automated differential proves Word revision
+semantics by comparing text after Accept All and Reject All. This review checks
+the layout and interaction details that `Document.Content.Text` cannot see.
+
+An AI agent may use this same checklist as a visual preflight by controlling the
+local Word UI and inspecting screenshots. Mark that report **AI visual
+preflight**; it helps select and triage cases but does not replace the human
+release sign-off described below.
+
+## Prepare the review set
+
+Run the automated lane first:
+
+```powershell
+npm run test:word
+npm run test:corpus:word
+npm run report:word:coverage
+npm run review:word:prepare -- --cycle=0
+```
+
+The last command writes a pending review manifest under ignored
+`tmp/word-manual-review/` containing changed catalogue families, the rotating
+20% synthetic release sample, and legal/administrative corpus representatives.
+It only prepares the selection: it never records a visual pass or human
+sign-off. Use a new cycle number for each release rotation.
+
+Synthetic documents are generated under `tmp/word-validation/`; reviewed
+SuperDoc results are under `tmp/superdoc-word-fixtures/`. Do not commit generated
+or downloaded `.docx` files.
+
+Select:
+
+- every new or changed case;
+- every case required by the triggers in `docs/TESTING.md`;
+- at least 20% of unchanged synthetic cases, rotating from the prior release;
+- at least one legal and one administrative SuperDoc result; and
+- representative list, table, formatted-run, and anchor/field/content-control
+  structures.
+
+Record the installed Word version and build from **File → Account → About
+Word**. Differences in rendering can be version-specific.
+
+## Configure Word
+
+For the tracked-change inspection:
+
+1. Open the generated fixture directly in desktop Word.
+2. On **Review**, select **All Markup**.
+3. Under **Show Markup**, enable insertions/deletions, formatting, comments, and
+   all reviewers relevant to the case.
+4. Use the expected balloons/inline display for the document and enable
+   paragraph marks when checking whitespace, tabs, breaks, lists, and empty
+   paragraphs.
+5. Do not overwrite the generated fixture. Work on disposable copies if a
+   saved accepted or rejected view is useful.
+
+## Inspect each case
+
+### Tracked-change view
+
+- The document opens without a repair, conversion, or unreadable-content prompt.
+- Word shows the expected revision count and author attribution.
+- Insertions and deletions are anchored at the intended words or paragraph
+  marks; a small edit has not become an unexplained whole-paragraph rewrite.
+- Untargeted text and surrounding revisions remain unchanged.
+- Existing bold, italic, underline, highlighting, fonts, styles, and language
+  settings remain visually consistent.
+- Spaces, tabs, manual breaks, paragraph spacing, indentation, and alignment
+  look intentional with formatting marks visible.
+- Lists retain numbering, levels, continuation, indentation, and marker style.
+- Tables retain widths, borders, merged cells, row heights, and alignment.
+- Bookmarks, hyperlinks, fields, content controls, comments, and note references
+  remain in the correct visible location and still behave when activated.
+- Headers, footers, section boundaries, page breaks, and pagination remain
+  stable around the edit.
+- Revision balloons and comment balloons point to the correct content and do
+  not obscure or displace unrelated layout unexpectedly.
+
+### Accept All view
+
+On a disposable copy, choose **Accept All Changes** and verify:
+
+- the resulting visible text expresses the intended edit;
+- no deletion residue, empty revision wrapper, unexpected blank line, or stale
+  formatting remains;
+- lists, tables, fields, links, comments, notes, and page layout still work; and
+- untargeted content is visually unchanged.
+
+Close the copy without replacing the generated fixture.
+
+### Reject All view
+
+Reopen a fresh copy, choose **Reject All Changes**, and verify:
+
+- the original visible text and formatting are restored;
+- original list numbering, table layout, fields, anchors, and pagination return;
+  and
+- no content introduced by the edit remains.
+
+## Record the result
+
+Keep the review report with the release-validation artifacts. Screenshots may be
+stored under ignored `tmp/word-manual-review/<date>/` when useful, but do not
+commit corpus document images or document contents without checking their
+rights and sensitivity.
+
+Suggested report:
+
+```markdown
+# Word visual review — <release/date>
+
+- Reviewer:
+- Review date:
+- Word version/build:
+- Automated synthetic result:
+- Automated corpus result:
+- Review type: Human sign-off | AI visual preflight
+
+| Case | Why selected | All Markup | Accept All | Reject All | Result | Notes |
+|---|---|---|---|---|---|---|
+| example-case | New table structure | Pass | Pass | Pass | Pass | No layout shift |
+
+## Failures or follow-ups
+
+- None.
+```
+
+A **Pass** requires all three views to pass. Record **Fail** if the rendering or
+interaction is wrong even when automated text comparison passes. Turn a failure
+into a fixed regression case when possible; otherwise record the exact harness
+or Word-version limitation in the active reliability plan.
+
+For an AI preflight, also record screenshot paths and confidence/uncertainty in
+the notes. A human reviewer should revisit every AI failure or uncertain result
+and must still complete the release sample independently.