@mailwoman/corpus 10.1.0 → 10.2.1

package/lib/es/tools/fetch/navarra.ts

@@ -15,11 +15,11 @@
  * Four properties of this service decide the harvest's shape.
  *
  * 1. **The archive link is the `enclosure` link, and the `alternate` link is not it.** Each entry
- *    carries six links, three of which address the same archive under `enclosure`, `section` and
+ *    lists six links, three of which address the same archive under `enclosure`, `section` and
  *    `alternate`. The entry's *first* `alternate` link is the relative href
  *    `Addresses_DatasetATOM_Navarra.xml`, which is the dataset feed, so a reader taking the first
  *    `alternate` link downloads an ATOM document in place of the archive. This harvest takes
- *    `enclosure` and refuses an entry that carries none.
+ *    `enclosure` and refuses an entry that lists none.
  * 2. **An entry leaves its own area unstated.** Every one of the 272 entries is titled
  *    `Address Navarra` and every `<id>` is empty, so the archive's own file name,
  *    `AD_Navarra_<n>.gml.zip`, is the only statement of which partition an entry offers. The
@@ -47,7 +47,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 { stringifyJSON } from "@mailwoman/core/json"
@@ -61,7 +61,8 @@ import { loadCollectionFiles, writeManifest } from "#tools/fetch/download"
 import { downloadZipArchive } from "#tools/fetch/zip-archive"
 
 /**
- * The ATOM service document, which lists one zipped GML partition per entry.
+ * The ATOM service document.
+ * It lists one zipped GML partition per entry.
  */
 export const ES_NAVARRA_SERVICE_FEED_URL =
 	"https://filescartografia.navarra.es/2_CARTOGRAFIA_TEMATICA/2_7_CATASTRO/2_7_3_INSPIRE_ATOM/2_7_3_3_AD/Addresses_ServiceATOM_Navarra.xml"
@@ -84,7 +85,8 @@ export const ES_NAVARRA_ATTRIBUTION = "Gobierno de Navarra"
 export const ES_NAVARRA_REQUEST_INTERVAL_MS = 250
 
 /**
- * The directory the harvest writes under, which is the adapter's `inputPath`.
+ * The directory the harvest writes under.
+ * The adapter reads this directory as its `inputPath`.
  */
 const SLUG = ES_NAVARRA_ADAPTER_ID
 
@@ -113,7 +115,8 @@ export interface ESNavarraPartition {
 	 */
 	partition: string
 	/**
-	 * The entry's title, which reads `Address Navarra` on every entry.
+	 * The entry's title.
+	 * Every entry states `Address Navarra`.
 	 */
 	title: string
 	/**
@@ -122,8 +125,8 @@ export interface ESNavarraPartition {
 	updated: string
 	archiveURL: string
 	/**
-	 * The file name the archive is written under, which is the name the publisher gave it
-	 * and the name the adapter globs.
+	 * The file name the archive is written under.
+	 * The publisher states it and the adapter globs it.
 	 */
 	filename: string
 }
@@ -131,8 +134,8 @@ export interface ESNavarraPartition {
 /**
  * The partitions the service document lists.
  *
- * @throws When the document holds no entry, when an entry carries no `enclosure` link, when a
- * linked archive is not named `AD_Navarra_<n>.gml.zip`, or when two entries name one archive.
+ * @throws When the document holds no entry, when an entry lists no `enclosure` link, when a linked
+ * archive's file name is not `AD_Navarra_<n>.gml.zip`, or when two entries point to one archive.
  * Each of those would otherwise write zero archives while reporting a completed run.
  */
 export function readESNavarraServiceFeed(feed: AtomFeed): readonly ESNavarraPartition[] {
@@ -199,7 +202,7 @@ export interface ESNavarraArchiveEntry extends SourceManifest {
 	/**
 	 * The `<updated>` the service document stated when this archive was fetched.
 	 *
-	 * A later run that reads the same value leaves the file alone.
+	 * A later run that reads the same value skips the archive.
 	 * The publisher moves it when it publishes a new edition.
 	 */
 	feed_updated: string
@@ -224,11 +227,12 @@ export interface ESNavarraHarvestManifest extends SourceCollectionManifest {
 
 export interface HarvestESNavarraOptions {
 	/**
-	 * Where the archives and the manifest are written, which is the adapter's `inputPath`.
+	 * Where the archives and the manifest are written.
+	 * The adapter reads it as its `inputPath`.
 	 */
 	outputDir: PathBuilderLike
 	/**
-	 * Harvest only these partition numbers, for a probe or for a repair of named partitions.
+	 * Harvest only these partition numbers, for a probe or to repair specific partitions.
 	 *
 	 * A number the service document does not list is reported as a failure rather than ignored.
 	 */
@@ -240,7 +244,8 @@ export interface HarvestESNavarraOptions {
 	/**
 	 * Re-read the sha256 of every archive already on disk instead of comparing its byte count.
 	 *
-	 * The default compares the recorded byte count against the file's size, which is one `stat`.
+	 * By default the harvest compares the recorded byte count against the file's size.
+	 * That comparison costs one `stat`.
 	 */
 	verifyDigests?: boolean
 	signal?: AbortSignal
@@ -251,11 +256,12 @@ export interface HarvestESNavarraOptions {
  * Whether the archive recorded for one partition is still the one the feed describes.
  *
  * A skip requires the feed to state an `<updated>` value.
- * Where it states none, both sides read an empty string and an equality test would hold,
- * which would keep an archive of unknown age for as long as the feed stayed silent.
+ * Where it states none, both sides read an empty string and an equality test would hold.
+ *
+ * That test would keep an archive of unknown age for as long as the feed stayed silent.
  */
 async function isCurrent(
-	recorded: ESNavarraArchiveEntry | undefined,
+	recorded: ESNavarraArchiveEntry | null,
 	partition: ESNavarraPartition,
 	path: PathBuilderLike,
 	verifyDigests: boolean
@@ -266,14 +272,15 @@ async function isCurrent(
 
 	if (!stat || stat.size !== recorded.bytes) return false
 
-	// The digest check reads the whole file rather than its metadata, which is why it is opt-in.
+	// The digest check reads the whole file rather than its metadata.
+	// The caller opts in.
 	if (!verifyDigests) return true
 
 	return (await sha256File(path)) === recorded.sha256
 }
 
 /**
- * The partitions this run considers, and the numbers a caller named that the feed does not list.
+ * The partitions this run considers, and the numbers a caller supplied that the feed does not list.
  *
  * A number the caller asked for and the service document does not list is returned
  * rather than dropped, because a partition that is not published is a different
@@ -317,8 +324,9 @@ function selectPartitions(
  * the pacing. {@linkcode fetchESNavarra} is the registry entry point and supplies both.
  *
  * @returns What was fetched, what the feed states is already recorded, and which partitions failed.
- * @throws When the service document lists no partition, which would otherwise answer
- * `{fetched: 0, skipped: 0, failed: 0}` and read to a caller as a completed fetch of an empty publisher.
+ * @throws When the service document lists no partition.
+ * The call would otherwise return `{fetched: 0, skipped: 0, failed: 0}`
+ * and read to a caller as a completed fetch of an empty publisher.
  */
 export async function harvestESNavarra(
 	client: Pick<APIClient, "fetch">,
@@ -357,8 +365,8 @@ export async function harvestESNavarra(
 	const previous = await loadCollectionFiles(manifestPath)
 	const files = new Map<string, ESNavarraArchiveEntry>()
 
-	// An entry for a partition this run does not consider is carried through,
-	// so a bounded run never drops what an earlier run recorded.
+	// An entry for a partition this run does not consider is kept, so a bounded
+	// run never drops what an earlier run recorded.
 	for (const [filename, entry] of previous) {
 		files.set(filename, entry as ESNavarraArchiveEntry)
 	}
@@ -390,7 +398,7 @@ export async function harvestESNavarra(
 
 		const dest = destDir(partition.filename)
 
-		if (await isCurrent(files.get(partition.filename), partition, dest, options.verifyDigests ?? false)) {
+		if (await isCurrent(files.get(partition.filename) ?? null, partition, dest, options.verifyDigests ?? false)) {
 			skipped++
 
 			continue
@@ -454,7 +462,7 @@ export interface FetchESNavarraOptions
 	/**
 	 * The minimum spacing between two requests, in milliseconds.
 	 *
-	 * Defaults to {@linkcode ES_NAVARRA_REQUEST_INTERVAL_MS}.
+	 * @defaultValue {@linkcode ES_NAVARRA_REQUEST_INTERVAL_MS}
 	 */
 	minRequestIntervalMs?: number
 }

package/lib/fi/adapters/ryhti/adapter.ts

@@ -17,43 +17,40 @@
  * every name column bare.
  *
  * A row's country comes from `municipality_number` rather than from the caller. Åland is part of
- * Finland and its sixteen municipalities carry Finnish municipality numbers, so one national file
- * holds both jurisdictions and {@linkcode ALAND_MUNICIPALITIES} is what separates them.
+ * Finland and its sixteen municipalities have Finnish municipality numbers, so one national file
+ * holds both jurisdictions and {@linkcode ALAND_MUNICIPALITIES} separates them.
  *
  * The street and the house number are read from the publisher's own part columns rather than from
  * its inline address text.
  * `address_name_fin` is the whole of `address_fin` or a space-delimited prefix of it, and the four
  * number-part columns reproduce the publisher's inline number.
- * Measured over the first 292,293 rows of the 2026-10-02 edition: 278,262 rows populate both
- * columns, 0 of them place `address_name_fin` anywhere but at the head of `address_fin`, and the
- * composed number equals the inline remainder byte for byte on all 265,830 numbered rows.
- * No row publishes inline address text with both name columns empty,
- * so reading the name columns loses no address.
+ * No row publishes inline address text with both name columns empty, so the part columns lose no
+ * address.
  *
- * `address_number` is not a house number. It is a 1-based ordinal over the addresses sharing one
- * `building_key`, which is how a corner building's several frontages are numbered, and it holds nine
- * distinct values across the file. The adapter ignores it.
+ * `address_number` is not a house number. It is a 1-based ordinal over the addresses that share one
+ * `building_key`. That is how a corner building's several frontages are numbered. The adapter
+ * ignores it.
  *
- * The file is bilingual, and which column carries which language depends on the municipality. On
+ * The file is bilingual, and which column holds which language depends on the municipality. On
  * mainland Finland `address_name_fin` is the Finnish name and `address_name_swe` the Swedish one. On
  * Åland the `*_fin` columns, where populated at all, hold the **Swedish** name: `address_fin` reads
  * `Skogshyddsvägen 11`.
  * So the adapter prefers `*_swe` on Åland and `*_fin` on the mainland, and emits one row per
  * published record from the preferred language's columns.
- * `locale` names the language of the name it emitted rather than the language of the column that
- * name came from, which gives three values.
- * `fi-FI` is a mainland record named in `address_name_fin`.
- * `sv-FI` is a mainland record that populates `address_name_swe` alone, which is the form a
+ * `locale` states the language of the name it emitted rather than the language of the column that
+ * name came from. That gives three values.
+ * `fi-FI` is a mainland record whose name came from `address_name_fin`.
+ * `sv-FI` is a mainland record that populates `address_name_swe` only. That is the form a
  * Swedish-speaking municipality publishes.
  * `sv-AX` is every Åland record, because the Swedish columns are the populated ones there and the
  * `*_fin` columns hold the Swedish name where they are populated at all.
  * A mainland record's Swedish name, where the record publishes both, is not emitted as a second
- * row: a record is one premise, and `CanonicalRow` carries one written surface.
+ * row: a record is one premise, and `CanonicalRow` holds one written surface.
  *
  * SYKE's metadata record `{DBD610F4-3392-44CD-B601-BAE8FA547A57}` grants CC BY 4.0 for its open data
  * and the register's two elected decisions for this file record `CC-BY-4.0` in their `spdx` field, so
  * the adapter records that license on every row. SYKE states the attribution it wants as
- * `Lähde: Syke Ryhti`, and the model card must carry it.
+ * `Lähde: Syke Ryhti`, and the model card must state it.
  *
  * The adapter streams with `CSVSpliterator.fromAsync`, so the 3.8M-row file never sits in memory. It
  * honors `opts.limit`, `opts.signal` and `opts.country`.
@@ -79,7 +76,6 @@ export const RYHTI_ADAPTER_ID = "ryhti"
  * The sixteen `municipality_number` values of Åland's municipalities.
  *
  * Every other number in the file belongs to a mainland Finnish municipality.
- * The file holds 308 distinct values, and these sixteen cover 32,518 of its 3,862,609 rows.
  *
  * The column is a zero-padded three-digit string, so a reader compares the padded form.
  */
@@ -154,8 +150,8 @@ export function countryOfFinnishMunicipality(municipalityNumber: string): string
  * as `184-183b` across a second pair of the same two columns.
  * The second pair is appended after a hyphen when either of its halves is populated.
  *
- * @returns The composed number, or an empty string for a row with no number at all,
- * which a caller treats as a named place rather than assigning it a number.
+ * @returns The composed number, or an empty string for a row with no number at all.
+ * A caller treats that empty string as a place name rather than a number.
  */
 export function composeRyhtiHouseNumber(record: Partial<RyhtiNumberParts>): string {
 	const first = composeHouseNumber(
@@ -186,7 +182,7 @@ interface NamedSurface {
 }
 
 /**
- * The surface to emit for one record, or `undefined` for a record that names no street.
+ * The surface to emit for one record, or `null` for a record with no street.
  *
  * On Åland the Swedish columns are preferred, and the Finnish ones are read as Swedish.
  * That is the language they hold there.
@@ -195,11 +191,11 @@ interface NamedSurface {
  * The Swedish ones stand in where `address_name_fin` is empty.
  * That is the form a Swedish-speaking municipality publishes.
  *
- * A language whose name column is empty names no street.
+ * A language whose name column is empty has no street.
  * Seven mainland rows publish an `address_swe` of a bare number with an empty `address_name_swe`.
  * This refuses them rather than giving them an empty street.
  */
-function surfaceOf(record: RyhtiRow, country: string): NamedSurface | undefined {
+function surfaceOf(record: RyhtiRow, country: string): NamedSurface | null {
 	const finnish = {
 		street: (record.address_name_fin ?? "").trim(),
 		locality: (record.postal_office_fin ?? "").trim(),
@@ -213,12 +209,12 @@ function surfaceOf(record: RyhtiRow, country: string): NamedSurface | undefined
 	if (country === "AX") {
 		const preferred = swedish.street ? swedish : finnish
 
-		return preferred.street ? { ...preferred, language: "sv" } : undefined
+		return preferred.street ? { ...preferred, language: "sv" } : null
 	}
 
 	if (finnish.street) return { ...finnish, language: "fi" }
 
-	return swedish.street ? { ...swedish, language: "sv" } : undefined
+	return swedish.street ? { ...swedish, language: "sv" } : null
 }
 
 export function createRyhtiAdapter(): CorpusAdapter {
@@ -251,7 +247,7 @@ export function createRyhtiAdapter(): CorpusAdapter {
 
 					const country = countryOfFinnishMunicipality(record.municipality_number ?? "")
 
-					// A caller that named one jurisdiction gets that jurisdiction's rows,
+					// A caller that requested one jurisdiction gets that jurisdiction's rows,
 					// so the one national file can be read once per country.
 					if (opts.country && country !== opts.country) continue
 

package/lib/fi/tools/fetch/ryhti.ts

@@ -14,31 +14,27 @@
  * this module sits beside `#fr/tools/fetch/ban` rather than in an `sdk/` root the workspace does
  * not declare.
  *
- * SYKE's metadata record `{DBD610F4-3392-44CD-B601-BAE8FA547A57}` grants CC BY 4.0, which the
- * address-source register elects, and states the attribution as `Lähde: Syke Ryhti`. The manifest
+ * SYKE's metadata record `{DBD610F4-3392-44CD-B601-BAE8FA547A57}` grants CC BY 4.0 and states the
+ * attribution as `Lähde: Syke Ryhti`. The address-source register elects that license. The manifest
  * records both, and `#fi/adapters/ryhti/adapter` records the license on every row.
  *
  * Four measured properties decide what this module does:
  *
- * 1. **The file is republished daily and its length changes with it.** `HEAD` answered
- *    `content-length: 351290196` and `last-modified: Fri, 2 Oct 2026 05:20:14 GMT` on 2026-10-02,
- *    against `351288399` and `Thu, 1 Oct 2026 05:20:03 GMT` the day before. So the re-run check is
- *    a `HEAD` compared against the manifest, which costs one small request instead of 351 MB, and
- *    neither number is written into this module as a constant.
+ * 1. **The file is republished daily and its length changes with it.** The re-run check is a `HEAD`
+ *    compared against the manifest, so one small request replaces the whole body and no length is a
+ *    constant here.
  * 2. **The host ignores `Range`.** `bytes=0-4095` answers HTTP 200 with no `content-range` and the
  *    whole `content-length`, and `accept-ranges` is absent, so a resumed transfer is not available
  *    and an interrupted one restarts. {@linkcode resumableDownload} would refuse the response.
- * 3. **This module moves bytes and decodes none of them.** The body is streamed to disk compressed, then
- *    decompressed stream to stream, so no chunk boundary is ever interpreted as a character
- *    boundary. A `chunk.toString("utf8")` per gzip chunk produces a U+FFFD at every boundary that
- *    splits a multi-byte character, and 60,014,592 decompressed bytes of this file were scanned for
- *    `EF BF BD` with 0 found: the replacement characters such a reader reports are its own.
+ * 3. **This module moves bytes and decodes none of them.** The body is streamed to disk compressed
+ *    and then decompressed stream to stream, so no chunk boundary is interpreted as a character
+ *    boundary. A `chunk.toString("utf8")` per gzip chunk would write U+FFFD at every split
+ *    multi-byte character.
  * 4. **The decompressed CSV is what the adapter can read.** `#fi/adapters/ryhti/adapter` hands
- *    `opts.inputPath` to `CSVSpliterator.fromAsync`, which reads the bytes as they are on disk, so
- *    a path to the `.gz` would be parsed as CSV over gzip bytes. The `.gz` is therefore removed once the CSV is
- *    written: 793 MB of readable input instead of 351 MB plus a reader the adapter does not have.
+ *    `opts.inputPath` to `CSVSpliterator.fromAsync`, which reads the bytes on disk. A path to the
+ *    `.gz` would be parsed as CSV over gzip bytes, so the `.gz` is removed once the CSV is written.
  *    A caller that wants the compressed copy kept passes
- *    {@linkcode FetchRyhtiOptions.keepCompressed}, which costs 1.14 GB for both.
+ *    {@linkcode FetchRyhtiOptions.keepCompressed}.
  */
 
 /* oxlint-disable sister-software/prefer-region-over-marks -- these markers label steps inside one
@@ -47,7 +43,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"
@@ -64,7 +60,7 @@ import { assertHeaderColumns, readDelimitedHeader } from "#tools/fetch/header"
 export const FI_RYHTI_CSV_URL = "https://paikkatiedot.ymparisto.fi/geoserver/www/open_address.csv.gz"
 
 /**
- * The directory the download is written under, which is the adapter's `inputPath`'s parent.
+ * The download directory, the adapter's `inputPath`'s parent.
  */
 const SLUG = RYHTI_ADAPTER_ID
 
@@ -84,7 +80,8 @@ const COMPRESSED_FILENAME = "open_address.csv.gz"
 export const FI_RYHTI_LICENSE = "CC-BY-4.0"
 
 /**
- * The attribution SYKE states for its open data, which the model card must carry.
+ * The attribution SYKE states for its open data.
+ * The model card must record it.
  */
 export const FI_RYHTI_ATTRIBUTION = "Lähde: Syke Ryhti"
 
@@ -115,8 +112,9 @@ export const FI_RYHTI_REQUIRED_COLUMNS: readonly string[] = [
 /**
  * What the manifest records about the one file.
  *
- * {@linkcode SourceManifest}'s five fields describe the decompressed CSV,
- * which is what the adapter reads and what the digest covers.
+ * {@linkcode SourceManifest}'s five fields describe the decompressed CSV.
+ * That file is what the adapter reads and what the digest covers.
+ *
  * The three added fields describe the transfer, and they are what the re-run
  * check compares before it downloads 351 MB.
  */
@@ -132,7 +130,7 @@ export interface RyhtiManifest extends SourceManifest {
 	 */
 	compressed_bytes: number | null
 	/**
-	 * The columns the header named when this file was downloaded, in order.
+	 * The columns the header held when this file was downloaded, in order.
 	 *
 	 * Recorded rather than counted, so a later edition's added, removed or renamed
 	 * column is a diff against this list rather than a count that moved.
@@ -165,7 +163,7 @@ export async function readRyhtiHead(client: Pick<APIClient, "fetch">, url = FI_R
 
 	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,
 	}
 }
@@ -202,13 +200,14 @@ export interface DownloadRyhtiOptions {
 	 * Keep the compressed copy beside the CSV.
 	 *
 	 * The adapter reads the CSV, so the default removes the archive once the CSV is written.
-	 * Keeping both holds 1.14 GB for the one file.
+	 * Both together hold 1.14 GB for the one file.
 	 */
 	keepCompressed?: boolean
 	/**
 	 * Re-read the CSV's sha256 on a re-run instead of comparing its byte count.
 	 *
-	 * The default compares the recorded byte count against the file's size, which is one `stat`.
+	 * The default compares the recorded byte count against the file's size.
+	 * That check is one `stat`.
 	 * This re-hashes 793 MB.
 	 */
 	verifyDigest?: boolean
@@ -218,14 +217,15 @@ export interface DownloadRyhtiOptions {
 	force?: boolean
 	/**
 	 * Attempts after the first for the one transfer.
-	 * Defaults to three.
 	 *
 	 * The host ignores `Range`, so each attempt starts the 351 MB again.
+	 *
+	 * @defaultValue three.
 	 */
 	retries?: number
 	/**
 	 * Pause between attempts, in milliseconds.
-	 * Defaults to `DEFAULT_RETRY_DELAY_MS`.
+	 * @defaultValue {@linkcode DEFAULT_RETRY_DELAY_MS}
 	 */
 	retryDelayMs?: number
 	signal?: AbortSignal
@@ -258,9 +258,9 @@ async function isCurrent(
 	if (!recorded) return false
 
 	// A host that states neither cannot be compared against, so the file 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
 
@@ -344,8 +344,8 @@ export async function downloadRyhti(
 				const contentType = response.headers.get("content-type") ?? ""
 
 				// The host serves `application/x-gzip`.
-				// An `text/html` body under http 200 is a portal page, which would otherwise
-				// be written to disk and fail later as a corrupt archive.
+				// An `text/html` body under http 200 is a portal page.
+				// A portal page saved to disk would fail later as a corrupt archive.
 				if (contentType.includes("text/html")) {
 					throw new Error(`${FI_RYHTI_CSV_URL} answered ${contentType}, which is a page rather than the file`)
 				}

package/lib/fr/adapters/annuaire-education/adapter.ts

@@ -11,8 +11,8 @@
  * `/api/explore/v2.1/catalog/datasets/fr-en-annuaire-education/exports/jsonl`. The export keys each
  * record by the dataset's field names (`nom_etablissement`, `adresse_1`, `adresse_2`, `adresse_3`,
  * `code_postal`, `nom_commune`, `code_departement`, `etat`), and {@linkcode AnnuaireRecord} declares
- * the ones this adapter reads. `fetchAnnuaireEducationOverseas` asks the export for the overseas departments
- * alone, and the adapter filters again, so a whole-country export reads the same.
+ * the ones this adapter reads. `fetchAnnuaireEducationOverseas` asks the export for the overseas
+ * departments only, and the adapter filters again, so a whole-country export reads the same.
  *
  * ## Which rows are read
  *
@@ -25,7 +25,7 @@
  * ## Organizations only
  *
  * Every record is an education establishment or office. One private school among the overseas
- * records writes its address care of a named person (`Chez …`), which places it at that person's
+ * records writes its address care of one person (`Chez …`), which places it at that person's
  * premises, so a line opening with `Chez` refuses the row under {@linkcode AnnuaireRefusal.CareOfPerson}.
  *
  * ## The three address lines
@@ -35,7 +35,7 @@
  * what it holds rather than by its position:
  *
  * - **A street.** `5 rue Maréchal Leclerc` opens with a number and a street-type word, and
- *   `Rue Marcel Bonin` with the word alone. The word becomes `street_prefix` through
+ *   `Rue Marcel Bonin` with the word only. The word becomes `street_prefix` through
  *   {@linkcode splitFrenchStreetType}, which reads the BAN reader's dictionary and then TRE-R35's
  *   street types for the words it lacks (`quartier`, `lotissement`, `ZAC`). A number of `0` is the
  *   publisher's placeholder for none. `Bourg` or `Village` written by itself refers to the
@@ -79,8 +79,8 @@
  * transformer, pour créer des « Informations dérivées », des produits ou des services », « Sous
  * réserve de : mentionner la paternité de l'« Information » : sa source (au moins le nom du «
  * Concédant ») et la date de dernière mise à jour de l'« Information » réutilisée. » Every row
- * records the license, and {@linkcode FR_ANNUAIRE_EDUCATION_ATTRIBUTION} is the credit, which the
- * model card completes with the update date the fetch manifest records.
+ * records the license, and {@linkcode FR_ANNUAIRE_EDUCATION_ATTRIBUTION} is the credit. The model
+ * card completes it with the update date the fetch manifest records.
  *
  * The adapter honors `opts.limit`, `opts.signal` and `opts.country`, and counts every refusal
  * under its reason in `opts.dropped`.
@@ -125,7 +125,7 @@ export const FR_ANNUAIRE_EDUCATION_ATTRIBUTION =
 
 /**
  * The overseas INSEE departments this adapter reads: every prefix in `COUNTRY_BY_INSEE_DEPARTMENT`
- * except `984`, the French Southern Territories, which has no schools.
+ * except `984`, the French Southern Territories, where there are no schools.
  */
 export const FR_ANNUAIRE_EDUCATION_DEPARTEMENTS: readonly string[] = [
 	"971",
@@ -206,7 +206,7 @@ export const AnnuaireRefusal = {
 	 */
 	DeliveryLineAbsent: "row:delivery-line-absent",
 	/**
-	 * The jurisdiction's layout does not print every component the row carries.
+	 * The jurisdiction's layout does not print every component the row holds.
 	 */
 	Unrenderable: "row:unrenderable",
 	/**
@@ -252,7 +252,8 @@ const ARCHIPELAGO_CODE = /^(?:idv|islv|tg|marq|australes)(?![\p{L}\d])/iu
 const LEADING_NUMBER = /^(\d+)(?:\s*(bis|ter|quater)(?![\p{L}])|\s?([A-Za-z])(?![\p{L}'’]))?[\s,]+(.+)$/iu
 
 /**
- * A leading `Lieu-dit` marker, which a place line drops.
+ * A leading `Lieu-dit` marker.
+ * A place line drops it.
  */
 const LIEU_DIT_MARKER = /^lieu[- ]dit\s+/iu
 
@@ -299,7 +300,7 @@ const THOROUGHFARE_WORDS: ReadonlySet<string> = new Set([
 ])
 
 /**
- * Street-type words that, written alone, name a settlement's center: `Bourg`, `Village`.
+ * Street-type words that stand for a settlement's center: `Bourg`, `Village`.
  */
 const LONE_PLACE_WORDS: ReadonlySet<string> = new Set(["bourg", "village", "le bourg"])
 
@@ -347,7 +348,8 @@ export function readAnnuaireLine(line: string): LineReading {
 
 	if (split) {
 		if (!split.street) {
-			// `Bourg` and `Village` alone name the settlement's center, which is a place.
+			// `Bourg` and `Village` on their own refer to the settlement's center.
+			// That center is a place.
 			if (!house && split.street_prefix && LONE_PLACE_WORDS.has(foldToken(split.street_prefix))) {
 				return { kind: "place", place: split.street_prefix }
 			}

package/lib/fr/adapters/ban/adapter.ts

@@ -7,12 +7,12 @@
  *
  * Input is a semicolon-separated CSV dump from `adresse.data.gouv.fr`. The adapter reads `numero`
  * as `house_number`, `rep` as a repetition index appended to it, `nom_voie` as `street`,
- * `code_postal` as `postcode`, and `nom_commune` as `locality`. BAN carries no region column, so
+ * `code_postal` as `postcode`, and `nom_commune` as `locality`. BAN holds no region column, so
  * region is left to the wof-postalcode and wof-admin cross-reference at corpus build time.
  *
  * IGN publishes one file per INSEE department beside the whole-country extract, and the overseas
- * departments carry the same 23-column header as the metropolitan rows. A row's country is therefore
- * derived from `code_insee` rather than asserted by the caller, which reads the same whether the
+ * departments hold the same 23-column header as the metropolitan rows. A row's country is therefore
+ * derived from `code_insee` rather than asserted by the caller. That derivation reads the same whether the
  * input is one department's file or an extract spanning several.
  *
  * The official BAN is dual-licensed under Licence Ouverte 2.0 and ODbL.
@@ -21,7 +21,7 @@
  *
  * The adapter streams with `CSVSpliterator.fromAsync`, so a 25M-row file never sits in memory. It
  * honors `opts.limit` and `opts.signal`. `opts.country` is optional: when set it both rejects a
- * jurisdiction BAN does not publish and keeps only the rows of the one named.
+ * jurisdiction BAN does not publish and keeps only the rows of the one requested.
  */
 
 import { formatAddressRow } from "@mailwoman/codex/address/format"
@@ -94,7 +94,7 @@ export function createBanAdapter(): CorpusAdapter {
 
 				const country = countryOfInseeCode(record.code_insee ?? "")
 
-				// A caller that named one jurisdiction gets that jurisdiction's rows,
+				// A caller that requested one jurisdiction gets that jurisdiction's rows,
 				// so one extract spanning several departments can be read once per country.
 				if (opts.country && country !== opts.country) continue
 
@@ -167,7 +167,7 @@ export function createBanAdapter(): CorpusAdapter {
 					components: aligned,
 					country,
 					// Every jurisdiction BAN publishes writes its addresses in French,
-					// so the language is constant and the region carries the jurisdiction.
+					// so the language is constant and the region holds the jurisdiction.
 					locale: `fr-${country}`,
 					source: BAN_ADAPTER_ID,
 					source_id: sourceID,