Expose Docxodus comparison settings via Python kwargs

Thread WmlComparerSettings options from Python kwargs through CLI
flags to the Docxodus C# binary. Supports detail_threshold,
case_insensitive, detect_moves, simplify_move_markup,
move_similarity_threshold, move_minimum_word_count,
detect_format_changes, conflate_spaces, and date_time.

- Extract _build_command() in BaseEngine, override in DocxodusEngine
- Add input validation for thresholds and word count
- Update Docxodus CLI to parse --flags (backward compat with legacy format)
- Rebuild all platform binaries with new flag support
- Add 13 new tests (integration, validation, unit)
- Update README with Comparison Settings section

Author: JSv4

CLAUDE.md

@@ -44,7 +44,7 @@ The system uses a two-layer wrapper pattern with a shared base class:
    - `XmlPowerToolsEngine(BaseEngine)` — sets constants for the Open-XML-PowerTools binary (`dist/`, `bin/`, `redlines`)
    - `DocxodusEngine(BaseEngine)` — sets constants for the Docxodus binary (`dist_docxodus/`, `bin_docxodus/`, `redline`)
 
-   Both engines share the same CLI argument format: `<author_tag> <original.docx> <modified.docx> <output.docx>`
+   Both engines expose `run_redline(author_tag, original, modified, **kwargs)`. `DocxodusEngine` overrides `_build_command()` to translate kwargs (e.g. `detect_moves`, `detail_threshold`) into CLI flags for the Docxodus binary. `XmlPowerToolsEngine` uses the legacy 4-positional-arg format and ignores kwargs.
 
 2. **C# binaries**:
    - `csproj/Program.cs` — Open-XML-PowerTools CLI tool

README.md

@@ -92,6 +92,42 @@ with open("redline.docx", "wb") as f:
 print(stdout)  # e.g. "Redline complete: 9 revision(s) found"
 ```
 
+## Comparison Settings (DocxodusEngine only)
+
+`DocxodusEngine` supports fine-grained control over the comparison via keyword arguments to `run_redline()`:
+
+```python
+from python_redlines import DocxodusEngine
+
+engine = DocxodusEngine()
+redline_bytes, stdout, stderr = engine.run_redline(
+    "Reviewer", original, modified,
+    detect_moves=True,
+    simplify_move_markup=True,
+    detail_threshold=0.3,
+    case_insensitive=True,
+)
+```
+
+| Setting | Type | Default | Description |
+|---|---|---|---|
+| `detail_threshold` | float | 0.0 | Comparison granularity (0.0–1.0, lower = more detailed) |
+| `case_insensitive` | bool | False | Ignore case differences |
+| `detect_moves` | bool | False | Enable move detection |
+| `simplify_move_markup` | bool | False | Convert moves to del/ins for Word compatibility |
+| `move_similarity_threshold` | float | 0.8 | Jaccard threshold for move matching (0.0–1.0) |
+| `move_minimum_word_count` | int | 3 | Minimum words for move detection |
+| `detect_format_changes` | bool | True | Detect formatting-only changes |
+| `conflate_spaces` | bool | True | Treat breaking/non-breaking spaces the same |
+| `date_time` | str | now | Custom ISO 8601 timestamp for revisions |
+
+> **Warning:** Move detection can cause Word to display "unreadable content" warnings due to a known
+> ID collision bug. When using `detect_moves=True`, always set `simplify_move_markup=True` as well.
+> This converts move markup to regular del/ins (loses green move styling but ensures Word compatibility).
+
+> **Note:** These settings are only available on `DocxodusEngine`. `XmlPowerToolsEngine` ignores
+> extra keyword arguments.
+
 ## Architecture Overview
 
 Both engines follow the same pattern: a Python wrapper class invokes a self-contained C# binary via subprocess.

docxodus

@@ -100,11 +100,23 @@ def _get_binaries_info(self):
 
         return binary_name, zip_name
 
-    def run_redline(self, author_tag: str, original: Union[bytes, Path], modified: Union[bytes, Path]) \
+    def _build_command(self, author_tag: str, original_path, modified_path, target_path, **kwargs):
+        """
+        Build the command list for subprocess execution.
+        Subclasses can override to customize argument format.
+        """
+        return [self.extracted_binaries_path, author_tag, original_path, modified_path, target_path]
+
+    def run_redline(self, author_tag: str, original: Union[bytes, Path], modified: Union[bytes, Path], **kwargs) \
             -> Tuple[bytes, Optional[str], Optional[str]]:
         """
         Runs the redline binary. The 'original' and 'modified' arguments can be either bytes or file paths.
         Returns the redline output as bytes.
+
+        Additional keyword arguments are passed to _build_command() for engine-specific options.
+        DocxodusEngine supports: detail_threshold, case_insensitive, detect_moves,
+        simplify_move_markup, move_similarity_threshold, move_minimum_word_count,
+        detect_format_changes, conflate_spaces, date_time.
         """
         temp_files = []
         try:
@@ -114,7 +126,7 @@ def run_redline(self, author_tag: str, original: Union[bytes, Path], modified: U
             modified_path = self._write_to_temp_file(modified) if isinstance(modified, bytes) else modified
             temp_files.extend([target_path, original_path, modified_path])
 
-            command = [self.extracted_binaries_path, author_tag, original_path, modified_path, target_path]
+            command = self._build_command(author_tag, original_path, modified_path, target_path, **kwargs)
 
             # Capture stdout and stderr
             result = subprocess.run(command, check=True, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
@@ -156,3 +168,61 @@ class DocxodusEngine(BaseEngine):
     DIST_DIR_NAME = 'dist_docxodus'
     BIN_DIR_NAME = 'bin_docxodus'
     BINARY_BASE_NAME = 'redline'
+
+    # Boolean flags (default False — presence enables)
+    _BOOL_FLAGS = [
+        ('case_insensitive', '--case-insensitive'),
+        ('detect_moves', '--detect-moves'),
+        ('simplify_move_markup', '--simplify-move-markup'),
+    ]
+
+    # Negatable flags (default True — --no- prefix disables)
+    _NEG_FLAGS = [
+        ('detect_format_changes', '--no-detect-format-changes'),
+        ('conflate_spaces', '--no-conflate-spaces'),
+    ]
+
+    # Value flags
+    _VALUE_FLAGS = [
+        ('detail_threshold', '--detail-threshold'),
+        ('move_similarity_threshold', '--move-similarity-threshold'),
+        ('move_minimum_word_count', '--move-minimum-word-count'),
+        ('date_time', '--date-time'),
+    ]
+
+    @staticmethod
+    def _validate_kwargs(kwargs):
+        if 'detail_threshold' in kwargs:
+            val = kwargs['detail_threshold']
+            if not isinstance(val, (int, float)) or val < 0.0 or val > 1.0:
+                raise ValueError(f"detail_threshold must be a float between 0.0 and 1.0, got {val!r}")
+
+        if 'move_similarity_threshold' in kwargs:
+            val = kwargs['move_similarity_threshold']
+            if not isinstance(val, (int, float)) or val < 0.0 or val > 1.0:
+                raise ValueError(f"move_similarity_threshold must be a float between 0.0 and 1.0, got {val!r}")
+
+        if 'move_minimum_word_count' in kwargs:
+            val = kwargs['move_minimum_word_count']
+            if not isinstance(val, int) or val < 1:
+                raise ValueError(f"move_minimum_word_count must be a positive integer, got {val!r}")
+
+    def _build_command(self, author_tag, original_path, modified_path, target_path, **kwargs):
+        self._validate_kwargs(kwargs)
+
+        cmd = [self.extracted_binaries_path, original_path, modified_path, target_path,
+               f'--author={author_tag}']
+
+        for kwarg, flag in self._BOOL_FLAGS:
+            if kwargs.get(kwarg):
+                cmd.append(flag)
+
+        for kwarg, neg_flag in self._NEG_FLAGS:
+            if kwarg in kwargs and not kwargs[kwarg]:
+                cmd.append(neg_flag)
+
+        for kwarg, flag in self._VALUE_FLAGS:
+            if kwarg in kwargs:
+                cmd.append(f'{flag}={kwargs[kwarg]}')
+
+        return cmd

src/python_redlines/engines.py

@@ -30,3 +30,161 @@ def test_run_docxodus_with_real_files(original_docx, modified_docx):
     assert len(redline_output) > 0
     assert stderr is None
     assert "revision(s) found" in stdout
+
+
+# --- Integration tests for comparison settings ---
+
+def test_docxodus_with_detect_moves(original_docx, modified_docx):
+    engine = DocxodusEngine()
+    redline_output, stdout, stderr = engine.run_redline(
+        "TestAuthor", original_docx, modified_docx,
+        detect_moves=True, simplify_move_markup=True,
+    )
+    assert redline_output is not None
+    assert len(redline_output) > 0
+    assert stderr is None
+    assert "revision(s) found" in stdout
+
+
+def test_docxodus_with_detail_threshold(original_docx, modified_docx):
+    engine = DocxodusEngine()
+    redline_output, stdout, stderr = engine.run_redline(
+        "TestAuthor", original_docx, modified_docx,
+        detail_threshold=0.5,
+    )
+    assert redline_output is not None
+    assert len(redline_output) > 0
+    assert stderr is None
+    assert "revision(s) found" in stdout
+
+
+def test_docxodus_with_case_insensitive(original_docx, modified_docx):
+    engine = DocxodusEngine()
+    redline_output, stdout, stderr = engine.run_redline(
+        "TestAuthor", original_docx, modified_docx,
+        case_insensitive=True,
+    )
+    assert redline_output is not None
+    assert len(redline_output) > 0
+    assert stderr is None
+    assert "revision(s) found" in stdout
+
+
+def test_docxodus_with_no_format_changes(original_docx, modified_docx):
+    engine = DocxodusEngine()
+    redline_output, stdout, stderr = engine.run_redline(
+        "TestAuthor", original_docx, modified_docx,
+        detect_format_changes=False,
+    )
+    assert redline_output is not None
+    assert len(redline_output) > 0
+    assert stderr is None
+    assert "revision(s) found" in stdout
+
+
+def test_docxodus_with_all_options(original_docx, modified_docx):
+    engine = DocxodusEngine()
+    redline_output, stdout, stderr = engine.run_redline(
+        "TestAuthor", original_docx, modified_docx,
+        detail_threshold=0.3,
+        case_insensitive=True,
+        detect_moves=True,
+        simplify_move_markup=True,
+        move_similarity_threshold=0.7,
+        move_minimum_word_count=2,
+        detect_format_changes=False,
+        conflate_spaces=False,
+        date_time="2025-01-01T00:00:00Z",
+    )
+    assert redline_output is not None
+    assert len(redline_output) > 0
+    assert stderr is None
+    assert "revision(s) found" in stdout
+
+
+# --- Validation tests ---
+
+def test_docxodus_invalid_detail_threshold():
+    engine = DocxodusEngine()
+    with pytest.raises(ValueError, match="detail_threshold must be a float between 0.0 and 1.0"):
+        engine._build_command("Author", "orig", "mod", "out", detail_threshold=1.5)
+
+
+def test_docxodus_invalid_move_similarity_threshold():
+    engine = DocxodusEngine()
+    with pytest.raises(ValueError, match="move_similarity_threshold must be a float between 0.0 and 1.0"):
+        engine._build_command("Author", "orig", "mod", "out", move_similarity_threshold=-0.1)
+
+
+def test_docxodus_invalid_move_minimum_word_count():
+    engine = DocxodusEngine()
+    with pytest.raises(ValueError, match="move_minimum_word_count must be a positive integer"):
+        engine._build_command("Author", "orig", "mod", "out", move_minimum_word_count=0)
+
+
+def test_docxodus_invalid_move_minimum_word_count_type():
+    engine = DocxodusEngine()
+    with pytest.raises(ValueError, match="move_minimum_word_count must be a positive integer"):
+        engine._build_command("Author", "orig", "mod", "out", move_minimum_word_count=2.5)
+
+
+# --- Unit test for _build_command flag construction ---
+
+def test_build_command_default():
+    engine = DocxodusEngine()
+    cmd = engine._build_command("Author", "/tmp/orig.docx", "/tmp/mod.docx", "/tmp/out.docx")
+    assert cmd[1] == "/tmp/orig.docx"
+    assert cmd[2] == "/tmp/mod.docx"
+    assert cmd[3] == "/tmp/out.docx"
+    assert "--author=Author" in cmd
+    assert len(cmd) == 5  # binary + 3 positional + --author
+
+
+def test_build_command_with_all_flags():
+    engine = DocxodusEngine()
+    cmd = engine._build_command(
+        "Author", "/tmp/orig.docx", "/tmp/mod.docx", "/tmp/out.docx",
+        detail_threshold=0.5,
+        case_insensitive=True,
+        detect_moves=True,
+        simplify_move_markup=True,
+        move_similarity_threshold=0.7,
+        move_minimum_word_count=2,
+        detect_format_changes=False,
+        conflate_spaces=False,
+        date_time="2025-01-01T00:00:00Z",
+    )
+    assert "--author=Author" in cmd
+    assert "--case-insensitive" in cmd
+    assert "--detect-moves" in cmd
+    assert "--simplify-move-markup" in cmd
+    assert "--no-detect-format-changes" in cmd
+    assert "--no-conflate-spaces" in cmd
+    assert "--detail-threshold=0.5" in cmd
+    assert "--move-similarity-threshold=0.7" in cmd
+    assert "--move-minimum-word-count=2" in cmd
+    assert "--date-time=2025-01-01T00:00:00Z" in cmd
+
+
+def test_build_command_false_bools_not_added():
+    """Boolean flags that are False should not be added to the command."""
+    engine = DocxodusEngine()
+    cmd = engine._build_command(
+        "Author", "/tmp/orig.docx", "/tmp/mod.docx", "/tmp/out.docx",
+        detect_moves=False,
+        case_insensitive=False,
+    )
+    assert "--detect-moves" not in cmd
+    assert "--case-insensitive" not in cmd
+
+
+def test_build_command_negatable_true_not_added():
+    """Negatable flags that are True (default) should not add --no- flags."""
+    engine = DocxodusEngine()
+    cmd = engine._build_command(
+        "Author", "/tmp/orig.docx", "/tmp/mod.docx", "/tmp/out.docx",
+        detect_format_changes=True,
+        conflate_spaces=True,
+    )
+    assert "--no-detect-format-changes" not in cmd
+    assert "--no-conflate-spaces" not in cmd