Read --json envelopes in CLI tests through one tests/common/envelope module (#1089)

[Mikola Lysenko (mikolalysenko)]

LLM Description written by Claude Code:claude-opus-5-5

Refs #1089 (child 1: the shared JSON assertion helpers). Also refs #824 (one test-support module).

Summary

CLI tests now read the --json envelope through one module, tests/common/envelope.rs. It parses stdout, reads events[], finds an event, and collects error and warning codes. About 25 private copies of those readers in 24 test files are deleted. A ratchet test stops new copies from appearing.

Why

• The "assert on stable codes, not sentences" tracker (#1089, register row C32; the living document's Part 8, "Exact human-text assertions") needs one set of envelope readers before its children can rewrite sentence assertions as code checks. Child 1 (Assert error codes instead of sentences in remove's covgap suite and add shared JSON assertion helpers #1090) asked for these helpers. Its own file, remove/covgap_commands_remove.rs, is changed by Use tests/common's binary() and git_sha256 in 40 more CLI tests (#824) #1258, so it moves in a later PR.
• Every suite has been hand-rolling the same readers, and the copies have drifted. Some panic on a missing events, others return empty. find_event takes either Option<&str> or a required code. events returns either Vec<(purl, action, errorCode)> or &Vec<Value>. There are five recursive "every code" walkers and six warning-code collectors.
• Leverage: B 0 · U 1 (Tracking: assert stable codes instead of human sentences in CLI tests, and fold the covgap suites #1089 children 2–6 assert through these helpers) · D ≈25 duplicate test helpers · S 0 · R L (tests only).

What changed

• New tests/common/envelope.rs, re-exported from common and includable on its own with #[path = "common/envelope.rs"] mod envelope;:
  • parse_json_envelope, json_string, envelope_error_code, envelope_error_message. These moved from common/mod.rs unchanged and are re-exported, so existing callers don't change.
  • events (strict), find_event(env, action, Option<code>), event_triples, event_codes (lenient), codes_in(warnings_array) and all_codes (recursive code/errorCode).
• Callers moved onto it, with their copies deleted:
  • covgap_commands_vendor, vendor_eject, vendor_partial_staging_e2e, apply/check_verifies_installed_tree and vendor_group_commit_e2e;
  • e2e_vendor_{bun,cargo,gem,golang,yarn_classic}_build;
  • e2e_sbt_{build,hosted,vendor,vendor_build}, e2e_scala_cli_vendor, e2e_sbt/agent and e2e_vex_lockfile/{golang,sbt_vendored};
  • e2e_gradle_agent_build, gradle_agent_cli, mode_migration_{bun,vlt}, covgap_commands_scan_hosted and coverage_fix_scan_hosted_dryrun_vendored.
• New cli/envelope_helper_copies.rs:
  • a ratchet that fails when a new top-level private reader appears. Files still listed are changed by open PRs, shared modules whose includers are, or readers with a rule of their own. A stale entry is not an error.
  • self-tests that run each former copy's shape through the shared readers on the inputs where the copies differed: strict vs lenient events, the golang Option find, absent triple fields, two chained warning arrays, non-string codes, and the order of errorCode vs code.

Deleted

git diff --stat origin/main: 28 files, +575/−462. All of it is test code; no production lines change. Of the additions, 109 are the shared module and 268 are the ratchet plus its self-tests. Without those, the migrated files are about −290 net.

Behavior

No production change. In the tests:

• events is now strict (it panics on a missing array) for the three callers that read it leniently. Every command envelope serializes events, and those suites pass.
• e2e_vendor_golang_build's three find_event(..).is_some() asserts now panic with the envelope, instead of a custom message, when the event is missing.
• Parse-failure panic texts now read "failed to parse JSON envelope".

Test evidence

• cargo clippy --workspace --all-features -- -D warnings: clean.
• cargo test -p socket-patch-cli --all-features --tests --no-run: every CLI test target compiles with no warnings, including the ignored e2e and docker binaries.
• Suites passed: cli 105 (with the new ratchet and self-tests), apply 119, vendor_eject 8, vendor_partial_staging_e2e 9, covgap_commands_scan_hosted 55, coverage_fix_scan_hosted_dryrun_vendored 9, gradle_agent_cli 52, vendor_group_commit_e2e 11, e2e_sbt_vendor 37, mode_migration_bun 33, mode_migration_vlt 26 (14 ignored), e2e_sbt_hosted 29, spawn_env_hygiene 12.
• covgap_commands_vendor: 52 passed, 3 failed. The 3 *_state_write_failure_* tests depend on chmod and fail the same way on main in this sandbox, because it runs as root; they pass in CI.

Risk

Low. The change is test-only and compiles across every test target. The e2e build suites that need real package managers (bun, cargo, gem, Go, yarn classic, sbt, scala-cli, Gradle) were compiled but not run here.

🤖 Generated with Claude Code

---

Note

Low Risk
Test-only refactor with no production code changes; behavior shifts are limited to stricter envelope helpers in migrated tests.

Overview
Centralizes CLI --json envelope parsing for tests in tests/common/envelope.rs (parse_json_envelope, events, find_event, event_triples, codes_in, all_codes, etc.) and re-exports the parse/error helpers from common/mod.rs.

~24 test files drop duplicated local readers and call the shared module instead (via common::envelope or #[path = "common/envelope.rs"]). cli/envelope_helper_copies.rs adds a ratchet that fails on new private envelope readers (with an allowlist for files still migrating) and self-tests that lock in former copy behavior (strict vs lenient events, warning chaining, etc.).

Test-only refactor for #1089; a few assertions now use stricter events / panic-on-miss find_event where envelopes always include events[].

^{Reviewed by Cursor Bugbot for commit 1ff215e. Configure here.}

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

BugBot review

---

Generated by Claude Code

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 1ff215e. Configure here.}

[Mikola Lysenko (mikolalysenko)]

[agent] gradle 8.14.3 / jdk 21 / vendor / windows-latest failed in e2e_vendor_jvm_build::gradle_multi_project_vendor_locked_offline_tamper_and_byte_exact_revert. The failure is a Gradle BUILD FAILED inside an artifact download (DefaultExternalResourceArtifactResolver.downloadByCoords). In the same leg, the other two Gradle cells passed.

I don't think this PR caused it. The PR changes only CLI test helpers and doesn't touch e2e_vendor_jvm_build, any JVM fixture or any production code. The failure is in Gradle's own fetch, before any socket-patch assertion runs. No fix exists to port.

This session can't re-run the job (the rerun call returned 403). Please re-run the failed job once. If it fails again, it's a real failure and needs a look.

---

Generated by Claude Code

[Mikola Lysenko (mikolalysenko)]

Ready for review at 1ff215ec5.

• CI: every check on this head green. The one red job (gradle 8.14.3 / jdk 21 / vendor / windows-latest, a Gradle artifact-download failure in a test this PR doesn't touch) passed on re-run. Merges cleanly into current main (88d5c598, which now includes Use tests/common's binary() and git_sha256 in 40 more CLI tests (#824) #1258's test-helper move).
• Bugbot: reviewed this head, no new issues; no open review threads.
• Test-only change: CLI tests read --json envelopes through tests/common/envelope.
• Slack: not announced (this run's Slack connector has no send tool); the next run should retry.

---

Generated by Claude Code