@remit/data-ports 0.0.31 → 0.0.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remit/data-ports",
-  "version": "0.0.31",
+  "version": "0.0.33",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -29,6 +29,10 @@
       "types": "./src/display-name.ts",
       "default": "./src/display-name.ts"
     },
+    "./mailbox-name": {
+      "types": "./src/mailbox-name.ts",
+      "default": "./src/mailbox-name.ts"
+    },
     "./wellknown": {
       "types": "./src/wellknown.ts",
       "default": "./src/wellknown.ts"

package/src/display-name.test.ts

@@ -5,9 +5,6 @@ import { storedDisplayName } from "./display-name.js";
 const OWN = "matthijs@ischen.nl";
 const SPOOFED = "aramirez@secresaludguaviare.gov.co";
 
-/**
- * The name is a stranger's address and nothing else, so nothing survives it.
- */
 const emptied: ReadonlyArray<readonly [string, string]> = [
 	["the incident", "matthijs@ischen.nl"],
 	["quoted", '"matthijs@ischen.nl"'],
@@ -21,11 +18,6 @@ const emptied: ReadonlyArray<readonly [string, string]> = [
 	["a non-ASCII local part", "Özcan@example.com"],
 ];
 
-/**
- * The name says something besides the address, and that something is what its
- * recipient knows the sender by. Removing it to remove the address destroys
- * real text on a live instance.
- */
 const stripped: ReadonlyArray<readonly [string, string, string]> = [
 	["parenthesised", "Support (support@acme.com)", "Support"],
 	["angle-bracketed", "Matthijs <matthijs@ischen.nl>", "Matthijs"],
@@ -84,11 +76,6 @@ describe("a display name that claims to be an address", () => {
 		assert.equal(storedDisplayName(name, OWN), name);
 	});
 
-	/**
-	 * SQLite folds `A-Z` and stops; JS folds the whole of Unicode. A rule spelled
-	 * once in SQL and once in TypeScript disagrees exactly here, and the
-	 * disagreement rewrites a name on a live database.
-	 */
 	it("folds case beyond ASCII on both sides", () => {
 		assert.equal(
 			storedDisplayName("Özcan@example.com", "özcan@example.com"),

package/src/display-name.ts

@@ -1,86 +1,40 @@
-/**
- * A display name that claims to be an email address (issue #826).
- *
- * The name on an envelope address is free text its sender chooses; the address
- * is verifiable. A spam envelope of
- * `matthijs@ischen.nl <aramirez@secresaludguaviare.gov.co>` therefore labels a
- * stranger's address with the reader's own, and every surface that shows a name
- * — the message list, the message header, contact autocomplete — repeats the
- * claim. On 2026-08-18 autocomplete offered such a row back and private mail
- * left the instance.
- *
- * The rule is one function because it has to hold in two places at once: the
- * harvest that decides what to store, and the repair that rewrites what is
- * already stored. Two spellings of it disagree at the edges — SQL `lower()`
- * folds ASCII only where JS folds all of Unicode — and every disagreement
- * rewrites a name on a live database that holds the only copy of it.
- *
- * What comes out is the name minus the claim, not the empty string. A sender
- * signing itself `Support (support@acme.com)` from `noreply@acme.com` is
- * ordinary mail, and `Support` is the name its recipient knows it by; deleting
- * that to remove the address takes real text off a live instance. Only the
- * address is removed, with the punctuation that was holding it, and a name that
- * is nothing but the claim comes back empty.
- *
- * An address the name shares with the address it labels is not a claim about
- * anyone else, so it stays — `Matthijs <matthijs@ischen.nl>` on
- * `matthijs@ischen.nl` is the same information twice.
- */
-
 const EMBEDDED_ADDRESS =
 	/[^\s@<>()[\],;:"'\\]+@[^\s@<>()[\],;:"'\\]+\.[^\s@<>()[\],;:"'\\.]{2,}/gu;
 
-/** `( )`, `< >`, `""` — a delimiter pair the removed address was sitting in. */
-const EMPTIED_PAIR = /[<([{"']\s*[>)\]}"']/gu;
+const DELIMITER_PAIR_LEFT_EMPTY = /[<([{"']\s*[>)\]}"']/gu;
 
-/**
- * What is left holding the address once it is gone: the separators around it.
- * Brackets and quotes are not trimmed here — EMPTIED_PAIR has already taken the
- * ones that were wrapping the address, and a name can legitimately end in one.
- */
-const EDGE_SEPARATORS = /^[\s,;:|/\\-]+|[\s,;:|/\\-]+$/gu;
+const LEADING_OR_TRAILING_SEPARATORS = /^[\s,;:|/\\-]+|[\s,;:|/\\-]+$/gu;
 
-const tidy = (text: string): string =>
+const tidyAfterAddressRemoval = (text: string): string =>
 	text
-		.replace(EMPTIED_PAIR, " ")
+		.replace(DELIMITER_PAIR_LEFT_EMPTY, " ")
 		.replace(/\s+/gu, " ")
-		.replace(EDGE_SEPARATORS, "")
+		.replace(LEADING_OR_TRAILING_SEPARATORS, "")
 		.trim();
 
-/**
- * `normalizedEmail` absent means the envelope carried no address this name
- * could be describing, so any address in the name is a claim about nobody.
- */
-const claimsAnotherAddress = (
+const carriesAddressOtherThan = (
 	text: string,
-	own: string | undefined,
+	ownAddress: string | undefined,
 ): boolean => {
 	for (const [address] of text.matchAll(EMBEDDED_ADDRESS)) {
-		if (address.toLowerCase() !== own) return true;
+		if (address.toLowerCase() !== ownAddress) return true;
 	}
 	return false;
 };
 
-/**
- * The display name as it should be stored, for both the harvest and the repair.
- * Unchanged when the name claims nothing.
- */
 export const storedDisplayName = (
 	displayName: string | undefined,
 	normalizedEmail: string | undefined,
 ): string => {
 	if (!displayName) return "";
-	const own = normalizedEmail?.toLowerCase();
-	if (!claimsAnotherAddress(displayName, own)) return displayName;
+	const ownAddress = normalizedEmail?.toLowerCase();
+	if (!carriesAddressOtherThan(displayName, ownAddress)) return displayName;
 
-	const remainder = tidy(
+	const remainder = tidyAfterAddressRemoval(
 		displayName.replace(EMBEDDED_ADDRESS, (address) =>
-			address.toLowerCase() === own ? address : " ",
+			address.toLowerCase() === ownAddress ? address : " ",
 		),
 	);
-	// Stripping leaves at most the row's own address behind, so the re-check is a
-	// backstop rather than a case: nothing that still claims another address is
-	// ever stored, whatever the shape it was hiding in.
-	if (!remainder || claimsAnotherAddress(remainder, own)) return "";
+	if (!remainder || carriesAddressOtherThan(remainder, ownAddress)) return "";
 	return remainder;
 };

package/src/mailbox-name.test.ts

@@ -0,0 +1,70 @@
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { resolveMailboxByLeafName } from "./mailbox-name.js";
+
+const JUNK_NAMES = ["junk", "spam", "junk e-mail", "junk email", "bulk mail"];
+
+const mailbox = (
+	mailboxId: string,
+	fullPath: string,
+	hierarchyDelimiter = "/",
+) => ({ mailboxId, fullPath, hierarchyDelimiter });
+
+describe("resolveMailboxByLeafName", () => {
+	it("resolves a Junk folder nested under INBOX", () => {
+		// The layout that broke report-spam's name fallback: an INBOX-prefixed
+		// namespace where Junk is `INBOX/Spam`, which never equals "spam".
+		const found = resolveMailboxByLeafName(
+			[
+				mailbox("m-inbox", "INBOX"),
+				mailbox("m-spam", "INBOX/Spam"),
+				mailbox("m-sent", "INBOX/Sent"),
+			],
+			JUNK_NAMES,
+		);
+		assert.equal(found?.mailboxId, "m-spam");
+	});
+
+	it("resolves under a non-slash delimiter and a non-INBOX prefix", () => {
+		const found = resolveMailboxByLeafName(
+			[mailbox("m-junk", "Mail.Junk E-mail", ".")],
+			JUNK_NAMES,
+		);
+		assert.equal(found?.mailboxId, "m-junk");
+	});
+
+	it("treats a flat namespace with no delimiter as its own leaf", () => {
+		const found = resolveMailboxByLeafName(
+			[mailbox("m-junk", "Junk", "")],
+			JUNK_NAMES,
+		);
+		assert.equal(found?.mailboxId, "m-junk");
+	});
+
+	it("prefers the shallowest match over a deeper one", () => {
+		const found = resolveMailboxByLeafName(
+			[
+				mailbox("m-buried", "Archive/2019/Spam"),
+				mailbox("m-real", "INBOX/Junk"),
+			],
+			JUNK_NAMES,
+		);
+		assert.equal(found?.mailboxId, "m-real");
+	});
+
+	it("prefers the better name at equal depth", () => {
+		const found = resolveMailboxByLeafName(
+			[mailbox("m-bulk", "INBOX/Bulk Mail"), mailbox("m-junk", "INBOX/Junk")],
+			JUNK_NAMES,
+		);
+		assert.equal(found?.mailboxId, "m-junk");
+	});
+
+	it("answers null when no folder carries a conventional name", () => {
+		const found = resolveMailboxByLeafName(
+			[mailbox("m-inbox", "INBOX"), mailbox("m-work", "INBOX/Work")],
+			JUNK_NAMES,
+		);
+		assert.equal(found, null);
+	});
+});

package/src/mailbox-name.ts

@@ -0,0 +1,54 @@
+export interface MailboxNameCandidate {
+	mailboxId: string;
+	fullPath: string;
+	hierarchyDelimiter: string;
+}
+
+// A flat mailbox namespace reports no delimiter at all — ImapFlow gives `""`
+// for a NIL LIST delimiter — and splitting on "" returns single characters, so
+// the path is its own leaf.
+const segments = (mailbox: MailboxNameCandidate): string[] =>
+	mailbox.hierarchyDelimiter.length === 0
+		? [mailbox.fullPath]
+		: mailbox.fullPath.split(mailbox.hierarchyDelimiter);
+
+const rank = (
+	mailbox: MailboxNameCandidate,
+	names: readonly string[],
+): number | null => {
+	const parts = segments(mailbox);
+	const leaf = parts[parts.length - 1] ?? mailbox.fullPath;
+	const nameIndex = names.indexOf(leaf.toLowerCase());
+	if (nameIndex < 0) return null;
+	// Depth outranks the name: a "Spam" buried under Trash or an archive must
+	// never beat the account's real "Junk" one level up.
+	return parts.length * names.length + nameIndex;
+};
+
+/**
+ * A special-use folder by conventional name, for servers that advertise no
+ * special-use flag for it. Matches the folder's own leaf segment against its
+ * mailbox's own hierarchy delimiter, so it resolves at any depth under any
+ * prefix (`INBOX/Spam`, `Mail.Junk E-mail`, `[Gmail]/Spam`) without knowing
+ * which prefixes a server uses. `names` is ordered best-first and must be
+ * lower case.
+ */
+export const resolveMailboxByLeafName = <T extends MailboxNameCandidate>(
+	mailboxes: T[],
+	names: readonly string[],
+): T | null => {
+	let best: { mailbox: T; rank: number } | null = null;
+	for (const mailbox of mailboxes) {
+		const candidate = rank(mailbox, names);
+		if (candidate === null) continue;
+		if (
+			!best ||
+			candidate < best.rank ||
+			(candidate === best.rank &&
+				mailbox.fullPath.localeCompare(best.mailbox.fullPath) < 0)
+		) {
+			best = { mailbox, rank: candidate };
+		}
+	}
+	return best?.mailbox ?? null;
+};