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        self.refresh_confidence_with_history(0);
160    }
161
162    /// Recompute confidence with a derived historical-consistency overlay.
163    ///
164    /// Live scan paths should call [`Self::refresh_confidence`] so outcomes
165    /// remain stateless. Persisted/history views can call this method after
166    /// computing a non-persisted history count.
167    pub fn refresh_confidence_with_history(&mut self, historical_consistency_count: usize) {
168        let access_paths = self
169            .profile_evidence
170            .iter()
171            .filter_map(|evidence| evidence.source.access_path.as_ref());
172        let authenticated_access = access_paths.clone().any(|path| path.authenticated);
173        let metadata_transport = access_paths.clone().map(|path| path.transport).next();
174        let metadata_escalated = access_paths.clone().any(|path| path.escalated);
175        let username_evidence_count = self
176            .profile_evidence
177            .iter()
178            .filter(|evidence| evidence.kind == ProfileEvidenceKind::Username)
179            .count();
180        let profile_evidence_count = self
181            .profile_evidence
182            .len()
183            .saturating_sub(username_evidence_count);
184        self.confidence = ConfidenceScore::from_signals(&ConfidenceSignals {
185            kind: self.kind,
186            reason: self.reason.clone(),
187            signal_evidence_count: self.evidence.len(),
188            profile_evidence_count,
189            username_evidence_count,
190            historical_consistency_count,
191            authenticated_access,
192            transport: metadata_transport.or(self.transport),
193            escalations: if metadata_escalated && self.escalations == 0 {
194                1
195            } else {
196                self.escalations
197            },
198        });
199    }
200}
201
202#[allow(clippy::trivially_copy_pass_by_ref)]
203fn is_zero_u8(n: &u8) -> bool {
204    *n == 0
205}
206
207#[cfg(test)]
208mod tests {
209    use super::*;
210
211    #[test]
212    fn match_kind_serialises_snake_case() {
213        assert_eq!(
214            serde_json::to_string(&MatchKind::Found).unwrap(),
215            "\"found\""
216        );
217        assert_eq!(
218            serde_json::to_string(&MatchKind::NotFound).unwrap(),
219            "\"not_found\""
220        );
221        assert_eq!(
222            serde_json::to_string(&MatchKind::Uncertain).unwrap(),
223            "\"uncertain\""
224        );
225    }
226
227    #[test]
228    fn match_kind_is_found() {
229        assert!(MatchKind::Found.is_found());
230        assert!(!MatchKind::NotFound.is_found());
231        assert!(!MatchKind::Uncertain.is_found());
232    }
233
234    #[test]
235    fn outcome_skips_absent_reason() {
236        let outcome = CheckOutcome {
237            site: "GitHub".into(),
238            url: "https://github.com/alice".into(),
239            kind: MatchKind::Found,
240            reason: None,
241            elapsed_ms: 42,
242            enrichment: BTreeMap::new(),
243            evidence: Vec::new(),
244            profile_evidence: Vec::new(),
245            confidence: ConfidenceScore::default(),
246            transport: None,
247            escalations: 0,
248        };
249        let json = serde_json::to_string(&outcome).unwrap();
250        assert!(
251            !json.contains("reason"),
252            "reason field must be omitted when None"
253        );
254        assert!(
255            !json.contains("enrichment"),
256            "enrichment must be omitted when empty"
257        );
258        assert!(
259            !json.contains("transport"),
260            "transport must be omitted when None"
261        );
262        assert!(
263            !json.contains("escalations"),
264            "escalations must be omitted when zero"
265        );
266        assert!(json.contains("\"kind\":\"found\""));
267        assert!(json.contains("\"elapsed_ms\":42"));
268    }
269
270    #[test]
271    fn unit_reason_serialises_as_snake_case_string() {
272        let outcome = CheckOutcome {
273            site: "GitHub".into(),
274            url: "https://github.com/alice".into(),
275            kind: MatchKind::Uncertain,
276            reason: Some(UncertainReason::RateLimited),
277            elapsed_ms: 5_000,
278            enrichment: BTreeMap::new(),
279            evidence: Vec::new(),
280            profile_evidence: Vec::new(),
281            confidence: ConfidenceScore::default(),
282            transport: None,
283            escalations: 0,
284        };
285        let json = serde_json::to_string(&outcome).unwrap();
286        assert!(json.contains("\"reason\":\"rate_limited\""), "{json}");
287    }
288
289    #[test]
290    fn detail_reason_serialises_as_tagged_object() {
291        let json = serde_json::to_string(&UncertainReason::Network("refused".into())).unwrap();
292        assert_eq!(json, "{\"network\":\"refused\"}");
293    }
294
295    #[test]
296    fn reason_display_matches_legacy_note_text() {
297        assert_eq!(UncertainReason::RateLimited.to_string(), "rate_limited");
298        assert_eq!(UncertainReason::Deadline.to_string(), "deadline reached");
299        assert_eq!(
300            UncertainReason::Network("boom".into()).to_string(),
301            "request: boom"
302        );
303    }
304
305    #[test]
306    fn old_outcome_json_defaults_confidence_and_profile_evidence() {
307        let json = r#"{
308            "site": "GitHub",
309            "url": "https://github.com/alice",
310            "kind": "found",
311            "elapsed_ms": 42
312        }"#;
313        let mut outcome: CheckOutcome = serde_json::from_str(json).unwrap();
314        assert!(outcome.profile_evidence.is_empty());
315        assert_eq!(outcome.confidence, ConfidenceScore::default());
316        outcome.refresh_confidence();
317        assert_eq!(outcome.confidence.score, 65);
318    }
319}
adler_core/check.rs

adler_core/
check.rs
