@remit/ui 0.0.17 → 0.0.19

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/ui",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "type": "module",
   "files": [
     "src"

package/src/components/quarantine-entry-row.tsx

@@ -41,7 +41,11 @@ export function QuarantineEntryRow({
 					{entry.failureMessage}
 				</p>
 				<p className="flex flex-wrap items-center gap-x-2 gap-y-1 text-2xs text-fg-subtle">
-					<Badge tone="warning">{canonicalRoleLabel(entry.mailboxRole)}</Badge>
+					{entry.mailboxRole && (
+						<Badge tone="warning">
+							{canonicalRoleLabel(entry.mailboxRole)}
+						</Badge>
+					)}
 					<span className="truncate" title={entry.mailboxPath}>
 						{providerLeaf(entry.mailboxPath)}
 					</span>

package/src/components/quarantine-fixtures.ts

@@ -3,43 +3,42 @@ import type { QuarantineEntry } from "./quarantine-report.js";
 /**
  * Demo entries backing the quarantine stories. Exported so the kit's own
  * stories and the workbench settings screen render the same data — they had
- * drifted on `appVersion` when each file carried its own copy.
+ * drifted on the worker build when each file carried its own copy.
  */
 export const quarantineDemoEntries: readonly QuarantineEntry[] = [
 	{
 		quarantineId: "q-1",
 		accountId: "acct-1",
 		mailboxId: "mbx-inbox",
+		uidValidity: 1_712_000_000,
 		uid: 40217,
 		mailboxRole: "inbox",
 		mailboxPath: "INBOX",
 		failureStage: "BodyParse",
-		failureCode: "UnterminatedMultipartBoundary",
+		failureCode: "UnreadableBody",
 		failureMessage: "multipart boundary was never closed",
-		failurePartPath: null,
+		failurePartPath: undefined,
 		quarantinedAt: Date.parse("2026-07-18T09:12:00Z"),
 		attempts: 3,
 		sizeBytes: 184_233,
 		contentType: "multipart/mixed",
 		transferEncoding: "7bit",
 		charset: "utf-8",
-		structure: {
-			contentType: "multipart/mixed",
-			parts: [
-				{
-					contentType: "multipart/alternative",
-					parts: [{ contentType: "text/plain" }, { contentType: "text/html" }],
-				},
-				{ contentType: "application/pdf" },
-			],
-		},
+		structure: [
+			{ depth: 0, contentType: "multipart/mixed" },
+			{ depth: 1, contentType: "multipart/alternative" },
+			{ depth: 2, contentType: "text/plain" },
+			{ depth: 2, contentType: "text/html" },
+			{ depth: 1, contentType: "application/pdf" },
+		],
 		messageIdHash: "sha256:6f1c4a9d20",
-		appVersion: "worker 1.0.0",
+		workerVersion: "worker 1.0.0",
 	},
 	{
 		quarantineId: "q-2",
 		accountId: "acct-1",
 		mailboxId: "mbx-archive",
+		uidValidity: 1_712_000_100,
 		uid: 40219,
 		mailboxRole: "archive",
 		mailboxPath: "Archive/2026",
@@ -53,29 +52,57 @@ export const quarantineDemoEntries: readonly QuarantineEntry[] = [
 		contentType: "text/plain",
 		transferEncoding: "quoted-printable",
 		charset: "x-user-defined",
-		structure: { contentType: "text/plain" },
+		structure: [{ depth: 0, contentType: "text/plain" }],
 		messageIdHash: "sha256:b31e0744af",
-		appVersion: "worker 1.0.0",
+		workerVersion: "worker 1.0.0",
 	},
 	{
 		quarantineId: "q-3",
 		accountId: "acct-1",
 		mailboxId: "mbx-junk",
+		uidValidity: 1_712_000_200,
 		uid: 40251,
-		mailboxRole: "junk",
-		mailboxPath: "Junk",
+		// A folder the user never appointed a role to — the ordinary state of a
+		// plain folder, and the reason mailboxRole is optional.
+		mailboxRole: undefined,
+		mailboxPath: "Clients/Acme Holdings",
 		failureStage: "BodyParse",
-		failureCode: "TruncatedBody",
+		failureCode: "UnreadableBody",
 		failureMessage: "stream ended before the declared body length",
-		failurePartPath: null,
+		failurePartPath: undefined,
 		quarantinedAt: Date.parse("2026-07-19T06:03:00Z"),
 		attempts: 1,
 		sizeBytes: 2_140,
 		contentType: "text/html",
 		transferEncoding: "base64",
-		charset: null,
-		structure: { contentType: "text/html" },
+		charset: undefined,
+		structure: [{ depth: 0, contentType: "text/html" }],
 		messageIdHash: "sha256:0a77de1c05",
-		appVersion: "worker 1.0.0",
+		workerVersion: "worker 1.0.0",
+	},
+	{
+		// The message shape is absent as a set: a message that failed before its
+		// BODYSTRUCTURE was read carries no content type, encoding, size or
+		// tree, and one that declared no Message-ID carries no hash either.
+		quarantineId: "q-4",
+		accountId: "acct-1",
+		mailboxId: "mbx-inbox",
+		uidValidity: 1_712_000_000,
+		uid: 40263,
+		mailboxRole: "inbox",
+		mailboxPath: "INBOX",
+		failureStage: "BodyParse",
+		failureCode: "UnreadableBody",
+		failureMessage: "connection closed mid-body",
+		failurePartPath: undefined,
+		quarantinedAt: Date.parse("2026-07-19T11:27:00Z"),
+		attempts: 2,
+		sizeBytes: undefined,
+		contentType: undefined,
+		transferEncoding: undefined,
+		charset: undefined,
+		structure: [],
+		messageIdHash: undefined,
+		workerVersion: "worker 1.0.0",
 	},
 ];

package/src/components/quarantine-report.test.ts

@@ -20,7 +20,7 @@ describe("formatQuarantineReport", () => {
 	it("names the stage, the code and the build that failed", () => {
 		const report = formatQuarantineReport(entry);
 		assert.match(report, /BodyParse/);
-		assert.match(report, /UnterminatedMultipartBoundary/);
+		assert.match(report, /UnreadableBody/);
 		assert.match(report, /worker 1\.0\.0/);
 	});
 
@@ -48,15 +48,13 @@ describe("formatQuarantineReport", () => {
 		const report = formatQuarantineReport({
 			...entry,
 			contentType: 'multipart/mixed; boundary="=_a1b2"',
-			structure: {
-				contentType: "multipart/mixed",
-				parts: [
-					{
-						contentType:
-							'application/octet-stream; name="Q3 payroll — Acme.pdf"',
-					},
-				],
-			},
+			structure: [
+				{ depth: 0, contentType: "multipart/mixed" },
+				{
+					depth: 1,
+					contentType: 'application/octet-stream; name="Q3 payroll — Acme.pdf"',
+				},
+			],
 		});
 		assert.doesNotMatch(report, /payroll/);
 		assert.doesNotMatch(report, /boundary/);
@@ -71,10 +69,39 @@ describe("formatQuarantineReport", () => {
 		);
 	});
 
+	it("says no role was appointed rather than inventing one", () => {
+		const report = formatQuarantineReport({
+			...entry,
+			mailboxRole: undefined,
+		});
+		assert.match(report, /Folder role.*none appointed/);
+	});
+
 	it("marks an undeclared charset rather than omitting it", () => {
-		const report = formatQuarantineReport({ ...entry, charset: null });
+		const report = formatQuarantineReport({ ...entry, charset: undefined });
 		assert.match(report, /Charset.*not declared/);
 	});
+
+	// Absent is the wire shape: the API omits an optional diagnostic and the
+	// repo maps a null column to undefined. A report that printed `undefined`
+	// into a public issue would do it on the common case — a whole-body parse
+	// failure has no failing part, which is every failure today.
+	it("never prints undefined for a diagnostic the message did not carry", () => {
+		const report = formatQuarantineReport({
+			...entry,
+			failurePartPath: undefined,
+			charset: undefined,
+			contentType: undefined,
+			transferEncoding: undefined,
+			sizeBytes: undefined,
+			messageIdHash: undefined,
+			structure: [],
+		});
+		assert.doesNotMatch(report, /undefined|null/);
+		assert.match(report, /Failing part.*whole message/);
+		assert.match(report, /Message-ID hash.*none declared/);
+		assert.match(report, /no MIME structure was read/);
+	});
 });
 
 describe("sender-controlled BODYSTRUCTURE strings", () => {
@@ -109,16 +136,38 @@ describe("sender-controlled BODYSTRUCTURE strings", () => {
 	it("keeps a hostile node type from closing the MIME fence", () => {
 		const report = formatQuarantineReport({
 			...entry,
-			structure: {
-				contentType: "multipart/mixed",
-				parts: [{ contentType: "```\n## Injected heading" }],
-			},
+			structure: [
+				{ depth: 0, contentType: "multipart/mixed" },
+				{ depth: 1, contentType: "```\n## Injected heading" },
+			],
 		});
 		assert.equal((report.match(/^```/gm) ?? []).length, 2);
 		assert.doesNotMatch(report, /^## Injected heading/m);
 	});
 });
 
+describe("a message that failed before its shape was read", () => {
+	const shapeless: QuarantineEntry = {
+		...entry,
+		contentType: undefined,
+		transferEncoding: undefined,
+		sizeBytes: undefined,
+		structure: [],
+	};
+
+	it("says the shape was never read rather than guessing one", () => {
+		const report = formatQuarantineReport(shapeless);
+		assert.match(report, /Content-Type.*not read/);
+		assert.match(report, /Content-Transfer-Encoding.*not read/);
+		assert.match(report, /Size.*not read/);
+	});
+
+	it("keeps the fence balanced with an empty tree", () => {
+		const report = formatQuarantineReport(shapeless);
+		assert.equal((report.match(/^```/gm) ?? []).length, 2);
+	});
+});
+
 describe("quarantineReportSections", () => {
 	it("hands the MIME tree over unfenced, so it can be truncated safely", () => {
 		const { head, structure, disclaimer } = quarantineReportSections(entry);
@@ -137,7 +186,7 @@ describe("quarantineReportSections", () => {
 describe("quarantineIssueTitle", () => {
 	it("carries only the closed vocabulary", () => {
 		const title = quarantineIssueTitle(entry);
-		assert.match(title, /UnterminatedMultipartBoundary/);
+		assert.match(title, /UnreadableBody/);
 		assert.match(title, /BodyParse/);
 		assert.doesNotMatch(title, /joan@/);
 	});

package/src/components/quarantine-report.ts

@@ -3,31 +3,17 @@ import type { FolderRole } from "./folder-role.js";
 /**
  * The pipeline step that refused the message.
  *
- * One member, because **no catch site on the sync path can currently tell a
- * parse failure from an infrastructure failure**. The per-message frame in
- * `body-sync.ts` wraps the S3 body write, the parsed-body cache write, the
- * body-part `pMap` and DynamoDB upsert, the placement move (SQS + DynamoDB)
- * and the label and counter writes, alongside the `simpleParser` call; only
- * connection drops are filtered out of it.
+ * One member, behind a real narrowing rather than a promise of one: the body
+ * parse has its own try block around the parse call and nothing else, so an
+ * error out of it can only be the message. S3, queue and database failures
+ * propagate and never become a record here — quarantining one would set a
+ * message aside for an outage, tell the user it was unreadable, and invite a
+ * public GitHub issue about it.
  *
- * **Precondition on Phase 3**: narrow the try block to the parse call before
- * quarantining anything. Quarantining at the frame as it stands would set a
- * message aside for a DynamoDB throttle, tell the user it was unreadable, and
- * invite a public GitHub issue for an outage — the same defect as naming an
- * S3 write `AttachmentExtract`, one layer up.
- *
- * There are three distinct parse sites, and a quarantine would have to
- * attribute them differently: the fresh-fetch path, `backfillClassification`
- * (its own parse over a different result list), and the header parse in
- * `imapflow-connection.ts`, which is swallowed and treated as "no thread
- * parent". Stages are added as those sites are separated — never ahead of it.
- *
- * The stages this replaced could not fire at all: an unparseable Date falls
- * back to INTERNALDATE, and an unrecognized MIME type maps to a safe default
- * rather than throwing. Unparseable addresses are dropped with a `continue`
- * and the message is written anyway — so that defect is reached but discarded,
- * never raised, which is a reason to have no `AddressParse` stage but not the
- * reason that it cannot happen.
+ * A message that arrives with no ENVELOPE is deliberately not a member:
+ * nothing can tell that apart from the FETCH row glitching, and the IMAP
+ * client is far more often the cause than the message. The sync path holds its
+ * cursor and retries instead.
  */
 export type QuarantineFailureStage = "BodyParse";
 
@@ -36,16 +22,23 @@ export type QuarantineFailureStage = "BodyParse";
  *
  * Closed, because `quarantineIssueTitle` interpolates it into a public issue
  * title: a `string` here would make the one field whose publishability is
- * asserted rather than derived into free text. Grows with the narrowing
- * described on `QuarantineFailureStage`, and no faster.
+ * asserted rather than derived into free text.
+ *
+ * Total and small. The body parser reports its refusals as free text with no
+ * stable type or code, so a member exists only where the writer can identify
+ * the defect without reading parser prose; anything it cannot name is
+ * `UnreadableBody`, and the parser's own words stay in `failureMessage`, which
+ * is shown on screen and never published.
  */
-export type QuarantineFailureCode =
-	| "UnterminatedMultipartBoundary"
-	| "UnknownCharset"
-	| "TruncatedBody";
+export type QuarantineFailureCode = "UnknownCharset" | "UnreadableBody";
 
 /**
- * A node in the message's MIME tree.
+ * One node of the message's MIME tree, in a pre-order walk.
+ *
+ * The tree arrives flat with an explicit `depth` rather than as nested
+ * children: a self-referential model is not expressible in the schema this
+ * comes from, and the tree is only ever rendered as an indented list, which a
+ * pre-order walk reproduces exactly.
  *
  * `contentType` is `type/subtype` only. BODYSTRUCTURE hands the type and its
  * parameters over separately, so a node is built from `type`/`subtype` and
@@ -53,8 +46,8 @@ export type QuarantineFailureCode =
  * `filename=`, which name the user's attachments.
  */
 export interface QuarantineMimeNode {
+	depth: number;
 	contentType: string;
-	parts?: readonly QuarantineMimeNode[];
 }
 
 /**
@@ -70,10 +63,19 @@ export interface QuarantineEntry {
 	quarantineId: string;
 	accountId: string;
 	mailboxId: string;
+	/**
+	 * UIDVALIDITY of the mailbox when the message was set aside. A uid names a
+	 * message only alongside it.
+	 */
+	uidValidity: number;
 	/** IMAP uid of the message that was not written. */
 	uid: number;
-	/** Canonical role of the folder it arrived in — travels in the report. */
-	mailboxRole: FolderRole;
+	/**
+	 * Canonical role of the folder it arrived in — travels in the report.
+	 * Absent when the user appointed no role to that folder, which is the
+	 * ordinary state of a plain folder.
+	 */
+	mailboxRole?: FolderRole;
 	/** The user's own folder name. Shown on screen, withheld from the report. */
 	mailboxPath: string;
 	failureStage: QuarantineFailureStage;
@@ -81,26 +83,36 @@ export interface QuarantineEntry {
 	/** Parser error text. Shown on screen, never in the report. */
 	failureMessage: string;
 	/**
-	 * Dot-numbered part path the failure is attributable to, or null when it is
-	 * not attributable to one node — the case for a whole-body parse failure.
+	 * Dot-numbered part path the failure is attributable to. Absent when it is
+	 * not attributable to one node — the case for a whole-body parse failure,
+	 * which is every failure today.
 	 */
-	failurePartPath: string | null;
+	failurePartPath?: string;
 	/** Epoch millis the message was quarantined. */
 	quarantinedAt: number;
 	/** Rounds attempted before the message was set aside. */
 	attempts: number;
-	sizeBytes: number;
+	/**
+	 * The message-shape fields all come off BODYSTRUCTURE and RFC822.SIZE in
+	 * the same FETCH, so a message that failed before either was read carries
+	 * none of them — they are absent together, and `structure` is empty.
+	 */
+	sizeBytes?: number;
 	/** Top-level Content-Type, `type/subtype` only. */
-	contentType: string;
-	transferEncoding: string;
-	/** Declared charset, or null when the message declared none. */
-	charset: string | null;
-	/** The MIME tree, structure only. */
-	structure: QuarantineMimeNode;
-	/** SHA-256 of the Message-ID, `sha256:` prefixed. */
-	messageIdHash: string;
+	contentType?: string;
+	transferEncoding?: string;
+	/** Declared charset. Absent when the message declared none. */
+	charset?: string;
+	/** The MIME tree, structure only, as a pre-order walk. */
+	structure: readonly QuarantineMimeNode[];
+	/**
+	 * SHA-256 of the Message-ID, `sha256:` prefixed. Absent when the message
+	 * declared no Message-ID — a shared hash of nothing would correlate
+	 * unrelated reports.
+	 */
+	messageIdHash?: string;
 	/** Build of the worker that failed to parse — a parse bug belongs to it. */
-	appVersion: string;
+	workerVersion: string;
 }
 
 const stageSummaries: Record<QuarantineFailureStage, string> = {
@@ -146,13 +158,18 @@ function renderNodeType(contentType: string): string {
 	return JSON.stringify(stripped);
 }
 
-function renderStructure(node: QuarantineMimeNode, depth = 0): string[] {
-	const line = `${"  ".repeat(depth)}- ${renderNodeType(node.contentType)}`;
-	const children = node.parts ?? [];
-	return [
-		line,
-		...children.flatMap((part) => renderStructure(part, depth + 1)),
-	];
+/**
+ * What a message-shape field reads as when the message failed before its
+ * BODYSTRUCTURE was read. Distinct from "not declared", which is a statement
+ * about the message rather than about how far sync got.
+ */
+const NOT_READ = "_not read_";
+
+function renderStructure(nodes: readonly QuarantineMimeNode[]): string[] {
+	if (nodes.length === 0) return ["(no MIME structure was read)"];
+	return nodes.map(
+		(node) => `${"  ".repeat(node.depth)}- ${renderNodeType(node.contentType)}`,
+	);
 }
 
 export const QUARANTINE_REPORT_DISCLAIMER =
@@ -182,18 +199,18 @@ export function quarantineReportSections(
 		`### Message quarantined at \`${entry.failureStage}\``,
 		"",
 		`- **Failure**: \`${entry.failureCode}\``,
-		`- **Folder role**: ${entry.mailboxRole}`,
-		`- **Failing part**: ${entry.failurePartPath === null ? "_whole message_" : `\`${entry.failurePartPath}\``}`,
+		`- **Folder role**: ${entry.mailboxRole ?? "_none appointed_"}`,
+		`- **Failing part**: ${entry.failurePartPath == null ? "_whole message_" : `\`${entry.failurePartPath}\``}`,
 		`- **Attempts before quarantine**: ${entry.attempts}`,
-		`- **Worker build**: ${entry.appVersion}`,
-		`- **Message-ID hash**: \`${entry.messageIdHash}\``,
+		`- **Worker build**: ${entry.workerVersion}`,
+		`- **Message-ID hash**: ${entry.messageIdHash == null ? "_none declared_" : `\`${entry.messageIdHash}\``}`,
 		"",
 		"#### Message shape",
 		"",
-		`- **Content-Type**: ${renderToken(stripParameters(entry.contentType), MEDIA_TYPE)}`,
-		`- **Content-Transfer-Encoding**: ${renderToken(entry.transferEncoding, TOKEN)}`,
-		`- **Charset**: ${entry.charset === null ? "_not declared_" : renderToken(entry.charset, TOKEN)}`,
-		`- **Size**: ${entry.sizeBytes} bytes`,
+		`- **Content-Type**: ${entry.contentType == null ? NOT_READ : renderToken(stripParameters(entry.contentType), MEDIA_TYPE)}`,
+		`- **Content-Transfer-Encoding**: ${entry.transferEncoding == null ? NOT_READ : renderToken(entry.transferEncoding, TOKEN)}`,
+		`- **Charset**: ${entry.charset == null ? "_not declared_" : renderToken(entry.charset, TOKEN)}`,
+		`- **Size**: ${entry.sizeBytes == null ? NOT_READ : `${entry.sizeBytes} bytes`}`,
 		"",
 		"MIME structure:",
 	].join("\n");

package/src/components/quarantine-section.render.test.ts

@@ -8,7 +8,7 @@ import type { QuarantineEntry } from "./quarantine-report.js";
 import { QuarantineSection } from "./quarantine-section.js";
 
 const noop = () => {};
-const [base, second] = quarantineDemoEntries;
+const [base, second, unappointedFolder] = quarantineDemoEntries;
 const ISSUE_URL = "https://github.com/remit-mail/reader/issues/new?title=x";
 
 const render = (entries: readonly QuarantineEntry[]) =>
@@ -38,6 +38,12 @@ describe("QuarantineSection", () => {
 		assert.match(html, /multipart boundary was never closed/);
 	});
 
+	it("names no role for a folder the user never appointed one to", () => {
+		const html = render([unappointedFolder]);
+		assert.doesNotMatch(html, /Inbox|Spam|Archive/);
+		assert.match(html, /Acme Holdings/);
+	});
+
 	it("offers reporting as the only per-row action", () => {
 		const html = render([base]);
 		assert.match(html, /Cut a bug/);
@@ -55,7 +61,7 @@ describe("QuarantineBugDialog", () => {
 				issueUrl: ISSUE_URL,
 			}),
 		);
-		assert.match(html, /UnterminatedMultipartBoundary/);
+		assert.match(html, /UnreadableBody/);
 		assert.match(html, /attachment names, or the parser's own error text/);
 		assert.match(html, /Copy report/);
 	});

package/src/components/quarantine-section.stories.tsx

@@ -5,7 +5,7 @@ import { quarantineDemoEntries } from "./quarantine-fixtures.js";
 import type { QuarantineEntry } from "./quarantine-report.js";
 import { QuarantineSection } from "./quarantine-section.js";
 
-const [unterminatedBoundary, unknownCharset, truncatedBody] =
+const [unterminatedBoundary, unknownCharset, truncatedBody, shapeUnread] =
 	quarantineDemoEntries;
 
 /**
@@ -62,6 +62,22 @@ export const CutABugFlow: Story = {
 	},
 };
 
+/**
+ * A message that failed before its BODYSTRUCTURE was read carries no content
+ * type, encoding, size or MIME tree, and one that declared no Message-ID
+ * carries no hash. The report says so rather than printing an empty value.
+ */
+export const BugReportWithoutMessageShape: Story = {
+	render: () => (
+		<QuarantineBugDialog
+			entry={shapeUnread}
+			issueUrl={demoIssueUrl}
+			onClose={() => {}}
+			onCopy={() => {}}
+		/>
+	),
+};
+
 export const BugReport: Story = {
 	render: () => (
 		<QuarantineBugDialog