@mailwoman/codex 9.4.0 → 10.0.0

package/out/address/key.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The canonical match key — a normalized, deterministic string derived from address components,
+ *   distinct from the human-readable formatted string.
+ *
+ *   Where `format.ts` produces something for a person to read, this produces something for a
+ *   _machine_ to collide on: lowercased, diacritic-stripped, punctuation-flattened, whitespace-
+ *   collapsed, fields in a fixed canonical order. Two records for the same address that differ only
+ *   in spelling, case, or punctuation produce the same key — which is exactly what the matcher's
+ *   blocking stage wants as one cheap, high-precision candidate signal (alongside geographic
+ *   proximity, which carries the real weight — see the geocode-first record-matching concept doc).
+ *
+ *   Deliberately NOT done yet (follow-ups, all conditioned on `@mailwoman/codex`): expanding street
+ *   suffixes (`Ave` → `avenue`) and directionals (`N` → `north`) to a canonical form, and
+ *   USPS-style standardization. This first version is pure normalization with no dictionary expansion,
+ *   so the key is stable and explainable; expansion is an additive refinement, not a rewrite.
+ */
+import type { ComponentDict } from "#address/format";
+/**
+ * Options accepted by {@linkcode canonicalKey}.
+ */
+export interface CanonicalKeyOptions {
+    /**
+     * Field separator in the emitted key. Default `"|"` — preserves field boundaries for blocking.
+     */
+    separator?: string;
+}
+/**
+ * Options for {@linkcode foldForKey} — the two points where the formatter's address-token fold and the record package's
+ * fragment fold legitimately differ.
+ */
+export interface FoldForKeyOptions {
+    /**
+     * How connective punctuation folds. `"space"` turns `&`, `+`, and `/` into word boundaries (`"A&B"` → `"a b"`);
+     * `"and"` spells `&` and `+` out as the word `and` (`"AT&T"` → `"at and t"`), leaving `/` to the punctuation
+     * catch-all (still a word boundary).
+     */
+    ampersand: "space" | "and";
+    /**
+     * Intra-token deletion set. When true, periods join the apostrophes as intra-token noise and are deleted (`"S.A."` →
+     * `"sa"`), while a backtick falls to the punctuation catch-all. When false or omitted, backticks are deleted
+     * alongside the apostrophes and periods become word boundaries (`"S.A."` → `"s a"`).
+     */
+    dropPeriods?: boolean;
+}
+/**
+ * The shared fold behind every match key: NFKD-decompose and strip combining marks (so `é` → `e`), lowercase, delete
+ * intra-token punctuation, expand or flatten connective punctuation per {@linkcode FoldForKeyOptions}, space every
+ * remaining non-alphanumeric, and collapse whitespace. Deterministic — the same input and options always yield the same
+ * output.
+ */
+export declare function foldForKey(input: string, options: FoldForKeyOptions): string;
+/**
+ * Normalize a single token for matching: {@linkcode foldForKey} with connective punctuation flattened to spaces (so
+ * `"A&B"` → `"a b"`, not `"ab"`). Deterministic and reversible-free — the same input always yields the same output.
+ */
+export declare function normalizeAddressToken(input: string): string;
+/**
+ * Derive the canonical match key from an address component dict: each present, address-identifying field normalized via
+ * {@linkcode normalizeAddressToken}, in fixed order, joined by the separator. Empty / whitespace-only fields are
+ * skipped. Returns an empty string if nothing identifying remains.
+ */
+export declare function canonicalKey(components: ComponentDict, opts?: CanonicalKeyOptions): string;
+//# sourceMappingURL=key.d.ts.map

package/out/address/key.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.d.ts","sourceRoot":"","sources":["../../lib/address/key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAyBpD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC;;OAEG;IACH,SAAS,CAAC,EAAE,MAAM,CAAA;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IACjC;;;;OAIG;IACH,SAAS,EAAE,OAAO,GAAG,KAAK,CAAA;IAC1B;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,GAAG,MAAM,CAqB5E;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,UAAU,EAAE,aAAa,EAAE,IAAI,GAAE,mBAAwB,GAAG,MAAM,CAgB9F"}

package/out/address/key.js

@@ -0,0 +1,91 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   The canonical match key — a normalized, deterministic string derived from address components,
+ *   distinct from the human-readable formatted string.
+ *
+ *   Where `format.ts` produces something for a person to read, this produces something for a
+ *   _machine_ to collide on: lowercased, diacritic-stripped, punctuation-flattened, whitespace-
+ *   collapsed, fields in a fixed canonical order. Two records for the same address that differ only
+ *   in spelling, case, or punctuation produce the same key — which is exactly what the matcher's
+ *   blocking stage wants as one cheap, high-precision candidate signal (alongside geographic
+ *   proximity, which carries the real weight — see the geocode-first record-matching concept doc).
+ *
+ *   Deliberately NOT done yet (follow-ups, all conditioned on `@mailwoman/codex`): expanding street
+ *   suffixes (`Ave` → `avenue`) and directionals (`N` → `north`) to a canonical form, and
+ *   USPS-style standardization. This first version is pure normalization with no dictionary expansion,
+ *   so the key is stable and explainable; expansion is an additive refinement, not a rewrite.
+ */
+/**
+ * The address-identifying components, in canonical key order. Venue / attention are intentionally excluded — those
+ * carry organization identity, which the record layer keys separately.
+ */
+const KEY_FIELD_ORDER = [
+    "po_box",
+    "house_number",
+    "street_prefix",
+    "street_prefix_particle",
+    "street",
+    "street_suffix",
+    "intersection_a",
+    "intersection_b",
+    "unit",
+    "dependent_locality",
+    "locality",
+    "subregion",
+    "region",
+    "postcode",
+    "country",
+];
+/**
+ * The shared fold behind every match key: NFKD-decompose and strip combining marks (so `é` → `e`), lowercase, delete
+ * intra-token punctuation, expand or flatten connective punctuation per {@linkcode FoldForKeyOptions}, space every
+ * remaining non-alphanumeric, and collapse whitespace. Deterministic — the same input and options always yield the same
+ * output.
+ */
+export function foldForKey(input, options) {
+    const folded = input
+        .normalize("NFKD")
+        // strip combining marks (U+0300–U+036F) left by NFKD decomposition, so "é" → "e"
+        .replaceAll(/[\u0300-\u036F]/g, "")
+        .toLowerCase()
+        // apostrophes are intra-word (possessives, "O'Brien") — delete so the token stays whole
+        .replaceAll(options.dropPeriods ? /[.'’]/g : /['’`]/g, "");
+    const connected = options.ampersand === "and"
+        ? folded.replaceAll("&", " and ").replaceAll("+", " and ")
+        : folded.replaceAll(/[&+/]/g, " ");
+    return (connected
+        // everything else non-alphanumeric (keep spaces) is noise
+        .replaceAll(/[^a-z0-9\s]/g, " ")
+        .replaceAll(/\s+/g, " ")
+        .trim());
+}
+/**
+ * Normalize a single token for matching: {@linkcode foldForKey} with connective punctuation flattened to spaces (so
+ * `"A&B"` → `"a b"`, not `"ab"`). Deterministic and reversible-free — the same input always yields the same output.
+ */
+export function normalizeAddressToken(input) {
+    return foldForKey(input, { ampersand: "space" });
+}
+/**
+ * Derive the canonical match key from an address component dict: each present, address-identifying field normalized via
+ * {@linkcode normalizeAddressToken}, in fixed order, joined by the separator. Empty / whitespace-only fields are
+ * skipped. Returns an empty string if nothing identifying remains.
+ */
+export function canonicalKey(components, opts = {}) {
+    const separator = opts.separator ?? "|";
+    const parts = [];
+    for (const tag of KEY_FIELD_ORDER) {
+        const value = components[tag];
+        if (!value)
+            continue;
+        const normalized = normalizeAddressToken(value);
+        if (normalized) {
+            parts.push(normalized);
+        }
+    }
+    return parts.join(separator);
+}
+//# sourceMappingURL=key.js.map

package/out/address/key.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"key.js","sourceRoot":"","sources":["../../lib/address/key.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAKH;;;GAGG;AACH,MAAM,eAAe,GAAG;IACvB,QAAQ;IACR,cAAc;IACd,eAAe;IACf,wBAAwB;IACxB,QAAQ;IACR,eAAe;IACf,gBAAgB;IAChB,gBAAgB;IAChB,MAAM;IACN,oBAAoB;IACpB,UAAU;IACV,WAAW;IACX,QAAQ;IACR,UAAU;IACV,SAAS;CACkC,CAAA;AA+B5C;;;;;GAKG;AACH,MAAM,UAAU,UAAU,CAAC,KAAa,EAAE,OAA0B;IACnE,MAAM,MAAM,GAAG,KAAK;SAClB,SAAS,CAAC,MAAM,CAAC;QAClB,iFAAiF;SAChF,UAAU,CAAC,kBAAkB,EAAE,EAAE,CAAC;SAClC,WAAW,EAAE;QACd,wFAAwF;SACvF,UAAU,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAA;IAE3D,MAAM,SAAS,GACd,OAAO,CAAC,SAAS,KAAK,KAAK;QAC1B,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC;QAC1D,CAAC,CAAC,MAAM,CAAC,UAAU,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAA;IAEpC,OAAO,CACN,SAAS;QACR,0DAA0D;SACzD,UAAU,CAAC,cAAc,EAAE,GAAG,CAAC;SAC/B,UAAU,CAAC,MAAM,EAAE,GAAG,CAAC;SACvB,IAAI,EAAE,CACR,CAAA;AACF,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAAa;IAClD,OAAO,UAAU,CAAC,KAAK,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,CAAA;AACjD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,UAAyB,EAAE,IAAI,GAAwB,EAAE;IACrF,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,GAAG,CAAA;IACvC,MAAM,KAAK,GAAa,EAAE,CAAA;IAE1B,KAAK,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;QACnC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,CAAC,CAAA;QAE7B,IAAI,CAAC,KAAK;YAAE,SAAQ;QACpB,MAAM,UAAU,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAA;QAE/C,IAAI,UAAU,EAAE,CAAC;YAChB,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC,CAAA;QACvB,CAAC;IACF,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAA;AAC7B,CAAC"}

package/out/address/layout.d.ts

@@ -0,0 +1,104 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Per-address-system LAYOUTS: the order a system prints its components in, as data.
+ *
+ *   A layout is written as a tagged template that reads in the order it prints, so reviewing one means looking at the
+ *   shape of the address it produces rather than at a nested function call. The interpolations are slots; the literal
+ *   text between them are connectors.
+ *
+ *   ONE RULE governs rendering, and it replaces four mechanisms that each did part of the job elsewhere — the
+ *   `filter(isPresent).join(…)` written by hand in 28 files, a pass that stripped a connector a template wrote between
+ *   two slots when one was empty, a pass that spliced a missing line back in, and a chain of `if (x) parts.push(x)`:
+ *
+ *   > A node that renders nothing removes itself, and its connector goes with it.
+ *
+ *   A connector between two slots renders when a slot rendered on each side of it. A connector at the edge of a line
+ *   has only one side, so it binds to the single slot it touches — which is how Japan's postal mark 〒 disappears with
+ *   an absent postcode while an interior space does not.
+ *
+ *   WHY A TEMPLATE RATHER THAN NESTED CALLS. The order has to be readable by someone checking whether a country is
+ *   right, and the check is "does this look like an address from there". A nested `seq(", ", locality, seq(" ", region,
+ *   postcode))` encodes the same thing and reads like a parser. The template also needs no nesting for the common case:
+ *   treating every separator as a connector makes each line flat, and the four outcomes of a partially-filled tail
+ *   (`New York, NY 10118` / `New York, NY` / `New York, 10118` / `NY 10118`) fall out of the one rule.
+ *
+ *   The RENDERER is the sibling `render.ts`, and the public surface over it is `format.ts`. They are separate modules
+ *   rather than one so a consumer that only wants the table — a conformance check, a documentation build — imports
+ *   `#address/layouts` and loads no evaluator.
+ */
+import { type ComponentTag } from "#component";
+/**
+ * A slot: one component tag's value, or nothing when the dict has no value for it.
+ */
+export interface AddressSlot {
+    readonly tag: ComponentTag;
+}
+/**
+ * A connector: literal text that renders only between neighbours that rendered. Written as the text BETWEEN
+ * interpolations, never constructed by hand.
+ */
+export interface AddressConnector {
+    readonly connector: string;
+}
+/**
+ * First alternative that renders. The street line needs it and nothing else does: an intersection prints as `<a> & <b>`
+ * where a street prints as its own family of tags.
+ */
+export interface AddressAlternation {
+    readonly alternatives: readonly AddressLayout[];
+}
+export type AddressAtom = AddressSlot | AddressConnector | AddressAlternation | AddressLayout;
+/**
+ * A layout: lines of atoms, in print order. A line break in the template starts a new line; how lines are joined for
+ * single-line output is the caller's choice, and per-system for the systems that join on nothing.
+ */
+export interface AddressLayout {
+    readonly lines: ReadonlyArray<readonly AddressAtom[]>;
+}
+export declare function isSlot(atom: AddressAtom): atom is AddressSlot;
+export declare function isConnector(atom: AddressAtom): atom is AddressConnector;
+export declare function isAlternation(atom: AddressAtom): atom is AddressAlternation;
+export declare function isLayout(atom: AddressAtom): atom is AddressLayout;
+/**
+ * Every {@linkcode ComponentTag} as a slot, so a layout names a tag by destructuring rather than by quoting it. A
+ * misspelled slot is then an unresolved identifier at compile time, and the spelling stays the tag's own —
+ * `dependent_locality`, never a parallel camelCase vocabulary.
+ */
+export declare const SLOTS: Readonly<Record<ComponentTag, AddressSlot>>;
+/**
+ * The first alternative that renders wins. Used for the street line, where an intersection and a street name are two
+ * ways of saying where, not two things to print.
+ */
+export declare function either(...alternatives: readonly AddressLayout[]): AddressAlternation;
+/**
+ * The street line where the number leads: the anglophone order, and France's.
+ *
+ * An intersection is an ALTERNATIVE to the street name because it is a different way of saying where, not a second
+ * thing to print — the shape the old `composeRoad` drew in its own docstring before hand-compiling it into a chain of
+ * `if` statements. The box is not an alternative, so it sits outside the choice.
+ */
+export declare const numberFirstStreet: AddressLayout;
+/**
+ * The number-first line where a comma separates the number from the name — India's order.
+ */
+export declare const numberFirstCommaStreet: AddressLayout;
+/**
+ * The street line where the number follows the name: the German-order systems, and Italy.
+ */
+export declare const numberLastStreet: AddressLayout;
+/**
+ * The number-last line where a comma separates the name from the number — `Calle Mayor, 12`, and Brazil's order.
+ *
+ * The separator is not cosmetic. Spain's corpus recipe renders both this form and the space form on purpose, because
+ * both occur in what a person types; collapsing one into the other would remove half the signal.
+ */
+export declare const numberLastCommaStreet: AddressLayout;
+/**
+ * Build a layout from a tagged template. A newline in the literal text starts a line; other literal text is a
+ * connector; an interpolation is a slot, an alternation, or another layout.
+ */
+export declare function addr(strings: TemplateStringsArray, ...values: readonly AddressAtom[]): AddressLayout;
+//# sourceMappingURL=layout.d.ts.map

package/out/address/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../../lib/address/layout.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AAEH,OAAO,EAAkB,KAAK,YAAY,EAAE,MAAM,YAAY,CAAA;AAE9D;;GAEG;AACH,MAAM,WAAW,WAAW;IAC3B,QAAQ,CAAC,GAAG,EAAE,YAAY,CAAA;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC,QAAQ,CAAC,YAAY,EAAE,SAAS,aAAa,EAAE,CAAA;CAC/C;AAED,MAAM,MAAM,WAAW,GAAG,WAAW,GAAG,gBAAgB,GAAG,kBAAkB,GAAG,aAAa,CAAA;AAE7F;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC,SAAS,WAAW,EAAE,CAAC,CAAA;CACrD;AAED,wBAAgB,MAAM,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,IAAI,WAAW,CAE7D;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,IAAI,gBAAgB,CAEvE;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,IAAI,kBAAkB,CAE3E;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,IAAI,aAAa,CAEjE;AAED;;;;GAIG;AACH,eAAO,MAAM,KAAK,EAAE,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,WAAW,CAAC,CAE7D,CAAA;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,GAAG,YAAY,EAAE,SAAS,aAAa,EAAE,GAAG,kBAAkB,CAEpF;AAYD;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,EAAE,aAI7B,CAAA;AAEH;;GAEG;AACH,eAAO,MAAM,sBAAsB,EAAE,aAIlC,CAAA;AAEH;;GAEG;AACH,eAAO,MAAM,gBAAgB,EAAE,aAI5B,CAAA;AAEH;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,EAAE,aAIjC,CAAA;AAEH;;;GAGG;AACH,wBAAgB,IAAI,CAAC,OAAO,EAAE,oBAAoB,EAAE,GAAG,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,aAAa,CA+BpG"}

package/out/address/layout.js

@@ -0,0 +1,123 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Per-address-system LAYOUTS: the order a system prints its components in, as data.
+ *
+ *   A layout is written as a tagged template that reads in the order it prints, so reviewing one means looking at the
+ *   shape of the address it produces rather than at a nested function call. The interpolations are slots; the literal
+ *   text between them are connectors.
+ *
+ *   ONE RULE governs rendering, and it replaces four mechanisms that each did part of the job elsewhere — the
+ *   `filter(isPresent).join(…)` written by hand in 28 files, a pass that stripped a connector a template wrote between
+ *   two slots when one was empty, a pass that spliced a missing line back in, and a chain of `if (x) parts.push(x)`:
+ *
+ *   > A node that renders nothing removes itself, and its connector goes with it.
+ *
+ *   A connector between two slots renders when a slot rendered on each side of it. A connector at the edge of a line
+ *   has only one side, so it binds to the single slot it touches — which is how Japan's postal mark 〒 disappears with
+ *   an absent postcode while an interior space does not.
+ *
+ *   WHY A TEMPLATE RATHER THAN NESTED CALLS. The order has to be readable by someone checking whether a country is
+ *   right, and the check is "does this look like an address from there". A nested `seq(", ", locality, seq(" ", region,
+ *   postcode))` encodes the same thing and reads like a parser. The template also needs no nesting for the common case:
+ *   treating every separator as a connector makes each line flat, and the four outcomes of a partially-filled tail
+ *   (`New York, NY 10118` / `New York, NY` / `New York, 10118` / `NY 10118`) fall out of the one rule.
+ *
+ *   The RENDERER is the sibling `render.ts`, and the public surface over it is `format.ts`. They are separate modules
+ *   rather than one so a consumer that only wants the table — a conformance check, a documentation build — imports
+ *   `#address/layouts` and loads no evaluator.
+ */
+import { COMPONENT_TAGS } from "#component";
+export function isSlot(atom) {
+    return "tag" in atom;
+}
+export function isConnector(atom) {
+    return "connector" in atom;
+}
+export function isAlternation(atom) {
+    return "alternatives" in atom;
+}
+export function isLayout(atom) {
+    return "lines" in atom;
+}
+/**
+ * Every {@linkcode ComponentTag} as a slot, so a layout names a tag by destructuring rather than by quoting it. A
+ * misspelled slot is then an unresolved identifier at compile time, and the spelling stays the tag's own —
+ * `dependent_locality`, never a parallel camelCase vocabulary.
+ */
+export const SLOTS = Object.freeze(Object.fromEntries(COMPONENT_TAGS.map((tag) => [tag, Object.freeze({ tag })])));
+/**
+ * The first alternative that renders wins. Used for the street line, where an intersection and a street name are two
+ * ways of saying where, not two things to print.
+ */
+export function either(...alternatives) {
+    return { alternatives };
+}
+/**
+ * A post-office box takes a line of its own directly above the street line, and coexists with one: a record may carry
+ * both a box and a street address, and printing the box alone would lose the half a courier needs.
+ *
+ * That placement is measured, not assumed. The engine this table replaces rendered `P.O. Box 5` + `100 Main St` +
+ * `Portland, OR 97214` as three lines in that order, and the same shape for Germany, Australia and Great Britain.
+ * libaddressinput models no box at all, which is why the slot is authored here rather than transcribed.
+ */
+const poBoxLine = SLOTS.po_box;
+/**
+ * The street line where the number leads: the anglophone order, and France's.
+ *
+ * An intersection is an ALTERNATIVE to the street name because it is a different way of saying where, not a second
+ * thing to print — the shape the old `composeRoad` drew in its own docstring before hand-compiling it into a chain of
+ * `if` statements. The box is not an alternative, so it sits outside the choice.
+ */
+export const numberFirstStreet = addr `${poBoxLine}
+${either(addr `${SLOTS.intersection_a} & ${SLOTS.intersection_b}`, addr `${SLOTS.house_number} ${SLOTS.street_prefix} ${SLOTS.street_prefix_particle} ${SLOTS.street} ${SLOTS.street_suffix} ${SLOTS.unit}`)}`;
+/**
+ * The number-first line where a comma separates the number from the name — India's order.
+ */
+export const numberFirstCommaStreet = addr `${poBoxLine}
+${either(addr `${SLOTS.intersection_a} & ${SLOTS.intersection_b}`, addr `${SLOTS.house_number}, ${SLOTS.street_prefix} ${SLOTS.street_prefix_particle} ${SLOTS.street} ${SLOTS.street_suffix} ${SLOTS.unit}`)}`;
+/**
+ * The street line where the number follows the name: the German-order systems, and Italy.
+ */
+export const numberLastStreet = addr `${poBoxLine}
+${either(addr `${SLOTS.intersection_a} & ${SLOTS.intersection_b}`, addr `${SLOTS.street_prefix} ${SLOTS.street_prefix_particle} ${SLOTS.street} ${SLOTS.street_suffix} ${SLOTS.house_number} ${SLOTS.unit}`)}`;
+/**
+ * The number-last line where a comma separates the name from the number — `Calle Mayor, 12`, and Brazil's order.
+ *
+ * The separator is not cosmetic. Spain's corpus recipe renders both this form and the space form on purpose, because
+ * both occur in what a person types; collapsing one into the other would remove half the signal.
+ */
+export const numberLastCommaStreet = addr `${poBoxLine}
+${either(addr `${SLOTS.intersection_a} & ${SLOTS.intersection_b}`, addr `${SLOTS.street_prefix} ${SLOTS.street_prefix_particle} ${SLOTS.street} ${SLOTS.street_suffix}, ${SLOTS.house_number} ${SLOTS.unit}`)}`;
+/**
+ * Build a layout from a tagged template. A newline in the literal text starts a line; other literal text is a
+ * connector; an interpolation is a slot, an alternation, or another layout.
+ */
+export function addr(strings, ...values) {
+    const lines = [[]];
+    const push = (atom) => {
+        lines.at(-1).push(atom);
+    };
+    for (const [index, raw] of strings.entries()) {
+        // A template's literal segment is bounded by the source text that spells it — one address line at most, and a
+        // layout cannot grow at runtime.
+        // oxlint-disable-next-line mailwoman/prefer-spliterator -- bounded by the source text, see above
+        const segments = raw.split("\n");
+        for (const [segmentIndex, segment] of segments.entries()) {
+            if (segmentIndex > 0) {
+                lines.push([]);
+            }
+            if (segment) {
+                push({ connector: segment });
+            }
+        }
+        const value = values[index];
+        if (value) {
+            push(value);
+        }
+    }
+    return { lines: lines.filter((line) => line.length > 0) };
+}
+//# sourceMappingURL=layout.js.map

package/out/address/layout.js.map

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

package/out/address/layouts/generated.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @generated
+ *
+ *   GENERATED — run `node packages/mailwoman/lib/dev-tools/codex/address-layouts.ts` to refresh. Do not edit by hand.
+ *
+ *   One layout per country, derived from libaddressinput's `fmt` skeleton (which fields print, in what order) and the
+ *   street order read once from the OpenCage templates (which slot leads). The `fmt` each was derived from is quoted
+ *   above it, so a reader can compare the two without opening the dataset.
+ *
+ *   The locales this project publishes weights for are NOT here: those are hand-authored in the sibling `index.ts` and
+ *   checked against real addresses on a board, because a generated skeleton is a starting point rather than a verdict.
+ */
+import { type AddressLayout } from "#address/layout";
+/**
+ * Generated layouts, keyed by ISO 3166-1 alpha-2.
+ */
+export declare const GENERATED_ADDRESS_LAYOUTS: Readonly<Record<string, AddressLayout>>;
+//# sourceMappingURL=generated.d.ts.map

package/out/address/layouts/generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated.d.ts","sourceRoot":"","sources":["../../../lib/address/layouts/generated.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,EAON,KAAK,aAAa,EAClB,MAAM,iBAAiB,CAAA;AAIxB;;GAEG;AACH,eAAO,MAAM,yBAAyB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,aAAa,CAAC,CAsgD7E,CAAA"}