use std::{fmt, time::Duration};
use crate::{Address, Mode, ParseErrorKind, PolicyKind};
mod finding;
mod status;
pub use finding::{Finding, FindingCode};
pub use status::{Certainty, DomainStatus, MailboxStatus, Outcome, Verdict};
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub struct Classification {
disposable: bool,
role: bool,
free_mail: bool,
suggested_domain: Option<&'static str>,
}
impl Classification {
#[must_use]
pub const fn is_disposable(self) -> bool {
self.disposable
}
#[must_use]
pub const fn is_role(self) -> bool {
self.role
}
#[must_use]
pub const fn is_free_mail(self) -> bool {
self.free_mail
}
#[must_use]
pub const fn suggested_domain(self) -> Option<&'static str> {
self.suggested_domain
}
#[cfg(feature = "classification")]
pub(crate) const fn new(
disposable: bool,
role: bool,
free_mail: bool,
suggested_domain: Option<&'static str>,
) -> Self {
Self {
disposable,
role,
free_mail,
suggested_domain,
}
}
}
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ReportMetadata {
mode: Mode,
policy: PolicyKind,
schema: u16,
pata_version: &'static str,
data_revision: Option<&'static str>,
elapsed: Duration,
}
impl ReportMetadata {
#[must_use]
pub const fn mode(&self) -> Mode {
self.mode
}
#[must_use]
pub const fn policy(&self) -> PolicyKind {
self.policy
}
#[must_use]
pub const fn schema(&self) -> u16 {
self.schema
}
#[must_use]
pub const fn pata_version(&self) -> &'static str {
self.pata_version
}
#[must_use]
pub const fn data_revision(&self) -> Option<&'static str> {
self.data_revision
}
#[must_use]
pub const fn elapsed(&self) -> Duration {
self.elapsed
}
pub(crate) const fn new(mode: Mode, policy: PolicyKind, elapsed: Duration) -> Self {
Self {
mode,
policy,
schema: 1,
pata_version: env!("CARGO_PKG_VERSION"),
data_revision: crate::classifier::REVISION,
elapsed,
}
}
}
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub struct Report {
input: String,
address: Option<Address>,
parse_error: Option<ParseErrorKind>,
verdict: Verdict,
findings: Vec<Finding>,
classification: Classification,
domain_status: DomainStatus,
mailbox_status: MailboxStatus,
#[cfg(feature = "posture")]
posture: Option<crate::DomainPosture>,
metadata: ReportMetadata,
}
impl Report {
#[must_use]
pub fn input(&self) -> &str {
&self.input
}
#[must_use]
pub const fn address(&self) -> Option<&Address> {
self.address.as_ref()
}
#[must_use]
pub const fn parse_error(&self) -> Option<ParseErrorKind> {
self.parse_error
}
#[must_use]
pub const fn verdict(&self) -> Verdict {
self.verdict
}
#[must_use]
pub fn findings(&self) -> &[Finding] {
&self.findings
}
#[must_use]
pub const fn classification(&self) -> Classification {
self.classification
}
#[must_use]
pub const fn domain_status(&self) -> DomainStatus {
self.domain_status
}
#[must_use]
pub const fn mailbox_status(&self) -> MailboxStatus {
self.mailbox_status
}
#[cfg(feature = "posture")]
#[must_use]
pub const fn posture(&self) -> Option<crate::DomainPosture> {
self.posture
}
#[must_use]
pub const fn metadata(&self) -> &ReportMetadata {
&self.metadata
}
pub(crate) fn invalid(
input: String,
parse_error: ParseErrorKind,
mode: Mode,
policy: PolicyKind,
elapsed: Duration,
) -> Self {
Self {
input,
address: None,
parse_error: Some(parse_error),
verdict: Verdict::Invalid,
findings: vec![Finding::new(
FindingCode::SyntaxInvalid,
Outcome::Fail,
Certainty::Conclusive,
"the input is not a valid mailbox address",
)],
classification: Classification::default(),
domain_status: DomainStatus::NotChecked,
mailbox_status: MailboxStatus::NotChecked,
#[cfg(feature = "posture")]
posture: None,
metadata: ReportMetadata::new(mode, policy, elapsed),
}
}
pub(crate) fn parsed(
input: String,
address: Address,
findings: Vec<Finding>,
classification: Classification,
mode: Mode,
policy: PolicyKind,
elapsed: Duration,
) -> Self {
Self {
input,
address: Some(address),
parse_error: None,
verdict: Verdict::Plausible,
findings,
classification,
domain_status: DomainStatus::NotChecked,
mailbox_status: MailboxStatus::NotChecked,
#[cfg(feature = "posture")]
posture: None,
metadata: ReportMetadata::new(mode, policy, elapsed),
}
}
pub(crate) fn set_verdict(&mut self, verdict: Verdict) {
self.verdict = verdict;
}
pub(crate) fn set_elapsed(&mut self, elapsed: Duration) {
self.metadata.elapsed = elapsed;
}
#[cfg(feature = "dns")]
pub(crate) fn append_domain(&mut self, status: DomainStatus, finding: Finding) {
self.domain_status = status;
self.findings.push(finding);
}
#[cfg(feature = "smtp")]
pub(crate) fn append_mailbox(&mut self, status: MailboxStatus, finding: Finding) {
self.mailbox_status = status;
self.findings.push(finding);
}
#[cfg(feature = "posture")]
pub(crate) fn set_posture(&mut self, posture: crate::DomainPosture) {
self.posture = Some(posture);
self.findings.extend(crate::posture::findings(posture));
}
}
impl fmt::Debug for Report {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("Report")
.field("address", &self.address)
.field("parse_error", &self.parse_error)
.field("verdict", &self.verdict)
.field("findings", &self.findings)
.field("classification", &self.classification)
.field("domain_status", &self.domain_status)
.field("mailbox_status", &self.mailbox_status)
.field("posture", &{
#[cfg(feature = "posture")]
{
self.posture
}
#[cfg(not(feature = "posture"))]
{
"disabled"
}
})
.field("metadata", &self.metadata)
.finish()
}
}
#[cfg(test)]
mod tests {
#[cfg(feature = "serde")]
use futures_executor::block_on;
use super::*;
#[test]
fn finding_codes_are_stable_and_human_readable() {
assert_eq!(FindingCode::DomainNullMx.as_str(), "domain.null_mx");
assert_eq!(FindingCode::SmtpAccepted.to_string(), "smtp.accepted");
}
#[test]
fn metadata_reports_only_compiled_classification_data() {
let metadata = ReportMetadata::new(Mode::Local, PolicyKind::Registration, Duration::ZERO);
assert_eq!(metadata.policy(), PolicyKind::Registration);
#[cfg(feature = "classification")]
assert_eq!(metadata.data_revision(), Some("2026-08-13.1"));
#[cfg(not(feature = "classification"))]
assert_eq!(metadata.data_revision(), None);
}
#[cfg(feature = "serde")]
#[test]
fn serialization_is_explicit_and_machine_stable() {
let report = block_on(crate::Validator::local().validate("maya@example.com"));
let value = serde_json::to_value(report).unwrap();
assert_eq!(value["verdict"], "plausible");
assert_eq!(value["input"], "maya@example.com");
assert_eq!(value["findings"][0]["code"], "syntax.valid");
assert_eq!(value["metadata"]["policy"], "registration");
}
}