structured-email-address 0.0.10

//! Hand-rolled RFC 5321/5322/6531 email address parser.
//!
//! Grammar reference: RFC 5322 §3.4.1 (addr-spec), §3.2.3 (atom, dot-atom),
//! §3.2.4 (quoted-string), §3.2.2 (FWS, CFWS), §4.4 (obs-local-part, obs-domain),
//! RFC 6531 §3.3 (UTF8-non-ascii in atext/qtext/dtext).
//!
//! This parser produces zero-copy byte-offset spans into the input string.

use crate::config::Strictness;
use crate::error::{Error, ErrorKind};

/// Maximum nesting depth for comments and obs-domain recursion.
const MAX_RECURSION_DEPTH: usize = 128;

/// Raw parse result with byte-offset spans into the input.
#[derive(Debug, Clone)]
pub(crate) struct Parsed<'a> {
    /// The original input.
    pub input: &'a str,
    /// Display name (from `name-addr` syntax), if present.
    pub display_name: Option<Span>,
    /// Full local-part span (may include quotes for quoted-string).
    pub local_part: Span,
    /// Domain span.
    pub domain: Span,
    /// Comments found during parsing.
    #[allow(dead_code)]
    pub comments: Vec<Span>,
    /// Clean local-part with CFWS stripped (only set for obs-local-part with CFWS).
    pub local_part_clean: Option<String>,
    /// Clean domain with CFWS stripped (only set for obs-domain with CFWS).
    pub domain_clean: Option<String>,
}

impl<'a> Parsed<'a> {
    /// Effective local-part content: CFWS-stripped version if available, otherwise raw span.
    pub fn local_part_str(&self) -> &str {
        self.local_part_clean
            .as_deref()
            .unwrap_or_else(|| self.local_part.as_str(self.input))
    }

    /// Effective domain content: CFWS-stripped version if available, otherwise raw span.
    pub fn domain_str(&self) -> &str {
        self.domain_clean
            .as_deref()
            .unwrap_or_else(|| self.domain.as_str(self.input))
    }
}

/// A byte-offset range into the input string.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub(crate) struct Span {
    pub start: usize,
    pub end: usize,
}

impl Span {
    fn new(start: usize, end: usize) -> Self {
        Self { start, end }
    }

    pub fn as_str<'a>(&self, input: &'a str) -> &'a str {
        &input[self.start..self.end]
    }
}

/// Parser state: tracks current position in the input.
struct Parser<'a> {
    input: &'a str,
    pos: usize,
    comments: Vec<Span>,
}

impl<'a> Parser<'a> {
    fn new(input: &'a str) -> Self {
        Self {
            input,
            pos: 0,
            comments: Vec::new(),
        }
    }

    /// Remaining unparsed input.
    fn remaining(&self) -> &'a str {
        &self.input[self.pos..]
    }

    /// Peek at the next character without consuming.
    fn peek(&self) -> Option<char> {
        self.remaining().chars().next()
    }

    /// Consume and return the next character.
    fn advance(&mut self) -> Option<char> {
        let ch = self.peek()?;
        self.pos += ch.len_utf8();
        Some(ch)
    }

    /// Consume the next character if it matches.
    fn eat(&mut self, expected: char) -> bool {
        if self.peek() == Some(expected) {
            self.pos += expected.len_utf8();
            true
        } else {
            false
        }
    }

    /// Check if we've consumed all input.
    fn at_end(&self) -> bool {
        self.pos >= self.input.len()
    }

    /// Create an error at the current position.
    fn error(&self, kind: ErrorKind) -> Error {
        Error::new(kind, self.pos)
    }

    /// Save current position for backtracking.
    fn save(&self) -> usize {
        self.pos
    }

    /// Restore position for backtracking.
    fn restore(&mut self, pos: usize) {
        self.pos = pos;
    }
}

/// Parse an email address string according to the given strictness level.
///
/// If `allow_display_name` is true, accepts `name-addr` format: `"Name" <addr>` or `Name <addr>`.
pub(crate) fn parse(
    input: &str,
    strictness: Strictness,
    allow_display_name: bool,
    allow_domain_literal: bool,
) -> Result<Parsed<'_>, Error> {
    if input.is_empty() {
        return Err(Error::new(ErrorKind::Empty, 0));
    }

    // No leading/trailing trim: bare CR/LF are not strippable whitespace —
    // accepting `user@host\n` would be a header-injection hazard. Legitimate
    // leading/trailing CFWS (spaces, folding whitespace, comments) is consumed
    // by skip_cfws in Standard/Lax; a bare CR/LF is left to be rejected.
    let mut parser = Parser::new(input);
    let allow_obs = matches!(strictness, Strictness::Lax);

    // Strip leading CFWS before choosing the display-name / angle-addr path
    // (RFC 5322: a mailbox may be preceded by CFWS). Without this, a leading
    // space would divert a quoted display name to the unquoted scanner. Strict
    // (RFC 5321) forbids CFWS, so leading whitespace is left to be rejected.
    if !matches!(strictness, Strictness::Strict) {
        skip_cfws(&mut parser, 0);
    }

    // Try name-addr format: display-name? "<" addr-spec ">"
    let display_name = if allow_display_name {
        try_parse_display_name(&mut parser, allow_obs)
    } else {
        None
    };

    // `is_angle` is set only when '<' is the current character: the display-name
    // parsers stop exactly at it, and the bare case tests `peek() == '<'`. So the
    // opening bracket is always present and consumed here.
    let is_angle = display_name.is_some() || parser.peek() == Some('<');
    if is_angle {
        parser.eat('<');
    }

    // Parse addr-spec: local-part "@" domain.
    // RFC 5322 §3.2.3: local-part dot-atom permits leading [CFWS]
    // (`dot-atom = [CFWS] dot-atom-text [CFWS]`), so a comment or folding
    // whitespace before the local-part is valid. Strip it in Standard/Lax;
    // RFC 5321 Strict forbids CFWS, so a leading '(' or space is left for
    // parse_local_part to reject.
    if !matches!(strictness, Strictness::Strict) {
        skip_cfws(&mut parser, 0);
    }
    let (local_part, local_part_clean) = parse_local_part(&mut parser, strictness)?;
    // RFC 5322 allows CFWS around "@" in Standard/Lax modes.
    if !matches!(strictness, Strictness::Strict) {
        skip_cfws(&mut parser, 0);
    }
    if !parser.eat('@') {
        return Err(parser.error(ErrorKind::MissingAtSign));
    }
    if !matches!(strictness, Strictness::Strict) {
        skip_cfws(&mut parser, 0);
    }
    let (domain, domain_clean) = parse_domain(&mut parser, strictness, allow_domain_literal)?;

    if is_angle {
        if !matches!(strictness, Strictness::Strict) {
            skip_cfws(&mut parser, 0);
        }
        if !parser.eat('>') {
            return Err(parser.error(ErrorKind::Unexpected {
                ch: parser.peek().unwrap_or('\0'),
            }));
        }
    }

    // Skip trailing CFWS (not in Strict mode — RFC 5321 forbids comments/CFWS).
    if !matches!(strictness, Strictness::Strict) {
        skip_cfws(&mut parser, 0);
    }

    if !parser.at_end() {
        let ch = parser.peek().unwrap_or('\0');
        return Err(parser.error(ErrorKind::Unexpected { ch }));
    }

    Ok(Parsed {
        input,
        display_name,
        local_part,
        domain,
        comments: parser.comments,
        local_part_clean,
        domain_clean,
    })
}

/// Try to parse a display name before `<`. Returns None and resets position on failure.
fn try_parse_display_name(parser: &mut Parser<'_>, allow_obs: bool) -> Option<Span> {
    let save = parser.save();

    // Quoted display name: "Name" <addr>
    if parser.peek() == Some('"') {
        let start = parser.pos;
        if parse_quoted_string(parser, allow_obs).is_err() {
            parser.restore(save);
            return None;
        }
        let end = parser.pos;
        skip_cfws(parser, 0);
        if parser.peek() == Some('<') {
            // Span excludes quotes
            return Some(Span::new(start + 1, end - 1));
        }
        parser.restore(save);
        return None;
    }

    // Unquoted display name: word+ before <
    let start = parser.pos;
    let mut found_content = false;
    loop {
        match parser.peek() {
            Some('<') if found_content => {
                // Trim trailing whitespace from display name
                let name = &parser.input[start..parser.pos];
                let trimmed_end = start + name.trim_end().len();
                return Some(Span::new(start, trimmed_end));
            }
            Some(ch) if ch == '@' || ch == '>' => {
                // Not a display name — probably bare addr-spec
                parser.restore(save);
                return None;
            }
            Some(ch) if ch < '\u{20}' && ch != '\t' => {
                // Control characters are not valid in display names.
                parser.restore(save);
                return None;
            }
            Some(_) => {
                found_content = true;
                parser.advance();
            }
            None => {
                parser.restore(save);
                return None;
            }
        }
    }
}

/// Parse local-part: dot-atom / quoted-string / obs-local-part.
///
/// Returns `(span, clean)` where `clean` is `Some(String)` when obs-local-part
/// contained CFWS that was stripped from the semantic value.
fn parse_local_part(
    parser: &mut Parser<'_>,
    strictness: Strictness,
) -> Result<(Span, Option<String>), Error> {
    let start = parser.pos;
    let allow_obs = matches!(strictness, Strictness::Lax);

    // Reject quoted-string local parts in Strict mode (RFC 5321 envelope).
    if parser.peek() == Some('"') {
        if matches!(strictness, Strictness::Strict) {
            return Err(parser.error(ErrorKind::InvalidLocalPartChar { ch: '"' }));
        }
        if !allow_obs {
            // Standard mode: quoted-string is the entire local-part.
            parse_quoted_string(parser, false)?;
            return Ok((Span::new(start, parser.pos), None));
        }
        // Lax mode: fall through — obs-local-part allows quoted-string as first word,
        // followed by optional "." word segments.
    }

    // dot-atom (or obs-local-part if Lax). parse_dot_atom_local always consumes
    // at least one token or returns an error, so the span is never empty here.
    let clean = parse_dot_atom_local(parser, allow_obs)?;

    Ok((Span::new(start, parser.pos), clean))
}

/// Parse dot-atom for local-part: `atext+ ("." atext+)*`.
/// If `allow_obs` is true, allows CFWS between atoms (obs-local-part).
///
/// Returns `Some(clean)` when obs-mode CFWS was present and stripped,
/// `None` when the span is already clean (zero-copy path).
fn parse_dot_atom_local(parser: &mut Parser<'_>, allow_obs: bool) -> Result<Option<String>, Error> {
    if !allow_obs {
        // Standard mode: no CFWS between atoms, span is always clean.
        if !eat_atext_run(parser) {
            return Err(match parser.peek() {
                Some(ch) if ch != '@' => parser.error(ErrorKind::InvalidLocalPartChar { ch }),
                _ => parser.error(ErrorKind::EmptyLocalPart),
            });
        }
        loop {
            let save = parser.save();
            if !parser.eat('.') {
                parser.restore(save);
                break;
            }
            if !eat_atext_run(parser) {
                return Err(parser.error(ErrorKind::EmptyLocalPart));
            }
        }
        return Ok(None);
    }

    // Obs mode: parse atoms, building a clean string only when CFWS is present.
    // Zero allocation in the common no-CFWS path. When CFWS is first detected,
    // the contiguous prefix (all prior atoms+dots, no CFWS gaps) is copied
    // from the raw span, then subsequent atoms are appended incrementally.
    let mut clean: Option<String> = None;
    let outer_start = parser.pos;

    // First word: any leading CFWS was already consumed by the caller (`parse`
    // skips it before the local-part). CFWS stripping here applies only between
    // segments, so the first word starts immediately.
    if !eat_atext_run(parser) && !try_quoted_string(parser, allow_obs) {
        return Err(match parser.peek() {
            Some(ch) if ch != '@' => parser.error(ErrorKind::InvalidLocalPartChar { ch }),
            _ => parser.error(ErrorKind::EmptyLocalPart),
        });
    }

    // Subsequent ".atom" segments
    loop {
        // `last_clean_end` marks the end of contiguous clean content before
        // any CFWS in this iteration. Used as prefix boundary if CFWS is
        // detected for the first time.
        let last_clean_end = parser.pos;
        let save = parser.save();
        let comments_len = parser.comments.len();
        skip_cfws(parser, 0);
        let had_cfws_before_dot = parser.pos > last_clean_end;
        if !parser.eat('.') {
            parser.restore(save);
            parser.comments.truncate(comments_len);
            break;
        }
        if had_cfws_before_dot && clean.is_none() {
            let mut s = String::with_capacity(last_clean_end - outer_start);
            s.push_str(&parser.input[outer_start..last_clean_end]);
            clean = Some(s);
        }
        skip_cfws(parser, 0);
        // If CFWS after dot and we haven't started clean yet, seed with
        // content before the dot — the dot is appended below via push('.').
        if clean.is_none() && parser.pos > last_clean_end + 1 {
            let mut s = String::with_capacity(last_clean_end - outer_start);
            s.push_str(&parser.input[outer_start..last_clean_end]);
            clean = Some(s);
        }
        let atom_start = parser.pos;
        if !eat_atext_run(parser) && !try_quoted_string(parser, allow_obs) {
            return Err(parser.error(ErrorKind::EmptyLocalPart));
        }
        if let Some(ref mut s) = clean {
            s.push('.');
            s.push_str(&parser.input[atom_start..parser.pos]);
        }
    }

    Ok(clean)
}

/// Consume one or more atext characters. Returns true if any consumed.
fn eat_atext_run(parser: &mut Parser<'_>) -> bool {
    let start = parser.pos;
    while let Some(ch) = parser.peek() {
        if is_atext(ch) {
            parser.advance();
        } else {
            break;
        }
    }
    parser.pos > start
}

/// Parse quoted-string: `"` (qtext | quoted-pair | FWS)* `"`.
///
/// With `allow_obs`, accepts obs-qtext and obs-qp (control characters) per
/// RFC 5322 §4.1 — used in Lax mode.
fn parse_quoted_string(parser: &mut Parser<'_>, allow_obs: bool) -> Result<(), Error> {
    if !parser.eat('"') {
        return Err(parser.error(ErrorKind::UnterminatedQuotedString));
    }

    loop {
        match parser.peek() {
            Some('"') => {
                parser.advance();
                return Ok(());
            }
            Some('\\') => {
                parser.advance();
                match parser.advance() {
                    Some(ch) if is_quoted_pair_char(ch, allow_obs) => {}
                    _ => return Err(parser.error(ErrorKind::InvalidQuotedPair)),
                }
            }
            Some(ch) if is_qtext(ch, allow_obs) => {
                parser.advance();
            }
            // RFC 5322 FWS: plain WSP or CRLF + WSP (folded whitespace).
            Some(ch) if is_wsp(ch) || ch == '\r' => {
                if !try_eat_fws(parser) {
                    return Err(parser.error(ErrorKind::InvalidLocalPartChar { ch: '\r' }));
                }
            }
            None => return Err(parser.error(ErrorKind::UnterminatedQuotedString)),
            Some(ch) => {
                return Err(parser.error(ErrorKind::InvalidLocalPartChar { ch }));
            }
        }
    }
}

/// Try to parse a quoted-string without error on failure.
fn try_quoted_string(parser: &mut Parser<'_>, allow_obs: bool) -> bool {
    if parser.peek() != Some('"') {
        return false;
    }
    let save = parser.save();
    if parse_quoted_string(parser, allow_obs).is_ok() {
        true
    } else {
        parser.restore(save);
        false
    }
}

/// Parse domain: dot-atom / domain-literal / obs-domain.
///
/// Returns `(span, clean)` where `clean` is `Some(String)` when obs-domain
/// contained CFWS that was stripped from the semantic value.
fn parse_domain(
    parser: &mut Parser<'_>,
    strictness: Strictness,
    allow_domain_literal: bool,
) -> Result<(Span, Option<String>), Error> {
    let start = parser.pos;

    // Domain literal: [...]
    if parser.peek() == Some('[') {
        if !allow_domain_literal {
            return Err(parser.error(ErrorKind::InvalidDomainChar { ch: '[' }));
        }
        parse_domain_literal(parser)?;
        return Ok((Span::new(start, parser.pos), None));
    }

    // dot-atom domain. parse_dot_atom_domain parses at least one label or
    // returns an error, so the span is never empty here.
    let allow_obs = matches!(strictness, Strictness::Lax);
    let clean = parse_dot_atom_domain(parser, allow_obs)?;

    Ok((Span::new(start, parser.pos), clean))
}

/// Parse dot-atom for domain: `label ("." label)*` where label avoids leading/trailing hyphen.
///
/// Returns `Some(clean)` when obs-mode CFWS was present and stripped,
/// `None` when the span is already clean (zero-copy path).
fn parse_dot_atom_domain(
    parser: &mut Parser<'_>,
    allow_obs: bool,
) -> Result<Option<String>, Error> {
    if !allow_obs {
        // Standard mode: no CFWS between labels, span is always clean.
        parse_domain_label(parser)?;
        loop {
            let save = parser.save();
            if !parser.eat('.') {
                parser.restore(save);
                break;
            }
            parse_domain_label(parser)?;
        }
        return Ok(None);
    }

    // Obs mode: parse labels, building a clean string only when CFWS is present.
    // Zero allocation in the common no-CFWS path. Same incremental strategy
    // as parse_dot_atom_local — see that function for detailed comments.
    let mut clean: Option<String> = None;
    let outer_start = parser.pos;

    parse_domain_label(parser)?;

    loop {
        let last_clean_end = parser.pos;
        let save = parser.save();
        let comments_len = parser.comments.len();
        skip_cfws(parser, 0);
        let had_cfws_before_dot = parser.pos > last_clean_end;
        if !parser.eat('.') {
            parser.restore(save);
            parser.comments.truncate(comments_len);
            break;
        }
        if had_cfws_before_dot && clean.is_none() {
            let mut s = String::with_capacity(last_clean_end - outer_start);
            s.push_str(&parser.input[outer_start..last_clean_end]);
            clean = Some(s);
        }
        skip_cfws(parser, 0);
        if clean.is_none() && parser.pos > last_clean_end + 1 {
            let mut s = String::with_capacity(last_clean_end - outer_start);
            s.push_str(&parser.input[outer_start..last_clean_end]);
            clean = Some(s);
        }
        let label_start = parser.pos;
        parse_domain_label(parser)?;
        if let Some(ref mut s) = clean {
            s.push('.');
            s.push_str(&parser.input[label_start..parser.pos]);
        }
    }

    Ok(clean)
}

/// Parse a single domain label: starts and ends with alnum, may contain hyphens.
fn parse_domain_label(parser: &mut Parser<'_>) -> Result<(), Error> {
    // First char must be alnum (or UTF-8 non-ASCII for IDN)
    match parser.peek() {
        Some(ch) if ch.is_ascii_alphanumeric() || is_utf8_non_ascii(ch) => {
            parser.advance();
        }
        Some('-') => return Err(parser.error(ErrorKind::DomainLabelHyphen)),
        _ => return Err(parser.error(ErrorKind::EmptyDomain)),
    }

    // Continue with alnum and hyphens
    let mut last_was_hyphen = false;
    while let Some(ch) = parser.peek() {
        if ch.is_ascii_alphanumeric() || is_utf8_non_ascii(ch) {
            last_was_hyphen = false;
            parser.advance();
        } else if ch == '-' {
            last_was_hyphen = true;
            parser.advance();
        } else {
            break;
        }
    }

    if last_was_hyphen {
        return Err(parser.error(ErrorKind::DomainLabelHyphen));
    }

    Ok(())
}

/// Parse domain literal: `[` ... `]`, accepting only valid RFC 5321 §4.1.3
/// address literals — an IPv4 dotted-quad or an `IPv6:`-tagged IPv6 address.
///
/// General RFC 5322 domain literals (arbitrary `dtext`, e.g.
/// `[RFC-5322-domain-literal]`) and malformed IP literals (`[255.255.255]`,
/// `[IPv6:1::2:]`) are syntactically consumed but rejected with
/// [`ErrorKind::InvalidAddressLiteral`]: a non-IP literal is not a usable mail
/// destination. This matches the isEmail conformance baseline, which classifies
/// such tokens as RFC 5322-only (not valid RFC 5321 addresses).
fn parse_domain_literal(parser: &mut Parser<'_>) -> Result<(), Error> {
    let open = parser.pos;
    if !parser.eat('[') {
        return Err(parser.error(ErrorKind::UnterminatedDomainLiteral));
    }
    let content_start = parser.pos;
    loop {
        match parser.peek() {
            Some(']') => {
                let content = &parser.input[content_start..parser.pos];
                parser.advance(); // consume ']'
                if is_address_literal(content) {
                    return Ok(());
                }
                return Err(Error::new(ErrorKind::InvalidAddressLiteral, open));
            }
            // A backslash escapes the next char (obs-dtext); consume both so an
            // escaped ']' does not close the literal early. The resulting
            // content fails IP validation above, so the literal is rejected.
            Some('\\') => {
                parser.advance();
                if parser.advance().is_none() {
                    return Err(parser.error(ErrorKind::UnterminatedDomainLiteral));
                }
            }
            None => return Err(parser.error(ErrorKind::UnterminatedDomainLiteral)),
            Some(_) => {
                parser.advance();
            }
        }
    }
}

/// Returns true if the domain-literal content (the text between `[` and `]`)
/// is a valid IPv4 address literal or an `IPv6:`-tagged IPv6 address literal
/// (RFC 5321 §4.1.3). Uses `core::net` parsers (no-std friendly).
fn is_address_literal(content: &str) -> bool {
    use core::net::{Ipv4Addr, Ipv6Addr};
    // The "IPv6:" tag is an ABNF string literal, hence case-insensitive
    // (RFC 5234 §2.3): `[ipv6:::1]` and `[IPV6:...]` are equally valid.
    if content
        .get(..5)
        .is_some_and(|tag| tag.eq_ignore_ascii_case("IPv6:"))
    {
        return content[5..].parse::<Ipv6Addr>().is_ok();
    }
    content.parse::<Ipv4Addr>().is_ok()
}

/// Try to consume one FWS token: either plain WSP, or CRLF followed by at least one WSP.
/// Returns true if any whitespace was consumed.
fn try_eat_fws(parser: &mut Parser<'_>) -> bool {
    match parser.peek() {
        Some(ch) if is_wsp(ch) => {
            parser.advance();
            // Consume any additional WSP
            while let Some(ch) = parser.peek() {
                if is_wsp(ch) {
                    parser.advance();
                } else {
                    break;
                }
            }
            true
        }
        Some('\r') => {
            let pos = parser.pos;
            let bytes = parser.input.as_bytes();
            if pos + 2 < bytes.len()
                && bytes[pos] == b'\r'
                && bytes[pos + 1] == b'\n'
                && (bytes[pos + 2] == b' ' || bytes[pos + 2] == b'\t')
            {
                parser.advance(); // '\r'
                parser.advance(); // '\n'
                while let Some(ch) = parser.peek() {
                    if is_wsp(ch) {
                        parser.advance();
                    } else {
                        break;
                    }
                }
                true
            } else {
                false
            }
        }
        _ => false,
    }
}

/// Skip CFWS (comments and folding whitespace). `depth` seeds the comment
/// nesting counter; recursion is bounded by [`parse_comment`].
fn skip_cfws(parser: &mut Parser<'_>, depth: usize) {
    loop {
        // Skip whitespace and RFC 5322 Folding White Space (CRLF + WSP).
        loop {
            match parser.peek() {
                // Regular WSP (space / tab)
                Some(ch) if is_wsp(ch) => {
                    parser.advance();
                }
                // Potential FWS: CRLF followed by WSP
                Some('\r') => {
                    let pos = parser.pos;
                    let bytes = parser.input.as_bytes();
                    // Check for CRLF + WSP as per RFC 5322 FWS
                    if pos + 2 < bytes.len()
                        && bytes[pos] == b'\r'
                        && bytes[pos + 1] == b'\n'
                        && (bytes[pos + 2] == b' ' || bytes[pos + 2] == b'\t')
                    {
                        // Consume CRLF
                        parser.advance(); // '\r'
                        parser.advance(); // '\n', then consume following WSP
                        while let Some(wch) = parser.peek() {
                            if is_wsp(wch) {
                                parser.advance();
                            } else {
                                break;
                            }
                        }
                    } else {
                        // Bare CR is not valid FWS; stop treating as CFWS here.
                        break;
                    }
                }
                // Bare LF is not valid FWS; stop here.
                Some('\n') => {
                    break;
                }
                _ => break,
            }
        }
        // Try comment
        if parser.peek() == Some('(') {
            let comment_start = parser.pos;
            match parse_comment(parser, depth) {
                Ok(()) => {
                    parser.comments.push(Span::new(comment_start, parser.pos));
                    continue;
                }
                Err(_) => {
                    // Intentionally swallowing comment parse errors here.
                    // skip_cfws is called in contexts where '(' may not start a comment
                    // (e.g., trailing garbage after addr-spec). Propagating the error
                    // would mask the real issue. Instead, restore position and let the
                    // caller produce a context-appropriate error (Unexpected, MissingAtSign, etc.).
                    parser.pos = comment_start;
                    break;
                }
            }
        }
        break;
    }
}

/// Parse a comment: `(` ccontent* `)`.
fn parse_comment(parser: &mut Parser<'_>, depth: usize) -> Result<(), Error> {
    if depth >= MAX_RECURSION_DEPTH || !parser.eat('(') {
        return Err(parser.error(ErrorKind::UnterminatedComment));
    }

    loop {
        match parser.peek() {
            Some(')') => {
                parser.advance();
                return Ok(());
            }
            Some('(') => {
                // Nested comment
                parse_comment(parser, depth + 1)?;
            }
            // A comment is free-form CFWS: a backslash escapes any following
            // character (including obs-qp control chars). Only a trailing
            // backslash at end-of-input is an error.
            Some('\\') => {
                parser.advance();
                if parser.advance().is_none() {
                    return Err(parser.error(ErrorKind::UnterminatedComment));
                }
            }
            Some(ch) if is_ctext(ch) || is_wsp(ch) => {
                parser.advance();
            }
            // Inside a comment, CR/LF is only valid as folding whitespace
            // (CRLF + WSP). A bare CR or LF is invalid (e.g. `(\r)`).
            Some('\r') | Some('\n') => {
                if !try_eat_fws(parser) {
                    return Err(parser.error(ErrorKind::UnterminatedComment));
                }
            }
            None => return Err(parser.error(ErrorKind::UnterminatedComment)),
            Some(_) => {
                parser.advance(); // be lenient in comments (obs-ctext controls)
            }
        }
    }
}

// ── Character class predicates (RFC 5322 §3.2.3 + RFC 6531) ──

/// atext: ALPHA / DIGIT / special chars / UTF-8 non-ASCII.
fn is_atext(ch: char) -> bool {
    ch.is_ascii_alphanumeric()
        || is_utf8_non_ascii(ch)
        || matches!(
            ch,
            '!' | '#'
                | '$'
                | '%'
                | '&'
                | '\''
                | '*'
                | '+'
                | '-'
                | '/'
                | '='
                | '?'
                | '^'
                | '_'
                | '`'
                | '{'
                | '|'
                | '}'
                | '~'
        )
}

/// qtext (RFC 5322 §3.2.4): printable ASCII except `"` and `\`, plus UTF-8
/// non-ASCII. With `allow_obs`, also accepts obs-qtext (obs-NO-WS-CTL controls).
fn is_qtext(ch: char, allow_obs: bool) -> bool {
    if ch == '"' || ch == '\\' {
        return false;
    }
    is_printable_ascii(ch) || is_utf8_non_ascii(ch) || (allow_obs && is_obs_no_ws_ctl(ch))
}

/// ctext: printable ASCII except `(`, `)`, `\`, plus UTF-8 non-ASCII.
fn is_ctext(ch: char) -> bool {
    ch != '(' && ch != ')' && ch != '\\' && (is_printable_ascii(ch) || is_utf8_non_ascii(ch))
}

/// Characters valid in a quoted-pair after `\` (RFC 5322 §3.2.1: `quoted-pair =
/// "\" (VCHAR / WSP)`). Non-ASCII is intentionally excluded — RFC 6531 allows
/// UTF-8 directly in qtext, so escaping it is invalid. With `allow_obs`, also
/// accepts obs-qp: NUL, CR, LF, and obs-NO-WS-CTL controls.
fn is_quoted_pair_char(ch: char, allow_obs: bool) -> bool {
    if is_printable_ascii(ch) || is_wsp(ch) {
        return true;
    }
    allow_obs && (matches!(ch, '\0' | '\n' | '\r') || is_obs_no_ws_ctl(ch))
}

/// obs-NO-WS-CTL (RFC 5322 §4.1): control chars usable in obsolete qtext and
/// quoted-pairs — %d1-8, %d11, %d12, %d14-31, %d127 (excludes NUL, TAB, LF, CR).
fn is_obs_no_ws_ctl(ch: char) -> bool {
    matches!(ch as u32, 0x01..=0x08 | 0x0b | 0x0c | 0x0e..=0x1f | 0x7f)
}

fn is_printable_ascii(ch: char) -> bool {
    matches!(ch as u32, 0x21..=0x7e)
}

fn is_utf8_non_ascii(ch: char) -> bool {
    (ch as u32) >= 0x80
}

fn is_wsp(ch: char) -> bool {
    ch == ' ' || ch == '\t'
}

#[cfg(test)]
mod tests {
    use super::*;

    fn parse_ok(input: &str) -> Parsed<'_> {
        parse(input, Strictness::Standard, false, false)
            .unwrap_or_else(|e| panic!("failed to parse '{input}': {e}"))
    }

    fn parse_ok_lax(input: &str) -> Parsed<'_> {
        parse(input, Strictness::Lax, false, false)
            .unwrap_or_else(|e| panic!("failed to parse '{input}': {e}"))
    }

    fn parse_err(input: &str) -> Error {
        parse(input, Strictness::Standard, false, false)
            .expect_err(&format!("expected error for '{input}'"))
    }

    // ── Basic valid addresses ──

    #[test]
    fn simple_address() {
        let p = parse_ok("user@example.com");
        assert_eq!(p.local_part.as_str(p.input), "user");
        assert_eq!(p.domain.as_str(p.input), "example.com");
    }

    #[test]
    fn subaddress_preserved() {
        let p = parse_ok("user+tag@example.com");
        assert_eq!(p.local_part.as_str(p.input), "user+tag");
    }

    #[test]
    fn dotted_local() {
        let p = parse_ok("first.last@example.com");
        assert_eq!(p.local_part.as_str(p.input), "first.last");
    }

    #[test]
    fn utf8_local() {
        let p = parse_ok("дмитрий@example.com");
        assert_eq!(p.local_part.as_str(p.input), "дмитрий");
    }

    #[test]
    fn utf8_domain() {
        let p = parse_ok("user@münchen.de");
        assert_eq!(p.domain.as_str(p.input), "münchen.de");
    }

    #[test]
    fn quoted_local_part() {
        let p = parse_ok("\"user@name\"@example.com");
        assert_eq!(p.local_part.as_str(p.input), "\"user@name\"");
    }

    #[test]
    fn quoted_local_with_spaces() {
        let p = parse_ok("\"user name\"@example.com");
        assert_eq!(p.local_part.as_str(p.input), "\"user name\"");
    }

    // ── Invalid addresses ──

    #[test]
    fn empty_input() {
        let e = parse_err("");
        assert_eq!(e.kind(), &ErrorKind::Empty);
    }

    #[test]
    fn no_at_sign() {
        let e = parse_err("userexample.com");
        assert_eq!(e.kind(), &ErrorKind::MissingAtSign);
    }

    #[test]
    fn empty_local() {
        let e = parse_err("@example.com");
        assert_eq!(e.kind(), &ErrorKind::EmptyLocalPart);
    }

    #[test]
    fn empty_domain() {
        let e = parse_err("user@");
        assert_eq!(e.kind(), &ErrorKind::EmptyDomain);
    }

    // ── Dot-atom edge cases ──

    #[test]
    fn trailing_dot_in_local_part_is_not_missing_at_sign() {
        let e = parse_err("user.@example.com");
        // Ensure this is treated as a local-part syntax error, not as a missing '@'.
        assert_ne!(e.kind(), &ErrorKind::MissingAtSign);
    }

    #[test]
    fn obs_local_part_quoted_first_word() {
        // obs-local-part: word *("." word), where word can be quoted-string.
        // "a".b@example.com must parse in Lax mode.
        let p = parse("\"a\".b@example.com", Strictness::Lax, false, false).unwrap_or_else(|e| {
            panic!("Lax must accept obs-local-part starting with quoted word: {e}")
        });
        assert_eq!(p.local_part.as_str(p.input), "\"a\".b");
        assert_eq!(p.domain.as_str(p.input), "example.com");
    }

    #[test]
    fn obs_local_part_rejected_in_standard() {
        let e = parse("a.\"b\"@example.com", Strictness::Standard, false, false)
            .expect_err("expected obs-local-part to be rejected in Standard strictness");
        // Should fail due to local-part syntax, not due to a missing '@'.
        assert_ne!(e.kind(), &ErrorKind::MissingAtSign);
    }

    #[test]
    fn obs_local_part_accepted_in_lax() {
        let p = parse("a.\"b\"@example.com", Strictness::Lax, false, false)
            .unwrap_or_else(|e| panic!("parse failed in Lax strictness: {e}"));
        assert_eq!(p.local_part.as_str(p.input), "a.\"b\"");
        assert_eq!(p.domain.as_str(p.input), "example.com");
    }

    // ── Display name ──

    #[test]
    fn display_name_angle() {
        let p = parse(
            "John Doe <user@example.com>",
            Strictness::Standard,
            true,
            false,
        )
        .unwrap_or_else(|e| panic!("parse failed: {e}"));
        assert_eq!(p.display_name.map(|s| s.as_str(p.input)), Some("John Doe"));
        assert_eq!(p.local_part.as_str(p.input), "user");
        assert_eq!(p.domain.as_str(p.input), "example.com");
    }

    #[test]
    fn quoted_display_name() {
        let p = parse(
            "\"John Doe\" <user@example.com>",
            Strictness::Standard,
            true,
            false,
        )
        .unwrap_or_else(|e| panic!("parse failed: {e}"));
        assert_eq!(p.display_name.map(|s| s.as_str(p.input)), Some("John Doe"));
    }

    // ── Domain literal ──

    #[test]
    fn domain_literal_allowed() {
        let p = parse("user@[192.168.1.1]", Strictness::Standard, false, true)
            .unwrap_or_else(|e| panic!("parse failed: {e}"));
        assert_eq!(p.domain.as_str(p.input), "[192.168.1.1]");
    }

    #[test]
    fn trailing_dot_in_domain_gives_domain_error() {
        // "user@example." — once '.' is consumed, error should be domain-specific.
        let e = parse_err("user@example.");
        assert!(
            matches!(e.kind(), ErrorKind::EmptyDomain),
            "expected EmptyDomain, got {:?}",
            e.kind()
        );
    }

    #[test]
    fn consecutive_dots_in_domain_gives_domain_error() {
        let e = parse_err("user@example..com");
        assert!(
            matches!(e.kind(), ErrorKind::EmptyDomain),
            "expected EmptyDomain, got {:?}",
            e.kind()
        );
    }

    #[test]
    fn strict_rejects_trailing_comment() {
        // RFC 5321 Strict mode must not accept trailing comments/CFWS.
        let e = parse(
            "user@example.com (comment)",
            Strictness::Strict,
            false,
            false,
        )
        .expect_err("Strict mode must reject trailing comment");
        assert!(matches!(e.kind(), ErrorKind::Unexpected { .. }));
    }

    #[test]
    fn strict_rejects_trailing_cfws_in_angle() {
        // Trailing CFWS between domain and '>' in Strict mode.
        let e = parse(
            "<user@example.com (comment)>",
            Strictness::Strict,
            false,
            false,
        )
        .expect_err("Strict mode must reject CFWS before closing angle bracket");
        assert!(matches!(e.kind(), ErrorKind::Unexpected { .. }));
    }

    #[test]
    fn strict_rejects_quoted_local_part() {
        // RFC 5321 Strict mode must reject quoted-string local parts.
        let e = parse("\"quoted\"@example.com", Strictness::Strict, false, false)
            .expect_err("Strict mode must reject quoted-string local part");
        assert_eq!(e.kind(), &ErrorKind::InvalidLocalPartChar { ch: '"' });
    }

    #[test]
    fn strict_rejects_leading_comment() {
        // RFC 5321 Strict mode must reject leading comments/CFWS.
        let e = parse(
            "(comment)user@example.com",
            Strictness::Strict,
            false,
            false,
        )
        .expect_err("Strict mode must reject leading comment");
        // Leading `(` is not valid atext — parser reports the offending char.
        assert_eq!(e.kind(), &ErrorKind::InvalidLocalPartChar { ch: '(' });
    }

    #[test]
    fn standard_accepts_quoted_string_and_comments() {
        // Standard mode (RFC 5322) must accept quoted-string local parts.
        let p = parse("\"quoted\"@example.com", Strictness::Standard, false, false)
            .unwrap_or_else(|e| panic!("Standard must accept quoted-string: {e}"));
        assert_eq!(p.local_part.as_str(p.input), "\"quoted\"");
        assert_eq!(p.domain.as_str(p.input), "example.com");

        // Standard mode must accept trailing comments.
        let p = parse(
            "user@example.com (comment)",
            Strictness::Standard,
            false,
            false,
        )
        .unwrap_or_else(|e| panic!("Standard must accept trailing comment: {e}"));
        assert_eq!(p.local_part.as_str(p.input), "user");
        assert_eq!(p.domain.as_str(p.input), "example.com");
    }

    #[test]
    fn domain_literal_rejected_by_default() {
        let e = parse("user@[192.168.1.1]", Strictness::Standard, false, false)
            .expect_err("expected error");
        assert_eq!(e.kind(), &ErrorKind::InvalidDomainChar { ch: '[' });
    }

    // ── Regression tests for #13: CFWS stripping in obs-local-part / obs-domain ──

    #[test]
    fn obs_local_part_cfws_comment_stripped() {
        // obs-local-part with comment between atoms: span must not include CFWS.
        let p = parse_ok_lax("user (comment) . name@example.com");
        assert_eq!(
            p.local_part_str(),
            "user.name",
            "CFWS comment must be stripped from obs-local-part"
        );
    }

    #[test]
    fn obs_local_part_whitespace_stripped() {
        // obs-local-part with plain whitespace between atoms.
        let p = parse_ok_lax("user . name@example.com");
        assert_eq!(
            p.local_part_str(),
            "user.name",
            "whitespace must be stripped from obs-local-part"
        );
    }

    #[test]
    fn obs_domain_cfws_comment_stripped() {
        // obs-domain with comment between labels: span must not include CFWS.
        let p = parse_ok_lax("user@example (comment) . com");
        assert_eq!(
            p.domain_str(),
            "example.com",
            "CFWS comment must be stripped from obs-domain"
        );
    }

    #[test]
    fn obs_domain_whitespace_stripped() {
        // obs-domain with plain whitespace between labels.
        let p = parse_ok_lax("user@example . com");
        assert_eq!(
            p.domain_str(),
            "example.com",
            "whitespace must be stripped from obs-domain"
        );
    }

    #[test]
    fn obs_local_no_cfws_zero_copy() {
        // obs-local-part without CFWS: clean field is None (zero-copy path).
        let p = parse_ok_lax("user.name@example.com");
        assert!(
            p.local_part_clean.is_none(),
            "no CFWS → local_part_clean must be None (zero-copy)"
        );
        assert_eq!(p.local_part_str(), "user.name");
    }

    #[test]
    fn obs_domain_no_cfws_zero_copy() {
        // obs-domain without CFWS: clean field is None (zero-copy path).
        let p = parse_ok_lax("user@example.com");
        assert!(
            p.domain_clean.is_none(),
            "no CFWS → domain_clean must be None (zero-copy)"
        );
        assert_eq!(p.domain_str(), "example.com");
    }

    #[test]
    fn obs_local_part_multiple_comments_stripped() {
        // Multiple CFWS segments between atoms.
        let p = parse_ok_lax("a (c1) . b (c2) . c@example.com");
        assert_eq!(p.local_part_str(), "a.b.c");
    }

    #[test]
    fn obs_leading_comment_accepted_in_bare_addr_spec() {
        // RFC 5322 §3.2.3: local-part dot-atom permits leading [CFWS]
        // (`dot-atom = [CFWS] dot-atom-text [CFWS]`), so a comment before the
        // local-part is valid and stripped from the semantic value. Combined
        // here with obs CFWS between atoms.
        let p = parse(
            "(leading) user . name@example.com",
            Strictness::Lax,
            false,
            false,
        )
        .unwrap_or_else(|e| panic!("leading comment must be accepted: {e}"));
        assert_eq!(p.local_part_str(), "user.name");
        assert_eq!(p.domain_str(), "example.com");
    }

    #[test]
    fn obs_local_cfws_after_dot_no_double_dots() {
        // CFWS only after dot: "user. name" must produce "user.name", not "user..name".
        let p = parse_ok_lax("user. name@example.com");
        assert_eq!(p.local_part_str(), "user.name");
    }

    #[test]
    fn obs_domain_cfws_after_dot_no_double_dots() {
        // CFWS only after dot: "example. com" must produce "example.com", not "example..com".
        let p = parse_ok_lax("user@example. com");
        assert_eq!(p.domain_str(), "example.com");
    }

    #[test]
    fn obs_trailing_cfws_before_at_preserves_zero_copy() {
        // Trailing CFWS before '@' is NOT between atoms — it's excluded from
        // the span by backtracking. Must not trigger allocation or duplicate
        // comment spans.
        let p = parse_ok_lax("user (trailing)@example.com");
        assert!(
            p.local_part_clean.is_none(),
            "trailing CFWS before @ must not trigger allocation"
        );
        assert_eq!(p.local_part_str(), "user");
        assert_eq!(
            p.comments.len(),
            1,
            "backtracked comment must not be duplicated"
        );
    }

    #[test]
    fn obs_trailing_cfws_after_domain_preserves_zero_copy() {
        // Trailing CFWS after domain is NOT between labels — must not allocate
        // or duplicate comment spans.
        let p = parse_ok_lax("user@example.com (trailing)");
        assert!(
            p.domain_clean.is_none(),
            "trailing CFWS after domain must not trigger allocation"
        );
        assert_eq!(p.domain_str(), "example.com");
        assert_eq!(
            p.comments.len(),
            1,
            "backtracked comment must not be duplicated"
        );
    }

    // ── Leading CFWS before local-part (RFC 5322 dot-atom = [CFWS] ...) ──

    #[test]
    fn leading_comment_accepted_standard_and_lax() {
        for strictness in [Strictness::Standard, Strictness::Lax] {
            let p = parse("(comment)jane.smith@example.com", strictness, false, false)
                .unwrap_or_else(|e| panic!("{strictness:?}: leading comment must parse: {e}"));
            assert_eq!(p.local_part_str(), "jane.smith");
            assert_eq!(p.domain_str(), "example.com");
        }
    }

    #[test]
    fn leading_comment_in_angle_addr() {
        let p = parse(
            "<(comment)user@example.com>",
            Strictness::Standard,
            false,
            false,
        )
        .unwrap_or_else(|e| panic!("leading comment in angle-addr must parse: {e}"));
        assert_eq!(p.local_part_str(), "user");
    }

    #[test]
    fn strict_still_rejects_leading_comment() {
        let e = parse(
            "(comment)user@example.com",
            Strictness::Strict,
            false,
            false,
        )
        .expect_err("Strict must reject leading comment");
        assert_eq!(e.kind(), &ErrorKind::InvalidLocalPartChar { ch: '(' });
    }

    #[test]
    fn comment_only_local_part_is_empty() {
        let e = parse("(comment)@example.com", Strictness::Lax, false, false)
            .expect_err("comment-only local part must be rejected");
        assert_eq!(e.kind(), &ErrorKind::EmptyLocalPart);
    }

    // ── CR/LF are not strippable whitespace (header-injection hardening) ──

    #[test]
    fn rejects_bare_trailing_lf() {
        for input in ["test@iana.org\n", "test@iana.org\r", "test@iana.org\r\n"] {
            assert!(
                parse(input, Strictness::Lax, false, false).is_err(),
                "must reject trailing bare CR/LF: {input:?}"
            );
        }
    }

    #[test]
    fn rejects_bare_leading_cr_lf() {
        for input in ["\rtest@iana.org", "\ntest@iana.org", "\r\ntest@iana.org"] {
            assert!(
                parse(input, Strictness::Lax, false, false).is_err(),
                "must reject leading bare CR/LF: {input:?}"
            );
        }
    }

    #[test]
    fn rejects_bare_cr_in_comment() {
        // A bare CR inside a comment is not valid FWS.
        let e = parse("test@iana.org(\r)", Strictness::Lax, false, false)
            .expect_err("bare CR in comment must be rejected");
        assert!(matches!(e.kind(), ErrorKind::Unexpected { .. }));
    }

    #[test]
    fn comment_may_contain_folding_whitespace() {
        // A comment may fold across lines: CRLF + WSP is valid FWS inside it.
        let p = parse("(a\r\n b)test@iana.org", Strictness::Lax, false, false)
            .unwrap_or_else(|e| panic!("folded comment must parse: {e}"));
        assert_eq!(p.local_part_str(), "test");
    }

    #[test]
    fn accepts_valid_folding_whitespace() {
        // FWS = CRLF followed by WSP — valid leading and trailing.
        let leading = parse(" \r\n test@iana.org", Strictness::Lax, false, false)
            .unwrap_or_else(|e| panic!("leading FWS must parse: {e}"));
        assert_eq!(leading.local_part_str(), "test");

        let trailing = parse("test@iana.org \r\n ", Strictness::Lax, false, false)
            .unwrap_or_else(|e| panic!("trailing FWS must parse: {e}"));
        assert_eq!(trailing.domain_str(), "iana.org");
    }

    #[test]
    fn accepts_trailing_and_leading_space() {
        // Plain leading/trailing spaces are CFWS, accepted in Standard/Lax.
        assert!(parse(" test@iana.org", Strictness::Standard, false, false).is_ok());
        assert!(parse("test@iana.org ", Strictness::Standard, false, false).is_ok());
    }

    // ── Address-literal validation (RFC 5321 §4.1.3) ──

    fn parse_lit(input: &str) -> Result<Parsed<'_>, Error> {
        // Domain literals require allow_domain_literal = true.
        parse(input, Strictness::Lax, false, true)
    }

    #[test]
    fn accepts_valid_ipv4_literal() {
        let p = parse_lit("test@[255.255.255.255]").unwrap_or_else(|e| panic!("{e}"));
        assert_eq!(p.domain_str(), "[255.255.255.255]");
    }

    #[test]
    fn accepts_valid_ipv6_literal() {
        for v6 in [
            "test@[IPv6:1111:2222:3333:4444:5555:6666:7777:8888]",
            "test@[IPv6:1111:2222:3333:4444:5555::8888]",
            "test@[IPv6:::]",
            "test@[IPv6:1111:2222:3333:4444::255.255.255.255]",
        ] {
            assert!(parse_lit(v6).is_ok(), "valid IPv6 literal must parse: {v6}");
        }
    }

    #[test]
    fn rejects_malformed_ip_literal() {
        for bad in [
            "test@[255.255.255]",                                  // 3 octets
            "test@[255.255.255.256]",                              // octet > 255
            "test@[IPv6:1111:2222:3333:4444:5555:6666:7777]",      // 7 groups
            "test@[IPv6:1111:2222:3333:4444:5555:6666:7777:888G]", // bad hex
            "test@[IPv6:1::2:]",                                   // trailing colon
            "test@[RFC-5322-domain-literal]",                      // general literal
        ] {
            let e = parse_lit(bad).expect_err(&format!("must reject: {bad}"));
            assert_eq!(
                e.kind(),
                &ErrorKind::InvalidAddressLiteral,
                "wrong error for {bad}"
            );
            assert!(
                e.to_string().contains("address literal"),
                "unexpected Display for {bad}: {e}"
            );
        }
    }

    #[test]
    fn parse_domain_literal_requires_open_bracket() {
        // Defensive contract: the helper errors if called without a leading '['
        // (callers only invoke it after peeking '[').
        let mut parser = Parser::new("nope");
        assert_eq!(
            parse_domain_literal(&mut parser).unwrap_err().kind(),
            &ErrorKind::UnterminatedDomainLiteral
        );
    }

    #[test]
    fn is_qtext_excludes_quote_and_backslash() {
        // '"' and '\\' are never qtext even though '"' is printable ASCII —
        // they are structural delimiters handled before is_qtext is consulted.
        assert!(!is_qtext('"', false));
        assert!(!is_qtext('"', true));
        assert!(!is_qtext('\\', true));
        assert!(is_qtext('a', false));
    }

    // ── obs-qp / obs-qtext (Lax only) ──

    #[test]
    fn lax_accepts_obs_qtext_and_obs_qp() {
        // Control chars (obs-NO-WS-CTL) in qtext and after a quoted-pair are
        // valid in Lax mode.
        for input in [
            "\"\u{07}\"@iana.org",   // obs-qtext BEL
            "\"\u{7f}\"@iana.org",   // obs-qtext DEL
            "\"\\\u{00}\"@iana.org", // obs-qp NUL
            "\"\\\u{0a}\"@iana.org", // obs-qp LF
        ] {
            assert!(
                parse(input, Strictness::Lax, false, false).is_ok(),
                "Lax must accept obs-qp/qtext: {input:?}"
            );
        }
    }

    #[test]
    fn standard_rejects_obs_qtext() {
        // Standard (non-obsolete) mode must reject control chars in qtext.
        let e = parse("\"\u{07}\"@iana.org", Strictness::Standard, false, false)
            .expect_err("Standard must reject obs-qtext");
        assert_eq!(e.kind(), &ErrorKind::InvalidLocalPartChar { ch: '\u{07}' });
    }

    #[test]
    fn rejects_quoted_pair_of_non_ascii() {
        // RFC 6531 puts UTF-8 directly in qtext; escaping it via quoted-pair is
        // invalid. Standard reports it directly as an invalid quoted-pair.
        let e = parse(
            "\"test\\\u{a9}\"@iana.org",
            Strictness::Standard,
            false,
            false,
        )
        .expect_err("quoted-pair of non-ASCII must be rejected");
        assert_eq!(e.kind(), &ErrorKind::InvalidQuotedPair);
        // Lax also rejects it (after backtracking the obs-local-part attempt).
        assert!(parse("\"test\\\u{a9}\"@iana.org", Strictness::Lax, false, false).is_err());
    }

    // ── FWS / recursion / quoted-string edge paths ──

    #[test]
    fn quoted_string_consumes_consecutive_wsp() {
        // Two spaces in a row exercise the multi-WSP loop in try_eat_fws.
        let p = parse("\"a  b\"@example.com", Strictness::Standard, false, false)
            .unwrap_or_else(|e| panic!("quoted string with double space: {e}"));
        assert_eq!(p.local_part.as_str(p.input), "\"a  b\"");
    }

    #[test]
    fn parse_quoted_string_requires_open_quote() {
        // Defensive contract: errors when not invoked at a '"'.
        let mut parser = Parser::new("x");
        assert_eq!(
            parse_quoted_string(&mut parser, false).unwrap_err().kind(),
            &ErrorKind::UnterminatedQuotedString
        );
    }

    #[test]
    fn deeply_nested_comment_is_rejected() {
        // Comment nesting beyond MAX_RECURSION_DEPTH is rejected (DoS guard).
        let input = format!(
            "{}x{}test@iana.org",
            "(".repeat(MAX_RECURSION_DEPTH + 2),
            ")".repeat(MAX_RECURSION_DEPTH + 2)
        );
        assert!(parse(&input, Strictness::Lax, false, false).is_err());
    }

    // ── Display-name parsing paths (allow_display_name = true) ──

    #[test]
    fn quoted_local_part_not_treated_as_display_name() {
        // A quoted string with no following '<' is the local-part, not a
        // display name — try_parse_display_name backtracks.
        let p = parse("\"quoted\"@example.com", Strictness::Standard, true, false)
            .unwrap_or_else(|e| panic!("quoted local with display_name enabled: {e}"));
        assert_eq!(p.display_name, None);
        assert_eq!(p.local_part.as_str(p.input), "\"quoted\"");
    }

    #[test]
    fn malformed_quoted_display_name_backtracks() {
        // An unterminated quoted string in display position backtracks, then
        // fails as a quoted local-part.
        let e = parse(
            "\"unterminated@example.com",
            Strictness::Standard,
            true,
            false,
        )
        .expect_err("unterminated quoted must fail");
        assert_eq!(e.kind(), &ErrorKind::UnterminatedQuotedString);
    }

    #[test]
    fn control_char_aborts_display_name_scan() {
        // A control character aborts the unquoted display-name scan; parsing
        // then falls back to addr-spec and rejects the control char.
        let e = parse("\u{01}user@example.com", Strictness::Standard, true, false)
            .expect_err("control char must be rejected");
        assert_eq!(e.kind(), &ErrorKind::InvalidLocalPartChar { ch: '\u{01}' });
    }

    #[test]
    fn unquoted_text_without_angle_is_not_display_name() {
        // Unquoted text reaching end-of-input with no '<' is not a display
        // name; it is parsed as an addr-spec, which here lacks '@'.
        let e = parse("plainname", Strictness::Standard, true, false)
            .expect_err("bare text without '@' must fail");
        assert_eq!(e.kind(), &ErrorKind::MissingAtSign);
    }

    #[test]
    fn leading_cfws_before_quoted_display_name() {
        // A leading space (CFWS) before a quoted display name must not divert
        // parsing to the unquoted scanner — the display name must be the
        // unquoted "John Doe", not the raw `"John Doe"` with quotes.
        let p = parse(
            " \"John Doe\" <user@example.com>",
            Strictness::Standard,
            true,
            false,
        )
        .unwrap_or_else(|e| panic!("leading CFWS + quoted display name: {e}"));
        assert_eq!(p.display_name.map(|s| s.as_str(p.input)), Some("John Doe"));
        assert_eq!(p.local_part.as_str(p.input), "user");
    }

    #[test]
    fn ipv6_address_literal_tag_is_case_insensitive() {
        // RFC ABNF string literals are case-insensitive, so the `IPv6:` tag may
        // be written in any case.
        for input in [
            "user@[ipv6:::1]",
            "user@[IPV6:2001:db8::1]",
            "user@[IPv6:::1]",
        ] {
            assert!(
                parse(input, Strictness::Lax, false, true).is_ok(),
                "case-insensitive IPv6 tag must parse: {input}"
            );
        }
    }
}