@mailwoman/corpus 10.0.0 → 10.2.0

package/lib/tools/fetch/download/network.ts

@@ -9,7 +9,7 @@
 import { openWriteStream, pipeline, Readable } from "@mailwoman/core/fs/streams"
 import { writeLocalFile } from "@mailwoman/core/fs/writers"
 import { sleep } from "@mailwoman/core/utils/sleep"
-import type { PathBuilderLike } from "path-ts"
+import type { PathBuilder, PathBuilderLike } from "path-ts"
 
 /**
  * Rate limited — retryable, the server is asking us to back off.
@@ -17,7 +17,9 @@ import type { PathBuilderLike } from "path-ts"
 const HTTP_TOO_MANY_REQUESTS = 429
 
 /**
- * Lowest 5xx status. Server-side failures are retryable; 4xx are not.
+ * Lowest 5xx status.
+ *
+ * Server-side failures are retryable. 4xx are not.
  */
 const HTTP_SERVER_ERROR_MIN = 500
 
@@ -36,21 +38,29 @@ export const DEFAULT_RETRY_DELAY_MS = 5000
 
 export interface BaseFetchOptions {
 	/**
-	 * Destination root for downloaded source data. Each source writes its own subdirectory.
+	 * Destination root for downloaded source data.
+	 *
+	 * Each source writes its own subdirectory.
 	 */
-	outRoot: PathBuilderLike
+	outRoot: PathBuilder
 	/**
-	 * Pause between transfer retries, in milliseconds. Defaults to {@linkcode DEFAULT_RETRY_DELAY_MS}.
+	 * Pause between transfer retries, in milliseconds.
+	 *
+	 * @defaultValue {@linkcode DEFAULT_RETRY_DELAY_MS}
 	 *
-	 * A test that exercises the failure path pays this delay once per retry in real time — measured at 20.1 s for the two
-	 * failing-transfer cases in `geonames-postal.test.ts`, which is the whole cost of that file. The retry COUNT is the
-	 * behaviour under test there; the pause between attempts is not, so it is a caller's to shorten.
+	 * A test that exercises the failure path pays this delay once per retry in real time.
+	 * Measured at 20.1 s for the two failing-transfer cases in `geonames-postal.test.ts`,
+	 * which is the whole cost of that file.
+	 * The retry count is the behavior under test there.
+	 *
+	 * The pause between attempts is not, so it is a caller's to shorten.
 	 */
 	retryDelayMs?: number
 }
 
 /**
- * The per-run result every fetch module returns; the command maps `failed > 0` to exit code 1.
+ * The per-run result every fetch module returns.
+ * The command maps `failed > 0` to exit code 1.
  */
 export interface FetchSummary {
 	fetched: number
@@ -60,8 +70,8 @@ export interface FetchSummary {
 }
 
 /**
- * The sibling `MANIFEST.json` shape the single-file fetch modules write: origin URL + fetch timestamp + byte count +
- * sha256, so downstream adapters can verify provenance.
+ * The sibling `manifest.json` shape the single-file fetch modules write: origin URL +
+ * fetch timestamp + byte count + sha256, so downstream adapters can verify provenance.
  */
 export interface SourceManifest {
 	source_url: string
@@ -75,11 +85,15 @@ export interface SourceManifest {
  * A status worth retrying: rate limiting or a server-side failure.
  */
 /**
- * An HTTP failure that CARRIES its status, so callers branch on `error.status` rather than on message prose. The prose
- * route shipped a real flake: a caller classified "not published upstream" with `message.includes("404")`, and the
- * message contains the URL — an ephemeral test-server port such as `:40453` satisfies it while the actual status is 500.
- * Roughly 1–2% of ephemeral ports contain the substring, which is exactly the kind of sometimes-failure that burns a CI
- * run and vanishes locally.
+ * An HTTP failure that includes its status, so callers branch on `error.status`
+ * rather than on message prose.
+ *
+ * The prose route shipped a real flake: a caller classified "not published upstream"
+ * with `message.includes("404")`, and the message contains the URL.
+ * An ephemeral test-server port such as `:40453` satisfies it while the actual status is 500.
+ *
+ * Roughly 1–2% of ephemeral ports contain the substring.
+ * That collision can fail a CI run and vanish locally.
  */
 export class HTTPStatusError extends Error {
 	readonly status: number
@@ -97,17 +111,23 @@ export function isTransientStatus(status: number): boolean {
 
 export interface DownloadOptions {
 	url: string
-	dest: string
+	dest: PathBuilderLike
 	/**
-	 * Per-attempt timeout. Default 10 minutes — these are multi-GB government dumps.
+	 * Per-attempt timeout.
+	 *
+	 * @defaultValue `10` minutes — these are multi-GB government dumps
 	 */
 	timeoutMs?: number
 	/**
-	 * Extra attempts after the first, taken only on transient statuses or network errors. Default 0.
+	 * Extra attempts after the first, taken only on transient statuses or network errors.
+	 *
+	 * @defaultValue `0`
 	 */
 	retries?: number
 	/**
-	 * Delay between attempts. Default 5s.
+	 * Delay between attempts.
+	 *
+	 * @defaultValue `5s`
 	 */
 	retryDelayMs?: number
 	headers?: Record<string, string>
@@ -115,8 +135,10 @@ export interface DownloadOptions {
 }
 
 /**
- * Download `url` to `dest` with per-attempt timeout and transient-status retry. Throws on a non-transient HTTP status
- * or once retries are exhausted. Returns the byte count written.
+ * Download `url` to `dest` with per-attempt timeout and transient-status retry.
+ *
+ * @throws On a non-transient http status or once retries are exhausted.
+ * Returns the byte count written.
  */
 export async function downloadToFile(options: DownloadOptions): Promise<{ bytes: number }> {
 	const {
@@ -140,9 +162,10 @@ export async function downloadToFile(options: DownloadOptions): Promise<{ bytes:
 		let res: Response
 
 		try {
-			// Raw `fetch`, deliberately: this is the shared FILE downloader and the body is piped to disk below.
-			// `APIClient` is the repo default for API requests — small bodies, repeated calls — and buffers a
-			// non-stream response in memory, which is the one thing a multi-gigabyte transfer must not do.
+			// Raw `fetch`, deliberately: this is the shared file downloader and the body is piped to disk below.
+			// `APIClient` is the repo default for API requests with small bodies and repeated calls.
+			// It buffers non-stream responses in memory.
+			// A multi-gigabyte transfer cannot use that path.
 			res = await fetch(url, { headers, signal: AbortSignal.timeout(timeoutMs) })
 		} catch (error) {
 			// AbortSignal timeouts and network-level failures are retryable.
@@ -182,14 +205,15 @@ export interface StreamDownloadOptions {
 }
 
 /**
- * Stream an HTTP download to disk, returning the final HTTP status (0 on network error after retries). Follows
- * redirects (the Census and OpenAddresses endpoints both 302 to their real hosts).
+ * Stream an http download to disk, returning the final http status (0 on network error after retries).
+ *
+ * Follows redirects (the Census and OpenAddresses endpoints both 302 to their real hosts).
  *
- * Kept separate from {@link downloadToFile} on purpose: this one streams a multi-GB body to disk (the buffered helper
- * reads via `arrayBuffer()`) and returns the HTTP status instead of throwing, which the per-file result collectors and
- * two-URL fallback ladders consume.
+ * Kept separate from {@link downloadToFile} on purpose: this one streams a multi-GB body to disk
+ * (the buffered helper reads via `arrayBuffer()`) and returns the HTTP status instead of throwing.
+ * Per-file result collectors and two-URL fallback ladders consume that result.
  */
-export async function streamDownload(url: string, dest: string, opts: StreamDownloadOptions): Promise<number> {
+export async function streamDownload(url: string, dest: PathBuilderLike, opts: StreamDownloadOptions): Promise<number> {
 	for (let attempt = 0; attempt <= opts.retries; attempt++) {
 		try {
 			const res = await fetch(url, {

package/lib/tools/fetch/download/retry.ts

@@ -5,29 +5,32 @@
  * @file Retries and resumes interrupted corpus downloads.
  */
 
-import { tryStat } from "@mailwoman/core/fs/readers"
+import { tryStat } from "@mailwoman/core/fs/readers/stat"
 import { openWriteStream, pipeline, Readable } from "@mailwoman/core/fs/streams"
 import { movePath } from "@mailwoman/core/fs/writers"
 import { sleep } from "@mailwoman/core/utils/sleep"
+import type { PathBuilderLike } from "path-ts"
 
 import { DEFAULT_RETRY_DELAY_MS, HTTPStatusError } from "#tools/fetch/download/network"
 
 /**
- * The answer to a range that starts at or past the end of the body: the resume point is already the whole file.
+ * The answer to a range that starts at or past the end of the body:
+ * the resume point is already the whole file.
  */
 const HTTP_RANGE_NOT_SATISFIABLE = 416
 
 /**
- * The answer to a satisfiable `Range` request; anything else means the host ignored the range and would send the whole
- * body again.
+ * The answer to a satisfiable `Range` request.
+ *
+ * Anything else means the host ignored the range and would send the whole body again.
  */
 const HTTP_PARTIAL_CONTENT = 206
 
 /**
- * Run one transfer up to `1 + retries` times, pausing `retryDelayMs` between attempts. A government portal drops a
- * multi-hundred-megabyte connection often enough that a collection fetch which lets the first `TypeError: terminated`
- * propagate loses the whole run to one file; the per-file loop calls the transfer through this and records the failure
- * only once the attempts are spent. The last error is rethrown so the caller can name the file it lost.
+ * Run one transfer up to `1 + retries` times, pausing `retryDelayMs` between attempts.
+ *
+ * A portal that drops a long connection would otherwise lose a whole collection fetch to one file.
+ * The last error is rethrown so the caller can name the file it lost.
  */
 export async function withRetries<T>(
 	transfer: () => Promise<T>,
@@ -52,9 +55,6 @@ export async function withRetries<T>(
 	throw lastError instanceof Error ? lastError : new Error(String(lastError))
 }
 
-/**
- * The byte count already at `path`, or 0 when nothing is there — the resume point of an interrupted range download.
- */
 async function bytesOnDisk(path: string): Promise<number> {
 	const stat = await tryStat(path)
 
@@ -62,16 +62,16 @@ async function bytesOnDisk(path: string): Promise<number> {
 }
 
 /**
- * Download `url` to `dest` in ranges, resuming from whatever the `.tmp` sibling already holds. For a host that drops a
- * long connection every few megabytes but answers `Range` with 206 (the Korean address portal does both, measured at
- * 0.9–12 MB per connection against a 181 MB file), a whole-body transfer never finishes and a plain retry starts over;
- * this one asks for the remainder each time and keeps what landed. The total comes from the first `Content-Range`, and
- * the loop gives up after `maxConnections` connections so a host that keeps answering 206 with no bytes cannot spin.
- * Answers the byte count written; throws when the host answers anything but 206 for a range.
+ * Download `url` to `dest` in ranges, resuming from whatever the `.tmp` sibling already holds.
+ *
+ * The total comes from the first `Content-Range`, and the loop gives up after `maxConnections`
+ * connections so a host that keeps answering 206 with no bytes cannot spin.
+ *
+ * Answers the byte count written and throws when the host answers anything but 206 for a range.
  */
 export async function resumableDownload(options: {
 	url: string
-	dest: string
+	dest: PathBuilderLike
 	headers?: Record<string, string>
 	maxConnections?: number
 	retryDelayMs?: number
@@ -80,10 +80,10 @@ export async function resumableDownload(options: {
 	const { url, dest, headers = {}, maxConnections = 400, retryDelayMs = DEFAULT_RETRY_DELAY_MS, report } = options
 	const tmp = dest + ".tmp"
 	let have = await bytesOnDisk(tmp)
-	let total: number | undefined
+	let total: number | null = null
 
 	for (let connection = 0; connection < maxConnections; connection++) {
-		if (total !== undefined && have >= total) break
+		if (total !== null && have >= total) break
 
 		let res: Response
 
@@ -96,8 +96,8 @@ export async function resumableDownload(options: {
 		}
 
 		if (res.status === HTTP_RANGE_NOT_SATISFIABLE && have > 0) {
-			// Nothing past `have`: the file on disk is already the whole body (a parallel filler or an earlier run
-			// landed it), and `Content-Range: bytes */<total>` says how long it is.
+			// The file on disk is already the whole body when no bytes follow `have`.
+			// `Content-Range: bytes */<total>` gives its length.
 			const whole = /\*\/(\d+)/.exec(res.headers.get("content-range") ?? "")?.[1]
 			total = whole ? Number(whole) : have
 			await res.body?.cancel()
@@ -118,13 +118,14 @@ export async function resumableDownload(options: {
 		const before = have
 
 		try {
-			// Append: the stream opens the file for appending so a partial body extends what earlier connections left.
 			await pipeline(
 				Readable.fromWeb(res.body as Parameters<typeof Readable.fromWeb>[0]),
 				openWriteStream(tmp, { flags: "a" })
 			)
 		} catch {
-			// The connection dropped mid-body; the bytes that landed are on disk, and the next range starts after them.
+			// The connection dropped mid-body.
+			// The received bytes remain on disk.
+			// The next range starts after them.
 		}
 
 		have = await bytesOnDisk(tmp)
@@ -136,7 +137,7 @@ export async function resumableDownload(options: {
 		}
 	}
 
-	if (total === undefined || have < total) {
+	if (total === null || have < total) {
 		throw new Error(`resumable download stalled at ${have} of ${total ?? "?"} bytes — ${url}`)
 	}
 
@@ -146,8 +147,8 @@ export async function resumableDownload(options: {
 }
 
 /**
- * The `Set-Cookie` values of a response folded into one `Cookie` header value, so a second request to the same portal
- * carries the session the first one opened.
+ * The `Set-Cookie` values of a response folded into one `Cookie` header,
+ * so a second request reuses the session the first opened.
  */
 export function cookieHeader(res: Response): string {
 	return res.headers
@@ -157,8 +158,8 @@ export function cookieHeader(res: Response): string {
 }
 
 /**
- * The file name a `Content-Disposition: attachment` header names, RFC 5987 form (`filename*=utf-8''…`) first, plain
- * `filename="…"` second, or `fallback` when the header carries neither.
+ * The file name a `Content-Disposition: attachment` header names, RFC 5987 form (`filename*=utf-8''…`)
+ * first, plain `filename="…"` second, or `fallback` when the header includes neither.
  */
 export function attachmentFilename(res: Response, fallback: string): string {
 	const disposition = res.headers.get("content-disposition") ?? ""

package/lib/tools/fetch/geonames/dump.ts

@@ -3,28 +3,30 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Fetch GeoNames per-country GAZETTEER dumps — the 19-column `<CC>.txt` files under
- *   `https://download.geonames.org/export/dump/` (NOT the postal exports; those are `export/zip/` and
- *   `geonames-postal.ts`'s job). The dumps carry feature classes and codes (column 8: `PPLC` national capital,
- *   `PPLA` first-order administrative seat), which is what the capitals reference build consumes (#1880).
+ *   Fetch GeoNames per-country gazetteer dumps. These are the 19-column `<CC>.txt` files under
+ *   `https://download.geonames.org/export/dump/`, the export directory rather than the postal export
+ *   at `export/zip/` that `geonames-postal.ts` handles. The dumps contain feature classes and codes
+ *   (column 8: `pplc` national capital, `ppla` first-order administrative seat), which is what the
+ *   capitals reference build consumes.
  *
- *   The catalog question is answered by the SOURCE, not by an ISO list: `countryInfo.txt` in the same directory
- *   enumerates every country GeoNames publishes, one row per ISO alpha-2 code, and also names each country's
- *   capital — the cross-check the capitals build grades its `PPLC` extraction against. Fetch that first; derive
- *   the country set from it; then a dump absent from disk is a measured gap against the source's own catalog
- *   rather than a silent hole. The dump directory may hold files this tool did not fetch: present files are never
- *   overwritten, and a present `<CC>.txt` that is NOT a 19-column gazetteer dump (GeoNames' postal exports share
- *   the basename) is reported as `wrong_format_present`, never counted as coverage.
+ *   `countryInfo.txt` supplies the country catalog. It lists each country GeoNames publishes with one
+ *   row per ISO alpha-2 code. Each row also lists the capital. The capitals build checks it against
+ *   its `pplc` extraction. The tool fetches this file first and derives the country set from it. A dump
+ *   absent from disk then counts as a gap in the source's own catalog.
+ *   The dump directory may contain files this tool never fetched. The tool keeps present files unchanged.
+ *   It checks each present `<CC>.txt` for the 19-column gazetteer format. GeoNames postal exports share
+ *   the basename, so a postal export receives `wrong_format_present` and does not count as coverage.
  */
 
-import { pathExists, readFileHead, readLocalBuffer, readLocalTextFile } from "@mailwoman/core/fs/readers"
+import { readFileHead, readLocalBuffer, readLocalTextFile } from "@mailwoman/core/fs/readers"
+import { pathExists } from "@mailwoman/core/fs/readers/stat"
 import { makeDirectories, removePathIfPresent } from "@mailwoman/core/fs/writers"
 import { extractZipEntry } from "@mailwoman/core/fs/zip"
 import { sha256File } from "@mailwoman/core/hash"
-import { join } from "path-ts"
+import { TSVSpliterator } from "spliterator"
 
-import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download/index"
-import { downloadToFile, HTTPStatusError, writeManifest } from "#tools/fetch/download/index"
+import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download"
+import { downloadToFile, HTTPStatusError, writeManifest } from "#tools/fetch/download"
 
 /**
  * The one status that means "the source does not publish this country" rather than "the transfer failed".
@@ -34,23 +36,30 @@ const HTTP_NOT_FOUND = 404
 const SLUG = "geonames-dump"
 
 /**
- * GeoNames' gazetteer-dump directory — one zip per ISO alpha-2 code holding `<CC>.txt`, plus `countryInfo.txt` as a
- * bare text file.
+ * GeoNames' gazetteer-dump directory — one zip per ISO alpha-2 code holding `<CC>.txt`,
+ * plus `countryInfo.txt` as a bare text file.
  */
 const BASE_URL = "https://download.geonames.org/export/dump"
 
 export interface FetchGeonamesDumpOptions extends BaseFetchOptions {
 	/**
-	 * ISO alpha-2 codes, any casing. Absent → every country `countryInfo.txt` enumerates.
+	 * ISO alpha-2 codes, any casing.
+	 *
+	 * Absent → every country `countryInfo.txt` enumerates.
 	 */
 	countries?: readonly string[]
 	/**
-	 * Dump directory to read from. Defaults to GeoNames' own; exists so the 404 and coverage behaviour can be exercised
-	 * against a local server.
+	 * Dump directory to read from.
+	 *
+	 * Exists so the 404 and coverage behavior can be exercised against a local server.
+	 *
+	 * @defaultValue GeoNames' own.
 	 */
 	baseURL?: string
 	/**
-	 * Refetch a dump whose `<CC>.txt` already exists. Default false — the tool fills gaps.
+	 * Refetch a dump whose `<CC>.txt` already exists.
+	 *
+	 * @defaultValue `false` — the tool fills gaps
 	 */
 	force?: boolean
 }
@@ -71,36 +80,43 @@ export interface GeonamesDumpManifest {
 	downloaded_at: string
 	files: GeonamesDumpFileEntry[]
 	/**
-	 * `<CC>.txt` files already on disk and left alone — the hand-fetched population this tool extends.
+	 * `<CC>.txt` files already on disk and leaves unchanged — the hand-fetched population this tool extends.
 	 */
 	skipped_present: string[]
 	/**
-	 * Countries in the source catalog that the source's dump directory nonetheless 404s — a fact about the source,
-	 * recorded so a later reader does not spend the fetch to rediscover it.
+	 * Countries in the source catalog that the source's dump directory nonetheless 404s.
+	 *
+	 * A fact about the source, recorded so a later reader does not spend the fetch to rediscover it.
 	 */
 	unavailable: string[]
 	/**
-	 * Present `<CC>.txt` files that are NOT 19-column gazetteer dumps — GeoNames' postal exports share the same basename,
-	 * and seven tier-1 postal files sat at these paths reading as "present" until the capitals build found them
-	 * capital-less. Left in place (this tool never overwrites data it did not fetch); the fix is to move the file to its
-	 * own home and rerun.
+	 * Present `<CC>.txt` files that are not 19-column gazetteer dumps.
+	 * GeoNames' postal exports share the same basename.
+	 *
+	 * Left in place (this tool never overwrites data it did not fetch).
+	 * The fix is to move the file to its own home and rerun.
 	 */
 	wrong_format_present: string[]
 }
 
 /**
- * Column count of a gazetteer dump row — the discriminator against GeoNames' 12-column postal exports, which share the
- * `<CC>.txt` basename.
+ * Column count of a gazetteer dump row.
+ *
+ * GeoNames postal exports have 12 columns and share the `<CC>.txt` basename.
  */
 const GAZETTEER_DUMP_COLUMNS = 19
 
 /**
- * True when the first non-empty line carries the gazetteer dump's 19 tab-separated columns. Accepts a partial head read
- * — the first line is the whole question, so callers need not hand it a resident 350 MB dump.
+ * True when the first non-empty line contains the gazetteer dump's 19 tab-separated columns.
+ *
+ * Accepts a partial head read.
+ * The first line is the whole question, so callers need not hand it a resident 350 MB dump.
+ *
+ * Walk the string directly instead of constructing a spliterator.
+ * The capitals builder already holds each country dump as a string.
  *
- * Walk the string directly rather than constructing a spliterator: the capitals builder already holds whole country
- * dumps as strings, and a byte-oriented spliterator would UTF-8 encode that input — allocating up to another 350 MB —
- * merely to inspect its first non-empty line.
+ * A byte-oriented spliterator would UTF-8 encode that input and allocate up to
+ * another 350 MB just to inspect the first non-empty line.
  */
 export function looksLikeGazetteerDump(text: string): boolean {
 	let start = 0
@@ -128,22 +144,19 @@ export function looksLikeGazetteerDump(text: string): boolean {
 }
 
 /**
- * Parse the ISO codes (column 1) and capital names (column 6) out of `countryInfo.txt` — `#`-prefixed lines are the
- * file's own commentary.
+ * Parse the ISO codes (column 1) and capital names (column 6) out of `countryInfo.txt`.
+ * `#`-prefixed lines are the file's own commentary.
  */
 export function parseCountryInfo(text: string): Array<{ country: string; capital: string }> {
 	const rows: Array<{ country: string; capital: string }> = []
 
-	// oxlint-disable-next-line mailwoman/prefer-spliterator -- countryInfo.txt is ~40 KB, one row per country on Earth; it cannot grow past that
-	for (const line of text.split("\n")) {
-		if (line.startsWith("#") || !line.trim()) continue
+	for (const cols of TSVSpliterator.from(text, { header: false, enableQuoteHandling: false })) {
+		const country = cols[0]?.toUpperCase()
 
-		// oxlint-disable-next-line mailwoman/prefer-spliterator -- one bounded 19-column catalog row
-		const cols = line.split("\t")
-		const country = cols[0]?.trim().toUpperCase()
+		if (!country || country.startsWith("#")) continue
 
-		if (country?.length === 2) {
-			rows.push({ country, capital: cols[5]?.trim() ?? "" })
+		if (country.length === 2) {
+			rows.push({ country, capital: cols[5] ?? "" })
 		}
 	}
 
@@ -151,14 +164,19 @@ export function parseCountryInfo(text: string): Array<{ country: string; capital
 }
 
 /**
- * Bytes read to classify a present file: enough to cover a first dump row whose alternate-names column runs long (they
- * reach several KB), a fraction of the largest dumps (US.txt is ~350 MB).
+ * Bytes read to classify a present file: enough to cover a first dump row whose alternate-names
+ * column runs long (they reach several KB), a fraction of the largest dumps (US.txt is ~350 MB).
  */
 const FORMAT_SNIFF_BYTES = 65_536
 
 /**
- * Download `countryInfo.txt` plus every missing `<CC>.zip`, extracting each to `<outRoot>/<CC>.txt` beside the
- * hand-fetched dumps, with a `MANIFEST.json` naming fetched, skipped-present, and source-unavailable countries.
+ * Download `countryInfo.txt` and each missing `<CC>.zip`.
+ *
+ * Extract each dump to `<outRoot>/<CC>.txt` beside the hand-fetched files.
+ * The `manifest.json` lists fetched countries.
+ *
+ * It also lists countries skipped because their files were already present
+ * and countries unavailable from the source.
  */
 export async function fetchGeonamesDumps(
 	options: FetchGeonamesDumpOptions,
@@ -167,7 +185,7 @@ export async function fetchGeonamesDumps(
 	await makeDirectories(options.outRoot)
 
 	const baseURL = options.baseURL ?? BASE_URL
-	const countryInfoDest = join(options.outRoot, "countryInfo.txt")
+	const countryInfoDest = options.outRoot("countryInfo.txt")
 
 	await downloadToFile({
 		url: `${baseURL}/countryInfo.txt`,
@@ -188,7 +206,7 @@ export async function fetchGeonamesDumps(
 	let fetched = 0
 
 	for (const country of countries) {
-		const txtDest = join(options.outRoot, `${country}.txt`)
+		const txtDest = options.outRoot(`${country}.txt`)
 
 		if (!options.force && (await pathExists(txtDest))) {
 			if (looksLikeGazetteerDump(await readFileHead(txtDest, FORMAT_SNIFF_BYTES))) {
@@ -203,7 +221,7 @@ export async function fetchGeonamesDumps(
 
 		const filename = `${country}.zip`
 		const url = `${baseURL}/${filename}`
-		const zipDest = join(options.outRoot, filename)
+		const zipDest = options.outRoot(filename)
 
 		report?.(`=== ${SLUG} / ${country}`)
 
@@ -226,8 +244,10 @@ export async function fetchGeonamesDumps(
 
 			const message = error instanceof Error ? error.message : String(error)
 
-			// Branch on the TYPED status (the geonames-postal lesson): message prose contains the URL, and a URL
-			// can contain any substring.
+			// Branch on the typed status.
+			// The error message contains a URL.
+			// URLs can contain any substring.
+			// Branch on the typed status instead of matching message text.
 			if (error instanceof HTTPStatusError && error.status === HTTP_NOT_FOUND) {
 				report?.(`✗ ${country}: GeoNames publishes no gazetteer dump for this country`)
 				unavailable.push(country)
@@ -251,7 +271,7 @@ export async function fetchGeonamesDumps(
 		wrong_format_present: wrongFormatPresent.toSorted(),
 	}
 
-	await writeManifest(join(options.outRoot, "MANIFEST.json"), manifest)
+	await writeManifest(options.outRoot("MANIFEST.json"), manifest)
 
 	return { fetched, skipped: skippedPresent.length, failed: failedCodes.length, failedCodes, skippedPresent }
 }