@mailwoman/corpus 10.1.0 → 10.2.0

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

@@ -6,17 +6,17 @@
  *   Harvests the INSPIRE Addresses theme the Diputación Foral de Bizkaia publishes into the
  *   directory `#es/adapters/bizkaia/adapter` reads.
  *
- *   ## Two services, because the archives carry addresses alone
+ *   ## Two services, because the archives hold only addresses
  *
  *   The ATOM download service at `https://apli.bizkaia.eus/apps/Danok/INSPIRE/addresses.xml` lists
  *   one entry per municipality, each offering that municipality's addresses as a zipped GML through a
  *   `rel="enclosure"` link. Those archives hold no `ad:ThoroughfareName`, `ad:PostalDescriptor` or
  *   `ad:AdminUnitName` feature: every `ad:component` reference an address writes is a stored-query
- *   URL on the publisher's WFS, which the ATOM service does not republish. An adapter handed the
- *   archives alone therefore reads every address in the province without its street, its postcode or
- *   its municipality, which is why this harvest acquires both services into one directory.
+ *   URL on the publisher's WFS that the ATOM service does not republish. An adapter handed only those
+ *   archives therefore reads every address in the province without its street, its postcode or
+ *   its municipality. This harvest acquires both services into one directory for that reason.
  *
- *   Each component type is read in one request, which is the only way this service serves it. Its
+ *   Each component type is read in one request, and that is the only way this service serves it. Its
  *   capabilities document states `ImplementsResultPaging` as `FALSE` and `CountDefault` as `1000`, so
  *   a reader that paged a type would receive the first page again. The harvest therefore asks
  *   `RESULTTYPE=hits` for the type's count and then asks for that many features in one `GetFeature`,
@@ -24,7 +24,7 @@
  *   count. A truncated component document is the failure that would otherwise reach the adapter as
  *   an unresolved reference per address.
  *
- *   A component document's own bytes are not reproducible. Its `wfs:FeatureCollection` carries a
+ *   A component document's own bytes are not reproducible. Its `wfs:FeatureCollection` holds a
  *   `timeStamp` attribute holding the moment of the request, so two identical harvests differ in
  *   that element and therefore in their digests. The manifest records each document's byte count and
  *   sha256 as what arrived, never as a value a later run compares against.
@@ -44,7 +44,7 @@
  *   The component documents state no version at all. The WFS answers them under `Cache-Control:
  *   no-cache` with no `Last-Modified`, so a run holds no value to compare and every run that
  *   harvests them downloads them again. {@linkcode HarvestESBizkaiaOptions.components} is how a run that wants
- *   the archives alone declines the 14 MB.
+ *   only the archives declines the 14 MB.
  */
 
 /* oxlint-disable sister-software/prefer-region-over-marks -- these markers label steps inside one
@@ -52,7 +52,7 @@
 
 import { APIClient, assertNoOGCServiceException, readWFSFeatureCount } 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, writeLocalFile } from "@mailwoman/core/fs/writers"
 import { sha256File, sha256Hex } from "@mailwoman/core/hash"
 import { rootAttribute } from "@mailwoman/core/html/document"
@@ -74,8 +74,8 @@ export const ES_BIZKAIA_SERVICE_URL = "https://apli.bizkaia.eus/apps/Danok/INSPI
 /**
  * The WFS the municipality archives reference their components on.
  *
- * Read from the `xlink:href` the archives themselves write, which addresses this
- * endpoint through the `GetFeatureById` stored query.
+ * Read from the `xlink:href` the archives themselves write.
+ * That link addresses this endpoint through the `GetFeatureById` stored query.
  */
 export const ES_BIZKAIA_WFS_URL =
 	"https://geo.bizkaia.eus/arcgisserverinspire/rest/services/Catastro/Annex1/MapServer/exts/InspireFeatureDownload/service"
@@ -115,8 +115,8 @@ export const ES_BIZKAIA_REQUEST_INTERVAL_MS = 250
 /**
  * Per-request timeout for a body, in milliseconds.
  *
- * Ten minutes, which covers both a municipality archive and the one component
- * document that carries every street in the province.
+ * Ten minutes.
+ * That covers both a municipality archive and the one component document with every street in the province.
  */
 const BODY_TIMEOUT_MS = 600_000
 
@@ -174,7 +174,8 @@ export interface ESBizkaiaMunicipalityDataset {
 	 */
 	downloadURL: string
 	/**
-	 * The file name the archive is written under, which is what the adapter globs.
+	 * The file name the archive is written under.
+	 * The adapter globs this name.
 	 */
 	filename: string
 }
@@ -187,9 +188,9 @@ export interface ESBizkaiaMunicipalityDataset {
  * the archive is stored under: a disagreement between the publisher's two statements of
  * a municipality would store one municipality's addresses under another's name.
  *
- * @throws When the feed lists no entry, when an entry states neither spelling of its municipality,
- * when the two spellings disagree, when two entries claim one file name — which would make
- * one archive overwrite the other — or when an entry carries no `rel="enclosure"` link.
+ * @throws When the feed lists no entry, when an entry states neither spelling of its
+ * municipality, when the two spellings disagree, when two entries claim one file name
+ * and one archive would overwrite the other, or when an entry has no `rel="enclosure"` link.
  */
 export function readESBizkaiaServiceFeed(feed: AtomFeed): readonly ESBizkaiaMunicipalityDataset[] {
 	if (!feed.entries.length) {
@@ -220,7 +221,7 @@ export function readESBizkaiaServiceFeed(feed: AtomFeed): readonly ESBizkaiaMuni
 			)
 		}
 
-		// The identifier carries the three-digit tail of the five-digit municipality code:
+		// The identifier holds the three-digit tail of the five-digit municipality code:
 		// `48915` is published as `ES.BFA.AD.915.zip`.
 		if (!fromTitle.endsWith(identified[2]!)) {
 			throw new Error(
@@ -288,8 +289,9 @@ export interface ESBizkaiaComponentEntry extends SourceManifest {
 	 */
 	feature_count: number
 	/**
-	 * The `numberReturned` the saved document states, which the harvest requires to
-	 * equal {@linkcode ESBizkaiaComponentEntry.feature_count}.
+	 * The `numberReturned` the saved document states.
+	 *
+	 * The harvest requires it to equal {@linkcode ESBizkaiaComponentEntry.feature_count}.
 	 */
 	features_returned: number
 }
@@ -311,7 +313,7 @@ export interface ESBizkaiaHarvestManifest extends SourceCollectionManifest {
 	municipalities_listed: number
 	files: ESBizkaiaArchiveEntry[]
 	/**
-	 * The saved WFS documents, kept apart from `files` because they carry no
+	 * The saved WFS documents, kept apart from `files` because they have no
 	 * municipality and no stated version.
 	 */
 	components: ESBizkaiaComponentEntry[]
@@ -319,12 +321,12 @@ export interface ESBizkaiaHarvestManifest extends SourceCollectionManifest {
 
 export interface HarvestESBizkaiaOptions {
 	/**
-	 * Where the archives, the component documents and the manifest are written,
-	 * which is the adapter's `inputPath`.
+	 * Where the archives, the component documents and the manifest are written.
+	 * This path is the adapter's `inputPath`.
 	 */
 	outputDir: PathBuilderLike
 	/**
-	 * Harvest only these five-digit municipality codes, for a probe or for a repair of named ones.
+	 * Harvest only these five-digit municipality codes, for a probe or to repair specific ones.
 	 *
 	 * A code the service document does not list is reported as a failure rather than ignored.
 	 */
@@ -335,10 +337,11 @@ export interface HarvestESBizkaiaOptions {
 	limit?: number
 	/**
 	 * Save the WFS component documents as well as the archives.
-	 * Defaults to true.
 	 *
 	 * An adapter run needs them: an archive references its street, its postcode
-	 * and its municipality and carries none of the three.
+	 * and its municipality and has none of the three.
+	 *
+	 * @defaultValue `true`
 	 */
 	components?: boolean
 	/**
@@ -348,7 +351,7 @@ export interface HarvestESBizkaiaOptions {
 	/**
 	 * 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`.
+	 * The default compares the recorded byte count against the file's size, one `stat`.
 	 */
 	verifyDigests?: boolean
 	signal?: AbortSignal
@@ -364,7 +367,7 @@ export interface HarvestESBizkaiaOptions {
  * so a service that stops stating a version is re-fetched rather than frozen.
  */
 async function archiveIsCurrent(
-	recorded: ESBizkaiaArchiveEntry | undefined,
+	recorded: ESBizkaiaArchiveEntry | null,
 	dataset: ESBizkaiaMunicipalityDataset,
 	path: PathBuilderLike,
 	verifyDigests: boolean
@@ -377,7 +380,8 @@ async function archiveIsCurrent(
 
 	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.
+	// It is opt-in.
 	if (!verifyDigests) return true
 
 	return (await sha256File(path)) === recorded.sha256
@@ -433,7 +437,7 @@ export async function fetchBizkaiaComponentDocument(
 	// count is read from `numberReturned` and compared against the hits request's figure.
 	const returned = rootAttribute(document, "numberReturned", { xml: true })
 
-	if (returned === undefined || !/^\d+$/u.test(returned)) {
+	if (!returned || !/^\d+$/u.test(returned)) {
 		throw new Error(
 			`${context}: the GetFeature response states numberReturned=${stringifyJSON(returned ?? null)} rather than ` +
 				`a count, so what the document holds against the ${featureCount} features the service matched is unknown`
@@ -514,8 +518,8 @@ export async function harvestESBizkaia(
 	const recordedManifest = await readManifest<ESBizkaiaHarvestManifest>(manifestPath)
 	const files = new Map<string, ESBizkaiaArchiveEntry>()
 
-	// An entry for a municipality this run does not consider is carried through,
-	// so a bounded run never drops what an earlier run recorded.
+	// An entry for a municipality 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 ESBizkaiaArchiveEntry)
 	}
@@ -558,7 +562,7 @@ export async function harvestESBizkaia(
 
 		if (
 			!options.force &&
-			(await archiveIsCurrent(files.get(dataset.filename), dataset, dest, options.verifyDigests ?? false))
+			(await archiveIsCurrent(files.get(dataset.filename) ?? null, dataset, dest, options.verifyDigests ?? false))
 		) {
 			skipped++
 
@@ -625,7 +629,7 @@ export async function harvestESBizkaia(
 }
 
 /**
- * The municipalities this run considers, and the codes a caller named that the feed does not list.
+ * The municipalities this run considers, and the codes a caller asked for that the feed does not list.
  *
  * A code the caller asked for and the service document does not list is returned
  * rather than dropped, because a municipality that is not published is a different
@@ -695,8 +699,8 @@ async function fetchArchive(
 /**
  * The path `#es/adapters/bizkaia/adapter` reads, given the root a fetch wrote under.
  *
- * The directory rather than a file: the adapter reads every archive and every saved WFS
- * document under it, and it is the component documents that carry the streets.
+ * The directory rather than a file: the adapter reads every archive and every saved
+ * WFS document under it, and the component documents hold the streets.
  */
 export function esBizkaiaInputPath(outRoot: BaseFetchOptions["outRoot"]): PathBuilderLike {
 	return outRoot(ES_BIZKAIA_ADAPTER_ID)
@@ -712,7 +716,7 @@ export interface FetchESBizkaiaOptions
 	/**
 	 * The minimum spacing between two requests, in milliseconds.
 	 *
-	 * Defaults to {@linkcode ES_BIZKAIA_REQUEST_INTERVAL_MS}.
+	 * @defaultValue {@linkcode ES_BIZKAIA_REQUEST_INTERVAL_MS}
 	 */
 	minRequestIntervalMs?: number
 }

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

@@ -27,16 +27,16 @@
  *    excluding three names. A feed that renames its offices then matches zero titles and raises.
  * 2. **A province feed declares ISO-8859-1 and means it, while the national feed declares UTF-8.**
  *    `ES.SDGC.ad.atom_15.xml` writes A Coruña's directory name with the byte `0xD1` for `Ñ`.
- *    Decoding that feed as UTF-8 yields U+FFFD, and the URL built from the replacement character
- *    answers an html error page under http 200 rather than the archive. So both levels are read as
- *    bytes and decoded through {@linkcode decodeDeclaredXML}, which reads each document's own
- *    declaration.
+ *    A UTF-8 decode of that feed yields U+FFFD. The URL built from the replacement character then
+ *    answers an html error page under http 200 rather than the archive. Both levels are therefore
+ *    read as bytes and decoded through {@linkcode decodeDeclaredXML}. That function reads each
+ *    document's own declaration.
  * 3. **An archive URL cannot be composed, and the href it is read from is not request-ready.** The
  *    directory segment is the municipality's own name, so Madrid sits under `28900-MADRID` while
  *    the composable `28079` answers an html page. The publisher writes that segment with literal
  *    spaces and with non-ASCII letters, and {@linkcode archiveRequestURL} percent-encodes both.
  * 4. **The municipality code is stated twice, and the two are checked against each other.** An
- *    entry's title reads `55101-CEUTA addresses` and its archive is named
+ *    entry's title reads `55101-CEUTA addresses` and its archive file is
  *    `A.ES.SDGC.AD.55101.zip`. The file keeps the publisher's own name rather than one built from
  *    the code, so the code decides which entry is read and never where the file lands. A
  *    disagreement between the publisher's two statements of it is a change in the feed's layout
@@ -62,7 +62,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 { decodeBytes } from "@mailwoman/core/fs/streams"
 import { makeDirectories } from "@mailwoman/core/fs/writers"
 import { sha256File } from "@mailwoman/core/hash"
@@ -77,7 +77,7 @@ import { loadCollectionFiles, writeManifest } from "#tools/fetch/download"
 import { downloadZipArchive } from "#tools/fetch/zip-archive"
 
 /**
- * The national ATOM service document, which lists one province feed per territorial office.
+ * The national ATOM service document that lists one province feed per territorial office.
  */
 export const ES_CATASTRO_SERVICE_FEED_URL = "https://www.catastro.hacienda.gob.es/INSPIRE/Addresses/ES.SDGC.AD.atom.xml"
 
@@ -100,7 +100,7 @@ export const ES_CATASTRO_ATTRIBUTION = "Dirección General del Catastro (Ministe
 export const ES_CATASTRO_REQUEST_INTERVAL_MS = 250
 
 /**
- * The directory the harvest writes under, which is the adapter's `inputPath`.
+ * The directory the harvest writes under and the adapter reads as `inputPath`.
  */
 const SLUG = ES_CATASTRO_ADAPTER_ID
 
@@ -126,8 +126,8 @@ const DECLARED_ENCODING = /<\?xml[^>]*encoding="([^"]+)"/iu
 /**
  * A national entry's title, `Territorial office 02 Albacete`.
  *
- * The three entries belonging to the foral cadastres are titled `Provincial Council of <name>`
- * and do not match, which is how they are left to their own adapters.
+ * The three foral-cadastre entries are titled `Provincial Council of <name>` and do not match.
+ * Their own adapters read those feeds.
  */
 const TERRITORIAL_OFFICE_TITLE = /^Territorial office\s+(\d{2})\s+(\S.*)$/u
 
@@ -151,7 +151,8 @@ const ARCHIVE_FILENAME = /^A\.ES\.SDGC\.AD\.(\d{5})\.zip$/iu
  *
  * The national feed declares UTF-8 and a province feed declares ISO-8859-1, so a reader
  * that fixed either encoding would mojibake the other publisher's accented place names.
- * A document that declares no encoding is decoded as UTF-8, which is what XML's own default states.
+ * A document that declares no encoding is decoded as UTF-8.
+ * XML states that default.
  */
 export function decodeDeclaredXML(bytes: Uint8Array): string {
 	const head = Buffer.from(bytes.subarray(0, DECLARATION_WINDOW)).toString("latin1")
@@ -164,7 +165,8 @@ export function decodeDeclaredXML(bytes: Uint8Array): string {
  *
  * A province feed writes a municipality's directory segment as the publisher spells it,
  * with literal spaces and with non-ASCII letters: `…/15/15900-A CORUÑA/A.ES.SDGC.AD.15900.zip`.
- * `URL` percent-encodes both, which is what the host serves the archive at.
+ * `URL` percent-encodes both.
+ * The host serves the archive at that encoded form.
  */
 export function archiveRequestURL(href: string): string {
 	return new URL(href).toString()
@@ -175,7 +177,9 @@ export function archiveRequestURL(href: string): string {
  */
 export interface ESCatastroProvince {
 	/**
-	 * The two-digit province code, which is also the first two digits of each of its municipality codes.
+	 * The two-digit province code.
+	 *
+	 * Each municipality code under it starts with these two digits.
 	 */
 	code: string
 	/**
@@ -184,7 +188,8 @@ export interface ESCatastroProvince {
 	name: string
 	title: string
 	/**
-	 * This office's province feed, which lists one archive per municipality.
+	 * This office's province feed.
+	 * It lists one archive per municipality.
 	 */
 	provinceFeedURL: string
 	/**
@@ -216,8 +221,9 @@ export interface ESCatastroMunicipalityDataset {
 	 */
 	updated: 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.
+	 *
+	 * It is the publisher's own name and the file the adapter globs.
 	 */
 	filename: string
 }
@@ -226,7 +232,7 @@ export interface ESCatastroMunicipalityDataset {
  * The territorial offices the national service document lists.
  *
  * @throws When the document holds no entry, when it holds no territorial-office entry at all,
- * when an office carries no province-feed link, or when two offices claim one province code.
+ * when an office has no province-feed link, or when two offices claim one province code.
  * Each of those would otherwise write zero archives while reporting a completed run.
  */
 export function readESCatastroServiceFeed(feed: AtomFeed): readonly ESCatastroProvince[] {
@@ -264,7 +270,7 @@ export function readESCatastroServiceFeed(feed: AtomFeed): readonly ESCatastroPr
 
 		const fromHref = PROVINCE_FEED_CODE.exec(link.href)?.[1]
 
-		if (fromHref !== undefined && fromHref !== code) {
+		if (fromHref && fromHref !== code) {
 			throw new Error(
 				`${ES_CATASTRO_SERVICE_FEED_URL}: the entry titled ${stringifyJSON(entry.title)} states province ` +
 					`${code} in its title and links ${link.href}, which names province ${fromHref}`
@@ -303,9 +309,9 @@ export function readESCatastroServiceFeed(feed: AtomFeed): readonly ESCatastroPr
 /**
  * The municipalities one province feed lists.
  *
- * @throws When the feed holds no entry, when an entry carries no archive link,
- * when the municipality code its title states disagrees with the one its archive
- * is named for, or when two entries name one archive.
+ * @throws When the feed holds no entry, when an entry has no archive link,
+ * when the municipality code its title states disagrees with the code in its archive
+ * file name, or when two entries reference one archive.
  */
 export function readESCatastroProvinceFeed(
 	feed: AtomFeed,
@@ -331,8 +337,8 @@ export function readESCatastroProvinceFeed(
 			)
 		}
 
-		// The publisher's own file name, taken off the href before it is percent-encoded,
-		// so the file on disk is named the way the feed names it.
+		// The publisher's own file name, taken off the href before percent-encoding,
+		// so the file on disk keeps the publisher's spelling.
 		const filename = link.href.slice(link.href.lastIndexOf("/") + 1)
 		const fromFilename = ARCHIVE_FILENAME.exec(filename)?.[1]
 
@@ -395,7 +401,7 @@ export interface ESCatastroArchiveEntry extends SourceManifest {
 	/**
 	 * The `<updated>` the province feed stated when this archive was fetched.
 	 *
-	 * A later run that reads the same value for this municipality leaves the file alone.
+	 * A later run that reads the same value for this municipality reuses the file.
 	 * The publisher moves it when it publishes a new edition.
 	 */
 	feed_updated: string
@@ -429,7 +435,8 @@ export interface ESCatastroHarvestManifest extends SourceCollectionManifest {
 
 export interface HarvestESCatastroOptions {
 	/**
-	 * 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 this directory as `inputPath`.
 	 */
 	outputDir: PathBuilderLike
 	/**
@@ -452,7 +459,8 @@ export interface HarvestESCatastroOptions {
 	/**
 	 * 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`.
+	 * The default compares the recorded byte count against the file's size.
+	 * That check costs one `stat`.
 	 */
 	verifyDigests?: boolean
 	signal?: AbortSignal
@@ -463,11 +471,13 @@ export interface HarvestESCatastroOptions {
  * Whether the archive recorded for one municipality is still the one the province 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.
+ *
+ * An equality test would then match, keeping an archive of unknown age for
+ * as long as the feed stayed silent.
  */
 async function isCurrent(
-	recorded: ESCatastroArchiveEntry | undefined,
+	recorded: ESCatastroArchiveEntry | null,
 	dataset: ESCatastroMunicipalityDataset,
 	path: PathBuilderLike,
 	verifyDigests: boolean
@@ -478,7 +488,8 @@ 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.
+	// That cost is why it is opt-in.
 	if (!verifyDigests) return true
 
 	return (await sha256File(path)) === recorded.sha256
@@ -504,11 +515,11 @@ async function readFeed(
 	// A feed shares the http 200 an exception report arrives on.
 	assertNoOGCServiceException(text, options.context)
 
-	return await readAtomFeed(feedChunks(text))
+	return readAtomFeed(feedChunks(text))
 }
 
 /**
- * The provinces this run reads, and the codes a caller named that the service document does not list.
+ * The provinces this run reads, and the codes a caller requested that the service document omits.
  */
 function selectProvinces(
 	listed: readonly ESCatastroProvince[],
@@ -578,8 +589,8 @@ export async function harvestESCatastro(
 	const previous = await loadCollectionFiles(manifestPath)
 	const files = new Map<string, ESCatastroArchiveEntry>()
 
-	// An entry for a municipality this run does not consider is carried through,
-	// so a bounded run never drops what an earlier run recorded.
+	// The harvest keeps an entry for a municipality this run skips, so a bounded
+	// run never drops what an earlier run recorded.
 	for (const [filename, entry] of previous) {
 		files.set(filename, entry as ESCatastroArchiveEntry)
 	}
@@ -589,7 +600,7 @@ export async function harvestESCatastro(
 	let municipalitiesListed = 0
 	let provincesHarvested = 0
 	const failedCodes: string[] = [...provinces.unknown]
-	const requested = options.municipalities === undefined ? undefined : new Set(options.municipalities)
+	const requested = options.municipalities ? new Set(options.municipalities) : undefined
 	const found = new Set<string>()
 
 	const writeHarvestManifest = async (): Promise<void> => {
@@ -641,7 +652,7 @@ export async function harvestESCatastro(
 
 			const dest = destDir(dataset.filename)
 
-			if (await isCurrent(files.get(dataset.filename), dataset, dest, options.verifyDigests ?? false)) {
+			if (await isCurrent(files.get(dataset.filename) ?? null, dataset, dest, options.verifyDigests ?? false)) {
 				skipped++
 
 				continue
@@ -683,9 +694,9 @@ export async function harvestESCatastro(
 		}
 	}
 
-	// A municipality a caller named and no selected province feed listed is reported
-	// rather than dropped, because a municipality that is not published is a different
-	// condition from a selection that holds no municipality.
+	// A municipality a caller requested and no selected province feed listed is reported rather than dropped.
+	// A municipality that is not published is a different condition from a
+	// selection that lists no municipality.
 	for (const code of requested ?? []) {
 		if (found.has(code)) continue
 
@@ -719,7 +730,7 @@ export interface FetchESCatastroOptions
 	/**
 	 * The minimum spacing between two requests, in milliseconds.
 	 *
-	 * Defaults to {@linkcode ES_CATASTRO_REQUEST_INTERVAL_MS}.
+	 * @defaultValue {@linkcode ES_CATASTRO_REQUEST_INTERVAL_MS}
 	 */
 	minRequestIntervalMs?: number
 }

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

@@ -14,7 +14,7 @@
  *
  *       addresses.xml  →  GML/ES.GFA.AD.zip
  *
- *   That entry links its dataset through `rel="alternate"`. It carries no `rel="enclosure"` link at
+ *   That entry links its dataset through `rel="alternate"`. It holds no `rel="enclosure"` link at
  *   all, and the `rel="describedby"` link beside the alternate is the ISO 19139 metadata record. A
  *   reader that looks for an enclosure therefore finds no dataset here, and a reader that takes the
  *   first link of any relation downloads the metadata record instead of 7,959,103 bytes of
@@ -28,7 +28,7 @@
  *   keep one archive forever. The archive's HTTP `last-modified` is the signal this fetcher compares,
  *   and {@linkcode gipuzkoaPublicationIsRecorded} requires the publisher to state one before it
  *   agrees to skip a download. The feed's value is recorded beside it, unused, because it is what
- *   the publisher says about the dataset.
+ *   the publisher states about the dataset.
  *
  *   ## Why the archive stays compressed
  *
@@ -39,7 +39,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"
@@ -55,7 +55,8 @@ import { downloadToFile, readManifest, writeManifest } from "#tools/fetch/downlo
 export const ES_GIPUZKOA_SERVICE_URL = "https://b5m.gipuzkoa.eus/inspire/download/addresses.xml"
 
 /**
- * The name the archive is written under, which is what the adapter's `inputPath` states.
+ * The name the archive is written under.
+ * The adapter's `inputPath` states that name.
  */
 export const ES_GIPUZKOA_ARCHIVE_FILENAME = "ES.GFA.AD.zip"
 
@@ -104,7 +105,7 @@ export interface DownloadGipuzkoaOptions {
 export interface GipuzkoaArchiveReference {
 	archiveURL: string
 	/**
-	 * The entry's title, which states the theme rather than a municipality.
+	 * The entry's title states the theme rather than a municipality.
 	 */
 	entryTitle: string
 	/**
@@ -116,7 +117,7 @@ export interface GipuzkoaArchiveReference {
 /**
  * Resolves the download service to the one archive its single entry links.
  *
- * Raises where the feed lists no entry, and where the entry carries no `rel="alternate"` link.
+ * Raises where the feed lists no entry, and where the entry holds no `rel="alternate"` link.
  * The alternative would return `{fetched: 0, skipped: 0, failed: 0}`, which a caller
  * reads as a fetch that completed and found the publisher empty.
  *
@@ -176,8 +177,9 @@ export async function resolveGipuzkoaArchive(
  * What the publisher's HEAD response states about the archive it holds.
  *
  * Both fields read `null` where the header is absent, rather than an empty string or zero.
- * An absent `last-modified` is the service declining to state a version, which is a
- * different fact from a version that happens to match the one on disk.
+ * An absent `last-modified` is the service declining to state a version.
+ *
+ * That differs from a version that happens to match the one on disk.
  */
 export interface GipuzkoaPublication {
 	lastModified: string | null
@@ -188,7 +190,7 @@ export interface GipuzkoaPublication {
  * Reads the publisher's HEAD response for one archive URL.
  *
  * Separate from {@linkcode downloadGipuzkoa} for the same reason {@linkcode resolveGipuzkoaArchive}
- * is: this request carries the whole freshness decision.
+ * is: this request holds the whole freshness decision.
  */
 export async function readGipuzkoaPublication(
 	client: Pick<APIClient, "fetch">,
@@ -215,7 +217,7 @@ export async function readGipuzkoaPublication(
  * Whether the archive on disk is the one the publisher now serves.
  *
  * A publisher that states no `last-modified` answers false.
- * Comparing an absent header against an absent recorded value makes `null === null` hold,
+ * An absent header compared against an absent recorded value makes `null === null` hold,
  * and that reading keeps a stale archive for as long as the service stays silent.
  */
 export function gipuzkoaPublicationIsRecorded(
@@ -223,7 +225,7 @@ export function gipuzkoaPublicationIsRecorded(
 	bytesOnDisk: number,
 	publication: GipuzkoaPublication
 ): boolean {
-	if (publication.lastModified === null) return false
+	if (!publication.lastModified) return false
 
 	return recorded.last_modified === publication.lastModified && recorded.bytes === bytesOnDisk
 }