[Ocean572]

Closes #146.

Problem

Apple Mail stores messages in .emlx files, which can also appear inside .mailbundle folders.

Previously, these files were indexed incorrectly because the document extractor did not properly handle several email-specific encoding formats:

• Quoted-printable bodies were indexed without decoding, leaving sequences such as =3D, =A0, and =0A in the searchable text.
• Base64 attachments were included in the extracted text, introducing large amounts of unreadable binary data.
• Mixed-case headers were not reliably recognized. Header names written as Subject: or Content-Type: could be missed because the existing lookup did not account for capitalization.

The reporter's --lines 3 reproduction showed quoted-printable escapes and base64 content appearing directly in the indexed output.

Changes

DocExtractor now recognizes Apple Mail's .emlx structure and handles its common MIME encoding formats.

1. Quoted-Printable Decoding

Quoted-printable decoding has been rewritten to use a single linear pass over substring views rather than scanning the input character by character.

The implementation handles:

• Soft line breaks: Removes encoded line continuations so words split across lines are reconstructed correctly.
• Encoded characters: Decodes sequences such as =3D and =A0.
• UTF-8 byte sequences: Handles encoded UTF-8 sequences such as =C2 and their associated continuation bytes.
• RFC 2047 encoded words: Supports both quoted-printable-style and base64-encoded header words.

An important compatibility detail is that RFC 2047 encoded words found in real-world messages are sometimes unpadded.

Before base64 decoding, encoded words are padded to a length divisible by four (% 4 == 0). This prevents the final encoded word from being truncated during decoding.

The decoder also handles the earliest applicable _ or = marker according to the RFC 2047 encoded-word rules.

Bounds checking using prefix(2).count protects short trailing input from invalid substring access.

2. Exclude Base64 Attachments from Searchable Text

Base64-encoded MIME attachments are now recognized and excluded from extracted searchable text.

This prevents binary attachment data from polluting the document index while preserving the actual message content.

The result is that:

• The email body remains searchable.
• Normal message text is retained.
• Base64 attachment payloads are omitted.

3. Case-Insensitive Header Lookup

Header field lookup now uses case-insensitive matching through:

NSString.range(of:options:)

This ensures that headers are recognized regardless of capitalization.

For example, all of the following now match:

• Subject:
• SUBJECT:
• subject:
• Content-Type:
• CONTENT-TYPE:

The implementation uses NSString.range(of:options:) because firstRange(of:options:) is unavailable on the current deployment target.

4. Read Each File Only Once

The extractor previously read the same file multiple times during its processing passes.

This has been simplified to a single readText operation, with subsequent processing performed against the already-loaded contents.

This avoids unnecessary filesystem reads and reduces redundant work during extraction.

Performance Measurements

Measured on the development machine:

Hardware and environment: Apple M1, 8 GB RAM, macOS 26.5.1.

Quoted-Printable Decoding

A 128,000-escape input body was used to compare the previous and new decoding implementations.

Implementation	Execution time
Previous per-character scanning	73.9 s
New linear-pass decoder	0.15 s

~493× faster

The previous implementation repeatedly scanned the input at the character level, resulting in quadratic behavior.

The new implementation processes substring views in a single linear pass, dramatically reducing decoding time.

End-to-End Verification

Tested against a real multipart .emlx message.

DocExtractor.text successfully returns the decoded message body with:

• No remaining =3D or =0A quoted-printable escapes.
• No base64 attachment payloads.
• The original searchable message text preserved.

Testing

The Swift test suite now contains 137 passing tests.

This includes 12 new tests covering:

• Quoted-printable encoding and decoding.
• Soft line breaks and encoded characters.
• UTF-8 encoded sequences.
• RFC 2047 encoded words.
• Unpadded base64 encoded words.
• Base64 attachment exclusion.
• Mixed-case email headers.
• .mailbundle directory extraction.

Scope and Limitations

The following cases remain outside the supported decoding behavior:

• Non-standard character sets: .emlx bodies using non-standard encodings are currently decoded using UTF-8 and Latin-1 handling only.
• Malformed MIME boundaries: If a message contains an invalid or malformed MIME boundary marker, extraction falls back to treating the content as plain text. The file remains indexable, but encoding artifacts may remain visible in the extracted text.
• Deployment target compatibility: The implementation uses NSString.range(of:options:) for case-insensitive header matching because firstRange(of:options:) is unavailable on the current deployment target.