@mailwoman/corpus 10.1.0 → 10.2.1

package/lib/it/adapters/anac/adapter.ts

@@ -4,41 +4,41 @@
  * @author Teffen Ellis, et al.
  *
  * `it-anac`: the OCDS release Autorità Nazionale Anticorruzione publishes for Italy's National
- * Database of Public Contracts, read for the addresses of the public bodies named on each contract.
+ * Database of Public Contracts, read for the addresses of the public bodies that appear on each contract.
  *
  * Input is the publisher's own JSON Lines: one OCDS release per line, as
  * `https://data.open-contracting.org/en/publication/117/download?name=<year>.jsonl.gz` serves it
- * once decompressed. A release carries a `parties` array, and each party holds a `roles` list, a
+ * once decompressed. A release has a `parties` array, and each party holds a `roles` list, a
  * `name`, an `identifier` and an `address` whose four fields are `locality`, `postalCode`,
  * `countryName` and `streetAddress`. The adapter streams the file through `JSONSpliterator`, so a
  * year's release never sits in memory whole. `opts.inputPath` is one `.jsonl` edition or a directory
- * holding several, which is what `fetchITANAC` writes.
+ * holding several. `fetchITANAC` writes the directory form.
  *
  * ## Which roles the adapter reads, and why those two
  *
- * The register's `addressRoles` for `it-procurement-grants-1` names exactly two fields,
+ * The register's `addressRoles` for `it-procurement-grants-1` records exactly two fields,
  * `parties[roles=buyer].address` and `parties[roles=payer].address`.
- * Those two are the only address fields the release carries. Measured over the whole 2025 edition, 9,405 releases and
+ * Those two are the only address fields in the release. Measured over the whole 2025 edition, 9,405 releases and
  * 29,823 party objects in three roles: a `supplier` party holds no `address` key at all on 11,075 of
  * 11,075, a `buyer` holds one on 9,381 of 9,381, and a `payer` on 9,359 of 9,367. So every address
  * in this release belongs to a contracting authority or to the office that pays.
  * Both of those are Italian public entities, and a contracting counterparty holds none.
  *
- * That is what makes this source admissible under the policy that a corpus carries the addresses of
+ * That is what makes this source admissible under the policy that admits the addresses of
  * organizations and no address of an identifiable natural person. The two admitted roles are held by
  * public bodies, and the one role whose parties can be sole traders publishes no address.
  * {@linkcode readANACParty} still applies a name check and refuses a party whose name takes the
- * `Surname, Firstname` form, because a later edition could carry one. On the 2025 edition the check
+ * `Surname, Firstname` form, because a later edition could add one. On the 2025 edition the check
  * refuses no party: 0 of the 18,740 address-bearing buyer and payer parties take that form, while 56
  * hold a comma inside an organization name — `PARCO NAZIONALE DEL CILENTO, VALLO DI DIANO E
- * ALBURNI` and `SETTORE PATRIMONIO, AMBIENTE E LAVORI PUBBLICI` among them — which is why the check
- * requires a single word on each side of the comma rather than a comma alone.
+ * ALBURNI` and `SETTORE PATRIMONIO, AMBIENTE E LAVORI PUBBLICI` among them. The check therefore
+ * requires one word on each side of the comma rather than any comma.
  *
  * ## The street line
  *
- * Italy writes the house number after the street name and joins the two with a space, which is what
- * `STREET_ORDERS` records as `number-last` and what `COMMA_JOINED_STREET_COUNTRIES` records by
- * leaving `IT` out. {@linkcode splitTrailingStreetLine} performs the split. Three Italian
+ * Italy writes the house number after the street name, joined by a space. `STREET_ORDERS` records
+ * that order as `number-last`. `COMMA_JOINED_STREET_COUNTRIES` records it by leaving `IT` out.
+ * {@linkcode splitTrailingStreetLine} performs the split. Three Italian
  * conventions are normalized before it runs, each measured over the 2025 edition's 11,930
  * non-placeholder street lines:
  *
@@ -52,23 +52,24 @@
  * 3. **`senza numero`.** 182 lines end `SNC` or `SN`, which states that the premise has no civic
  *    number, so the tail is dropped and no `house_number` is composed from it.
  *
- * A kilometer point is not a house number. `S.S. 7 APPIA KM 671` names a point on a state highway,
- * so a number preceded by `KM` is left in the street line, which then refuses the row under the rule
- * below.
+ * A number preceded by `KM` names a point on a state highway rather than a house number, as
+ * `S.S. 7 APPIA KM 671` does. That number stays in the street line, and the rule below refuses the
+ * row.
  *
  * **A street line holding a digit the split could not place refuses the row.**
  * {@linkcode ANACRefusal.StreetNumberUnplaced} covers 194 of those 11,930 lines, where the publisher
  * appends a qualifier after the number: `VIA CIRCONVALLAZIONE, 1 PARCO IDROSCALO`, `VIA FELTRE 57
- * 32100 BELLUNO (BL)`, `VIA SAN SECONDO 29 BIS`. Emitting them would label a civic number as part of
- * a street name. A line with no digit at all is emitted as a street with no number, which is the
- * ordinary `PIAZZA CASTELLO` case and 1,416 of the 11,930. The remaining 10,320 carry a number.
+ * 32100 BELLUNO (BL)`, `VIA SAN SECONDO 29 BIS`. The adapter refuses that line, because emitting it
+ * would label a civic number as part of a street name. A line with no digit at all is emitted as a
+ * street with no number. `PIAZZA CASTELLO` is the ordinary case, and 1,416 of the 11,930 lines take
+ * it. The remaining 10,320 state a number.
  *
  * Two limits of the split are the publisher's own ambiguity rather than this reader's. `PIAZZA
  * UMBERTO 1` is Umberto I's square and reads identically to civic number 1, and the release gives no
  * field that separates them. A number written twice, as `CORSO ITALIA 55 55` and `VIALE DEI PIANETI 1
- * 1`, leaves the first copy in the street name. Together with Italy's date-named streets — `VIA 4
- * NOVEMBRE`, `PIAZZA 1 MAGGIO`, `VIA 2 AGOSTO 1980` — 93 of the 10,320 numbered lines keep a digit
- * inside the street, and most of those digits belong to the street's name.
+ * 1`, leaves the first copy in the street name. Together with streets that take a date for a name —
+ * `VIA 4 NOVEMBRE`, `PIAZZA 1 MAGGIO`, `VIA 2 AGOSTO 1980` — 93 of the 10,320 numbered lines keep a
+ * digit inside the street, and most of those digits belong to the street's name.
  *
  * ## What the split was checked against
  *
@@ -82,15 +83,15 @@
  * published token. Which side of the split each token belongs on is the part no field of this
  * publisher's confirms.
  *
- * Every other component is a published value copied unchanged, which the same pass checked: 0 of the
- * 18,473 rows the 2025 edition admits carry a `locality`, `postcode` or `venue` that differs from the
+ * Every other component is a published value copied unchanged. The same pass checked this: 0 of the
+ * 18,473 rows the 2025 edition admits show a `locality`, `postcode` or `venue` that differs from the
  * field it came from.
  *
  * ## Placeholders and the postcode
  *
  * The publisher writes the literal `N.A.` where it holds no value: 476 postcodes, 6 localities and 6
  * street lines on the 2025 edition. {@linkcode isPlaceholderValue} treats it as absent, so no row
- * carries `N.A.` as a postcode.
+ * records `N.A.` as a postcode.
  *
  * An Italian CAP is five digits. A postcode that is neither a placeholder nor five digits is not a
  * CAP, and the row is refused rather than stripped of the field: the one such value on the 2025
@@ -102,14 +103,14 @@
  * ## Identity and license
  *
  * The row id is content-addressed over the aligned components. The publisher's party identifier
- * cannot serve: a buyer's `IT-CF` fiscal code carries more than one address on 17 of 3,119 distinct
+ * cannot serve: a buyer's `IT-CF` fiscal code covers more than one address on 17 of 3,119 distinct
  * codes, and one address recurs across hundreds of releases, so the identifier identifies the
  * organization rather than the address.
  *
- * The OCP Data Registry publishes this release under CC BY 4.0, which the address-source register
- * elected on 2026-09-30 with `spdx` `CC-BY-4.0`. CC BY requires credit, a link to the license and a
- * statement that changes were made, so every row records the license and
- * {@linkcode IT_ANAC_ATTRIBUTION} is the credit the model card carries.
+ * The OCP Data Registry publishes this release under CC BY 4.0. The address-source register elected
+ * that license on 2026-09-30 with `spdx` `CC-BY-4.0`. CC BY requires credit, a link to the license
+ * and a statement that changes were made. Every row records the license, and
+ * {@linkcode IT_ANAC_ATTRIBUTION} is the credit the model card records.
  *
  * The adapter honors `opts.limit`, `opts.signal` and `opts.country`.
  */
@@ -148,15 +149,16 @@ export const IT_ANAC_COUNTRIES: readonly string[] = ["IT"]
 export const IT_ANAC_LICENSE = "CC-BY-4.0"
 
 /**
- * The credit CC BY 4.0 obliges, which the model card carries beside the license
- * and a statement that the data was changed.
+ * The credit CC BY 4.0 obliges.
+ *
+ * The model card records it beside the license and a statement that the data was changed.
  */
 export const IT_ANAC_ATTRIBUTION = "Autorità Nazionale Anticorruzione (ANAC), via the OCP Data Registry"
 
 /**
  * The two party roles the adapter reads.
  *
- * The register's `addressRoles` names these two fields alone.
+ * The register's `addressRoles` records exactly these two fields.
  * The `supplier` role is the one role whose parties are contracting counterparties
  * rather than public bodies.
  * That role publishes no `address` object.
@@ -172,12 +174,12 @@ export const IT_ANAC_PARTY_ROLES: readonly string[] = ["buyer", "payer"]
  */
 export const ANACRefusal = {
 	/**
-	 * The party holds a role other than `buyer` or `payer`, so its address is out
-	 * of scope even where it carries one.
+	 * The party holds a role other than `buyer` or `payer`, so its address is
+	 * out of scope even where one appears.
 	 */
 	RoleNotAdmitted: "role-not-admitted",
 	/**
-	 * The party carries no `address` object, or every field in it is empty or a placeholder.
+	 * The party has no `address` object, or every field in it is empty or a placeholder.
 	 */
 	AddressAbsent: "address-absent",
 	/**
@@ -205,10 +207,10 @@ export const ANACRefusal = {
 	 */
 	Unrenderable: "unrenderable",
 	/**
-	 * The rendered line carries one component, so it is a place name rather than an address.
+	 * The rendered line holds one component, so it is a place name rather than an address.
 	 *
-	 * A party whose name holds no letter, whose postcode is the publisher's placeholder
-	 * and whose street line is absent leaves the locality alone.
+	 * A party leaves only the locality when its name holds no letter, its postcode is
+	 * the publisher's placeholder and its street line is absent.
 	 */
 	ComponentsTooFew: "components-too-few",
 } as const
@@ -245,9 +247,9 @@ export interface ANACParty {
 /**
  * One line of the input: an OCDS release.
  *
- * The adapter reads `parties` alone.
- * A release also carries `tender`, `awards` and `contracts`, and no address
- * sits on any of them in this publication.
+ * The adapter reads only `parties`.
+ * A release also has `tender`, `awards` and `contracts`, and no address sits
+ * on any of them in this publication.
  */
 export interface ANACRelease {
 	ocid?: string
@@ -293,8 +295,9 @@ const CIVIC_MARKER = /(?<=^|[\s,])(?:n|nr|num|civ|civico)\s*\.?\s*(?=\d)/giu
 const SENZA_NUMERO = /[\s,]+(?:snc|sn)\.?$/iu
 
 /**
- * A number introduced by a kilometer marker, which points at a place on a highway
- * rather than at a premise on a street.
+ * A number introduced by a kilometer marker.
+ *
+ * Such a number points at a place on a highway rather than a premise on a street.
  */
 const KILOMETRE_POINT = /[\s,]+km\.?[\s,]*\d+(?:[.,]\d+)?$/iu
 
@@ -337,8 +340,8 @@ function fieldValue(value: string | null | undefined): string {
  * The street line with the three Italian conventions normalized away: a trailing copy
  * of the locality, a civic marker before the number, and a `senza numero` tail.
  *
- * `locality` is the publisher's own value for this party, which is what
- * authorizes removing the trailing copy.
+ * `locality` is the publisher's own value for this party.
+ * That value authorizes removing the trailing copy.
  * An empty string leaves the line as it is.
  */
 export function normalizeANACStreetLine(line: string, locality: string): string {
@@ -497,7 +500,9 @@ export function createITANACAdapter(): CorpusAdapter {
  * The registry serves one file per year beside an all-time `full.jsonl.gz`,
  * and `fetchITANAC` writes whichever editions a caller asked for into one directory,
  * so a build reading several years points at that directory.
- * The editions are read in sorted order, which puts the years in chronological order and `full` after them.
+ * The editions are read in sorted order.
+ *
+ * That puts the years in chronological order and `full` after them.
  *
  * A directory holding no edition raises rather than yielding zero rows, so a wrong path
  * reports itself instead of reading as a publisher with no contracts.

package/lib/it/tools/fetch/anac.ts

@@ -8,31 +8,29 @@
  * The Open Contracting Partnership's Data Registry serves publication 117 at
  * `https://data.open-contracting.org/en/publication/117/download?name=<edition>.jsonl.gz`, where an
  * edition is a year, `undated`, or `full` for every year in one file. Each file is JSON Lines, one
- * OCDS release per line, which is the shape `#it/adapters/anac/adapter` reads.
+ * OCDS release per line. That is the shape `#it/adapters/anac/adapter` reads.
  *
  * The acquisition belongs under a `tools/` root. `@mailwoman/corpus` is one of the
  * `TOOLING_PACKAGES` in `dependency-cruiser.config.mjs`, which keep their tooling under `lib/`, so
  * this module sits beside `#fi/tools/fetch/ryhti` rather than in an `sdk/` root the workspace does
  * not declare.
  *
- * Three measured properties of the host decide what this module does. Measured on 2026-10-02:
+ * Three host behaviors decide what this module does:
  *
  * 1. **The host honors `Range`.** It answers `accept-ranges: bytes`, so an interrupted transfer
- *    resumes through {@linkcode resumableDownload} rather than restarting. That matters for the
- *    `full` edition, whose `content-length` was 183,974,254.
- * 2. **An edition's length and modification time are both served by `HEAD`.** `full.jsonl.gz`
- *    answered `last-modified` `Sat, 19 Sep 2026 03:30:49 GMT` and `2025.jsonl.gz` answered `Sat, 19
- *    Sep 2026 03:31:23 GMT` with `content-length` 3,963,957. The re-run check compares the pair
- *    against the manifest, which costs one small request per edition instead of the body.
+ *    resumes through {@linkcode resumableDownload} rather than restarting. That matters most for
+ *    the `full` edition.
+ * 2. **An edition's length and modification time are both served by `HEAD`.** The re-run check
+ *    compares the pair against the manifest, so one small request per edition replaces the body.
  * 3. **This module moves bytes and decodes none of them.** The compressed body is streamed to disk
  *    and then decompressed stream to stream, so no chunk boundary is interpreted as a character
- *    boundary. ANAC's data carries accented Italian place names, and a `chunk.toString("utf8")` per
- *    gzip chunk writes U+FFFD at every boundary that splits a multi-byte character.
+ *    boundary. ANAC's data holds accented Italian place names, and a `chunk.toString("utf8")` per
+ *    gzip chunk would write U+FFFD at every split multi-byte character.
  *
- * ANAC updates the publication monthly, on the second of the month, which is why the current year's
+ * ANAC updates the publication monthly, on the second of the month. The current year's
  * edition is re-fetched on a `HEAD` disagreement rather than treated as final.
  *
- * The registry publishes this release under CC BY 4.0, which the address-source register elected.
+ * The registry publishes this release under CC BY 4.0. The address-source register elected it.
  * The manifest records the license and the attribution, and the adapter records the license on every
  * row.
  */
@@ -40,7 +38,7 @@
 import { APIClient } from "@mailwoman/core/api"
 import { gunzipChunks } from "@mailwoman/core/fs/compression"
 import { ByteFormatter } from "@mailwoman/core/fs/formatters"
-import { tryStat } from "@mailwoman/core/fs/readers"
+import { tryStat } from "@mailwoman/core/fs/readers/stat"
 import { openReadStream, openWriteStream, pipeline, Readable } from "@mailwoman/core/fs/streams"
 import { makeDirectories, removePathIfPresent } from "@mailwoman/core/fs/writers"
 import { sha256File } from "@mailwoman/core/hash"
@@ -54,10 +52,8 @@ import { loadCollectionFiles, resumableDownload, writeManifest } from "#tools/fe
  * The publication the registry serves this release under.
  *
  * Italy has four publications on the registry and id 117 is ANAC's.
- * Id 87 is OpenTender's Italian publication.
- *
- * It runs to March 2024 and comes from a different body.
- * Reading the country alone would take the wrong publication.
+ * Id 87 is OpenTender's Italian publication, so a reader that filters by country
+ * would take the wrong publication.
  */
 export const IT_ANAC_PUBLICATION_ID = 117
 
@@ -69,14 +65,15 @@ export function anacEditionURL(edition: string): string {
 }
 
 /**
- * The directory the editions are written under, which is the adapter's `inputPath`.
+ * The directory the editions are written under, the adapter's `inputPath`.
  */
 const SLUG = IT_ANAC_ADAPTER_ID
 
 /**
  * The edition fetched when a caller names none.
  *
- * `full` is every year in one file, which is what a corpus build reads.
+ * `full` is every year in one file.
+ * A corpus build reads that edition.
  * A caller measuring one year names that year instead.
  */
 export const IT_ANAC_DEFAULT_EDITIONS: readonly string[] = ["full"]
@@ -125,7 +122,7 @@ export async function readANACEditionHead(client: Pick<APIClient, "fetch">, edit
 
 	return {
 		lastModified: headers?.["last-modified"] ?? null,
-		contentLength: length !== undefined && /^\d+$/u.test(length) ? Number(length) : null,
+		contentLength: length && /^\d+$/u.test(length) ? Number(length) : null,
 		contentType: headers?.["content-type"] ?? null,
 	}
 }
@@ -138,7 +135,7 @@ export interface DownloadANACOptions {
 	outputDir: PathBuilderLike
 	/**
 	 * Which editions to fetch: a year, `undated`, or `full`.
-	 * Defaults to {@linkcode IT_ANAC_DEFAULT_EDITIONS}.
+	 * @defaultValue {@linkcode IT_ANAC_DEFAULT_EDITIONS}
 	 */
 	editions?: readonly string[]
 	/**
@@ -187,7 +184,7 @@ export function itANACInputPath(outRoot: BaseFetchOptions["outRoot"]): PathBuild
  * letting {@linkcode downloadITANAC} reach the host to find out which branch it took.
  */
 export async function isANACEditionCurrent(
-	recorded: ANACEditionManifest | undefined,
+	recorded: ANACEditionManifest | null,
 	head: ANACEditionHead,
 	path: PathBuilderLike,
 	verifyDigest: boolean
@@ -195,9 +192,9 @@ export async function isANACEditionCurrent(
 	if (!recorded) return false
 
 	// A host that states neither cannot be compared against, so the edition is downloaded.
-	if (head.lastModified === null && head.contentLength === null) return false
+	if (!head.lastModified && head.contentLength === null) return false
 
-	if (head.lastModified !== null && head.lastModified !== recorded.last_modified) return false
+	if (head.lastModified && head.lastModified !== recorded.last_modified) return false
 
 	if (head.contentLength !== null && head.contentLength !== recorded.compressed_bytes) return false
 
@@ -259,7 +256,7 @@ export async function downloadITANAC(
 
 		const current =
 			!options.force &&
-			(await isANACEditionCurrent(recorded.get(filename), head, editionPath, options.verifyDigest ?? false))
+			(await isANACEditionCurrent(recorded.get(filename) ?? null, head, editionPath, options.verifyDigest ?? false))
 
 		if (current) {
 			report?.(`  ✓ ${edition} already current — no download.`)

package/lib/jp/adapters/wof-admin/adapter.ts

@@ -68,11 +68,7 @@ interface PlaceRow {
  * That analogue stores the nearest ancestor's name for each tag.
  * This function receives one `PlaceRow` per level and reads the chain directly.
  */
-function chainOf(
-	byID: Map<number, PlaceRow>,
-	resolve: (id: number) => PlaceRow | undefined,
-	startID: number
-): PlaceRow[] {
+function chainOf(byID: Map<number, PlaceRow>, resolve: (id: number) => PlaceRow | null, startID: number): PlaceRow[] {
 	const out: PlaceRow[] = []
 	let id = startID
 
@@ -177,7 +173,7 @@ export function createWOFAdminJpAdapter(): CorpusAdapter {
 
 			const outsideStmt = db.prepare(`SELECT id, name, placetype, parent_id, country FROM spr WHERE id = ?`)
 
-			const resolveOutside = (id: number): PlaceRow | undefined => {
+			const resolveOutside = (id: number): PlaceRow | null => {
 				const row = getRow<PlaceRow>(outsideStmt, id)
 
 				if (row) {

package/lib/jp/tools/fetch/houjin.ts

@@ -41,14 +41,14 @@ export type FetchHoujinJPOptions = BaseFetchOptions
 /**
  * The nationwide row of the "CSV形式・Unicode" table stores the file number in its `doDownload(N)` handler.
  */
-function nationwideUnicodeFileNumber(html: string): string | undefined {
+function nationwideUnicodeFileNumber(html: string): string | null {
 	const start = html.indexOf('id="csv-unicode"')
 
-	if (start === -1) return undefined
+	if (start === -1) return null
 	const section = html.slice(start, html.indexOf('id="xml-unicode"', start))
 	const row = /全国[\s\S]{0,600}?doDownload\((\d+)\)/.exec(section)
 
-	return row?.[1]
+	return row?.[1] ?? null
 }
 
 export async function fetchHoujinJP(

package/lib/kr/adapters/localdata/permit-rows.ts

@@ -73,7 +73,7 @@ function firstColumn(row: Record<string, string | undefined>, ...names: readonly
 	for (const name of names) {
 		const value = row[name]
 
-		if (value !== undefined && value !== null) return String(value).trim()
+		if (value) return String(value).trim()
 	}
 
 	return ""

package/lib/kr/tools/fetch/juso.ts

@@ -66,7 +66,7 @@ export interface FetchJusoKROptions extends BaseFetchOptions {
 	/**
 	 * The month to fetch as `yyyymm`.
 	 *
-	 * Defaults to the latest month the portal lists as present.
+	 * @defaultValue the latest month the portal lists as present.
 	 */
 	month?: string
 }

package/lib/kr/tools/fetch/localdata.ts

@@ -26,7 +26,7 @@
  */
 
 import { BYTES_PER_KIB } from "@mailwoman/core/fs/formatters"
-import { pathExists } from "@mailwoman/core/fs/readers"
+import { pathExists } from "@mailwoman/core/fs/readers/stat"
 import { makeDirectories } from "@mailwoman/core/fs/writers"
 import { sha256File } from "@mailwoman/core/hash"
 import { sleep } from "@mailwoman/core/utils/sleep"
@@ -46,7 +46,7 @@ export interface FetchLocaldataKROptions extends BaseFetchOptions {
 	/**
 	 * Category slugs to fetch (the path segment of `/file/<slug>/info`).
 	 *
-	 * Defaults to every category the portal lists.
+	 * @defaultValue every category the portal lists.
 	 */
 	categories?: string[]
 }

package/lib/lu/adapters/bd-adresses/adapter.ts

@@ -19,11 +19,11 @@
  * `CC0-1.0` for `lu-property-building-1` on that statement, so the adapter records that license on
  * every row.
  *
- * Luxembourg writes the house number before the street, which `STREET_ORDERS` records as
+ * Luxembourg writes the house number before the street. `STREET_ORDERS` records that order as
  * `number-first`, and `COMMA_JOINED_STREET_COUNTRIES` does not list it. `formatAddressRow` therefore
  * renders `20 Kaesfurterstrooss, L-9755 Hupperdange`.
  *
- * ## The file carries one street name, in no single language
+ * ## The file holds one street name, in no single language
  *
  * Luxembourg is trilingual, and the CSV declares one street column.
  * There is no `rue_fr`, `rue_de` or `rue_lb` to choose between, so the adapter emits `rue` as the
@@ -38,7 +38,7 @@
  * No column marks a row's language, so `locale` reads `und-LU`.
  * `und` is BCP-47's undetermined language subtag, and the repository already stores it in
  * `#recipes/bare/country` and `#tools/postcode-triples`.
- * Labeling every row `fr-LU` or `lb-LU` would assert a language for a name the publisher did not
+ * A `fr-LU` or `lb-LU` label would assert a language for a name the publisher did not
  * tag.
  *
  * ## The number comes from `numero`, and never from the street line
@@ -46,10 +46,10 @@
  * `rue` and `numero` are separate columns and the publisher never composes them, so neither
  * `splitStreetLine` nor `composeHouseNumber` applies here: there is no line to split and no second
  * column to join.
- * Splitting the street would also be wrong in both directions.
+ * A street split would also be wrong in both directions.
  * 175 `rue` values end in a digit, among them `Route Nationale 1`, `Rue du 9 août 2019` and
  * `Cité des Sacrifiés 1940-1945`.
- * `numero` already carries its own suffix as one token: 162,273 rows hold bare digits, 17,087 a
+ * `numero` already holds its own suffix as one token: 162,273 rows hold bare digits, 17,087 a
  * trailing letter such as `12A`, 239 a hyphenated range such as `22-26`, eight the word `BIS` or
  * `bis`, and 15 are empty.
  *
@@ -59,15 +59,15 @@
  * The file publishes no preformatted address line, so a rendered single line has no publisher-side
  * counterpart to be asserted against.
  *
- * ## Reading the file needs a quote-aware parser
+ * ## The file needs a quote-aware parser
  *
  * 22 rows RFC 4180-quote `rue` and double its interior quotes:
  * `"Cité ""Pënscherbierg""";3;Wilwerwiltz;…`.
- * Those rows carry no semicolon inside the quotes, so a naive split on `;` still yields 13 fields
+ * Those rows hold no semicolon inside the quotes, so a naive split on `;` still yields 13 fields
  * and passes a field-count check while handing the street to the corpus as
  * `"Cité ""Pënscherbierg"""`.
  * `CSVSpliterator` unescapes it to `Cité "Pënscherbierg"`.
- * The same edition carries 0 fields with an embedded newline and 0 carriage returns in the whole
+ * The same edition holds 0 fields with an embedded newline and 0 carriage returns in the whole
  * file.
  *
  * The file opens with a UTF-8 byte-order mark, the three bytes `EF BB BF`, which the reader strips.
@@ -102,7 +102,7 @@ export const BD_ADRESSES_DEFAULT_LICENSE = "CC0-1.0"
  * Every jurisdiction this adapter emits, checked against a caller's `--country`.
  *
  * BD-Adresses is one national file and Luxembourg has no dependency, so this is a single entry
- * where `ban`, `matrikkelen` and `ryhti` each carry more than one.
+ * where `ban`, `matrikkelen` and `ryhti` each hold more than one.
  */
 export const BD_ADRESSES_COUNTRIES: readonly string[] = ["LU"]
 
@@ -185,7 +185,7 @@ export function createBDAdressesAdapter(): CorpusAdapter {
 
 					// 15 of the 179,622 rows publish an empty `numero`, among them `Al Géidgen`
 					// in Goedange and `Jaanshaff` in Walferdange.
-					// Those are named places, so they keep their street and postcode
+					// These describe a place, so they keep their street and postcode
 					// rather than being assigned a number.
 					if (house) {
 						components.house_number = house

package/lib/lu/tools/fetch/bd-adresses.ts

@@ -11,13 +11,13 @@
  * this module sits beside `#fi/tools/fetch/ryhti` rather than in an `sdk/` root the workspace does
  * not declare.
  *
- * `data.public.lu` states `cc-zero` for this dataset, which the address-source register elects as
- * `CC0-1.0` under `lu-property-building-1`. CC0 asks for no attribution, and crediting the ACT
+ * `data.public.lu` states `cc-zero` for this dataset. The address-source register elects
+ * `CC0-1.0` for it under `lu-property-building-1`. CC0 asks for no attribution, and crediting the ACT
  * remains good practice, so the manifest records the publisher beside the license.
  *
  * Four measured properties decide what this module does:
  *
- * 1. **The download URL carries the edition's own timestamp.** The dataset is republished weekly
+ * 1. **The download URL holds the edition's own timestamp.** The dataset is republished weekly
  *    and the CSV resource's `url` reads
  *    `https://download.data.public.lu/resources/adresses-georeferencees-bd-adresses/20260928-023119/addresses.csv`,
  *    where the path segment is the publication time. A hardcoded URL therefore pins one edition and
@@ -26,14 +26,14 @@
  *    `https://data.public.lu/fr/datasets/r/<resource id>`, answers http 302 to the same dated path,
  *    and the dated path is the one downloaded, so the bytes and the checksum recorded beside them
  *    belong to one edition.
- * 2. **The publisher states an md5 for the file.** The resource carries
+ * 2. **The publisher states an md5 for the file.** The resource records
  *    `checksum: {type: "md5", value: "…"}` and a `filesize`, measured as
  *    `c2df2f3c18b846144bb5d5dc57fc14ca` and 28,186,970 on the 2026-09-28 edition. The transfer is
  *    checked against both, so a truncated body is a reported failure rather than a short CSV that
  *    parses. A publisher that one day states a digest of another type is reported rather than
  *    skipped silently.
- * 3. **The file opens with a UTF-8 byte-order mark**, `EF BB BF`. The portal's `filesize` counts it,
- *    which is why a reader that discards the mark reports three bytes fewer than the portal does.
+ * 3. **The file opens with a UTF-8 byte-order mark**, `EF BB BF`. The portal's `filesize` counts it.
+ *    A reader that discards the mark therefore reports three bytes fewer than the portal does.
  *    The module writes the body to disk unaltered and checks the digest over the bytes as delivered.
  * 4. **The re-run check is the stated checksum against the manifest.** The dataset API answer is
  *    roughly 15 KB, so comparing it costs one small request instead of 28 MB.
@@ -45,7 +45,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, removePathIfPresent } from "@mailwoman/core/fs/writers"
 import { md5File, sha256File } from "@mailwoman/core/hash"
 import { PathBuilder, type PathBuilderLike } from "path-ts"
@@ -65,7 +65,7 @@ import { assertHeaderColumns, readDelimitedHeader } from "#tools/fetch/header"
 export const LU_BD_ADRESSES_DATASET_URL = "https://data.public.lu/api/1/datasets/adresses-georeferencees-bd-adresses/"
 
 /**
- * The directory the download is written under, which is the adapter's `inputPath`'s parent.
+ * The directory the download is written under, the adapter's `inputPath`'s parent.
  */
 const SLUG = BD_ADRESSES_ADAPTER_ID
 
@@ -91,7 +91,8 @@ export const LU_BD_ADRESSES_DELIMITER = ";"
  */
 export interface BDAdressesResource {
 	/**
-	 * The dated download URL, which names one edition.
+	 * The dated download URL.
+	 * It identifies one edition.
 	 */
 	url: string
 	/**
@@ -116,7 +117,8 @@ export interface BDAdressesManifest extends SourceManifest {
 	attribution: string
 	dataset_url: string
 	/**
-	 * The md5 the dataset record stated, which the downloaded bytes were checked against.
+	 * The md5 the dataset record stated.
+	 * The downloaded bytes were checked against it.
 	 */
 	publisher_md5: string | null
 	/**
@@ -143,7 +145,7 @@ interface DatasetRecord {
 /**
  * The CSV resource of a dataset record.
  *
- * @throws When the record carries no `csv` resource with a URL, because the publisher
+ * @throws When the record holds no `csv` resource with a URL, because the publisher
  * having moved the file is a reported failure rather than an empty transfer.
  */
 export function readBDAdressesResource(record: DatasetRecord): BDAdressesResource {
@@ -225,7 +227,7 @@ export async function downloadBDAdresses(
 		!options.force &&
 		present &&
 		existing &&
-		resource.md5 !== null &&
+		resource.md5 &&
 		existing.publisher_md5 === resource.md5 &&
 		existing.source_url === resource.url
 	) {
@@ -270,7 +272,7 @@ export async function downloadBDAdresses(
 
 	const md5 = await md5File(csvPath)
 
-	if (resource.md5 !== null && resource.md5 !== md5) {
+	if (resource.md5 && resource.md5 !== md5) {
 		report?.(`  ✗ the dataset record states md5 ${resource.md5} and the bytes hash to ${md5}`)
 		await removePathIfPresent(csvPath)