@mailwoman/corpus 10.1.0 → 10.2.0

package/lib/lv/adapters/varis/adapter.ts

@@ -23,19 +23,19 @@
  * Each record names its immediate parent by `VKUR_CD` and `VKUR_TIPS`, and the parent names its own
  * the same way, up to the country. The type codes are the register's: `104` city (`pilsēta`), `105`
  * parish (`pagasts`), `106` village (`ciems`), `107` street (`iela`), `113` municipality (`novads`)
- * and `101` Latvia, whose code `100000000` no table holds as a row. Over the 550,652 active records the
+ * and `101` Latvia. No table read lists its code `100000000` as a row. Over the 550,652 active records the
  * chains take seven shapes, written from the parent upward. The rows column counts what the adapter
  * emits after the refusals below:
  *
  * | Chain                         | Records |    Rows | {@linkcode VarisAddressType}  |
  * | ----------------------------- | ------: | ------: | ----------------------------- |
- * | parish, municipality          | 116,225 | 116,225 | `parish-named-house`          |
- * | street, city, municipality    | 113,906 | 113,905 | `town-street`                 |
- * | street, city                  | 111,218 | 111,217 | `state-city-street`           |
- * | village, parish, municipality | 108,164 | 108,164 | `village-named-house`         |
- * | street, village, parish, mun. |  98,192 |  98,179 | `village-street`              |
- * | city, municipality            |   2,814 |   2,814 | `city-named-house`            |
- * | city                          |     133 |     133 | `city-named-house`            |
+ * | parish, municipality          | 116,225 | 116,225 | `ParishNamedHouse`          |
+ * | street, city, municipality    | 113,906 | 113,905 | `TownStreet`                 |
+ * | street, city                  | 111,218 | 111,217 | `StateCityStreet`           |
+ * | village, parish, municipality | 108,164 | 108,164 | `VillageNamedHouse`         |
+ * | street, village, parish, mun. |  98,192 |  98,179 | `VillageStreet`              |
+ * | city, municipality            |   2,814 |   2,814 | `CityNamedHouse`            |
+ * | city                          |     133 |     133 | `CityNamedHouse`            |
  *
  * No active record has an unresolved or inactive ancestor, 0 of 550,652.
  *
@@ -45,11 +45,11 @@
  * `"Riņņi", Vecates pag., Valmieras nov., LV-4211`. Each
  * part is the `NOSAUKUMS` of one object in the chain, in chain order, joined by a comma and a space,
  * with the postcode `ATRIB` last. A building on a street writes the street name and the house number
- * as one part, and a named building writes its name inside ASCII double quotes. The adapter composes
+ * as one part, and a building with its own name writes it inside ASCII double quotes. The adapter composes
  * that string from the chain and compares it with `STD`. Over the 550,637 active records the adapter
  * does not refuse first, the two are equal on 550,637. A record where they differ is refused, so every
  * row's `raw` is `STD` unchanged and every component's position in it is known. The row's surface is
- * `attested`. Aligning the 550,637 rows with `alignRow` at edit distance 0 quarantines none and places
+ * `attested`. `alignRow` aligns the 550,637 rows at edit distance 0, quarantines none, and places
  * every component in the order above.
  *
  * The comparison reads values as stored. 25 building names end in a space, and `STD` keeps it inside the
@@ -68,8 +68,8 @@
  *   block (`korpuss`) 1, one address in the register. Over the 323,316 street addresses, 249,783 are
  *   bare digits and 56,374 digits and a letter. 15 hold no digit, such as `Bauskas iela Ozoli`, where
  *   a house name stands in the number's place. Those are refused, because the name is not a number
- *   and labeling it a venue would place a venue after a street, which no other Latvian row does.
- * - A building's name is `venue`. SCHEMA.mdx defines `venue` as a named place and keeps
+ *   and labeling it a venue would place a venue after a street. No other Latvian row does that.
+ * - A building's name is `venue`. SCHEMA.mdx defines `venue` as a place with a name and keeps
  *   `building_name` for Japan, and the Estonian register adapter labels a farm name `venue` for the same
  *   reason. The quotes are punctuation and lie outside the span. 236 names hold a quote of their own,
  *   such as `Stacija "Biksti"`, which the register writes `"Stacija "Biksti""`.
@@ -81,7 +81,7 @@
  *   village inside a rural municipality the same way.
  * - A municipality is `region`, abbreviation included: `Valmieras nov.`. The register holds no tier
  *   above it: the parent of all 35 active municipalities is Latvia. The 7 active cities whose parent is
- *   Latvia, the state cities such as Rīga and Daugavpils, write no municipality, so their rows carry no
+ *   Latvia, the state cities such as Rīga and Daugavpils, write no municipality, so their rows have no
  *   region.
  * - `ATRIB` is `postcode`, prefix included: `LV-4211`.
  *
@@ -94,7 +94,7 @@
  *
  * ## Personal data, identity and license
  *
- * The register records places and names no owner or occupant, so no row carries a natural person's
+ * The register records places and names no owner or occupant, so no row has a natural person's
  * name. A building name is the name of the property, as on a map.
  *
  * The row id is the register's own object code, `lv-varis-<KODS>`. Five `STD` strings are each written
@@ -104,7 +104,7 @@
  * publisher Valsts zemes dienests, and the column metadata posted beside `aw_dziv.csv` names
  * `https://creativecommons.org/licenses/by/4.0/` as `dc:license`. CC BY 4.0 requires credit, a link to the license and
  * a statement that changes were made, so every row records the license and
- * {@linkcode LV_VARIS_ATTRIBUTION} is the credit the model card carries.
+ * {@linkcode LV_VARIS_ATTRIBUTION} is the credit the model card states.
  *
  * The adapter honors `opts.limit` and `opts.signal`. `opts.country` is optional and accepts only `LV`.
  */
@@ -208,11 +208,11 @@ export const VarisRefusal = {
 	 */
 	UnexpectedHierarchy: "row:unexpected-hierarchy",
 	/**
-	 * The record carries no `LV-` postcode.
+	 * The record has no `LV-` postcode.
 	 */
 	PostcodeAbsent: "row:postcode-absent",
 	/**
-	 * A building on a street carries a name with no digit where its number belongs.
+	 * A building on a street has a name with no digit where its number belongs.
 	 */
 	NamedHouseOnStreet: "row:named-house-on-street",
 	/**
@@ -228,7 +228,8 @@ export type VarisRefusal = (typeof VarisRefusal)[keyof typeof VarisRefusal]
  */
 export const VarisAddressType = {
 	/**
-	 * A street address in one of the state cities, which lie under no municipality.
+	 * A street address in one of the state cities.
+	 * Those cities lie under no municipality.
 	 */
 	StateCityStreet: "state-city-street",
 	/**
@@ -240,15 +241,15 @@ export const VarisAddressType = {
 	 */
 	VillageStreet: "village-street",
 	/**
-	 * A named house in a city, on no street.
+	 * A house with its own name in a city, on no street.
 	 */
 	CityNamedHouse: "city-named-house",
 	/**
-	 * A named house in a village.
+	 * A house with its own name in a village.
 	 */
 	VillageNamedHouse: "village-named-house",
 	/**
-	 * A named house in a parish, in no village.
+	 * A house with its own name in a parish, in no village.
 	 */
 	ParishNamedHouse: "parish-named-house",
 } as const
@@ -419,8 +420,8 @@ export function readVarisBuilding(record: VarisRecord, places: VarisPlaces): Var
 /**
  * Streams one table's records, each value as stored.
  *
- * Trimming is off because `STD` keeps a stored trailing space inside a building
- * name's quotes, and the composition check compares the two.
+ * The reader turns trimming off because `STD` keeps a stored trailing space inside a building name's quotes.
+ * The composition check compares the two.
  */
 export function readVarisTable(path: PathBuilderLike): AsyncIterable<VarisRecord> {
 	return CSVSpliterator.fromAsync(path, { normalizeKeys: false, trim: false }) as AsyncIterable<VarisRecord>

package/lib/lv/tools/fetch/varis.ts

@@ -16,7 +16,7 @@
 
 import { APIClient } from "@mailwoman/core/api"
 import { ByteFormatter } from "@mailwoman/core/fs/formatters"
-import { tryStat } from "@mailwoman/core/fs/readers"
+import { tryStat } from "@mailwoman/core/fs/readers/stat"
 import { makeDirectories } from "@mailwoman/core/fs/writers"
 import { sha256File } from "@mailwoman/core/hash"
 import { PathBuilder, type PathBuilderLike } from "path-ts"
@@ -89,7 +89,8 @@ export interface DownloadVarisOptions {
 	outputDir: PathBuilderLike
 	/**
 	 * The tables to download.
-	 * Defaults to every table the adapter reads.
+	 *
+	 * @defaultValue every table the adapter reads.
 	 */
 	tables?: readonly VarisTable[]
 	force?: boolean

package/lib/nl/adapters/kadaster/adapter.ts

@@ -8,13 +8,13 @@
  * Kadaster serves the whole country in one file. The ATOM service document at
  * `https://service.pdok.nl/kadaster/ad/atom/adressen_inspire_geharmoniseerd.xml`, 2,247 bytes, holds
  * one entry, and its `rel="alternate"` link is
- * `https://service.pdok.nl/kadaster/ad/atom/downloads/addresses.gml.gz`, 819,465,603 bytes, which
+ * `https://service.pdok.nl/kadaster/ad/atom/downloads/addresses.gml.gz`, 819,465,603 bytes. It
  * inflates to 29,677,448,685 bytes of GML holding 10,066,060 address features. The sibling feed URL
  * the entry's own `<id>` names answers HTTP 404, so the download link is the only live one.
  *
  * The size decides the shape of the reader. The document is never buffered: the adapter opens the
- * local `.gml.gz`, inflates it as a byte stream and takes one feature subtree at a time, and it keeps
- * a value rather than a subtree for each feature an address references, so the index it holds is
+ * local `.gml.gz`, inflates it as a byte stream and takes one feature subtree at a time. Each feature
+ * an address references contributes a value rather than its subtree, so the index is
  * bounded by a string per street and per place name rather than by the document.
  *
  * Four things separate this publisher from the Czech one the shared primitives were first written
@@ -45,8 +45,8 @@
  *
  * So the extension joins the number with no separator and the second extension follows a hyphen.
  * 305,542 of 345,309 addresses in the prefix write an `addressNumberExtension` that is present and
- * empty, spelled `<ad:designator/>`. That states an address with no extension, which is a different
- * condition from void.
+ * empty, spelled `<ad:designator/>`. That states an address with no extension. That condition differs
+ * from void.
  *
  * The place name comes from `ad:AddressAreaName`, the BAG *woonplaats*. The prefix holds exactly one
  * `ad:AdminUnitName` feature and it is the country, `Nederland` at `1stOrder`, so this feed publishes
@@ -60,8 +60,8 @@
  * against 2,622 dot-form ids and 0 hyphen-form ids. The same element on an `ad:AddressAreaName` uses
  * the dot form and resolves. A reader walking `ThoroughfareName → situatedWithin → AddressAreaName`
  * would therefore read an empty locality for every street and report no failure. So the adapter reads
- * the street and the place from the address's own `ad:component` references, which use the dot form,
- * and never follows `ad:situatedWithin`. Every reference it does follow raises when it resolves to no
+ * the street and the place from the address's own `ad:component` references, and those use the dot
+ * form. It never follows `ad:situatedWithin`. Every reference it does follow raises when it resolves to no
  * feature, so the hyphen form reaching an `ad:component` would be reported rather than dropped.
  *
  * Unlike Czechia, this publisher offers no string to check a whole rendered line against.
@@ -70,7 +70,7 @@
  *
  * Kadaster states one license and states it as a URL. Both `rights` elements of the ATOM service
  * document read `https://creativecommons.org/publicdomain/zero/1.0/deed.nl`, the Dutch deed page for
- * CC0 1.0 Universal, which the address-source register elected with `spdx` `CC0-1.0`. CC0 reserves no
+ * CC0 1.0 Universal. The address-source register elected it with `spdx` `CC0-1.0`. CC0 reserves no
  * act, so every row records that identifier and no attribution clause is owed, although crediting
  * Kadaster stays good practice.
  *
@@ -161,19 +161,20 @@ const COMPONENT_TYPES = ["ad:ThoroughfareName", "ad:AddressAreaName", "ad:AdminU
  */
 interface ReferencedValue {
 	/**
-	 * The feature's element name, which decides where its value goes.
+	 * The feature's element name.
+	 * That decides where its value goes.
 	 */
 	readonly type: string
 
 	/**
-	 * The street name or place name the feature states, absent when the feature states none.
+	 * The street name or place name the feature states, null when the feature states none.
 	 */
-	readonly name?: string
+	readonly name: string | null
 
 	/**
 	 * The administrative level an `ad:AdminUnitName` states, such as `1stOrder`.
 	 */
-	readonly level?: string
+	readonly level: string | null
 }
 
 /**
@@ -181,29 +182,29 @@ interface ReferencedValue {
  */
 function referencedValue(feature: MarkupElement): ReferencedValue {
 	if (feature.name === "ad:ThoroughfareName") {
-		return { type: feature.name, name: thoroughfareName(feature) }
+		return { type: feature.name, name: thoroughfareName(feature), level: null }
 	}
 
 	if (feature.name === "ad:AdminUnitName") {
 		return { type: feature.name, name: placeName(feature), level: adminUnitLevel(feature) }
 	}
 
-	return { type: feature.name, name: placeName(feature) }
+	return { type: feature.name, name: placeName(feature), level: null }
 }
 
 /**
  * The house number as Kadaster writes it in BAG's `huis_nlt`.
  *
- * The letter joins the number directly and the addition follows a hyphen,
- * which the table in this module's header reads off three records matched against
+ * The letter joins the number directly and the addition follows a hyphen.
+ * The table in this module's header reads that off three records matched against
  * the Locatieserver by their `nummeraanduiding` id.
  *
- * @returns The joined number, or undefined when the publisher states no `addressNumber`.
+ * @returns The joined number, or null when the publisher states no `addressNumber`.
  */
-export function dutchHouseNumber(byType: ReadonlyMap<string, readonly string[]>): string | undefined {
+export function dutchHouseNumber(byType: ReadonlyMap<string, readonly string[]>): string | null {
 	const number = designator(byType, "addressNumber")
 
-	if (!number) return undefined
+	if (!number) return null
 
 	const letter = designator(byType, "addressNumberExtension") ?? ""
 	const addition = designator(byType, "addressNumber2ndExtension") ?? ""
@@ -240,8 +241,7 @@ export function createNLKadasterAdapter(): CorpusAdapter {
 				for await (const row of streamInspireRows<ReferencedValue>({
 					chunks: documentChunks(documentPath),
 					componentElements: COMPONENT_TYPES,
-					// One string per feature rather than its subtree, which holds 300,318 strings
-					// instead of 300,318 trees.
+					// One string per feature rather than its subtree.
 					index: referencedValue,
 					compose: (address, referenced, final) => composeRow(address, referenced, { final }),
 					limit: opts.limit === undefined ? undefined : opts.limit - emitted,
@@ -257,7 +257,7 @@ export function createNLKadasterAdapter(): CorpusAdapter {
 }
 
 /**
- * One address's row, `undefined` when it holds too little to render, or `"deferred"`
+ * One address's row, `null` when it holds too little to render, or `"deferred"`
  * when a reference it states is not indexed yet.
  *
  * With `final` set the document has ended, so an unresolved reference is a value the reader
@@ -267,16 +267,16 @@ function composeRow(
 	address: MarkupElement,
 	referenced: ReadonlyMap<string, ReferencedValue>,
 	options: { final?: boolean } = {}
-): CanonicalRow | undefined | "deferred" {
-	const addressID = address.attributes["gml:id"]?.trim()
+): CanonicalRow | null | "deferred" {
+	const addressID = address.attributes["gml:id"]?.trim() ?? null
 	const voided = voidDesignatorTypes(address)
 
 	for (const type of ["addressNumber", "postalDeliveryIdentifier"]) {
 		if (voided.has(type)) throw new VoidDesignatorError(NL_KADASTER_ADAPTER_ID, addressID, type)
 	}
 
-	let street: string | undefined
-	let locality: string | undefined
+	let street: string | null = null
+	let locality: string | null = null
 
 	for (const href of componentHrefs(address)) {
 		const key = componentJoinKey(href)
@@ -299,13 +299,13 @@ function composeRow(
 		// reads `1stOrder` while the reference's position states no level at all.
 	}
 
-	if (!locality) return undefined
+	if (!locality) return null
 
 	const byType = designatorsByType(address)
 	const house = dutchHouseNumber(byType)
 	const postcode = designator(byType, "postalDeliveryIdentifier")
 
-	if (!street && !postcode) return undefined
+	if (!street && !postcode) return null
 
 	const components: CanonicalRow["components"] = {}
 
@@ -325,7 +325,7 @@ function composeRow(
 
 	const rendered = formatAddressRow(components, "NL", { singleLine: true })
 
-	if (!rendered) return undefined
+	if (!rendered) return null
 
 	const { raw, components: aligned } = rendered
 

package/lib/nl/tools/fetch/kadaster.ts

@@ -33,7 +33,7 @@
 
 import { APIClient, assertNoOGCServiceException } from "@mailwoman/core/api"
 import { ByteFormatter } from "@mailwoman/core/fs/formatters"
-import { tryStat } from "@mailwoman/core/fs/readers"
+import { tryStat } from "@mailwoman/core/fs/readers/stat"
 import { makeDirectories } from "@mailwoman/core/fs/writers"
 import { sha256File } from "@mailwoman/core/hash"
 import { PathBuilder, type PathBuilderLike } from "path-ts"
@@ -44,12 +44,14 @@ import type { BaseFetchOptions, FetchSummary, SourceManifest } from "#tools/fetc
 import { downloadToFile, readManifest, writeManifest } from "#tools/fetch/download"
 
 /**
- * The ATOM download service for the theme, which holds the country's one entry.
+ * The ATOM download service for the theme.
+ * It holds the country's one entry.
  */
 export const NL_KADASTER_FEED_URL = "https://service.pdok.nl/kadaster/ad/atom/adressen_inspire_geharmoniseerd.xml"
 
 /**
- * The name the download is written under, which is what the adapter's `inputPath` states.
+ * The name the download is written under.
+ * The adapter's `inputPath` states this name.
  *
  * The publisher's own name for the file.
  * The adapter reads a `.gml.gz` by inflating it, so the suffix is load-bearing.
@@ -59,8 +61,8 @@ export const NL_KADASTER_DOWNLOAD_FILENAME = "addresses.gml.gz"
 /**
  * The attribution recorded in the manifest.
  *
- * CC0 1.0 reserves no act and owes no attribution clause, so this is the credit the
- * repository chooses to carry rather than a condition of the grant.
+ * CC0 1.0 reserves no act and owes no attribution clause.
+ * This attribution is a credit the repository chooses, rather than a condition of the grant.
  */
 export const NL_KADASTER_ATTRIBUTION = "Kadaster"
 
@@ -70,8 +72,9 @@ const SLUG = NL_KADASTER_ADAPTER_ID
  * What one run recorded.
  *
  * `feed_updated` is the entry's own `<updated>`.
- * A later run downloads again when that value changes, which is what the ATOM
- * pattern offers in place of an HTTP validator.
+ * A later run downloads again when that value changes.
+ *
+ * That is the freshness signal the ATOM feed offers in place of an HTTP validator.
  *
  * `rights` is the license URL the feed states, recorded so a change of terms is
  * visible in the artifact rather than only in the register.
@@ -108,7 +111,7 @@ export interface NLKadasterPublication {
 	 * The entry's own `<updated>`, or `null` where the feed states none.
 	 *
 	 * `updated` sits on the Atom entry as well as on the feed, and this reads
-	 * the entry that carried the data link.
+	 * the entry that held the data link.
 	 * The feed reported `2026-09-02T11:45:47Z` when this reader was written.
 	 */
 	feedUpdated: string | null
@@ -178,17 +181,18 @@ export async function readNLKadasterPublication(
  * Whether the file on disk is the one the feed currently offers.
  *
  * A skip requires the feed to state an `<updated>` value.
- * Where it states none, both sides read `null` and an equality test would hold,
- * which would keep a download of unknown age for as long as the feed stayed silent.
+ * Where it states none, both sides read `null` and an equality test would hold.
+ *
+ * A skip there would keep a download of unknown age for as long as the feed stayed silent.
  *
- * Downloading 782 MiB again is the slower error and the recoverable one.
+ * A second 782 MiB download is the slower error and the recoverable one.
  */
 export function nlKadasterPublicationIsRecorded(
 	recorded: NLKadasterManifest,
 	bytesOnDisk: number,
 	publication: NLKadasterPublication
 ): boolean {
-	if (publication.feedUpdated === null) return false
+	if (!publication.feedUpdated) return false
 
 	return recorded.feed_updated === publication.feedUpdated && recorded.bytes === bytesOnDisk
 }

package/lib/no/adapters/matrikkelen/adapter.ts

@@ -6,7 +6,7 @@
  * `matrikkelen`: Kartverket's `Matrikkelen - Adresse` CSV adapter, covering Norway and Svalbard.
  *
  * Input is a semicolon-separated CSV from Geonorge, published per area beside a whole-country
- * extract. Both carry the same 46 columns, so one reader serves either. The adapter reads
+ * extract. Both have the same 46 columns, so one reader serves either. The adapter reads
  * `adressenavn` as the street, `nummer` and `bokstav` as the house number, and `postnummer` with
  * `poststed` as the postcode and its postal place.
  *
@@ -55,8 +55,9 @@ export const MATRIKKELEN_COUNTRIES: readonly string[] = ["NO", "SJ"]
  * The subset of the 46 columns the adapter consults.
  *
  * The explicit shape catches a column rename early.
- * The first column's name carries a byte-order mark in the published file, and the
- * adapter reads `adresseId` instead, so no field here depends on that spelling.
+ * The first column's name has a byte-order mark in the published file.
+ *
+ * The adapter reads `adresseId` instead, so no field here depends on that spelling.
  */
 interface MatrikkelenRow {
 	kommunenummer: string
@@ -111,8 +112,8 @@ export function createMatrikkelenAdapter(): CorpusAdapter {
 
 					// A `matrikkeladresse` addresses a cadastral unit rather than a street, so its
 					// `adresseTekst` reads as a farm name and a holding number, such as `Øvrabø, 124/1`.
-					// It carries no street to align, and the mainland file holds 34,522 of
-					// them against 2,568,832 `vegadresse` rows.
+					// It has no street to align, and the mainland file holds 34,522 of them
+					// against 2,568,832 `vegadresse` rows.
 					if ((record.adressetype ?? "").trim() !== "vegadresse") {
 						cadastral += 1