backend-infra-engineer: Post v0.3.9-hotfix7 snapshot (build cleanup)

docs/internal/plans/comprehensive-test-and-cli-plan.md

@@ -0,0 +1,123 @@
+# Comprehensive Plan: E2E Testing & z3ed CLI Improvements
+
+This document outlines the design for ROM-dependent End-to-End (E2E) tests for `yaze` editors and improvements to the `z3ed` CLI tool.
+
+## 1. E2E Testing Design
+
+The goal is to ensure stability and correctness of major editors by simulating user actions and verifying the state of the ROM and application.
+
+### 1.1. Test Infrastructure
+
+We will extend the existing `RomDependentTestSuite` in `src/app/test/rom_dependent_test_suite.h` or create a new `EditorE2ETestSuite`.
+
+**Key Components:**
+- **Test Fixture:** A setup that loads a clean ROM (or a specific test ROM) before each test.
+- **Action Simulator:** Helper functions to simulate editor actions (e.g., `SelectTile`, `PlaceObject`, `Save`).
+- **State Verifier:** Helper functions to verify the ROM state matches expectations after actions.
+
+### 1.2. Overworld Editor Tests
+
+**Scope:**
+- **Draw Tile 16:** Select a tile from the blockset and place it on the map. Verify the map data reflects the change.
+- **Edit Tile 16:** Modify a Tile16 definition (e.g., change sub-tiles, flip, priority). Verify the Tile16 data is updated.
+- **Multi-select & Draw:** Select a range of tiles and draw them. Verify all tiles are placed correctly.
+- **Manipulate Entities:** Add, move, and delete sprites/exits/items. Verify their coordinates and properties.
+- **Change Properties:** Modify map properties (e.g., palette, music, message ID).
+- **Expanded Features:** Test features specific to ZSCustomOverworld (if applicable).
+
+**Implementation Strategy:**
+- Use `OverworldEditor` class directly or via a wrapper to invoke methods like `SetTile`, `UpdateEntity`.
+- Verify by inspecting `OverworldMap` data and `GameData`.
+
+### 1.3. Dungeon Editor Tests
+
+**Scope:**
+- **Object Manipulation:** Add, delete, move, and resize objects.
+- **Door Manipulation:** Change door types, toggle open/closed states.
+- **Items & Sprites:** Add/remove items (chests, pots) and sprites. Verify properties.
+- **Room Properties:** Change header settings (music, palette, floor).
+
+**Implementation Strategy:**
+- Use `DungeonEditor` and `Room` classes.
+- Simulate mouse/keyboard inputs if possible, or call logical methods directly.
+- Verify by reloading the room and checking object lists.
+
+### 1.4. Graphics & Palette Editor Tests
+
+**Scope:**
+- **Graphics:** Edit pixel data in a sprite sheet. Save and reload. Verify pixels are preserved and no corruption occurs.
+- **Palette:** Change color values. Save and reload. Verify colors are preserved.
+
+**Implementation Strategy:**
+- Modify `Bitmap` data directly or via editor methods.
+- Trigger `SaveGraphics` / `SavePalettes`.
+- Reload and compare byte-for-byte.
+
+### 1.5. Message Editor Tests
+
+**Scope:**
+- **Text Editing:** Modify dialogue text.
+- **Command Insertion:** Insert control codes (e.g., wait, speed change).
+- **Save/Reload:** Verify text and commands are preserved.
+
+**Implementation Strategy:**
+- Use `MessageEditor` backend.
+- Verify encoded text data in ROM.
+
+## 2. z3ed CLI Improvements
+
+The `z3ed` CLI is a vital tool for ROM hacking workflows. We will improve its "doctor" and "comparison" capabilities and general UX.
+
+### 2.1. Doctor Command Improvements (`z3ed doctor`)
+
+**Goal:** Provide deeper insights into ROM health and potential issues.
+
+**New Features:**
+- **Deep Scan:** Analyze all rooms, not just a sample (already exists via `--all`, but make it default or more prominent).
+- **Corruption Heuristics:** Check for common corruption patterns (e.g., invalid pointers, overlapping data).
+- **Expanded Feature Validation:** Verify integrity of expanded tables (Tile16, Tile32, Monologue).
+- **Fix Suggestions:** Where possible, offer specific commands or actions to fix issues (e.g., "Run `z3ed fix-checksum`").
+- **JSON Output:** Ensure comprehensive JSON output for CI/CD integration.
+
+### 2.2. Comparison Command Improvements (`z3ed compare`)
+
+**Goal:** Make it easier to track changes and spot unintended regressions.
+
+**New Features:**
+- **Smart Diff:** Ignore insignificant changes (e.g., checksum, timestamp) if requested.
+- **Visual Diff (Text):** Improved hex dump visualization of differences (side-by-side).
+- **Region Filtering:** Allow comparing only specific regions (e.g., "Overworld", "Dungeon", "Code").
+- **Summary Mode:** Show high-level summary of changed areas (e.g., "3 Rooms modified, 1 Overworld map modified").
+
+### 2.3. UX Improvements
+
+- **Progress Bars:** Add progress indicators for long-running operations (like full ROM scan).
+- **Interactive Mode:** For `doctor`, allow interactive fixing of simple issues.
+- **Better Help:** Improve help messages and examples.
+- **Colorized Output:** Enhance readability with color-coded status (Green=OK, Yellow=Warning, Red=Error).
+
+## 3. Implementation Roadmap
+
+1.  **Phase 1: Foundation & CLI**
+    - Refactor `z3ed` commands for better extensibility.
+    - Implement improved `doctor` and `compare` logic.
+    - Add UX enhancements (colors, progress).
+
+2.  **Phase 2: Editor Test Framework**
+    - Create `EditorTestBase` class.
+    - Implement helpers for ROM loading/resetting.
+
+3.  **Phase 3: Specific Editor Tests**
+    - Implement Overworld tests.
+    - Implement Dungeon tests.
+    - Implement Graphics/Palette/Message tests.
+
+4.  **Phase 4: Documentation & Integration**
+    - Update docs with usage guides.
+    - Integrate into CI pipeline.
+
+## 4. Verification Plan
+
+- **Unit Tests:** Verify individual command logic.
+- **Integration Tests:** Run `z3ed` against known good and bad ROMs.
+- **Manual Verification:** Use the improved CLI tools on real projects to verify utility.