mail-parser 4.6.4__tar.gz → 4.7.0__tar.gz

mail_parser-4.6.4/CLAUDE.md → mail_parser-4.7.0/AGENTS.md

@@ -1,6 +1,8 @@
-# CLAUDE.md
+# AGENTS.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+This file is the shared source of repository instructions for Codex, Claude Code,
+and other coding agents. It applies throughout this repository. Keep shared
+instructions here; `CLAUDE.md` imports this file for Claude Code.
 
 ## Engineering Principles
 
@@ -13,6 +15,71 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 - Every third-party import must have an explicit entry in `pyproject.toml`. Use extras when the
   runtime feature requires them (e.g. `elasticsearch[async]`).
 
+## RFC 5322 compliance and forensic recovery
+
+For **every code change**, consult [RFC 5322](https://www.rfc-editor.org/info/rfc5322/)
+and check the affected behavior against its applicable syntax and semantics.
+Record the sections consulted and the compliance checks performed in the change
+summary; if the change has no message-format impact, explicitly explain why.
+Check applicable errata and updates linked by the RFC Editor, and related
+standards when the change concerns SMTP trace fields or MIME.
+
+Distinguish syntax permitted for newly generated messages (sections 2 and 3)
+from obsolete syntax that receivers must still parse (section 4). Consult
+section 5 for security considerations. Do not label an accepted obsolete form
+invalid solely because it must not be generated in new messages.
+
+This is a forensic parser: malformed input can deliberately exploit differences
+between parsers to evade security tools. For nonconforming messages:
+
+- Recover as much content as can be interpreted safely, preserving suspicious
+  display text, addresses, headers, and payload evidence. Do not silently discard
+  or normalize away data that could expose an evasion attempt.
+- Surface violations through `has_defects` and the relevant structured defect
+  metadata. For address headers, preserve `address_header_defects` entries with
+  `reason`, `raw`, `recovered`, `candidates`, `header`, and `occurrence`.
+  Successful recovery must not erase the defect or imply RFC compliance.
+- Keep ambiguous or incomplete evidence distinguishable from selected values.
+  Never promote an address found in display text or a comment over a complete
+  structural mailbox. Preserve occurrence context for repeated headers.
+- Report observable defects and conflicting interpretations; malformed syntax
+  alone does not prove malicious intent.
+- Keep existing resource, path, subprocess, and trust-boundary safeguards.
+  Recovery must not introduce crashes, unbounded amplification, unsafe side
+  effects, or fabricated attribution. Use controlled errors when safe recovery
+  is impossible; the fail-fast principle must not become blanket rejection of
+  recoverable malformed mail.
+
+For parsing changes, cover conforming input, applicable obsolete syntax, and
+malformed/adversarial variants with regression tests. Assert both recovered
+content and defect metadata, including cases where no unambiguous recovery is
+possible. Check that valid neighboring fields or list members remain intact.
+
+Example of required recovery behavior (address syntax: sections 3.2.3, 3.2.5,
+and 3.4). Preserve the misleading unquoted display name as evidence, select the
+address inside angle brackets, and expose the invalid display name:
+
+```python
+import mailparser
+
+mail = mailparser.parse_from_string(
+    "From: billing@trusted.example < billing@vendor.example >\r\n\r\n"
+)
+assert mail.from_ == [("billing@trusted.example", "billing@vendor.example")]
+assert mail.has_defects is True
+assert mail.address_header_defects == [{
+    "reason": "invalid-display-name",
+    "raw": "billing@trusted.example < billing@vendor.example >",
+    "recovered": True,
+    "candidates": [{
+        "display_name": "billing@trusted.example",
+        "address": "billing@vendor.example",
+    }],
+    "header": "from",
+    "occurrence": 0,
+}]
+```
+
 ## Python Style
 
 - Follow PEP 8. Use 4 spaces, never tabs.
@@ -27,22 +94,26 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 ```bash
 uv sync                  # install all dependencies
 uv run pytest            # run all tests
-uv run pytest tests/test_mail_parser.py::TestMailParser::test_name  # single test
+uv run pytest tests/test_mail_parser.py -k test_valid_mail  # single test
 uv run ruff check .      # lint
 uv run ruff format .     # format
+uv run pre-commit run --files AGENTS.md CLAUDE.md README.md  # selected files
+make pre-commit          # all tracked files
 make check               # lint + tests
 make build               # clean + build wheel/sdist
 ```
 
 ## Architecture
 
-**Package layout**: `src/mailparser/` (src layout, no runtime deps — stdlib only).
+**Package layout**: `src/mailparser/` (src layout, Python 3.9+, stdlib-only core;
+optional Outlook dependencies are installed with `uv sync --extra outlook`).
 
 ### Module responsibilities
 
 | Module          | Role                                                                  |
 | --------------- | --------------------------------------------------------------------- |
 | `core.py`       | `MailParser` class + `parse_from_*` factory functions                 |
+| `addresses.py`  | Forensic address scanner and recovery diagnostics                     |
 | `utils.py`      | Stateless parsing helpers (address, received headers, date, encoding) |
 | `const.py`      | Compiled regexes, header sets, clause splitter                        |
 | `exceptions.py` | Custom exception hierarchy                                            |
@@ -80,11 +151,17 @@ parse. `Message.get_all()` is a linear scan, so the one call per distinct name p
 `_make_mail()` cost O(distinct × total) on attacker-chosen names. Look up via the index inside any
 loop over header names.
 
-**RFC non-compliance fallback in `get_addresses()`**: Python's
-`email.utils.getaddresses(strict=True)` (hardened against CVE-2023-27043) rejects headers where
-the display name contains `@`. Since this is a forensics tool, `utils.py` applies
-`_ADDR_FALLBACK_RE` whenever strict parsing returns empty results — always surfacing what is
-actually in the header.
+**Forensic address parsing**: `addresses.py` scans structural delimiters in a
+single pass, respecting quotes, escapes, nested comments and domain literals.
+`utils.get_addresses()` adapts input and delegates to it. Complete angle-addrs
+have precedence over display text; incomplete/ambiguous items are evidence,
+not selected mailboxes. Never search display names/comments for bare addresses
+or reintroduce the old overlapping fallback regex (ReDoS). Parsing a malformed
+list member must not change the interpretation of its neighbours. `core.py`
+caches address results and recovery diagnostics once per parse, examining every
+header occurrence while retaining first-occurrence semantics for address
+properties. `address_header_defects` is reserved computed metadata; literal
+wire headers with that name remain accessible through `headers`/`message`.
 
 **Received header parsing**: `utils.receiveds_parsing()` tokenizes on RFC 5321 clause keywords
 (`from`, `by`, `via`, `with`, `id`, `for`, `envelope-from`) using `const._CLAUSE_SPLITTER`.
@@ -116,8 +193,10 @@ cases — three rounds of that each reopened a hole the previous one closed.
 RFC violations. `EPILOGUE_DEFECTS` triggers special epilogue extraction to recover hidden payloads
 in malformed boundaries.
 
-**Outlook support**: `parse_from_file_msg()` shells out to the system `msgconvert` Perl tool
-(`libemail-outlook-message-perl`) to convert `.msg` → `.eml`, then parses normally.
+**Outlook support**: `parse_from_file_msg()` prefers the optional `extract-msg`
+Python backend (`uv sync --extra outlook`). When unavailable, it falls back to
+the deprecated system `msgconvert` Perl tool (`libemail-outlook-message-perl`)
+to convert `.msg` → `.eml`, then parses normally.
 
 **Partial vs full mail**: `_make_mail(complete=True)` includes all headers found in the message;
 `complete=False` restricts to `const.ADDRESSES_HEADERS | const.OTHERS_PARTS` (the "main" headers).
@@ -136,12 +215,24 @@ attribute access.
 
 After every change:
 
-1. Add/update unittests to cover the change.
+1. For code changes, perform the RFC 5322 review described above before
+   implementation and verify the resulting behavior against it before reporting
+   done. Include the RFC sections, recovery/defect checks, and any remaining
+   compliance gaps in the change summary.
+1. Add/update unittests for behavior changes.
 1. Update README.md if the change affects usage, API, or setup.
-1. Stage changes and run pre-commit; fix all reported issues before proceeding.
+1. Run `uv run pre-commit run --files <changed-files>`; include new files and
+   fix all reported issues before proceeding. Use `make pre-commit` for all
+   tracked files.
 1. Run full test suite; fix all failures before reporting done.
-1. Run a security review of the change with the `security-reviewer` sub-agent
-   (`.claude/agents/security-reviewer.md`). All parsed input is
-   attacker-controlled, so any change to parsing, regexes, subprocess, temp
-   files, or attachment handling must be reviewed. Reproduce and fix every
-   High/Medium finding (with a regression test) before reporting done.
+1. Run a security review of the change using the procedure in
+   [`.claude/agents/security-reviewer.md`](.claude/agents/security-reviewer.md).
+   In Claude Code, use the `security-reviewer` sub-agent. In Codex or another
+   agent, give the Markdown body of that file to a review sub-agent when
+   available, or follow it directly when delegation is unavailable. The YAML
+   front matter configures Claude Code only; it does not select tools or models
+   in Codex. All parsed input is attacker-controlled, so any change to parsing,
+   regexes, subprocess, temp files, or attachment handling must be reviewed.
+   Reproduce and fix every High/Medium finding (with a regression test) before
+   reporting done. For documentation-only changes, check that security
+   invariants and review requirements remain intact.

mail_parser-4.7.0/CLAUDE.md

@@ -0,0 +1,5 @@
+# Claude Code instructions
+
+Shared repository instructions are maintained in `AGENTS.md`.
+
+@AGENTS.md

{mail_parser-4.6.4 → mail_parser-4.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mail-parser
-Version: 4.6.4
+Version: 4.7.0
 Summary: A tool that parses emails by enhancing the Python standard library, extracting all details into a comprehensive object.
 Project-URL: Homepage, https://github.com/SpamScope/mail-parser
 Project-URL: Source, https://github.com/SpamScope/mail-parser
@@ -298,6 +298,49 @@ mail.to_raw      # Original "To:" header string as it appears in the email
 The command-line tool outputs parsed emails in JSON format by default for easy integration with
 other tools and pipelines.
 
+### Address recovery and ambiguous headers
+
+Address properties such as `from_`, `to`, and `reply_to` retain their list of
+`(display_name, address)` tuples. Mailbox selection respects quoted strings,
+escapes, nested comments, groups, and folding whitespace. For example:
+
+```python
+mail = mailparser.parse_from_string(
+    "From: billing@trusted.example < billing@vendor.example >\r\n\r\n"
+)
+mail.from_
+# [('billing@trusted.example', 'billing@vendor.example')]
+mail.has_defects
+# True
+mail.address_header_defects[0]["reason"]
+# 'invalid-display-name'
+```
+
+RFC 5322 permits whitespace around the mailbox inside `<...>`; the unquoted
+`@` in this example's display name requires forensic recovery. A complete,
+unambiguous angle-address takes precedence over its display name. Addresses
+inside comments or quoted display names are never mailbox candidates.
+
+`address_header_defects` exposes recovery and ambiguity evidence. Each entry
+contains `header`, zero-based `occurrence`, the original `raw` list item,
+`reason`, `recovered`, and `candidates` (display-name/address dictionaries).
+It is included in `mail`, `mail_partial`, and their JSON output when nonempty,
+and also sets `has_defects` and the `AddressHeaderDefect` category. Diagnostics
+are computed once per parse, including repeated header occurrences; address
+properties retain their existing first-occurrence semantics.
+
+Ambiguous or incomplete items are omitted from address tuples, with their
+raw evidence and any structurally identified candidates retained in diagnostics.
+Valid neighbouring items are parsed independently. Consumers making filtering
+or attribution decisions should inspect these diagnostics: an empty address
+list does not establish that the original header contained no addresses.
+`structural-recovery` means the stdlib's interpretation could not be used; it
+is not by itself proof of an RFC violation. This recovery policy is not a full
+RFC validator or a guarantee of how every mail client displays malformed mail.
+The complete original header values remain available through `from_raw`,
+`to_raw`, etc.; literal headers colliding with computed metadata remain in
+`headers` and `message.get_all(...)`.
+
 ## Defects and Their Critical Role in Email Security
 
 Email structural defects are not merely technical curiosities—they represent **potential security
@@ -574,3 +617,16 @@ The default configuration includes:
 
 Customize the `docker-compose.yml` file to adjust mount points, command-line options, or
 environment variables for your specific use case.
+
+# Working with coding agents
+
+[AGENTS.md](AGENTS.md) is the shared source of development commands, coding
+conventions, architecture notes, and security review requirements.
+[Codex reads it automatically](https://developers.openai.com/codex/guides/agents-md).
+[CLAUDE.md](CLAUDE.md) imports the same file using
+[Claude Code's import syntax](https://code.claude.com/docs/en/memory#import-additional-files),
+so updates to shared guidance belong in `AGENTS.md`.
+
+The existing [security reviewer](.claude/agents/security-reviewer.md) remains
+available as a Claude Code sub-agent. Codex follows the same review procedure
+as described in `AGENTS.md`.

{mail_parser-4.6.4 → mail_parser-4.7.0}/README.md

@@ -266,6 +266,49 @@ mail.to_raw      # Original "To:" header string as it appears in the email
 The command-line tool outputs parsed emails in JSON format by default for easy integration with
 other tools and pipelines.
 
+### Address recovery and ambiguous headers
+
+Address properties such as `from_`, `to`, and `reply_to` retain their list of
+`(display_name, address)` tuples. Mailbox selection respects quoted strings,
+escapes, nested comments, groups, and folding whitespace. For example:
+
+```python
+mail = mailparser.parse_from_string(
+    "From: billing@trusted.example < billing@vendor.example >\r\n\r\n"
+)
+mail.from_
+# [('billing@trusted.example', 'billing@vendor.example')]
+mail.has_defects
+# True
+mail.address_header_defects[0]["reason"]
+# 'invalid-display-name'
+```
+
+RFC 5322 permits whitespace around the mailbox inside `<...>`; the unquoted
+`@` in this example's display name requires forensic recovery. A complete,
+unambiguous angle-address takes precedence over its display name. Addresses
+inside comments or quoted display names are never mailbox candidates.
+
+`address_header_defects` exposes recovery and ambiguity evidence. Each entry
+contains `header`, zero-based `occurrence`, the original `raw` list item,
+`reason`, `recovered`, and `candidates` (display-name/address dictionaries).
+It is included in `mail`, `mail_partial`, and their JSON output when nonempty,
+and also sets `has_defects` and the `AddressHeaderDefect` category. Diagnostics
+are computed once per parse, including repeated header occurrences; address
+properties retain their existing first-occurrence semantics.
+
+Ambiguous or incomplete items are omitted from address tuples, with their
+raw evidence and any structurally identified candidates retained in diagnostics.
+Valid neighbouring items are parsed independently. Consumers making filtering
+or attribution decisions should inspect these diagnostics: an empty address
+list does not establish that the original header contained no addresses.
+`structural-recovery` means the stdlib's interpretation could not be used; it
+is not by itself proof of an RFC violation. This recovery policy is not a full
+RFC validator or a guarantee of how every mail client displays malformed mail.
+The complete original header values remain available through `from_raw`,
+`to_raw`, etc.; literal headers colliding with computed metadata remain in
+`headers` and `message.get_all(...)`.
+
 ## Defects and Their Critical Role in Email Security
 
 Email structural defects are not merely technical curiosities—they represent **potential security
@@ -542,3 +585,16 @@ The default configuration includes:
 
 Customize the `docker-compose.yml` file to adjust mount points, command-line options, or
 environment variables for your specific use case.
+
+# Working with coding agents
+
+[AGENTS.md](AGENTS.md) is the shared source of development commands, coding
+conventions, architecture notes, and security review requirements.
+[Codex reads it automatically](https://developers.openai.com/codex/guides/agents-md).
+[CLAUDE.md](CLAUDE.md) imports the same file using
+[Claude Code's import syntax](https://code.claude.com/docs/en/memory#import-additional-files),
+so updates to shared guidance belong in `AGENTS.md`.
+
+The existing [security reviewer](.claude/agents/security-reviewer.md) remains
+available as a Claude Code sub-agent. Codex follows the same review procedure
+as described in `AGENTS.md`.

mail_parser-4.7.0/src/mailparser/addresses.py

@@ -0,0 +1,291 @@
+"""Structural address recovery for untrusted RFC 5322 header values.
+
+The scanner owns lexical boundaries and checks complete addr-specs against
+bounded grammar patterns. The stdlib supplies conventional display names for
+structurally consistent items. Recovery never searches a display name or
+comment for a convenient email substring.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+
+_FOLD = re.compile(r"\r?\n[ \t]+")
+# Anchored grammar checks: atom, quote and delimiter character sets do not
+# overlap. In particular, do not search for bare addresses in arbitrary text
+# or hand long malformed word sequences to headerregistry's quadratic parser.
+_ATOM = r"[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+"
+_QUOTED = r'"(?:[^"\\\r\n]|\\[^\r\n])*"'
+_WORD = rf"(?:{_ATOM}|{_QUOTED})"
+_LOCAL = rf"{_WORD}(?:[ \t]*\.[ \t]*{_WORD})*"
+_DOMAIN = rf"{_ATOM}(?:[ \t]*\.[ \t]*{_ATOM})*"
+_LITERAL = r"\[(?:[^\[\]\\\r\n]|\\[^\r\n])*\]"
+_ADDR_SPEC = re.compile(rf"{_LOCAL}[ \t]*@[ \t]*(?:{_DOMAIN}|{_LITERAL})")
+
+
+@dataclass
+class _Item:
+    raw: str
+    text: str
+    angles: list[tuple[int, int]]
+    problems: list[str] = field(default_factory=list)
+    comment_depth: int = 0
+
+
+def _scan(raw: str) -> list[_Item]:
+    """Split only at structural delimiters; bound work per input character."""
+    items: list[_Item] = []
+    buf: list[str] = []
+    angles: list[tuple[int, int]] = []
+    problems: list[str] = []
+    start = 0
+    angle = None
+    comment = max_comment = 0
+    quote = literal = escaped = group = False
+
+    def emit(end):
+        nonlocal buf, angles, problems, start, max_comment
+        text = "".join(buf)
+        if text.strip() or problems:
+            items.append(_Item(raw[start:end], text, angles, problems, max_comment))
+        buf, angles, problems = [], [], []
+        start = end + 1
+        max_comment = 0
+
+    for i, ch in enumerate(raw):
+        if escaped:
+            if not comment:
+                buf.append(ch)
+            escaped = False
+            continue
+        if ch == "\\" and (quote or comment or literal):
+            escaped = True
+            if not comment:
+                buf.append(ch)
+            continue
+        if comment:
+            if ch == "(":
+                comment += 1
+                max_comment = max(max_comment, comment)
+            elif ch == ")":
+                comment -= 1
+            continue
+        if quote:
+            buf.append(ch)
+            if ch == '"':
+                quote = False
+            continue
+        if literal:
+            buf.append(ch)
+            if ch == "]":
+                literal = False
+            continue
+        if ch == "(":
+            comment = 1
+            max_comment = max(max_comment, 1)
+            buf.append(" ")
+        elif ch == '"':
+            quote = True
+            buf.append(ch)
+        elif ch == "[":
+            literal = True
+            buf.append(ch)
+        elif ch == "<":
+            if angle is not None:
+                problems.append("nested-angle")
+            else:
+                angle = len(buf)
+            buf.append(ch)
+        elif ch == ">":
+            if angle is None:
+                problems.append("unmatched-angle")
+            else:
+                angles.append((angle, len(buf)))
+                angle = None
+            buf.append(ch)
+        elif angle is None and ch == ",":
+            emit(i)
+        elif angle is None and ch == ":":
+            if group or angles:
+                problems.append("invalid-group-boundary")
+                buf.append(ch)
+            else:
+                group = True
+                # Preserve malformed labels as diagnostics, never mailboxes.
+                if not _valid_phrase("".join(buf)):
+                    problems.append("invalid-group-name")
+                    emit(i)
+                buf = []
+                start = i + 1
+        elif angle is None and ch == ";":
+            if not group:
+                problems.append("unmatched-group")
+            emit(i)
+            group = False
+        else:
+            if ch in ")]":
+                problems.append("unmatched-delimiter")
+            buf.append(ch)
+
+    if quote or comment or literal or angle is not None or escaped:
+        problems.append("unclosed-delimiter")
+    if group:
+        problems.append("unclosed-group")
+    emit(len(raw))
+    return items
+
+
+def _mailbox(value: str) -> str | None:
+    """Validate the whole addr-spec, including quoted local parts and CFWS."""
+    value = _FOLD.sub(" ", value).strip()
+    # RFC 5322 section 4.4: obsolete source routes precede the addr-spec.
+    if value.startswith(("@", ",")):
+        literal = escaped = False
+        domains = []
+        start = 0
+        for i, ch in enumerate(value):
+            if escaped:
+                escaped = False
+            elif ch == "\\" and literal:
+                escaped = True
+            elif ch == "[":
+                literal = True
+            elif ch == "]":
+                literal = False
+            elif not literal and ch in ",:":
+                domain = value[start:i].strip()
+                if domain:
+                    domains.append(domain)
+                start = i + 1
+                if ch == ":":
+                    break
+        else:
+            return None
+        if not domains or any(
+            not domain.startswith("@") or not _ADDR_SPEC.fullmatch("route" + domain)
+            for domain in domains
+        ):
+            return None
+        value = value[start:].strip()
+    if not _ADDR_SPEC.fullmatch(value):
+        return None
+    # CFWS is not part of an atom. Retain spaces and escapes inside quoted
+    # local parts and domain literals, but remove token-separating FWS.
+    normalized = []
+    quoted = literal = escaped = False
+    for ch in value:
+        if escaped:
+            escaped = False
+        elif ch == "\\" and (quoted or literal):
+            escaped = True
+        elif ch == '"' and not literal:
+            quoted = not quoted
+        elif ch == "[" and not quoted:
+            literal = True
+        elif ch == "]" and literal:
+            literal = False
+        if ch not in " \t" or quoted or literal:
+            normalized.append(ch)
+    return "".join(normalized)
+
+
+def _valid_phrase(value: str) -> bool:
+    """Check label specials outside quoted strings (period is obs-phrase)."""
+    quoted = escaped = False
+    for ch in _FOLD.sub(" ", value).strip():
+        if ord(ch) < 32 and ch != "\t":
+            return False
+        if escaped:
+            escaped = False
+        elif ch == "\\" and quoted:
+            escaped = True
+        elif ch == '"':
+            quoted = not quoted
+        elif not quoted and ch in "@<>[]:;,\\":
+            return False
+    return bool(value.strip()) and not (quoted or escaped)
+
+
+def _name(value: str) -> str:
+    """Recover a display phrase, unquoting quoted pairs without regexes."""
+    result = []
+    quoted = escaped = False
+    for ch in _FOLD.sub(" ", value).strip():
+        if escaped:
+            result.append(ch)
+            escaped = False
+        elif ch == "\\" and quoted:
+            escaped = True
+        elif ch == '"':
+            quoted = not quoted
+        else:
+            result.append(ch)
+    return "".join(result).strip()
+
+
+def parse_address_header(raw: str, strict_parser):
+    """Return mailbox tuples and evidence for recovery or ambiguity.
+
+    ``strict_parser`` is the runtime-compatible email.utils adapter. Each
+    list member is parsed independently so a malformed member cannot change
+    the interpretation of a neighbouring, valid quoted name.
+    """
+    results = []
+    diagnostics = []
+    for item in _scan(raw):
+        candidates = []
+        # Derive the prefix once: repeating it for every angle-addr would
+        # copy quadratically much text on a long ambiguous item.
+        name = _name(item.text[: item.angles[0][0]]) if item.angles else ""
+        for index, (left, right) in enumerate(item.angles):
+            address = _mailbox(item.text[left + 1 : right])
+            if address:
+                candidates.append((name if index == 0 else "", address))
+        reason = None
+        selected = []
+        if item.problems:
+            reason = ",".join(sorted(set(item.problems)))
+        elif item.angles:
+            left, right = item.angles[0]
+            if len(item.angles) != 1 or item.text[right + 1 :].strip():
+                reason = "ambiguous-angle-address"
+            elif not candidates:
+                reason = "invalid-angle-address"
+            else:
+                selected = candidates
+                if item.text[:left].strip() and not _valid_phrase(item.text[:left]):
+                    reason = "invalid-display-name"
+        else:
+            address = _mailbox(item.text)
+            if address:
+                selected = [("", address)]
+                candidates = selected
+            else:
+                reason = "invalid-or-ambiguous-address"
+
+        if selected:
+            # Deep comments are stripped by the iterative scanner before
+            # reaching the stdlib's recursive comment parser.
+            source = item.raw if item.comment_depth < 16 else item.text
+            parsed = strict_parser([source])
+            if [addr for _, addr in parsed if addr] == [a for _, a in selected]:
+                selected = [(name, addr) for name, addr in parsed if addr]
+            else:
+                # Parsing can reject legal CFWS too. This records recovery,
+                # not a claim that every rejection proves RFC noncompliance.
+                reason = reason or "structural-recovery"
+        results.extend(selected)
+        if reason:
+            diagnostics.append(
+                {
+                    "reason": reason,
+                    "raw": item.raw,
+                    "recovered": bool(selected),
+                    "candidates": [
+                        {"display_name": name, "address": addr}
+                        for name, addr in candidates
+                    ],
+                }
+            )
+    return results, diagnostics