REG-1909 Foundation 1

[sirdodger]

REG-1909 Foundation 1

Foundation PR for the upcoming rover contract preview and rover subgraph preview commands (two independent stacks, both rooted on this branch: REG-1909 Subgraph Preview 2a/3a, REG-1909 Contract Preview 2b/3b). Stacked on REG-1909 Error Fix 0, an unrelated bug fix that was split out of this PR at review request. (original large PR, for posterity and PR feedback comments.)

• crates/rover-client/src/shared/async_build_response.rs: AsyncBuildStatus, PreviewJobResponse — the async build-status/response shapes shared by both preview commands.
• crates/rover-client/src/shared/filter_config.rs: ContractFilterConfig — the include/exclude/hide-unreachable-types filter shared by both commands.
• crates/rover-client/src/shared/preview_poll.rs: require_variant/poll_preview_build, the generic async-preview polling helper built on the existing check-workflow poller (shared/check_workflow_poll.rs).
• crates/rover-client/.schema/schema.graphql: schema additions for the new async preview mutations/queries.

Nothing in this crate calls the new preview_poll helpers yet — the contract-preview and subgraph-preview operations that consume them land in the two stacks above.

Test plan

• cargo test -p rover-client
• cargo clippy --locked --workspace --all-features --all-targets
• cargo +nightly fmt --all -- --check

[x] A CHANGELOG.md entry is not needed for this PR

[apollo-librarian]

✅ Docs preview has no changes

The preview was not built because there were no changes.

Build ID: c87a6ea9770631888740796a
Build Logs: View logs

---

✅ AI Style Review — No Changes Detected

No MDX files were changed in this pull request.

Review Log: View detailed log

This review is AI-generated. Please use common sense when accepting these suggestions, as they may not always be accurate or appropriate for your specific context.

[claude]

Code review

Two findings.

1. Shallow assertion discards the field the function under test threads through

crates/rover-client/src/shared/preview_poll.rs#L36-L41

assert_that!(matches!(err, RoverClientError::GraphNotFound ..)).is_true() collapses the error to a boolean variant check and drops graph_ref — the one thing require_variant actually threads through. The test constructs a specific test-graph@test-variant ref, but would still pass if the implementation dropped it, defaulted it, or substituted a different ref.

CLAUDE.md → Testing Conventions:

When asserting with speculoos's assert_that!, assert on the full object or the full string (.is_equal_to(...) against a complete expected value), not just .is_ok()/.is_some()/.contains(...). A shallow assertion (result is Ok, string contains a substring) passes even when the rest of the value silently regresses

The sibling test just above (L28-L35) already uses the full-value form. Suggested replacement for line 40:

let RoverClientError::GraphNotFound {
    graph_ref: actual_graph_ref,
} = err
else {
    panic!("expected RoverClientError::GraphNotFound");
};
assert_that!(&actual_graph_ref).is_equal_to(&graph_ref);

2. No linked planning artifact in the PR description

The description references the ticket as a bare string (REG-1909) and links to the original large PR #3522, but a PR link is not an issue reference and the bare ticket ID is not a link to a planning doc. Per CLAUDE.md → Planning Prerequisites:

When reviewing a PR, check the description for a linked Confluence PRD/One-Pager or a referenced GitHub issue (e.g. Fixes followed by an issue number). Flag the PR if neither is present, unless the change is clearly trivial.

This adds new shared abstractions, new error variants, new schema types, and a new generic Tower retry policy, so it is not trivial. Adding the Confluence PRD/One-Pager URL for REG-1909 to the description closes this out.

---

Checked and clean: PollRetryPolicy deadline/retry semantics and the in-place Err rewrite on timeout, AsyncBuildStatus serde/Display agreement and is_terminal, the new RoverClientError variants wired into RoverErrorMetadata, schema additions (no duplicate type definitions, all union members resolve), and rover-tower dependency/feature wiring.

Posted as a top-level comment rather than an inline review comment — the inline-comment API was unavailable in this environment. Apologies for the placeholder text previously in this comment.