Skip to content

docs: HTML previews render now; stop saying they are skipped - #33

Merged
JSv4 merged 1 commit into
mainfrom
docs/html-previews-now-render
Sep 6, 2026
Merged

docs: HTML previews render now; stop saying they are skipped#33
JSv4 merged 1 commit into
mainfrom
docs/html-previews-now-render

Conversation

@JSv4

@JSv4 JSv4 commented Sep 6, 2026

Copy link
Copy Markdown
Owner

Follow-up to #32.

The README told readers that HTML previews were waiting on something:

HTML previews require a Docx2Html release with --track-changes support (Docxodus ≥ 7.1.0); until that is on NuGet, the default auto mode skips previews with a warning.

That release is on NuGet. The v1.0.0 action self-test installed Docx2Html 12.1.0 and returned a real preview path:

{"path":"tests/fixtures/modified.docx","revisions":10,
 "html":"redlines/tests/fixtures/modified.redline.html"}

So the caveat described a state of the world that no longer holds. Corrected in README.md and CLAUDE.md.

Why this needed more than a text edit

html-preview: auto passes whether or not previews actually render — that is the whole point of the mode. It is also what let the stale claim sit there unnoticed: no check would ever have contradicted it.

The self-test's explicit-pair job now uses html-preview: true and asserts a preview came back, so the README's claim has something holding it up.

That created a gap, since the only other job runs html-preview: 'false' — nothing would exercise auto, which is the default and the path most callers hit. resolve_previewer had no unit coverage at all, so its mode logic is now pinned there instead: 'false' never even looks for the tool (what makes .NET genuinely optional), 'auto' warns and skips when it is missing, 'true' raises. Faster than an integration run and independent of what happens to be installed.

These tests were written against existing behaviour, so passing proves nothing on its own. Verified by mutation instead — removing the 'false' short-circuit and neutering the 'true' raise each fail the matching test, and only that test:

MUTATION 1: drop the 'false' short-circuit
  FAILED test_resolve_previewer_returns_none_when_disabled     (1 failed, 4 passed)
MUTATION 2: 'true' no longer raises
  FAILED test_resolve_previewer_true_fails_when_tool_is_missing (1 failed, 4 passed)

Scope note

You asked for the stale README line. The self-test change and the unit tests are here because they are what keeps that line from going stale again — but they are a separable concern, so say the word and I will cut this back to the two doc edits.

77 passed, 1 skipped locally.

🤖 Generated with Claude Code

https://claude.ai/code/session_014ed9PC7DDco5AFPjsZyy9F

The README said previews wait on "a Docx2Html release with --track-changes
support" reaching NuGet. That release is there — the v1.0.0 action
self-test installed Docx2Html 12.1.0 and produced a .redline.html — so
the caveat described a state of the world that no longer holds.

Requires the preview in the self-test rather than tolerating a skip.
'auto' would keep passing whether or not previews worked, which is what
let the stale claim survive unnoticed; 'true' fails the run instead, so
the README's claim has something holding it up.

That leaves 'auto' — the default, and the path most callers take —
without integration coverage, since the other job runs 'false'. Its mode
logic is now unit-tested instead, which is faster and does not depend on
what happens to be installed: 'false' never looks for the tool, 'auto'
warns and skips when it is absent, 'true' raises. Verified by mutation:
removing the 'false' short-circuit and the 'true' raise each fail the
matching test.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_014ed9PC7DDco5AFPjsZyy9F
@JSv4
JSv4 merged commit a84be23 into main Sep 6, 2026
15 checks passed
@JSv4
JSv4 deleted the docs/html-previews-now-render branch September 6, 2026 14:20
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant