72 lines
6.3 KiB
Markdown
72 lines
6.3 KiB
Markdown
|
# Failing Crates Repair Plan
|
|||
|
|
|
|||
|
|
## Goal
|
|||
|
|
|
|||
|
|
Make the bulk Linux and Windows test runners complete without platform-feature build failures, preserve compilation coverage for the existing egui visual examples, and report the exact names of failed crates instead of only a count.
|
|||
|
|
|
|||
|
|
## Confirmed Findings
|
|||
|
|
|
|||
|
|
- `hcie-blend` fails because its `eframe` dev-dependency disables defaults without enabling either Linux backend; `winit 0.30.13` therefore emits “platform ... not supported”.
|
|||
|
|
- The same manifest defect exists in `hcie-draw`, `hcie-filter`, `hcie-text`, and `hcie-vector`.
|
|||
|
|
- `hcie-brush-engine` succeeds because it enables `x11`; `hcie-io` enables both `x11` and `wayland`.
|
|||
|
|
- The root workspace already defines the intended cross-platform `eframe` configuration with `wayland` and `x11`.
|
|||
|
|
- `hcie-text/Cargo.toml` currently repeats `proptest` and `approx`, which is a duplicate-key manifest error and must be fixed before any Cargo validation.
|
|||
|
|
- The supplied terminal output proves one named failure (`hcie-blend`) and six failures in total. It does not expose all six names, so the prior six-name claim must not be treated as authoritative.
|
|||
|
|
- `run_all_tests.*` and `run_tests_categorized.*` only retain failure counts. Their `--no-4k` command also places `--skip` on the Cargo side instead of after Cargo’s `--` test-harness separator.
|
|||
|
|
|
|||
|
|
## Implementation Steps
|
|||
|
|
|
|||
|
|
1. **Restore a valid workspace manifest.**
|
|||
|
|
- Remove the duplicate `proptest` and `approx` entries from `hcie-text/Cargo.toml`.
|
|||
|
|
- Run `cargo metadata --no-deps` immediately; stop if any other manifest error remains.
|
|||
|
|
|
|||
|
|
2. **Centralize visual-example GUI dev-dependencies.**
|
|||
|
|
- In `hcie-blend`, `hcie-brush-engine`, `hcie-draw`, `hcie-filter`, `hcie-text`, `hcie-vector`, and `hcie-io`, replace crate-local `egui = "0.34"` and custom `eframe` feature lists with `egui = { workspace = true }` and `eframe = { workspace = true }` under `[dev-dependencies]`.
|
|||
|
|
- Preserve all non-GUI dev-dependencies and existing visual examples.
|
|||
|
|
- Do not add GUI dependencies to runtime `[dependencies]` and do not modify engine source files.
|
|||
|
|
- This intentionally reuses the root’s `default_fonts`, `glow`, `persistence`, `wayland`, and `x11` configuration so platform support cannot drift between crates.
|
|||
|
|
|
|||
|
|
3. **Verify feature resolution before compiling.**
|
|||
|
|
- Use `cargo tree -p <crate> -e features -i winit` for the five confirmed failing crates and the two known-good comparison crates.
|
|||
|
|
- Confirm Linux builds activate at least one backend and the standardized configuration activates both `winit/x11` and `winit/wayland`.
|
|||
|
|
|
|||
|
|
4. **Improve test-runner diagnostics in both platform versions.**
|
|||
|
|
- Update `run_all_tests.sh`, `run_all_tests.bat`, `run_tests_categorized.sh`, and `run_tests_categorized.bat` to append every failed crate name to a failure list and every skipped crate name to a skip list.
|
|||
|
|
- Print those lists in the final summary while preserving pass/fail/skip counts and non-zero exit status.
|
|||
|
|
- In shell scripts, use arrays for Cargo arguments rather than a space-split string.
|
|||
|
|
- Fix the 4K exclusion to invoke `cargo test -p hcie-engine-api -- --skip benchmark_4k_stroke_on_multilayer_document`; apply equivalent quoting and argument ordering in `.bat` files.
|
|||
|
|
- Keep default `cargo test -p <crate>` behavior so examples are compiled; do not hide the defect by globally switching to `--tests`.
|
|||
|
|
|
|||
|
|
5. **Run focused crate validation.**
|
|||
|
|
- Run `cargo check -p <crate> --examples` and `cargo test -p <crate>` for `hcie-blend`, `hcie-draw`, `hcie-filter`, `hcie-text`, and `hcie-vector`.
|
|||
|
|
- Re-run `hcie-brush-engine` and `hcie-io` to detect regressions from dependency centralization.
|
|||
|
|
- For `hcie-io`, distinguish build/test failures from missing external PSD fixtures; fixture-dependent early returns are not platform compilation failures.
|
|||
|
|
|
|||
|
|
6. **Identify and repair the sixth failure from evidence.**
|
|||
|
|
- Run the improved Linux bulk runner first with `--no-io --no-4k` for deterministic feedback.
|
|||
|
|
- Read the emitted failed-crate list. If a failure remains outside the five confirmed manifests, capture its first compiler/test error and fix that crate’s actual cause rather than assuming another `winit` defect.
|
|||
|
|
- Re-run only the remaining failed crate until green, then repeat the deterministic bulk run.
|
|||
|
|
|
|||
|
|
7. **Complete end-to-end validation.**
|
|||
|
|
- Run `./run_all_tests.sh --no-io --no-4k`; require zero failed crates and verify the summary names no failures.
|
|||
|
|
- Run `cargo test -p hcie-io` separately with the expected fixture set or record fixture skips distinctly.
|
|||
|
|
- Run the 4K engine test explicitly with the protected command from `AGENTS.md` rather than silently omitting performance coverage.
|
|||
|
|
- Validate `.bat` parity on Windows (or Windows CI): targeted five-crate tests, `run_all_tests.bat --no-io --no-4k`, correct failed-name reporting, and non-zero exit code on an intentional failing command.
|
|||
|
|
|
|||
|
|
## Risks And Guardrails
|
|||
|
|
|
|||
|
|
- Enabling `x11`/`wayland` compiles native backend support but does not launch windows during tests; headless execution remains safe because examples are only compiled.
|
|||
|
|
- Do not use cached success as proof. At least one validation pass should use a fresh dedicated target directory (`CARGO_TARGET_DIR=target/platform-test`) rather than deleting the shared target directory.
|
|||
|
|
- Do not alter locked engine logic or protected performance mechanisms; this repair is confined to manifests and test runners unless the newly identified sixth failure proves independent.
|
|||
|
|
- Do not relocate the visual examples in this repair. Removing all GUI dev-dependencies from engine crates would require a separate architecture migration into the GUI workspace.
|
|||
|
|
- The Linux environment cannot establish Windows batch correctness alone; Windows execution is a required validation gate, not an inferred result.
|
|||
|
|
|
|||
|
|
## Acceptance Criteria
|
|||
|
|
|
|||
|
|
- `cargo metadata --no-deps` succeeds with no duplicate manifest keys.
|
|||
|
|
- The five confirmed crates compile their examples and pass their tests on Linux.
|
|||
|
|
- The bulk runner reports failed crate names and exits zero when all selected crates pass.
|
|||
|
|
- `./run_all_tests.sh --no-io --no-4k` reports zero failed crates from a fresh target directory.
|
|||
|
|
- Windows `.bat` behavior matches Linux for argument handling, result lists, and exit status.
|
|||
|
|
- Any sixth failure is named and resolved from its own diagnostic output, not from dependency-based speculation.
|