adler_core/
check.rs

1//! Verdict types produced when a site is probed.
2
3use std::collections::BTreeMap;
4use std::fmt;
5
6use serde::{Deserialize, Serialize};
7
8use crate::confidence::{ConfidenceScore, ConfidenceSignals};
9use crate::profile::{ProfileEvidence, ProfileEvidenceKind};
10
11/// Outcome of a single site probe.
12#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
13#[serde(rename_all = "snake_case")]
14pub enum MatchKind {
15    /// The account exists on this site.
16    Found,
17    /// The account does not exist on this site.
18    NotFound,
19    /// The response was inconclusive (network error, unexpected status,
20    /// ambiguous content). Reported separately so the user can review them
21    /// rather than silently dropping signal.
22    Uncertain,
23}
24
25impl MatchKind {
26    /// True if the verdict represents a positive (existing) account.
27    pub const fn is_found(self) -> bool {
28        matches!(self, Self::Found)
29    }
30}
31
32/// Why a probe was inconclusive.
33///
34/// `Uncertain` outcomes carry a typed reason rather than a free-form string,
35/// so logic that reacts to specific cases (e.g. retry on a transient ban)
36/// matches an enum variant instead of a fragile string. The [`fmt::Display`]
37/// rendering is what the CLI prints; serialization is the externally-tagged
38/// default (unit variants → a `snake_case` string, detail-carrying variants →
39/// `{ "network": "…" }`).
40#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
41#[serde(rename_all = "snake_case")]
42pub enum UncertainReason {
43    /// HTTP 429, or 503 with a `Retry-After` header.
44    RateLimited,
45    /// A Cloudflare interstitial / "checking your browser" page.
46    CloudflareChallenge,
47    /// A captcha gate.
48    Captcha,
49    /// The path is disallowed by the host's `robots.txt` (`--respect-robots`).
50    RobotsDisallowed,
51    /// The scan deadline elapsed before this site finished.
52    Deadline,
53    /// The executor's scheduler was closed (does not happen in practice).
54    SchedulerClosed,
55    /// A transport/network error while issuing the request.
56    Network(String),
57    /// An error reading the response body.
58    BodyRead(String),
59    /// A `bot-protected` site needed the browser backend but the per-scan
60    /// `--browser-budget` cap was already spent on earlier sites.
61    BrowserBudget,
62    /// The username doesn't satisfy the site's `regex_check`
63    /// (e.g. too short, contains forbidden characters). Reported
64    /// without issuing any HTTP request — saves both network and the
65    /// false-positive class where the site 404s on illegal usernames
66    /// in ways our signal can't tell apart from a missing account.
67    UsernameNotAllowed,
68    /// The browser backend itself failed (timeout, navigation error,
69    /// session drop, …) for a `bot-protected` site.
70    BrowserFailed(String),
71    /// The site's [`AccessPolicy`](crate::AccessPolicy) requires an
72    /// egress (country / IP type) that no configured proxy in the pool
73    /// satisfies, so the probe was skipped rather than fetched from the
74    /// wrong location. "Couldn't reach from the required geo" is not
75    /// "account absent" — hence `Uncertain`, never `NotFound`.
76    GeoUnavailable,
77    /// The site's [`AccessPolicy`](crate::AccessPolicy) names a session
78    /// (`access.session`) that wasn't supplied, so the probe was skipped
79    /// rather than sent unauthenticated into a login wall — which reads
80    /// the same for an existing and a missing account.
81    SessionRequired,
82    /// Any other reason (e.g. a `doctor` pre-flight skip).
83    Other(String),
84}
85
86impl fmt::Display for UncertainReason {
87    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
88        match self {
89            Self::RateLimited => f.write_str("rate_limited"),
90            Self::CloudflareChallenge => f.write_str("cloudflare_challenge"),
91            Self::Captcha => f.write_str("captcha"),
92            Self::RobotsDisallowed => f.write_str("robots_disallowed"),
93            Self::Deadline => f.write_str("deadline reached"),
94            Self::SchedulerClosed => f.write_str("scheduler closed"),
95            Self::Network(detail) => write!(f, "request: {detail}"),
96            Self::BodyRead(detail) => write!(f, "body read: {detail}"),
97            Self::BrowserBudget => f.write_str("browser_budget_exceeded"),
98            Self::UsernameNotAllowed => f.write_str("username_not_allowed"),
99            Self::BrowserFailed(detail) => write!(f, "browser: {detail}"),
100            Self::GeoUnavailable => f.write_str("geo_unavailable"),
101            Self::SessionRequired => f.write_str("session_required"),
102            Self::Other(detail) => f.write_str(detail),
103        }
104    }
105}
106
107/// Result of probing a single site for a username.
108#[derive(Debug, Clone, Serialize, Deserialize)]
109pub struct CheckOutcome {
110    /// Site name (matches `Site::name`).
111    pub site: String,
112    /// Concrete URL that was requested.
113    pub url: String,
114    /// Verdict produced by the site's detection strategy.
115    pub kind: MatchKind,
116    /// Why the outcome is `Uncertain`, if it is. `None` for `Found` /
117    /// `NotFound`.
118    #[serde(default, skip_serializing_if = "Option::is_none")]
119    pub reason: Option<UncertainReason>,
120    /// Wall-clock duration of the probe.
121    pub elapsed_ms: u64,
122    /// Fields extracted from a `Found` profile when `--enrich` is active
123    /// (e.g. `name`, `bio`, `avatar`). Empty unless enrichment ran and the
124    /// site has extractor rules. Ordered by field name.
125    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
126    pub enrichment: BTreeMap<String, String>,
127    /// Human-readable descriptions of the signals that produced the verdict —
128    /// e.g. `"HTTP 404 (status_not_found)"`. Empty for `Uncertain` (no signal
129    /// fired). Surfaced by `--explain`; always present in JSON output.
130    #[serde(default, skip_serializing_if = "Vec::is_empty")]
131    pub evidence: Vec<String>,
132    /// Normalized profile facts collected from extraction/enrichment. This is
133    /// distinct from the legacy `evidence` field above: `evidence` explains
134    /// the detection signal, while `profile_evidence` is structured product
135    /// data for confidence scoring, identity clustering, timelines, and
136    /// reports.
137    #[serde(default, skip_serializing_if = "Vec::is_empty")]
138    pub profile_evidence: Vec<ProfileEvidence>,
139    /// Explainable confidence in this per-site verdict.
140    #[serde(default)]
141    pub confidence: ConfidenceScore,
142    /// Which transport produced this outcome (HTTP / impersonate / browser).
143    /// `None` only on outcomes from older persisted scans saved before this
144    /// field existed; live scans always populate it.
145    #[serde(default, skip_serializing_if = "Option::is_none")]
146    pub transport: Option<crate::escalation::TransportTier>,
147    /// Number of *automatic* escalations to a heavier transport beyond the
148    /// site's primary route — usually 0, at most 1 today (HTTP / impersonate
149    /// → browser on `Uncertain(CloudflareChallenge | RateLimited)`).
150    /// Stamped so the doctor can spot sites where the primary route
151    /// systematically fails and the registry should pre-tag them.
152    #[serde(default, skip_serializing_if = "is_zero_u8")]
153    pub escalations: u8,
154}
155
156impl CheckOutcome {
157    /// Recompute confidence after callers attach signal or profile evidence.
158    pub fn refresh_confidence(&mut self) {
159        let access_paths = self
160            .profile_evidence
161            .iter()
162            .filter_map(|evidence| evidence.source.access_path.as_ref());
163        let authenticated_access = access_paths.clone().any(|path| path.authenticated);
164        let metadata_transport = access_paths.clone().map(|path| path.transport).next();
165        let metadata_escalated = access_paths.clone().any(|path| path.escalated);
166        let username_evidence_count = self
167            .profile_evidence
168            .iter()
169            .filter(|evidence| evidence.kind == ProfileEvidenceKind::Username)
170            .count();
171        let profile_evidence_count = self
172            .profile_evidence
173            .len()
174            .saturating_sub(username_evidence_count);
175        self.confidence = ConfidenceScore::from_signals(&ConfidenceSignals {
176            kind: self.kind,
177            reason: self.reason.clone(),
178            signal_evidence_count: self.evidence.len(),
179            profile_evidence_count,
180            username_evidence_count,
181            authenticated_access,
182            transport: metadata_transport.or(self.transport),
183            escalations: if metadata_escalated && self.escalations == 0 {
184                1
185            } else {
186                self.escalations
187            },
188        });
189    }
190}
191
192#[allow(clippy::trivially_copy_pass_by_ref)]
193fn is_zero_u8(n: &u8) -> bool {
194    *n == 0
195}
196
197#[cfg(test)]
198mod tests {
199    use super::*;
200
201    #[test]
202    fn match_kind_serialises_snake_case() {
203        assert_eq!(
204            serde_json::to_string(&MatchKind::Found).unwrap(),
205            "\"found\""
206        );
207        assert_eq!(
208            serde_json::to_string(&MatchKind::NotFound).unwrap(),
209            "\"not_found\""
210        );
211        assert_eq!(
212            serde_json::to_string(&MatchKind::Uncertain).unwrap(),
213            "\"uncertain\""
214        );
215    }
216
217    #[test]
218    fn match_kind_is_found() {
219        assert!(MatchKind::Found.is_found());
220        assert!(!MatchKind::NotFound.is_found());
221        assert!(!MatchKind::Uncertain.is_found());
222    }
223
224    #[test]
225    fn outcome_skips_absent_reason() {
226        let outcome = CheckOutcome {
227            site: "GitHub".into(),
228            url: "https://github.com/alice".into(),
229            kind: MatchKind::Found,
230            reason: None,
231            elapsed_ms: 42,
232            enrichment: BTreeMap::new(),
233            evidence: Vec::new(),
234            profile_evidence: Vec::new(),
235            confidence: ConfidenceScore::default(),
236            transport: None,
237            escalations: 0,
238        };
239        let json = serde_json::to_string(&outcome).unwrap();
240        assert!(
241            !json.contains("reason"),
242            "reason field must be omitted when None"
243        );
244        assert!(
245            !json.contains("enrichment"),
246            "enrichment must be omitted when empty"
247        );
248        assert!(
249            !json.contains("transport"),
250            "transport must be omitted when None"
251        );
252        assert!(
253            !json.contains("escalations"),
254            "escalations must be omitted when zero"
255        );
256        assert!(json.contains("\"kind\":\"found\""));
257        assert!(json.contains("\"elapsed_ms\":42"));
258    }
259
260    #[test]
261    fn unit_reason_serialises_as_snake_case_string() {
262        let outcome = CheckOutcome {
263            site: "GitHub".into(),
264            url: "https://github.com/alice".into(),
265            kind: MatchKind::Uncertain,
266            reason: Some(UncertainReason::RateLimited),
267            elapsed_ms: 5_000,
268            enrichment: BTreeMap::new(),
269            evidence: Vec::new(),
270            profile_evidence: Vec::new(),
271            confidence: ConfidenceScore::default(),
272            transport: None,
273            escalations: 0,
274        };
275        let json = serde_json::to_string(&outcome).unwrap();
276        assert!(json.contains("\"reason\":\"rate_limited\""), "{json}");
277    }
278
279    #[test]
280    fn detail_reason_serialises_as_tagged_object() {
281        let json = serde_json::to_string(&UncertainReason::Network("refused".into())).unwrap();
282        assert_eq!(json, "{\"network\":\"refused\"}");
283    }
284
285    #[test]
286    fn reason_display_matches_legacy_note_text() {
287        assert_eq!(UncertainReason::RateLimited.to_string(), "rate_limited");
288        assert_eq!(UncertainReason::Deadline.to_string(), "deadline reached");
289        assert_eq!(
290            UncertainReason::Network("boom".into()).to_string(),
291            "request: boom"
292        );
293    }
294
295    #[test]
296    fn old_outcome_json_defaults_confidence_and_profile_evidence() {
297        let json = r#"{
298            "site": "GitHub",
299            "url": "https://github.com/alice",
300            "kind": "found",
301            "elapsed_ms": 42
302        }"#;
303        let mut outcome: CheckOutcome = serde_json::from_str(json).unwrap();
304        assert!(outcome.profile_evidence.is_empty());
305        assert_eq!(outcome.confidence, ConfidenceScore::default());
306        outcome.refresh_confidence();
307        assert_eq!(outcome.confidence.score, 65);
308    }
309}
adler_core/check.rs

adler_core/
check.rs
