@postalsys/email-content 0.0.1

package/dist/mime/headers.js

@@ -0,0 +1,127 @@
+"use strict";
+/**
+ * Header extraction helpers.
+ *
+ * Nothing in the pipeline may depend on a header being present. Every accessor returns null rather
+ * than throwing, and every decode is wrapped so that a malformed encoded word cannot abort a parse.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeWordsSafe = decodeWordsSafe;
+exports.parseHeaderValueSafe = parseHeaderValueSafe;
+exports.toHeaderEntries = toHeaderEntries;
+exports.normaliseMessageId = normaliseMessageId;
+exports.parseReferences = parseReferences;
+exports.extractMessageHeaders = extractMessageHeaders;
+const libmime_1 = __importDefault(require("libmime"));
+/** Decode MIME encoded words, falling back to the raw value on any failure. */
+function decodeWordsSafe(value) {
+    try {
+        return libmime_1.default.decodeWords(value);
+    }
+    catch {
+        return value;
+    }
+}
+/** Parse a structured header value such as Content-Type into a value plus parameters. */
+function parseHeaderValueSafe(value) {
+    try {
+        const parsed = libmime_1.default.parseHeaderValue(value);
+        return { value: String(parsed.value || ''), params: parsed.params || {} };
+    }
+    catch {
+        return { value, params: {} };
+    }
+}
+/**
+ * Convert mailsplit's raw header lines into normalised entries.
+ *
+ * mailsplit returns `{ key, line }` where `line` still contains the field name and any folded
+ * continuations joined with CRLF. Lines with no colon at all are kept with an empty key so that
+ * malformed input is still visible to diagnostics.
+ */
+function toHeaderEntries(list) {
+    const entries = [];
+    for (const item of list) {
+        const line = String(item.line || '');
+        const colon = line.indexOf(':');
+        const key = String(item.key || '').toLowerCase();
+        const rawValue = colon === -1 ? '' : line.slice(colon + 1);
+        // Unfold: a folded continuation is CRLF followed by whitespace.
+        const value = rawValue.replace(/\r?\n[ \t]+/g, ' ').trim();
+        entries.push({ key, value, decoded: decodeWordsSafe(value) });
+    }
+    return entries;
+}
+function first(entries, key) {
+    for (const entry of entries) {
+        if (entry.key === key) {
+            return entry;
+        }
+    }
+    return null;
+}
+function firstValue(entries, key) {
+    const entry = first(entries, key);
+    return entry ? entry.value || null : null;
+}
+function firstDecoded(entries, key) {
+    const entry = first(entries, key);
+    return entry ? entry.decoded || null : null;
+}
+/** Strip angle brackets and surrounding whitespace from a Message-ID style value. */
+function normaliseMessageId(value) {
+    if (!value) {
+        return null;
+    }
+    const match = value.match(/<([^>]+)>/);
+    const id = (match?.[1] ?? value).trim().toLowerCase();
+    return id || null;
+}
+/** Extract every angle bracketed id from a References style header. */
+function parseReferences(value) {
+    if (!value) {
+        return [];
+    }
+    const matches = value.match(/<[^>\s]+>/g);
+    if (matches) {
+        return matches.map(item => item.slice(1, -1).trim().toLowerCase()).filter(Boolean);
+    }
+    // Some clients emit bare, whitespace separated ids.
+    return value
+        .split(/\s+/)
+        .map(item => item.trim().toLowerCase())
+        .filter(item => item.includes('@'));
+}
+function parseDateMs(value) {
+    if (!value) {
+        return null;
+    }
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? parsed : null;
+}
+/** Collect the headers the analysis pipeline uses. All fields are optional by design. */
+function extractMessageHeaders(entries) {
+    const dateRaw = firstValue(entries, 'date');
+    return {
+        messageId: normaliseMessageId(firstValue(entries, 'message-id')),
+        inReplyTo: normaliseMessageId(firstValue(entries, 'in-reply-to')),
+        references: parseReferences(firstValue(entries, 'references')),
+        from: firstDecoded(entries, 'from'),
+        to: firstDecoded(entries, 'to'),
+        cc: firstDecoded(entries, 'cc'),
+        date: dateRaw,
+        dateMs: parseDateMs(dateRaw),
+        subject: firstDecoded(entries, 'subject'),
+        contentType: firstValue(entries, 'content-type'),
+        userAgent: firstValue(entries, 'user-agent'),
+        xMailer: firstValue(entries, 'x-mailer'),
+        listId: firstValue(entries, 'list-id'),
+        listUnsubscribe: firstValue(entries, 'list-unsubscribe'),
+        precedence: firstValue(entries, 'precedence'),
+        autoSubmitted: firstValue(entries, 'auto-submitted')
+    };
+}
+//# sourceMappingURL=headers.js.map

package/dist/mime/headers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"headers.js","sourceRoot":"","sources":["../../src/mime/headers.ts"],"names":[],"mappings":"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"}

package/dist/mime/model.d.ts

@@ -0,0 +1,111 @@
+/**
+ * Normalised internal representation of a parsed message.
+ *
+ * The MIME tree is preserved as a tree. Nothing is flattened into a single html/text pair, because
+ * the extractor needs to know which text part is the alternative sibling of which html part, and
+ * needs to be able to point at the exact bytes a segment came from.
+ */
+import { type Warning } from '../types';
+export interface ByteRange {
+    start: number;
+    end: number;
+}
+export interface HeaderEntry {
+    /** Lowercased field name. */
+    key: string;
+    /** Raw value as it appeared, unfolded but not decoded. */
+    value: string;
+    /** MIME encoded words decoded, best effort. Falls back to the raw value. */
+    decoded: string;
+}
+/** Result of decoding a text part, with enough detail to judge how much to trust it. */
+export interface DecodedText {
+    /** Decoded, charset converted, flowed unfolded text. */
+    text: string;
+    /** Charset actually used, which may differ from the declared one. */
+    charsetUsed: string;
+    /** Charset as declared in the Content-Type header, if any. */
+    charsetDeclared: string | null;
+    /** Count of U+FFFD replacement characters produced by the decode. */
+    replacementChars: number;
+    /** True when the part exceeded the configured size cap and was cut short. */
+    truncated: boolean;
+}
+export interface MimePart {
+    /** IMAP style part path, for example "1.2". The root of a single part message is "TEXT". */
+    partId: string;
+    partNr: (number | string)[];
+    /** Lowercased content type, for example "text/html". Never empty, defaults per RFC 2046. */
+    contentType: string;
+    contentTypeParams: Record<string, string>;
+    charset: string | null;
+    encoding: string | null;
+    disposition: 'attachment' | 'inline' | null;
+    filename: string | null;
+    /** Multipart subtype ("alternative", "mixed", "related") or null for leaves. */
+    multipart: string | null;
+    /** True for a message/rfc822 container. */
+    rfc822: boolean;
+    /** True when this node is the root of an embedded message. */
+    embeddedRoot: boolean;
+    flowed: boolean;
+    delSp: boolean;
+    parentId: string | null;
+    childIds: string[];
+    /** Byte range of the raw header block within the original message. */
+    headerRange: ByteRange;
+    /** Byte range of the raw, still encoded body within the original message. Null for containers. */
+    bodyRange: ByteRange | null;
+    /** Raw encoded body size in bytes. */
+    rawBodySize: number;
+    /** All header lines of this part. */
+    headers: HeaderEntry[];
+    /** Decoded content, populated for text/plain and text/html only. */
+    decoded: DecodedText | null;
+}
+/** Headers the analysis cares about, decoded and normalised. Any of them may be missing. */
+export interface MessageHeaders {
+    messageId: string | null;
+    inReplyTo: string | null;
+    references: string[];
+    from: string | null;
+    to: string | null;
+    cc: string | null;
+    date: string | null;
+    /** Parsed date as epoch milliseconds, or null when absent or unparseable. */
+    dateMs: number | null;
+    subject: string | null;
+    contentType: string | null;
+    userAgent: string | null;
+    xMailer: string | null;
+    listId: string | null;
+    listUnsubscribe: string | null;
+    precedence: string | null;
+    autoSubmitted: string | null;
+}
+export interface ParsedMessage {
+    /** All parts keyed by partId, in document order. */
+    parts: MimePart[];
+    partsById: Map<string, MimePart>;
+    rootId: string;
+    headers: MessageHeaders;
+    /** Every header line of the outermost message, for diagnostics and client fingerprinting. */
+    rootHeaders: HeaderEntry[];
+    warnings: Warning[];
+    /** Total size of the raw message in bytes. */
+    size: number;
+    /** Compact structural signature, for example "m/alternative(P,H)". */
+    structure: string;
+}
+export interface ParseOptions {
+    /** Maximum decoded bytes retained per text part. Default 1 MiB. */
+    maxTextPartBytes?: number;
+    /** Maximum number of parts before the walk stops recording. Default 500. */
+    maxParts?: number;
+    /** Maximum raw header block size per part, passed to mailsplit. Default 1 MiB. */
+    maxHeadSize?: number;
+    /** Treat message/rfc822 as an opaque leaf instead of descending into it. Default false. */
+    ignoreEmbedded?: boolean;
+}
+export declare const DEFAULT_PARSE_OPTIONS: Required<ParseOptions>;
+//# sourceMappingURL=model.d.ts.map

package/dist/mime/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/mime/model.ts"],"names":[],"mappings":"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"}

package/dist/mime/model.js

@@ -0,0 +1,17 @@
+"use strict";
+/**
+ * Normalised internal representation of a parsed message.
+ *
+ * The MIME tree is preserved as a tree. Nothing is flattened into a single html/text pair, because
+ * the extractor needs to know which text part is the alternative sibling of which html part, and
+ * needs to be able to point at the exact bytes a segment came from.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_PARSE_OPTIONS = void 0;
+exports.DEFAULT_PARSE_OPTIONS = {
+    maxTextPartBytes: 1024 * 1024,
+    maxParts: 500,
+    maxHeadSize: 1024 * 1024,
+    ignoreEmbedded: false
+};
+//# sourceMappingURL=model.js.map

package/dist/mime/model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.js","sourceRoot":"","sources":["../../src/mime/model.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAgHU,QAAA,qBAAqB,GAA2B;IACzD,gBAAgB,EAAE,IAAI,GAAG,IAAI;IAC7B,QAAQ,EAAE,GAAG;IACb,WAAW,EAAE,IAAI,GAAG,IAAI;IACxB,cAAc,EAAE,KAAK;CACxB,CAAC"}

package/dist/mime/parse.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Stage 1: MIME parsing.
+ *
+ * Built on @zone-eu/mailsplit rather than a full parser, because mailsplit is the only local option
+ * that walks the tree non-destructively: it emits raw header bytes and raw body chunks in document
+ * order, byte for byte, and gives every node an IMAP style part number. That is what makes the
+ * traceability requirement satisfiable. postal-mime and mailparser both collapse the tree into a
+ * single html/text pair and discard byte spans.
+ *
+ * Byte offsets are not exposed as a field by mailsplit, so this module reconstructs them by
+ * accumulating chunk lengths in emission order. mailsplit's own round trip test asserts that the
+ * concatenation of all chunks equals the input, which is what makes the running sum exact.
+ *
+ * Nothing in here throws for malformed input. Problems are recorded as warnings and the walk
+ * continues, because a corpus run must never stop on one bad message.
+ */
+import { type MimePart, type ParseOptions, type ParsedMessage } from './model';
+/** Compact structural signature such as "m/alternative(P,H)", used for corpus statistics. */
+export declare function structureSignature(parts: readonly MimePart[], partsById: ReadonlyMap<string, MimePart>, rootId: string): string;
+/**
+ * Parse a raw RFC 5322 message into the normalised internal representation.
+ *
+ * Never rejects on malformed input. The only rejection path is an internal stream error, and even
+ * that is converted into a parsed message carrying a `mime_parse_error` warning.
+ */
+export declare function parseMessage(raw: Buffer, options?: ParseOptions): Promise<ParsedMessage>;
+//# sourceMappingURL=parse.d.ts.map

package/dist/mime/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../../src/mime/parse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAQH,OAAO,EAA2C,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,MAAM,SAAS,CAAC;AA4HxH,6FAA6F;AAC7F,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,SAAS,QAAQ,EAAE,EAAE,SAAS,EAAE,WAAW,CAAC,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CA0B/H;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,GAAE,YAAiB,GAAG,OAAO,CAAC,aAAa,CAAC,CAgMlG"}

package/dist/mime/parse.js

@@ -0,0 +1,343 @@
+"use strict";
+/**
+ * Stage 1: MIME parsing.
+ *
+ * Built on @zone-eu/mailsplit rather than a full parser, because mailsplit is the only local option
+ * that walks the tree non-destructively: it emits raw header bytes and raw body chunks in document
+ * order, byte for byte, and gives every node an IMAP style part number. That is what makes the
+ * traceability requirement satisfiable. postal-mime and mailparser both collapse the tree into a
+ * single html/text pair and discard byte spans.
+ *
+ * Byte offsets are not exposed as a field by mailsplit, so this module reconstructs them by
+ * accumulating chunk lengths in emission order. mailsplit's own round trip test asserts that the
+ * concatenation of all chunks equals the input, which is what makes the running sum exact.
+ *
+ * Nothing in here throws for malformed input. Problems are recorded as warnings and the walk
+ * continues, because a corpus run must never stop on one bad message.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.structureSignature = structureSignature;
+exports.parseMessage = parseMessage;
+const mailsplit_1 = require("@zone-eu/mailsplit");
+const libmime_1 = __importDefault(require("libmime"));
+const charset_1 = require("./charset");
+const headers_1 = require("./headers");
+const model_1 = require("./model");
+/** Content types whose bodies are decoded and retained. Everything else is measured and dropped. */
+const TEXT_TYPES = new Set(['text/plain', 'text/html']);
+function partIdOf(partNr) {
+    if (!partNr || partNr.length === 0) {
+        return 'TEXT';
+    }
+    return partNr.join('.');
+}
+function normaliseDisposition(value) {
+    if (!value) {
+        return null;
+    }
+    const lowered = String(value).toLowerCase();
+    if (lowered.startsWith('attachment')) {
+        return 'attachment';
+    }
+    if (lowered.startsWith('inline')) {
+        return 'inline';
+    }
+    return null;
+}
+/** Decode one text part: transfer encoding, then charset, then format=flowed. */
+async function decodeTextPart(pending, maxBytes, warnings) {
+    const { part, node } = pending;
+    const raw = Buffer.concat(pending.bodyChunks, pending.bodyBytes);
+    let transferDecoded;
+    try {
+        transferDecoded = await runDecoder(node, raw);
+    }
+    catch (err) {
+        warnings.push({
+            code: 'transfer_encoding_error',
+            mimePart: part.partId,
+            detail: `${part.encoding || 'unknown'}: ${errorLabel(err)}`
+        });
+        transferDecoded = raw;
+    }
+    let truncated = false;
+    if (transferDecoded.length > maxBytes) {
+        transferDecoded = transferDecoded.subarray(0, maxBytes);
+        truncated = true;
+        warnings.push({ code: 'text_part_truncated', mimePart: part.partId, detail: `capped at ${maxBytes} bytes` });
+    }
+    const decoded = (0, charset_1.decodeCharset)(transferDecoded, part.charset);
+    if (decoded.fellBack) {
+        warnings.push({
+            code: 'unknown_charset',
+            mimePart: part.partId,
+            detail: `declared ${part.charset || 'none'}, used ${decoded.charsetUsed}`
+        });
+    }
+    if (decoded.replacementChars > 0) {
+        warnings.push({
+            code: 'charset_decode_replacement_chars',
+            mimePart: part.partId,
+            detail: `${decoded.replacementChars} replacement characters`
+        });
+    }
+    let text = decoded.text;
+    if (part.flowed && part.contentType === 'text/plain') {
+        try {
+            text = libmime_1.default.decodeFlowed(text, part.delSp);
+        }
+        catch {
+            // Keep the unfolded text. A failed flowed decode is cosmetic, never a reason to lose content.
+        }
+    }
+    return {
+        text,
+        charsetUsed: decoded.charsetUsed,
+        charsetDeclared: part.charset,
+        replacementChars: decoded.replacementChars,
+        truncated
+    };
+}
+/** Run mailsplit's transfer decoder over a buffer, using its public streaming interface. */
+function runDecoder(node, raw) {
+    return new Promise((resolve, reject) => {
+        let decoder;
+        try {
+            decoder = node.getDecoder();
+        }
+        catch (err) {
+            reject(err);
+            return;
+        }
+        const chunks = [];
+        let size = 0;
+        decoder.on('data', (chunk) => {
+            chunks.push(chunk);
+            size += chunk.length;
+        });
+        decoder.on('error', reject);
+        decoder.on('end', () => resolve(Buffer.concat(chunks, size)));
+        decoder.end(raw);
+    });
+}
+function errorLabel(err) {
+    if (err instanceof Error) {
+        return err.message.slice(0, 200);
+    }
+    return String(err).slice(0, 200);
+}
+/** Compact structural signature such as "m/alternative(P,H)", used for corpus statistics. */
+function structureSignature(parts, partsById, rootId) {
+    const render = (id, depth) => {
+        if (depth > 12) {
+            return '...';
+        }
+        const part = partsById.get(id);
+        if (!part) {
+            return '?';
+        }
+        if (part.multipart) {
+            const children = part.childIds.map(child => render(child, depth + 1)).join(',');
+            return `m/${part.multipart}(${children})`;
+        }
+        if (part.rfc822 && part.childIds.length) {
+            return `rfc822[${part.childIds.map(child => render(child, depth + 1)).join(',')}]`;
+        }
+        if (part.contentType === 'text/plain') {
+            return 'P';
+        }
+        if (part.contentType === 'text/html') {
+            return 'H';
+        }
+        const major = part.contentType.split('/')[0] || 'unknown';
+        return major;
+    };
+    return parts.length ? render(rootId, 0) : '(empty)';
+}
+/**
+ * Parse a raw RFC 5322 message into the normalised internal representation.
+ *
+ * Never rejects on malformed input. The only rejection path is an internal stream error, and even
+ * that is converted into a parsed message carrying a `mime_parse_error` warning.
+ */
+async function parseMessage(raw, options = {}) {
+    const opts = { ...model_1.DEFAULT_PARSE_OPTIONS, ...options };
+    const warnings = [];
+    const pendingParts = [];
+    const partsById = new Map();
+    let offset = 0;
+    let rootId = 'TEXT';
+    let rootHeaderList = [];
+    let truncatedTree = false;
+    await new Promise(resolve => {
+        const splitter = new mailsplit_1.Splitter({
+            maxHeadSize: opts.maxHeadSize,
+            maxChildNodes: opts.maxParts,
+            ignoreEmbedded: opts.ignoreEmbedded
+        });
+        let settled = false;
+        const finish = () => {
+            if (!settled) {
+                settled = true;
+                resolve();
+            }
+        };
+        splitter.on('data', chunk => {
+            if (chunk.type === 'node') {
+                const node = chunk;
+                let headerBytes;
+                try {
+                    headerBytes = node.getHeaders();
+                }
+                catch (err) {
+                    warnings.push({ code: 'mime_parse_error', detail: errorLabel(err) });
+                    headerBytes = Buffer.alloc(0);
+                }
+                const headerStart = offset;
+                offset += headerBytes.length;
+                if (pendingParts.length >= opts.maxParts) {
+                    if (!truncatedTree) {
+                        truncatedTree = true;
+                        warnings.push({ code: 'max_parts_exceeded', detail: `stopped after ${opts.maxParts} parts` });
+                    }
+                    return;
+                }
+                const headerList = node.headers ? node.headers.getList() : [];
+                const entries = (0, headers_1.toHeaderEntries)(headerList);
+                const contentTypeHeader = entries.find(entry => entry.key === 'content-type');
+                const ctParams = contentTypeHeader ? (0, headers_1.parseHeaderValueSafe)(contentTypeHeader.value).params : {};
+                const partId = partIdOf(node.partNr);
+                const parentId = node.parentNode ? partIdOf(node.parentNode.partNr) : null;
+                const part = {
+                    partId,
+                    partNr: node.partNr ? [...node.partNr] : ['TEXT'],
+                    contentType: node.contentType ? String(node.contentType).toLowerCase() : 'text/plain',
+                    contentTypeParams: ctParams,
+                    charset: node.charset ? String(node.charset) : null,
+                    encoding: node.encoding ? String(node.encoding).toLowerCase() : null,
+                    disposition: normaliseDisposition(node.disposition),
+                    filename: node.filename ? String(node.filename) : null,
+                    multipart: node.multipart ? String(node.multipart) : null,
+                    rfc822: Boolean(node.rfc822),
+                    embeddedRoot: Boolean(node.messageNode),
+                    flowed: Boolean(node.flowed),
+                    delSp: Boolean(node.delSp),
+                    parentId,
+                    childIds: [],
+                    headerRange: { start: headerStart, end: offset },
+                    bodyRange: null,
+                    rawBodySize: 0,
+                    headers: entries,
+                    decoded: null
+                };
+                const pending = {
+                    part,
+                    node,
+                    bodyChunks: [],
+                    bodyBytes: 0,
+                    collecting: TEXT_TYPES.has(part.contentType),
+                    nonContiguous: false
+                };
+                if (node.root) {
+                    rootId = partId;
+                    rootHeaderList = headerList;
+                }
+                // Duplicate part ids can occur in pathological messages. Keep the first, so that
+                // references from children stay stable.
+                if (!partsById.has(partId)) {
+                    partsById.set(partId, pending);
+                    pendingParts.push(pending);
+                    if (parentId) {
+                        const parent = partsById.get(parentId);
+                        if (parent) {
+                            parent.part.childIds.push(partId);
+                        }
+                    }
+                }
+                return;
+            }
+            const value = chunk.value;
+            const start = offset;
+            offset += value.length;
+            if (chunk.type !== 'body' || !chunk.node) {
+                return;
+            }
+            const owner = partsById.get(partIdOf(chunk.node.partNr));
+            if (!owner) {
+                return;
+            }
+            if (owner.part.bodyRange && owner.part.bodyRange.end !== start) {
+                owner.nonContiguous = true;
+            }
+            owner.part.bodyRange = { start: owner.part.bodyRange ? owner.part.bodyRange.start : start, end: offset };
+            owner.part.rawBodySize += value.length;
+            if (owner.collecting) {
+                // Guard against a single enormous text part exhausting memory. Collect a little more
+                // than the cap so that the truncation warning is accurate.
+                if (owner.bodyBytes < opts.maxTextPartBytes * 2) {
+                    owner.bodyChunks.push(value);
+                    owner.bodyBytes += value.length;
+                }
+            }
+        });
+        // The bundled typings narrow `on` to the 'data' event only, which shadows the inherited
+        // Transform overloads and makes the class structurally incompatible with Transform. Register
+        // lifecycle listeners through a minimal local view instead.
+        const lifecycle = splitter;
+        lifecycle.on('error', (err) => {
+            warnings.push({ code: 'mime_parse_error', detail: errorLabel(err) });
+            finish();
+        });
+        lifecycle.on('end', finish);
+        lifecycle.on('close', finish);
+        try {
+            splitter.end(raw);
+        }
+        catch (err) {
+            warnings.push({ code: 'mime_parse_error', detail: errorLabel(err) });
+            finish();
+        }
+    });
+    for (const pending of pendingParts) {
+        if (pending.nonContiguous) {
+            warnings.push({ code: 'non_contiguous_body', mimePart: pending.part.partId });
+        }
+        if (pending.collecting && pending.bodyBytes > 0) {
+            pending.part.decoded = await decodeTextPart(pending, opts.maxTextPartBytes, warnings);
+        }
+        else if (pending.collecting) {
+            pending.part.decoded = {
+                text: '',
+                charsetUsed: pending.part.charset || 'utf-8',
+                charsetDeclared: pending.part.charset,
+                replacementChars: 0,
+                truncated: false
+            };
+        }
+        // Release references to raw chunks as soon as they are no longer needed.
+        pending.bodyChunks.length = 0;
+    }
+    const parts = pendingParts.map(pending => pending.part);
+    const byId = new Map(parts.map(part => [part.partId, part]));
+    const rootHeaders = (0, headers_1.toHeaderEntries)(rootHeaderList);
+    if (!parts.length) {
+        warnings.push({ code: 'mime_parse_error', detail: 'no MIME nodes produced' });
+    }
+    if (!parts.some(part => TEXT_TYPES.has(part.contentType))) {
+        warnings.push({ code: 'no_body_parts' });
+    }
+    return {
+        parts,
+        partsById: byId,
+        rootId,
+        headers: (0, headers_1.extractMessageHeaders)(rootHeaders),
+        rootHeaders,
+        warnings,
+        size: raw.length,
+        structure: structureSignature(parts, byId, rootId)
+    };
+}
+//# sourceMappingURL=parse.js.map