@ansonlai/docx-redline-js 0.1.4 → 0.2.0

package/docs/VALIDATION.md

@@ -0,0 +1,104 @@
+# Validation
+
+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
+dependency).
+
+The test suite verifies the accept/reject round-trip invariant using the
+library's own transforms. Because a shared misconception between the
+generator and the resolver would pass those tests silently, release
+validation adds **independent oracles**: Microsoft Word, LibreOffice, and
+the ECMA-376 schemas.
+
+## Automated Checks (every `npm test`)
+
+```bash
+npm test              # includes tests/roundtrip_fuzz_tests.mjs (seeded, deterministic)
+npm run test:isolation
+npm run check:types
+```
+
+The fuzz harness generates random paragraph structures and edits, then
+asserts the round-trip invariant plus `validateRedlineOoxml` on each case.
+Tune or reproduce with:
+
+```bash
+FUZZ_SEED=<seed> FUZZ_ITERATIONS=<n> node tests/roundtrip_fuzz_tests.mjs
+```
+
+A failing case prints its exact reproduction command.
+
+## Runtime Guardrail
+
+`validateRedlineOoxml(oxml)` (exported from `index.js`) runs the structural
+invariants at runtime and returns `{ valid, issues }`. Downstream packagers
+should call it before writing engine output into `word/document.xml`.
+
+## Export Fixtures
+
+```bash
+node scripts/export-validation-fixtures.mjs
+```
+
+Writes to `tmp/validation-docx/`, per case:
+
+- `<name>.document.xml` — generated `word/document.xml` payload
+- `<name>.docx` — minimal assembled package
+- `<name>.expected.json` — expected accept-all / reject-all plain text,
+  derived from edit *intent* (not from this library's transforms), so
+  external consumers act as independent oracles
+
+## Word Differential Check (Windows, desktop Word)
+
+```bash
+node scripts/export-validation-fixtures.mjs
+npm run smoke:word:diff
+```
+
+For each fixture, desktop Word opens the `.docx`, confirms revisions are
+visible, runs **AcceptAllRevisions**, and compares the document text to the
+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.
+
+The older `npm run smoke:word -- path/to/file.docx` open-only smoke check
+remains available for ad-hoc files.
+
+## Schema Validation (ECMA-376 transitional XSD)
+
+```bash
+node scripts/export-validation-fixtures.mjs
+bash scripts/validate-fixtures-xsd.sh
+```
+
+Downloads (and caches in `.cache/ooxml-schemas/`) the transitional
+wordprocessingml schemas from ECMA-376 Part 4, patches the `xml:` namespace
+import to resolve offline, and validates every `*.document.xml` fixture with
+`xmllint`. Requires `curl`, `unzip`, and `xmllint` (`libxml2-utils` on
+Debian/Ubuntu; available on Windows via conda/msys).
+
+## LibreOffice Consumer Check
+
+```bash
+cd tmp/validation-docx
+soffice --headless --convert-to pdf --outdir converted *.docx
+```
+
+A second independent OOXML consumer parsing the fixtures without error.
+
+## Continuous Validation
+
+`.github/workflows/validation.yml` runs nightly (and on demand via
+`workflow_dispatch`):
+
+1. **xsd-schema** — exports fixtures and validates them against the
+   ECMA-376 transitional `wml.xsd`.
+2. **libreoffice** — exports fixtures and converts them with headless
+   LibreOffice.
+3. **fuzz-extended** — 20,000 fuzz round-trip cases with a date-derived
+   seed, so every night explores new inputs. A failure log includes the
+   exact `FUZZ_SEED` reproduction command.
+
+The Word differential check stays manual because it requires desktop Word;
+run it before tagging a release.

package/docs/plans/2026-03-01-release-0.1.4-design.md

@@ -0,0 +1,31 @@
+# 0.1.4 Release Prep Design
+
+**Objective:** Prepare the repository for a `0.1.4` patch release without publishing from this session.
+
+## Scope
+
+- Bump the package version from `0.1.3` to `0.1.4` in release metadata.
+- Update local release-note examples that are pinned to the prior version.
+- Run release preflight verification locally after the version bump.
+- Hand off the exact npm commands for the manual publish step.
+
+## Approach
+
+Use minimal, explicit edits so the release prep is easy to review. Keep the release workflow local and manual, consistent with the existing policy in `.anson/release-ci-cd-notes.md`.
+
+## Verification
+
+Run the same preflight commands documented in the local release notes:
+
+- `npm test:isolation`
+- `npm test`
+- `npm run build`
+- `npm pack --dry-run`
+
+## Manual Handoff
+
+After verification, provide the exact commands for:
+
+- `npm whoami`
+- `npm publish --access public`
+- `npm view @ansonlai/docx-redline-js version`

package/docs/plans/2026-03-01-release-0.1.4.md

@@ -0,0 +1,108 @@
+# 0.1.4 Release Prep Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Prepare the repository for a local/manual `0.1.4` release and verify it is ready to publish.
+
+**Architecture:** Keep the release prep narrowly scoped to version metadata, local release instructions, and preflight verification. Do not publish from the implementation step; instead, leave the workspace in a verified, reviewable state and hand off the final npm commands.
+
+**Tech Stack:** Node.js, npm, PowerShell, package metadata files
+
+---
+
+### Task 1: Update Release Metadata
+
+**Files:**
+- Create: `docs/plans/2026-03-01-release-0.1.4-design.md`
+- Create: `docs/plans/2026-03-01-release-0.1.4.md`
+- Modify: `package.json`
+- Modify: `package-lock.json`
+- Modify: `.anson/release-ci-cd-notes.md`
+
+**Step 1: Write the failing test**
+
+Inspect the current version references and confirm they still show `0.1.3`.
+
+**Step 2: Run test to verify it fails**
+
+Run: `rg -uu -n "0\\.1\\.3|0\\.1\\.4" .`
+Expected: package metadata and local release-note examples still point to `0.1.3`.
+
+**Step 3: Write minimal implementation**
+
+- Change package version fields to `0.1.4`.
+- Update local release-note example commands and CDN URLs to `0.1.4`.
+- Save the release design and implementation plan docs.
+
+**Step 4: Run test to verify it passes**
+
+Run: `rg -uu -n "0\\.1\\.3|0\\.1\\.4" package.json package-lock.json .anson/release-ci-cd-notes.md`
+Expected: only `0.1.4` appears in those release-facing files.
+
+**Step 5: Commit**
+
+```bash
+git add docs/plans/2026-03-01-release-0.1.4-design.md docs/plans/2026-03-01-release-0.1.4.md package.json package-lock.json .anson/release-ci-cd-notes.md
+git commit -m "release: prep v0.1.4"
+```
+
+### Task 2: Run Release Preflight
+
+**Files:**
+- Modify: `dist/docx-redline-js.esm.js`
+
+**Step 1: Write the failing test**
+
+Assume the built artifact banner still reflects the previous version until the build runs.
+
+**Step 2: Run test to verify it fails**
+
+Run: `rg -n "v0\\.1\\.3|v0\\.1\\.4" dist/docx-redline-js.esm.js`
+Expected: the banner still shows `v0.1.3` before rebuilding.
+
+**Step 3: Write minimal implementation**
+
+Run the documented preflight:
+
+- `npm test:isolation`
+- `npm test`
+- `npm run build`
+- `npm pack --dry-run`
+
+**Step 4: Run test to verify it passes**
+
+Run: `rg -n "v0\\.1\\.3|v0\\.1\\.4" dist/docx-redline-js.esm.js`
+Expected: the banner shows `v0.1.4`, and the preflight commands complete successfully.
+
+**Step 5: Commit**
+
+```bash
+git add dist/docx-redline-js.esm.js
+git commit -m "build: refresh dist for v0.1.4"
+```
+
+### Task 3: Publish Handoff
+
+**Files:**
+- No file changes
+
+**Step 1: Write the failing test**
+
+Confirm the package is not yet published from this session.
+
+**Step 2: Run test to verify it fails**
+
+Run: `npm view @ansonlai/docx-redline-js version`
+Expected: the registry version may still report the prior published release until you publish manually.
+
+**Step 3: Write minimal implementation**
+
+Provide the exact local commands for npm auth check, publish, optional tag push, and post-publish verification.
+
+**Step 4: Run test to verify it passes**
+
+User runs the publish commands locally and confirms `npm view @ansonlai/docx-redline-js version` returns `0.1.4`.
+
+**Step 5: Commit**
+
+No additional commit required.