Skip to main content

code_system_graph_core/
pull_requests.rs

1//! Explicitly enabled, transport-independent pull-request inspection.
2//!
3//! Provider clients in this module only speak documented public REST contracts. They never
4//! perform network I/O themselves and never retain source patches or raw HTTP responses.
5
6use std::collections::{BTreeMap, BTreeSet};
7use std::fmt;
8use std::sync::{Arc, Mutex};
9use std::time::{Duration, Instant};
10
11use async_trait::async_trait;
12use schemars::JsonSchema;
13use serde::{Deserialize, Serialize};
14use serde_json::Value;
15use tokio_util::sync::CancellationToken;
16use url::Url;
17
18const REDACTED: &str = "[REDACTED]";
19const DEFAULT_MAX_OUTPUT_BYTES: usize = 2 * 1024 * 1024;
20const DEFAULT_MAX_ITEMS: usize = 500;
21const DEFAULT_MAX_PAGES: usize = 20;
22const MAX_SAME_ORIGIN_REDIRECTS: usize = 3;
23const MAX_PULL_REQUEST_LIST_LIMIT: usize = 100;
24
25/// Pull-request service understood by the public provider adapter.
26#[derive(
27    Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize, JsonSchema,
28)]
29#[serde(rename_all = "snake_case")]
30pub enum PullRequestProviderKind {
31    /// GitHub's public REST API.
32    GitHub,
33    /// Bitbucket Cloud's public REST API 2.0.
34    BitbucketCloud,
35    /// Bitbucket Data Center, represented for configuration compatibility but not implemented.
36    BitbucketDataCenter,
37}
38
39/// Stable provider coordinates for one pull request.
40#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
41pub struct PullRequestCoordinates {
42    /// Provider that owns the pull request.
43    pub provider: PullRequestProviderKind,
44    /// GitHub owner or Bitbucket workspace.
45    pub owner: String,
46    /// GitHub repository name or Bitbucket repository slug.
47    pub repository: String,
48    /// Provider-native pull-request number.
49    pub number: u64,
50}
51
52/// Secret bearer token whose debug representation is always redacted.
53#[derive(Clone, Default, PartialEq, Eq)]
54pub struct PrAuthToken(String);
55
56impl PrAuthToken {
57    /// Wraps a token without validating or persisting it.
58    #[must_use]
59    pub fn new(token: impl Into<String>) -> Self {
60        Self(token.into())
61    }
62
63    /// Exposes the token only to an injected transport implementation.
64    #[must_use]
65    pub fn expose_secret(&self) -> &str {
66        &self.0
67    }
68
69    fn is_empty(&self) -> bool {
70        self.0.is_empty()
71    }
72}
73
74impl fmt::Debug for PrAuthToken {
75    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
76        formatter.write_str("PrAuthToken([REDACTED])")
77    }
78}
79
80/// Explicit provider configuration and hard request bounds.
81#[derive(Clone, Serialize, Deserialize, JsonSchema)]
82pub struct PullRequestProviderConfig {
83    /// Provider contract selected for this client.
84    pub provider: PullRequestProviderKind,
85    /// Master opt-in switch. The default is `false`.
86    pub enabled: bool,
87    /// Provider API base URL.
88    pub api_base_url: String,
89    /// Exact allowed API base URLs.
90    pub api_base_url_allowlist: Vec<String>,
91    /// Allows plain HTTP only for loopback test servers.
92    pub allow_loopback_http: bool,
93    /// Ephemeral bearer token, excluded from serialization and schemas.
94    #[serde(skip)]
95    #[schemars(skip)]
96    pub auth_token: PrAuthToken,
97    /// Ephemeral Atlassian account email for Bitbucket API-token Basic authentication.
98    #[serde(skip)]
99    #[schemars(skip)]
100    pub basic_auth_username: Option<String>,
101    /// Per-request timeout in milliseconds.
102    pub request_timeout_ms: u64,
103    /// Maximum cumulative response bytes accepted by one inspection.
104    pub max_output_bytes: usize,
105    /// Maximum changed files, checks, or reviews retained per collection.
106    pub max_items: usize,
107    /// Maximum pages fetched per paginated endpoint.
108    pub max_pages: usize,
109    /// Structured result cache lifetime in seconds.
110    pub cache_ttl_seconds: u64,
111}
112
113impl fmt::Debug for PullRequestProviderConfig {
114    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
115        formatter
116            .debug_struct("PullRequestProviderConfig")
117            .field("provider", &self.provider)
118            .field("enabled", &self.enabled)
119            .field("api_base_url", &self.api_base_url)
120            .field("api_base_url_allowlist", &self.api_base_url_allowlist)
121            .field("allow_loopback_http", &self.allow_loopback_http)
122            .field("auth_token", &REDACTED)
123            .field(
124                "basic_auth_username",
125                &self.basic_auth_username.as_ref().map(|_| REDACTED),
126            )
127            .field("request_timeout_ms", &self.request_timeout_ms)
128            .field("max_output_bytes", &self.max_output_bytes)
129            .field("max_items", &self.max_items)
130            .field("max_pages", &self.max_pages)
131            .field("cache_ttl_seconds", &self.cache_ttl_seconds)
132            .finish()
133    }
134}
135
136impl Default for PullRequestProviderConfig {
137    fn default() -> Self {
138        Self {
139            provider: PullRequestProviderKind::GitHub,
140            enabled: false,
141            api_base_url: "https://api.github.com".to_owned(),
142            api_base_url_allowlist: vec!["https://api.github.com".to_owned()],
143            allow_loopback_http: false,
144            auth_token: PrAuthToken::default(),
145            basic_auth_username: None,
146            request_timeout_ms: 10_000,
147            max_output_bytes: DEFAULT_MAX_OUTPUT_BYTES,
148            max_items: DEFAULT_MAX_ITEMS,
149            max_pages: DEFAULT_MAX_PAGES,
150            cache_ttl_seconds: 60,
151        }
152    }
153}
154
155impl PullRequestProviderConfig {
156    /// Returns a disabled Bitbucket Cloud configuration with the public endpoint allowlisted.
157    #[must_use]
158    pub fn bitbucket_cloud() -> Self {
159        Self {
160            provider: PullRequestProviderKind::BitbucketCloud,
161            api_base_url: "https://api.bitbucket.org/2.0".to_owned(),
162            api_base_url_allowlist: vec!["https://api.bitbucket.org/2.0".to_owned()],
163            ..Self::default()
164        }
165    }
166
167    /// Validates URL policy and non-zero request bounds.
168    ///
169    /// # Errors
170    ///
171    /// Returns [`PullRequestError::InvalidConfiguration`] for an unsafe URL or empty bound.
172    pub fn validate(&self) -> Result<(), PullRequestError> {
173        if self.request_timeout_ms == 0
174            || self.max_output_bytes == 0
175            || self.max_items == 0
176            || self.max_pages == 0
177        {
178            return Err(PullRequestError::InvalidConfiguration(
179                "request bounds must be greater than zero".to_owned(),
180            ));
181        }
182        if self.basic_auth_username.as_ref().is_some_and(|username| {
183            username.trim().is_empty() || username.chars().any(char::is_control)
184        }) {
185            return Err(PullRequestError::InvalidConfiguration(
186                "Basic-auth username must be non-empty and control-free".to_owned(),
187            ));
188        }
189        let base = parse_base_url(&self.api_base_url)?;
190        if is_loopback(&base) && self.allow_loopback_http {
191            return Ok(());
192        }
193        if base.scheme() != "https" {
194            return Err(PullRequestError::InvalidConfiguration(
195                "provider API base URL must use HTTPS".to_owned(),
196            ));
197        }
198        let normalized = normalize_base_url(base);
199        let allowed = self
200            .api_base_url_allowlist
201            .iter()
202            .filter_map(|candidate| Url::parse(candidate).ok())
203            .any(|candidate| {
204                candidate.scheme() == "https" && normalize_base_url(candidate) == normalized
205            });
206        if !allowed {
207            return Err(PullRequestError::InvalidConfiguration(
208                "provider API base URL is not allowlisted".to_owned(),
209            ));
210        }
211        Ok(())
212    }
213}
214
215/// One opt-in inspection request.
216#[derive(Debug, Clone)]
217pub struct PullRequestInspectRequest {
218    /// Provider coordinates to inspect.
219    pub coordinates: PullRequestCoordinates,
220    /// Per-call confirmation that remote access is allowed.
221    pub consent_to_remote_access: bool,
222    /// Cooperative cancellation signal.
223    pub cancellation: CancellationToken,
224}
225
226/// Provider-native lifecycle filter for pull-request listings.
227#[derive(Debug, Clone, Copy, PartialEq, Eq, Default, Serialize, Deserialize, JsonSchema)]
228#[serde(rename_all = "snake_case")]
229pub enum PullRequestListState {
230    /// Return only pull requests that remain open.
231    Open,
232    /// Return provider-native closed pull requests, including merged pull requests.
233    Closed,
234    /// Return pull requests in every provider-native state.
235    #[default]
236    All,
237}
238
239/// One explicitly authorized request for a bounded pull-request list page.
240#[derive(Debug, Clone, Serialize, Deserialize, JsonSchema)]
241pub struct PullRequestListRequest {
242    /// Provider contract used for the request.
243    pub provider: PullRequestProviderKind,
244    /// GitHub owner or Bitbucket workspace.
245    pub owner: String,
246    /// GitHub repository name or Bitbucket repository slug.
247    pub repository: String,
248    /// Provider-native lifecycle filter.
249    #[serde(default)]
250    pub state: PullRequestListState,
251    /// Opaque positive page cursor returned by a previous list response.
252    #[serde(default)]
253    pub cursor: Option<String>,
254    /// Maximum number of summaries to return, from 1 through 100.
255    #[schemars(range(min = 1, max = 100))]
256    pub limit: usize,
257    /// Per-call confirmation that remote access is allowed.
258    pub consent_to_remote_access: bool,
259    /// Cooperative cancellation signal, excluded from serialized requests and schemas.
260    #[serde(skip, default)]
261    #[schemars(skip)]
262    pub cancellation: CancellationToken,
263}
264
265/// Source-free pull-request metadata returned by list operations.
266#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
267pub struct PullRequestSummary {
268    /// Stable provider coordinates.
269    pub coordinates: PullRequestCoordinates,
270    /// Pull-request title.
271    pub title: String,
272    /// Human-facing provider URL.
273    pub url: String,
274    /// Normalized lifecycle state.
275    pub state: PullRequestState,
276    /// Whether the provider marks the pull request as draft.
277    pub draft: bool,
278    /// Provider-native author identity.
279    pub author: String,
280    /// Merge destination branch.
281    pub base_branch: String,
282    /// Proposed branch name, without source content.
283    pub head_branch: String,
284    /// Provider creation timestamp retained as an RFC 3339 string.
285    pub created_at: String,
286    /// Provider update timestamp retained as an RFC 3339 string.
287    pub updated_at: String,
288}
289
290/// One bounded, deterministically ordered pull-request list page.
291#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
292pub struct PullRequestListPage {
293    /// Source-free summaries sorted by provider-native pull-request number.
294    pub items: Vec<PullRequestSummary>,
295    /// Cursor for the next provider page, or `None` when no next page was reported.
296    pub next_cursor: Option<String>,
297    /// Whether the provider reported another page.
298    pub has_more: bool,
299    /// Whether a configured item bound reduced the caller's requested page size.
300    pub truncated: bool,
301    /// Last observed provider rate-limit metadata.
302    pub rate_limit: PullRequestRateLimit,
303    /// Non-fatal truncation or compatibility warnings.
304    pub warnings: Vec<PullRequestWarning>,
305}
306
307/// Repository identity attached to a pull-request ref.
308#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
309pub struct PullRequestRepository {
310    /// Provider-native owner/name identity.
311    pub full_name: String,
312    /// Public repository URL when supplied by the provider.
313    pub url: Option<String>,
314}
315
316/// Base or head ref metadata.
317#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
318pub struct PullRequestRef {
319    /// Branch or named ref.
320    pub name: String,
321    /// Commit SHA or hash.
322    pub sha: String,
323    /// Repository containing the ref.
324    pub repository: PullRequestRepository,
325}
326
327/// Provider-neutral pull-request state.
328#[derive(
329    Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize, JsonSchema,
330)]
331#[serde(rename_all = "snake_case")]
332pub enum PullRequestState {
333    /// Open for work or review.
334    Open,
335    /// Closed without a confirmed merge.
336    Closed,
337    /// Merged.
338    Merged,
339    /// Provider returned an unrecognized state.
340    Unknown,
341}
342
343/// Common pull-request metadata.
344#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
345pub struct PullRequestMetadata {
346    /// Provider-native identifier.
347    pub id: String,
348    /// Pull-request title.
349    pub title: String,
350    /// Human-facing URL.
351    pub url: String,
352    /// Normalized lifecycle state.
353    pub state: PullRequestState,
354    /// Whether the provider marks the pull request as draft.
355    pub draft: bool,
356    /// Provider-native author identity.
357    pub author: String,
358    /// Merge destination.
359    pub base: PullRequestRef,
360    /// Proposed source.
361    pub head: PullRequestRef,
362    /// Provider timestamp, retained as its RFC 3339 string.
363    pub created_at: String,
364    /// Provider timestamp, retained as its RFC 3339 string.
365    pub updated_at: String,
366}
367
368/// Normalized changed-file status.
369#[derive(
370    Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize, JsonSchema,
371)]
372#[serde(rename_all = "snake_case")]
373pub enum ChangedFileStatus {
374    /// Newly added path.
375    Added,
376    /// Modified path.
377    Modified,
378    /// Removed path.
379    Removed,
380    /// Renamed path.
381    Renamed,
382    /// Copied path.
383    Copied,
384    /// Provider status was not recognized.
385    Unknown,
386}
387
388/// Source-free changed-file summary.
389#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
390pub struct PullRequestChangedFile {
391    /// Normalized provider status.
392    pub status: ChangedFileStatus,
393    /// Previous path for renames or deletions.
394    pub old_path: Option<String>,
395    /// Current path for additions, modifications, or renames.
396    pub new_path: Option<String>,
397    /// Added line count.
398    pub additions: u64,
399    /// Deleted line count.
400    pub deletions: u64,
401    /// Whether provider metadata identifies or strongly implies a binary file.
402    pub binary: bool,
403    /// Whether a provider patch was present but intentionally discarded.
404    pub patch_truncated: bool,
405}
406
407/// Normalized CI or check outcome.
408#[derive(
409    Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize, JsonSchema,
410)]
411#[serde(rename_all = "snake_case")]
412pub enum CheckState {
413    /// All reported checks completed successfully.
414    Success,
415    /// At least one check failed.
416    Failure,
417    /// Checks are queued or running.
418    Pending,
419    /// No usable status was reported.
420    Unknown,
421}
422
423/// One provider check or commit status.
424#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
425pub struct PullRequestCheck {
426    /// Check name or key.
427    pub name: String,
428    /// Normalized check state.
429    pub state: CheckState,
430    /// Provider details URL.
431    pub url: Option<String>,
432}
433
434/// Aggregate CI state and bounded checks.
435#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
436pub struct PullRequestCi {
437    /// Aggregate state.
438    pub state: CheckState,
439    /// Individual checks or statuses.
440    pub checks: Vec<PullRequestCheck>,
441}
442
443/// One review or participant decision.
444#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
445pub struct PullRequestReview {
446    /// Provider-native review or participant identifier.
447    pub id: String,
448    /// Reviewer identity.
449    pub author: String,
450    /// Provider review state.
451    pub state: String,
452    /// Submission timestamp when available.
453    pub submitted_at: Option<String>,
454}
455
456/// Aggregate review readiness.
457#[derive(
458    Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize, JsonSchema,
459)]
460#[serde(rename_all = "snake_case")]
461pub enum ReviewState {
462    /// At least one current approval and no current change request.
463    Approved,
464    /// A current review requests changes.
465    ChangesRequested,
466    /// Reviews exist but do not establish readiness.
467    Pending,
468    /// No usable review information was reported.
469    Unknown,
470}
471
472/// Aggregate approvals and bounded review decisions.
473#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
474pub struct PullRequestReviewSummary {
475    /// Aggregate review state.
476    pub state: ReviewState,
477    /// Number of current approving reviewers.
478    pub approvals: usize,
479    /// Reviews or participants retained under the item limit.
480    pub reviews: Vec<PullRequestReview>,
481}
482
483/// Provider rate-limit metadata.
484#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
485pub struct PullRequestRateLimit {
486    /// Request quota limit.
487    pub limit: Option<u64>,
488    /// Remaining requests.
489    pub remaining: Option<u64>,
490    /// Provider reset timestamp or duration string.
491    pub reset: Option<String>,
492    /// Retry delay in seconds supplied by `Retry-After`.
493    pub retry_after_seconds: Option<u64>,
494}
495
496/// Non-fatal provider degradation.
497#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
498pub struct PullRequestWarning {
499    /// Stable machine-readable warning code.
500    pub code: String,
501    /// Secret-free explanation.
502    pub message: String,
503}
504
505/// Complete source-free inspection result.
506#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
507pub struct PullRequestInspection {
508    /// Provider coordinates.
509    pub coordinates: PullRequestCoordinates,
510    /// Common metadata.
511    pub metadata: PullRequestMetadata,
512    /// Bounded changed-file summaries.
513    pub changed_files: Vec<PullRequestChangedFile>,
514    /// CI/check state.
515    pub ci: PullRequestCi,
516    /// Review/approval state.
517    pub review: PullRequestReviewSummary,
518    /// Last observed rate-limit metadata.
519    pub rate_limit: PullRequestRateLimit,
520    /// Non-fatal truncation or compatibility warnings.
521    pub warnings: Vec<PullRequestWarning>,
522    /// Deterministic fingerprint of metadata and changed-file summaries.
523    pub fingerprint: String,
524    /// Whether this result came directly from the structured cache.
525    pub from_cache: bool,
526}
527
528/// Bounded HTTP method set needed by provider adapters.
529#[derive(Debug, Clone, Copy, PartialEq, Eq)]
530pub enum PrHttpMethod {
531    /// HTTP GET.
532    Get,
533}
534
535/// Ephemeral provider authentication passed only to the HTTP transport.
536#[derive(Clone, Default)]
537pub enum PrHttpAuthentication {
538    /// Anonymous public API request.
539    #[default]
540    None,
541    /// OAuth or repository/project/workspace access token.
542    Bearer(PrAuthToken),
543    /// Atlassian account email and API token.
544    Basic {
545        /// Atlassian account email.
546        username: String,
547        /// Ephemeral API token used as the Basic-auth password.
548        token: PrAuthToken,
549    },
550}
551
552impl fmt::Debug for PrHttpAuthentication {
553    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
554        match self {
555            Self::None => formatter.write_str("PrHttpAuthentication::None"),
556            Self::Bearer(_) => formatter.write_str("PrHttpAuthentication::Bearer([REDACTED])"),
557            Self::Basic { .. } => formatter.write_str("PrHttpAuthentication::Basic([REDACTED])"),
558        }
559    }
560}
561
562/// HTTP request passed to an injected transport.
563#[derive(Clone)]
564pub struct PrHttpRequest {
565    /// Request method.
566    pub method: PrHttpMethod,
567    /// Fully validated provider URL.
568    pub url: String,
569    /// Non-secret request headers.
570    pub headers: BTreeMap<String, String>,
571    /// Ephemeral provider authentication sent separately from ordinary headers.
572    pub authentication: PrHttpAuthentication,
573    /// Maximum accepted response body size.
574    pub max_response_bytes: usize,
575    /// Request timeout.
576    pub timeout: Duration,
577    /// Cooperative cancellation signal.
578    pub cancellation: CancellationToken,
579}
580
581impl fmt::Debug for PrHttpRequest {
582    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
583        formatter
584            .debug_struct("PrHttpRequest")
585            .field("method", &self.method)
586            .field("url", &self.url)
587            .field("headers", &self.headers)
588            .field("authentication", &self.authentication)
589            .field("max_response_bytes", &self.max_response_bytes)
590            .field("timeout", &self.timeout)
591            .finish_non_exhaustive()
592    }
593}
594
595/// Bounded HTTP response returned by an injected transport.
596#[derive(Clone, PartialEq, Eq)]
597pub struct PrHttpResponse {
598    /// HTTP status code.
599    pub status: u16,
600    /// Response headers.
601    pub headers: BTreeMap<String, String>,
602    /// Response bytes, bounded by the request contract.
603    pub body: Vec<u8>,
604}
605
606impl fmt::Debug for PrHttpResponse {
607    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
608        formatter
609            .debug_struct("PrHttpResponse")
610            .field("status", &self.status)
611            .field("headers", &self.headers)
612            .field("body_bytes", &self.body.len())
613            .finish()
614    }
615}
616
617/// Secret-free transport failure.
618#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
619#[error("pull-request transport failed: {message}")]
620pub struct PrHttpTransportError {
621    /// Transport-supplied message, sanitized again by the provider.
622    pub message: String,
623}
624
625/// Injectable asynchronous HTTP boundary.
626#[allow(clippy::double_must_use)]
627#[async_trait]
628pub trait PrHttpTransport: Send + Sync {
629    /// Sends one bounded request.
630    ///
631    /// # Errors
632    ///
633    /// Returns [`PrHttpTransportError`] for transport failures.
634    async fn send(&self, request: PrHttpRequest) -> Result<PrHttpResponse, PrHttpTransportError>;
635}
636
637/// Production HTTPS transport with redirects disabled and bounded streaming responses.
638#[derive(Debug, Clone)]
639pub struct ReqwestPrHttpTransport {
640    client: reqwest::Client,
641}
642
643impl ReqwestPrHttpTransport {
644    /// Creates a reusable provider HTTP client.
645    ///
646    /// # Errors
647    ///
648    /// Returns [`PrHttpTransportError`] when the client cannot be constructed.
649    pub fn new() -> Result<Self, PrHttpTransportError> {
650        reqwest::Client::builder()
651            .redirect(reqwest::redirect::Policy::none())
652            .user_agent(concat!("code-system-graph/", env!("CARGO_PKG_VERSION")))
653            .build()
654            .map(|client| Self { client })
655            .map_err(|error| PrHttpTransportError {
656                message: error.to_string(),
657            })
658    }
659}
660
661#[async_trait]
662impl PrHttpTransport for ReqwestPrHttpTransport {
663    async fn send(&self, request: PrHttpRequest) -> Result<PrHttpResponse, PrHttpTransportError> {
664        if request.cancellation.is_cancelled() {
665            return Err(PrHttpTransportError {
666                message: "request was cancelled".to_owned(),
667            });
668        }
669        let mut builder = match request.method {
670            PrHttpMethod::Get => self.client.get(&request.url),
671        }
672        .timeout(request.timeout);
673        for (name, value) in &request.headers {
674            builder = builder.header(name, value);
675        }
676        match &request.authentication {
677            PrHttpAuthentication::None => {}
678            PrHttpAuthentication::Bearer(token) => {
679                if !token.is_empty() {
680                    builder = builder.bearer_auth(token.expose_secret());
681                }
682            }
683            PrHttpAuthentication::Basic { username, token } => {
684                builder = builder.basic_auth(username, Some(token.expose_secret()));
685            }
686        }
687        let mut response = tokio::select! {
688            () = request.cancellation.cancelled() => {
689                return Err(PrHttpTransportError {
690                    message: "request was cancelled".to_owned(),
691                });
692            }
693            result = builder.send() => result.map_err(|error| PrHttpTransportError {
694                message: error.to_string(),
695            })?,
696        };
697        if response
698            .content_length()
699            .is_some_and(|length| length > request.max_response_bytes as u64)
700        {
701            return Err(PrHttpTransportError {
702                message: "response exceeded the configured output limit".to_owned(),
703            });
704        }
705        let status = response.status().as_u16();
706        let headers = response
707            .headers()
708            .iter()
709            .filter_map(|(name, value)| {
710                value
711                    .to_str()
712                    .ok()
713                    .map(|value| (name.as_str().to_owned(), value.to_owned()))
714            })
715            .collect();
716        let mut body = Vec::new();
717        loop {
718            let chunk = tokio::select! {
719                () = request.cancellation.cancelled() => {
720                    return Err(PrHttpTransportError {
721                        message: "request was cancelled".to_owned(),
722                    });
723                }
724                result = response.chunk() => result.map_err(|error| PrHttpTransportError {
725                    message: error.to_string(),
726                })?,
727            };
728            let Some(chunk) = chunk else {
729                break;
730            };
731            if body.len().saturating_add(chunk.len()) > request.max_response_bytes {
732                return Err(PrHttpTransportError {
733                    message: "response exceeded the configured output limit".to_owned(),
734                });
735            }
736            body.extend_from_slice(&chunk);
737        }
738        Ok(PrHttpResponse {
739            status,
740            headers,
741            body,
742        })
743    }
744}
745
746/// Pull-request provider failure.
747#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
748pub enum PullRequestError {
749    /// Provider use was not explicitly enabled.
750    #[error("pull-request provider is disabled")]
751    Disabled,
752    /// The caller did not consent to remote access.
753    #[error("remote pull-request access requires explicit per-request consent")]
754    ConsentRequired,
755    /// Configuration violates URL or budget policy.
756    #[error("invalid pull-request provider configuration: {0}")]
757    InvalidConfiguration(String),
758    /// Request coordinates do not match the configured provider.
759    #[error("pull-request coordinates do not match the configured provider")]
760    ProviderMismatch,
761    /// The selected provider contract is represented but intentionally unsupported.
762    #[error("pull-request provider is not supported")]
763    UnsupportedProvider,
764    /// Operation was cancelled.
765    #[error("pull-request inspection was cancelled")]
766    Cancelled,
767    /// Provider request exceeded its timeout.
768    #[error("pull-request provider request timed out")]
769    Timeout,
770    /// Response exceeded the configured byte budget.
771    #[error("pull-request provider response exceeded the configured output limit")]
772    OutputLimitExceeded,
773    /// Provider requested caller-managed backoff.
774    #[error("pull-request provider rate limited the request")]
775    RateLimited {
776        /// HTTP response status.
777        status: u16,
778        /// Provider rate-limit metadata.
779        metadata: PullRequestRateLimit,
780    },
781    /// Provider returned an unsuccessful API response.
782    #[error("pull-request provider returned HTTP {status}: {message}")]
783    Api {
784        /// HTTP response status.
785        status: u16,
786        /// Bounded, token-redacted provider message.
787        message: String,
788    },
789    /// Provider returned malformed or contract-incompatible JSON.
790    #[error("malformed pull-request provider response: {0}")]
791    MalformedResponse(String),
792    /// Injected transport failed.
793    #[error("pull-request transport failed: {0}")]
794    Transport(String),
795    /// Internal cache mutex was poisoned.
796    #[error("pull-request cache is unavailable")]
797    CacheUnavailable,
798}
799
800/// Asynchronous provider interface.
801#[allow(clippy::double_must_use)]
802#[async_trait]
803pub trait PullRequestProvider: Send + Sync {
804    /// Returns the provider contract implemented by this client.
805    fn kind(&self) -> PullRequestProviderKind;
806
807    /// Inspects one pull request after checking both opt-in gates.
808    ///
809    /// # Errors
810    ///
811    /// Returns [`PullRequestError`] for policy, transport, API, cancellation, or parse failures.
812    async fn inspect(
813        &self,
814        request: PullRequestInspectRequest,
815    ) -> Result<PullRequestInspection, PullRequestError>;
816
817    /// Lists one bounded, source-free page after checking both opt-in gates.
818    ///
819    /// # Errors
820    ///
821    /// Returns [`PullRequestError`] for policy, bounds, transport, API, cancellation, or parse
822    /// failures.
823    async fn list(
824        &self,
825        request: PullRequestListRequest,
826    ) -> Result<PullRequestListPage, PullRequestError>;
827}
828
829#[derive(Clone)]
830struct CacheEntry {
831    inspection: PullRequestInspection,
832    etag: Option<String>,
833    expires_at: Instant,
834}
835
836struct ProviderCore {
837    config: PullRequestProviderConfig,
838    transport: Arc<dyn PrHttpTransport>,
839    cache: Mutex<BTreeMap<PullRequestCoordinatesKey, CacheEntry>>,
840}
841
842#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord)]
843struct PullRequestCoordinatesKey {
844    owner: String,
845    repository: String,
846    number: u64,
847}
848
849impl From<&PullRequestCoordinates> for PullRequestCoordinatesKey {
850    fn from(value: &PullRequestCoordinates) -> Self {
851        Self {
852            owner: value.owner.clone(),
853            repository: value.repository.clone(),
854            number: value.number,
855        }
856    }
857}
858
859impl ProviderCore {
860    fn new(
861        config: PullRequestProviderConfig,
862        expected: PullRequestProviderKind,
863        transport: Arc<dyn PrHttpTransport>,
864    ) -> Result<Self, PullRequestError> {
865        config.validate()?;
866        if config.provider != expected {
867            return Err(PullRequestError::ProviderMismatch);
868        }
869        Ok(Self {
870            config,
871            transport,
872            cache: Mutex::new(BTreeMap::new()),
873        })
874    }
875
876    fn authorize(
877        &self,
878        request: &PullRequestInspectRequest,
879        expected: PullRequestProviderKind,
880    ) -> Result<(), PullRequestError> {
881        if !self.config.enabled {
882            return Err(PullRequestError::Disabled);
883        }
884        if !request.consent_to_remote_access {
885            return Err(PullRequestError::ConsentRequired);
886        }
887        if request.coordinates.provider != expected {
888            return Err(PullRequestError::ProviderMismatch);
889        }
890        if request.cancellation.is_cancelled() {
891            return Err(PullRequestError::Cancelled);
892        }
893        Ok(())
894    }
895
896    fn authorize_list(
897        &self,
898        request: &PullRequestListRequest,
899        expected: PullRequestProviderKind,
900    ) -> Result<(), PullRequestError> {
901        if !self.config.enabled {
902            return Err(PullRequestError::Disabled);
903        }
904        if !request.consent_to_remote_access {
905            return Err(PullRequestError::ConsentRequired);
906        }
907        if request.provider == PullRequestProviderKind::BitbucketDataCenter {
908            return Err(PullRequestError::UnsupportedProvider);
909        }
910        if request.provider != expected {
911            return Err(PullRequestError::ProviderMismatch);
912        }
913        if request.cancellation.is_cancelled() {
914            return Err(PullRequestError::Cancelled);
915        }
916        validate_list_request(request)
917    }
918
919    fn authentication(&self) -> PrHttpAuthentication {
920        if self.config.auth_token.is_empty() {
921            PrHttpAuthentication::None
922        } else if let Some(username) = &self.config.basic_auth_username {
923            PrHttpAuthentication::Basic {
924                username: username.clone(),
925                token: self.config.auth_token.clone(),
926            }
927        } else {
928            PrHttpAuthentication::Bearer(self.config.auth_token.clone())
929        }
930    }
931
932    fn fresh_cache(
933        &self,
934        coordinates: &PullRequestCoordinates,
935    ) -> Result<Option<PullRequestInspection>, PullRequestError> {
936        let cache = self
937            .cache
938            .lock()
939            .map_err(|_| PullRequestError::CacheUnavailable)?;
940        Ok(cache
941            .get(&PullRequestCoordinatesKey::from(coordinates))
942            .filter(|entry| Instant::now() < entry.expires_at)
943            .map(|entry| {
944                let mut inspection = entry.inspection.clone();
945                inspection.from_cache = true;
946                inspection
947            }))
948    }
949
950    fn stale_cache(
951        &self,
952        coordinates: &PullRequestCoordinates,
953    ) -> Result<Option<CacheEntry>, PullRequestError> {
954        self.cache
955            .lock()
956            .map_err(|_| PullRequestError::CacheUnavailable)
957            .map(|cache| {
958                cache
959                    .get(&PullRequestCoordinatesKey::from(coordinates))
960                    .cloned()
961            })
962    }
963
964    fn store_cache(
965        &self,
966        coordinates: &PullRequestCoordinates,
967        inspection: &PullRequestInspection,
968        etag: Option<String>,
969    ) -> Result<(), PullRequestError> {
970        let mut cached = inspection.clone();
971        cached.from_cache = false;
972        let entry = CacheEntry {
973            inspection: cached,
974            etag,
975            expires_at: Instant::now() + Duration::from_secs(self.config.cache_ttl_seconds),
976        };
977        self.cache
978            .lock()
979            .map_err(|_| PullRequestError::CacheUnavailable)?
980            .insert(PullRequestCoordinatesKey::from(coordinates), entry);
981        Ok(())
982    }
983
984    async fn get_json(
985        &self,
986        url: Url,
987        etag: Option<&str>,
988        cancellation: &CancellationToken,
989        budget: &mut ResponseBudget,
990    ) -> Result<FetchJson, PullRequestError> {
991        let response = self
992            .send_json_request(url, etag, cancellation, budget)
993            .await?;
994        if response.status == 304 {
995            return Ok(FetchJson::NotModified);
996        }
997        let rate_limited = response.status == 429
998            || (response.status == 403
999                && (budget.rate_limit.remaining == Some(0)
1000                    || budget.rate_limit.retry_after_seconds.is_some()));
1001        if rate_limited {
1002            return Err(PullRequestError::RateLimited {
1003                status: response.status,
1004                metadata: budget.rate_limit.clone(),
1005            });
1006        }
1007        if !(200..300).contains(&response.status) {
1008            let message = api_error_message(&response.body, &self.config.auth_token);
1009            return Err(PullRequestError::Api {
1010                status: response.status,
1011                message,
1012            });
1013        }
1014        let value = serde_json::from_slice(&response.body)
1015            .map_err(|error| PullRequestError::MalformedResponse(error.to_string()))?;
1016        Ok(FetchJson::Value {
1017            value,
1018            etag: header(&response.headers, "etag").map(str::to_owned),
1019            headers: response.headers,
1020        })
1021    }
1022
1023    async fn send_json_request(
1024        &self,
1025        mut url: Url,
1026        etag: Option<&str>,
1027        cancellation: &CancellationToken,
1028        budget: &mut ResponseBudget,
1029    ) -> Result<PrHttpResponse, PullRequestError> {
1030        let mut redirects = 0;
1031        loop {
1032            if cancellation.is_cancelled() {
1033                return Err(PullRequestError::Cancelled);
1034            }
1035            let remaining = self
1036                .config
1037                .max_output_bytes
1038                .saturating_sub(budget.output_bytes);
1039            if remaining == 0 {
1040                return Err(PullRequestError::OutputLimitExceeded);
1041            }
1042            let mut headers = BTreeMap::from([
1043                ("accept".to_owned(), "application/json".to_owned()),
1044                ("user-agent".to_owned(), "code-system-graph".to_owned()),
1045            ]);
1046            if let Some(etag) = etag {
1047                headers.insert("if-none-match".to_owned(), etag.to_owned());
1048            }
1049            let transport_request = PrHttpRequest {
1050                method: PrHttpMethod::Get,
1051                url: url.to_string(),
1052                headers,
1053                authentication: self.authentication(),
1054                max_response_bytes: remaining,
1055                timeout: Duration::from_millis(self.config.request_timeout_ms),
1056                cancellation: cancellation.clone(),
1057            };
1058            let timeout = tokio::time::sleep(Duration::from_millis(self.config.request_timeout_ms));
1059            tokio::pin!(timeout);
1060            let response = tokio::select! {
1061                () = cancellation.cancelled() => return Err(PullRequestError::Cancelled),
1062                () = &mut timeout => return Err(PullRequestError::Timeout),
1063                result = self.transport.send(transport_request) => {
1064                    result.map_err(|error| {
1065                        PullRequestError::Transport(redact_message(
1066                            &error.message,
1067                            &self.config.auth_token,
1068                        ))
1069                    })?
1070                }
1071            };
1072            if response.body.len() > remaining {
1073                return Err(PullRequestError::OutputLimitExceeded);
1074            }
1075            budget.output_bytes += response.body.len();
1076            budget.rate_limit = rate_limit_from_headers(&response.headers);
1077            if matches!(response.status, 301 | 302 | 303 | 307 | 308) {
1078                if redirects >= MAX_SAME_ORIGIN_REDIRECTS {
1079                    return Err(PullRequestError::Api {
1080                        status: response.status,
1081                        message: "provider redirect limit exceeded".to_owned(),
1082                    });
1083                }
1084                let location = header(&response.headers, "location").ok_or_else(|| {
1085                    PullRequestError::MalformedResponse(
1086                        "provider redirect omitted the location header".to_owned(),
1087                    )
1088                })?;
1089                let redirected = url.join(location).map_err(|_| {
1090                    PullRequestError::MalformedResponse(
1091                        "provider returned an invalid redirect URL".to_owned(),
1092                    )
1093                })?;
1094                if redirected.origin() != url.origin() {
1095                    return Err(PullRequestError::Api {
1096                        status: response.status,
1097                        message: "provider redirect crossed the configured origin".to_owned(),
1098                    });
1099                }
1100                url = redirected;
1101                redirects += 1;
1102                continue;
1103            }
1104            return Ok(response);
1105        }
1106    }
1107
1108    fn url(&self, segments: &[&str]) -> Result<Url, PullRequestError> {
1109        let mut url = parse_base_url(&self.config.api_base_url)?;
1110        {
1111            let mut path = url.path_segments_mut().map_err(|()| {
1112                PullRequestError::InvalidConfiguration(
1113                    "provider API base URL cannot be a base".to_owned(),
1114                )
1115            })?;
1116            path.pop_if_empty();
1117            path.extend(segments);
1118        }
1119        Ok(url)
1120    }
1121}
1122
1123#[derive(Default)]
1124struct ResponseBudget {
1125    output_bytes: usize,
1126    rate_limit: PullRequestRateLimit,
1127}
1128
1129enum FetchJson {
1130    NotModified,
1131    Value {
1132        value: Value,
1133        etag: Option<String>,
1134        headers: BTreeMap<String, String>,
1135    },
1136}
1137
1138/// GitHub public REST pull-request adapter.
1139pub struct GitHubProvider {
1140    core: ProviderCore,
1141}
1142
1143impl GitHubProvider {
1144    /// Creates a GitHub provider over an injected transport.
1145    ///
1146    /// # Errors
1147    ///
1148    /// Returns [`PullRequestError`] when configuration is invalid or selects another provider.
1149    pub fn new(
1150        config: PullRequestProviderConfig,
1151        transport: Arc<dyn PrHttpTransport>,
1152    ) -> Result<Self, PullRequestError> {
1153        ProviderCore::new(config, PullRequestProviderKind::GitHub, transport)
1154            .map(|core| Self { core })
1155    }
1156}
1157
1158#[async_trait]
1159impl PullRequestProvider for GitHubProvider {
1160    fn kind(&self) -> PullRequestProviderKind {
1161        PullRequestProviderKind::GitHub
1162    }
1163
1164    async fn inspect(
1165        &self,
1166        request: PullRequestInspectRequest,
1167    ) -> Result<PullRequestInspection, PullRequestError> {
1168        self.core
1169            .authorize(&request, PullRequestProviderKind::GitHub)?;
1170        if let Some(cached) = self.core.fresh_cache(&request.coordinates)? {
1171            return Ok(cached);
1172        }
1173        let stale = self.core.stale_cache(&request.coordinates)?;
1174        let mut budget = ResponseBudget::default();
1175        let number = request.coordinates.number.to_string();
1176        let metadata_url = self.core.url(&[
1177            "repos",
1178            &request.coordinates.owner,
1179            &request.coordinates.repository,
1180            "pulls",
1181            &number,
1182        ])?;
1183        let metadata_fetch = self
1184            .core
1185            .get_json(
1186                metadata_url,
1187                stale.as_ref().and_then(|entry| entry.etag.as_deref()),
1188                &request.cancellation,
1189                &mut budget,
1190            )
1191            .await?;
1192        let (metadata_json, etag) = match metadata_fetch {
1193            FetchJson::NotModified => {
1194                let mut cached = stale
1195                    .ok_or_else(|| {
1196                        PullRequestError::MalformedResponse(
1197                            "provider returned 304 without a cached representation".to_owned(),
1198                        )
1199                    })?
1200                    .inspection;
1201                cached.from_cache = true;
1202                self.core.store_cache(
1203                    &request.coordinates,
1204                    &cached,
1205                    self.core
1206                        .stale_cache(&request.coordinates)?
1207                        .and_then(|entry| entry.etag),
1208                )?;
1209                return Ok(cached);
1210            }
1211            FetchJson::Value { value, etag, .. } => (value, etag),
1212        };
1213        let metadata = parse_github_metadata(&metadata_json)?;
1214        let mut warnings = Vec::new();
1215        let files = self
1216            .github_files(&request, &number, &mut budget, &mut warnings)
1217            .await?;
1218        let checks = self
1219            .github_checks(&request, &metadata.head.sha, &mut budget, &mut warnings)
1220            .await?;
1221        let reviews = self
1222            .github_reviews(&request, &number, &mut budget, &mut warnings)
1223            .await?;
1224        let fingerprint = fingerprint(&metadata, &files)?;
1225        let inspection = PullRequestInspection {
1226            coordinates: request.coordinates.clone(),
1227            metadata,
1228            changed_files: files,
1229            ci: summarize_checks(checks),
1230            review: summarize_github_reviews(reviews),
1231            rate_limit: budget.rate_limit,
1232            warnings,
1233            fingerprint,
1234            from_cache: false,
1235        };
1236        self.core
1237            .store_cache(&request.coordinates, &inspection, etag)?;
1238        Ok(inspection)
1239    }
1240
1241    async fn list(
1242        &self,
1243        request: PullRequestListRequest,
1244    ) -> Result<PullRequestListPage, PullRequestError> {
1245        self.core
1246            .authorize_list(&request, PullRequestProviderKind::GitHub)?;
1247        let page_limit = request
1248            .limit
1249            .min(self.core.config.max_items)
1250            .min(MAX_PULL_REQUEST_LIST_LIMIT);
1251        let mut url = self
1252            .core
1253            .url(&["repos", &request.owner, &request.repository, "pulls"])?;
1254        let expected_path = url.path().to_owned();
1255        let page_limit_text = page_limit.to_string();
1256        {
1257            let mut query = url.query_pairs_mut();
1258            query
1259                .append_pair("state", github_list_state(request.state))
1260                .append_pair("per_page", &page_limit_text)
1261                .append_pair("sort", "created")
1262                .append_pair("direction", "asc");
1263            if let Some(cursor) = &request.cursor {
1264                query.append_pair("page", cursor);
1265            }
1266        }
1267        let mut budget = ResponseBudget::default();
1268        let fetch = self
1269            .core
1270            .get_json(url, None, &request.cancellation, &mut budget)
1271            .await?;
1272        let FetchJson::Value { value, headers, .. } = fetch else {
1273            return Err(PullRequestError::MalformedResponse(
1274                "unexpected 304 for uncached pull-request list".to_owned(),
1275            ));
1276        };
1277        let values = required_array(&value, "pull requests")?;
1278        if values.len() > page_limit {
1279            return Err(PullRequestError::MalformedResponse(
1280                "GitHub returned more pull requests than the requested page size".to_owned(),
1281            ));
1282        }
1283        let mut items = values
1284            .iter()
1285            .map(|value| parse_github_summary(value, &request.owner, &request.repository))
1286            .collect::<Result<Vec<_>, _>>()?;
1287        items.sort_by_key(|summary| summary.coordinates.number);
1288        let base = parse_base_url(&self.core.config.api_base_url)?;
1289        let next_cursor = github_next_url(&headers, &base)?
1290            .map(|next| pagination_cursor(&next, &base, &expected_path, "per_page"))
1291            .transpose()?;
1292        Ok(list_page(
1293            items,
1294            next_cursor,
1295            request.limit,
1296            page_limit,
1297            budget.rate_limit,
1298        ))
1299    }
1300}
1301
1302impl GitHubProvider {
1303    async fn github_files(
1304        &self,
1305        request: &PullRequestInspectRequest,
1306        number: &str,
1307        budget: &mut ResponseBudget,
1308        warnings: &mut Vec<PullRequestWarning>,
1309    ) -> Result<Vec<PullRequestChangedFile>, PullRequestError> {
1310        let initial = self.core.url(&[
1311            "repos",
1312            &request.coordinates.owner,
1313            &request.coordinates.repository,
1314            "pulls",
1315            number,
1316            "files",
1317        ])?;
1318        self.github_paginated(initial, &request.cancellation, budget, warnings, |value| {
1319            parse_github_file(value)
1320        })
1321        .await
1322    }
1323
1324    async fn github_checks(
1325        &self,
1326        request: &PullRequestInspectRequest,
1327        sha: &str,
1328        budget: &mut ResponseBudget,
1329        warnings: &mut Vec<PullRequestWarning>,
1330    ) -> Result<Vec<PullRequestCheck>, PullRequestError> {
1331        let initial = self.core.url(&[
1332            "repos",
1333            &request.coordinates.owner,
1334            &request.coordinates.repository,
1335            "commits",
1336            sha,
1337            "check-runs",
1338        ])?;
1339        self.github_paginated_key(
1340            initial,
1341            "check_runs",
1342            &request.cancellation,
1343            budget,
1344            warnings,
1345            parse_github_check,
1346        )
1347        .await
1348    }
1349
1350    async fn github_reviews(
1351        &self,
1352        request: &PullRequestInspectRequest,
1353        number: &str,
1354        budget: &mut ResponseBudget,
1355        warnings: &mut Vec<PullRequestWarning>,
1356    ) -> Result<Vec<PullRequestReview>, PullRequestError> {
1357        let initial = self.core.url(&[
1358            "repos",
1359            &request.coordinates.owner,
1360            &request.coordinates.repository,
1361            "pulls",
1362            number,
1363            "reviews",
1364        ])?;
1365        self.github_paginated(initial, &request.cancellation, budget, warnings, |value| {
1366            parse_github_review(value)
1367        })
1368        .await
1369    }
1370
1371    async fn github_paginated<T, F>(
1372        &self,
1373        initial: Url,
1374        cancellation: &CancellationToken,
1375        budget: &mut ResponseBudget,
1376        warnings: &mut Vec<PullRequestWarning>,
1377        parse: F,
1378    ) -> Result<Vec<T>, PullRequestError>
1379    where
1380        F: Fn(&Value) -> Result<T, PullRequestError>,
1381    {
1382        self.github_paginated_impl(initial, None, cancellation, budget, warnings, parse)
1383            .await
1384    }
1385
1386    async fn github_paginated_key<T, F>(
1387        &self,
1388        initial: Url,
1389        key: &str,
1390        cancellation: &CancellationToken,
1391        budget: &mut ResponseBudget,
1392        warnings: &mut Vec<PullRequestWarning>,
1393        parse: F,
1394    ) -> Result<Vec<T>, PullRequestError>
1395    where
1396        F: Fn(&Value) -> Result<T, PullRequestError>,
1397    {
1398        self.github_paginated_impl(initial, Some(key), cancellation, budget, warnings, parse)
1399            .await
1400    }
1401
1402    async fn github_paginated_impl<T, F>(
1403        &self,
1404        initial: Url,
1405        key: Option<&str>,
1406        cancellation: &CancellationToken,
1407        budget: &mut ResponseBudget,
1408        warnings: &mut Vec<PullRequestWarning>,
1409        parse: F,
1410    ) -> Result<Vec<T>, PullRequestError>
1411    where
1412        F: Fn(&Value) -> Result<T, PullRequestError>,
1413    {
1414        let mut output = Vec::new();
1415        let mut next = Some(initial);
1416        let mut pages = 0;
1417        while let Some(url) = next {
1418            if pages >= self.core.config.max_pages || output.len() >= self.core.config.max_items {
1419                warnings.push(limit_warning("pagination"));
1420                break;
1421            }
1422            pages += 1;
1423            let response = self.core.get_json(url, None, cancellation, budget).await?;
1424            let FetchJson::Value { value, headers, .. } = response else {
1425                return Err(PullRequestError::MalformedResponse(
1426                    "unexpected 304 for uncached page".to_owned(),
1427                ));
1428            };
1429            let values = match key {
1430                Some(key) => required_array(required_field(&value, key)?, key)?,
1431                None => required_array(&value, "page")?,
1432            };
1433            for item in values {
1434                if output.len() >= self.core.config.max_items {
1435                    warnings.push(limit_warning("items"));
1436                    break;
1437                }
1438                output.push(parse(item)?);
1439            }
1440            next = github_next_url(&headers, &parse_base_url(&self.core.config.api_base_url)?)?;
1441        }
1442        Ok(output)
1443    }
1444}
1445
1446/// Bitbucket Cloud public REST 2.0 pull-request adapter.
1447pub struct BitbucketProvider {
1448    core: ProviderCore,
1449}
1450
1451impl BitbucketProvider {
1452    /// Creates a Bitbucket Cloud provider over an injected transport.
1453    ///
1454    /// # Errors
1455    ///
1456    /// Returns [`PullRequestError`] when configuration is invalid or selects another provider.
1457    pub fn new(
1458        config: PullRequestProviderConfig,
1459        transport: Arc<dyn PrHttpTransport>,
1460    ) -> Result<Self, PullRequestError> {
1461        ProviderCore::new(config, PullRequestProviderKind::BitbucketCloud, transport)
1462            .map(|core| Self { core })
1463    }
1464}
1465
1466#[async_trait]
1467impl PullRequestProvider for BitbucketProvider {
1468    fn kind(&self) -> PullRequestProviderKind {
1469        PullRequestProviderKind::BitbucketCloud
1470    }
1471
1472    async fn inspect(
1473        &self,
1474        request: PullRequestInspectRequest,
1475    ) -> Result<PullRequestInspection, PullRequestError> {
1476        self.core
1477            .authorize(&request, PullRequestProviderKind::BitbucketCloud)?;
1478        if let Some(cached) = self.core.fresh_cache(&request.coordinates)? {
1479            return Ok(cached);
1480        }
1481        let stale = self.core.stale_cache(&request.coordinates)?;
1482        let mut budget = ResponseBudget::default();
1483        let number = request.coordinates.number.to_string();
1484        let metadata_url = self.core.url(&[
1485            "repositories",
1486            &request.coordinates.owner,
1487            &request.coordinates.repository,
1488            "pullrequests",
1489            &number,
1490        ])?;
1491        let metadata_fetch = self
1492            .core
1493            .get_json(
1494                metadata_url,
1495                stale.as_ref().and_then(|entry| entry.etag.as_deref()),
1496                &request.cancellation,
1497                &mut budget,
1498            )
1499            .await?;
1500        let (metadata_json, etag) = match metadata_fetch {
1501            FetchJson::NotModified => {
1502                let entry = stale.ok_or_else(|| {
1503                    PullRequestError::MalformedResponse(
1504                        "provider returned 304 without a cached representation".to_owned(),
1505                    )
1506                })?;
1507                let mut cached = entry.inspection;
1508                cached.from_cache = true;
1509                self.core
1510                    .store_cache(&request.coordinates, &cached, entry.etag)?;
1511                return Ok(cached);
1512            }
1513            FetchJson::Value { value, etag, .. } => (value, etag),
1514        };
1515        let metadata = parse_bitbucket_metadata(&metadata_json)?;
1516        let mut warnings = Vec::new();
1517        let files_url = self.core.url(&[
1518            "repositories",
1519            &request.coordinates.owner,
1520            &request.coordinates.repository,
1521            "pullrequests",
1522            &number,
1523            "diffstat",
1524        ])?;
1525        let files = self
1526            .bitbucket_optional_paginated(
1527                files_url,
1528                &request.cancellation,
1529                &mut budget,
1530                &mut warnings,
1531                "changed files",
1532                parse_bitbucket_file,
1533            )
1534            .await?;
1535        let checks_url = self.core.url(&[
1536            "repositories",
1537            &request.coordinates.owner,
1538            &request.coordinates.repository,
1539            "commit",
1540            &metadata.head.sha,
1541            "statuses",
1542        ])?;
1543        let checks = self
1544            .bitbucket_optional_paginated(
1545                checks_url,
1546                &request.cancellation,
1547                &mut budget,
1548                &mut warnings,
1549                "commit statuses",
1550                parse_bitbucket_check,
1551            )
1552            .await?;
1553        let review = parse_bitbucket_reviews(&metadata_json, self.core.config.max_items)?;
1554        let fingerprint = fingerprint(&metadata, &files)?;
1555        let inspection = PullRequestInspection {
1556            coordinates: request.coordinates.clone(),
1557            metadata,
1558            changed_files: files,
1559            ci: summarize_checks(checks),
1560            review,
1561            rate_limit: budget.rate_limit,
1562            warnings,
1563            fingerprint,
1564            from_cache: false,
1565        };
1566        self.core
1567            .store_cache(&request.coordinates, &inspection, etag)?;
1568        Ok(inspection)
1569    }
1570
1571    async fn list(
1572        &self,
1573        request: PullRequestListRequest,
1574    ) -> Result<PullRequestListPage, PullRequestError> {
1575        self.core
1576            .authorize_list(&request, PullRequestProviderKind::BitbucketCloud)?;
1577        let page_limit = request
1578            .limit
1579            .min(self.core.config.max_items)
1580            .min(MAX_PULL_REQUEST_LIST_LIMIT);
1581        let mut url = self.core.url(&[
1582            "repositories",
1583            &request.owner,
1584            &request.repository,
1585            "pullrequests",
1586        ])?;
1587        let expected_path = url.path().to_owned();
1588        let page_limit_text = page_limit.to_string();
1589        let page = request
1590            .cursor
1591            .as_deref()
1592            .map(parse_list_cursor)
1593            .transpose()?;
1594        let page_text = page.map(|page| page.to_string());
1595        {
1596            let mut query = url.query_pairs_mut();
1597            query
1598                .append_pair("pagelen", &page_limit_text)
1599                .append_pair("sort", "created_on");
1600            match request.state {
1601                PullRequestListState::Open => {
1602                    query.append_pair("state", "OPEN");
1603                }
1604                PullRequestListState::Closed => {
1605                    query
1606                        .append_pair("state", "MERGED")
1607                        .append_pair("state", "FULFILLED")
1608                        .append_pair("state", "DECLINED")
1609                        .append_pair("state", "SUPERSEDED");
1610                }
1611                PullRequestListState::All => {}
1612            }
1613            if let Some(page) = &page_text {
1614                query.append_pair("page", page);
1615            }
1616        }
1617        let mut budget = ResponseBudget::default();
1618        let fetch = self
1619            .core
1620            .get_json(url, None, &request.cancellation, &mut budget)
1621            .await?;
1622        let FetchJson::Value { value, .. } = fetch else {
1623            return Err(PullRequestError::MalformedResponse(
1624                "unexpected 304 for uncached pull-request list".to_owned(),
1625            ));
1626        };
1627        let values = required_array(required_field(&value, "values")?, "values")?;
1628        if values.len() > page_limit {
1629            return Err(PullRequestError::MalformedResponse(
1630                "Bitbucket returned more pull requests than the requested page size".to_owned(),
1631            ));
1632        }
1633        let mut items = values
1634            .iter()
1635            .map(|value| parse_bitbucket_summary(value, &request.owner, &request.repository))
1636            .collect::<Result<Vec<_>, _>>()?;
1637        items.sort_by_key(|summary| summary.coordinates.number);
1638        let base = parse_base_url(&self.core.config.api_base_url)?;
1639        let next_cursor = optional_string(&value, "next")
1640            .map(Url::parse)
1641            .transpose()
1642            .map_err(|_| {
1643                PullRequestError::MalformedResponse(
1644                    "Bitbucket returned an invalid pagination URL".to_owned(),
1645                )
1646            })?
1647            .map(|next| pagination_cursor(&next, &base, &expected_path, "pagelen"))
1648            .transpose()?;
1649        Ok(list_page(
1650            items,
1651            next_cursor,
1652            request.limit,
1653            page_limit,
1654            budget.rate_limit,
1655        ))
1656    }
1657}
1658
1659impl BitbucketProvider {
1660    async fn bitbucket_optional_paginated<T, F>(
1661        &self,
1662        initial: Url,
1663        cancellation: &CancellationToken,
1664        budget: &mut ResponseBudget,
1665        warnings: &mut Vec<PullRequestWarning>,
1666        subject: &str,
1667        parse: F,
1668    ) -> Result<Vec<T>, PullRequestError>
1669    where
1670        F: Fn(&Value) -> Result<T, PullRequestError>,
1671    {
1672        match self
1673            .bitbucket_paginated(initial, cancellation, budget, warnings, parse)
1674            .await
1675        {
1676            Ok(items) => Ok(items),
1677            Err(PullRequestError::Api {
1678                status: 401 | 403, ..
1679            }) => {
1680                warnings.push(provider_scope_warning(subject));
1681                Ok(Vec::new())
1682            }
1683            Err(error) => Err(error),
1684        }
1685    }
1686
1687    async fn bitbucket_paginated<T, F>(
1688        &self,
1689        initial: Url,
1690        cancellation: &CancellationToken,
1691        budget: &mut ResponseBudget,
1692        warnings: &mut Vec<PullRequestWarning>,
1693        parse: F,
1694    ) -> Result<Vec<T>, PullRequestError>
1695    where
1696        F: Fn(&Value) -> Result<T, PullRequestError>,
1697    {
1698        let mut output = Vec::new();
1699        let mut next = Some(initial);
1700        let mut pages = 0;
1701        while let Some(url) = next {
1702            if pages >= self.core.config.max_pages || output.len() >= self.core.config.max_items {
1703                warnings.push(limit_warning("pagination"));
1704                break;
1705            }
1706            pages += 1;
1707            let response = self.core.get_json(url, None, cancellation, budget).await?;
1708            let FetchJson::Value { value, .. } = response else {
1709                return Err(PullRequestError::MalformedResponse(
1710                    "unexpected 304 for uncached page".to_owned(),
1711                ));
1712            };
1713            for item in required_array(required_field(&value, "values")?, "values")? {
1714                if output.len() >= self.core.config.max_items {
1715                    warnings.push(limit_warning("items"));
1716                    break;
1717                }
1718                output.push(parse(item)?);
1719            }
1720            next = optional_string(&value, "next")
1721                .map(Url::parse)
1722                .transpose()
1723                .map_err(|_| {
1724                    PullRequestError::MalformedResponse(
1725                        "Bitbucket returned an invalid pagination URL".to_owned(),
1726                    )
1727                })?;
1728            if let Some(candidate) = &next {
1729                validate_pagination_origin(
1730                    &parse_base_url(&self.core.config.api_base_url)?,
1731                    candidate,
1732                )?;
1733            }
1734        }
1735        Ok(output)
1736    }
1737}
1738
1739fn github_next_url(
1740    headers: &BTreeMap<String, String>,
1741    base: &Url,
1742) -> Result<Option<Url>, PullRequestError> {
1743    let Some(link) = header(headers, "link") else {
1744        return Ok(None);
1745    };
1746    for part in link.split(',') {
1747        let mut sections = part.trim().split(';');
1748        let Some(target) = sections.next() else {
1749            continue;
1750        };
1751        let is_next = sections.any(|section| section.trim() == r#"rel="next""#);
1752        if !is_next {
1753            continue;
1754        }
1755        let raw = target.trim().trim_start_matches('<').trim_end_matches('>');
1756        let candidate = Url::parse(raw).map_err(|_| {
1757            PullRequestError::MalformedResponse(
1758                "GitHub returned an invalid pagination URL".to_owned(),
1759            )
1760        })?;
1761        validate_pagination_origin(base, &candidate)?;
1762        return Ok(Some(candidate));
1763    }
1764    Ok(None)
1765}
1766
1767fn validate_list_request(request: &PullRequestListRequest) -> Result<(), PullRequestError> {
1768    if !(1..=MAX_PULL_REQUEST_LIST_LIMIT).contains(&request.limit) {
1769        return Err(PullRequestError::InvalidConfiguration(
1770            "pull-request list limit must be between 1 and 100".to_owned(),
1771        ));
1772    }
1773    for (name, value) in [
1774        ("owner", request.owner.as_str()),
1775        ("repository", request.repository.as_str()),
1776    ] {
1777        if value.trim().is_empty()
1778            || matches!(value, "." | "..")
1779            || value.chars().any(char::is_control)
1780        {
1781            return Err(PullRequestError::InvalidConfiguration(format!(
1782                "pull-request list {name} must be non-empty and control-free"
1783            )));
1784        }
1785    }
1786    if let Some(cursor) = request.cursor.as_deref() {
1787        parse_list_cursor(cursor)?;
1788    }
1789    Ok(())
1790}
1791
1792fn parse_list_cursor(cursor: &str) -> Result<u64, PullRequestError> {
1793    cursor
1794        .parse::<u64>()
1795        .ok()
1796        .filter(|page| *page > 0)
1797        .ok_or_else(|| {
1798            PullRequestError::InvalidConfiguration(
1799                "pull-request list cursor must be a positive page number".to_owned(),
1800            )
1801        })
1802}
1803
1804fn github_list_state(state: PullRequestListState) -> &'static str {
1805    match state {
1806        PullRequestListState::Open => "open",
1807        PullRequestListState::Closed => "closed",
1808        PullRequestListState::All => "all",
1809    }
1810}
1811
1812fn pagination_cursor(
1813    candidate: &Url,
1814    base: &Url,
1815    expected_path: &str,
1816    page_size_parameter: &str,
1817) -> Result<String, PullRequestError> {
1818    validate_pagination_origin(base, candidate)?;
1819    if !candidate.username().is_empty()
1820        || candidate.password().is_some()
1821        || candidate.fragment().is_some()
1822        || candidate.path() != expected_path
1823    {
1824        return Err(PullRequestError::MalformedResponse(
1825            "pagination URL escaped the pull-request list endpoint".to_owned(),
1826        ));
1827    }
1828    if let Some(page_size) = candidate
1829        .query_pairs()
1830        .find(|(name, _)| name == page_size_parameter)
1831        .map(|(_, value)| value)
1832    {
1833        let valid = page_size
1834            .parse::<usize>()
1835            .is_ok_and(|value| (1..=MAX_PULL_REQUEST_LIST_LIMIT).contains(&value));
1836        if !valid {
1837            return Err(PullRequestError::MalformedResponse(
1838                "provider pagination exceeded the pull-request list limit".to_owned(),
1839            ));
1840        }
1841    }
1842    let mut pages = candidate
1843        .query_pairs()
1844        .filter(|(name, _)| name == "page")
1845        .map(|(_, value)| value);
1846    let page = pages.next().ok_or_else(|| {
1847        PullRequestError::MalformedResponse(
1848            "provider pagination omitted a positive page cursor".to_owned(),
1849        )
1850    })?;
1851    if pages.next().is_some() {
1852        return Err(PullRequestError::MalformedResponse(
1853            "provider pagination returned multiple page cursors".to_owned(),
1854        ));
1855    }
1856    let page = page
1857        .parse::<u64>()
1858        .ok()
1859        .filter(|page| *page > 0)
1860        .ok_or_else(|| {
1861            PullRequestError::MalformedResponse(
1862                "provider pagination returned an invalid page cursor".to_owned(),
1863            )
1864        })?;
1865    Ok(page.to_string())
1866}
1867
1868fn list_page(
1869    items: Vec<PullRequestSummary>,
1870    next_cursor: Option<String>,
1871    requested_limit: usize,
1872    effective_limit: usize,
1873    rate_limit: PullRequestRateLimit,
1874) -> PullRequestListPage {
1875    let has_more = next_cursor.is_some();
1876    let truncated = requested_limit > effective_limit && has_more;
1877    let warnings = truncated
1878        .then(|| PullRequestWarning {
1879            code: "configured_limit_applied".to_owned(),
1880            message: format!(
1881                "Pull-request list page size was reduced to the configured limit of \
1882                 {effective_limit}"
1883            ),
1884        })
1885        .into_iter()
1886        .collect();
1887    PullRequestListPage {
1888        items,
1889        next_cursor,
1890        has_more,
1891        truncated,
1892        rate_limit,
1893        warnings,
1894    }
1895}
1896
1897fn parse_base_url(value: &str) -> Result<Url, PullRequestError> {
1898    let url = Url::parse(value).map_err(|_| {
1899        PullRequestError::InvalidConfiguration("provider API base URL is invalid".to_owned())
1900    })?;
1901    if url.cannot_be_a_base()
1902        || url.host_str().is_none()
1903        || !url.username().is_empty()
1904        || url.password().is_some()
1905        || url.query().is_some()
1906        || url.fragment().is_some()
1907    {
1908        return Err(PullRequestError::InvalidConfiguration(
1909            "provider API base URL must be an absolute credential-free URL".to_owned(),
1910        ));
1911    }
1912    Ok(url)
1913}
1914
1915fn normalize_base_url(mut url: Url) -> String {
1916    url.set_fragment(None);
1917    url.set_query(None);
1918    let trimmed = url.path().trim_end_matches('/').to_owned();
1919    url.set_path(&trimmed);
1920    url.to_string().trim_end_matches('/').to_owned()
1921}
1922
1923fn is_loopback(url: &Url) -> bool {
1924    url.host_str().is_some_and(|host| {
1925        host.eq_ignore_ascii_case("localhost")
1926            || host
1927                .parse::<std::net::IpAddr>()
1928                .is_ok_and(|ip| ip.is_loopback())
1929    })
1930}
1931
1932fn validate_pagination_origin(base: &Url, candidate: &Url) -> Result<(), PullRequestError> {
1933    if base.scheme() != candidate.scheme()
1934        || base.host_str() != candidate.host_str()
1935        || base.port_or_known_default() != candidate.port_or_known_default()
1936    {
1937        return Err(PullRequestError::MalformedResponse(
1938            "pagination URL escaped the configured provider origin".to_owned(),
1939        ));
1940    }
1941    Ok(())
1942}
1943
1944fn header<'a>(headers: &'a BTreeMap<String, String>, name: &str) -> Option<&'a str> {
1945    headers
1946        .iter()
1947        .find(|(key, _)| key.eq_ignore_ascii_case(name))
1948        .map(|(_, value)| value.as_str())
1949}
1950
1951fn rate_limit_from_headers(headers: &BTreeMap<String, String>) -> PullRequestRateLimit {
1952    PullRequestRateLimit {
1953        limit: header(headers, "x-ratelimit-limit").and_then(|value| value.parse().ok()),
1954        remaining: header(headers, "x-ratelimit-remaining").and_then(|value| value.parse().ok()),
1955        reset: header(headers, "x-ratelimit-reset").map(str::to_owned),
1956        retry_after_seconds: header(headers, "retry-after").and_then(|value| value.parse().ok()),
1957    }
1958}
1959
1960fn api_error_message(body: &[u8], token: &PrAuthToken) -> String {
1961    let parsed = serde_json::from_slice::<Value>(body).ok();
1962    let message = parsed
1963        .as_ref()
1964        .and_then(|value| {
1965            optional_string(value, "message").or_else(|| {
1966                value
1967                    .get("error")
1968                    .and_then(|error| optional_string(error, "message"))
1969            })
1970        })
1971        .unwrap_or("provider returned an error");
1972    redact_message(message, token)
1973}
1974
1975fn redact_message(message: &str, token: &PrAuthToken) -> String {
1976    let bounded: String = message.chars().take(512).collect();
1977    if token.is_empty() {
1978        bounded
1979    } else {
1980        bounded.replace(token.expose_secret(), REDACTED)
1981    }
1982}
1983
1984fn required_field<'a>(value: &'a Value, field: &str) -> Result<&'a Value, PullRequestError> {
1985    value.get(field).ok_or_else(|| {
1986        PullRequestError::MalformedResponse(format!("missing required field `{field}`"))
1987    })
1988}
1989
1990fn required_string<'a>(value: &'a Value, field: &str) -> Result<&'a str, PullRequestError> {
1991    required_field(value, field)?
1992        .as_str()
1993        .filter(|text| !text.is_empty())
1994        .ok_or_else(|| {
1995            PullRequestError::MalformedResponse(format!("field `{field}` must be a string"))
1996        })
1997}
1998
1999fn optional_string<'a>(value: &'a Value, field: &str) -> Option<&'a str> {
2000    value.get(field).and_then(Value::as_str)
2001}
2002
2003fn required_array<'a>(value: &'a Value, field: &str) -> Result<&'a [Value], PullRequestError> {
2004    value.as_array().map(Vec::as_slice).ok_or_else(|| {
2005        PullRequestError::MalformedResponse(format!("field `{field}` must be an array"))
2006    })
2007}
2008
2009fn nested<'a>(value: &'a Value, fields: &[&str]) -> Result<&'a Value, PullRequestError> {
2010    fields
2011        .iter()
2012        .try_fold(value, |current, field| required_field(current, field))
2013}
2014
2015fn nested_string<'a>(value: &'a Value, fields: &[&str]) -> Result<&'a str, PullRequestError> {
2016    let (last, parents) = fields
2017        .split_last()
2018        .ok_or_else(|| PullRequestError::MalformedResponse("empty JSON field path".to_owned()))?;
2019    required_string(nested(value, parents)?, last)
2020}
2021
2022fn value_id(value: &Value, field: &str) -> Result<String, PullRequestError> {
2023    let id = required_field(value, field)?;
2024    id.as_str()
2025        .map(str::to_owned)
2026        .or_else(|| id.as_u64().map(|number| number.to_string()))
2027        .ok_or_else(|| {
2028            PullRequestError::MalformedResponse(format!(
2029                "field `{field}` must be a string or integer"
2030            ))
2031        })
2032}
2033
2034fn required_u64(value: &Value, field: &str) -> Result<u64, PullRequestError> {
2035    required_field(value, field)?.as_u64().ok_or_else(|| {
2036        PullRequestError::MalformedResponse(format!(
2037            "field `{field}` must be a non-negative integer"
2038        ))
2039    })
2040}
2041
2042fn parse_github_summary(
2043    value: &Value,
2044    owner: &str,
2045    repository: &str,
2046) -> Result<PullRequestSummary, PullRequestError> {
2047    let state = if value.get("merged_at").is_some_and(|value| !value.is_null()) {
2048        PullRequestState::Merged
2049    } else {
2050        match required_string(value, "state")? {
2051            "open" => PullRequestState::Open,
2052            "closed" => PullRequestState::Closed,
2053            _ => PullRequestState::Unknown,
2054        }
2055    };
2056    Ok(PullRequestSummary {
2057        coordinates: PullRequestCoordinates {
2058            provider: PullRequestProviderKind::GitHub,
2059            owner: owner.to_owned(),
2060            repository: repository.to_owned(),
2061            number: required_u64(value, "number")?,
2062        },
2063        title: required_string(value, "title")?.to_owned(),
2064        url: required_string(value, "html_url")?.to_owned(),
2065        state,
2066        draft: value.get("draft").and_then(Value::as_bool).unwrap_or(false),
2067        author: nested_string(value, &["user", "login"])?.to_owned(),
2068        base_branch: nested_string(value, &["base", "ref"])?.to_owned(),
2069        head_branch: nested_string(value, &["head", "ref"])?.to_owned(),
2070        created_at: required_string(value, "created_at")?.to_owned(),
2071        updated_at: required_string(value, "updated_at")?.to_owned(),
2072    })
2073}
2074
2075fn parse_github_metadata(value: &Value) -> Result<PullRequestMetadata, PullRequestError> {
2076    let merged = value
2077        .get("merged")
2078        .and_then(Value::as_bool)
2079        .unwrap_or(false);
2080    let state = if merged {
2081        PullRequestState::Merged
2082    } else {
2083        match required_string(value, "state")? {
2084            "open" => PullRequestState::Open,
2085            "closed" => PullRequestState::Closed,
2086            _ => PullRequestState::Unknown,
2087        }
2088    };
2089    Ok(PullRequestMetadata {
2090        id: value_id(value, "id")?,
2091        title: required_string(value, "title")?.to_owned(),
2092        url: required_string(value, "html_url")?.to_owned(),
2093        state,
2094        draft: value.get("draft").and_then(Value::as_bool).unwrap_or(false),
2095        author: nested_string(value, &["user", "login"])?.to_owned(),
2096        base: parse_github_ref(required_field(value, "base")?)?,
2097        head: parse_github_ref(required_field(value, "head")?)?,
2098        created_at: required_string(value, "created_at")?.to_owned(),
2099        updated_at: required_string(value, "updated_at")?.to_owned(),
2100    })
2101}
2102
2103fn parse_github_ref(value: &Value) -> Result<PullRequestRef, PullRequestError> {
2104    Ok(PullRequestRef {
2105        name: required_string(value, "ref")?.to_owned(),
2106        sha: required_string(value, "sha")?.to_owned(),
2107        repository: PullRequestRepository {
2108            full_name: nested_string(value, &["repo", "full_name"])?.to_owned(),
2109            url: nested(value, &["repo"])
2110                .ok()
2111                .and_then(|repo| optional_string(repo, "html_url"))
2112                .map(str::to_owned),
2113        },
2114    })
2115}
2116
2117fn parse_github_file(value: &Value) -> Result<PullRequestChangedFile, PullRequestError> {
2118    let filename = required_string(value, "filename")?.to_owned();
2119    let provider_status = required_string(value, "status")?;
2120    let status = match provider_status {
2121        "added" => ChangedFileStatus::Added,
2122        "modified" | "changed" => ChangedFileStatus::Modified,
2123        "removed" => ChangedFileStatus::Removed,
2124        "renamed" => ChangedFileStatus::Renamed,
2125        "copied" => ChangedFileStatus::Copied,
2126        _ => ChangedFileStatus::Unknown,
2127    };
2128    let old_path = if matches!(status, ChangedFileStatus::Renamed) {
2129        optional_string(value, "previous_filename").map(str::to_owned)
2130    } else if matches!(status, ChangedFileStatus::Removed) {
2131        Some(filename.clone())
2132    } else {
2133        None
2134    };
2135    let new_path = (!matches!(status, ChangedFileStatus::Removed)).then_some(filename);
2136    let additions = value.get("additions").and_then(Value::as_u64).unwrap_or(0);
2137    let deletions = value.get("deletions").and_then(Value::as_u64).unwrap_or(0);
2138    let patch_present = value.get("patch").and_then(Value::as_str).is_some();
2139    Ok(PullRequestChangedFile {
2140        status,
2141        old_path,
2142        new_path,
2143        additions,
2144        deletions,
2145        binary: !patch_present && additions.saturating_add(deletions) > 0,
2146        patch_truncated: patch_present,
2147    })
2148}
2149
2150fn parse_github_check(value: &Value) -> Result<PullRequestCheck, PullRequestError> {
2151    let status = optional_string(value, "status").unwrap_or("unknown");
2152    let conclusion = optional_string(value, "conclusion").unwrap_or("unknown");
2153    let state = if status == "completed" {
2154        match conclusion {
2155            "success" | "neutral" | "skipped" => CheckState::Success,
2156            "failure" | "timed_out" | "cancelled" | "action_required" => CheckState::Failure,
2157            _ => CheckState::Unknown,
2158        }
2159    } else {
2160        CheckState::Pending
2161    };
2162    Ok(PullRequestCheck {
2163        name: required_string(value, "name")?.to_owned(),
2164        state,
2165        url: optional_string(value, "details_url").map(str::to_owned),
2166    })
2167}
2168
2169fn parse_github_review(value: &Value) -> Result<PullRequestReview, PullRequestError> {
2170    Ok(PullRequestReview {
2171        id: value_id(value, "id")?,
2172        author: nested_string(value, &["user", "login"])?.to_owned(),
2173        state: required_string(value, "state")?.to_ascii_lowercase(),
2174        submitted_at: optional_string(value, "submitted_at").map(str::to_owned),
2175    })
2176}
2177
2178fn parse_bitbucket_metadata(value: &Value) -> Result<PullRequestMetadata, PullRequestError> {
2179    let state = match required_string(value, "state")? {
2180        "OPEN" => PullRequestState::Open,
2181        "MERGED" | "FULFILLED" => PullRequestState::Merged,
2182        "DECLINED" | "SUPERSEDED" => PullRequestState::Closed,
2183        _ => PullRequestState::Unknown,
2184    };
2185    Ok(PullRequestMetadata {
2186        id: value_id(value, "id")?,
2187        title: required_string(value, "title")?.to_owned(),
2188        url: nested_string(value, &["links", "html", "href"])?.to_owned(),
2189        state,
2190        draft: value.get("draft").and_then(Value::as_bool).unwrap_or(false),
2191        author: nested_string(value, &["author", "display_name"])?.to_owned(),
2192        base: parse_bitbucket_ref(required_field(value, "destination")?)?,
2193        head: parse_bitbucket_ref(required_field(value, "source")?)?,
2194        created_at: required_string(value, "created_on")?.to_owned(),
2195        updated_at: required_string(value, "updated_on")?.to_owned(),
2196    })
2197}
2198
2199fn parse_bitbucket_summary(
2200    value: &Value,
2201    owner: &str,
2202    repository: &str,
2203) -> Result<PullRequestSummary, PullRequestError> {
2204    let state = match required_string(value, "state")? {
2205        "OPEN" => PullRequestState::Open,
2206        "MERGED" | "FULFILLED" => PullRequestState::Merged,
2207        "DECLINED" | "SUPERSEDED" => PullRequestState::Closed,
2208        _ => PullRequestState::Unknown,
2209    };
2210    Ok(PullRequestSummary {
2211        coordinates: PullRequestCoordinates {
2212            provider: PullRequestProviderKind::BitbucketCloud,
2213            owner: owner.to_owned(),
2214            repository: repository.to_owned(),
2215            number: required_u64(value, "id")?,
2216        },
2217        title: required_string(value, "title")?.to_owned(),
2218        url: nested_string(value, &["links", "html", "href"])?.to_owned(),
2219        state,
2220        draft: value.get("draft").and_then(Value::as_bool).unwrap_or(false),
2221        author: nested_string(value, &["author", "display_name"])?.to_owned(),
2222        base_branch: nested_string(value, &["destination", "branch", "name"])?.to_owned(),
2223        head_branch: nested_string(value, &["source", "branch", "name"])?.to_owned(),
2224        created_at: required_string(value, "created_on")?.to_owned(),
2225        updated_at: required_string(value, "updated_on")?.to_owned(),
2226    })
2227}
2228
2229fn parse_bitbucket_ref(value: &Value) -> Result<PullRequestRef, PullRequestError> {
2230    let repository = required_field(value, "repository")?;
2231    Ok(PullRequestRef {
2232        name: nested_string(value, &["branch", "name"])?.to_owned(),
2233        sha: nested_string(value, &["commit", "hash"])?.to_owned(),
2234        repository: PullRequestRepository {
2235            full_name: required_string(repository, "full_name")?.to_owned(),
2236            url: nested(repository, &["links", "html"])
2237                .ok()
2238                .and_then(|html| optional_string(html, "href"))
2239                .map(str::to_owned),
2240        },
2241    })
2242}
2243
2244fn parse_bitbucket_file(value: &Value) -> Result<PullRequestChangedFile, PullRequestError> {
2245    let status_text = required_string(value, "status")?;
2246    let status = match status_text {
2247        "added" => ChangedFileStatus::Added,
2248        "modified" => ChangedFileStatus::Modified,
2249        "removed" => ChangedFileStatus::Removed,
2250        "renamed" => ChangedFileStatus::Renamed,
2251        _ => ChangedFileStatus::Unknown,
2252    };
2253    let old_path = value
2254        .get("old")
2255        .and_then(|old| optional_string(old, "path"))
2256        .map(str::to_owned);
2257    let new_path = value
2258        .get("new")
2259        .and_then(|new| optional_string(new, "path"))
2260        .map(str::to_owned);
2261    let binary = value
2262        .get("new")
2263        .or_else(|| value.get("old"))
2264        .and_then(|entry| optional_string(entry, "type"))
2265        .is_some_and(|kind| kind.eq_ignore_ascii_case("binary"));
2266    Ok(PullRequestChangedFile {
2267        status,
2268        old_path,
2269        new_path,
2270        additions: value
2271            .get("lines_added")
2272            .and_then(Value::as_u64)
2273            .unwrap_or(0),
2274        deletions: value
2275            .get("lines_removed")
2276            .and_then(Value::as_u64)
2277            .unwrap_or(0),
2278        binary,
2279        patch_truncated: false,
2280    })
2281}
2282
2283fn parse_bitbucket_check(value: &Value) -> Result<PullRequestCheck, PullRequestError> {
2284    let state = match required_string(value, "state")? {
2285        "SUCCESSFUL" => CheckState::Success,
2286        "FAILED" | "STOPPED" => CheckState::Failure,
2287        "INPROGRESS" => CheckState::Pending,
2288        _ => CheckState::Unknown,
2289    };
2290    Ok(PullRequestCheck {
2291        name: required_string(value, "key")?.to_owned(),
2292        state,
2293        url: optional_string(value, "url").map(str::to_owned),
2294    })
2295}
2296
2297fn parse_bitbucket_reviews(
2298    metadata: &Value,
2299    max_items: usize,
2300) -> Result<PullRequestReviewSummary, PullRequestError> {
2301    let Some(participants) = metadata.get("participants") else {
2302        return Ok(PullRequestReviewSummary {
2303            state: ReviewState::Unknown,
2304            approvals: 0,
2305            reviews: Vec::new(),
2306        });
2307    };
2308    let mut reviews = Vec::new();
2309    let mut approvals = 0;
2310    let mut changes_requested = false;
2311    for participant in required_array(participants, "participants")?
2312        .iter()
2313        .take(max_items)
2314    {
2315        let approved = participant
2316            .get("approved")
2317            .and_then(Value::as_bool)
2318            .unwrap_or(false);
2319        let state = optional_string(participant, "state")
2320            .unwrap_or(if approved { "approved" } else { "pending" })
2321            .to_ascii_lowercase();
2322        approvals += usize::from(approved);
2323        changes_requested |= state.contains("changes_requested");
2324        let user = required_field(participant, "user")?;
2325        let author = optional_string(user, "display_name")
2326            .or_else(|| optional_string(user, "nickname"))
2327            .ok_or_else(|| {
2328                PullRequestError::MalformedResponse(
2329                    "Bitbucket participant has no identity".to_owned(),
2330                )
2331            })?;
2332        let id = optional_string(user, "uuid").unwrap_or(author);
2333        reviews.push(PullRequestReview {
2334            id: id.to_owned(),
2335            author: author.to_owned(),
2336            state,
2337            submitted_at: None,
2338        });
2339    }
2340    let state = if changes_requested {
2341        ReviewState::ChangesRequested
2342    } else if approvals > 0 {
2343        ReviewState::Approved
2344    } else if reviews.is_empty() {
2345        ReviewState::Unknown
2346    } else {
2347        ReviewState::Pending
2348    };
2349    Ok(PullRequestReviewSummary {
2350        state,
2351        approvals,
2352        reviews,
2353    })
2354}
2355
2356fn summarize_checks(checks: Vec<PullRequestCheck>) -> PullRequestCi {
2357    let state = if checks.is_empty() {
2358        CheckState::Unknown
2359    } else if checks
2360        .iter()
2361        .any(|check| check.state == CheckState::Failure)
2362    {
2363        CheckState::Failure
2364    } else if checks
2365        .iter()
2366        .any(|check| check.state == CheckState::Pending)
2367    {
2368        CheckState::Pending
2369    } else if checks
2370        .iter()
2371        .all(|check| check.state == CheckState::Success)
2372    {
2373        CheckState::Success
2374    } else {
2375        CheckState::Unknown
2376    };
2377    PullRequestCi { state, checks }
2378}
2379
2380fn summarize_github_reviews(reviews: Vec<PullRequestReview>) -> PullRequestReviewSummary {
2381    let mut latest = BTreeMap::new();
2382    for review in &reviews {
2383        latest.insert(review.author.as_str(), review.state.as_str());
2384    }
2385    let approvals = latest
2386        .values()
2387        .filter(|state| **state == "approved")
2388        .count();
2389    let changes_requested = latest.values().any(|state| *state == "changes_requested");
2390    let state = if changes_requested {
2391        ReviewState::ChangesRequested
2392    } else if approvals > 0 {
2393        ReviewState::Approved
2394    } else if reviews.is_empty() {
2395        ReviewState::Unknown
2396    } else {
2397        ReviewState::Pending
2398    };
2399    PullRequestReviewSummary {
2400        state,
2401        approvals,
2402        reviews,
2403    }
2404}
2405
2406fn fingerprint(
2407    metadata: &PullRequestMetadata,
2408    files: &[PullRequestChangedFile],
2409) -> Result<String, PullRequestError> {
2410    serde_json::to_vec(&(metadata, files))
2411        .map(|bytes| blake3::hash(&bytes).to_hex().to_string())
2412        .map_err(|error| PullRequestError::MalformedResponse(error.to_string()))
2413}
2414
2415fn limit_warning(subject: &str) -> PullRequestWarning {
2416    PullRequestWarning {
2417        code: "limit_reached".to_owned(),
2418        message: format!("{subject} stopped at the configured limit"),
2419    }
2420}
2421
2422fn provider_scope_warning(subject: &str) -> PullRequestWarning {
2423    PullRequestWarning {
2424        code: "provider_scope_missing".to_owned(),
2425        message: format!(
2426            "Provider credentials cannot read {subject}; the corresponding result is unknown"
2427        ),
2428    }
2429}
2430
2431/// Contract role used by semantic overlap and ordering.
2432#[derive(
2433    Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize, JsonSchema,
2434)]
2435#[serde(rename_all = "snake_case")]
2436pub enum ContractRole {
2437    /// Defines or serves the contract.
2438    Provider,
2439    /// Consumes the contract.
2440    Consumer,
2441}
2442
2443/// Contract touched by a pull request.
2444#[derive(Debug, Clone, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize, JsonSchema)]
2445pub struct PullRequestContractChange {
2446    /// Stable contract identity.
2447    pub contract: String,
2448    /// Relationship of the changed repository to the contract.
2449    pub role: ContractRole,
2450    /// Whether compatibility analysis classified the change as breaking.
2451    pub breaking: bool,
2452}
2453
2454/// Readiness freshness for conservative ordering.
2455#[derive(
2456    Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize, JsonSchema,
2457)]
2458#[serde(rename_all = "snake_case")]
2459pub enum PullRequestReadiness {
2460    /// CI and review data establish readiness.
2461    Ready,
2462    /// CI or review data establishes a blocker.
2463    Blocked,
2464    /// Required readiness data is unavailable.
2465    Unknown,
2466    /// Readiness data is stale.
2467    Stale,
2468}
2469
2470/// Provider-neutral semantic inputs for one pull request.
2471#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
2472pub struct PullRequestSemanticInput {
2473    /// Stable fingerprint used as an ordering identity.
2474    pub fingerprint: String,
2475    /// Changed paths.
2476    pub files: BTreeSet<String>,
2477    /// Contracts touched by the change.
2478    pub contracts: BTreeSet<PullRequestContractChange>,
2479    /// Stable service identities touched by the change.
2480    pub services: BTreeSet<String>,
2481    /// Stable community identities touched by the change.
2482    pub communities: BTreeSet<String>,
2483    /// Fingerprints that must be merged before this change.
2484    pub depends_on: BTreeSet<String>,
2485    /// Current CI and review readiness.
2486    pub readiness: PullRequestReadiness,
2487}
2488
2489/// Strongest deterministic semantic overlap classification.
2490#[derive(
2491    Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize, JsonSchema,
2492)]
2493#[serde(rename_all = "snake_case")]
2494pub enum PullRequestOverlapKind {
2495    /// No common semantic input.
2496    Disjoint,
2497    /// At least one path overlaps.
2498    File,
2499    /// At least one contract overlaps.
2500    Contract,
2501    /// At least one service overlaps.
2502    Service,
2503    /// At least one graph community overlaps.
2504    Community,
2505    /// Shared migration or breaking-contract changes require coordination.
2506    Conflicting,
2507}
2508
2509/// Deterministic semantic overlap result.
2510#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
2511pub struct PullRequestOverlap {
2512    /// Strongest overlap classification.
2513    pub kind: PullRequestOverlapKind,
2514    /// Shared paths in lexical order.
2515    pub files: Vec<String>,
2516    /// Shared contract identities in lexical order.
2517    pub contracts: Vec<String>,
2518    /// Shared service identities in lexical order.
2519    pub services: Vec<String>,
2520    /// Shared community identities in lexical order.
2521    pub communities: Vec<String>,
2522}
2523
2524/// Computes deterministic overlap without treating missing evidence as safety.
2525#[must_use]
2526pub fn semantic_pull_request_overlap(
2527    left: &PullRequestSemanticInput,
2528    right: &PullRequestSemanticInput,
2529) -> PullRequestOverlap {
2530    let files = intersection(&left.files, &right.files);
2531    let left_contracts: BTreeSet<_> = left
2532        .contracts
2533        .iter()
2534        .map(|change| change.contract.clone())
2535        .collect();
2536    let right_contracts: BTreeSet<_> = right
2537        .contracts
2538        .iter()
2539        .map(|change| change.contract.clone())
2540        .collect();
2541    let contracts = intersection(&left_contracts, &right_contracts);
2542    let services = intersection(&left.services, &right.services);
2543    let communities = intersection(&left.communities, &right.communities);
2544    let migration_conflict = files.iter().any(|path| is_migration_path(path));
2545    let breaking_contract_conflict = contracts.iter().any(|contract| {
2546        left.contracts
2547            .iter()
2548            .chain(&right.contracts)
2549            .any(|change| change.contract == *contract && change.breaking)
2550    });
2551    let kind = if migration_conflict || breaking_contract_conflict {
2552        PullRequestOverlapKind::Conflicting
2553    } else if !contracts.is_empty() {
2554        PullRequestOverlapKind::Contract
2555    } else if !services.is_empty() {
2556        PullRequestOverlapKind::Service
2557    } else if !communities.is_empty() {
2558        PullRequestOverlapKind::Community
2559    } else if !files.is_empty() {
2560        PullRequestOverlapKind::File
2561    } else {
2562        PullRequestOverlapKind::Disjoint
2563    };
2564    PullRequestOverlap {
2565        kind,
2566        files,
2567        contracts,
2568        services,
2569        communities,
2570    }
2571}
2572
2573fn intersection(left: &BTreeSet<String>, right: &BTreeSet<String>) -> Vec<String> {
2574    left.intersection(right).cloned().collect()
2575}
2576
2577fn is_migration_path(path: &str) -> bool {
2578    let normalized = path.replace('\\', "/").to_ascii_lowercase();
2579    normalized.contains("/migrations/")
2580        || normalized.starts_with("migrations/")
2581        || normalized.ends_with(".migration.sql")
2582}
2583
2584/// Suggested relationship between two review or merge operations.
2585#[derive(
2586    Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Serialize, Deserialize, JsonSchema,
2587)]
2588#[serde(rename_all = "snake_case")]
2589pub enum PullRequestOrder {
2590    /// Review or merge the left input first.
2591    LeftFirst,
2592    /// Review or merge the right input first.
2593    RightFirst,
2594    /// Changes should be coordinated rather than linearly ordered.
2595    Coordinated,
2596    /// Evidence does not justify a definitive order.
2597    NoDefinitiveOrder,
2598}
2599
2600/// Deterministic review/merge ordering suggestion.
2601#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize, JsonSchema)]
2602pub struct PullRequestOrderSuggestion {
2603    /// Suggested relationship.
2604    pub order: PullRequestOrder,
2605    /// Stable machine-readable reasons in lexical order.
2606    pub reasons: Vec<String>,
2607}
2608
2609/// Suggests a conservative review/merge order from dependencies, contracts, and readiness.
2610#[must_use]
2611pub fn suggest_pull_request_order(
2612    left: &PullRequestSemanticInput,
2613    right: &PullRequestSemanticInput,
2614) -> PullRequestOrderSuggestion {
2615    if matches!(
2616        left.readiness,
2617        PullRequestReadiness::Unknown | PullRequestReadiness::Stale
2618    ) || matches!(
2619        right.readiness,
2620        PullRequestReadiness::Unknown | PullRequestReadiness::Stale
2621    ) {
2622        return suggestion(
2623            PullRequestOrder::NoDefinitiveOrder,
2624            ["readiness_unknown_or_stale"],
2625        );
2626    }
2627    let overlap = semantic_pull_request_overlap(left, right);
2628    if overlap.kind == PullRequestOverlapKind::Conflicting {
2629        return suggestion(
2630            PullRequestOrder::Coordinated,
2631            ["shared_migration_or_breaking_contract"],
2632        );
2633    }
2634    let left_depends_on_right = left.depends_on.contains(&right.fingerprint);
2635    let right_depends_on_left = right.depends_on.contains(&left.fingerprint);
2636    match (left_depends_on_right, right_depends_on_left) {
2637        (true, true) => {
2638            return suggestion(PullRequestOrder::Coordinated, ["dependency_cycle"]);
2639        }
2640        (true, false) => {
2641            return suggestion(PullRequestOrder::RightFirst, ["dependency_direction"]);
2642        }
2643        (false, true) => {
2644            return suggestion(PullRequestOrder::LeftFirst, ["dependency_direction"]);
2645        }
2646        (false, false) => {}
2647    }
2648    if let Some(order) = breaking_provider_order(left, right) {
2649        return suggestion(order, ["breaking_contract_provider_before_consumer"]);
2650    }
2651    match (left.readiness, right.readiness) {
2652        (PullRequestReadiness::Ready, PullRequestReadiness::Blocked) => {
2653            suggestion(PullRequestOrder::LeftFirst, ["ci_review_readiness"])
2654        }
2655        (PullRequestReadiness::Blocked, PullRequestReadiness::Ready) => {
2656            suggestion(PullRequestOrder::RightFirst, ["ci_review_readiness"])
2657        }
2658        _ => suggestion(
2659            PullRequestOrder::NoDefinitiveOrder,
2660            ["no_ordering_evidence"],
2661        ),
2662    }
2663}
2664
2665fn breaking_provider_order(
2666    left: &PullRequestSemanticInput,
2667    right: &PullRequestSemanticInput,
2668) -> Option<PullRequestOrder> {
2669    for left_change in &left.contracts {
2670        for right_change in &right.contracts {
2671            if left_change.contract != right_change.contract {
2672                continue;
2673            }
2674            if left_change.breaking && left_change.role == ContractRole::Provider {
2675                return Some(PullRequestOrder::LeftFirst);
2676            }
2677            if right_change.breaking && right_change.role == ContractRole::Provider {
2678                return Some(PullRequestOrder::RightFirst);
2679            }
2680        }
2681    }
2682    None
2683}
2684
2685fn suggestion(
2686    order: PullRequestOrder,
2687    reasons: impl IntoIterator<Item = &'static str>,
2688) -> PullRequestOrderSuggestion {
2689    let mut reasons: Vec<_> = reasons.into_iter().map(str::to_owned).collect();
2690    reasons.sort();
2691    reasons.dedup();
2692    PullRequestOrderSuggestion { order, reasons }
2693}
2694
2695#[cfg(test)]
2696mod tests {
2697    use std::collections::VecDeque;
2698    use std::io::{Read, Write};
2699    use std::net::TcpListener;
2700
2701    use serde_json::json;
2702
2703    use super::*;
2704
2705    fn one_response_server(response: &'static [u8]) -> String {
2706        let listener = TcpListener::bind("127.0.0.1:0").expect("bind test server");
2707        let address = listener.local_addr().expect("test server address");
2708        std::thread::spawn(move || {
2709            let (mut stream, _) = listener.accept().expect("accept test request");
2710            let mut request = [0_u8; 4096];
2711            let _ = stream.read(&mut request).expect("read test request");
2712            stream.write_all(response).expect("write test response");
2713        });
2714        format!("http://{address}/test")
2715    }
2716
2717    #[tokio::test]
2718    async fn production_transport_streams_bounded_responses_without_redirects() {
2719        let url = one_response_server(b"HTTP/1.1 302 Found\r\nLocation: http://127.0.0.1:1/blocked\r\nContent-Length: 4\r\nConnection: close\r\n\r\nbody");
2720        let transport = ReqwestPrHttpTransport::new().expect("production transport");
2721        let response = transport
2722            .send(PrHttpRequest {
2723                method: PrHttpMethod::Get,
2724                url,
2725                headers: BTreeMap::new(),
2726                authentication: PrHttpAuthentication::None,
2727                max_response_bytes: 4,
2728                timeout: Duration::from_secs(2),
2729                cancellation: CancellationToken::new(),
2730            })
2731            .await
2732            .expect("bounded response");
2733        assert_eq!((response.status, response.body), (302, b"body".to_vec()));
2734    }
2735
2736    #[tokio::test]
2737    async fn production_transport_rejects_declared_oversized_responses() {
2738        let url = one_response_server(
2739            b"HTTP/1.1 200 OK\r\nContent-Length: 8\r\nConnection: close\r\n\r\noversize",
2740        );
2741        let transport = ReqwestPrHttpTransport::new().expect("production transport");
2742        let error = transport
2743            .send(PrHttpRequest {
2744                method: PrHttpMethod::Get,
2745                url,
2746                headers: BTreeMap::new(),
2747                authentication: PrHttpAuthentication::None,
2748                max_response_bytes: 4,
2749                timeout: Duration::from_secs(2),
2750                cancellation: CancellationToken::new(),
2751            })
2752            .await
2753            .expect_err("oversized response");
2754        assert!(error.message.contains("output limit"));
2755    }
2756
2757    #[derive(Default)]
2758    struct MockTransport {
2759        responses: Mutex<VecDeque<Result<PrHttpResponse, PrHttpTransportError>>>,
2760        requests: Mutex<Vec<PrHttpRequest>>,
2761    }
2762
2763    impl MockTransport {
2764        fn with(responses: Vec<PrHttpResponse>) -> Arc<Self> {
2765            Arc::new(Self {
2766                responses: Mutex::new(responses.into_iter().map(Ok).collect()),
2767                requests: Mutex::default(),
2768            })
2769        }
2770
2771        fn request_count(&self) -> usize {
2772            self.requests.lock().expect("requests lock").len()
2773        }
2774
2775        fn request_header(&self, index: usize, name: &str) -> Option<String> {
2776            self.requests
2777                .lock()
2778                .expect("requests lock")
2779                .get(index)
2780                .and_then(|request| request.headers.get(name))
2781                .cloned()
2782        }
2783
2784        fn request_url(&self, index: usize) -> Option<String> {
2785            self.requests
2786                .lock()
2787                .expect("requests lock")
2788                .get(index)
2789                .map(|request| request.url.clone())
2790        }
2791
2792        fn request_authentication(&self, index: usize) -> Option<PrHttpAuthentication> {
2793            self.requests
2794                .lock()
2795                .expect("requests lock")
2796                .get(index)
2797                .map(|request| request.authentication.clone())
2798        }
2799    }
2800
2801    #[async_trait]
2802    impl PrHttpTransport for MockTransport {
2803        async fn send(
2804            &self,
2805            request: PrHttpRequest,
2806        ) -> Result<PrHttpResponse, PrHttpTransportError> {
2807            self.requests.lock().expect("requests lock").push(request);
2808            self.responses
2809                .lock()
2810                .expect("responses lock")
2811                .pop_front()
2812                .expect("mock response")
2813        }
2814    }
2815
2816    fn response(status: u16, value: &Value) -> PrHttpResponse {
2817        PrHttpResponse {
2818            status,
2819            headers: BTreeMap::new(),
2820            body: serde_json::to_vec(value).expect("JSON"),
2821        }
2822    }
2823
2824    fn github_metadata() -> Value {
2825        json!({
2826            "id": 10, "title": "Change", "html_url": "https://example/pr/1",
2827            "state": "open", "draft": false, "user": {"login": "alice"},
2828            "base": {"ref": "main", "sha": "base", "repo": {"full_name": "o/r", "html_url": "https://example/o/r"}},
2829            "head": {"ref": "feature", "sha": "head", "repo": {"full_name": "o/r", "html_url": "https://example/o/r"}},
2830            "created_at": "2026-01-01T00:00:00Z", "updated_at": "2026-01-02T00:00:00Z"
2831        })
2832    }
2833
2834    fn bitbucket_metadata() -> Value {
2835        json!({
2836            "id": 7, "title": "Change", "state": "OPEN", "draft": false,
2837            "links": {"html": {"href": "https://example/pr/7"}},
2838            "author": {"display_name": "Alice"},
2839            "destination": {"branch": {"name": "main"}, "commit": {"hash": "base"},
2840                "repository": {"full_name": "w/r", "links": {"html": {"href": "https://example/w/r"}}}},
2841            "source": {"branch": {"name": "feature"}, "commit": {"hash": "head"},
2842                "repository": {"full_name": "w/r", "links": {"html": {"href": "https://example/w/r"}}}},
2843            "created_on": "2026-01-01T00:00:00Z", "updated_on": "2026-01-02T00:00:00Z",
2844            "participants": [{"approved": true, "state": "approved",
2845                "user": {"display_name": "Bob", "uuid": "{bob}"}}]
2846        })
2847    }
2848
2849    fn github_summary(number: u64, state: &str) -> Value {
2850        json!({
2851            "number": number,
2852            "title": format!("Change {number}"),
2853            "html_url": format!("https://github.example/o/r/pull/{number}"),
2854            "state": state,
2855            "merged_at": null,
2856            "draft": false,
2857            "user": {"login": "alice"},
2858            "base": {"ref": "main"},
2859            "head": {"ref": format!("feature-{number}")},
2860            "created_at": "2026-01-01T00:00:00Z",
2861            "updated_at": "2026-01-02T00:00:00Z"
2862        })
2863    }
2864
2865    fn bitbucket_summary(number: u64, state: &str) -> Value {
2866        json!({
2867            "id": number,
2868            "title": format!("Change {number}"),
2869            "state": state,
2870            "draft": false,
2871            "links": {"html": {"href": format!("https://bitbucket.example/w/r/pull-requests/{number}")}},
2872            "author": {"display_name": "Alice"},
2873            "destination": {"branch": {"name": "main"}},
2874            "source": {"branch": {"name": format!("feature-{number}")}},
2875            "created_on": "2026-01-01T00:00:00Z",
2876            "updated_on": "2026-01-02T00:00:00Z"
2877        })
2878    }
2879
2880    fn github_config() -> PullRequestProviderConfig {
2881        PullRequestProviderConfig {
2882            enabled: true,
2883            cache_ttl_seconds: 60,
2884            ..PullRequestProviderConfig::default()
2885        }
2886    }
2887
2888    fn bitbucket_config() -> PullRequestProviderConfig {
2889        PullRequestProviderConfig {
2890            enabled: true,
2891            cache_ttl_seconds: 60,
2892            ..PullRequestProviderConfig::bitbucket_cloud()
2893        }
2894    }
2895
2896    fn request(kind: PullRequestProviderKind) -> PullRequestInspectRequest {
2897        PullRequestInspectRequest {
2898            coordinates: PullRequestCoordinates {
2899                provider: kind,
2900                owner: "o".to_owned(),
2901                repository: "r".to_owned(),
2902                number: 1,
2903            },
2904            consent_to_remote_access: true,
2905            cancellation: CancellationToken::new(),
2906        }
2907    }
2908
2909    fn list_request(kind: PullRequestProviderKind) -> PullRequestListRequest {
2910        PullRequestListRequest {
2911            provider: kind,
2912            owner: "o".to_owned(),
2913            repository: "r".to_owned(),
2914            state: PullRequestListState::All,
2915            cursor: None,
2916            limit: 10,
2917            consent_to_remote_access: true,
2918            cancellation: CancellationToken::new(),
2919        }
2920    }
2921
2922    fn github_success_responses() -> Vec<PrHttpResponse> {
2923        vec![
2924            response(200, &github_metadata()),
2925            response(
2926                200,
2927                &json!([{"filename":"src/lib.rs","status":"modified","additions":2,"deletions":1,"patch":"secret source"}]),
2928            ),
2929            response(
2930                200,
2931                &json!({"check_runs":[{"name":"test","status":"completed","conclusion":"success"}]}),
2932            ),
2933            response(
2934                200,
2935                &json!([{"id":1,"user":{"login":"bob"},"state":"APPROVED","submitted_at":"2026-01-02T00:00:00Z"}]),
2936            ),
2937        ]
2938    }
2939
2940    fn semantic(name: &str) -> PullRequestSemanticInput {
2941        PullRequestSemanticInput {
2942            fingerprint: name.to_owned(),
2943            files: BTreeSet::new(),
2944            contracts: BTreeSet::new(),
2945            services: BTreeSet::new(),
2946            communities: BTreeSet::new(),
2947            depends_on: BTreeSet::new(),
2948            readiness: PullRequestReadiness::Ready,
2949        }
2950    }
2951
2952    #[test]
2953    fn default_configuration_is_disabled() {
2954        assert!(!PullRequestProviderConfig::default().enabled);
2955    }
2956
2957    #[test]
2958    fn configuration_rejects_non_https_remote_url() {
2959        let config = PullRequestProviderConfig {
2960            api_base_url: "http://example.com".to_owned(),
2961            api_base_url_allowlist: vec!["http://example.com".to_owned()],
2962            ..PullRequestProviderConfig::default()
2963        };
2964        assert!(matches!(
2965            config.validate(),
2966            Err(PullRequestError::InvalidConfiguration(_))
2967        ));
2968    }
2969
2970    #[test]
2971    fn configuration_allows_explicit_loopback_mock() {
2972        let config = PullRequestProviderConfig {
2973            api_base_url: "http://127.0.0.1:8080".to_owned(),
2974            allow_loopback_http: true,
2975            ..PullRequestProviderConfig::default()
2976        };
2977        assert_eq!(config.validate(), Ok(()));
2978    }
2979
2980    #[test]
2981    fn token_is_redacted_from_debug_and_serialization() {
2982        let config = PullRequestProviderConfig {
2983            auth_token: PrAuthToken::new("top-secret"),
2984            ..PullRequestProviderConfig::default()
2985        };
2986        let rendered = format!(
2987            "{config:?} {}",
2988            serde_json::to_string(&config).expect("JSON")
2989        );
2990        assert!(!rendered.contains("top-secret"));
2991    }
2992
2993    #[tokio::test]
2994    async fn github_rejects_disabled_provider_without_transport() {
2995        let transport = MockTransport::default();
2996        let provider =
2997            GitHubProvider::new(PullRequestProviderConfig::default(), Arc::new(transport))
2998                .expect("provider");
2999        let error = provider
3000            .inspect(request(PullRequestProviderKind::GitHub))
3001            .await
3002            .expect_err("disabled");
3003        assert_eq!(error, PullRequestError::Disabled);
3004    }
3005
3006    #[tokio::test]
3007    async fn github_requires_per_request_consent() {
3008        let transport = Arc::new(MockTransport::default());
3009        let provider = GitHubProvider::new(github_config(), transport.clone()).expect("provider");
3010        let mut input = request(PullRequestProviderKind::GitHub);
3011        input.consent_to_remote_access = false;
3012        let error = provider.inspect(input).await.expect_err("consent");
3013        assert_eq!(
3014            (error, transport.request_count()),
3015            (PullRequestError::ConsentRequired, 0)
3016        );
3017    }
3018
3019    #[tokio::test]
3020    async fn github_parses_success_without_retaining_patch() {
3021        let transport = MockTransport::with(github_success_responses());
3022        let provider = GitHubProvider::new(github_config(), transport).expect("provider");
3023        let result = provider
3024            .inspect(request(PullRequestProviderKind::GitHub))
3025            .await
3026            .expect("inspection");
3027        let serialized = serde_json::to_string(&result).expect("JSON");
3028        assert_eq!(
3029            (
3030                result.changed_files[0].patch_truncated,
3031                result.ci.state,
3032                result.review.state,
3033                serialized.contains("secret source"),
3034            ),
3035            (true, CheckState::Success, ReviewState::Approved, false)
3036        );
3037    }
3038
3039    #[tokio::test]
3040    async fn github_uses_fresh_structured_cache() {
3041        let transport = MockTransport::with(github_success_responses());
3042        let provider = GitHubProvider::new(github_config(), transport.clone()).expect("provider");
3043        provider
3044            .inspect(request(PullRequestProviderKind::GitHub))
3045            .await
3046            .expect("first");
3047        let second = provider
3048            .inspect(request(PullRequestProviderKind::GitHub))
3049            .await
3050            .expect("second");
3051        assert_eq!((second.from_cache, transport.request_count()), (true, 4));
3052    }
3053
3054    #[tokio::test]
3055    async fn github_reports_rate_limit_without_sleeping() {
3056        let mut limited = response(429, &json!({"message":"slow down"}));
3057        limited
3058            .headers
3059            .insert("retry-after".to_owned(), "12".to_owned());
3060        let transport = MockTransport::with(vec![limited]);
3061        let provider = GitHubProvider::new(github_config(), transport).expect("provider");
3062        let error = provider
3063            .inspect(request(PullRequestProviderKind::GitHub))
3064            .await
3065            .expect_err("rate limit");
3066        assert!(matches!(
3067            error,
3068            PullRequestError::RateLimited {
3069                metadata: PullRequestRateLimit {
3070                    retry_after_seconds: Some(12),
3071                    ..
3072                },
3073                ..
3074            }
3075        ));
3076    }
3077
3078    #[tokio::test]
3079    async fn github_redacts_token_from_api_error() {
3080        let transport = MockTransport::with(vec![response(
3081            401,
3082            &json!({"message":"token top-secret is invalid"}),
3083        )]);
3084        let mut config = github_config();
3085        config.auth_token = PrAuthToken::new("top-secret");
3086        let provider = GitHubProvider::new(config, transport).expect("provider");
3087        let error = provider
3088            .inspect(request(PullRequestProviderKind::GitHub))
3089            .await
3090            .expect_err("API error");
3091        assert!(!error.to_string().contains("top-secret"));
3092    }
3093
3094    #[tokio::test]
3095    async fn github_rejects_malformed_metadata() {
3096        let transport = MockTransport::with(vec![response(200, &json!({"id": 1}))]);
3097        let provider = GitHubProvider::new(github_config(), transport).expect("provider");
3098        assert!(matches!(
3099            provider
3100                .inspect(request(PullRequestProviderKind::GitHub))
3101                .await,
3102            Err(PullRequestError::MalformedResponse(_))
3103        ));
3104    }
3105
3106    #[tokio::test]
3107    async fn github_follows_link_header_pagination() {
3108        let mut first_page = response(
3109            200,
3110            &json!([{"filename":"a.rs","status":"added","additions":1,"deletions":0}]),
3111        );
3112        first_page.headers.insert(
3113            "link".to_owned(),
3114            r#"<https://api.github.com/repos/o/r/pulls/1/files?page=2>; rel="next""#.to_owned(),
3115        );
3116        let transport = MockTransport::with(vec![
3117            response(200, &github_metadata()),
3118            first_page,
3119            response(
3120                200,
3121                &json!([{"filename":"b.rs","status":"added","additions":1,"deletions":0}]),
3122            ),
3123            response(200, &json!({"check_runs":[]})),
3124            response(200, &json!([])),
3125        ]);
3126        let provider = GitHubProvider::new(github_config(), transport).expect("provider");
3127        let result = provider
3128            .inspect(request(PullRequestProviderKind::GitHub))
3129            .await
3130            .expect("inspection");
3131        assert_eq!(result.changed_files.len(), 2);
3132    }
3133
3134    #[tokio::test]
3135    async fn github_revalidates_stale_cache_with_etag() {
3136        let mut responses = github_success_responses();
3137        responses[0]
3138            .headers
3139            .insert("etag".to_owned(), r#""version-1""#.to_owned());
3140        responses.push(PrHttpResponse {
3141            status: 304,
3142            headers: BTreeMap::new(),
3143            body: Vec::new(),
3144        });
3145        let transport = MockTransport::with(responses);
3146        let mut config = github_config();
3147        config.cache_ttl_seconds = 0;
3148        let provider = GitHubProvider::new(config, transport.clone()).expect("provider");
3149        provider
3150            .inspect(request(PullRequestProviderKind::GitHub))
3151            .await
3152            .expect("first");
3153        let second = provider
3154            .inspect(request(PullRequestProviderKind::GitHub))
3155            .await
3156            .expect("revalidated");
3157        assert_eq!(
3158            (
3159                second.from_cache,
3160                transport.request_count(),
3161                transport.request_header(4, "if-none-match"),
3162            ),
3163            (true, 5, Some(r#""version-1""#.to_owned()))
3164        );
3165    }
3166
3167    #[tokio::test]
3168    async fn github_honors_cancellation_before_transport() {
3169        let transport = Arc::new(MockTransport::default());
3170        let provider = GitHubProvider::new(github_config(), transport.clone()).expect("provider");
3171        let input = request(PullRequestProviderKind::GitHub);
3172        input.cancellation.cancel();
3173        let error = provider.inspect(input).await.expect_err("cancelled");
3174        assert_eq!(
3175            (error, transport.request_count()),
3176            (PullRequestError::Cancelled, 0)
3177        );
3178    }
3179
3180    #[tokio::test]
3181    async fn github_list_returns_source_free_summaries_in_provider_number_order() {
3182        let mut page = response(
3183            200,
3184            &json!([github_summary(9, "open"), github_summary(2, "open")]),
3185        );
3186        page.headers
3187            .insert("x-ratelimit-remaining".to_owned(), "42".to_owned());
3188        let transport = MockTransport::with(vec![page]);
3189        let provider = GitHubProvider::new(github_config(), transport.clone()).expect("provider");
3190        let result = provider
3191            .list(list_request(PullRequestProviderKind::GitHub))
3192            .await
3193            .expect("list page");
3194        let serialized = serde_json::to_string(&result).expect("JSON");
3195        assert_eq!(
3196            (
3197                result
3198                    .items
3199                    .iter()
3200                    .map(|summary| summary.coordinates.number)
3201                    .collect::<Vec<_>>(),
3202                result.rate_limit.remaining,
3203                serialized.contains("patch"),
3204                transport
3205                    .request_url(0)
3206                    .is_some_and(|url| url.contains("state=all") && url.contains("per_page=10")),
3207            ),
3208            (vec![2, 9], Some(42), false, true)
3209        );
3210    }
3211
3212    #[tokio::test]
3213    async fn github_list_requires_consent_before_transport() {
3214        let transport = Arc::new(MockTransport::default());
3215        let provider = GitHubProvider::new(github_config(), transport.clone()).expect("provider");
3216        let mut input = list_request(PullRequestProviderKind::GitHub);
3217        input.consent_to_remote_access = false;
3218        let error = provider.list(input).await.expect_err("consent");
3219        assert_eq!(
3220            (error, transport.request_count()),
3221            (PullRequestError::ConsentRequired, 0)
3222        );
3223    }
3224
3225    #[tokio::test]
3226    async fn github_list_rejects_disabled_provider_before_transport() {
3227        let transport = Arc::new(MockTransport::default());
3228        let provider = GitHubProvider::new(PullRequestProviderConfig::default(), transport.clone())
3229            .expect("provider");
3230        let error = provider
3231            .list(list_request(PullRequestProviderKind::GitHub))
3232            .await
3233            .expect_err("disabled");
3234        assert_eq!(
3235            (error, transport.request_count()),
3236            (PullRequestError::Disabled, 0)
3237        );
3238    }
3239
3240    #[tokio::test]
3241    async fn github_list_rejects_zero_limit_before_transport() {
3242        let transport = Arc::new(MockTransport::default());
3243        let provider = GitHubProvider::new(github_config(), transport.clone()).expect("provider");
3244        let mut input = list_request(PullRequestProviderKind::GitHub);
3245        input.limit = 0;
3246        let error = provider.list(input).await.expect_err("invalid limit");
3247        assert!(matches!(
3248            (error, transport.request_count()),
3249            (PullRequestError::InvalidConfiguration(_), 0)
3250        ));
3251    }
3252
3253    #[tokio::test]
3254    async fn github_list_rejects_limit_above_one_hundred_before_transport() {
3255        let transport = Arc::new(MockTransport::default());
3256        let provider = GitHubProvider::new(github_config(), transport.clone()).expect("provider");
3257        let mut input = list_request(PullRequestProviderKind::GitHub);
3258        input.limit = 101;
3259        let error = provider.list(input).await.expect_err("invalid limit");
3260        assert!(matches!(
3261            (error, transport.request_count()),
3262            (PullRequestError::InvalidConfiguration(_), 0)
3263        ));
3264    }
3265
3266    #[tokio::test]
3267    async fn github_list_round_trips_same_origin_page_cursor() {
3268        let mut first = response(200, &json!([github_summary(1, "open")]));
3269        first.headers.insert(
3270            "link".to_owned(),
3271            r#"<https://api.github.com/repos/o/r/pulls?state=all&per_page=10&page=2>; rel="next""#
3272                .to_owned(),
3273        );
3274        let transport = MockTransport::with(vec![
3275            first,
3276            response(200, &json!([github_summary(2, "open")])),
3277        ]);
3278        let provider = GitHubProvider::new(github_config(), transport.clone()).expect("provider");
3279        let first_page = provider
3280            .list(list_request(PullRequestProviderKind::GitHub))
3281            .await
3282            .expect("first page");
3283        let mut second_request = list_request(PullRequestProviderKind::GitHub);
3284        second_request.cursor = first_page.next_cursor;
3285        let second_page = provider.list(second_request).await.expect("second page");
3286        assert_eq!(
3287            (
3288                first_page.has_more,
3289                second_page.items[0].coordinates.number,
3290                transport
3291                    .request_url(1)
3292                    .is_some_and(|url| url.contains("page=2")),
3293            ),
3294            (true, 2, true)
3295        );
3296    }
3297
3298    #[tokio::test]
3299    async fn github_list_rejects_cross_origin_pagination() {
3300        let mut page = response(200, &json!([github_summary(1, "open")]));
3301        page.headers.insert(
3302            "link".to_owned(),
3303            r#"<https://attacker.invalid/repos/o/r/pulls?page=2>; rel="next""#.to_owned(),
3304        );
3305        let transport = MockTransport::with(vec![page]);
3306        let provider = GitHubProvider::new(github_config(), transport).expect("provider");
3307        assert!(matches!(
3308            provider
3309                .list(list_request(PullRequestProviderKind::GitHub))
3310                .await,
3311            Err(PullRequestError::MalformedResponse(_))
3312        ));
3313    }
3314
3315    #[tokio::test]
3316    async fn github_list_reports_missing_scope_as_api_error() {
3317        let transport = MockTransport::with(vec![response(
3318            403,
3319            &json!({"message":"resource not accessible by token"}),
3320        )]);
3321        let provider = GitHubProvider::new(github_config(), transport).expect("provider");
3322        assert!(matches!(
3323            provider
3324                .list(list_request(PullRequestProviderKind::GitHub))
3325                .await,
3326            Err(PullRequestError::Api { status: 403, .. })
3327        ));
3328    }
3329
3330    #[tokio::test]
3331    async fn github_list_redacts_token_from_api_error() {
3332        let transport = MockTransport::with(vec![response(
3333            401,
3334            &json!({"message":"token list-secret is invalid"}),
3335        )]);
3336        let mut config = github_config();
3337        config.auth_token = PrAuthToken::new("list-secret");
3338        let provider = GitHubProvider::new(config, transport).expect("provider");
3339        let error = provider
3340            .list(list_request(PullRequestProviderKind::GitHub))
3341            .await
3342            .expect_err("API error");
3343        assert!(!error.to_string().contains("list-secret"));
3344    }
3345
3346    #[tokio::test]
3347    async fn github_list_marks_configured_page_reduction_as_truncated() {
3348        let mut page = response(200, &json!([github_summary(1, "open")]));
3349        page.headers.insert(
3350            "link".to_owned(),
3351            r#"<https://api.github.com/repos/o/r/pulls?state=all&per_page=1&page=2>; rel="next""#
3352                .to_owned(),
3353        );
3354        let transport = MockTransport::with(vec![page]);
3355        let mut config = github_config();
3356        config.max_items = 1;
3357        let provider = GitHubProvider::new(config, transport).expect("provider");
3358        let result = provider
3359            .list(list_request(PullRequestProviderKind::GitHub))
3360            .await
3361            .expect("bounded page");
3362        assert_eq!(
3363            (
3364                result.truncated,
3365                result.warnings.first().map(|warning| warning.code.as_str()),
3366            ),
3367            (true, Some("configured_limit_applied"))
3368        );
3369    }
3370
3371    #[tokio::test]
3372    async fn list_reports_bitbucket_data_center_as_unsupported_without_transport() {
3373        let transport = Arc::new(MockTransport::default());
3374        let provider = GitHubProvider::new(github_config(), transport.clone()).expect("provider");
3375        let error = provider
3376            .list(list_request(PullRequestProviderKind::BitbucketDataCenter))
3377            .await
3378            .expect_err("unsupported provider");
3379        assert_eq!(
3380            (error, transport.request_count()),
3381            (PullRequestError::UnsupportedProvider, 0)
3382        );
3383    }
3384
3385    #[tokio::test]
3386    async fn bitbucket_parses_success_and_participant_approval() {
3387        let transport = MockTransport::with(vec![
3388            response(200, &bitbucket_metadata()),
3389            response(
3390                200,
3391                &json!({"values":[{"status":"modified","old":{"path":"a"},"new":{"path":"a"},"lines_added":3,"lines_removed":1}]}),
3392            ),
3393            response(
3394                200,
3395                &json!({"values":[{"key":"build","state":"SUCCESSFUL"}]}),
3396            ),
3397        ]);
3398        let provider = BitbucketProvider::new(bitbucket_config(), transport).expect("provider");
3399        let result = provider
3400            .inspect(request(PullRequestProviderKind::BitbucketCloud))
3401            .await
3402            .expect("inspection");
3403        assert_eq!(
3404            (result.review.approvals, result.ci.state),
3405            (1, CheckState::Success)
3406        );
3407    }
3408
3409    #[tokio::test]
3410    async fn bitbucket_api_token_should_use_basic_auth_with_atlassian_email() {
3411        let transport = MockTransport::with(vec![
3412            response(200, &bitbucket_metadata()),
3413            response(200, &json!({"values":[]})),
3414            response(200, &json!({"values":[]})),
3415        ]);
3416        let mut config = bitbucket_config();
3417        config.auth_token = PrAuthToken::new("api-token");
3418        config.basic_auth_username = Some("user@example.com".to_owned());
3419        let provider =
3420            BitbucketProvider::new(config, transport.clone()).expect("Bitbucket provider");
3421        provider
3422            .inspect(request(PullRequestProviderKind::BitbucketCloud))
3423            .await
3424            .expect("inspection");
3425        assert!(matches!(
3426            transport.request_authentication(0),
3427            Some(PrHttpAuthentication::Basic { username, token })
3428                if username == "user@example.com" && token.expose_secret() == "api-token"
3429        ));
3430    }
3431
3432    #[tokio::test]
3433    async fn bitbucket_should_follow_same_origin_diffstat_redirect_and_degrade_missing_scopes() {
3434        let transport = MockTransport::with(vec![
3435            response(200, &bitbucket_metadata()),
3436            PrHttpResponse {
3437                status: 302,
3438                headers: BTreeMap::from([(
3439                    "location".to_owned(),
3440                    "https://api.bitbucket.org/2.0/repositories/o/r/diffstat/base..head".to_owned(),
3441                )]),
3442                body: Vec::new(),
3443            },
3444            response(
3445                403,
3446                &json!({"error":{"message":"missing repository scope"}}),
3447            ),
3448            response(
3449                403,
3450                &json!({"error":{"message":"missing repository scope"}}),
3451            ),
3452        ]);
3453        let provider =
3454            BitbucketProvider::new(bitbucket_config(), transport.clone()).expect("provider");
3455        let result = provider
3456            .inspect(request(PullRequestProviderKind::BitbucketCloud))
3457            .await
3458            .expect("degraded inspection");
3459        assert_eq!(
3460            (
3461                result.changed_files.len(),
3462                result.ci.state,
3463                result.warnings.len(),
3464                transport.request_count(),
3465            ),
3466            (0, CheckState::Unknown, 2, 4)
3467        );
3468        assert!(
3469            result
3470                .warnings
3471                .iter()
3472                .all(|warning| warning.code == "provider_scope_missing")
3473        );
3474    }
3475
3476    #[tokio::test]
3477    async fn bitbucket_should_reject_cross_origin_redirect_without_forwarding_credentials() {
3478        let transport = MockTransport::with(vec![
3479            response(200, &bitbucket_metadata()),
3480            PrHttpResponse {
3481                status: 302,
3482                headers: BTreeMap::from([(
3483                    "location".to_owned(),
3484                    "https://attacker.invalid/diffstat".to_owned(),
3485                )]),
3486                body: Vec::new(),
3487            },
3488        ]);
3489        let provider =
3490            BitbucketProvider::new(bitbucket_config(), transport.clone()).expect("provider");
3491        let error = provider
3492            .inspect(request(PullRequestProviderKind::BitbucketCloud))
3493            .await
3494            .expect_err("cross-origin redirect");
3495        assert!(matches!(
3496            error,
3497            PullRequestError::Api { message, .. } if message.contains("crossed")
3498        ));
3499        assert_eq!(transport.request_count(), 2);
3500    }
3501
3502    #[tokio::test]
3503    async fn bitbucket_follows_diffstat_pagination() {
3504        let transport = MockTransport::with(vec![
3505            response(200, &bitbucket_metadata()),
3506            response(
3507                200,
3508                &json!({"values":[], "next":"https://api.bitbucket.org/2.0/next"}),
3509            ),
3510            response(
3511                200,
3512                &json!({"values":[{"status":"added","new":{"path":"a"},"lines_added":1,"lines_removed":0}]}),
3513            ),
3514            response(200, &json!({"values":[]})),
3515        ]);
3516        let provider =
3517            BitbucketProvider::new(bitbucket_config(), transport.clone()).expect("provider");
3518        let result = provider
3519            .inspect(request(PullRequestProviderKind::BitbucketCloud))
3520            .await
3521            .expect("inspection");
3522        assert_eq!(
3523            (result.changed_files.len(), transport.request_count()),
3524            (1, 4)
3525        );
3526    }
3527
3528    #[tokio::test]
3529    async fn bitbucket_uses_fresh_structured_cache() {
3530        let transport = MockTransport::with(vec![
3531            response(200, &bitbucket_metadata()),
3532            response(200, &json!({"values":[]})),
3533            response(200, &json!({"values":[]})),
3534        ]);
3535        let provider =
3536            BitbucketProvider::new(bitbucket_config(), transport.clone()).expect("provider");
3537        provider
3538            .inspect(request(PullRequestProviderKind::BitbucketCloud))
3539            .await
3540            .expect("first");
3541        let second = provider
3542            .inspect(request(PullRequestProviderKind::BitbucketCloud))
3543            .await
3544            .expect("second");
3545        assert_eq!((second.from_cache, transport.request_count()), (true, 3));
3546    }
3547
3548    #[tokio::test]
3549    async fn bitbucket_reports_rate_limit_metadata() {
3550        let mut limited = response(403, &json!({"error":{"message":"quota"}}));
3551        limited
3552            .headers
3553            .insert("x-ratelimit-remaining".to_owned(), "0".to_owned());
3554        let transport = MockTransport::with(vec![limited]);
3555        let provider = BitbucketProvider::new(bitbucket_config(), transport).expect("provider");
3556        let error = provider
3557            .inspect(request(PullRequestProviderKind::BitbucketCloud))
3558            .await
3559            .expect_err("rate limit");
3560        assert!(matches!(
3561            error,
3562            PullRequestError::RateLimited {
3563                metadata: PullRequestRateLimit {
3564                    remaining: Some(0),
3565                    ..
3566                },
3567                ..
3568            }
3569        ));
3570    }
3571
3572    #[tokio::test]
3573    async fn bitbucket_requires_per_request_consent() {
3574        let transport = Arc::new(MockTransport::default());
3575        let provider =
3576            BitbucketProvider::new(bitbucket_config(), transport.clone()).expect("provider");
3577        let mut input = request(PullRequestProviderKind::BitbucketCloud);
3578        input.consent_to_remote_access = false;
3579        let error = provider.inspect(input).await.expect_err("consent");
3580        assert_eq!(
3581            (error, transport.request_count()),
3582            (PullRequestError::ConsentRequired, 0)
3583        );
3584    }
3585
3586    #[tokio::test]
3587    async fn bitbucket_redacts_token_from_api_error() {
3588        let transport = MockTransport::with(vec![response(
3589            400,
3590            &json!({"error":{"message":"credential bb-secret rejected"}}),
3591        )]);
3592        let mut config = bitbucket_config();
3593        config.auth_token = PrAuthToken::new("bb-secret");
3594        let provider = BitbucketProvider::new(config, transport).expect("provider");
3595        let error = provider
3596            .inspect(request(PullRequestProviderKind::BitbucketCloud))
3597            .await
3598            .expect_err("API error");
3599        assert!(!error.to_string().contains("bb-secret"));
3600    }
3601
3602    #[tokio::test]
3603    async fn bitbucket_rejects_cross_origin_pagination() {
3604        let transport = MockTransport::with(vec![
3605            response(200, &bitbucket_metadata()),
3606            response(
3607                200,
3608                &json!({"values":[], "next":"https://evil.example/next"}),
3609            ),
3610        ]);
3611        let provider = BitbucketProvider::new(bitbucket_config(), transport).expect("provider");
3612        assert!(matches!(
3613            provider
3614                .inspect(request(PullRequestProviderKind::BitbucketCloud))
3615                .await,
3616            Err(PullRequestError::MalformedResponse(_))
3617        ));
3618    }
3619
3620    #[tokio::test]
3621    async fn bitbucket_list_returns_source_free_summaries_in_provider_number_order() {
3622        let transport = MockTransport::with(vec![response(
3623            200,
3624            &json!({
3625                "values": [
3626                    bitbucket_summary(8, "OPEN"),
3627                    bitbucket_summary(3, "DECLINED")
3628                ]
3629            }),
3630        )]);
3631        let provider =
3632            BitbucketProvider::new(bitbucket_config(), transport.clone()).expect("provider");
3633        let mut input = list_request(PullRequestProviderKind::BitbucketCloud);
3634        input.state = PullRequestListState::Open;
3635        let result = provider.list(input).await.expect("list page");
3636        assert_eq!(
3637            (
3638                result
3639                    .items
3640                    .iter()
3641                    .map(|summary| summary.coordinates.number)
3642                    .collect::<Vec<_>>(),
3643                transport.request_url(0).is_some_and(|url| {
3644                    url.contains("pagelen=10") && url.contains("state=OPEN")
3645                }),
3646            ),
3647            (vec![3, 8], true)
3648        );
3649    }
3650
3651    #[tokio::test]
3652    async fn bitbucket_list_requires_consent_before_transport() {
3653        let transport = Arc::new(MockTransport::default());
3654        let provider =
3655            BitbucketProvider::new(bitbucket_config(), transport.clone()).expect("provider");
3656        let mut input = list_request(PullRequestProviderKind::BitbucketCloud);
3657        input.consent_to_remote_access = false;
3658        let error = provider.list(input).await.expect_err("consent");
3659        assert_eq!(
3660            (error, transport.request_count()),
3661            (PullRequestError::ConsentRequired, 0)
3662        );
3663    }
3664
3665    #[tokio::test]
3666    async fn bitbucket_list_round_trips_same_origin_page_cursor() {
3667        let transport = MockTransport::with(vec![
3668            response(
3669                200,
3670                &json!({
3671                    "values": [bitbucket_summary(1, "OPEN")],
3672                    "next": "https://api.bitbucket.org/2.0/repositories/o/r/pullrequests?pagelen=10&page=2"
3673                }),
3674            ),
3675            response(200, &json!({"values": [bitbucket_summary(2, "OPEN")]})),
3676        ]);
3677        let provider =
3678            BitbucketProvider::new(bitbucket_config(), transport.clone()).expect("provider");
3679        let first_page = provider
3680            .list(list_request(PullRequestProviderKind::BitbucketCloud))
3681            .await
3682            .expect("first page");
3683        let mut second_request = list_request(PullRequestProviderKind::BitbucketCloud);
3684        second_request.cursor = first_page.next_cursor;
3685        let second_page = provider.list(second_request).await.expect("second page");
3686        assert_eq!(
3687            (
3688                first_page.has_more,
3689                second_page.items[0].coordinates.number,
3690                transport
3691                    .request_url(1)
3692                    .is_some_and(|url| url.contains("page=2")),
3693            ),
3694            (true, 2, true)
3695        );
3696    }
3697
3698    #[tokio::test]
3699    async fn bitbucket_list_rejects_cross_origin_pagination() {
3700        let transport = MockTransport::with(vec![response(
3701            200,
3702            &json!({
3703                "values": [bitbucket_summary(1, "OPEN")],
3704                "next": "https://attacker.invalid/repositories/o/r/pullrequests?page=2"
3705            }),
3706        )]);
3707        let provider = BitbucketProvider::new(bitbucket_config(), transport).expect("provider");
3708        assert!(matches!(
3709            provider
3710                .list(list_request(PullRequestProviderKind::BitbucketCloud))
3711                .await,
3712            Err(PullRequestError::MalformedResponse(_))
3713        ));
3714    }
3715
3716    #[tokio::test]
3717    async fn bitbucket_list_reports_missing_scope_as_api_error() {
3718        let transport = MockTransport::with(vec![response(
3719            403,
3720            &json!({"error":{"message":"missing pullrequest scope"}}),
3721        )]);
3722        let provider = BitbucketProvider::new(bitbucket_config(), transport).expect("provider");
3723        assert!(matches!(
3724            provider
3725                .list(list_request(PullRequestProviderKind::BitbucketCloud))
3726                .await,
3727            Err(PullRequestError::Api { status: 403, .. })
3728        ));
3729    }
3730
3731    #[tokio::test]
3732    async fn bitbucket_list_redacts_token_from_api_error() {
3733        let transport = MockTransport::with(vec![response(
3734            401,
3735            &json!({"error":{"message":"credential bb-list-secret rejected"}}),
3736        )]);
3737        let mut config = bitbucket_config();
3738        config.auth_token = PrAuthToken::new("bb-list-secret");
3739        let provider = BitbucketProvider::new(config, transport).expect("provider");
3740        let error = provider
3741            .list(list_request(PullRequestProviderKind::BitbucketCloud))
3742            .await
3743            .expect_err("API error");
3744        assert!(!error.to_string().contains("bb-list-secret"));
3745    }
3746
3747    #[test]
3748    fn overlap_is_disjoint_for_unrelated_inputs() {
3749        assert_eq!(
3750            semantic_pull_request_overlap(&semantic("a"), &semantic("b")).kind,
3751            PullRequestOverlapKind::Disjoint
3752        );
3753    }
3754
3755    #[test]
3756    fn overlap_classifies_shared_file_deterministically() {
3757        let mut left = semantic("a");
3758        let mut right = semantic("b");
3759        left.files.extend(["z.rs".to_owned(), "a.rs".to_owned()]);
3760        right.files.extend(["a.rs".to_owned(), "z.rs".to_owned()]);
3761        assert_eq!(
3762            semantic_pull_request_overlap(&left, &right).files,
3763            vec!["a.rs".to_owned(), "z.rs".to_owned()]
3764        );
3765    }
3766
3767    #[test]
3768    fn overlap_classifies_shared_service() {
3769        let mut left = semantic("a");
3770        let mut right = semantic("b");
3771        left.services.insert("billing".to_owned());
3772        right.services.insert("billing".to_owned());
3773        assert_eq!(
3774            semantic_pull_request_overlap(&left, &right).kind,
3775            PullRequestOverlapKind::Service
3776        );
3777    }
3778
3779    #[test]
3780    fn overlap_classifies_shared_community() {
3781        let mut left = semantic("a");
3782        let mut right = semantic("b");
3783        left.communities.insert("community-1".to_owned());
3784        right.communities.insert("community-1".to_owned());
3785        assert_eq!(
3786            semantic_pull_request_overlap(&left, &right).kind,
3787            PullRequestOverlapKind::Community
3788        );
3789    }
3790
3791    #[test]
3792    fn overlap_marks_shared_migration_conflicting() {
3793        let mut left = semantic("a");
3794        let mut right = semantic("b");
3795        left.files.insert("migrations/001.sql".to_owned());
3796        right.files.insert("migrations/001.sql".to_owned());
3797        assert_eq!(
3798            semantic_pull_request_overlap(&left, &right).kind,
3799            PullRequestOverlapKind::Conflicting
3800        );
3801    }
3802
3803    #[test]
3804    fn order_follows_dependency_direction() {
3805        let left = semantic("a");
3806        let mut right = semantic("b");
3807        right.depends_on.insert("a".to_owned());
3808        assert_eq!(
3809            suggest_pull_request_order(&left, &right).order,
3810            PullRequestOrder::LeftFirst
3811        );
3812    }
3813
3814    #[test]
3815    fn order_coordinates_dependency_cycle() {
3816        let mut left = semantic("a");
3817        let mut right = semantic("b");
3818        left.depends_on.insert("b".to_owned());
3819        right.depends_on.insert("a".to_owned());
3820        assert_eq!(
3821            suggest_pull_request_order(&left, &right).order,
3822            PullRequestOrder::Coordinated
3823        );
3824    }
3825
3826    #[test]
3827    fn order_is_indefinite_for_stale_readiness() {
3828        let mut left = semantic("a");
3829        left.readiness = PullRequestReadiness::Stale;
3830        assert_eq!(
3831            suggest_pull_request_order(&left, &semantic("b")).order,
3832            PullRequestOrder::NoDefinitiveOrder
3833        );
3834    }
3835
3836    #[test]
3837    fn order_prefers_ready_change_when_other_is_blocked() {
3838        let left = semantic("a");
3839        let mut right = semantic("b");
3840        right.readiness = PullRequestReadiness::Blocked;
3841        assert_eq!(
3842            suggest_pull_request_order(&left, &right).order,
3843            PullRequestOrder::LeftFirst
3844        );
3845    }
3846}