@mailwoman/corpus 10.1.0 → 10.2.1

package/data/licenses/cdla-permissive-2.0.md

@@ -25,7 +25,7 @@ so the condition attaches to that hosting, which is why this file is committed.
 > 3.1. This agreement does not impose any restriction or obligations with respect to the use,
 > modification, or sharing of Results.
 
-> 5.4. "Results" means any outcome obtained by computational analysis of Data, including for example
+> 5.4. "Results" means any result obtained by computational analysis of Data, including for example
 > machine learning models and models' insights.
 
 Read together, the agreement states that a machine-learning model is a Result and that it carries no

package/lib/adapters/cordis/adapter.ts

@@ -93,7 +93,7 @@
  *
  * A value holding no letter and no digit (`-`, `.`), or one of `N/A`, `NA`, `none`, `Not applicable`,
  * is treated as absent. A postcode with no digit (`EIRE`, `Clare`, `POSTFACH`) and a postcode of
- * zeroes alone are dropped from the row rather than refusing it, and counted as `component:postcode:*`.
+ * zeroes only are dropped from the row rather than refusing it, and counted as `component:postcode:*`.
  * A postcode written with its country prefix, `LV-1063` or `LT-01103`, is kept as published: Latvia
  * and Lithuania write that prefix in their official form.
  *
@@ -312,8 +312,10 @@ const streetOrderMemo = new Map<string, StreetOrder | null>()
 /**
  * The side a country writes its house number on, or `null` where codex's sources disagree or state none.
  *
- * Read from the `house-number-precedes-street` claim, which collects libaddressinput's `fmt` and `lfmt`,
- * the OpenCage street order, the board's hand-authored layout and a retrieved UPU S42 template.
+ * Read from the `house-number-precedes-street` claim.
+ * That claim collects libaddressinput's `fmt` and `lfmt`, the OpenCage street order,
+ * the board's hand-authored layout and a retrieved UPU S42 template.
+ *
  * A side is returned only when at least one source states it and none states the other.
  *
  * Hong Kong's Chinese-script `fmt` writes the number after the street
@@ -583,10 +585,14 @@ export function readCORDISRecord(record: CORDISOrganizationRecord, lexicon: Pers
 
 	components.locality = locality
 
-	// The script is passed rather than left to the formatter, which keeps a country's local
-	// order whenever its Latin order has fewer slots: `Weixing Road` and `Changchun` would
-	// otherwise print run together in China's Han-script line, with no separator between them.
-	const rendered = formatAddressRow(components, country, { singleLine: true, script: scriptOfComponents(components) })
+	// The script is passed rather than left to the formatter.
+	// That keeps a country's local order whenever its Latin order has fewer slots:
+	// `Weixing Road` and `Changchun` would otherwise print run together in China's
+	// Han-script line, with no separator between them.
+	const rendered = formatAddressRow(components, country, {
+		singleLine: true,
+		script: scriptOfComponents(components),
+	})
 
 	if (!rendered) return { refused: CORDISRefusal.Unrenderable, country }
 

package/lib/adapters/dedup-key.ts

@@ -19,7 +19,7 @@ import type { CanonicalRow } from "#types"
  *
  * License and provenance fields stay out of the key, so two adapters emitting
  * the same address produce the same key.
- * That alone does not deduplicate the corpus across adapters: `runAdapter` holds its key store as a local
+ * The key store does not deduplicate across adapters: `runAdapter` holds its own as a local
  * and discards it when the adapter returns, so each adapter is deduplicated only against itself.
  *
  * A cross-adapter pass would hold every adapter's keys at once and would have to choose

package/lib/adapters/geonames/adapter.ts

@@ -11,7 +11,7 @@
 
 import { componentsPresentIn } from "@mailwoman/codex/address/format"
 import { readUnquotedTSV } from "@mailwoman/core/fs/delimited"
-import { pathExists } from "@mailwoman/core/fs/readers"
+import { pathExists } from "@mailwoman/core/fs/readers/stat"
 import { PathBuilder } from "path-ts"
 
 import { stableSourceID } from "#adapters/source-id"

package/lib/adapters/gleif/adapter.ts

@@ -20,12 +20,12 @@
  * and/or download individual LEIs and/or related LE-RD and/or the entire set or a subset of LEIs",
  * which is the golden copy. GLEIF's open-data page states the same: "The data on GLEIF's website is
  * provided under a Creative Commons (CC0) license." The same terms ask a user not to create the
- * impression that derived data or services are provided or endorsed by GLEIF, which is why
+ * impression that derived data or services are provided or endorsed by GLEIF. That is why
  * {@linkcode GLEIF_ATTRIBUTION} credits the source rather than the corpus.
  *
  * ## Organization addresses only
  *
- * The register carries legal entities, and three of its fields identify an entity that is a natural
+ * The register holds legal entities, and three of its fields identify an entity that is a natural
  * person trading in their own name. {@linkcode readGLEIFEntity} refuses each:
  *
  * 1. `Entity.EntityCategory` = `SOLE_PROPRIETOR`.
@@ -67,7 +67,7 @@
  * The value the split leaves as `street` must then read as a street. It is refused where it still holds
  * a comma (`CAVES CORPORATE CENTRE, BUILDING 2` under the Bahamas' number-last layout), where it holds
  * a building or in-building word (`1302 DOMINION CENTRE`, `903 PLATINUM TOWER`, `APTO 2`), and where it
- * is a generic word alone (`910 Street`). Each of those numbers a room, an office or a building, and
+ * is only a generic word (`910 Street`). Each of those numbers a room, an office or a building, and
  * labeling it `house_number` beside a building name labeled `street` would teach the wrong boundary.
  *
  * `AdditionalAddressLine.1`–`3` mix building names, districts, floors and second street lines, and
@@ -77,7 +77,7 @@
  * ## Region
  *
  * `Region` is an ISO 3166-2 code such as `SK-KI`, which is not how an address writes the region.
- * It reaches a row only where the code's suffix is the written form, which
+ * It reaches a row only where the code's suffix is the written form.
  * `matchSubdivisionIn` answers for the United States, Canada and Australia. A code whose
  * country prefix differs from `Country` refuses the address as contradicting it.
  *
@@ -145,7 +145,7 @@ export const GLEIF_LICENSE = "CC0-1.0"
 export const GLEIF_LICENSE_URL = "https://www.gleif.org/en/meta/lei-data-terms-of-use"
 
 /**
- * The credit a model card carries.
+ * The credit a model card includes.
  *
  * CC0 requires none.
  * The terms ask that no derived product imply GLEIF's endorsement, so the credit
@@ -278,7 +278,7 @@ export const GLEIFRefusal = {
 	 */
 	StreetHoldsPremiseWord: "street-holds-premise-word",
 	/**
-	 * The street the split left is a generic word alone, as Qatar's `910 Street` leaves `Street`.
+	 * The street the split left is only a generic word, as Qatar's `910 Street` leaves `Street`.
 	 */
 	StreetNameGenericOnly: "street-name-generic-only",
 	/**
@@ -290,7 +290,7 @@ export const GLEIFRefusal = {
 	 */
 	Unrenderable: "unrenderable",
 	/**
-	 * The rendered line carries fewer than two address components besides the venue.
+	 * The rendered line holds fewer than two address components besides the venue.
 	 */
 	ComponentsTooFew: "components-too-few",
 } as const
@@ -301,7 +301,7 @@ export const GLEIFRefusal = {
 export type GLEIFRefusal = (typeof GLEIFRefusal)[keyof typeof GLEIFRefusal]
 
 /**
- * The two address blocks a record carries for its entity.
+ * The two address blocks a record holds for its entity.
  */
 export const GLEIFAddressBlock = {
 	Legal: "LegalAddress",
@@ -324,7 +324,7 @@ export type GLEIFRecord = Readonly<Record<string, string | undefined>>
 export type GLEIFAddressReading = { readonly admitted: CanonicalRow } | { readonly refused: GLEIFRefusal }
 
 /**
- * The address fields a block carries, in the order the CDF lists them.
+ * The address fields a block holds, in the order the CDF lists them.
  */
 const ADDRESS_FIELDS = [
 	"FirstAddressLine",
@@ -365,7 +365,7 @@ const CARE_OF = /^(?:c\s*\/\s*o\b|c\/-|care\s+of\b|attn\b|attention\b)/iu
 const PO_BOX_LINE = /^(?:p\.?\s?o\.?\s?box|post\s+office\s+box)\s*(?:no\.?\s*)?\d+[a-z]?$/iu
 
 /**
- * An English ordinal written in digits, which is part of a street's name rather than a premise number.
+ * An English ordinal written in digits, such as `5TH`, is part of the street name.
  */
 const ORDINAL_TOKEN = /\b\d+(?:st|nd|rd|th)\b/giu
 
@@ -394,12 +394,12 @@ const PREMISE_WORD =
 	/\b(?:building|bldg|tower|centre|center|plaza|house|complex|chambers|palazzo|edificio|torre|floor|level|suite|room|office|unit|apto|apt|piso|block|lot|plot|box|km)\b/iu
 
 /**
- * A house number of zeros alone.
+ * A house number that holds only zeros.
  */
 const ZERO_NUMBER = /^0+$/u
 
 /**
- * A street generic standing alone, as a number-first split of `910 Street` leaves it.
+ * A street name that is only a generic word, as a number-first split of `910 Street` leaves it.
  */
 const GENERIC_ONLY = /^(?:street|road|avenue|st|rd|ave)\.?$/iu
 
@@ -411,7 +411,7 @@ const TRAILING_NUMBER_PERIOD = /(\d[\dA-Za-z/-]*)\.$/u
 /**
  * A published value with whitespace collapsed, or an empty string for an absent or placeholder value.
  */
-function fieldValue(value: string | undefined): string {
+function fieldValue(value: string | null | undefined): string {
 	const trimmed = (value ?? "").replaceAll(/\s+/gu, " ").trim()
 
 	return isPlaceholderValue(trimmed) ? "" : trimmed
@@ -462,7 +462,7 @@ const numberOrderCache = new Map<string, boolean | null>()
  *
  * @returns `null` where the layout prints no street line.
  */
-export function houseNumberLeadsStreet(country: string, script?: AddressScript): boolean | null {
+export function houseNumberLeadsStreet(country: string, script: AddressScript | null = null): boolean | null {
 	const key = `${country}:${script ?? ""}`
 	const cached = numberOrderCache.get(key)
 
@@ -618,7 +618,7 @@ function placeStreetNumber(
 	line: string,
 	addressNumber: string,
 	country: string,
-	script: AddressScript | undefined
+	script: AddressScript | null
 ): { street: string; house_number?: string } | { refused: GLEIFRefusal } {
 	const unplacedDigit = (street: string): boolean => /\d/u.test(street.replaceAll(ORDINAL_TOKEN, ""))
 
@@ -643,7 +643,8 @@ function placeStreetNumber(
 
 	// A number-first line may close the number with a comma, as Luxembourg's
 	// `49, AVENUE JOHN F. KENNEDY` does.
-	// The layout renders its own separator, so the comma is not carried into a component.
+	// The layout renders its own separator.
+	// The comma stays out of the component.
 	const split = leads ? splitStreetLine(line.replace(LEADING_NUMBER_COMMA, "$1 ")) : splitTrailingStreetLine(line)
 
 	if (!split?.house_number || ZERO_NUMBER.test(split.house_number) || unplacedDigit(split.street)) {

package/lib/adapters/libpostal-dictionary.ts

@@ -18,8 +18,6 @@ import { TextSpliterator } from "spliterator"
  * A line opening with `#` is a comment.
  *
  * `resourceDictionaryPath` resolves both layouts, `core/data/…` from source and the packaged `out/` tree.
- * The candidate list this replaced named one of them twice, guessed a third path from `process.cwd()`,
- * and swallowed every error while probing, so a corrupt dictionary reported as a missing one.
  *
  * The largest dictionary is 8.4 KB, and each caller loads it once per process at module load.
  */

package/lib/adapters/openaddresses/adapter.ts

@@ -91,7 +91,7 @@ export interface OpenaddressesAdapterOptions {
 	/**
 	 * Per-row license used when a Feature lacks an explicit `LICENSE` property.
 	 *
-	 * Defaults to `CC-BY-4.0` — the most common license across the OpenAddresses collection.
+	 * @defaultValue `CC-BY-4.0` — the most common license across the OpenAddresses collection.
 	 * Override per dump via the runner's adapter-options passthrough.
 	 */
 	defaultLicense?: string
@@ -99,13 +99,14 @@ export interface OpenaddressesAdapterOptions {
 	/**
 	 * Whether this adapter emits a row whose per-file license requires share-alike.
 	 *
-	 * The default is `true`.
 	 * `buildCorpus({ licensePolicy })` and `mw corpus build --license-policy share-alike-free`
 	 * express a refusal at build level.
 	 *
 	 * The policy reads the obligations of every adapter's rows under one policy and records what it refused.
 	 *
 	 * Pass `false` only for an adapter-scoped drop, such as a fixture that must use one license.
+	 *
+	 * @defaultValue `true`
 	 */
 	allowShareAlike?: boolean
 }
@@ -174,7 +175,7 @@ export function createOpenaddressesAdapter(opts: OpenaddressesAdapterOptions = {
 
 					const license = (props.license?.trim() || defaultLicense).trim()
 
-					if (!allowShareAlike && shareAlike.read(license).refusal !== null) {
+					if (!allowShareAlike && shareAlike.read(license).refusal) {
 						shareAlikeBlocked++
 
 						continue

package/lib/adapters/osm/adapter.ts

@@ -48,8 +48,9 @@ export const OSM_LICENSE_URL = "https://opendatacommons.org/licenses/odbl/1-0/"
 /**
  * The attribution OSM requires in redistributed data and derived works.
  *
- * A database built from OSM embeds it, and a model card carries it when OSM-derived
- * rows reached the checkpoint, which the effective training manifest records.
+ * A database built from OSM embeds it.
+ * A model card holds it when OSM-derived rows reach the checkpoint.
+ * The effective training manifest records those rows.
  */
 export const OSM_ATTRIBUTION =
 	"© OpenStreetMap contributors. Data licensed under the Open Database License (ODbL) 1.0 " +
@@ -59,17 +60,17 @@ export const OSM_ATTRIBUTION =
  * The per-row shape `@mailwoman/osm`'s `emit-corpus-jsonl` writes.
  */
 interface OSMCorpusRow {
-	street?: string
-	number?: string
-	postcode?: string
-	suburb?: string
-	city?: string
-	unit?: string
-	place?: string
-	subdistrict?: string
-	district?: string
-	province?: string
-	country?: string
+	street?: string | null
+	number?: string | null
+	postcode?: string | null
+	suburb?: string | null
+	city?: string | null
+	unit?: string | null
+	place?: string | null
+	subdistrict?: string | null
+	district?: string | null
+	province?: string | null
+	country?: string | null
 }
 
 const MAX_STREET_WORDS = 8
@@ -119,7 +120,7 @@ export function splitCityValue(value: string): { locality: string; head: string
 
 const PLACEHOLDERS = new Set(["n/a", "na", "none", "-", "nil"])
 
-function clean(value: string | undefined): string | null {
+function clean(value: string | null | undefined): string | null {
 	const trimmed = value?.trim() ?? ""
 
 	return trimmed && !PLACEHOLDERS.has(trimmed.toLowerCase()) ? trimmed : null
@@ -142,10 +143,10 @@ function parseLine(line: string): OSMCorpusRow | null {
  * A row with no `addr:street` at all is admitted as a streetless premise when its house
  * number is designator-shaped and a tag that maps to `locality` or `dependent_locality`
  * (`addr:city`, `addr:place`, `addr:suburb`, `addr:subdistrict`, `addr:district`)
- * carries the identity the street would have carried.
+ * holds the identity the street would have held.
  *
- * That is OSM's documented scheme for addresses numbered within a named place
- * rather than along a street, and it is the `streetless-premise-identity` shape.
+ * That is OSM's documented scheme for addresses numbered within a place rather than
+ * along a street, and it is the `streetless-premise-identity` shape.
  * A row whose `addr:street` holds a line rather than a name stays refused:
  * the mapper supplied a street, and the value is a line.
  *
@@ -205,7 +206,7 @@ export function componentsForOSMRow(
 	// `district` never becomes `region`, because Vietnam's country template
 	// renders it only when no city is present.
 	const dependent = [row.suburb, row.subdistrict, row.district, row.place, split?.head]
-		.map((value) => clean(value ?? undefined))
+		.map((value) => clean(value))
 		.find(
 			(value) =>
 				value !== null &&
@@ -220,12 +221,12 @@ export function componentsForOSMRow(
 
 	const province = clean(row.province)
 
-	if (province && (split === null || !sameName(province, split.locality))) {
+	if (province && (!split || !sameName(province, split.locality))) {
 		components.region = province
 	}
 
-	// A streetless premise is a house number within a named place, so it needs a locality
-	// or a dependent locality, from any of the tags that map to them.
+	// A streetless premise is a house number within a place that has a name, so it needs
+	// a locality or a dependent locality, from any of the tags that map to them.
 	if (!street && !components.locality && !components.dependent_locality) {
 		countDropped(tally, "row:streetless-no-locality")
 

package/lib/adapters/po-box/adapter.ts

@@ -56,18 +56,21 @@ export interface PoBoxAdapterOptions {
 	/**
 	 * Probability (0..1) of emitting a PMB-with-street variant when the input has
 	 * a street and the locale supports PMB.
-	 * The default is 0.15.
+	 *
+	 * @defaultValue `0.15`
 	 */
 	pmbRatio?: number
 	/**
 	 * Deterministic seed for reproducible synthesis.
-	 * The default is `Date.now()`.
+	 *
+	 * @defaultValue `Date.now()`
 	 */
 	seed?: number
 	/**
 	 * Probability (0..1) per input tuple of additionally emitting one self-contained US
 	 * military/diplomatic PO-box row, so military volume scales with the input stream.
-	 * The default is 0.
+	 *
+	 * @defaultValue `0`
 	 */
 	militaryRatio?: number
 }
@@ -110,7 +113,7 @@ export function createPoBoxAdapter(opts: PoBoxAdapterOptions = {}): CorpusAdapte
 
 				const input = tryParsingJSON<PoBoxInputRow>(trimmed)
 
-				if (input === null) {
+				if (!input) {
 					skipped++
 
 					continue
@@ -160,7 +163,9 @@ export function createPoBoxAdapter(opts: PoBoxAdapterOptions = {}): CorpusAdapte
 
 				// US military/diplomatic rows are self-contained and off by default,
 				// so the default random stream and output stay byte-identical.
-				// They are US-only and count against `limit`.
+				// They are US-only and count against `limit`. country-branch: APO/FPO/DPO
+				// rows exist in the US postal system only.
+				// A postal-regime flag in the codex would replace this.
 				const militaryAllowed = !options.country || options.country === "US"
 
 				if (

package/lib/adapters/registry.ts

@@ -26,9 +26,9 @@ export interface AdapterRegistry {
 	register(adapter: CorpusAdapter): void
 
 	/**
-	 * Return the adapter for `id`, or `undefined`.
+	 * Return the adapter for `id`, or `null`.
 	 */
-	get(id: string): CorpusAdapter | undefined
+	get(id: string): CorpusAdapter | null
 
 	/**
 	 * All registered adapters, in insertion order.
@@ -58,8 +58,8 @@ export class InMemoryAdapterRegistry implements AdapterRegistry {
 		this.#byID.set(adapter.id, adapter)
 	}
 
-	get(id: string): CorpusAdapter | undefined {
-		return this.#byID.get(id)
+	get(id: string): CorpusAdapter | null {
+		return this.#byID.get(id) ?? null
 	}
 
 	list(): readonly CorpusAdapter[] {

package/lib/adapters/source-id.ts

@@ -5,7 +5,7 @@
  *
  *   The deterministic row id for a source that publishes no primary key of its own.
  *
- * A CSV row or GeoJSON feature often carries no stable identifier. The runner still needs one, so
+ * A CSV row or GeoJSON feature often has no stable identifier. The runner still needs one, so
  * deduplication and holdout manifests agree across reruns and a run can resume. These functions
  * derive it by hashing the adapter id together with a canonical serialization of the row's values.
  *
@@ -20,7 +20,7 @@ import { sha256Hex } from "@mailwoman/core/hash"
  * The deterministic content-addressed source id for a row, keyed by its components.
  *
  * The output is `<adapterID>-<first 12 hex characters of sha256>`.
- * Twelve hex characters carry 48 bits, which holds about 17 million rows per adapter
+ * Twelve hex characters give 48 bits, about 17 million rows per adapter
  * before the expected collision count passes 1.
  * An adapter above that extends the prefix.
  */

package/lib/adapters/street-line.ts

@@ -3,12 +3,12 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Reading a house number and a street out of the columns a publisher supplies.
+ *   This module reads a house number and a street out of the columns a publisher supplies.
  *
  * Publishers divide the same address two ways. Some write one street line that holds the number and
- * the street together, which {@linkcode splitStreetLine} separates for a number-first country and
+ * the street together. {@linkcode splitStreetLine} separates that line for a number-first country and
  * {@linkcode splitTrailingStreetLine} for a number-last one. Others write the number across
- * two columns, which {@linkcode composeHouseNumber} joins. Every adapter facing either shape uses
+ * two columns. {@linkcode composeHouseNumber} joins those. Every adapter facing either shape uses
  * these, so an edge case fixed here is fixed for all of them.
  *
  * Which of the two split functions a country takes is `STREET_ORDERS` in
@@ -73,7 +73,7 @@ export function splitStreetLine(line: string): SplitStreetLine | null {
  *
  * The street and the number are separated by whitespace, a comma, or both,
  * because a publisher in a number-last country may write either: Italy's ANAC release
- * carries `VIA INDIPENDENZA, 41` and `VIA MAZZINI 7` in the same column.
+ * holds `VIA INDIPENDENZA, 41` and `VIA MAZZINI 7` in the same column.
  * The separator is required, so `VIA1` stays one street name.
  *
  * Group 1 starts at `\S` and the lazy `.*?` is bounded by that required separator,
@@ -85,8 +85,9 @@ export const HOUSE_NUMBER_SUFFIX = /^(\S.*?)[\s,]+(\d+[A-Za-z]?(?:\s*[/-]\s*[0-9
 /**
  * Split a number-last street line on {@link HOUSE_NUMBER_SUFFIX}.
  *
- * A number-last country writes the number after the street name, which is what
- * `STREET_ORDERS` records for Italy, Germany, Finland and 150 other jurisdictions.
+ * A number-last country writes the number after the street name.
+ * `STREET_ORDERS` records that order for Italy, Germany, Finland and 150 other jurisdictions.
+ *
  * Whitespace inside the line is collapsed, and the separators inside a subdivided
  * number are closed up, so `VIA PERUGIA 2 / A` yields `2/A`.
  *

package/lib/adapters/wof/admin/json/adapter.ts

@@ -59,7 +59,7 @@ import { buildAncestorNameIndex, walkFeatures, type AncestorNames, type WOFRecor
  * Per-adapter deliberately (the postalcode adapter has its own): each table is a record
  * filter for its adapter's emission set rather than a shared vocabulary.
  */
-function placetypeToTag(placetype: WhosOnFirstPlacetype | string): ComponentTag | undefined {
+function placetypeToTag(placetype: WhosOnFirstPlacetype | string): ComponentTag | null {
 	switch (placetype) {
 		case "country":
 		case "nation":
@@ -79,7 +79,7 @@ function placetypeToTag(placetype: WhosOnFirstPlacetype | string): ComponentTag
 		case "microhood":
 			return "dependent_locality"
 		default:
-			return undefined
+			return null
 	}
 }
 

package/lib/adapters/wof/json-rows.ts

@@ -108,8 +108,9 @@ export interface NameSlotOptions {
 	/**
 	 * Canonical surface for the record's own `"default"` slot.
 	 *
-	 * Default `rec.name` verbatim.
 	 * The admin adapter substitutes the OpenCage-canonical {@link COUNTRY_DISPLAY_NAME} for country records.
+	 *
+	 * @defaultValue `rec.name` verbatim.
 	 */
 	canonicalName?: (rec: WOFRecord) => string
 }

package/lib/adapters/wof/postalcode-json/adapter.ts

@@ -48,6 +48,10 @@ const US_STATE_ABBREVIATION_BY_NAME: ReadonlyMap<string, string> = new Map(
  * Other names pass through.
  */
 function regionSurface(country: string, name: string): string {
+	// country-branch: the codex holds a name-to-code table for US states only.
+	// The WOF admin database's `place_abbr` holds codes for ten countries
+	// and an ISO 3166-2 table would cover every country.
+	// The tree holds neither as a lookup yet.
 	if (country !== "US") return name
 
 	return US_STATE_ABBREVIATION_BY_NAME.get(name.trim().toLowerCase()) ?? name
@@ -60,7 +64,7 @@ function regionSurface(country: string, name: string): string {
  * and the ancestor placetypes the variants use.
  * The admin adapter keeps its own mapping.
  */
-function placetypeToTag(placetype: WhosOnFirstPlacetype | string): ComponentTag | undefined {
+function placetypeToTag(placetype: WhosOnFirstPlacetype | string): ComponentTag | null {
 	switch (placetype) {
 		case "country":
 		case "nation":
@@ -73,7 +77,7 @@ function placetypeToTag(placetype: WhosOnFirstPlacetype | string): ComponentTag
 		case "postalcode":
 			return "postcode"
 		default:
-			return undefined
+			return null
 	}
 }
 

package/lib/adapters.ts

@@ -16,16 +16,16 @@
  *   cadastre et de la topographie under `lu`, the State Address Register under `lv`, Kartverket's Matrikkelen
  *   under `no`, EMUiA under `pl`, Romania's school network under `ro`, and the FCC and USGov readers under `us`. A national publisher
  *   stays there even when its own files cover that state's dependencies, because the publisher is
- *   what the adapter reads: BAN carries France and ten overseas jurisdictions, Matrikkelen carries
- *   Norway and Svalbard, and Ryhti's one national file carries Åland beside the Finnish mainland.
+ *   what the adapter reads: BAN covers France and ten overseas jurisdictions, Matrikkelen covers
+ *   Norway and Svalbard, and Ryhti's one national file covers Åland beside the Finnish mainland.
  *
  *   Flanders is the counter-case worth stating. Its adapter sits under `be` and covers the Flemish
- *   Region alone, because Brussels and Wallonia publish the INSPIRE theme through their own
+ *   Region only, because Brussels and Wallonia publish the INSPIRE theme through their own
  *   services, so Belgium needs three adapters rather than one.
  *
  *   Spain needs four, for the same reason. `es-catastro` reads the Dirección General del Catastro's
- *   52 provinces, and `es-bizkaia`, `es-gipuzkoa` and `es-navarra` read the foral cadastres, which
- *   state their own terms and which the national feed links rather than serves.
+ *   52 provinces. `es-bizkaia`, `es-gipuzkoa` and `es-navarra` read the foral cadastres. Those
+ *   cadastres state their own terms. The national feed links them rather than serving them.
  *
  *   An adapter reading a publisher that is not any one country's lives here, at `lib/adapters/<id>/`.
  *   That is the aggregators, `./openaddresses/`, `./osm/`, `./overture/`, `./geonames/` and `./wof/`,

package/lib/au/adapters/gnaf/adapter.ts

@@ -92,7 +92,7 @@ export function createGNAFAdapter(): CorpusAdapter {
 
 				const t = tryParsingJSON<GNAFTuple>(line)
 
-				if (t === null) continue
+				if (!t) continue
 
 				if (!t.house_number || !t.street || !t.locality || !t.postcode) continue