@mailwoman/corpus 10.0.0 → 10.1.0

package/lib/recipes/street.ts

@@ -3,19 +3,42 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   `street` slice recipe — synthetic street-decomposition rows for Stage 3 (US-only): tuples →
- *   {@link synthesizeStreetRow} → aligned LabeledRow. Ported from scripts/build-street-slice.mjs.
+ *   `street` recipe — synthetic street-decomposition rows for Stage 3 (US-only): tuples →
+ *   {@link synthesizeStreetRow} → aligned LabeledRow. Ported from the root build script it replaced.
  */
 
 import { makeLcg } from "@mailwoman/core/utils"
 
-import { stableSourceID } from "#adapters/utils"
+import { stableSourceID } from "#adapters/source-id"
 import { alignAndWrite, readTuples, type CorpusRecipe } from "#recipes/scaffold"
+import { defaultRecipeSource } from "#recipes/sources"
 import { synthesizeStreetRow, type StreetBaseTuple } from "#synthesizers/street"
+import { SurfaceOrigin } from "#types"
 
 /**
- * Slice recipe registered with the corpus builder — see the file header for the parse behaviour it exists to exercise,
- * and `description` below for the surface form it generates.
+ * The recipe draws a street name from a pool and joins it to a tuple's locality, region and postcode.
+ *
+ * No register asserts that the street runs through that locality.
+ * The row is invented rather than a rendering of a published record.
+ */
+/**
+ * Resolved once, because `source_id` includes the source as its prefix and a pair
+ * that disagreed would name a source no row of this output declares.
+ */
+const STREET_SOURCE = defaultRecipeSource("synth-street")
+
+const STREET_PROVENANCE = {
+	register: null,
+	surface: SurfaceOrigin.Invented,
+	// An invented row has no underlying record to name.
+	baseSourceID: null,
+}
+
+/**
+ * Recipe registered with the corpus builder.
+ *
+ * The file header describes the parse behavior this recipe exercises.
+ * `description` below shows the generated surface form.
  */
 export const streetRecipe: CorpusRecipe = {
 	name: "street",
@@ -57,8 +80,8 @@ export const streetRecipe: CorpusRecipe = {
 						components: synth.components,
 						country: tuple.country,
 						locale: synth.locale,
-						source: "synth-street",
-						source_id: stableSourceID("synth-street", {
+						source: STREET_SOURCE,
+						source_id: stableSourceID(STREET_SOURCE, {
 							locality: `${tuple.locality}#${v}`,
 							region: tuple.region,
 							postcode: tuple.postcode,
@@ -67,7 +90,8 @@ export const streetRecipe: CorpusRecipe = {
 						corpus_version: "0.4.0",
 						license: "Synthetic — public-domain street name + tuple combination",
 					},
-					"street-decomp"
+					"street-decomp",
+					STREET_PROVENANCE
 				)
 
 				if (ok) {

package/lib/recipes/sub/venue/context.ts

@@ -10,19 +10,23 @@ import { mulberry32 as makeMulberry32 } from "@mailwoman/core/utils"
 import type { PathBuilderLike } from "path-ts"
 
 import { readTuples as readLocaleTuples, type LocalePart } from "#international/recipes/locale"
-import { readTuples as readSliceTuples } from "#recipes/scaffold"
-import type { LocaleBaseTuple } from "#synthesizers/locale"
+import { readTuples as readRecipeTuples } from "#recipes/scaffold"
+import type { LocaleBaseTuple } from "#surfaces/locale"
 
-//#region Address context
+// #region Address context
 
 /**
- * DE + ES address context. Both read through {@link readLocaleTuples}, the `locale` recipe's own streaming + reservoir
- * reader, so the CSV handling (quoted fields, CRLF, city-noise cleaning, the DE per-part region fallback) has exactly
- * one implementation.
+ * DE + ES address context.
  *
- * DE reads `europe.zip`'s two members rather than `oa-cache/de__*.zip`: the cached per-state zips the `locale` recipe
- * names are not materialized on this host, and the archive members are byte-identical to OA's current run (verified in
- * `corpus/AGENTS.md`'s "a file's mtime is not its data's vintage" note).
+ * Both read through {@link readLocaleTuples}, the `locale` recipe's own streaming + reservoir reader,
+ * so the CSV handling (quoted fields, crlf, city-noise cleaning, the DE per-part region fallback)
+ * has exactly one implementation.
+ *
+ * The DE adapter reads two members from `europe.zip` instead of `oa-cache/de__*.zip`.
+ * The cached per-state zips used by the `locale` recipe are absent on this host.
+ *
+ * The archive members match OA's current run byte for byte.
+ * The note "a file's mtime is not its data's vintage" in `corpus/agents.md` records this comparison.
  */
 const CONTEXT_PARTS: Readonly<Record<string, readonly LocalePart[]>> = {
 	DE: [
@@ -33,9 +37,9 @@ const CONTEXT_PARTS: Readonly<Record<string, readonly LocalePart[]>> = {
 }
 
 /**
- * Load the address skeletons every leg renders onto: GB / US / FR from the house-venue v3 tuples (the same 176,519 real
- * rows the `synth-house-venue` slice is built from, so the two slices' address halves are drawn from one pool), DE and
- * ES streamed out of OpenAddresses.
+ * Load the address skeletons every leg renders onto: GB / US / FR from the house-venue v3 tuples
+ * (the same 176,519 real rows the `invented-house-venue` recipe output is built from, so the two
+ * recipes' address halves are drawn from one pool), DE and ES streamed out of OpenAddresses.
  */
 export async function loadContextTuples(
 	tuplesPath: PathBuilderLike,
@@ -43,7 +47,7 @@ export async function loadContextTuples(
 ): Promise<Map<string, LocaleBaseTuple[]>> {
 	const byCountry = new Map<string, LocaleBaseTuple[]>()
 
-	for await (const tuple of readSliceTuples(tuplesPath)) {
+	for await (const tuple of readRecipeTuples(tuplesPath)) {
 		const country = String(tuple.country ?? "")
 
 		if (!country || !tuple.locality || !tuple.street) continue
@@ -70,8 +74,8 @@ export async function loadContextTuples(
 		const pooled: LocaleBaseTuple[] = []
 
 		for (const [index, part] of parts.entries()) {
-			// A dedicated stream PRNG, seeded per part, so the input sample is reproducible without
-			// perturbing the emit loop's draws (the `locale` recipe's rule, kept).
+			// A dedicated stream prng, seeded per part, so the input sample is reproducible
+			// without perturbing the emit loop's draws (the `locale` recipe's rule, kept).
 			const streamRandom = makeMulberry32(seed + index)
 
 			for (const tuple of await readLocaleTuples(part, streamRandom)) {
@@ -86,12 +90,15 @@ export async function loadContextTuples(
 }
 
 /**
- * The street-side confound classes, mined from the leg's OWN address tuples.
+ * The street-side confound classes, mined from the leg's own address tuples.
+ *
+ * Real streets rather than invented ones.
+ * The 176,519-row context pool includes 195 GB `hall` streets and 114 GB `gate` streets.
  *
- * Real streets, not invented ones. The 176,519-row context pool carries 195 GB `hall` streets, 114 GB `gate` streets,
- * 134 distinct GB `-gate` single tokens and a two-figure `<modifier> <designator>` population in both GB and US — small
- * absolute numbers, but every one of them a street somebody lives on, which is the property an invented list cannot
- * have.
+ * It includes 134 distinct GB `-gate` tokens and a two-figure `<modifier> <designator>`
+ * population in both GB and US.
+ * Each item comes from a real address where someone lives.
+ * Each example comes from a real address tuple.
  */
 export interface StreetNegatives {
 	designator: LocaleBaseTuple[]
@@ -100,8 +107,8 @@ export interface StreetNegatives {
 }
 
 /**
- * Shortest token that can carry a `-gate` street suffix and still be a NAME rather than the bare word: `gate` itself is
- * four characters, so the class starts at five (`Highgate`, `Moorgate`, `Stonegate`).
+ * Shortest token that can take a `-gate` street suffix and still be a name rather than the bare word:
+ * `gate` itself is four characters, so the class starts at five (`Highgate`, `Moorgate`, `Stonegate`).
  */
 const MIN_GATE_SUFFIX_TOKEN_LENGTH = 5
 
@@ -146,4 +153,4 @@ export function buildStreetNegatives(
 	return { designator, modifierDesignator, gateSuffix }
 }
 
-//#endregion
+// #endregion

package/lib/recipes/sub/venue/render.ts

@@ -0,0 +1,170 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Renders labeled pieces into sub-venue rows in a sampled case register and a per-country address order.
+ */
+
+import { layoutForCountry } from "@mailwoman/codex/address/layouts"
+import { type ComponentDict, renderAddress } from "@mailwoman/codex/address/render"
+import type { ComponentTag } from "@mailwoman/codex/component"
+import { isPresent } from "@mailwoman/core/objects"
+
+import type { LocaleBaseTuple } from "#surfaces/locale"
+
+/**
+ * One labeled piece of a row.
+ *
+ * Pieces inside a group are joined with a space.
+ * Groups are joined with the register's separator.
+ */
+export interface Piece {
+	text: string
+	tag?: ComponentTag
+}
+
+/**
+ * A run of pieces that share one comma segment.
+ */
+export type Group = Piece[]
+
+/**
+ * The case and punctuation style of a rendered row.
+ *
+ * Users often type addresses in lowercase, so every recipe output includes lowercase rows.
+ */
+export const Register = {
+	Canonical: "canonical",
+	CommaFree: "comma-free",
+	Lower: "lower",
+	Upper: "upper",
+} as const
+
+/**
+ * One of the {@link Register} values.
+ */
+export type Register = (typeof Register)[keyof typeof Register]
+
+// The cutoffs are cumulative: 45% canonical, 20% comma-free, 25% lower and 10% upper.
+const CANONICAL_REGISTER_CUTOFF = 0.45
+const COMMA_FREE_REGISTER_CUTOFF = 0.65
+const LOWER_REGISTER_CUTOFF = 0.9
+
+/**
+ * Samples a register with the fixed shares above.
+ */
+export function sampleRegister(random: () => number): Register {
+	const r = random()
+
+	if (r < CANONICAL_REGISTER_CUTOFF) return Register.Canonical
+
+	if (r < COMMA_FREE_REGISTER_CUTOFF) return Register.CommaFree
+
+	if (r < LOWER_REGISTER_CUTOFF) return Register.Lower
+
+	return Register.Upper
+}
+
+/**
+ * Joins groups into `raw` and `components`.
+ *
+ * The register's case change applies to both so that alignment still finds every component value in `raw`.
+ */
+export function renderGroups(
+	groups: Group[],
+	register: Register
+): { raw: string; components: Partial<Record<ComponentTag, string>> } {
+	const fold = (text: string): string => {
+		if (register === Register.Lower) return text.toLowerCase()
+
+		if (register === Register.Upper) return text.toUpperCase()
+
+		return text
+	}
+
+	const separator = register === Register.CommaFree ? " " : ", "
+
+	const raw = groups
+		.map((group) => group.map((piece) => fold(piece.text)).join(" "))
+		.filter(isPresent)
+		.join(separator)
+
+	const components: Partial<Record<ComponentTag, string>> = {}
+
+	for (const group of groups) {
+		for (const piece of group) {
+			if (piece.tag && !components[piece.tag]) {
+				components[piece.tag] = fold(piece.text)
+			}
+		}
+	}
+
+	return { raw, components }
+}
+
+/**
+ * Layout connectors that end a group.
+ */
+const GROUP_BREAK = new Set([", ", "\n"])
+
+/**
+ * Returns the street and locality groups for a country in the order of its codex address layout.
+ *
+ * The function splits the rendered layout at comma and line-break connectors.
+ * It returns an empty list when codex has no Latin-script layout for the country.
+ */
+export function addressGroups(country: string, tuple: LocaleBaseTuple, withStreet: boolean): Group[] {
+	const components: ComponentDict = {}
+	const street = tuple.street.trim()
+	const houseNumber = tuple.house_number?.trim()
+
+	if (withStreet && street) {
+		components.street = street
+
+		if (houseNumber) {
+			components.house_number = houseNumber
+		}
+	}
+
+	const locality = tuple.locality.trim()
+	const postcode = tuple.postcode?.trim()
+	const region = tuple.region?.trim()
+
+	if (locality) {
+		components.locality = locality
+	}
+
+	if (postcode) {
+		components.postcode = postcode
+	}
+
+	if (region) {
+		components.region = region
+	}
+
+	const layout = layoutForCountry(country, "latin")
+
+	if (!layout) return []
+
+	const groups: Group[] = []
+	let current: Group = []
+
+	for (const piece of renderAddress(layout, components).pieces) {
+		if (piece.tag === null) {
+			if (GROUP_BREAK.has(piece.text) && current.length) {
+				groups.push(current)
+				current = []
+			}
+
+			continue
+		}
+
+		current.push({ text: piece.text, tag: piece.tag })
+	}
+
+	if (current.length) {
+		groups.push(current)
+	}
+
+	return groups
+}