@mailwoman/corpus 8.0.0 → 8.2.0

package/src/tools/fetch/index.ts

@@ -105,7 +105,9 @@ export * from "./state-hi-schools.ts"
 export * from "./state-sources.ts"
 export * from "./tiger-full.ts"
 
-/** The fetch-source registry: id → module entry point. Each entry point takes its own options interface. */
+/**
+ * The fetch-source registry: id → module entry point. Each entry point takes its own options interface.
+ */
 export const FETCH_SOURCES = {
 	ban: fetchBan,
 	nad: fetchNAD,

package/src/tools/fetch/nad.ts

@@ -46,23 +46,38 @@ import type { BaseFetchOptions, FetchSummary } from "./download.ts"
 import { downloadToFile, readManifest, writeManifest } from "./download.ts"
 
 const SLUG = "usgov-nad"
+
 const FEATURE_SERVICE_URL =
 	"https://services.arcgis.com/xOi1kZaI0eWDREZv/ArcGIS/rest/services/Address_Points_from_National_Address_Database_view/FeatureServer/0"
 
 export interface FetchNADOptions extends BaseFetchOptions {
-	/** Fetch strategy. Default `featureserver`. */
+	/**
+	 * Fetch strategy. Default `featureserver`.
+	 */
 	mode?: "featureserver" | "bulk"
-	/** Pre-signed S3 URL for bulk mode. */
+	/**
+	 * Pre-signed S3 URL for bulk mode.
+	 */
 	nadURL?: string
-	/** Records per output file. Default `100000`. */
+	/**
+	 * Records per output file. Default `100000`.
+	 */
 	chunkSize?: number
-	/** Records per HTTP request. Default `5000`. */
+	/**
+	 * Records per HTTP request. Default `5000`.
+	 */
 	pageSize?: number
-	/** Parallel page fetches within a chunk. Default `4`. */
+	/**
+	 * Parallel page fetches within a chunk. Default `4`.
+	 */
 	concurrency?: number
-	/** Start OBJECTID. Default `1`. */
+	/**
+	 * Start OBJECTID. Default `1`.
+	 */
 	startOID?: number
-	/** Stop before this OID. Default = total count. */
+	/**
+	 * Stop before this OID. Default = total count.
+	 */
 	endOID?: number
 }
 
@@ -138,7 +153,9 @@ async function fetchChunk(
 		rows: [],
 		error: null,
 	}))
+
 	let nextSlot = 0
+
 	const workers = Array.from({ length: Math.min(concurrency, pageRanges.length) }, async () => {
 		while (true) {
 			const slot = nextSlot++
@@ -148,12 +165,13 @@ async function fetchChunk(
 
 			try {
 				pageResults[slot]!.rows = await fetchPage(s, e, pageSize)
-			} catch (err) {
-				pageResults[slot]!.error = err as Error
-				report?.(`    ✗ page ${s}-${e}: ${(err as Error).message}`)
+			} catch (error) {
+				pageResults[slot]!.error = error as Error
+				report?.(`    ✗ page ${s}-${e}: ${(error as Error).message}`)
 			}
 		}
 	})
+
 	await Promise.all(workers)
 
 	// Single-writer phase — write all pages in OID order to keep NDJSON deterministic.
@@ -163,6 +181,7 @@ async function fetchChunk(
 	for (const { rows, error } of pageResults) {
 		if (error) {
 			errors++
+
 			continue
 		}
 
@@ -170,14 +189,15 @@ async function fetchChunk(
 			lines.push(JSON.stringify(row))
 		}
 	}
-	await writeFile(chunkPath, lines.length === 0 ? "" : lines.join("\n") + "\n")
+
+	await writeFile(chunkPath, !lines.length ? "" : lines.join("\n") + "\n")
 
 	return { recordCount: lines.length, errors }
 }
 
 async function featureserverMode(options: FetchNADOptions, report?: (line: string) => void): Promise<FetchSummary> {
 	const chunkSize = options.chunkSize ?? 100_000
-	const pageSize = options.pageSize ?? 5_000
+	const pageSize = options.pageSize ?? 5000
 	const concurrency = options.concurrency ?? 4
 	const startOID = options.startOID ?? 1
 
@@ -211,6 +231,7 @@ async function featureserverMode(options: FetchNADOptions, report?: (line: strin
 
 			if (recorded?.complete) {
 				skipped++
+
 				continue
 			}
 		}
@@ -233,12 +254,15 @@ async function featureserverMode(options: FetchNADOptions, report?: (line: strin
 			page_errors: errors,
 			complete: errors === 0,
 		}
+
 		await writeManifest(manifestPath, manifest)
 
 		const status = errors === 0 ? "✓" : `⚠ ${errors} page errors`
+
 		report?.(
 			`    ${status}  ${recordCount.toLocaleString()} records in ${elapsed}s  (${(bytes / 1024 / 1024).toFixed(1)} MB)`
 		)
+
 		fetched++
 		totalRecords += recordCount
 		totalErrors += errors
@@ -266,6 +290,7 @@ async function bulkMode(options: FetchNADOptions, report?: (line: string) => voi
 				`accept the disclaimer, and re-run with the pre-signed S3 URL.`
 		)
 	}
+
 	const destDir = join(options.outRoot, SLUG)
 	mkdirSync(destDir, { recursive: true })
 	const filename = new URL(options.nadURL).pathname.split("/").pop() ?? "NAD.zip"
@@ -277,6 +302,7 @@ async function bulkMode(options: FetchNADOptions, report?: (line: string) => voi
 	const { bytes } = await downloadToFile({ url: options.nadURL, dest: destPath, timeoutMs: 3 * 3600 * 1000, report })
 
 	const sha = await sha256File(destPath)
+
 	await writeManifest(join(destDir, "MANIFEST.json"), {
 		source_url: options.nadURL,
 		downloaded_at: new Date().toISOString(),
@@ -284,6 +310,7 @@ async function bulkMode(options: FetchNADOptions, report?: (line: string) => voi
 		sha256: sha,
 		bytes,
 	})
+
 	report?.(`  ✓ ${(bytes / 1024 / 1024 / 1024).toFixed(2)} GB  sha256=${sha}`)
 
 	return { fetched: 1, skipped: 0, failed: 0, failedCodes: [] }

package/src/tools/fetch/nppes.ts

@@ -21,6 +21,9 @@
  *   sha256 matches MANIFEST, skips download.
  */
 
+/* oxlint-disable sister-software/prefer-region-over-marks -- these markers label steps inside one
+   procedure, not sections of declarations. A region there folds nothing a reader wants folded. */
+
 import { execFile } from "node:child_process"
 import { existsSync, mkdirSync, statSync } from "node:fs"
 import { rm } from "node:fs/promises"
@@ -70,7 +73,9 @@ async function discoverLatestZip(): Promise<string | undefined> {
 	return undefined
 }
 
-/** Extract the main registry CSV name (npidata_pfile_*.csv) from a ZIP's `unzip -l` listing. */
+/**
+ * Extract the main registry CSV name (npidata_pfile_*.csv) from a ZIP's `unzip -l` listing.
+ */
 async function findNpidataCSV(zipPath: string): Promise<string | undefined> {
 	const listing = await execFileAsync("unzip", ["-l", zipPath])
 
@@ -103,10 +108,8 @@ export async function fetchNPPES(options: FetchNPPESOptions, report?: (line: str
 	const zipDest = join(destDir, zipFilename)
 	report?.(`  Latest full file: ${zipFilename}`)
 
-	// ------------------------------------------------------------------
 	// Idempotency check: if the main CSV already exists and sha matches,
 	// skip re-download.
-	// ------------------------------------------------------------------
 	const recorded = await readManifest<Partial<SourceManifest>>(manifestPath)
 
 	if (recorded?.sha256 && recorded.filename) {
@@ -119,10 +122,10 @@ export async function fetchNPPES(options: FetchNPPESOptions, report?: (line: str
 		}
 	}
 
-	// ------------------------------------------------------------------
-	// Download ZIP (large; 60-minute timeout)
-	// ------------------------------------------------------------------
+	// MARK: Download ZIP (large; 60-minute timeout)
+
 	report?.(`  Downloading ${zipURL} ...`)
+
 	const { bytes: zipSize } = await downloadToFile({
 		url: zipURL,
 		dest: zipDest,
@@ -130,11 +133,11 @@ export async function fetchNPPES(options: FetchNPPESOptions, report?: (line: str
 		headers: { "Accept-Encoding": "gzip, br" },
 		report,
 	})
+
 	report?.(`  Downloaded: ${(zipSize / 1024 / 1024).toFixed(1)} MB`)
 
-	// ------------------------------------------------------------------
-	// Extract only the main registry CSV (npidata_pfile_*.csv)
-	// ------------------------------------------------------------------
+	// MARK: Extract only the main registry CSV (npidata_pfile_*.csv)
+
 	report?.("  Extracting npidata_pfile CSV from ZIP ...")
 	const csvName = await findNpidataCSV(zipDest)
 
@@ -152,15 +155,13 @@ export async function fetchNPPES(options: FetchNPPESOptions, report?: (line: str
 	const csvSha = await sha256File(csvDest)
 	report?.(`  CSV size: ${(csvSize / 1024 / 1024).toFixed(1)} MB`)
 
-	// ------------------------------------------------------------------
-	// Remove the ZIP to reclaim ~1 GB (the CSV is what adapters consume)
-	// ------------------------------------------------------------------
+	// MARK: Remove the ZIP to reclaim ~1 GB
+
 	await rm(zipDest, { force: true })
 	report?.("  Removed ZIP (CSV kept)")
 
-	// ------------------------------------------------------------------
-	// Write MANIFEST (records the extracted CSV, not the ZIP)
-	// ------------------------------------------------------------------
+	// MARK: Write MANIFEST (records the extracted CSV, not the ZIP)
+
 	const manifest: SourceManifest = {
 		source_url: zipURL,
 		downloaded_at: new Date().toISOString(),
@@ -168,6 +169,7 @@ export async function fetchNPPES(options: FetchNPPESOptions, report?: (line: str
 		sha256: csvSha,
 		bytes: csvSize,
 	}
+
 	await writeManifest(manifestPath, manifest)
 
 	report?.(`  ✓ ${(csvSize / 1024 / 1024).toFixed(1)} MB  sha256=${csvSha}`)

package/src/tools/fetch/openaddresses.ts

@@ -51,6 +51,9 @@
  *   ```
  */
 
+/* oxlint-disable sister-software/prefer-region-over-marks -- these markers label steps inside one
+   procedure, not sections of declarations. A region there folds nothing a reader wants folded. */
+
 import { execFile, spawn } from "node:child_process"
 import { createReadStream, createWriteStream, existsSync, mkdirSync, renameSync, rmSync, statSync } from "node:fs"
 import { join } from "node:path"
@@ -65,6 +68,22 @@ import { sha256File } from "@mailwoman/core/utils"
 import type { BaseFetchOptions, FetchSummary } from "./download.ts"
 import { isTransientStatus, writeManifest } from "./download.ts"
 
+/**
+ * Bytes per KiB — the divisor for human-readable sizes, and the floor below which a "download" is an error page rather
+ * than data.
+ */
+/**
+ * A successful fetch; anything else is an error page or a redirect we did not follow.
+ */
+const HTTP_OK = 200
+
+/**
+ * Smallest plausible OpenAddresses shard. Below 10 KiB the file is a stub or an error body.
+ */
+const MIN_PLAUSIBLE_SHARD_BYTES = 10_240
+
+const BYTES_PER_KIB = 1024
+
 const execFileAsync = promisify(execFile)
 
 const OA_BASE = "https://batch.openaddresses.io"
@@ -83,7 +102,9 @@ const OA_COLLECTION_IDS: Record<string, number> = {
 }
 
 export interface FetchOpenAddressesOptions extends BaseFetchOptions {
-	/** OA country collection code. Default `ca`. */
+	/**
+	 * OA country collection code. Default `ca`.
+	 */
 	country?: string
 }
 
@@ -94,13 +115,15 @@ interface OaCollection {
 	size?: number
 }
 
-/** Stream-count newlines, matching `wc -l` (memory-safe for the multi-GB collection). */
+/**
+ * Stream-count newlines, matching `wc -l` (memory-safe for the multi-GB collection).
+ */
 async function countLines(path: string): Promise<number> {
 	let count = 0
 
 	for await (const chunk of createReadStream(path) as AsyncIterable<Buffer>) {
-		for (let i = 0; i < chunk.length; i++) {
-			if (chunk[i] === 0x0a) {
+		for (const byte of chunk) {
+			if (byte === 0x0a) {
 				count++
 			}
 		}
@@ -114,8 +137,9 @@ function humanBytes(bytes: number): string {
 	let value = bytes
 	let unit = 0
 
-	while (value >= 1024 && unit < units.length - 1) {
+	while (value >= BYTES_PER_KIB && unit < units.length - 1) {
 		value /= 1024
+
 		unit++
 	}
 
@@ -154,6 +178,7 @@ async function streamDownload(url: string, dest: string, opts: StreamDownloadOpt
 
 			if (attempt < opts.retries && isTransientStatus(res.status)) {
 				await sleep(opts.retryDelayMs)
+
 				continue
 			}
 
@@ -161,6 +186,7 @@ async function streamDownload(url: string, dest: string, opts: StreamDownloadOpt
 		} catch {
 			if (attempt < opts.retries) {
 				await sleep(opts.retryDelayMs)
+
 				continue
 			}
 
@@ -171,12 +197,16 @@ async function streamDownload(url: string, dest: string, opts: StreamDownloadOpt
 	return 0
 }
 
-/** Decompress `src` → `dest` with the same deprioritized subprocess the old fetcher used. */
+/**
+ * Decompress `src` → `dest` with the same deprioritized subprocess the old fetcher used.
+ */
 async function gunzipToFile(src: string, dest: string): Promise<void> {
 	const child = spawn("nice", ["-n", "15", "ionice", "-c", "3", "gunzip", "-c", src], {
 		stdio: ["ignore", "pipe", "inherit"],
 	})
+
 	await pipeline(child.stdout!, createWriteStream(dest))
+
 	await new Promise<void>((resolve, reject) => {
 		child.on("close", (code) => (code === 0 ? resolve() : reject(new Error(`gunzip exited with code ${code}`))))
 		child.on("error", reject)
@@ -201,9 +231,8 @@ export async function fetchOpenAddresses(
 
 	mkdirSync(destDir, { recursive: true })
 
-	// -------------------------------------------------------------------------
-	// Authentication check
-	// -------------------------------------------------------------------------
+	// MARK: Authentication check
+
 	if (!token) {
 		report?.(`
 ERROR: OA_BATCH_TOKEN is not set.
@@ -227,13 +256,13 @@ The Canada collection (ca) is ~2 GiB compressed / ~7 GiB uncompressed
 		return fail("OA_BATCH_TOKEN")
 	}
 
-	// -------------------------------------------------------------------------
-	// Determine collection ID
-	// -------------------------------------------------------------------------
+	// MARK: Determine collection ID
+
 	let collectionID = OA_COLLECTION_IDS[country]
 
 	if (collectionID === undefined) {
 		report?.(`Unknown country code '${country}'. Fetching collection list to find ID...`)
+
 		const res = await fetch(`${OA_BASE}/api/collections`, {
 			headers: { Authorization: `Bearer ${token}`, "Accept-Encoding": "gzip, br" },
 			signal: AbortSignal.timeout(30_000),
@@ -264,9 +293,8 @@ The Canada collection (ca) is ~2 GiB compressed / ~7 GiB uncompressed
 		report?.(`  Found collection id=${collectionID} for '${country}'`)
 	}
 
-	// -------------------------------------------------------------------------
-	// Download via the collections download endpoint (302s to S3)
-	// -------------------------------------------------------------------------
+	// MARK: Download via the collections download endpoint (302s to S3)
+
 	report?.(`  Resolving download URL for collection id=${collectionID}...`)
 	report?.(`  Attempting authenticated download...`)
 
@@ -281,7 +309,7 @@ The Canada collection (ca) is ~2 GiB compressed / ~7 GiB uncompressed
 		retryDelayMs: 30_000,
 	})
 
-	if (httpStatus !== 200) {
+	if (httpStatus !== HTTP_OK) {
 		// Try the geojsonl.gz directly with token as query param (alternate URL shape).
 		httpStatus = await streamDownload(`${OA_BASE}/api/collections/${collectionID}/geojsonl.gz?token=${token}`, tmpGz, {
 			timeoutMs: 7_200_000,
@@ -290,8 +318,9 @@ The Canada collection (ca) is ~2 GiB compressed / ~7 GiB uncompressed
 		})
 	}
 
-	if (httpStatus !== 200) {
+	if (httpStatus !== HTTP_OK) {
 		rmSync(tmpGz, { force: true })
+
 		report?.(`
 ERROR: Download returned HTTP ${httpStatus}.
 
@@ -312,9 +341,8 @@ URL tried: ${OA_BASE}/api/collections/${collectionID}/download
 		return fail(country)
 	}
 
-	// -------------------------------------------------------------------------
-	// Decompress if the downloaded file is gzipped
-	// -------------------------------------------------------------------------
+	// MARK: Decompress if the downloaded file is gzipped
+
 	const fileMagic = (await execFileAsync("file", ["--brief", tmpGz]).catch(() => ({ stdout: "" }))).stdout
 
 	if (/gzip|compressed/i.test(fileMagic)) {
@@ -332,9 +360,8 @@ URL tried: ${OA_BASE}/api/collections/${collectionID}/download
 		report?.(`  WARNING: Downloaded file type is '${fileMagic.trim()}' — may need manual decompression.`)
 	}
 
-	// -------------------------------------------------------------------------
-	// Verify + write MANIFEST
-	// -------------------------------------------------------------------------
+	// MARK: Verify + write MANIFEST
+
 	if (!existsSync(outputFile)) {
 		report?.(`ERROR: Output file not found at ${outputFile} after download.`)
 
@@ -343,7 +370,7 @@ URL tried: ${OA_BASE}/api/collections/${collectionID}/download
 
 	const size = statSync(outputFile).size
 
-	if (size < 10240) {
+	if (size < MIN_PLAUSIBLE_SHARD_BYTES) {
 		report?.(`ERROR: File is suspiciously small (${size} bytes) — likely an error response.`)
 
 		return fail(country)
@@ -365,6 +392,7 @@ URL tried: ${OA_BASE}/api/collections/${collectionID}/download
 		notes:
 			"batch.openaddresses.io requires a free registered account for downloads. License is mixed per-row; use the openaddresses adapter with allowShareAlike=false (default) to filter Tier-C rows.",
 	}
+
 	await writeManifest(manifestPath, manifest)
 
 	report?.(`  ✓ ${humanBytes(size)}  rows=${rowCount}  sha256=${sha}`)

package/src/tools/fetch/ppd.ts

@@ -48,25 +48,36 @@ export async function extractPPDTuples(
 	write("NUMBER,STREET,CITY,DISTRICT,REGION,POSTCODE")
 
 	for await (const cells of input) {
-		const [, , , postcode, , , , paon, saon, street, locality, town, , county] = cells
+		// HM Land Registry Price Paid Data column order (see the PPD FAQ for the full field list).
+		const postcode = cells[3]
+		const paon = cells[7]
+		const saon = cells[8]
+		const street = cells[9]
+		const locality = cells[10]
+		const town = cells[11]
+		const county = cells[13]
 
 		if (saon) {
 			stats.skippedSAON++
+
 			continue
 		}
 
 		if (!paon || !HOUSE_NUMBER_PATTERN.test(paon)) {
 			stats.skippedPAON++
+
 			continue
 		}
 
 		if (!street) {
 			stats.skippedNoStreet++
+
 			continue
 		}
 
 		if (!postcode) {
 			stats.skippedNoPostcode++
+
 			continue
 		}
 
@@ -83,13 +94,16 @@ export async function extractPPDTuples(
 				postcode,
 			].join(",")
 		)
+
 		stats.kept++
 	}
 
 	return stats
 }
 
-/** Stream `inputPath` (PPD CSV) → `outputPath` (OA-shaped tuples CSV), returning the row-count stats. */
+/**
+ * Stream `inputPath` (PPD CSV) → `outputPath` (OA-shaped tuples CSV), returning the row-count stats.
+ */
 export async function runPPDExtract(inputPath: string, outputPath: string): Promise<PPDExtractStats> {
 	// No `encoding` — CSVSpliterator delimits raw bytes and decodes utf-8 itself (see readTuples in
 	// shard-recipes/locale.ts). `header: false` yields every row as data — PPD ships no header row.
@@ -98,10 +112,13 @@ export async function runPPDExtract(inputPath: string, outputPath: string): Prom
 		header: false,
 		enableQuoteHandling: true,
 	})
+
 	const out = createWriteStream(outputPath, { encoding: "utf8" })
 	const stats = await extractPPDTuples(rows, (line) => out.write(line + "\n"))
 
-	await new Promise<void>((res) => out.end(res))
+	await new Promise<void>((res) => {
+		out.end(res)
+	})
 
 	return stats
 }
@@ -113,6 +130,8 @@ runIfScript(import.meta, async () => {
 			output: { type: "string", default: dataRootPath("ppd", "2026-07-22", "gb-tuples.csv") },
 		},
 	})
+
 	const stats = await runPPDExtract(values.input!, values.output!)
+
 	console.log(`[ppd] ${JSON.stringify(stats)}`)
 })

package/src/tools/fetch/state-hi-schools.ts

@@ -30,6 +30,12 @@ import { sha256File } from "@mailwoman/core/utils"
 import type { BaseFetchOptions, FetchSummary } from "./download.ts"
 import { downloadToFile, readManifest, writeManifest } from "./download.ts"
 
+/**
+ * Bytes per KiB — the divisor for human-readable sizes, and the floor below which a "download" is an error page rather
+ * than data.
+ */
+const BYTES_PER_KIB = 1024
+
 const SOURCE_URL = "https://www.hawaiipublicschools.org/DOE%20Forms/SchoolList.xlsx"
 const SLUG = "state-hi-schools"
 const CSV_FILENAME = "HI_Public_Schools_List.csv"
@@ -90,15 +96,18 @@ interface Manifest {
 	notes: string
 }
 
-/** Mimic `numfmt --to=iec` for a friendly byte-size log line. */
+/**
+ * Mimic `numfmt --to=iec` for a friendly byte-size log line.
+ */
 function iec(bytes: number): string {
-	if (bytes < 1024) return String(bytes)
+	if (bytes < BYTES_PER_KIB) return String(bytes)
 	const units = ["K", "M", "G", "T", "P"]
 	let value = bytes / 1024
 	let i = 0
 
-	while (value >= 1024 && i < units.length - 1) {
+	while (value >= BYTES_PER_KIB && i < units.length - 1) {
 		value /= 1024
+
 		i++
 	}
 
@@ -115,6 +124,7 @@ async function convertXLSXToCSV(xlsxPath: string, csvPath: string): Promise<void
 	const child = spawn("python3", ["-c", PY_CONVERT, xlsxPath, csvPath], {
 		stdio: ["ignore", "inherit", "inherit"],
 	})
+
 	await new Promise<void>((resolve, reject) => {
 		child.on("close", (code) => (code === 0 ? resolve() : reject(new Error(`python3 converter exited with ${code}`))))
 		child.on("error", reject)
@@ -173,8 +183,8 @@ export async function fetchStateHISchools(
 			headers: { "Accept-Encoding": "gzip, br" },
 			report,
 		})
-	} catch (err) {
-		report?.(`  ✗ Download failed (${(err as Error).message})`)
+	} catch (error) {
+		report?.(`  ✗ Download failed (${(error as Error).message})`)
 
 		return { fetched: 0, skipped: 0, failed: 1, failedCodes: [SLUG] }
 	}
@@ -182,7 +192,7 @@ export async function fetchStateHISchools(
 	const xlsxSize = statSync(xlsxDest).size
 	report?.(`  Downloaded XLSX: ${iec(xlsxSize)}`)
 
-	if (xlsxSize < 1024) {
+	if (xlsxSize < BYTES_PER_KIB) {
 		report?.(`  ✗ Response too small (${xlsxSize} bytes) — probable error page`)
 
 		return { fetched: 0, skipped: 0, failed: 1, failedCodes: [SLUG] }
@@ -208,6 +218,7 @@ export async function fetchStateHISchools(
 		bytes: csvSize,
 		notes: "Converted from XLSX (sheets HIDOE + PCS concatenated under shared header).",
 	}
+
 	await writeManifest(manifestPath, manifest)
 
 	report?.(`  ✓ ${iec(csvSize)}  sha256=${csvSha}`)

package/src/tools/fetch/state-sources.ts

@@ -25,6 +25,12 @@ import { sha256File } from "@mailwoman/core/utils"
 import type { BaseFetchOptions, FetchSummary } from "./download.ts"
 import { downloadToFile, writeManifest } from "./download.ts"
 
+/**
+ * Bytes per KiB — the divisor for human-readable sizes, and the floor below which a "download" is an error page rather
+ * than data.
+ */
+const BYTES_PER_KIB = 1024
+
 export type FetchStateSourcesOptions = BaseFetchOptions
 
 interface Source {
@@ -106,21 +112,26 @@ export async function fetchStateSources(
 				headers: { "Accept-Encoding": "gzip, br" },
 				report,
 			}))
-		} catch (err) {
-			report?.(`  ✗ download failed for ${url}: ${(err as Error).message}`)
+		} catch (error) {
+			report?.(`  ✗ download failed for ${url}: ${(error as Error).message}`)
+
 			failed++
 			failedCodes.push(slug)
+
 			continue
 		}
 
-		if (bytes < 1024) {
+		if (bytes < BYTES_PER_KIB) {
 			report?.(`  ✗ response too small (${bytes} bytes) — probable 404 / error page`)
+
 			failed++
 			failedCodes.push(slug)
+
 			continue
 		}
 
 		const sha = await sha256File(dest)
+
 		const manifest: SourceManifest = {
 			source_url: url,
 			downloaded_at: new Date().toISOString(),
@@ -128,9 +139,11 @@ export async function fetchStateSources(
 			sha256: sha,
 			bytes,
 		}
+
 		await writeManifest(join(destDir, "MANIFEST.json"), manifest)
 
 		report?.(`  ✓ ${(bytes / 1024 / 1024).toFixed(1)} MB  sha256=${sha}`)
+
 		fetched++
 	}