@mailwoman/corpus 10.1.0 → 10.2.1

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

@@ -21,7 +21,7 @@
  *
  * ## Which rows are read
  *
- * `departement` carries a two-character code, and the overseas ones are `9A` Guadeloupe, `9B`
+ * `departement` holds a two-character code, and the overseas ones are `9A` Guadeloupe, `9B`
  * Martinique, `9C` Guyane, `9D` La Réunion, `9E` Saint-Pierre-et-Miquelon, `9F` Mayotte and `9J`
  * Wallis-et-Futuna. Saint-Barthélemy and Saint-Martin have no code of their own: their
  * establishments sit under `9A`, and the postcodes 97133 and 97150 separate them, so the adapter
@@ -51,7 +51,7 @@
  *
  * `compvoie` is one of `B`, `T`, `Q` or `C`. The first three are bis, ter and quater. `C` is
  * refused under {@linkcode FinessRefusal.RepetitionIndexAmbiguous}: INSEE's coding reads it as
- * quinquies, and the national extract carries 133 `C` against 31 `Q`, which is not the ratio of a
+ * quinquies, and the national extract holds 133 `C` against 31 `Q`, which is not the ratio of a
  * fifth repetition to a fourth and reads as a letter suffix entered in the index field.
  *
  * A digit in `voie` is refused under {@linkcode FinessRefusal.StreetDigitUnplaced} unless the digits
@@ -70,8 +70,8 @@
  * under {@linkcode FinessTrim.LieuDitPremiseDescriptor}, because the row stays an address without it.
  *
  * `ligneacheminement` is La Poste's routing line, `97100 BASSE TERRE` or `97331 CAYENNE CEDEX`. It
- * gives the postcode, the locality as La Poste routes it and the `cedex` phrase, which the codex
- * layouts of every jurisdiction this adapter emits except French Polynesia print after the locality.
+ * gives the postcode, the locality as La Poste routes it and the `cedex` phrase. Every codex layout
+ * this adapter emits prints that phrase after the locality. French Polynesia is the exception.
  *
  * ## Identity and license
  *
@@ -81,11 +81,11 @@
  * data.gouv.fr publishes the dataset under the license whose id is `fr-lo`, titled `Licence Ouverte /
  * Open Licence`, and links its text at
  * `https://www.etalab.gouv.fr/wp-content/uploads/2014/05/Licence_Ouverte.pdf`. That is version 1.0
- * of October 2011, which grants the reuser the right to « Adapter, modifier, extraire et
+ * of October 2011. It grants the reuser the right to « Adapter, modifier, extraire et
  * transformer à partir de « l'Information », notamment pour créer des « Informations dérivées » »,
  * « Sous réserve de : Mentionner la paternité de « l'Information » : sa source (a minima le nom du
  * « Producteur ») et la date de sa dernière mise à jour. » Every row records that license, and
- * {@linkcode FR_FINESS_ATTRIBUTION} is the credit, which the model card completes with the
+ * {@linkcode FR_FINESS_ATTRIBUTION} is the credit. The model card completes it with the
  * extraction date the fetch manifest records.
  *
  * The adapter honors `opts.limit`, `opts.signal` and `opts.country`, and counts every refusal
@@ -138,7 +138,7 @@ export const FR_FINESS_ATTRIBUTION =
 /**
  * The jurisdiction each overseas `departement` code belongs to.
  *
- * `9A` also holds Saint-Barthélemy and Saint-Martin, which {@linkcode FINESS_COUNTRY_BY_POSTCODE} separates.
+ * `9A` also holds Saint-Barthélemy and Saint-Martin. {@linkcode FINESS_COUNTRY_BY_POSTCODE} separates them.
  */
 export const FINESS_COUNTRY_BY_DEPARTEMENT: Readonly<Record<string, string>> = {
 	"9A": "GP",
@@ -174,14 +174,15 @@ export const FINESS_FAMILY_PLACEMENT_CATEGORIES: ReadonlySet<string> = new Set([
 /**
  * An establishment name that states family placement, for one filed under another category.
  *
- * Saint-Pierre-et-Miquelon's `CENTRE D'ACCUEIL FAMILIAL SPECIALISE` is filed under `377`,
- * Etablissement expérimental pour enfance handicapée, so the category list alone admits it.
+ * Saint-Pierre-et-Miquelon's `CENTRE D'ACCUEIL FAMILIAL SPECIALISE` is filed under `377`, Etablissement
+ * expérimental pour enfance handicapée, so the category list would admit it without the name check.
  */
 const FAMILY_PLACEMENT_NAME = /\b(?:accueil|placement) famil|\blieux? de vie\b/iu
 
 /**
- * The positions, counted from 0, of the columns this adapter reads, each named by
- * what it holds with the publisher's column name beside it.
+ * The positions, counted from 0, of the columns this adapter reads.
+ *
+ * Each entry gives the publisher's column name and what the column holds.
  */
 export const FinessColumn = {
 	/**
@@ -265,7 +266,7 @@ export const FinessRefusal = {
 	 */
 	RepetitionIndexAmbiguous: "row:repetition-index-ambiguous",
 	/**
-	 * A house number with no street name to carry it.
+	 * A house number with no street name.
 	 */
 	NumberWithoutStreet: "row:number-without-street",
 	/**
@@ -285,7 +286,7 @@ export const FinessRefusal = {
 	 */
 	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",
 	/**
@@ -387,8 +388,8 @@ function readStreet(
 
 	if (word === undefined) return { refused: FinessRefusal.VoieTypeUnknown }
 
-	// With no code, or a code that adds no word, the name carries whatever type word it has.
-	if (word === null) {
+	// With no code, or a code that adds no word, the name holds whatever type word it has.
+	if (!word) {
 		const split = splitFrenchStreetType(name)
 
 		if (split?.street) {

package/lib/fr/adapters/finess/voie-type.ts

@@ -37,7 +37,7 @@ import { decomposeFrStreet } from "#fr/street-decompose"
  * and TRE-R35's own display for `HLM` is the acronym.
  *
  * `LD` maps to `null`.
- * A lieu-dit is written by its name alone, so the code adds no word to the line.
+ * A lieu-dit is written by its name only, so the code adds no word to the line.
  *
  * `VAL` keeps the code as its word.
  * TRE-R35 displays it as `Vallée, vallon`, two words the code does not choose between,
@@ -145,7 +145,7 @@ export interface FrenchStreetSplit {
  *
  * The BAN reader's {@linkcode decomposeFrStreet} is consulted first, then TRE-R35's words and the
  * codex's `FR_VOIE_TYPES`, which hold the overseas types it lacks (`quartier`, `lotissement`, `ZAC`).
- * The name may come back empty, as it does for a line reading `Rue` alone.
+ * The name may come back empty, as it does for a line reading only `Rue`.
  */
 export function splitFrenchStreetType(line: string): FrenchStreetSplit | null {
 	const decomposed = decomposeFrStreet(line)
@@ -168,7 +168,8 @@ export function splitFrenchStreetType(line: string): FrenchStreetSplit | null {
 }
 
 /**
- * The French month names, folded, which a date-named street writes after its day.
+ * The French month names, folded.
+ * A street name with a date writes the month after the day.
  */
 const MONTHS = "janvier|fevrier|mars|avril|mai|juin|juillet|aout|septembre|octobre|novembre|decembre"
 

package/lib/fr/insee-country.ts

@@ -42,11 +42,11 @@ export const COUNTRY_BY_INSEE_DEPARTMENT: Readonly<Record<string, string>> = {
 }
 
 /**
- * Every jurisdiction an INSEE-coded French source can carry, so a caller's `--country`
+ * Every jurisdiction an INSEE-coded French source can produce, so a caller's `--country`
  * is checked against the set rather than against one value.
  *
  * `TF` and `WF` are in the set and currently yield no rows, because the set describes what
- * the publisher's files can carry rather than what the address-source register has elected.
+ * the publisher's files can contain rather than what the address-source register has elected.
  */
 export const INSEE_COUNTRIES: readonly string[] = ["FR", ...Object.values(COUNTRY_BY_INSEE_DEPARTMENT)]
 

package/lib/fr/recipes/lieudit.ts

@@ -60,9 +60,10 @@ interface LieuDitTuple {
 	locality: string
 	dependentLocality: string
 	/**
-	 * The row's INSEE commune code, which decides its jurisdiction.
+	 * The row's INSEE commune code.
+	 * This code decides the row's jurisdiction.
 	 *
-	 * BAN's overseas department files carry the same columns as the metropolitan ones,
+	 * BAN's overseas department files hold the same columns as the metropolitan ones,
 	 * so a recipe that reads the fetched BAN directory receives Guadeloupe, Martinique,
 	 * French Guiana, Réunion and Mayotte rows beside the metropolitan ones.
 	 */
@@ -238,10 +239,11 @@ export const frLieuditRecipe: CorpusRecipe = {
 			// `countryFraction <= 0` (the default) never draws from `random`,
 			// so the byte-stream is unaffected when the flag is unset.
 			//
-			// Codex states surface forms for `FR` alone among the jurisdictions BAN covers, so an overseas
+			// Among the jurisdictions BAN covers, codex states surface forms only for `FR`, so an overseas
 			// row draws from `random` and then leaves `raw` and `components.country` as they were.
-			// The draw happens either way, which keeps the byte-stream a function of `countryFraction`
-			// rather than of the mixture of jurisdictions in the input files.
+			// The draw happens either way.
+			// This keeps the byte-stream a function of `countryFraction` rather than of
+			// the mixture of jurisdictions in the input files.
 			if (countryFraction > 0 && random() < countryFraction) {
 				const forms: readonly string[] | undefined =
 					COUNTRY_SURFACE_FORMS[country as keyof typeof COUNTRY_SURFACE_FORMS]
@@ -270,7 +272,7 @@ export const frLieuditRecipe: CorpusRecipe = {
 				components,
 				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,
 				source_id: sourceID,

package/lib/fr/tools/fetch/annuaire-education.ts

@@ -10,7 +10,7 @@
  * `fr-en-annuaire-education` on `data.education.gouv.fr`. Its Explore API v2.1 serves the catalog
  * record (license, `modified`, record count) at `/api/explore/v2.1/catalog/datasets/<id>` and a whole
  * or filtered export at `/exports/jsonl?where=<ODSQL>`. The fetcher asks the export for the overseas
- * departments the adapter reads, which is 3,145 records of the dataset's 68,564 on 2026-10-03, and
+ * departments the adapter reads: 3,145 of the dataset's 68,564 records on 2026-10-03. It
  * writes them as JSON Lines.
  *
  * Two checks keep a short transfer from reading as a small directory. The records endpoint is asked
@@ -23,7 +23,7 @@
 import { APIClient } from "@mailwoman/core/api"
 import { isSuccessStatus } from "@mailwoman/core/api/responses"
 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 { sha256File } from "@mailwoman/core/hash"
 import { PathBuilder, type PathBuilderLike } from "path-ts"
@@ -49,12 +49,14 @@ export const ANNUAIRE_EDUCATION_DATASET_ID = "fr-en-annuaire-education"
 export const ANNUAIRE_EDUCATION_API_URL = `https://data.education.gouv.fr/api/explore/v2.1/catalog/datasets/${ANNUAIRE_EDUCATION_DATASET_ID}`
 
 /**
- * The dataset's page, which states the license.
+ * The dataset's page.
+ * It states the license.
  */
 export const ANNUAIRE_EDUCATION_PAGE_URL = `https://data.education.gouv.fr/explore/dataset/${ANNUAIRE_EDUCATION_DATASET_ID}/`
 
 /**
- * The file the export is written to, which is the adapter's input.
+ * The file the export is written to.
+ * The adapter reads it as input.
  */
 export const ANNUAIRE_EDUCATION_FILENAME = "fr-en-annuaire-education-overseas.jsonl"
 
@@ -105,7 +107,8 @@ export interface AnnuaireExportManifest extends SourceManifest {
 	dataset_license: string | null
 	dataset_license_url: string | null
 	/**
-	 * The record count the filter selected, which the written line count matched.
+	 * The record count the filter selected.
+	 * The written line count must match it.
 	 */
 	records: number
 }
@@ -237,17 +240,17 @@ export async function downloadAnnuaireEducation(
 		retryDelayMs: options.retryDelayMs ?? DEFAULT_RETRY_DELAY_MS,
 	})
 
-	if (!isSuccessStatus(status)) return await fail(`export answered HTTP ${status}`)
+	if (!isSuccessStatus(status)) return fail(`export answered HTTP ${status}`)
 
 	const lines = await countJSONLines(dest)
 
 	if (lines !== expected) {
-		return await fail(`the filter selects ${expected} records and the export wrote ${lines}`)
+		return fail(`the filter selects ${expected} records and the export wrote ${lines}`)
 	}
 
 	const stat = await tryStat(dest)
 
-	if (!stat) return await fail(`the export is not at ${dest.toString()}`)
+	if (!stat) return fail(`the export is not at ${dest.toString()}`)
 
 	const entry: AnnuaireExportManifest = {
 		source_url: annuaireExportURL(),

package/lib/fr/tools/fetch/ban.ts

@@ -5,7 +5,7 @@
  *
  *   Fetch the full French BAN (Base Adresse Nationale): every metropolitan département (01-95, 2A,
  *   2B) and the ten overseas files the publisher serves, 971-978 plus 987 French Polynesia and 988 New
- *   Caledonia. Each overseas file is its own ISO 3166-1 jurisdiction, which the adapter derives from
+ *   Caledonia. Each overseas file is its own ISO 3166-1 jurisdiction. The adapter derives it from
  *   `code_insee`.
  *
  *   Source: https://adresse.data.gouv.fr/data/ban/adresses/latest/csv/
@@ -22,7 +22,8 @@
 
 import { gunzip } from "@mailwoman/core/fs/compression"
 import { BYTES_PER_KIB, ByteFormatter } from "@mailwoman/core/fs/formatters"
-import { isFile, readLocalBuffer, tryStat } from "@mailwoman/core/fs/readers"
+import { readLocalBuffer } from "@mailwoman/core/fs/readers"
+import { isFile, tryStat } from "@mailwoman/core/fs/readers/stat"
 import { makeDirectories, removePath, writeLocalFile } from "@mailwoman/core/fs/writers"
 import { sha256File } from "@mailwoman/core/hash"
 import { sleep } from "@mailwoman/core/utils/sleep"

package/lib/fr/tools/fetch/finess.ts

@@ -9,7 +9,7 @@
  * `finess-extraction-du-fichier-des-etablissements`, whose API record at
  * `https://www.data.gouv.fr/api/1/datasets/finess-extraction-du-fichier-des-etablissements/` lists
  * every resource with its URL, `last_modified`, `filesize` and a SHA-1 `checksum`. The establishment
- * extract is the resource whose file is named `etalab-cs1100502-stock-<date>-<time>.csv`; the
+ * extract is the resource whose file matches `etalab-cs1100502-stock-<date>-<time>.csv`. The
  * geolocated extract `etalab-cs1100507-…` and the history archive sit beside it and are not read.
  * {@linkcode selectFinessExtract} picks the newest establishment extract the record lists, so the
  * fetcher follows a republication without a code change.
@@ -27,12 +27,13 @@
  * decides, and the manifest records all three digests. A file that matches neither is an
  * interrupted transfer or an error page and is removed rather than recorded. The manifest records the SHA-256 the corpus tooling compares,
  * the resource's `last_modified`, and the extract's own first line (`finess;etalab;111;2026-05-12`),
- * which carries the extraction date Licence Ouverte's attribution names.
+ * That line states the extraction date Licence Ouverte's attribution requires.
  */
 
 import { APIClient } from "@mailwoman/core/api"
 import { ByteFormatter } from "@mailwoman/core/fs/formatters"
-import { readFileHead, readLocalBuffer, tryStat } from "@mailwoman/core/fs/readers"
+import { readFileHead, readLocalBuffer } from "@mailwoman/core/fs/readers"
+import { tryStat } from "@mailwoman/core/fs/readers/stat"
 import { makeDirectories, removePathIfPresent } from "@mailwoman/core/fs/writers"
 import { createHash, md5File, sha256File } from "@mailwoman/core/hash"
 import { stringifyJSON } from "@mailwoman/core/json"
@@ -48,12 +49,12 @@ import { downloadToFile, loadCollectionFiles, writeManifest } from "#tools/fetch
 export const FINESS_DATASET_SLUG = "finess-extraction-du-fichier-des-etablissements"
 
 /**
- * The dataset's API record, which lists its resources.
+ * The API record that lists the dataset's resources.
  */
 export const FINESS_DATASET_API_URL = `https://www.data.gouv.fr/api/1/datasets/${FINESS_DATASET_SLUG}/`
 
 /**
- * The dataset's page, which states the license.
+ * The page that states the dataset's license.
  */
 export const FINESS_DATASET_PAGE_URL = `https://www.data.gouv.fr/datasets/${FINESS_DATASET_SLUG}`
 
@@ -63,7 +64,7 @@ export const FINESS_DATASET_PAGE_URL = `https://www.data.gouv.fr/datasets/${FINE
 const ESTABLISHMENT_EXTRACT = /\/(etalab-cs1100502-stock-\d{8}-\d{4}\.csv)$/u
 
 /**
- * The opening of the extract's comment line, which an HTML error page does not have.
+ * The opening of the extract's comment line.
  */
 const EXTRACT_HEADER = "finess;"
 
@@ -98,7 +99,7 @@ export interface FinessExtractManifest extends SourceManifest {
 	 */
 	dataset_license: string | null
 	/**
-	 * The extract's first line, which ends with the extraction date.
+	 * The extract's first line, ending with the extraction date.
 	 */
 	extract_header: string
 	/**
@@ -156,7 +157,7 @@ export function selectFinessExtract(dataset: DataGouvDataset): DataGouvResource
 export async function readFinessDataset(client: Pick<APIClient, "fetch">): Promise<DataGouvDataset> {
 	const { data } = await client.fetch<DataGouvDataset | string>({ url: FINESS_DATASET_API_URL })
 
-	if (typeof data !== "object" || data === null || !Array.isArray(data.resources)) {
+	if (typeof data !== "object" || !data || !Array.isArray(data.resources)) {
 		throw new Error(`${FR_FINESS_ADAPTER_ID}: ${FINESS_DATASET_API_URL} did not answer a dataset record`)
 	}
 
@@ -164,7 +165,7 @@ export async function readFinessDataset(client: Pick<APIClient, "fetch">): Promi
 }
 
 /**
- * The SHA-1 of a file, which is the digest data.gouv.fr publishes for a resource.
+ * A file's SHA-1, the digest data.gouv.fr publishes for a resource.
  */
 async function sha1File(path: PathBuilderLike): Promise<string> {
 	return createHash("sha1")
@@ -257,11 +258,11 @@ export async function downloadFinessExtract(
 
 		bytes = written.bytes
 	} catch (error) {
-		return await fail(`download failed: ${error instanceof Error ? error.message : String(error)}`)
+		return fail(`download failed: ${error instanceof Error ? error.message : String(error)}`)
 	}
 
 	if (typeof resource.filesize === "number" && resource.filesize !== bytes) {
-		return await fail(`the record states ${resource.filesize} bytes and ${bytes} arrived`)
+		return fail(`the record states ${resource.filesize} bytes and ${bytes} arrived`)
 	}
 
 	const sha1 = await sha1File(dest)
@@ -274,7 +275,7 @@ export async function downloadFinessExtract(
 		const md5 = await md5File(dest)
 
 		if (servedMD5 !== md5) {
-			return await fail(
+			return fail(
 				`SHA-1 ${sha1} differs from the record's ${resource.checksum.value}, ` +
 					`and MD5 ${md5} differs from the served ETag ${servedMD5 ?? "(absent)"}`
 			)
@@ -290,7 +291,7 @@ export async function downloadFinessExtract(
 	const header = head.split(/\r?\n/u)[0] ?? ""
 
 	if (!header.startsWith(EXTRACT_HEADER)) {
-		return await fail(`the file opens with ${stringifyJSON(header.slice(0, 40))}, not the extract's comment line`)
+		return fail(`the file opens with ${stringifyJSON(header.slice(0, 40))}, not the extract's comment line`)
 	}
 
 	const entry: FinessExtractManifest = {