docs(migration): map the Bash tests to Rust coverage (Phase 3)

Record the test-to-coverage map, mark Phase 3 verified, and drop the Bash
installer from the contributor docs that are not under docs/.
This commit is contained in:
Phoebus 2026-09-20 03:57:22 -07:00
parent 875278b9a9
commit fbffa5ca8f
3 changed files with 37 additions and 31 deletions

View file

@ -65,13 +65,7 @@ These are not preferences. Do not violate them, even to make a test pass.
AGENTS.md this file (read first) AGENTS.md this file (read first)
README.md short project overview README.md short project overview
docs/ objectives, roadmap, status, architecture, process docs/ objectives, roadmap, status, architecture, process
installer/ proven Bash installer (reference / fallback) installer/tests/vm/ disposable UEFI VM harness (static Rust binary)
bin/ai-installer entry point
lib/ deterministic backend modules
tui/ dialog/whiptail UI
config/ defaults, example config, OpenCode manifest
tests/ unit suite + tests/vm/ disposable-VM harness
doc/ environment findings and VM boot verification
installer-rs/ production Rust installer installer-rs/ production Rust installer
crates/phoebus-core types, validation, plan, policy, target-root safety crates/phoebus-core types, validation, plan, policy, target-root safety
crates/phoebus-executor command layer, storage, Portage, boot, snapshots, ... crates/phoebus-executor command layer, storage, Portage, boot, snapshots, ...
@ -113,13 +107,6 @@ when the next engineering step is clear.
## 5. Build and test gates ## 5. Build and test gates
Bash installer (reference):
```sh
installer/tests/run_tests.sh # unit/regression assertions
shellcheck -S warning installer/bin/ai-installer installer/lib/*.sh installer/tui/*.sh
```
Rust installer (production): Rust installer (production):
```sh ```sh
@ -138,8 +125,8 @@ RUSTFLAGS="-C target-feature=+crt-static" \
cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu cargo build --release -p phoebus-installer --target x86_64-unknown-linux-gnu
``` ```
Both test suites must pass before a commit. The pre-commit hook runs the fast The Rust suite must pass before a commit. The pre-commit hook runs a secret scan
Bash suite and a secret scan; see `docs/GIT-WORKFLOW.md`. and an optional Rust suite; see `docs/GIT-WORKFLOW.md`.
--- ---
@ -165,9 +152,9 @@ never `sh -c`; every command goes through `phoebus-executor::Exec`; every
target write goes through `TargetRoot`; destructive functions require a target write goes through `TargetRoot`; destructive functions require a
`DestructiveAuthorization` token. `DestructiveAuthorization` token.
Bash (while it exists): `shellcheck` clean; no `local a="$1" b="$a"` (dynamic Bash (developer tooling only): `shellcheck` clean; no `local a="$1" b="$a"`
scoping bug class); no writes to host paths without the target root; quote (dynamic scoping bug class); no writes to host paths without the target root;
everything. quote everything.
Use `just`-style readability, not cleverness. Fewer lines is not the goal; Use `just`-style readability, not cleverness. Fewer lines is not the goal;
correctness, testability and observability are. correctness, testability and observability are.

View file

@ -31,10 +31,6 @@ The Gentoo LiveGUI ISO is a reference artifact and is **not** tracked by git.
## Build and test ## Build and test
```sh ```sh
# Bash reference
installer/tests/run_tests.sh
# Rust production installer
cd installer-rs cd installer-rs
cargo fmt --all -- --check cargo fmt --all -- --check
cargo clippy --workspace --all-targets cargo clippy --workspace --all-targets

View file

@ -328,7 +328,7 @@ exit gate has been run and recorded.
| 0 | Preserve and instrument | VERIFIED | tag `v0.1.0-bash-reference`; parity 1 passed; `cli_coverage` failed only on `--bootstrap-opencode` (`fb8bdfd`) | | 0 | Preserve and instrument | VERIFIED | tag `v0.1.0-bash-reference`; parity 1 passed; `cli_coverage` failed only on `--bootstrap-opencode` (`fb8bdfd`) |
| 1 | Close product gaps (opencode) | VERIFIED | `cargo test --workspace`: opencode 7 passed, `cli_coverage` 2 passed, clippy rc 0 (`4071c7d`) | | 1 | Close product gaps (opencode) | VERIFIED | `cargo test --workspace`: opencode 7 passed, `cli_coverage` 2 passed, clippy rc 0 (`4071c7d`) |
| 2 | VM harness on the Rust binary | VERIFIED | static-binary install `INSTALL-RC=0` + detached boot (systemd PID1, running, 0 failed units, LUKS, login) | | 2 | VM harness on the Rust binary | VERIFIED | static-binary install `INSTALL-RC=0` + detached boot (systemd PID1, running, 0 failed units, LUKS, login) |
| 3 | Retire the tests | TODO | | | 3 | Retire the tests | VERIFIED | `make test` green; `git grep "run_tests.sh\|ai-installer\|installer/lib"` outside docs/installer returns nothing (`875278b`) |
| 4 | Delete the Bash tree | TODO | | | 4 | Delete the Bash tree | TODO | |
| 5 | Developer tooling (optional) | TODO | | | 5 | Developer tooling (optional) | TODO | |
@ -351,11 +351,11 @@ exit gate has been run and recorded.
| 2.4 | VM install with Rust binary | VERIFIED | | serial log: `phoebus-installer 0.1.0`, `===INSTALL-RC=0===`, `NO_SECRET_LEAK`, `===POWEROFF===` (commit `54701bd`) | | 2.4 | VM install with Rust binary | VERIFIED | | serial log: `phoebus-installer 0.1.0`, `===INSTALL-RC=0===`, `NO_SECRET_LEAK`, `===POWEROFF===` (commit `54701bd`) |
| 2.5 | VM detached boot | VERIFIED | | `systemd-boot` -> LUKS unlock -> login -> `running`, `0 loaded units listed`, `enp0s2 10.0.2.15/24` (commit `54701bd`) | | 2.5 | VM detached boot | VERIFIED | | `systemd-boot` -> LUKS unlock -> login -> `running`, `0 loaded units listed`, `enp0s2 10.0.2.15/24` (commit `54701bd`) |
| 2.6 | Boot evidence recorded | VERIFIED | | `installer/doc/VM-BOOT-VERIFICATION.md` "Official harness on the static binary" (commit `54701bd`) | | 2.6 | Boot evidence recorded | VERIFIED | | `installer/doc/VM-BOOT-VERIFICATION.md` "Official harness on the static binary" (commit `54701bd`) |
| 3.1 | Bash-test coverage mapping | TODO | | | | 3.1 | Bash-test coverage mapping | VERIFIED | | map below; no Bash test lacks a Rust equivalent (`4c59a1f`) |
| 3.2 | Golden plan tests; remove `parity.rs` | TODO | | | | 3.2 | Golden plan tests; remove `parity.rs` | VERIFIED | | `cargo test -p phoebus-installer --test plan_golden` -> 3 passed; `parity.rs` deleted (`4c59a1f`) |
| 3.3 | CI updated | TODO | | | | 3.3 | CI updated | VERIFIED | | `.forgejo/workflows/ci.yml` -> fmt + clippy + test (`875278b`) |
| 3.4 | Pre-commit hook updated | TODO | | | | 3.4 | Pre-commit hook updated | VERIFIED | | Bash-suite block removed; image-size + secret scan kept (`875278b`) |
| 3.5 | `Makefile` updated | TODO | | | | 3.5 | `Makefile` updated | VERIFIED | | `test: test-rust`; `test-bash` removed (`875278b`) |
| 4.1 | Relocate `installer/doc` | TODO | | | | 4.1 | Relocate `installer/doc` | TODO | | |
| 4.2 | Delete Bash tree | TODO | | | | 4.2 | Delete Bash tree | TODO | | |
| 4.3 | Update all references | TODO | | | | 4.3 | Update all references | TODO | | |
@ -372,6 +372,27 @@ and 0600 API-credential storage (`ai_store_api_key`), and the
keyword-based offline explainer. These belong to the installer/TUI surface, not keyword-based offline explainer. These belong to the installer/TUI surface, not
`sys`; record as separate future work rather than silently dropping them. `sys`; record as separate future work rather than silently dropping them.
### Bash test → Rust coverage map (task 3.1)
Every `installer/tests/test_*.sh` maps to committed Rust coverage:
| Bash test | Behavior | Rust coverage |
| --------- | -------- | ------------- |
| `test_plan.sh` | plan facts, step order, subvolumes, preview | `phoebus-core::plan::tests::{sequence_matches_proven_order, render_contains_key_facts, destructive_preview_warns_loudly}`; `phoebus-installer/tests/plan_golden.rs` |
| `test_validation.sh` | hostname/user/tz/disk rules, protected disks, password strength | `phoebus-core::validate::tests::{hostname_rules, password_strength_levels, ...}`; `phoebus-core::disk::tests::{optical_live_media_is_protected, loop_and_dm_are_protected, mounted_is_protected}` |
| `test_pkgpolicy.sh` | compile-time lookup, policy/history/binhost decision | `phoebus-core::policy::tests::{balanced_compiles_cheap_and_binaries_expensive, source_first_always_compiles, binary_first_prefers_binary_but_falls_back, history_overrides_estimate}` |
| `test_state.sh` | config round-trip, secret redaction | `phoebus-core::config::tests::{legacy_config_parses_flat_keys, load_from_path_detects_legacy_format}`; `phoebus-core::secret` + `Redactor::tests::{redactor_scrubs_registered_values, redactor_handles_multiple_and_dedup}` |
| `test_ai.sh` | proposal parse/allowlist/validate; offline translator | `phoebus-ai::tests::{parses_and_applies_a_valid_proposal, unknown_action_fails_closed, invalid_value_rejects_whole_proposal}`; `phoebus-core::action::tests::{parses_typed_actions, rejects_shell_action, rejects_unknown_fields_and_bad_values}` |
| `test_opencode.sh` | manifest + checksum policy | `phoebus-executor::opencode::tests` (7 tests) |
| `test_safety.sh` | destructive gate, dry-run sandbox root | `phoebus-executor::auth` tests; `phoebus-executor::exec::tests::dry_run_does_not_execute`; `phoebus-core::target` tests |
| `test_install_dryrun.sh` | dry-run never writes the host root | `phoebus-executor::exec::tests::dry_run_does_not_execute`; `phoebus-installer` dry-run path |
| `test_btrfs_order.sh` | subvolumes created before `subvol=@` mount | `phoebus-executor::storage::tests::create_layout_creates_subvolumes_before_mounting_root` |
| `test_regressions.sh` | cmdline/install.conf/dracut/fstab order, TMPDIR, base pkgs, package.use, log scrub | `phoebus-executor::{kernel, boot, portage, storage}` tests (`cmdline_uses_rd_luks_name`, `install_conf_has_uki_generator_none`, `base_packages_include_storage_tools`); `phoebus-core::system::tests::fstab_mounts_all_subvolumes_including_swap`; `Redactor` log-scrub tests |
| `test_syntax.sh` | `bash -n` over the Bash tree | obsolete once the Bash tree is deleted; `cargo fmt`/`clippy`/compile replace it |
No Bash test exercises behavior that lacks a Rust equivalent. `test_syntax.sh`
is deleted with the Bash tree (Phase 4).
--- ---
## 11. Session protocol ## 11. Session protocol
@ -420,9 +441,11 @@ detail.
- `YYYY-MM-DD` — (agent/session) phase worked, tasks moved, verification run, - `YYYY-MM-DD` — (agent/session) phase worked, tasks moved, verification run,
blocker, commit hash. blocker, commit hash.
- `2026-09-20` — Phases 0–2. Tagged `v0.1.0-bash-reference`; baseline cleanup - `2026-09-20` — Phases 0–3. Tagged `v0.1.0-bash-reference`; baseline cleanup
(`ec88d65`); CLI-coverage gate (`fb8bdfd`); OpenCode executor + 7 tests and (`ec88d65`); CLI-coverage gate (`fb8bdfd`); OpenCode executor + 7 tests and
`--bootstrap-opencode` (`4071c7d`); harness moved to the static binary `--bootstrap-opencode` (`4071c7d`); harness moved to the static binary
(`f984b01`); full VM install `INSTALL-RC=0` + detached boot (systemd PID1, (`f984b01`); full VM install `INSTALL-RC=0` + detached boot (systemd PID1,
`running`, 0 failed units, LUKS, login) recorded in `running`, 0 failed units, LUKS, login) recorded in
`installer/doc/VM-BOOT-VERIFICATION.md`. No blockers. `installer/doc/VM-BOOT-VERIFICATION.md`; golden plan tests replace `parity.rs`
(`4c59a1f`); CI/hook/Makefile/scripts now gate on Rust only and `git grep` has
no dangling Bash reference (`875278b`). No blockers. Phase 4 next.