@remit/web-client 0.0.281 → 0.0.283

package/src/lib/spam-offer.test.ts

@@ -1,84 +1,192 @@
 import assert from "node:assert/strict";
 import { describe, it } from "node:test";
-import type { SearchResult } from "@remit/ui";
-import { spamOfferForResults } from "./spam-offer";
-
-const row = (
-	id: string,
-	mailboxId: string,
-	role?: "junk" | "inbox",
-): SearchResult => ({
-	id,
-	sender: "Someone",
-	subject: "Subject",
-	snippet: "",
-	date: "",
+import { type SpamMailboxCount, spamOfferFromCounts } from "./spam-offer";
+
+const exact = (mailboxId: string, value: number): SpamMailboxCount => ({
+	mailboxId,
+	count: { kind: "exact", value },
+	failed: false,
+});
+
+const uncounted = (mailboxId: string): SpamMailboxCount => ({
+	mailboxId,
+	count: { kind: "unknown" },
+	failed: false,
+});
+
+const errored = (mailboxId: string): SpamMailboxCount => ({
 	mailboxId,
-	...(role ? { folder: { role } } : {}),
+	count: { kind: "unknown" },
+	failed: true,
+});
+
+/** The loaded page held no junk row of its own. */
+const NO_PAGE_ROWS = { pageRowsByMailbox: new Map<string, number>() };
+
+const pageRows = (
+	entries: Record<string, number>,
+): { pageRowsByMailbox: ReadonlyMap<string, number> } => ({
+	pageRowsByMailbox: new Map(Object.entries(entries)),
 });
 
-describe("spamOfferForResults", () => {
-	it("makes no offer when nothing came from Spam", () => {
+describe("spamOfferFromCounts", () => {
+	it("makes no offer when there is no junk folder to count", () => {
+		assert.equal(spamOfferFromCounts([], NO_PAGE_ROWS), undefined);
+	});
+
+	it("makes no offer when every junk folder counted zero", () => {
 		assert.equal(
-			spamOfferForResults([row("1", "mb-inbox", "inbox"), row("2", "mb-a")]),
+			spamOfferFromCounts(
+				[exact("mb-junk-a", 0), exact("mb-junk-b", 0)],
+				NO_PAGE_ROWS,
+			),
 			undefined,
 		);
 	});
 
-	it("counts the spam rows and names their mailbox", () => {
+	it("states the server's count for the one junk folder", () => {
+		assert.deepEqual(
+			spamOfferFromCounts([exact("mb-junk", 42)], NO_PAGE_ROWS),
+			{
+				mailboxId: "mb-junk",
+				count: { kind: "exact", value: 42 },
+			},
+		);
+	});
+
+	it("sums every junk folder, so several accounts read as one number", () => {
+		assert.deepEqual(
+			spamOfferFromCounts(
+				[exact("mb-junk-a", 3), exact("mb-junk-b", 7), exact("mb-junk-c", 2)],
+				NO_PAGE_ROWS,
+			),
+			{ mailboxId: "mb-junk-b", count: { kind: "exact", value: 12 } },
+		);
+	});
+
+	it("sends the reader to the junk folder holding the most matches", () => {
+		assert.equal(
+			spamOfferFromCounts(
+				[exact("mb-junk-a", 1), exact("mb-junk-b", 9)],
+				NO_PAGE_ROWS,
+			)?.mailboxId,
+			"mb-junk-b",
+		);
+	});
+
+	it("breaks a tie on folder order, so the destination does not flip", () => {
+		assert.equal(
+			spamOfferFromCounts(
+				[exact("mb-junk-a", 4), exact("mb-junk-b", 4)],
+				NO_PAGE_ROWS,
+			)?.mailboxId,
+			"mb-junk-a",
+		);
+	});
+
+	it("states no number when one junk folder went uncounted", () => {
+		// Summing only the folders that answered would state a figure that is exact
+		// in form and short in fact.
 		assert.deepEqual(
-			spamOfferForResults([
-				row("1", "mb-inbox", "inbox"),
-				row("2", "mb-junk", "junk"),
-				row("3", "mb-junk", "junk"),
-			]),
-			{ mailboxId: "mb-junk", count: 2 },
+			spamOfferFromCounts(
+				[exact("mb-junk-a", 5), uncounted("mb-junk-b")],
+				NO_PAGE_ROWS,
+			),
+			{ mailboxId: "mb-junk-a", count: { kind: "unknown" } },
+		);
+	});
+
+	it("stands down when nothing is known and the page held no spam either", () => {
+		assert.equal(
+			spamOfferFromCounts(
+				[uncounted("mb-junk-a"), uncounted("mb-junk-b")],
+				NO_PAGE_ROWS,
+			),
+			undefined,
 		);
 	});
 
-	it("targets the Spam folder with the most matches when accounts compete", () => {
+	// A failed count is not a folder saying it holds nothing. Dropping the offer
+	// on one would make a lapsed session look exactly like a clean search.
+	it("keeps the offer when a count request failed", () => {
 		assert.deepEqual(
-			spamOfferForResults([
-				row("1", "mb-junk-a", "junk"),
-				row("2", "mb-junk-b", "junk"),
-				row("3", "mb-junk-b", "junk"),
-			]),
-			{ mailboxId: "mb-junk-b", count: 2 },
+			spamOfferFromCounts(
+				[exact("mb-junk-a", 0), errored("mb-junk-b")],
+				NO_PAGE_ROWS,
+			),
+			{ mailboxId: "mb-junk-b", count: { kind: "unknown" } },
 		);
 	});
 
-	it("breaks a tie on result order, so the offer does not flip", () => {
+	it("does not read an uncounted folder as an empty one", () => {
 		assert.deepEqual(
-			spamOfferForResults([
-				row("1", "mb-junk-a", "junk"),
-				row("2", "mb-junk-b", "junk"),
-			]),
-			{ mailboxId: "mb-junk-a", count: 1 },
+			spamOfferFromCounts(
+				[exact("mb-junk-a", 0), uncounted("mb-junk-b")],
+				pageRows({ "mb-junk-b": 1 }),
+			),
+			{ mailboxId: "mb-junk-b", count: { kind: "unknown" } },
+		);
+	});
+});
+
+describe("spamOfferFromCounts destination", () => {
+	// The regression: with counts switched off, every folder is `unknown` and the
+	// destination fell to whichever folder happened to be first. Two accounts,
+	// every held-out row in B's Spam, and the button opened A's — "No matches"
+	// over mail the list was holding out on the very same screen.
+	it("follows the page's junk rows when no folder was counted", () => {
+		assert.equal(
+			spamOfferFromCounts(
+				[uncounted("mb-junk-a"), uncounted("mb-junk-b")],
+				pageRows({ "mb-junk-b": 3 }),
+			)?.mailboxId,
+			"mb-junk-b",
+		);
+	});
+
+	// An exact zero is the one folder known to hold nothing, so it is the one
+	// destination guaranteed to show an empty list — below a folder that simply
+	// has not answered.
+	it("never sends the reader to a folder that counted zero", () => {
+		assert.equal(
+			spamOfferFromCounts(
+				[exact("mb-junk-a", 0), uncounted("mb-junk-b"), errored("mb-junk-c")],
+				NO_PAGE_ROWS,
+			)?.mailboxId,
+			"mb-junk-b",
 		);
 	});
 
-	it("picks a destination without claiming to have counted every account", () => {
-		// Three spam rows across two accounts: the destination is the bigger folder,
-		// and its share is 2 — deliberately not the total, which the results list
-		// states for itself so the banner cannot under-report.
-		const offer = spamOfferForResults([
-			row("1", "mb-junk-a", "junk"),
-			row("2", "mb-junk-b", "junk"),
-			row("3", "mb-junk-b", "junk"),
-		]);
-		assert.equal(offer?.mailboxId, "mb-junk-b");
-		assert.equal(offer?.count, 2);
+	it("prefers a counted match over the folder the page's rows came from", () => {
+		assert.equal(
+			spamOfferFromCounts(
+				[exact("mb-junk-a", 9), uncounted("mb-junk-b")],
+				pageRows({ "mb-junk-b": 4 }),
+			)?.mailboxId,
+			"mb-junk-a",
+		);
+	});
+
+	// The mailbox lists are still loading, or the folder arrived after the count
+	// requests went out. Its rows are already held out of the list, so it has to
+	// be reachable.
+	it("offers a junk folder the page names and the counts do not", () => {
+		assert.deepEqual(spamOfferFromCounts([], pageRows({ "mb-junk-late": 2 })), {
+			mailboxId: "mb-junk-late",
+			count: { kind: "unknown" },
+		});
 	});
 
-	it("ignores a spam row that carries no mailbox to navigate to", () => {
-		const orphan: SearchResult = {
-			id: "1",
-			sender: "Someone",
-			subject: "Subject",
-			snippet: "",
-			date: "",
-			folder: { role: "junk" },
-		};
-		assert.equal(spamOfferForResults([orphan]), undefined);
+	// A count that says nothing over a page that is holding junk rows is stale by
+	// up to its half-minute. The rows are on screen; the offer stands and states
+	// no figure rather than "0 results from Spam".
+	it("states no number when an exact zero contradicts the page's rows", () => {
+		assert.deepEqual(
+			spamOfferFromCounts(
+				[exact("mb-junk-a", 0), exact("mb-junk-b", 0)],
+				pageRows({ "mb-junk-b": 2 }),
+			),
+			{ mailboxId: "mb-junk-b", count: { kind: "unknown" } },
+		);
 	});
 });

package/src/lib/spam-offer.ts

@@ -1,37 +1,163 @@
 /**
- * Where taking the Spam offer lands.
+ * The Spam offer: how much of a search sits in Spam, and where taking the offer
+ * lands.
  *
- * Scoping is a route and a route names one mailbox, so the offer has to pick a
- * single Spam folder even when several accounts matched; it picks the one
- * holding the most matches. `count` is that folder's share, used only to choose
- * between folders — the banner states the full number of rows held out, which
- * the results list counts for itself.
+ * Both answers come from one server count per junk folder the search reached
+ * (`useSpamMatchCounts`). The number is their sum, because a search spans every
+ * account and every account has its own Spam folder — "N in Spam" that named
+ * one folder's share would be smaller than the mail the phrase describes.
+ *
+ * The destination is a single folder even so: scoping is a route and a route
+ * names one mailbox. It is the folder holding the most matches, which is the
+ * best a single click can do, and `SpamResultsOffer` says where the button goes
+ * rather than promising to show every match. Where no count ranks the folders —
+ * a short query, a residual token, a failed request — the page's own junk rows
+ * do, because they are the only evidence left of where the mail is.
+ *
+ * This used to group the search results the header held and count each group.
+ * That array is a page, so the figure was a count of the loaded window offered
+ * as a count of a mailbox: a Spam match below the page was missing from it, and
+ * the number climbed as further pages loaded (#313).
+ *
+ * A folder whose count did not arrive makes the total `unknown`. Summing the
+ * ones that did would state a figure that is exact in form and short in fact,
+ * and nothing distinguishes it from a true one on screen.
  */
-import { partitionSpamResults, type SearchResult } from "@remit/ui";
+import type { ResultCount } from "@remit/ui";
+
+export interface SpamMailboxCount {
+	mailboxId: string;
+	count: ResultCount;
+	/**
+	 * The count request failed. Distinct from `unknown`, which also covers a
+	 * request still in flight or one nobody made: a failure is a folder that
+	 * could not answer, and it must never read as a folder holding nothing.
+	 */
+	failed: boolean;
+}
 
 export interface SpamOffer {
+	/** The junk folder "Go to Spam" scopes the search to. */
+	mailboxId: string;
+	/** Matches across every junk folder, or `unknown` if any went uncounted. */
+	count: ResultCount;
+}
+
+export interface SpamOfferEvidence {
+	/**
+	 * Junk rows the loaded page held, per junk folder.
+	 *
+	 * Never the number the offer states — a page is a page. It is what says
+	 * spam was reached at all while the counts are absent, and, crucially, WHICH
+	 * folder the reader is being sent to: with no count to rank the folders by,
+	 * the rows on screen are the only evidence of where the mail is, and a
+	 * "Go to Spam" that lands on the wrong account's folder shows "No matches"
+	 * over mail this very page is holding out.
+	 */
+	pageRowsByMailbox: ReadonlyMap<string, number>;
+}
+
+interface Candidate {
 	mailboxId: string;
-	count: number;
+	count: ResultCount;
+	failed: boolean;
+	pageRows: number;
 }
 
-export function spamOfferForResults(
-	results: readonly SearchResult[],
+/**
+ * How good a destination a folder is, before ties are broken.
+ *
+ * A counted match is the best evidence; junk rows on the page are the next
+ * best, and they outrank the folder's own count because the rows are on screen
+ * while the count may be half a minute old. A folder that answered zero and
+ * shows no row ranks LAST — it is the only one known to hold nothing, so
+ * sending the reader there is the one choice guaranteed to show an empty list.
+ */
+const tier = (candidate: Candidate): number => {
+	if (candidate.count.kind === "exact" && candidate.count.value > 0) return 3;
+	if (candidate.pageRows > 0) return 2;
+	return candidate.count.kind === "unknown" ? 1 : 0;
+};
+
+const exactValue = (candidate: Candidate): number =>
+	candidate.count.kind === "exact" ? candidate.count.value : 0;
+
+/** Strict, so equal candidates leave the earlier one standing. */
+const isBetterDestination = (
+	candidate: Candidate,
+	standing: Candidate,
+): boolean => {
+	if (tier(candidate) !== tier(standing)) {
+		return tier(candidate) > tier(standing);
+	}
+	if (exactValue(candidate) !== exactValue(standing)) {
+		return exactValue(candidate) > exactValue(standing);
+	}
+	return candidate.pageRows > standing.pageRows;
+};
+
+/**
+ * The offer these per-folder counts support, or none.
+ *
+ * None when every junk folder answered and they sum to zero with no junk row on
+ * the page either — the search reaches no spam. Anything else is an offer: rows
+ * held out of the list are always offered a way back, because hiding mail
+ * without one is worse than hiding a number.
+ *
+ * The figure is the sum, and only when every folder answered. One folder
+ * missing takes it off, because summing the folders that replied states a
+ * number exact in form and short in fact. A sum of zero over a page that is
+ * holding junk rows takes it off too: the two disagree, so neither is stated.
+ */
+export function spamOfferFromCounts(
+	counts: readonly SpamMailboxCount[],
+	{ pageRowsByMailbox }: SpamOfferEvidence,
 ): SpamOffer | undefined {
-	const { spam } = partitionSpamResults([...results]);
-	const countByMailbox = new Map<string, number>();
-	for (const result of spam) {
-		if (!result.mailboxId) continue;
-		countByMailbox.set(
-			result.mailboxId,
-			(countByMailbox.get(result.mailboxId) ?? 0) + 1,
-		);
+	const candidates: Candidate[] = counts.map((entry) => ({
+		...entry,
+		pageRows: pageRowsByMailbox.get(entry.mailboxId) ?? 0,
+	}));
+	// A folder the page names but the counts do not — the mailbox lists are still
+	// loading, or the folder arrived after the requests went out. Its rows are
+	// already being held out of the list, so it has to be reachable.
+	for (const [mailboxId, pageRows] of pageRowsByMailbox) {
+		if (pageRows <= 0) continue;
+		if (candidates.some((entry) => entry.mailboxId === mailboxId)) continue;
+		candidates.push({
+			mailboxId,
+			count: { kind: "unknown" },
+			failed: false,
+			pageRows,
+		});
+	}
+
+	const first = candidates[0];
+	if (!first) return undefined;
+
+	let total = 0;
+	let everyFolderAnswered = true;
+	let best = first;
+	for (const candidate of candidates) {
+		if (candidate.count.kind === "unknown") everyFolderAnswered = false;
+		else total += candidate.count.value;
+		if (isBetterDestination(candidate, best)) best = candidate;
 	}
 
-	let offer: SpamOffer | undefined;
-	// Insertion order is result order, so the first-seen folder wins a tie and
-	// the offer does not flip between renders of the same results.
-	for (const [mailboxId, count] of countByMailbox) {
-		if (!offer || count > offer.count) offer = { mailboxId, count };
+	const pageHeldSpam = candidates.some((candidate) => candidate.pageRows > 0);
+	const anyFailed = candidates.some((candidate) => candidate.failed);
+	if (total === 0 && !pageHeldSpam && (everyFolderAnswered || !anyFailed)) {
+		return undefined;
 	}
-	return offer;
+
+	// The count and the page disagree: an exact zero under rows the list is
+	// holding out. The rows are on screen and the count is up to half a minute
+	// old, so the offer stands and states nothing.
+	const contradicted = everyFolderAnswered && total === 0 && pageHeldSpam;
+	return {
+		mailboxId: best.mailboxId,
+		count:
+			everyFolderAnswered && !contradicted
+				? { kind: "exact", value: total }
+				: { kind: "unknown" },
+	};
 }