@mailwoman/corpus 10.1.0 → 10.2.1

package/lib/tools/fetch/inspire-addresses.ts

@@ -9,15 +9,14 @@
  * service: a predefined-dataset ATOM feed and a Web Feature Service. Most member states publish the
  * second, so a file download reaches only a minority of them.
  *
- * An `ad:Address` feature carries its point, its lifecycle dates and its locator. It does not carry
- * its street name, its postcode or its administrative units: those are separate feature types, and
- * the address references them through `component`. A complete address is therefore assembled from
- * several feature types rather than read from one.
+ * An `ad:Address` feature holds its point, its lifecycle dates and its locator. Its street name,
+ * postcode and administrative units are separate feature types that the address references through
+ * `component`. A complete address therefore comes from several feature types.
  *
  * Measured on Slovakia's service, one address holds four component references that resolve to three
- * `ad:AdminUnitName` features and one `ad:PostalDescriptor`. Resolving each reference with its own
- * request would cost roughly four requests per address, which is 6.8 million for that service's
- * 1,704,196 addresses. This module therefore pages each feature type in bulk and joins locally.
+ * `ad:AdminUnitName` features and one `ad:PostalDescriptor`. One request per reference would cost
+ * roughly four requests per address, 6.8 million for that service's 1,704,196 addresses. This module
+ * therefore pages each feature type in bulk and joins locally.
  *
  * A service's feature count is read with `readCheckedWFSFeatureCount` from `@mailwoman/core/api`,
  * which owns every WFS count this repository takes.
@@ -59,8 +58,8 @@ export type ADFeatureType = (typeof AD_FEATURE_TYPES)[number]
  * Poland publishes `ms:AD.Address`.
  *
  * A reader that compares the part after the colon against `Address` finds a type
- * on two services and none on the other two, which reads as a service publishing
- * no addresses rather than as a naming difference.
+ * on two services and none on the other two.
+ * That reads as a service publishing no addresses rather than as a naming difference.
  */
 export function adFeatureTypeOf(qualifiedName: string): ADFeatureType | null {
 	const local = qualifiedName.slice(qualifiedName.lastIndexOf(":") + 1)
@@ -85,8 +84,8 @@ export interface WFSCapabilities {
 	/**
 	 * The advertised format this module would ask for, or `null` when the service offers no JSON.
 	 *
-	 * A service without one is readable through its GML, which this module leaves
-	 * to its caller rather than reporting as unreadable.
+	 * A service without one is readable through its GML.
+	 * This module leaves that to its caller rather than reporting it as unreadable.
 	 *
 	 * `application/json` is preferred over `application/geo+json` because a service
 	 * may advertise the second and reject it.
@@ -107,14 +106,15 @@ export interface WFSCapabilities {
 	 *
 	 * A service that does not cannot be paged, so a caller has to take the whole
 	 * type in one request or decline it.
-	 * Reading past the first page of such a service silently repeats page one.
+	 * A request past the first page of such a service silently repeats page one.
 	 */
 	supportsPaging: boolean
 	/**
 	 * The `CountDefault` the service advertises, or `null` where it advertises none.
 	 *
-	 * The largest page the service will serve, which is also the number its own
-	 * `numberMatched` reports when that number is a cap rather than a count.
+	 * The largest page the service will serve.
+	 * Its own `numberMatched` reports that number when the service caps the query rather than counting it.
+	 *
 	 * Estonia advertises 1000000 and Poland 1000, measured 2026-10-02.
 	 */
 	countDefault: number | null
@@ -131,8 +131,9 @@ export interface WFSCapabilities {
 /**
  * A value a GeoServer JSON response uses for a voidable property that holds no value.
  *
- * INSPIRE marks many attributes voidable, which requires the property to be present
- * carrying either a value or a void with a reason.
+ * INSPIRE marks many attributes voidable.
+ * A voidable property must be present with either a value or a void with a reason.
+ *
  * GeoServer encodes that void as an object rather than as `null`, so `String(value)`
  * on one yields `[object Object]` and stores it as though it were data.
  */
@@ -160,8 +161,8 @@ export function isVoided(value: unknown): value is VoidedValue {
  * This collapses both to `null`, so a caller that needs the two apart reads the
  * property's presence on `properties` itself.
  */
-export function readVoidable<T>(value: T | VoidedValue | undefined): T | null {
-	if (value === undefined || isVoided(value)) return null
+export function readVoidable<T>(value: T | VoidedValue | null): T | null {
+	if (value === null || isVoided(value)) return null
 
 	return value as T
 }
@@ -215,7 +216,7 @@ export async function readWFSCapabilities(
 
 	// `application/json` is GeoServer's GeoJSON writer, and `application/geo+json` is
 	// the alias a service may advertise without implementing.
-	// The other JSON-ish formats carry a different envelope, so they are left out rather than tried.
+	// The other JSON-ish formats have a different envelope, so they are left out rather than tried.
 	const jsonFormats = ["application/json", "application/geo+json"].filter((format) => outputFormats.includes(format))
 
 	const countDefault = /<(?:\w+:)?Constraint\s+name="CountDefault"[\s\S]{0,240}?<(?:\w+:)?DefaultValue>\s*(\d+)\s*</iu
@@ -226,7 +227,7 @@ export async function readWFSCapabilities(
 		outputFormats,
 		jsonFormat: jsonFormats[0] ?? null,
 		jsonFormats,
-		countDefault: countDefault === undefined ? null : Number(countDefault),
+		countDefault: countDefault ? Number(countDefault) : null,
 		supportsPaging: /ImplementsResultPaging[\s\S]{0,120}?>\s*(?:TRUE|true)\s*</u.test(data),
 		typeNames,
 	}
@@ -247,8 +248,8 @@ export interface FeaturePage<Feature> {
 	/**
 	 * The `timeStamp` the service dated the page with, or `null` where it stated none.
 	 *
-	 * The service's own clock rather than the caller's, which is what a manifest
-	 * records to date a page against the service that served it.
+	 * The service's own clock rather than the caller's.
+	 * A manifest records it to date a page against the service that served it.
 	 */
 	timeStamp: string | null
 }
@@ -283,8 +284,10 @@ export async function readFeaturePage(
 		/**
 		 * The property the service orders the results by, where it honors one.
 		 *
-		 * Paging without an ordering rests on the service returning the same features in
-		 * the same order for every request, which no WFS guarantees.
+		 * A caller that pages without an ordering assumes the service returns the same
+		 * features in the same order for every request.
+		 * No WFS guarantees that.
+		 *
 		 * Estonia honors `sortBy=gml_id` and Flanders answers HTTP 504 for its identifier,
 		 * so the parameter is the caller's to supply or leave out.
 		 */
@@ -362,19 +365,20 @@ const VOID_REASON_TEXT = new Set(["unpopulated", "unknown", "withheld"])
 const FLATTENED_COMPONENT = /^component\d*_xlink_href$/iu
 
 /**
- * Every `component` reference an address carries, as the service wrote them.
+ * Every `component` reference an address has, as the service wrote them.
  *
  * Two encodings appear across the services measured.
  * Slovakia and Flanders write a `component` array of objects carrying `@href`.
  *
  * Estonia writes one flat property per slot, `component1_xlink_href` through `component6_xlink_href`,
  * and fills an unused slot with the string `unpopulated` rather than with a void object.
- * Reading only the array reported 0 references for every Estonian address, where each carries four.
+ * A read of only the array reported 0 references for every Estonian address.
+ * Each address has four.
  *
  * A reference may leave the service: Estonia's first three slots address its Administrative
  * Units theme at `AU_haldusyksused` rather than its Addresses theme.
- * That is a reference this module reads and {@linkcode resolveComponents} reports as unjoined
- * against Addresses features, which is the honest answer rather than a dropped reference.
+ * That is a reference this module reads. {@linkcode resolveComponents} reports it as
+ * unjoined against Addresses features rather than dropping it.
  */
 export function componentReferences(feature: GeoJSONFeature): readonly string[] {
 	const properties = feature.properties ?? {}
@@ -402,25 +406,26 @@ export function componentReferences(feature: GeoJSONFeature): readonly string[]
 /**
  * The key a component feature publishes for an address to reference it by.
  *
- * `identifier.value` is the INSPIRE external object identifier, which is what
- * Flanders writes on both sides of the join.
+ * `identifier.value` is the INSPIRE external object identifier.
+ * Flanders writes it on both sides of the join.
+ *
  * `gml_id` is the fallback for a service that publishes no identifier,
  * and a stored-query reference addresses that id.
  */
 export function componentIdentifier(feature: GeoJSONFeature): string | null {
 	const identifier = feature.properties?.["identifier"]
 
-	if (typeof identifier === "object" && identifier !== null) {
+	if (typeof identifier === "object" && identifier) {
 		const value = (identifier as Record<string, unknown>)["value"]
 
-		if (typeof value === "string" && value.length) return value
+		if (typeof value === "string" && value) return value
 	}
 
-	if (typeof identifier === "string" && identifier.length) return identifier
+	if (typeof identifier === "string" && identifier) return identifier
 
 	const gmlID = feature.properties?.["gml_id"] ?? feature.id
 
-	return gmlID === undefined || gmlID === null ? null : String(gmlID)
+	return gmlID ? String(gmlID) : null
 }
 
 /**
@@ -460,7 +465,7 @@ export function resolveComponents(
 	for (const feature of components) {
 		const identifier = componentIdentifier(feature)
 
-		if (identifier !== null) {
+		if (identifier) {
 			identifiers.add(identifier)
 		}
 	}
@@ -474,7 +479,7 @@ export function resolveComponents(
 		for (const href of componentReferences(address)) {
 			const key = componentJoinKey(href)
 
-			if (key === undefined) {
+			if (!key) {
 				unreadable++
 
 				continue

package/lib/tools/fetch/openaddresses.ts

@@ -9,7 +9,7 @@ import { APIClient, isSuccessStatus } from "@mailwoman/core/api"
 /* oxlint-disable sister-software/prefer-region-over-marks -- these markers label steps inside one
    procedure rather than sections of declarations. A region there folds no element a reader wants folded. */
 import { ByteFormatter } from "@mailwoman/core/fs/formatters"
-import { statPath, pathExists } from "@mailwoman/core/fs/readers"
+import { statPath, pathExists } from "@mailwoman/core/fs/readers/stat"
 import { openWriteStream, pipeline } from "@mailwoman/core/fs/streams"
 import { movePath, removePathIfPresent, makeDirectories } from "@mailwoman/core/fs/writers"
 import { sha256File } from "@mailwoman/core/hash"

package/lib/tools/fetch/vlaanderen-ad.ts

@@ -14,7 +14,7 @@
  *    adapter joins locally rather than resolving four references per address against 4,563,062 of
  *    them.
  * 2. `sortBy=gml:identifier` answers HTTP 504, so the service grants no ordering. The manifest
- *    records the pages taken and their order, which is what makes a harvest reproducible even though
+ *    records the pages taken and their order. That record makes a harvest reproducible even though
  *    a second harvest need not match the first.
  * 3. A bare `resultType=hits` answers `numberMatched="10000"` whatever `count` asks for. The count
  *    has to be taken past index 0: `startIndex=1` answers `numberMatched="4563062"`, and the
@@ -22,7 +22,7 @@
  *    returns none.
  *
  * Article 3 of the elected `Modellicentie voor gratis hergebruik Vlaanderen` grants reproduction and
- * transmission, which is what paging performs, and article 6 states that access is free. The
+ * transmission, and article 6 states that access is free. Those two grants cover paging. The
  * capabilities document's `ows:Fees` and `ows:AccessConstraints` describe the service rather than
  * the data, so neither is read here.
  */
@@ -48,7 +48,7 @@ export const VLAANDEREN_AD_WFS = "https://geo.api.vlaanderen.be/ad/wfs"
  * The `outputFormat` the harvest is written in.
  *
  * GML is the format whose `ad:component/@xlink:href` the adapter reads.
- * `application/json` carries the same references under `@href` and serves the same lost characters,
+ * `application/json` holds the same references under `@href` and serves the same lost characters,
  * so the choice is a matter of which reader the adapter uses rather than of what the service knows.
  */
 const OUTPUT_FORMAT = "application/gml+xml; version=3.2"
@@ -68,8 +68,7 @@ export const MAX_PAGE_SIZE = 10_000
  * Measured 2026-10-02, `ad:ThoroughfareName` holds 167,218 features against a 10,000 page cap,
  * so it needs 17 pages, while the other two hold 1,190 and 609 and fit in one.
  *
- * Writing the small ones as a single file would leave the harvester correct only
- * until one of them passed the cap.
+ * A single file for the small ones would leave the harvester correct only until one of them passed the cap.
  */
 const COMPONENT_STEMS = {
 	ThoroughfareName: "thoroughfare-name",
@@ -103,8 +102,8 @@ export interface FeaturePageBody {
 /**
  * Issues one `GetFeature` against the service.
  *
- * `#tools/fetch/wfs-harvest` owns the request, the exception check and the counts,
- * which every markup-serving WFS in this directory shares.
+ * `#tools/fetch/wfs-harvest` owns the request, the exception check and the counts.
+ * Every markup-serving WFS in this directory shares them.
  * This states the service and its context.
  *
  * @throws When the service answers an OGC exception report, so a 400 carrying
@@ -162,7 +161,7 @@ export interface HarvestVlaanderenOptions {
 	 * Features per component page, capped at {@link MAX_PAGE_SIZE} and defaulting to it.
 	 *
 	 * Only a test lowers this.
-	 * A component type is always taken whole, so a smaller page buys requests alone.
+	 * A component type is always taken whole, so a smaller page yields only more requests.
 	 */
 	componentPageSize?: number
 	signal?: AbortSignal
@@ -173,14 +172,14 @@ export interface HarvestVlaanderenOptions {
  *
  * The component types are taken first and whole, so a harvest that stops early
  * holds address pages whose references all resolve.
- * Taking addresses first would leave every page unjoinable.
+ * Addresses first would leave every page unjoinable.
  *
  * @returns The manifest as written.
  */
 /**
  * How much of a page is read to find its root attributes.
  *
- * `numberReturned` sits on the `wfs:FeatureCollection` element, which opens the document.
+ * `numberReturned` sits on the `wfs:FeatureCollection` element that opens the document.
  * A page of this service is about 20 MB, and reading all of one to find an attribute in
  * its first kilobyte would cost 1.6 GB of reads across a whole-region harvest.
  */
@@ -204,9 +203,10 @@ interface PageOnDisk {
  *
  * The feature count is read from each file's own `numberReturned` rather than assumed
  * from the page size, so a page the service answered short is recorded as short.
- * A file whose opening bytes state no `numberReturned` is left out, which makes the
- * harvest request that index again: a page of unknown extent is not a page this
- * harvest can count, and a run killed mid-write leaves exactly that.
+ * A file whose opening bytes state no `numberReturned` is left out.
+ *
+ * The harvest then requests that index again: a page of unknown extent is not a page
+ * this harvest can count, and a run killed mid-write leaves exactly that.
  *
  * A group small enough for one page is written under `<stem>.gml` with no index,
  * so that name reads as `startIndex` 0.
@@ -222,7 +222,7 @@ async function pagesOnDisk(root: PathBuilder, stem: string): Promise<Map<number,
 
 		if (!matched) continue
 
-		const startIndex = matched[1] === undefined ? 0 : Number(matched[1])
+		const startIndex = matched[1] ? Number(matched[1]) : 0
 
 		if (!Number.isInteger(startIndex)) continue
 
@@ -236,7 +236,7 @@ async function pagesOnDisk(root: PathBuilder, stem: string): Promise<Map<number,
 				xml: true,
 			})
 
-			if (returned === undefined || !/^\d+$/u.test(returned)) continue
+			if (!returned || !/^\d+$/u.test(returned)) continue
 
 			pages.set(startIndex, { file: name, numberReturned: Number(returned) })
 		} finally {
@@ -271,7 +271,7 @@ export async function harvestVlaanderenAD(
 		for (let startIndex = 0; startIndex < count; startIndex += componentPageSize) {
 			const held = existing.get(startIndex)
 
-			if (held !== undefined) {
+			if (held) {
 				componentFiles[typeName].push(held.file)
 				read += held.numberReturned
 
@@ -331,7 +331,7 @@ export async function harvestVlaanderenAD(
 
 		const existing = onDisk.get(startIndex)
 
-		if (existing !== undefined) {
+		if (existing) {
 			addressPages.push({ startIndex, file: existing.file, numberReturned: existing.numberReturned })
 
 			continue

package/lib/tools/fetch/wfs-harvest.ts

@@ -22,10 +22,10 @@
  *
  * 1. A service may ignore `startIndex` and answer every page with the first. `countWFSFeaturesByPaging`
  *    in `@mailwoman/core/api` refuses such a service by comparing two pages' leading feature. A
- *    harvest sees the same defect as two consecutive pages with equal bytes, which this refuses.
+ *    harvest sees the same defect as two consecutive pages with equal bytes. It refuses that pair.
  * 2. A service's own `numberMatched` may be a per-request cap rather than a count. The caller states
  *    what its count is and where it came from, and {@linkcode PagedWFSHarvestOptions.featureCount}
- *    carries both. No count is written into this module, and a harvest with no usable count ends on
+ *    holds both. No count is written into this module, and a harvest with no usable count ends on
  *    the first page that returns no features.
  * 3. A page may return fewer features than `count` asks for. The next `startIndex` therefore advances
  *    by the features the service returned rather than by the page size, so a service that caps a page
@@ -34,7 +34,8 @@
 
 import { APIClient, assertNoOGCServiceException, type CheckedWFSFeatureCount } from "@mailwoman/core/api"
 import { ByteFormatter } from "@mailwoman/core/fs/formatters"
-import { readFileRange, tryStat } from "@mailwoman/core/fs/readers"
+import { readFileRange } from "@mailwoman/core/fs/readers"
+import { tryStat } from "@mailwoman/core/fs/readers/stat"
 import { appendLocalTextFile, makeDirectories, removePathIfPresent, truncateFile } from "@mailwoman/core/fs/writers"
 import { sha256File, sha256Hex } from "@mailwoman/core/hash"
 import { stringifyJSON } from "@mailwoman/core/json"
@@ -69,7 +70,8 @@ export interface MarkupRoot {
 	 */
 	name: string
 	/**
-	 * The text between the name and the tag's terminator, which holds the attributes.
+	 * The text between the name and the tag's terminator.
+	 * It holds the attributes.
 	 */
 	attributes: string
 	/**
@@ -85,17 +87,18 @@ export interface MarkupRoot {
  * opening tag verbatim to open the file it assembles, and parsing a 1.6 MB page per request
  * to recover a tag that the first 400 bytes already hold costs a document parse per page.
  *
- * The leading `[A-Za-z_]` skips the XML declaration, which opens `<?xml`.
+ * The leading `[A-Za-z_]` skips the XML declaration.
+ * That declaration opens `<?xml`.
  */
 const ROOT_OPENING_TAG = /<([A-Za-z_][\w.:-]*)([^>]*)>/u
 
 /**
  * One attribute of an opening tag, by local name.
  */
-function tagAttribute(root: MarkupRoot, attribute: string): string | undefined {
+function tagAttribute(root: MarkupRoot, attribute: string): string | null {
 	const pattern = new RegExp(`(?:^|\\s)(?:[\\w.-]+:)?${attribute}\\s*=\\s*"([^"]*)"`, "iu")
 
-	return pattern.exec(root.attributes)?.[1]
+	return pattern.exec(root.attributes)?.[1] ?? null
 }
 
 /**
@@ -106,7 +109,7 @@ function tagAttribute(root: MarkupRoot, attribute: string): string | undefined {
 export function rootCount(root: MarkupRoot, attribute: string): number | null {
 	const value = tagAttribute(root, attribute)
 
-	return value !== undefined && /^\d+$/u.test(value) ? Number(value) : null
+	return value && /^\d+$/u.test(value) ? Number(value) : null
 }
 
 /**
@@ -133,7 +136,8 @@ export function readMarkupRoot(body: string, context: string): MarkupRoot {
 }
 
 /**
- * The content between a document's root tags, which for a `wfs:FeatureCollection` is its members.
+ * The content between a document's root tags.
+ * For a `wfs:FeatureCollection` those are its members.
  *
  * @throws When the root element is not closed, so a truncated transfer reads as
  * unreadable rather than as a page of no features.
@@ -214,7 +218,7 @@ export async function readWFSMarkupPage(
 		root,
 		numberReturned: rootCount(root, "numberReturned"),
 		numberMatched: rootCount(root, "numberMatched"),
-		timeStamp: tagAttribute(root, "timeStamp") ?? null,
+		timeStamp: tagAttribute(root, "timeStamp"),
 	}
 }
 
@@ -231,8 +235,9 @@ export interface WFSHarvestRequest {
 	/**
 	 * The property the service was asked to order by, or `null` where it grants no ordering.
 	 *
-	 * Without one, a resumed harvest rests on the service returning the same features
-	 * in the same order as the earlier run, which no WFS guarantees.
+	 * Without one, a resumed harvest rests on the service returning the same
+	 * features in the same order as the earlier run.
+	 * No WFS guarantees that order.
 	 */
 	sortBy: string | null
 }
@@ -252,8 +257,9 @@ export interface FeatureCountStatement {
 /**
  * The count a service states, or no count and the reason there is none.
  *
- * `readCheckedWFSFeatureCount` proves a reported `numberMatched` against a page of the
- * same type, which catches a service whose count is smaller than one of its own pages.
+ * `readCheckedWFSFeatureCount` proves a reported `numberMatched` against a page of the same type.
+ * That comparison catches a service whose count is smaller than one of its own pages.
+ *
  * It cannot catch a count that equals the service's page cap: no page can return more
  * features than the cap, so the page it asks for agrees with the cap every time.
  *
@@ -263,7 +269,7 @@ export interface FeatureCountStatement {
  *
  * The reported number is the cap, and a harvest that read it as a count would store 1,000
  * of the 8.6 million features the service holds and record the type as read whole.
- * A reported count equal to the cap is therefore carried as no count.
+ * The harvest therefore records no count when the reported number equals the cap.
  *
  * @param pageCap The largest page the service will serve, from its advertised `CountDefault`.
  */
@@ -305,7 +311,8 @@ export interface HarvestedPayload {
 	 */
 	footer?: string
 	/**
-	 * The features the service returned, which is what the next `startIndex` advances by.
+	 * The features the service returned.
+	 * The next `startIndex` advances by this number.
 	 *
 	 * `null` where the service stated none.
 	 * The harvest refuses that rather than reading it as zero.
@@ -324,7 +331,8 @@ export interface HarvestedPayload {
 export interface WFSHarvestPageRecord {
 	start_index: number
 	/**
-	 * The page size requested, which a service may answer with fewer features.
+	 * The page size requested.
+	 * A service may answer with fewer features.
 	 */
 	count: number
 	offset: number
@@ -508,15 +516,14 @@ function nextStartIndexOf(pages: readonly WFSHarvestPageRecord[]): number {
 }
 
 /**
- * The recorded pages that are actually on disk, with the file truncated back to the last of them.
+ * The recorded pages present on disk, with the file truncated back to the last of them.
  *
  * An interrupted run can leave a partial page at the end of the file,
  * or a footer the next page has to be appended past.
- * Both are resolved by cutting the file at the last page boundary the file reaches,
- * which is a page boundary rather than an arbitrary offset.
+ * Both are resolved by truncating the file at the last page boundary it reaches.
  *
- * @throws When the last surviving page's bytes no longer hash to what the manifest recorded,
- * which is a file that was altered rather than one that was cut short.
+ * @throws When the last surviving page's bytes no longer hash to what the manifest recorded.
+ * A mismatch means the file was altered after the harvest recorded it.
  */
 async function reconcileHarvestFile(
 	manifest: WFSHarvestManifest,
@@ -601,7 +608,7 @@ export interface HarvestCurrencyExpectation {
  * Two harvests need none:
  *
  * - A complete one whose data file still hashes to the digest the manifest records.
- * - A partial one that already holds `maxPages` pages, which is what a bounded probe asks for.
+ * - A partial one that already holds `maxPages` pages, the cap a bounded probe requests.
  *
  * @throws When a page's recorded byte range no longer hashes to its recorded digest,
  * so a file that was altered under its manifest is reported rather than used.
@@ -679,7 +686,7 @@ export async function harvestPagedWFS(options: PagedWFSHarvestOptions): Promise<
 	const recorded = await readManifest<WFSHarvestManifest>(manifestPath)
 	const resumable = recorded !== null && Array.isArray(recorded.pages) && describesSameRequest(recorded, options)
 
-	if (recorded !== null && !resumable) {
+	if (recorded && !resumable) {
 		options.report?.("  The manifest describes a different request — starting the harvest over")
 
 		await removePathIfPresent(dataPath)
@@ -833,7 +840,8 @@ export async function harvestPagedWFS(options: PagedWFSHarvestOptions): Promise<
  */
 export interface RunWFSHarvestOptions {
 	/**
-	 * The slug the harvest is written under and reported by, which matches the adapter's own id.
+	 * The slug the harvest is written under and reported by.
+	 * It matches the adapter's own id.
 	 */
 	slug: string
 
@@ -843,7 +851,8 @@ export interface RunWFSHarvestOptions {
 	outRoot: (segment: string) => PathBuilderLike
 
 	/**
-	 * The data file inside the harvest directory, which is also the adapter's `inputPath`.
+	 * The data file inside the harvest directory.
+	 * The adapter's `inputPath` points here.
 	 */
 	filename: string
 
@@ -868,12 +877,14 @@ export interface RunWFSHarvestOptions {
 	harvest: (client: Pick<APIClient, "fetch">) => Promise<WFSHarvestManifest>
 
 	/**
-	 * A client to use rather than constructing one, which a test supplies.
+	 * A client to use rather than constructing one.
+	 * A test supplies this.
 	 */
 	client?: Pick<APIClient, "fetch">
 
 	/**
-	 * A page cap, which makes an incomplete harvest a success.
+	 * A page cap.
+	 * A capped run treats an incomplete harvest as a success.
 	 */
 	maxPages?: number
 }

package/lib/tools/fetch.ts

@@ -48,48 +48,6 @@ import { fetchStateHISchools } from "#us/tools/fetch/state/hi-schools"
 import { fetchStateSources } from "#us/tools/fetch/state/sources"
 import { fetchTigerFull } from "#us/tools/fetch/tiger-full"
 
-export * from "#sg/tools/fetch/acra"
-export * from "#ee/tools/fetch/ads"
-export * from "#be/tools/fetch/brussels"
-export * from "#tools/fetch/vlaanderen-ad"
-export * from "#be/tools/fetch/wallonie"
-export * from "#it/tools/fetch/anac"
-export * from "#fr/tools/fetch/finess"
-export * from "#fr/tools/fetch/annuaire-education"
-export * from "#ro/tools/fetch/retea-scolara"
-export * from "#tools/fetch/cordis"
-export * from "#tools/fetch/gleif"
-export * from "#fr/tools/fetch/ban"
-export * from "#lu/tools/fetch/bd-adresses"
-export * from "#lv/tools/fetch/varis"
-export * from "#es/tools/fetch/bizkaia"
-export * from "#es/tools/fetch/catastro"
-export * from "#cz/tools/fetch/cuzk"
-export * from "#es/tools/fetch/gipuzkoa"
-export * from "#es/tools/fetch/navarra"
-export * from "#pl/tools/fetch/emuia"
-export * from "#dk/tools/fetch/inspire"
-export * from "#sk/tools/fetch/inspire"
-export * from "#tw/tools/fetch/gcis"
-export * from "#tools/fetch/geonames/dump"
-export * from "#tools/fetch/geonames/postal"
-export * from "#jp/tools/fetch/houjin"
-export * from "#us/tools/fetch/hrsa"
-export * from "#us/tools/fetch/imls-pls"
-export * from "#kr/tools/fetch/juso"
-export * from "#nl/tools/fetch/kadaster"
-export * from "#kr/tools/fetch/localdata"
-export * from "#no/tools/fetch/matrikkelen"
-export * from "#us/tools/fetch/nad"
-export * from "#us/tools/fetch/nppes"
-export * from "#tools/fetch/openaddresses"
-export * from "#tools/fetch/ourairports"
-export * from "#fi/tools/fetch/ryhti"
-export * from "#us/tools/fetch/state/hi-schools"
-export * from "#us/tools/fetch/state/sources"
-export * from "#us/tools/fetch/tiger-full"
-export * from "#tools/fetch/wikidata-subvenue"
-
 /**
  * The fetcher for each source id that `mailwoman corpus fetch` accepts.
  */

package/lib/tools/golden/expand.ts

@@ -113,43 +113,43 @@ export interface ExpandGoldenOptions {
 	/**
 	 * Corpus test-split parquet path(s), comma-separated.
 	 *
-	 * Default: the v0.2.0 test parquet file under the data root.
+	 * @defaultValue the v0.2.0 test parquet file under the data root.
 	 */
 	corpus?: string
 	/**
 	 * Total seeds to process.
 	 *
-	 * Default `100` (pilot).
+	 * @defaultValue `100` (pilot).
 	 */
 	count?: number
 	/**
 	 * Variants requested per seed.
 	 *
-	 * Default `5`.
+	 * @defaultValue `5`
 	 */
 	variants?: number
 	/**
 	 * Jsonl output path.
 	 *
-	 * Default `data/eval/golden/candidates/expand-<ts>.jsonl`.
+	 * @defaultValue `data/eval/golden/candidates/expand-<ts>.jsonl`
 	 */
 	output?: string
 	/**
 	 * LLM provider.
 	 *
-	 * Default `deepseek`.
+	 * @defaultValue `deepseek`
 	 */
 	provider?: "deepseek" | "anthropic"
 	/**
 	 * Model id.
 	 *
-	 * Default depends on provider.
+	 * @defaultValue depends on provider.
 	 */
 	model?: string
 	/**
 	 * Parallel LLM calls.
 	 *
-	 * Default `4`.
+	 * @defaultValue `4`
 	 */
 	concurrency?: number
 	/**
@@ -444,7 +444,7 @@ function parseCandidates(text: string): Candidate[] {
 	if (Array.isArray(parsed)) return parsed as Candidate[]
 
 	// Some providers wrap in {"variants": [...]} or {"candidates": [...]}
-	if (typeof parsed === "object" && parsed !== null) {
+	if (typeof parsed === "object" && parsed) {
 		for (const key of ["variants", "candidates", "results"]) {
 			const v = (parsed as Record<string, unknown>)[key]