Incrementally decouple DiffGraph analysis from HTML rendering

[avikalpg]

Context

Today wild diff combines two responsibilities:

1. analyse a Git diff and build DiffGraph data; and
2. generate a complete HTML document containing the current summary and Mermaid-based visualization.

The existing VS Code extension relies on that HTML output and displays it inside a Webview. This keeps the current experience simple, but couples every host platform to the CLI's presentation layer.

This issue tracks an incremental, behaviour-preserving migration toward a versioned JSON contract and a reusable web renderer. Each checkbox should be delivered as a contained change/PR rather than as one large rewrite.

Connected VS Code issue: WildestAI/wildest-vscode-ext#17

Target architecture

DiffGraph analysis
    -> versioned JSON contract
        -> shared web renderer
            -> standalone CLI HTML shell
            -> VS Code Webview shell
            -> future browser-extension shell

The JSON contract should be presentation-neutral. Hosts may reuse the shared rendering core while adding platform-specific behaviour.

Incremental delivery plan

• Audit everything consumed by the current HTML report (including AI summary and Mermaid representation) against schema-v2 JSON, and document any parity gaps.
• Add any missing presentation-neutral fields to a versioned schema with fixtures, validation, and backwards-compatibility tests.
• Refactor standalone HTML generation to consume the canonical JSON representation while preserving the current browser output and CLI behaviour.
• Extract/package the compiled web renderer so host integrations can reuse it without importing Python implementation details.
• Retain the legacy HTML path as an internal fallback for one release; remove it later in a separate, explicit change after parity is established.

Compatibility requirements

• Existing wild diff invocations must continue to work during the migration.
• Current HTML visual and functional behaviour should remain materially unchanged unless a difference is explicitly reviewed and accepted.
• JSON schema changes must be versioned and covered by representative golden fixtures.
• Standalone HTML must remain self-contained/offline-capable; it should not require the VS Code extension.
• CLI packaging/builds must include the renderer assets deterministically.

Acceptance criteria

• CLI analysis has one canonical structured representation.
• Both JSON output and standalone HTML are generated from that representation.
• Representative diffs produce equivalent summaries, nodes, edges, and interactions before and after the refactor.
• Tests cover schema compatibility and HTML rendering inputs.
• The connected VS Code migration can consume the contract without scraping or loading CLI-generated HTML.

[nia-sg-bot]

Product-direction review — 2026-08-01

Verdict: KEEP · P0

This is the right rendering/compatibility epic. Sequence it after the deterministic canonical producer: freeze golden v2 artifacts → make analysis return that artifact → adapt HTML → package a reusable renderer → migrate the extension with an explicit fallback/removal window. Add unknown-major rejection, offline/CSP, extension fixture, and asset-integrity acceptance tests.

This is a scope/alignment review, not an automatic closure decision. Items marked DISCUSS CLOSE should be resolved with maintainer context before closing.