workutils/docs/superpowers/plans/2026-07-30-diff-engine-phase-5.md

Diff Engine Phase 5 Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Make CLI and JavaFX text comparison share one UI-independent line and character diff engine, then run expensive comparisons off the JavaFX thread.

Architecture: DiffEngine returns immutable line and character segment records without HTML or JavaFX dependencies. DiffPlugin delegates CLI comparison to it. DiffWindow renders those records and owns only presentation/navigation, with AsyncOperationController owning background execution.

Tech Stack: Java 17, JavaFX, JUnit 5, Maven.

Global Constraints

• Preserve current unified text output and HTML colors/navigation.
• DiffEngine must not import JavaFX, HTML generators, filesystem, or plugin classes.
• CLI and UI must use the same line-diff implementation.
• Capture text on the UI thread before background execution.
• Test first.

---

Task 1: Immutable line diff engine

Files:

• Create: src/main/java/com/example/workutils/biz/diff/domain/DiffEngine.java
• Test: src/test/java/com/example/workutils/biz/diff/domain/DiffEngineLineTest.java

Interfaces:

• Produces DiffResult compareLines(List<String> left, List<String> right).

• Produces immutable LineDiff, LineType, and counts.

• Test unchanged, added, removed, replacement, and input-list mutation.

• Observe focused test failure.

• Implement LCS line comparison.

• Confirm focused test passes.

Task 2: Structured character diff

Files:

• Modify: src/main/java/com/example/workutils/biz/diff/domain/DiffEngine.java
• Test: src/test/java/com/example/workutils/biz/diff/domain/DiffEngineCharacterTest.java

Interfaces:

• Produces CharacterDiff compareCharacters(String left, String right).

• Produces immutable CharacterSegment(Type, text) lists for both sides.

• Produces similarity(String left, String right).

• Test insertion, deletion, replacement, equality, HTML-like text, and similarity.

• Observe focused test failure.

• Implement character LCS and merged segments.

• Confirm focused test passes.

Task 3: Migrate CLI and renderer

Files:

• Modify: src/main/java/com/example/workutils/biz/diff/DiffPlugin.java

• Modify: src/main/java/com/example/workutils/biz/diff/DiffWindow.java

• Replace DiffPlugin nested algorithm types with DiffEngine.

• Replace Window line/character computation with engine records.

• Delete duplicate LCS methods from Plugin and Window.

• Run focused engine and existing tests.

Task 4: Background comparison state

Files:

• Modify: src/main/java/com/example/workutils/biz/diff/DiffWindow.java

• Add AsyncOperationController<DiffRender>.

• Bind compare button through LoadingButtonBinder.

• Add OperationStatusPane.

• Capture both text values before background execution.

• Apply HTML and counters only on success.

Task 5: Verification

• Run all tests and compile with JDK 17.
• Run git diff --check.
• Confirm no LCS matrix implementation remains in DiffPlugin or DiffWindow.
• Inspect empty, equal, and different short-text UI states without saving files.