Merge pull request #33 from JSv4/docs/html-previews-now-render

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

Author: JSv4

.github/workflows/redline-action-test.yml

@@ -27,9 +27,10 @@ jobs:
           original: tests/fixtures/original.docx
           modified: tests/fixtures/modified.docx
           author: Action Self-Test
-          # 'auto' exercises the graceful-skip path until a Docx2Html release
-          # with --track-changes support is on NuGet, then starts rendering.
-          html-preview: auto
+          # Docx2Html on NuGet now supports --track-changes, so previews are
+          # required here: 'true' fails the run rather than skipping, which is
+          # what keeps the README's claim that previews render honest.
+          html-preview: true
           artifact-name: docx-redlines-explicit
 
       - name: Assert outputs
@@ -49,8 +50,11 @@ jobs:
           # The exact count is pinned in tests/test_docxodus_engine.py, which runs
           # against the working tree.
           assert isinstance(record["revisions"], int) and record["revisions"] > 0, record
+          # html-preview is 'true' above, so a preview is part of the contract now.
+          assert record["html"], record
           '
           test -s "redlines/tests/fixtures/modified.redline.docx"
+          test -s "redlines/tests/fixtures/modified.redline.html"
 
   auto-detect:
     runs-on: ubuntu-latest

CLAUDE.md

@@ -39,7 +39,8 @@ between two commits (PR base/head, push before/after, or explicit `base-ref`/`he
 or takes an explicit `original`/`modified` pair, runs an engine via pip-installed
 python-redlines (PyPI wheels, not the working tree), and optionally renders HTML previews
 by invoking the Docxodus `Docx2Html` dotnet tool with `--track-changes` (requires
-Docxodus ≥ 7.1.0; `html-preview: auto` skips gracefully below that). Script unit +
+Docxodus ≥ 7.1.0, satisfied by the current NuGet release, so `auto` renders; it still
+skips gracefully when the tool is absent or pinned older). Script unit +
 integration tests: `tests/test_action_script.py`; action-level self-test:
 `.github/workflows/redline-action-test.yml` (runs the action from the checkout in both
 modes and asserts on outputs).

README.md

@@ -138,8 +138,11 @@ Notes:
 - Added and deleted `.docx` files are listed in the summary but not redlined — a redline
   needs both a base and a head version. Pure renames report zero revisions without
   invoking the engine.
-- 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.
+- HTML previews need the `Docx2Html` dotnet tool with `--track-changes` support (Docxodus
+  ≥ 7.1.0). That is now on NuGet, so the default `auto` mode renders previews rather than
+  skipping them. `auto` still degrades to a warning-and-skip when the tool is missing or
+  when `docx2html-version` pins it below 7.1.0; use `html-preview: true` to require a
+  preview and fail the run if one cannot be produced.
 - The action installs python-redlines from PyPI with prebuilt engine binaries — it does
   not build anything from the repository, so runs are fast on `ubuntu-latest` runners.
 

tests/test_action_script.py

@@ -83,6 +83,49 @@ def test_comparison_rejection_explains_the_removal():
     assert 'DocxDiff' in message
 
 
+# ---------------------------------------------------------------------------
+# HTML preview mode resolution
+#
+# Docx2Html on NuGet now supports --track-changes, so the action self-test
+# requires a rendered preview. That leaves the tolerant 'auto' path — the
+# default, and the one most callers hit — without integration coverage, so its
+# behaviour is pinned here instead, without depending on what is installed.
+# ---------------------------------------------------------------------------
+
+def test_resolve_previewer_returns_none_when_disabled(monkeypatch):
+    """'false' must not even look for the tool — that is what makes .NET optional."""
+    def fail():
+        raise AssertionError('find_docx2html() called despite html-preview: false')
+
+    monkeypatch.setattr(ra, 'find_docx2html', fail)
+    inputs = ra.Inputs.from_env({'INPUT_HTML_PREVIEW': 'false'})
+    assert ra.resolve_previewer(inputs) is None
+
+
+def test_resolve_previewer_auto_warns_and_skips_when_tool_is_missing(monkeypatch, capsys):
+    monkeypatch.setattr(ra, 'find_docx2html', lambda: None)
+    inputs = ra.Inputs.from_env({'INPUT_HTML_PREVIEW': 'auto'})
+
+    assert ra.resolve_previewer(inputs) is None
+    assert '::warning::' in capsys.readouterr().out
+
+
+def test_resolve_previewer_true_fails_when_tool_is_missing(monkeypatch):
+    monkeypatch.setattr(ra, 'find_docx2html', lambda: None)
+    inputs = ra.Inputs.from_env({'INPUT_HTML_PREVIEW': 'true'})
+
+    with pytest.raises(ra.ConfigError, match='Docx2Html'):
+        ra.resolve_previewer(inputs)
+
+
+@pytest.mark.parametrize('mode', ['auto', 'true'])
+def test_resolve_previewer_returns_the_tool_when_available(monkeypatch, mode):
+    monkeypatch.setattr(ra, 'find_docx2html', lambda: '/usr/local/bin/docx2html')
+    inputs = ra.Inputs.from_env({'INPUT_HTML_PREVIEW': mode})
+
+    assert ra.resolve_previewer(inputs) == '/usr/local/bin/docx2html'
+
+
 @pytest.mark.parametrize('env', [
     {'INPUT_ENGINE': 'wordperfect'},
     {'INPUT_HTML_PREVIEW': 'maybe'},