Add pluggable comparison engine system with Docxodus support

This commit introduces a pluggable architecture for document comparison engines,
allowing users to choose between Open-Xml-PowerTools and Docxodus backends.

Key changes:
- Add abstract ComparisonEngine base class defining the engine interface
- Refactor XmlPowerToolsEngine to inherit from ComparisonEngine
- Add DocxodusEngine for the modern Docxodus backend (.NET 8.0)
- Create EngineRegistry for dynamic engine discovery and selection
- Add get_engine(), list_engines(), list_available_engines() functions
- Create Docxodus C# CLI project using Docxodus NuGet package
- Update build system to support building both engines
- Add comprehensive test suite (79 tests) covering:
  - Base class interface contracts
  - Engine implementations with mocking
  - Registry functionality
  - Package imports and API
  - Backward compatibility with run_redline() method

Breaking changes: None - maintains full backward compatibility

Usage:
  from python_redlines import get_engine
  engine = get_engine()  # default: openxml-powertools
  engine = get_engine('docxodus')  # use Docxodus
  redline, _, _ = engine.compare(author, original, modified)

Author: claude

build_differ.py

@@ -1,7 +1,41 @@
+"""
+Build script for compiling comparison engine binaries.
+
+This script builds self-contained .NET executables for multiple platforms
+for both the Open-Xml-PowerTools and Docxodus comparison engines.
+"""
+
 import subprocess
 import os
+import sys
 import tarfile
 import zipfile
+import argparse
+
+
+# Engine configurations
+ENGINES = {
+    'openxml-powertools': {
+        'csproj_path': './csproj',
+        'binary_name': 'redlines',
+        'dist_subdir': 'openxml-powertools',
+    },
+    'docxodus': {
+        'csproj_path': './csproj-docxodus',
+        'binary_name': 'redline',
+        'dist_subdir': 'docxodus',
+    },
+}
+
+# Platform configurations
+PLATFORMS = [
+    {'rid': 'linux-x64', 'archive_ext': '.tar.gz'},
+    {'rid': 'linux-arm64', 'archive_ext': '.tar.gz'},
+    {'rid': 'win-x64', 'archive_ext': '.zip'},
+    {'rid': 'win-arm64', 'archive_ext': '.zip'},
+    {'rid': 'osx-x64', 'archive_ext': '.tar.gz'},
+    {'rid': 'osx-arm64', 'archive_ext': '.tar.gz'},
+]
 
 
 def get_version():
@@ -14,95 +48,160 @@ def get_version():
     return about['__version__']
 
 
-def run_command(command):
+def run_command(command, check=True):
     """
     Runs a shell command and prints its output.
+    Returns True if successful, False otherwise.
     """
-    process = subprocess.Popen(command, shell=True, stdout=subprocess.PIPE, stderr=subprocess.STDOUT)
+    print(f"Running: {command}")
+    process = subprocess.Popen(
+        command,
+        shell=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT
+    )
+    output_lines = []
     for line in process.stdout:
-        print(line.decode().strip())
+        decoded = line.decode().strip()
+        print(decoded)
+        output_lines.append(decoded)
+
+    process.wait()
+    if check and process.returncode != 0:
+        print(f"Command failed with return code {process.returncode}")
+        return False
+    return True
 
 
 def compress_files(source_dir, target_file):
     """
     Compresses files in the specified directory into a tar.gz or zip file.
     """
+    print(f"Compressing {source_dir} to {target_file}")
     if target_file.endswith('.tar.gz'):
         with tarfile.open(target_file, "w:gz") as tar:
             tar.add(source_dir, arcname=os.path.basename(source_dir))
     elif target_file.endswith('.zip'):
         with zipfile.ZipFile(target_file, 'w', zipfile.ZIP_DEFLATED) as zipf:
             for root, dirs, files in os.walk(source_dir):
                 for file in files:
-                    zipf.write(os.path.join(root, file),
-                               os.path.relpath(os.path.join(root, file),
-                                               os.path.join(source_dir, '..')))
+                    file_path = os.path.join(root, file)
+                    arcname = os.path.relpath(file_path, os.path.dirname(source_dir))
+                    zipf.write(file_path, arcname)
 
 
 def cleanup_old_builds(dist_dir, current_version):
     """
     Deletes any build files ending in .zip or .tar.gz in the dist_dir with a different version tag.
     """
+    if not os.path.exists(dist_dir):
+        return
+
     for file in os.listdir(dist_dir):
-        if not file.endswith((f'{current_version}.zip', f'{current_version}.tar.gz', '.gitignore')):
+        if file.endswith(('.zip', '.tar.gz')) and current_version not in file:
             file_path = os.path.join(dist_dir, file)
             os.remove(file_path)
             print(f"Deleted old build file: {file}")
 
 
-def main():
-    version = get_version()
-    print(f"Version: {version}")
-
-    dist_dir = "./src/python_redlines/dist/"
+def build_engine(engine_name, engine_config, version, platforms=None):
+    """
+    Build binaries for a specific engine.
 
-    # Build for Linux x64
-    print("Building for Linux x64...")
-    run_command('dotnet publish ./csproj -c Release -r linux-x64 --self-contained')
+    Args:
+        engine_name: Name of the engine
+        engine_config: Configuration dict for the engine
+        version: Version string
+        platforms: Optional list of platforms to build (default: all)
+    """
+    csproj_path = engine_config['csproj_path']
+    binary_name = engine_config['binary_name']
+    dist_subdir = engine_config['dist_subdir']
 
-    # Build for Linux ARM64
-    print("Building for Linux ARM64...")
-    run_command('dotnet publish ./csproj -c Release -r linux-arm64 --self-contained')
+    dist_dir = f"./src/python_redlines/dist/{dist_subdir}/"
 
-    # Build for Windows x64
-    print("Building for Windows x64...")
-    run_command('dotnet publish ./csproj -c Release -r win-x64 --self-contained')
+    # Ensure dist directory exists
+    os.makedirs(dist_dir, exist_ok=True)
 
-    # Build for Windows ARM64
-    print("Building for Windows ARM64...")
-    run_command('dotnet publish ./csproj -c Release -r win-arm64 --self-contained')
+    platforms_to_build = platforms or PLATFORMS
 
-    # Build for macOS x64
-    print("Building for macOS x64...")
-    run_command('dotnet publish ./csproj -c Release -r osx-x64 --self-contained')
+    print(f"\n{'='*60}")
+    print(f"Building {engine_name} engine")
+    print(f"{'='*60}\n")
 
-    # Build for macOS ARM64
-    print("Building for macOS ARM64...")
-    run_command('dotnet publish ./csproj -c Release -r osx-arm64 --self-contained')
+    for platform_config in platforms_to_build:
+        rid = platform_config['rid']
+        archive_ext = platform_config['archive_ext']
 
-    # Compress the Linux x64 build
-    linux_x64_build_dir = './csproj/bin/Release/net8.0/linux-x64'
-    compress_files(linux_x64_build_dir, f"{dist_dir}/linux-x64-{version}.tar.gz")
+        print(f"\nBuilding for {rid}...")
 
-    # Compress the Linux ARM64 build
-    linux_arm64_build_dir = './csproj/bin/Release/net8.0/linux-arm64'
-    compress_files(linux_arm64_build_dir, f"{dist_dir}/linux-arm64-{version}.tar.gz")
+        # Build the binary
+        cmd = f'dotnet publish {csproj_path} -c Release -r {rid} --self-contained'
+        if not run_command(cmd, check=False):
+            print(f"Warning: Build failed for {rid}")
+            continue
 
-    # Compress the Windows x64 build
-    windows_build_dir = './csproj/bin/Release/net8.0/win-x64'
-    compress_files(windows_build_dir, f"{dist_dir}/win-x64-{version}.zip")
+        # Determine build output directory
+        build_dir = f'{csproj_path}/bin/Release/net8.0/{rid}'
 
-    # Compress the macOS x64 build
-    macos_x64_build_dir = './csproj/bin/Release/net8.0/osx-x64'
-    compress_files(macos_x64_build_dir, f"{dist_dir}/osx-x64-{version}.tar.gz")
+        # Check if build directory exists
+        if not os.path.exists(build_dir):
+            print(f"Warning: Build directory not found: {build_dir}")
+            continue
 
-    # Compress the macOS ARM64 build
-    macos_arm64_build_dir = './csproj/bin/Release/net8.0/osx-arm64'
-    compress_files(macos_arm64_build_dir, f"{dist_dir}/osx-arm64-{version}.tar.gz")
+        # Compress to archive
+        archive_name = f"{rid}-{version}{archive_ext}"
+        archive_path = os.path.join(dist_dir, archive_name)
+        compress_files(build_dir, archive_path)
+        print(f"Created: {archive_path}")
 
+    # Cleanup old builds
     cleanup_old_builds(dist_dir, version)
 
-    print("Build and compression complete.")
+    print(f"\n{engine_name} build complete.")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Build comparison engine binaries for multiple platforms.'
+    )
+    parser.add_argument(
+        '--engine',
+        choices=['all'] + list(ENGINES.keys()),
+        default='all',
+        help='Which engine to build (default: all)'
+    )
+    parser.add_argument(
+        '--platform',
+        choices=['all'] + [p['rid'] for p in PLATFORMS],
+        default='all',
+        help='Which platform to build for (default: all)'
+    )
+
+    args = parser.parse_args()
+
+    version = get_version()
+    print(f"Version: {version}")
+
+    # Determine which platforms to build
+    if args.platform == 'all':
+        platforms = PLATFORMS
+    else:
+        platforms = [p for p in PLATFORMS if p['rid'] == args.platform]
+
+    # Determine which engines to build
+    if args.engine == 'all':
+        engines_to_build = ENGINES.items()
+    else:
+        engines_to_build = [(args.engine, ENGINES[args.engine])]
+
+    # Build each engine
+    for engine_name, engine_config in engines_to_build:
+        build_engine(engine_name, engine_config, version, platforms)
+
+    print("\n" + "="*60)
+    print("All builds complete.")
+    print("="*60)
 
 
 if __name__ == "__main__":

csproj-docxodus/Program.cs

@@ -0,0 +1,73 @@
+using System;
+using System.IO;
+using Docxodus;
+using DocumentFormat.OpenXml.Packaging;
+
+class Program
+{
+    static int Main(string[] args)
+    {
+        // Parse arguments: <original> <modified> <output> [--author=<name>]
+        if (args.Length < 3)
+        {
+            Console.WriteLine("Usage: redline <original.docx> <modified.docx> <output.docx> [--author=<name>]");
+            return 1;
+        }
+
+        string originalFilePath = args[0];
+        string modifiedFilePath = args[1];
+        string outputFilePath = args[2];
+        string authorTag = "Redline";
+
+        // Parse optional --author flag
+        for (int i = 3; i < args.Length; i++)
+        {
+            if (args[i].StartsWith("--author="))
+            {
+                authorTag = args[i].Substring("--author=".Length);
+            }
+        }
+
+        if (!File.Exists(originalFilePath))
+        {
+            Console.Error.WriteLine($"Error: Original file does not exist: {originalFilePath}");
+            return 1;
+        }
+
+        if (!File.Exists(modifiedFilePath))
+        {
+            Console.Error.WriteLine($"Error: Modified file does not exist: {modifiedFilePath}");
+            return 1;
+        }
+
+        try
+        {
+            var originalBytes = File.ReadAllBytes(originalFilePath);
+            var modifiedBytes = File.ReadAllBytes(modifiedFilePath);
+            var originalDocument = new WmlDocument(originalFilePath, originalBytes);
+            var modifiedDocument = new WmlDocument(modifiedFilePath, modifiedBytes);
+
+            var comparisonSettings = new WmlComparerSettings
+            {
+                AuthorForRevisions = authorTag,
+                DetailThreshold = 0
+            };
+
+            var comparisonResults = WmlComparer.Compare(originalDocument, modifiedDocument, comparisonSettings);
+            var revisions = WmlComparer.GetRevisions(comparisonResults, comparisonSettings);
+
+            // Output results
+            Console.WriteLine($"Revisions found: {revisions.Count}");
+
+            File.WriteAllBytes(outputFilePath, comparisonResults.DocumentByteArray);
+            return 0;
+        }
+        catch (Exception ex)
+        {
+            Console.Error.WriteLine($"Error: {ex.Message}");
+            Console.Error.WriteLine("Detailed Stack Trace:");
+            Console.Error.WriteLine(ex.StackTrace);
+            return 1;
+        }
+    }
+}

csproj-docxodus/redline.csproj

@@ -0,0 +1,15 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <OutputType>Exe</OutputType>
+    <TargetFramework>net8.0</TargetFramework>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <Nullable>enable</Nullable>
+    <AssemblyName>redline</AssemblyName>
+  </PropertyGroup>
+
+  <ItemGroup>
+    <PackageReference Include="Docxodus" Version="5.4.1" />
+  </ItemGroup>
+
+</Project>

hatch_run_build_hook.py

@@ -1,9 +1,46 @@
+"""
+Hatch build hook for building comparison engine binaries.
+
+This hook runs during the package build process to compile the
+.NET binaries for all supported comparison engines and platforms.
+"""
+
+import os
 import subprocess
 from hatchling.builders.hooks.plugin.interface import BuildHookInterface
 
+
 class HatchRunBuildHook(BuildHookInterface):
     PLUGIN_NAME = 'hatch-run-build'
 
     def initialize(self, version, build_data):
-        # Run the 'hatch run build' command
-        subprocess.run(["python", "-m", "build_differ"], check=True)
+        """
+        Initialize the build hook by compiling engine binaries.
+
+        This runs the build_differ.py script which compiles self-contained
+        .NET executables for all engines and platforms.
+        """
+        # Check if we should skip the build (useful for development)
+        if os.environ.get('SKIP_BINARY_BUILD', '').lower() in ('1', 'true', 'yes'):
+            print("Skipping binary build (SKIP_BINARY_BUILD is set)")
+            return
+
+        # Run the build script
+        print("Building comparison engine binaries...")
+        try:
+            result = subprocess.run(
+                ["python", "-m", "build_differ"],
+                check=True,
+                capture_output=True,
+                text=True
+            )
+            if result.stdout:
+                print(result.stdout)
+        except subprocess.CalledProcessError as e:
+            print(f"Warning: Binary build failed: {e}")
+            if e.stdout:
+                print(f"stdout: {e.stdout}")
+            if e.stderr:
+                print(f"stderr: {e.stderr}")
+            # Don't fail the build - binaries might already exist
+            # or the user might be installing on a platform we don't build for