@mailwoman/corpus 8.0.0 → 8.2.0

package/src/tools/audit.ts

@@ -18,6 +18,17 @@
 import { existsSync, readFileSync, readdirSync } from "node:fs"
 import { basename, join } from "node:path"
 
+/**
+ * Share of a shard one source may hold before the mix is flagged as dominated by it.
+ */
+const DOMINANT_SOURCE_SHARE = 0.4
+
+/**
+ * How far the leading source may outweigh the runner-up before the mix is flagged. Catches the case where no single
+ * source clears {@link DOMINANT_SOURCE_SHARE} but the distribution is still lopsided.
+ */
+const MAX_TOP_TO_RUNNER_UP_RATIO = 1.5
+
 export interface AuditOpts {
 	corpusDir: string
 	configPath?: string
@@ -30,11 +41,17 @@ export interface AuditOpts {
 }
 
 interface ShardStats {
-	/** Shards per source per split */
+	/**
+	 * Shards per source per split
+	 */
 	bySplit: Record<string, Record<string, number>>
-	/** Total shards counted (may be less than file count if sampleShardCount caps reads) */
+	/**
+	 * Total shards counted (may be less than file count if sampleShardCount caps reads)
+	 */
 	totalShards: number
-	/** Total shards on disk (file count) — equals totalShards unless capped */
+	/**
+	 * Total shards on disk (file count) — equals totalShards unless capped
+	 */
 	totalFiles: number
 }
 
@@ -61,6 +78,7 @@ function parseConfig(configPath: string): ParsedConfig | null {
 		if (sourceWeightsMatch) {
 			inBlock = true
 			blockIndent = sourceWeightsMatch[1]!.length
+
 			continue
 		}
 
@@ -73,12 +91,14 @@ function parseConfig(configPath: string): ParsedConfig | null {
 
 		if (indent <= blockIndent) {
 			inBlock = false
+
 			continue
 		}
+
 		const m = raw.match(/^[\t ]+([\w-]+):\s*([\d.]+)/)
 
 		if (m) {
-			weights[m[1]!] = parseFloat(m[2]!)
+			weights[m[1]!] = Number.parseFloat(m[2]!)
 		}
 	}
 
@@ -96,9 +116,11 @@ function scanShards(corpusDir: string, sampleCount: number): ShardStats {
 		const splitDir = join(corpusDir, split)
 
 		if (!existsSync(splitDir)) continue
+
 		const files = readdirSync(splitDir)
 			.filter((f) => f.endsWith(".parquet"))
-			.sort()
+			.toSorted()
+
 		stats.totalFiles += files.length
 		const sampleEvery = Math.max(1, Math.floor(files.length / sampleCount))
 		const sampled = files.filter((_, i) => i % sampleEvery === 0).slice(0, sampleCount)
@@ -112,12 +134,14 @@ function scanShards(corpusDir: string, sampleCount: number): ShardStats {
 			const inferred = inferSourceFromFilename(f)
 			splitMap[inferred] = (splitMap[inferred] ?? 0) + 1
 		}
+
 		// Scale to estimated full-shard counts.
 		const scale = files.length / Math.max(sampled.length, 1)
 
 		for (const k of Object.keys(splitMap)) {
 			splitMap[k] = Math.round(splitMap[k]! * scale)
 		}
+
 		stats.bySplit[split] = splitMap
 		stats.totalShards += files.length
 	}
@@ -165,10 +189,12 @@ const KNOWN_SOURCE_PREFIXES: ReadonlyArray<string> = [
 	"deepseek-translit-armn",
 ]
 
-/** Extract the source-name prefix from a `first_source_id` value. */
+/**
+ * Extract the source-name prefix from a `first_source_id` value.
+ */
 function sourceFromID(sourceID: string, knownPrefixes: readonly string[]): string {
 	// Sort longest-first so usgov-nad beats usgov, wof-admin beats wof.
-	const sorted = [...knownPrefixes].sort((a, b) => b.length - a.length)
+	const sorted = [...knownPrefixes].toSorted((a, b) => b.length - a.length)
 
 	for (const prefix of sorted) {
 		if (sourceID.startsWith(prefix + "-") || sourceID === prefix) return prefix
@@ -190,6 +216,7 @@ function manifestScan(corpusDir: string, knownPrefixes: readonly string[]): Shar
 	const manifestPath = join(corpusDir, "MANIFEST.json")
 
 	if (!existsSync(manifestPath)) return null
+
 	const manifest = JSON.parse(readFileSync(manifestPath, "utf8")) as {
 		shards?: Array<{ split: string; source?: string | null; first_source_id?: string | null }>
 	}
@@ -203,6 +230,7 @@ function manifestScan(corpusDir: string, knownPrefixes: readonly string[]): Shar
 		bySplit[split] ??= {}
 		bySplit[split][src] = (bySplit[split][src] ?? 0) + 1
 	}
+
 	const total = Object.values(bySplit).reduce((sum, m) => sum + Object.values(m).reduce((a, b) => a + b, 0), 0)
 
 	return { bySplit, totalShards: total, totalFiles: total }
@@ -231,12 +259,14 @@ function buildAuditRows(stats: Record<string, number>, weights: Record<string, n
 		const effective = weight !== undefined ? shards * weight : 0
 		sampleWeights.push([src, effective])
 	}
+
 	const totalSampleWeight = sampleWeights.reduce((a, [, w]) => a + w, 0)
 
 	for (const src of allSources) {
 		const shards = stats[src] ?? 0
 		const weight = weights[src] ?? "—"
 		const effective = typeof weight === "number" ? (shards * weight) / Math.max(totalSampleWeight, 1) : "—"
+
 		rows.push({
 			source: src,
 			shards,
@@ -245,6 +275,7 @@ function buildAuditRows(stats: Record<string, number>, weights: Record<string, n
 			effectiveSamplePct: typeof effective === "number" ? effective : "—",
 		})
 	}
+
 	// Flag the dominator: empirically calibrated against the v0.3.0 → v0.4.0 retrospective.
 	// v0.3.0 had usgov-nad at 52% effective sample (1.9× ban); the resulting label-space dilution
 	// was responsible for the coarse-F1 regression. So flag a source as "concentration warning"
@@ -252,16 +283,21 @@ function buildAuditRows(stats: Record<string, number>, weights: Record<string, n
 	const numeric = rows.filter((r) => typeof r.effectiveSamplePct === "number") as Array<
 		AuditRow & { effectiveSamplePct: number }
 	>
+
 	numeric.sort((a, b) => b.effectiveSamplePct - a.effectiveSamplePct)
 
-	if (numeric.length >= 1) {
+	if (numeric.length) {
 		const top = numeric[0]!
 		const next = numeric[1]?.effectiveSamplePct ?? 0
 
-		if (top.effectiveSamplePct > 0.4 || (next > 0 && top.effectiveSamplePct / next > 1.5)) {
+		if (
+			top.effectiveSamplePct > DOMINANT_SOURCE_SHARE ||
+			(next > 0 && top.effectiveSamplePct / next > MAX_TOP_TO_RUNNER_UP_RATIO)
+		) {
 			top.overweightFactor = next > 0 ? top.effectiveSamplePct / next : Infinity
 		}
 	}
+
 	rows.sort((a, b) => b.shards - a.shards)
 
 	return rows
@@ -279,19 +315,24 @@ function printReport(corpusDir: string, configPath: string | undefined, stats: S
 	if (configPath) {
 		console.log(`Config:        ${configPath}`)
 	}
+
 	console.log(
 		`Total shards:  ${stats.totalShards}${stats.totalFiles !== stats.totalShards ? ` (${stats.totalFiles} files on disk)` : ""}`
 	)
 	console.log("")
+
 	const trainStats = stats.bySplit["train"]
 
 	if (trainStats) {
 		const total = Object.values(trainStats).reduce((a, b) => a + b, 0)
+
 		console.log(`Train split: ${total} shards`)
 		console.log("")
+
 		const headers = ["source", "shards", "shard %", "weight", "eff. sample %"]
 		const widths = [22, 8, 10, 8, 14]
 		const fmtRow = (cells: string[]) => cells.map((c, i) => c.padEnd(widths[i]!)).join("  ")
+
 		console.log(fmtRow(headers))
 		console.log(fmtRow(widths.map((w) => "─".repeat(w))))
 
@@ -306,12 +347,15 @@ function printReport(corpusDir: string, configPath: string | undefined, stats: S
 				])
 			)
 		}
+
 		console.log("")
+
 		const dominator = rows.find((r) => r.overweightFactor !== undefined)
 
 		if (dominator) {
 			const factor = dominator.overweightFactor
 			const factorStr = factor === Infinity ? "∞" : factor?.toFixed(1)
+
 			console.error(
 				`⚠ Concentration: ${dominator.source} would sample ${formatPct(dominator.effectiveSamplePct)} ` +
 					`of training rows (${factorStr}× the next-highest). ` +
@@ -321,17 +365,19 @@ function printReport(corpusDir: string, configPath: string | undefined, stats: S
 		} else {
 			console.log("✓ No single-source concentration (top source < 40% effective sample AND < 1.5× next).")
 		}
+
 		const missingWeights = rows.filter((r) => r.weight === "—" && r.shards > 0)
 
-		if (missingWeights.length > 0 && configPath) {
+		if (missingWeights.length && configPath) {
 			console.error(
 				`⚠ Sources present in corpus but absent from config.source_weights ` +
 					`(loader will skip them): ${missingWeights.map((r) => r.source).join(", ")}`
 			)
 		}
+
 		const orphanWeights = rows.filter((r) => typeof r.weight === "number" && r.shards === 0)
 
-		if (orphanWeights.length > 0) {
+		if (orphanWeights.length) {
 			console.error(
 				`⚠ Sources weighted in config but no shards found in corpus ` +
 					`(no-op weights): ${orphanWeights.map((r) => r.source).join(", ")}`

package/src/tools/corpus-stats.ts

@@ -82,6 +82,7 @@ n = min(len(tokens_col), ${limit ?? "len(tokens_col)"})
 for i in range(n):
     sys.stdout.write(json.dumps({"tokens": tokens_col[i], "labels": labels_col[i]}) + "\\n")
 `
+
 	const buf = execSync(`python3`, { input: py, maxBuffer: 1024 * 1024 * 1024 })
 	const rows: Array<{ tokens: string[]; labels: string[] }> = []
 
@@ -95,6 +96,7 @@ for i in range(n):
 
 export function buildCorpusStats(args: CorpusStatsOptions): void {
 	const shardPaths = discoverShards(args.shardsArg)
+
 	console.error(`Discovered ${shardPaths.length} parquet shard(s)`)
 
 	const tokenStats = new Map<string, Map<string, number>>()
@@ -103,6 +105,7 @@ export function buildCorpusStats(args: CorpusStatsOptions): void {
 
 	for (const path of shardPaths) {
 		console.error(`Reading ${path}...`)
+
 		const rows = streamShardRows(path, args.limitPerShard)
 		totalRows += rows.length
 
@@ -121,6 +124,7 @@ export function buildCorpusStats(args: CorpusStatsOptions): void {
 					labelMap = new Map()
 					tokenStats.set(tk, labelMap)
 				}
+
 				labelMap.set(lb, (labelMap.get(lb) ?? 0) + 1)
 
 				if (i + 1 < tokens.length) {
@@ -132,10 +136,12 @@ export function buildCorpusStats(args: CorpusStatsOptions): void {
 						bMap = new Map()
 						bigramStats.set(bigramKey, bMap)
 					}
+
 					bMap.set(bigramLabel, (bMap.get(bigramLabel) ?? 0) + 1)
 				}
 			}
 		}
+
 		console.error(
 			`  ${rows.length} rows; running totals: ${tokenStats.size} unique tokens, ${bigramStats.size} unique bigrams`
 		)
@@ -155,9 +161,11 @@ export function buildCorpusStats(args: CorpusStatsOptions): void {
 
 		if (total < MIN_BIGRAM_COUNT) {
 			bigramStats.delete(k)
+
 			prunedBigrams++
 		}
 	}
+
 	console.error(`Pruned ${prunedBigrams} singleton bigrams; ${bigramStats.size} remain`)
 
 	const out = {
@@ -177,6 +185,7 @@ export function buildCorpusStats(args: CorpusStatsOptions): void {
 
 	writeFileSync(args.outputPath, JSON.stringify(out))
 	const sizeMB = (Buffer.byteLength(JSON.stringify(out)) / 1024 / 1024).toFixed(1)
+
 	console.error(
 		`Wrote ${args.outputPath} (${sizeMB} MB) — ${totalRows} rows, ${tokenStats.size} tokens, ${bigramStats.size} bigrams`
 	)

package/src/tools/fetch/ban.ts

@@ -29,6 +29,12 @@ import { sha256File } from "@mailwoman/core/utils"
 import type { BaseFetchOptions, FetchSummary } from "./download.ts"
 import { downloadToFile, loadManifestEntries, 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 BASE_URL = "https://adresse.data.gouv.fr/data/ban/adresses/latest/csv"
 
 /**
@@ -150,15 +156,18 @@ export interface BanManifestEntry {
 
 export type FetchBanOptions = BaseFetchOptions
 
-/** 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++
 	}
 
@@ -195,7 +204,9 @@ export async function fetchBan(options: FetchBanOptions, report?: (line: string)
 
 			if (recordedSha && existingSha === recordedSha) {
 				report?.(`  → already present + sha matches — skipping`)
+
 				skipped++
+
 				continue
 			}
 
@@ -212,40 +223,49 @@ export async function fetchBan(options: FetchBanOptions, report?: (line: string)
 				headers: { "Accept-Encoding": "gzip, br" },
 				report,
 			})
-		} catch (err) {
-			report?.(`  ✗ download failed: ${url} (${(err as Error).message})`)
+		} catch (error) {
+			report?.(`  ✗ download failed: ${url} (${(error as Error).message})`)
+
 			failed++
 			failedCodes.push(code)
+
 			continue
 		}
 
 		// Guard against truncated 404/error pages.
 		const gzSize = statSync(gzFile).size
 
-		if (gzSize < 1024) {
+		if (gzSize < BYTES_PER_KIB) {
 			report?.(`  ✗ response too small (${gzSize} bytes) — probable 404 / error page`)
 			await unlink(gzFile)
+
 			failed++
 			failedCodes.push(code)
+
 			continue
 		}
 
 		// Decompress in-place; delete the .gz.
 		try {
 			await writeFile(csvFile, gunzipSync(await readFile(gzFile)))
-		} catch (err) {
-			report?.(`  ✗ decompress failed: ${(err as Error).message}`)
+		} catch (error) {
+			report?.(`  ✗ decompress failed: ${(error as Error).message}`)
 			await unlink(gzFile)
+
 			failed++
 			failedCodes.push(code)
+
 			continue
 		}
+
 		await unlink(gzFile)
 
 		if (!existsSync(csvFile)) {
 			report?.(`  ✗ decompressed file not found at ${csvFile}`)
+
 			failed++
 			failedCodes.push(code)
+
 			continue
 		}
 
@@ -262,6 +282,7 @@ export async function fetchBan(options: FetchBanOptions, report?: (line: string)
 		})
 
 		report?.(`  ✓ ${iec(bytes)}  sha256=${sha}`)
+
 		fetched++
 
 		// Be a polite citizen — short pause between requests.
@@ -269,9 +290,10 @@ export async function fetchBan(options: FetchBanOptions, report?: (line: string)
 	}
 
 	// Write the consolidated MANIFEST.json (entries sorted by dept_code, codepoint order).
-	const sorted = [...entries.values()].sort((a, b) =>
+	const sorted = [...entries.values()].toSorted((a, b) =>
 		a.dept_code < b.dept_code ? -1 : a.dept_code > b.dept_code ? 1 : 0
 	)
+
 	await writeManifest(manifestPath, sorted)
 	report?.(`Wrote ${manifestPath} with ${sorted.length} entries.`)
 
@@ -280,7 +302,7 @@ export async function fetchBan(options: FetchBanOptions, report?: (line: string)
 	report?.(`skipped:  ${skipped} (already present + sha matched)`)
 	report?.(`failed:   ${failed}`)
 
-	if (failedCodes.length > 0) {
+	if (failedCodes.length) {
 		report?.(`failed codes: ${failedCodes.join(" ")}`)
 	}
 

package/src/tools/fetch/download.ts

@@ -12,13 +12,34 @@ import { existsSync } from "node:fs"
 import { readFile, writeFile } from "node:fs/promises"
 import { setTimeout as sleep } from "node:timers/promises"
 
-/** The option base every `mailwoman corpus fetch <source>` module extends. */
+/**
+ * Rate limited — retryable, the server is asking us to back off.
+ */
+const HTTP_TOO_MANY_REQUESTS = 429
+
+/**
+ * Lowest 5xx status. Server-side failures are retryable; 4xx are not.
+ */
+const HTTP_SERVER_ERROR_MIN = 500
+
+/**
+ * Highest 5xx status.
+ */
+const HTTP_SERVER_ERROR_MAX = 599
+
+/**
+ * The option base every `mailwoman corpus fetch <source>` module extends.
+ */
 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: string
 }
 
-/** 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
 	skipped: number
@@ -26,19 +47,27 @@ export interface FetchSummary {
 	failedCodes: string[]
 }
 
-/** A status worth retrying: rate limiting or a server-side failure. */
+/**
+ * A status worth retrying: rate limiting or a server-side failure.
+ */
 export function isTransientStatus(status: number): boolean {
-	return status === 429 || (status >= 500 && status <= 599)
+	return status === HTTP_TOO_MANY_REQUESTS || (status >= HTTP_SERVER_ERROR_MIN && status <= HTTP_SERVER_ERROR_MAX)
 }
 
 export interface DownloadOptions {
 	url: string
 	dest: string
-	/** Per-attempt timeout. Default 10 minutes — these are multi-GB government dumps. */
+	/**
+	 * Per-attempt timeout. Default 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. Default 0.
+	 */
 	retries?: number
-	/** Delay between attempts. Default 5s. */
+	/**
+	 * Delay between attempts. Default 5s.
+	 */
 	retryDelayMs?: number
 	headers?: Record<string, string>
 	report?: (line: string) => void
@@ -49,7 +78,7 @@ export interface DownloadOptions {
  * or once retries are exhausted. Returns the byte count written.
  */
 export async function downloadToFile(options: DownloadOptions): Promise<{ bytes: number }> {
-	const { url, dest, timeoutMs = 600_000, retries = 0, retryDelayMs = 5_000, headers, report } = options
+	const { url, dest, timeoutMs = 600_000, retries = 0, retryDelayMs = 5000, headers, report } = options
 	let lastError: unknown
 
 	for (let attempt = 0; attempt <= retries; attempt++) {
@@ -65,6 +94,7 @@ export async function downloadToFile(options: DownloadOptions): Promise<{ bytes:
 		} catch (error) {
 			// AbortSignal timeouts and network-level failures are retryable.
 			lastError = error
+
 			continue
 		}
 
@@ -73,6 +103,7 @@ export async function downloadToFile(options: DownloadOptions): Promise<{ bytes:
 
 			if (!isTransientStatus(res.status)) throw error
 			lastError = error
+
 			continue
 		}
 
@@ -90,7 +121,9 @@ export async function downloadToFile(options: DownloadOptions): Promise<{ bytes:
 	throw lastError instanceof Error ? lastError : new Error(String(lastError))
 }
 
-/** Read a MANIFEST.json; `null` when missing or corrupt (callers re-fetch from scratch). */
+/**
+ * Read a MANIFEST.json; `null` when missing or corrupt (callers re-fetch from scratch).
+ */
 export async function readManifest<T>(path: string): Promise<T | null> {
 	if (!existsSync(path)) return null
 
@@ -101,7 +134,9 @@ export async function readManifest<T>(path: string): Promise<T | null> {
 	}
 }
 
-/** Load manifest entries into a map so untouched keys survive a partial re-fetch. */
+/**
+ * Load manifest entries into a map so untouched keys survive a partial re-fetch.
+ */
 export async function loadManifestEntries<T>(path: string, key: (entry: T) => string): Promise<Map<string, T>> {
 	const entries = new Map<string, T>()
 	const parsed = await readManifest<T[]>(path)
@@ -113,7 +148,9 @@ export async function loadManifestEntries<T>(path: string, key: (entry: T) => st
 	return entries
 }
 
-/** Write a MANIFEST.json in the house shape: pretty-printed, trailing newline. */
+/**
+ * Write a MANIFEST.json in the house shape: pretty-printed, trailing newline.
+ */
 export async function writeManifest(path: string, manifest: unknown): Promise<void> {
 	await writeFile(path, JSON.stringify(manifest, null, 2) + "\n")
 }

package/src/tools/fetch/hrsa.ts

@@ -41,6 +41,7 @@ export async function fetchHRSA(options: FetchHRSAOptions, report?: (line: strin
 	const dest = join(destDir, FILENAME)
 
 	report?.(`=== ${SLUG} / ${FILENAME}`)
+
 	const { bytes } = await downloadToFile({
 		url: SOURCE_URL,
 		dest,
@@ -48,6 +49,7 @@ export async function fetchHRSA(options: FetchHRSAOptions, report?: (line: strin
 		headers: { "Accept-Encoding": "gzip, br" },
 		report,
 	})
+
 	const sha = await sha256File(dest)
 
 	const manifest: SourceManifest = {
@@ -57,6 +59,7 @@ export async function fetchHRSA(options: FetchHRSAOptions, report?: (line: strin
 		sha256: sha,
 		bytes,
 	}
+
 	await writeManifest(join(destDir, "MANIFEST.json"), manifest)
 
 	report?.(`  ✓ ${(bytes / 1024 / 1024).toFixed(1)} MB  sha256=${sha}`)

package/src/tools/fetch/imls-pls.ts

@@ -20,6 +20,9 @@
  *   and sha 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"
@@ -31,10 +34,17 @@ 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 execFileAsync = promisify(execFile)
 
-// The PLS FY 2023 bulk CSV ZIP (most recent as of 2026-05).
-// If IMLS publishes a newer year, update this URL.
+/**
+ * The PLS FY 2023 bulk CSV ZIP (most recent as of 2026-05). If IMLS publishes a newer year, update this URL.
+ */
 const ZIP_URL = "https://www.imls.gov/sites/default/files/2025-08/pls_fy2023_csv.zip"
 const SLUG = "usgov-imls-pls"
 
@@ -48,7 +58,9 @@ interface SourceManifest {
 	bytes: number
 }
 
-/** Return the filenames listed inside a ZIP (the trailing column of each `unzip -l` row). */
+/**
+ * Return the filenames listed inside a ZIP (the trailing column of each `unzip -l` row).
+ */
 async function listZipEntries(zipPath: string): Promise<string[]> {
 	const listing = await execFileAsync("unzip", ["-l", zipPath])
 
@@ -70,9 +82,8 @@ export async function fetchIMLSPLS(
 
 	report?.(`=== ${SLUG}`)
 
-	// ------------------------------------------------------------------
-	// Idempotency check: if outlet CSV already exists and sha matches, skip.
-	// ------------------------------------------------------------------
+	// MARK: Idempotency check
+
 	const recorded = await readManifest<Partial<SourceManifest>>(manifestPath)
 
 	if (recorded?.sha256 && recorded.filename) {
@@ -85,10 +96,10 @@ export async function fetchIMLSPLS(
 		}
 	}
 
-	// ------------------------------------------------------------------
-	// Download ZIP
-	// ------------------------------------------------------------------
+	// MARK: Download ZIP
+
 	report?.(`  Downloading ${ZIP_URL} ...`)
+
 	const { bytes: zipSize } = await downloadToFile({
 		url: ZIP_URL,
 		dest: zipDest,
@@ -96,19 +107,18 @@ export async function fetchIMLSPLS(
 		headers: { "Accept-Encoding": "gzip, br" },
 		report,
 	})
+
 	report?.(`  Downloaded: ${(zipSize / 1024 / 1024).toFixed(1)} MB`)
 
-	if (zipSize < 1024) {
+	if (zipSize < BYTES_PER_KIB) {
 		report?.(`  ✗ Response too small (${zipSize} bytes) — probable error page`)
 
 		return { fetched: 0, skipped: 0, failed: 1, failedCodes: [SLUG] }
 	}
 
-	// ------------------------------------------------------------------
 	// Discover the outlet-level CSV inside the ZIP.
 	// Outlet files match: pls_fy*outlet*.csv (case-insensitive)
 	// Administrative-entity files match: pls_fy*ae*.csv — we skip those.
-	// ------------------------------------------------------------------
 	report?.("  Inspecting ZIP contents ...")
 	const entries = await listZipEntries(zipDest)
 
@@ -125,6 +135,7 @@ export async function fetchIMLSPLS(
 		for (const name of entries) {
 			report?.(`    ${name}`)
 		}
+
 		report?.("  ✗ Could not identify outlet CSV — inspect above listing and update this module")
 
 		return { fetched: 0, skipped: 0, failed: 1, failedCodes: [SLUG] }
@@ -137,15 +148,13 @@ export async function fetchIMLSPLS(
 	const csvSize = statSync(csvDest).size
 	const csvSha = await sha256File(csvDest)
 
-	// ------------------------------------------------------------------
-	// Remove ZIP (small, but keep destDir clean)
-	// ------------------------------------------------------------------
+	// MARK: Remove ZIP (small, but keep destDir clean)
+
 	await rm(zipDest, { force: true })
 	report?.("  Removed ZIP (CSV kept)")
 
-	// ------------------------------------------------------------------
-	// Write MANIFEST
-	// ------------------------------------------------------------------
+	// MARK: Write MANIFEST
+
 	const manifest: SourceManifest = {
 		source_url: ZIP_URL,
 		downloaded_at: new Date().toISOString(),
@@ -153,6 +162,7 @@ export async function fetchIMLSPLS(
 		sha256: csvSha,
 		bytes: csvSize,
 	}
+
 	await writeManifest(manifestPath, manifest)
 
 	report?.(`  ✓ ${(csvSize / 1024 / 1024).toFixed(1)} MB  sha256=${csvSha}`)