@remit/web-client 0.0.85 → 0.0.87

package/src/lib/organize/property-prefill.test.ts

@@ -0,0 +1,173 @@
+/**
+ * The opening clauses a properties-only rule offers (RFC 038 D2/D4). The
+ * prefill is a starting point the user edits, so the contract worth holding is
+ * the order of evidence — sender before subject, and nothing at all rather than
+ * a guess that matches half a mailbox.
+ */
+
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+	derivePropertyClauses,
+	normalizeSubject,
+	sharedSubjectFragment,
+} from "./property-prefill";
+
+describe("normalizeSubject", () => {
+	it("strips stacked reply, forward, and list decorations", () => {
+		assert.equal(
+			normalizeSubject("Re: Fwd: [ops] Invoice 1841"),
+			"Invoice 1841",
+		);
+		assert.equal(normalizeSubject("RE[2]: Invoice 1841"), "Invoice 1841");
+		assert.equal(normalizeSubject("AW: SV: Invoice 1841"), "Invoice 1841");
+	});
+
+	it("collapses whitespace and trims", () => {
+		assert.equal(normalizeSubject("  Invoice   1841  "), "Invoice 1841");
+	});
+
+	it("leaves a subject that is only decoration empty", () => {
+		assert.equal(normalizeSubject("Re: "), "");
+	});
+});
+
+describe("sharedSubjectFragment", () => {
+	it("takes the longest run of whole words every subject carries", () => {
+		assert.equal(
+			sharedSubjectFragment([
+				"Invoice 1841",
+				"Invoice 1902",
+				"Re: Invoice 2003",
+			]),
+			"Invoice",
+		);
+	});
+
+	it("matches case-insensitively and answers in the first subject's casing", () => {
+		assert.equal(
+			sharedSubjectFragment(["Invoice 1841", "INVOICE 1902"]),
+			"Invoice",
+		);
+	});
+
+	it("compares whole words, never a partial one", () => {
+		// "Invoice 18" is a shared character run and not a shared word run.
+		assert.equal(
+			sharedSubjectFragment(["Invoice 1841", "Invoice 1892"]),
+			"Invoice",
+		);
+	});
+
+	it("keeps a single subject as its own fragment", () => {
+		assert.equal(sharedSubjectFragment(["Invoice 1841"]), "Invoice 1841");
+	});
+
+	it("rejects a single subject that is nothing but filler", () => {
+		assert.equal(sharedSubjectFragment(["for you"]), undefined);
+	});
+
+	it("rejects a shared run of filler words", () => {
+		assert.equal(
+			sharedSubjectFragment(["the report", "the summary"]),
+			undefined,
+		);
+	});
+
+	it("rejects a shared run too short to be worth matching", () => {
+		assert.equal(
+			sharedSubjectFragment(["Q3 numbers", "Q3 results"]),
+			undefined,
+		);
+	});
+
+	it("is undefined when the subjects share nothing", () => {
+		assert.equal(
+			sharedSubjectFragment(["Invoice 1841", "Standup notes"]),
+			undefined,
+		);
+	});
+
+	it("is undefined when no subject survives normalizing", () => {
+		assert.equal(sharedSubjectFragment(["Re:", "   "]), undefined);
+	});
+});
+
+describe("derivePropertyClauses", () => {
+	it("matches on the sender when the whole selection is from one address", () => {
+		assert.deepEqual(
+			derivePropertyClauses(
+				["npm@github.com", "npm@github.com", "npm@github.com"],
+				["Invoice 1841", "Standup notes", "Deploy failed"],
+			),
+			[{ field: "From", value: "npm@github.com" }],
+		);
+	});
+
+	it("matches on the domain when several senders share one", () => {
+		assert.deepEqual(
+			derivePropertyClauses(
+				["npm@github.com", "notifications@github.com", "ci@sub.github.com"],
+				["Invoice 1841", "Standup notes", "Deploy failed"],
+			),
+			[{ field: "FromDomain", value: "github.com" }],
+		);
+	});
+
+	it("prefers the sender over the subject even when the subjects share a run", () => {
+		assert.deepEqual(
+			derivePropertyClauses(
+				["npm@github.com", "npm@github.com"],
+				["Invoice 1841", "Invoice 1902"],
+			),
+			[{ field: "From", value: "npm@github.com" }],
+		);
+	});
+
+	it("falls back to what mixed senders' subjects have in common", () => {
+		assert.deepEqual(
+			derivePropertyClauses(
+				["billing@acme.test", "accounts@globex.test", "ap@initech.test"],
+				["Invoice 1841", "Invoice 1902", "Re: Invoice 2003"],
+			),
+			[{ field: "Subject", value: "Invoice" }],
+		);
+	});
+
+	it("offers one sender chip each when mixed senders share no subject either", () => {
+		assert.deepEqual(
+			derivePropertyClauses(
+				["billing@acme.test", "accounts@globex.test"],
+				["Invoice 1841", "Standup notes"],
+			),
+			[
+				{ field: "From", value: "billing@acme.test" },
+				{ field: "From", value: "accounts@globex.test" },
+			],
+		);
+	});
+
+	it("refuses a filler-only subject run rather than prefilling a wide match", () => {
+		assert.deepEqual(
+			derivePropertyClauses(
+				["billing@acme.test", "accounts@globex.test"],
+				["the report", "the summary"],
+			),
+			[
+				{ field: "From", value: "billing@acme.test" },
+				{ field: "From", value: "accounts@globex.test" },
+			],
+		);
+	});
+
+	it("reads a single message as its own sender", () => {
+		assert.deepEqual(
+			derivePropertyClauses(["billing@acme.test"], ["Invoice 1841"]),
+			[{ field: "From", value: "billing@acme.test" }],
+		);
+	});
+
+	it("offers nothing when the selection carries no sender and no shared subject", () => {
+		assert.deepEqual(derivePropertyClauses([], ["Re:", "   "]), []);
+	});
+});

package/src/lib/organize/property-prefill.ts

@@ -0,0 +1,151 @@
+import type { RemitImapFilterClause } from "@remit/api-http-client/types.gen.ts";
+import { deriveSenderClauses, distinctSenders } from "./sender-fallback";
+
+/**
+ * The opening clauses for a rule matched on properties alone — no semantic
+ * anchor (RFC 038 D2/D4). The selection is the only evidence available, so the
+ * prefill reads it in the order the evidence is strongest:
+ *
+ * 1. One sender across the whole selection, or several that collapse to one
+ *    registrable domain — the sender-fallback derivation (#251, #262) already
+ *    decides between a `From` and a `FromDomain` clause, and this reuses it
+ *    rather than deciding again.
+ * 2. Mixed senders — what the messages share is their subject, so match on the
+ *    part the subjects have in common instead.
+ * 3. Neither — no clauses. The editor opens empty and asks for one; a wrong
+ *    guess costs more than an absent one.
+ *
+ * Every clause it produces is an ordinary chip: visible, editable, removable.
+ * It is where the user starts, never what the rule is.
+ */
+
+/** Reply, forward, and list-tag decorations that carry no meaning for a match. */
+const SUBJECT_PREFIX =
+	/^\s*(?:(?:re|aw|fwd?|vs|sv|antw|res|enc|tr)\s*(?:\[\d+\])?\s*:|\[[^\]]{1,32}\])\s*/i;
+
+/**
+ * A subject reduced to the part worth matching on: reply and forward markers
+ * and leading list tags stripped (repeatedly — real threads stack them), and
+ * whitespace collapsed.
+ */
+export const normalizeSubject = (subject: string): string => {
+	let value = subject.replace(/\s+/g, " ").trim();
+	for (;;) {
+		const stripped = value.replace(SUBJECT_PREFIX, "");
+		if (stripped === value) return value.trim();
+		value = stripped;
+	}
+};
+
+/**
+ * Words too common to be a rule on their own. A single shared word from this
+ * list matches half a mailbox, which is worse than offering nothing.
+ */
+const WEAK_WORDS = new Set([
+	"a",
+	"an",
+	"and",
+	"are",
+	"as",
+	"at",
+	"be",
+	"by",
+	"for",
+	"from",
+	"has",
+	"have",
+	"in",
+	"is",
+	"it",
+	"me",
+	"my",
+	"new",
+	"of",
+	"on",
+	"or",
+	"our",
+	"the",
+	"this",
+	"to",
+	"was",
+	"we",
+	"with",
+	"you",
+	"your",
+]);
+
+/** The shortest fragment worth prefilling as a `Subject` clause. */
+const MIN_FRAGMENT_LENGTH = 3;
+
+const words = (subject: string): string[] =>
+	subject.split(" ").filter((word) => word !== "");
+
+const isUseful = (fragment: string[]): boolean => {
+	if (fragment.length === 0) return false;
+	if (fragment.join(" ").length < MIN_FRAGMENT_LENGTH) return false;
+	return fragment.some((word) => !WEAK_WORDS.has(word.toLowerCase()));
+};
+
+const runAt = (haystack: string[], needle: string[]): number =>
+	haystack.findIndex((_, start) =>
+		needle.every(
+			(word, offset) =>
+				haystack[start + offset]?.toLowerCase() === word.toLowerCase(),
+		),
+	);
+
+/**
+ * The longest run of whole words every subject carries, compared
+ * case-insensitively and returned in the casing the first subject uses. Whole
+ * words rather than raw characters, so "Invoice 1841" and "Invoice 1902" share
+ * "Invoice" and not "Invoice 18".
+ *
+ * `undefined` when the subjects share nothing worth matching on — a single
+ * filler word does not count.
+ */
+export const sharedSubjectFragment = (
+	subjects: readonly string[],
+): string | undefined => {
+	const normalized = subjects
+		.map(normalizeSubject)
+		.filter((subject) => subject !== "");
+	if (normalized.length === 0) return undefined;
+	const [first, ...rest] = normalized;
+	if (rest.length === 0) return isUseful(words(first)) ? first : undefined;
+
+	const firstWords = words(first);
+	for (let length = firstWords.length; length > 0; length -= 1) {
+		for (let start = 0; start + length <= firstWords.length; start += 1) {
+			const candidate = firstWords.slice(start, start + length);
+			if (!isUseful(candidate)) continue;
+			if (rest.every((subject) => runAt(words(subject), candidate) >= 0)) {
+				return candidate.join(" ");
+			}
+		}
+	}
+	return undefined;
+};
+
+/**
+ * The clauses a properties-only rule opens on, derived from the selected
+ * messages' senders and subjects. Empty when the selection gives nothing to go
+ * on — the editor then holds the commit until the user adds a clause, which is
+ * the honest state.
+ */
+export const derivePropertyClauses = (
+	senders: readonly string[],
+	subjects: readonly string[],
+): RemitImapFilterClause[] => {
+	const senderClauses = deriveSenderClauses(senders);
+	// One sender across the selection, or several on one registrable domain:
+	// a single sharp clause, and sharper than any subject fragment.
+	if (distinctSenders(senders).length === 1) return senderClauses;
+	if (senderClauses.length === 1 && senderClauses[0].field === "FromDomain")
+		return senderClauses;
+
+	const fragment = sharedSubjectFragment(subjects);
+	if (fragment !== undefined) return [{ field: "Subject", value: fragment }];
+	// Mixed senders with nothing shared in their subjects: one `From` chip each,
+	// the widen fallback's own derivation (#251).
+	return senderClauses;
+};

package/src/lib/organize/rule-model.test.ts

@@ -11,6 +11,7 @@ import { buildOrganizeInput } from "./organize-model";
 import {
 	buildInitialRule,
 	derivePreview,
+	isEvaluablePredicate,
 	normalizeClauseValue,
 	normalizeListId,
 	predicateSignature,
@@ -300,3 +301,59 @@ describe("derivePreview", () => {
 		);
 	});
 });
+
+describe("isEvaluablePredicate", () => {
+	it("accepts literal clauses the vector-free matcher can read off the index", () => {
+		assert.equal(
+			isEvaluablePredicate({
+				matchOperator: "And",
+				literalClauses: [
+					{ field: "From", value: "npm@github.com" },
+					{ field: "Subject", value: "Invoice" },
+				],
+			}),
+			true,
+		);
+	});
+
+	it("rejects a body clause with no anchor — the shape that answered 500", () => {
+		assert.equal(
+			isEvaluablePredicate({
+				matchOperator: "And",
+				literalClauses: [{ field: "HasWords", value: "receipt" }],
+			}),
+			false,
+		);
+	});
+
+	it("rejects it however it is mixed in with clauses that are evaluable", () => {
+		assert.equal(
+			isEvaluablePredicate({
+				matchOperator: "Or",
+				literalClauses: [
+					{ field: "From", value: "npm@github.com" },
+					{ field: "HasWords", value: "receipt" },
+				],
+			}),
+			false,
+		);
+	});
+
+	it("accepts a body clause once an anchor puts the matcher on the semantic arm", () => {
+		assert.equal(
+			isEvaluablePredicate({
+				anchorMessageId: "msg-1",
+				matchOperator: "And",
+				literalClauses: [{ field: "HasWords", value: "receipt" }],
+			}),
+			true,
+		);
+	});
+
+	it("accepts an empty predicate", () => {
+		assert.equal(
+			isEvaluablePredicate({ matchOperator: "And", literalClauses: [] }),
+			true,
+		);
+	});
+});

package/src/lib/organize/rule-model.ts

@@ -4,14 +4,13 @@ import type {
 	MatchOperator,
 	PreviewCount,
 	RuleClause,
+	RuleMatchMode,
 	RuleScope,
 } from "@remit/ui";
 import { pickedDateToExpiresAt } from "./filter-status";
 import type { OrganizeDraft } from "./organize-model";
-import {
-	deriveSenderClauses,
-	type OrganizeMatchPredicate,
-} from "./sender-fallback";
+import { derivePropertyClauses } from "./property-prefill";
+import type { OrganizeMatchPredicate } from "./sender-fallback";
 
 /**
  * The clause fields the Organize editor may offer (RFC 038 D2). Gated on what
@@ -55,11 +54,19 @@ export interface InitialRuleInput {
 	anchorMessageId?: string;
 	/**
 	 * The deployment ships no vector pipeline, so the widen cannot run. The rule
-	 * opens on the sender-derived literal clauses instead of an anchor.
+	 * opens on the property-derived literal clauses instead of an anchor.
 	 */
 	semanticUnavailable: boolean;
-	/** Distinct sender addresses of the selection, for the fallback clauses. */
+	/**
+	 * How the rule opens. Defaults to `properties` when the deployment cannot
+	 * serve the widen, `similar` otherwise — semantic stays the default wherever
+	 * it can run.
+	 */
+	matchMode?: RuleMatchMode;
+	/** Distinct sender addresses of the selection, for the derived clauses. */
 	senders: readonly string[];
+	/** Subjects of the selected messages, for the shared-subject prefill. */
+	subjects?: readonly string[];
 	/** How many messages the selection holds — the widen's anchor count. */
 	selectionCount: number;
 	/** A folder a "Something else" shortcut pre-picked. */
@@ -68,41 +75,96 @@ export interface InitialRuleInput {
 	seedScope?: RuleScope;
 }
 
+export const defaultMatchMode = (
+	semanticUnavailable: boolean,
+): RuleMatchMode => (semanticUnavailable ? "properties" : "similar");
+
+/** The property prefill as editor chips, flagged as derived so a mode switch
+ *  can take back its own guesses without touching a clause the user wrote. */
+const derivedClauses = (
+	senders: readonly string[],
+	subjects: readonly string[],
+): RuleClause[] =>
+	derivePropertyClauses(senders, subjects).map((clause, index) => ({
+		id: `derived-${index}`,
+		field: clause.field,
+		value: clause.value,
+		derived: true,
+	}));
+
+export interface RuleMatchers {
+	clauses: RuleClause[];
+	matchOperator: MatchOperator;
+	widen?: FilterRule["widen"];
+}
+
+export interface MatchersInput {
+	anchorMessageId?: string;
+	senders: readonly string[];
+	subjects: readonly string[];
+	selectionCount: number;
+	/** Clauses the user wrote, carried across a mode switch untouched. */
+	keepClauses?: RuleClause[];
+	/** The operator to keep when the user already has clauses of their own. */
+	currentOperator?: MatchOperator;
+}
+
 /**
- * The rule the editor opens on, built from the widen probe. A semantic-capable
- * deployment opens on the widen chip (the anchor, no literal clauses); one
- * without the vector pipeline opens on the sender-fallback `From` chips (#251),
- * visible and editable, matched with `Or`. Either way the move destination and
- * scope come from any "Something else" seed.
+ * What a rule matches on in a given mode, with the action and scope left alone.
+ *
+ * - `similar` — the semantic widen chip, the anchor doing the work.
+ * - `properties` — no anchor at all: the selection's own sender or shared
+ *   subject as ordinary literal chips ({@link derivePropertyClauses}).
+ *
+ * Both keep clauses the user added by hand, so switching mode is never
+ * destructive of their own edits.
  */
-export const buildInitialRule = (input: InitialRuleInput): FilterRule => {
-	const scope = input.seedScope ?? "once";
-	if (input.semanticUnavailable) {
-		// The same derivation the widen fallback runs (#251, #262): one `From`
-		// clause per sender, or a single `FromDomain` clause when they share a
-		// registrable domain. Surfaced as ordinary editable chips.
-		const clauses: RuleClause[] = deriveSenderClauses(input.senders).map(
-			(clause, index) => ({
-				id: `derived-${index}`,
-				field: clause.field,
-				value: clause.value,
-				derived: true,
-			}),
+export const matchersForMode = (
+	mode: RuleMatchMode,
+	input: MatchersInput,
+): RuleMatchers => {
+	const kept = input.keepClauses ?? [];
+	if (mode === "properties") {
+		const prefill = derivedClauses(input.senders, input.subjects).filter(
+			(clause) =>
+				!kept.some(
+					(existing) =>
+						existing.field === clause.field && existing.value === clause.value,
+				),
 		);
 		return {
-			clauses,
-			matchOperator: "any",
-			moveMailboxId: input.seedMailboxId,
-			scope,
-			name: "",
+			clauses: [...kept, ...prefill],
+			matchOperator: kept.length > 0 ? (input.currentOperator ?? "any") : "any",
+			widen: undefined,
 		};
 	}
 	return {
-		clauses: [],
-		matchOperator: "all",
+		clauses: kept,
+		matchOperator: kept.length > 0 ? (input.currentOperator ?? "all") : "all",
 		widen: input.anchorMessageId
 			? { anchorCount: Math.max(input.selectionCount, 1) }
 			: undefined,
+	};
+};
+
+/**
+ * The rule the editor opens on, built from the widen probe. A semantic-capable
+ * deployment opens on the widen chip (the anchor, no literal clauses); one
+ * without the vector pipeline, or a user who picked properties matching, opens
+ * on the derived `From` / `FromDomain` / `Subject` chips (#251), visible and
+ * editable, matched with `Or`. Either way the move destination and scope come
+ * from any "Something else" seed.
+ */
+export const buildInitialRule = (input: InitialRuleInput): FilterRule => {
+	const scope = input.seedScope ?? "once";
+	const mode = input.matchMode ?? defaultMatchMode(input.semanticUnavailable);
+	return {
+		...matchersForMode(mode, {
+			anchorMessageId: input.anchorMessageId,
+			senders: input.senders,
+			subjects: input.subjects ?? [],
+			selectionCount: input.selectionCount,
+		}),
 		moveMailboxId: input.seedMailboxId,
 		scope,
 		name: "",
@@ -132,6 +194,23 @@ export const rulePredicate = (
 	};
 };
 
+/**
+ * Whether the matcher behind `/organize/preview` can evaluate this predicate at
+ * all. Without an anchor it takes the vector-free literal arm, which reads no
+ * message body and rejects a `HasWords` clause rather than narrowing the match
+ * silently (`assertNoBodyContentClause`, backend/service/organize.ts). Asking it
+ * anyway is a 500, so the caller must not ask.
+ */
+export const isEvaluablePredicate = (
+	predicate: OrganizeMatchPredicate,
+): boolean =>
+	predicate.anchorMessageId !== undefined ||
+	!predicate.literalClauses.some((clause) => clause.field === "HasWords");
+
+/** What the count says when the predicate cannot be counted at all. */
+export const UNCOUNTABLE_PREDICATE_REASON =
+	"Can't count matches — “has the words” reads message bodies, which only a saved rule does.";
+
 /**
  * A stable key for a predicate's match set. Two predicates with the same key
  * match the same messages; a change to the key is what marks the live count

package/src/lib/organize/search-to-rule.ts

@@ -18,7 +18,8 @@ import {
  * The mapping is honest about what a filter cannot carry. A facet with no clause
  * equivalent is never silently folded into the rule: a folder scope is reported
  * as dropped-and-kept-out (the filter matches everywhere, not just there), the
- * attribute facets (attachment / unread / date) are reported as left out, and a
+ * attribute facets (attachment / read state / starred / category / date) are
+ * reported as left out, and a
  * free-text query kept as a literal `HasWords` clause is reported as having lost
  * its semantic "similar mail" reach on a deployment that cannot embed the query
  * (D5). Pure functions only — the capability is injected, not probed here.
@@ -72,15 +73,18 @@ interface ConvertOptions {
 const FACET_HAS_NO_CLAUSE: ReadonlySet<SearchToken["type"]> = new Set([
 	"hasAttachment",
 	"isUnread",
+	"isRead",
+	"isStarred",
+	"category",
 	"before",
 	"after",
 ]);
 
 /**
  * Convert the current search into a rule's clauses and a record of what could not
- * be carried. Terms become a `HasWords` clause; a `from:` facet a `From` clause;
- * an `in:` facet a kept-out folder scope; `account:` the target account; the
- * attribute facets are dropped. The search's terms are ANDed with its facets, so
+ * be carried. Terms become a `HasWords` clause; a `from:` facet a `From` clause
+ * and a `subject:` facet a `Subject` clause; an `in:` facet a kept-out folder
+ * scope; `account:` the target account; the attribute facets are dropped. The search's terms are ANDed with its facets, so
  * the rule matches all of them (`all`).
  */
 export const convertSearchToRule = (
@@ -97,6 +101,10 @@ export const convertSearchToRule = (
 			clauses.push({ field: "From", value: token.value });
 			continue;
 		}
+		if (token.type === "subject") {
+			clauses.push({ field: "Subject", value: token.value });
+			continue;
+		}
 		if (token.type === "in") {
 			scopedOut = { mailboxId: token.mailboxId, label: token.value };
 			continue;

package/src/lib/organize/sender-fallback.ts

@@ -37,6 +37,16 @@ const hostOf = (address: string): string => {
 	return at >= 0 ? address.slice(at + 1) : address;
 };
 
+/**
+ * The registrable domain behind a sender address, public-suffix aware (tldts
+ * `getDomain`), or `null` when the address carries none. The one place an
+ * address is turned into a `FromDomain` value — a clause the prefill derives and
+ * a domain the value field suggests must be the same string, or the suggestion
+ * would offer a domain the matcher never produces.
+ */
+export const senderDomain = (address: string): string | null =>
+	getDomain(hostOf(address.trim()));
+
 /**
  * The single registrable domain the whole selection collapses to, or `null` when
  * it does not collapse. A collapse needs at least two distinct senders that all
@@ -52,7 +62,7 @@ export const collapsibleDomain = (
 	if (distinct.length < 2) return null;
 	let shared: string | null = null;
 	for (const sender of distinct) {
-		const domain = getDomain(hostOf(sender));
+		const domain = senderDomain(sender);
 		if (domain === null) return null;
 		if (shared === null) shared = domain;
 		else if (shared !== domain) return null;

package/src/lib/search-result.ts

@@ -44,6 +44,7 @@ export function threadToSearchResult(
 	return {
 		id: thread.messageId,
 		sender: thread.fromName ?? thread.fromEmail ?? "Unknown",
+		...(thread.fromEmail ? { senderEmail: thread.fromEmail } : {}),
 		subject: thread.subject ?? "(No subject)",
 		snippet: thread.snippet ?? "",
 		date: formatEmailDate(thread.sentDate),
@@ -66,6 +67,7 @@ export function rowToSearchResult(
 	return {
 		id: row.id,
 		sender: row.fromName,
+		...(row.fromEmail ? { senderEmail: row.fromEmail } : {}),
 		subject: row.subject,
 		snippet: row.snippet,
 		date: row.timeLabel,