@mailwoman/corpus 10.0.0 → 10.2.0

package/out/tools/fetch/geonames/dump.d.ts

@@ -3,32 +3,40 @@
  * @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 type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download/index";
+import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download";
 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;
 }
@@ -47,42 +55,53 @@ 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[];
 }
 /**
- * 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.
  *
- * 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.
+ * 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.
+ *
+ * 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 declare 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 declare function parseCountryInfo(text: string): Array<{
     country: string;
     capital: string;
 }>;
 /**
- * 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 declare function fetchGeonamesDumps(options: FetchGeonamesDumpOptions, report?: (line: string) => void): Promise<FetchSummary & {
     skippedPresent: string[];

package/out/tools/fetch/geonames/dump.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dump.d.ts","sourceRoot":"","sources":["../../../../lib/tools/fetch/geonames/dump.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAQH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAgBjF,MAAM,WAAW,wBAAyB,SAAQ,gBAAgB;IACjE;;OAEG;IACH,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC7B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;OAEG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;CACf;AAED,UAAU,qBAAqB;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,oBAAoB;IACpC,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,EAAE,MAAM,CAAA;IACrB,KAAK,EAAE,qBAAqB,EAAE,CAAA;IAC9B;;OAEG;IACH,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB;;;OAGG;IACH,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB;;;;;OAKG;IACH,oBAAoB,EAAE,MAAM,EAAE,CAAA;CAC9B;AAQD;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAuB5D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAiB1F;AAQD;;;GAGG;AACH,wBAAsB,kBAAkB,CACvC,OAAO,EAAE,wBAAwB,EACjC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAC7B,OAAO,CAAC,YAAY,GAAG;IAAE,cAAc,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CA2FtD"}
+{"version":3,"file":"dump.d.ts","sourceRoot":"","sources":["../../../../lib/tools/fetch/geonames/dump.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AASH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAgB3E,MAAM,WAAW,wBAAyB,SAAQ,gBAAgB;IACjE;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC7B;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,OAAO,CAAA;CACf;AAED,UAAU,qBAAqB;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,QAAQ,EAAE,MAAM,CAAA;IAChB,UAAU,EAAE,MAAM,CAAA;IAClB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,MAAM,CAAA;CACb;AAED,MAAM,WAAW,oBAAoB;IACpC,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;IACf,WAAW,EAAE,MAAM,CAAA;IACnB,aAAa,EAAE,MAAM,CAAA;IACrB,KAAK,EAAE,qBAAqB,EAAE,CAAA;IAC9B;;OAEG;IACH,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB;;;;OAIG;IACH,WAAW,EAAE,MAAM,EAAE,CAAA;IACrB;;;;;;OAMG;IACH,oBAAoB,EAAE,MAAM,EAAE,CAAA;CAC9B;AASD;;;;;;;;;;;GAWG;AACH,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAuB5D;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,CAAC;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC,CAc1F;AAQD;;;;;;;;GAQG;AACH,wBAAsB,kBAAkB,CACvC,OAAO,EAAE,wBAAwB,EACjC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAC7B,OAAO,CAAC,YAAY,GAAG;IAAE,cAAc,EAAE,MAAM,EAAE,CAAA;CAAE,CAAC,CA6FtD"}

package/out/tools/fetch/geonames/dump.js

@@ -3,47 +3,54 @@
  * @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 { downloadToFile, HTTPStatusError, writeManifest } from "#tools/fetch/download/index";
+import { TSVSpliterator } from "spliterator";
+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".
  */
 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";
 /**
- * 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) {
     let start = 0;
@@ -64,37 +71,39 @@ export function looksLikeGazetteerDump(text) {
     return false;
 }
 /**
- * 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) {
     const rows = [];
-    // 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())
+    for (const cols of TSVSpliterator.from(text, { header: false, enableQuoteHandling: false })) {
+        const country = cols[0]?.toUpperCase();
+        if (!country || country.startsWith("#"))
             continue;
-        // 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?.length === 2) {
-            rows.push({ country, capital: cols[5]?.trim() ?? "" });
+        if (country.length === 2) {
+            rows.push({ country, capital: cols[5] ?? "" });
         }
     }
     return rows;
 }
 /**
- * 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, report) {
     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`,
         dest: countryInfoDest,
@@ -111,7 +120,7 @@ export async function fetchGeonamesDumps(options, report) {
     const wrongFormatPresent = [];
     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))) {
                 skippedPresent.push(country);
@@ -124,7 +133,7 @@ export async function fetchGeonamesDumps(options, report) {
         }
         const filename = `${country}.zip`;
         const url = `${baseURL}/${filename}`;
-        const zipDest = join(options.outRoot, filename);
+        const zipDest = options.outRoot(filename);
         report?.(`=== ${SLUG} / ${country}`);
         try {
             await downloadToFile({ url, dest: zipDest, timeoutMs: 300_000, retries: 2, report });
@@ -142,8 +151,10 @@ export async function fetchGeonamesDumps(options, report) {
         catch (error) {
             await removePathIfPresent(zipDest);
             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);
@@ -165,7 +176,7 @@ export async function fetchGeonamesDumps(options, report) {
         unavailable,
         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 };
 }
 //# sourceMappingURL=dump.js.map

package/out/tools/fetch/geonames/dump.js.map

@@ -1 +1 @@
-{"version":3,"file":"dump.js","sourceRoot":"","sources":["../../../../lib/tools/fetch/geonames/dump.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"dump.js","sourceRoot":"","sources":["../../../../lib/tools/fetch/geonames/dump.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAA;AAC7F,OAAO,EAAE,UAAU,EAAE,MAAM,iCAAiC,CAAA;AAC5D,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,4BAA4B,CAAA;AACjF,OAAO,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AACjD,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAG5C,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAEtF;;GAEG;AACH,MAAM,cAAc,GAAG,GAAG,CAAA;AAE1B,MAAM,IAAI,GAAG,eAAe,CAAA;AAE5B;;;GAGG;AACH,MAAM,QAAQ,GAAG,2CAA2C,CAAA;AA4D5D;;;;GAIG;AACH,MAAM,sBAAsB,GAAG,EAAE,CAAA;AAEjC;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,sBAAsB,CAAC,IAAY;IAClD,IAAI,KAAK,GAAG,CAAC,CAAA;IAEb,OAAO,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;QAC5B,MAAM,GAAG,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,CAAA;QACrC,MAAM,IAAI,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE,GAAG,CAAC,CAAA;QAEpE,IAAI,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YACjB,IAAI,IAAI,GAAG,CAAC,CAAA;YAEZ,KAAK,IAAI,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;gBAC1E,IAAI,EAAE,CAAA;YACP,CAAC;YAED,OAAO,IAAI,KAAK,sBAAsB,GAAG,CAAC,CAAA;QAC3C,CAAC;QAED,IAAI,GAAG,KAAK,CAAC,CAAC;YAAE,MAAK;QAErB,KAAK,GAAG,GAAG,GAAG,CAAC,CAAA;IAChB,CAAC;IAED,OAAO,KAAK,CAAA;AACb,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,IAAY;IAC5C,MAAM,IAAI,GAAgD,EAAE,CAAA;IAE5D,KAAK,MAAM,IAAI,IAAI,cAAc,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,EAAE,KAAK,EAAE,CAAC,EAAE,CAAC;QAC7F,MAAM,OAAO,GAAG,IAAI,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAA;QAEtC,IAAI,CAAC,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAQ;QAEjD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC1B,IAAI,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAA;QAC/C,CAAC;IACF,CAAC;IAED,OAAO,IAAI,CAAA;AACZ,CAAC;AAED;;;GAGG;AACH,MAAM,kBAAkB,GAAG,MAAM,CAAA;AAEjC;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACvC,OAAiC,EACjC,MAA+B;IAE/B,MAAM,eAAe,CAAC,OAAO,CAAC,OAAO,CAAC,CAAA;IAEtC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,QAAQ,CAAA;IAC3C,MAAM,eAAe,GAAG,OAAO,CAAC,OAAO,CAAC,iBAAiB,CAAC,CAAA;IAE1D,MAAM,cAAc,CAAC;QACpB,GAAG,EAAE,GAAG,OAAO,kBAAkB;QACjC,IAAI,EAAE,eAAe;QACrB,SAAS,EAAE,OAAO;QAClB,OAAO,EAAE,CAAC;QACV,MAAM;KACN,CAAC,CAAA;IAEF,MAAM,OAAO,GAAG,gBAAgB,CAAC,MAAM,iBAAiB,CAAC,eAAe,CAAC,CAAC,CAAA;IAC1E,MAAM,SAAS,GAAG,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,GAAG,CAAC,OAAO,CAAC,CAAA;IAElH,MAAM,OAAO,GAA4B,EAAE,CAAA;IAC3C,MAAM,WAAW,GAAa,EAAE,CAAA;IAChC,MAAM,WAAW,GAAa,EAAE,CAAA;IAChC,MAAM,cAAc,GAAa,EAAE,CAAA;IACnC,MAAM,kBAAkB,GAAa,EAAE,CAAA;IACvC,IAAI,OAAO,GAAG,CAAC,CAAA;IAEf,KAAK,MAAM,OAAO,IAAI,SAAS,EAAE,CAAC;QACjC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,GAAG,OAAO,MAAM,CAAC,CAAA;QAEjD,IAAI,CAAC,OAAO,CAAC,KAAK,IAAI,CAAC,MAAM,UAAU,CAAC,OAAO,CAAC,CAAC,EAAE,CAAC;YACnD,IAAI,sBAAsB,CAAC,MAAM,YAAY,CAAC,OAAO,EAAE,kBAAkB,CAAC,CAAC,EAAE,CAAC;gBAC7E,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;YAC7B,CAAC;iBAAM,CAAC;gBACP,MAAM,EAAE,CAAC,KAAK,OAAO,iFAAiF,CAAC,CAAA;gBACvG,kBAAkB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;YACjC,CAAC;YAED,SAAQ;QACT,CAAC;QAED,MAAM,QAAQ,GAAG,GAAG,OAAO,MAAM,CAAA;QACjC,MAAM,GAAG,GAAG,GAAG,OAAO,IAAI,QAAQ,EAAE,CAAA;QACpC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAA;QAEzC,MAAM,EAAE,CAAC,OAAO,IAAI,MAAM,OAAO,EAAE,CAAC,CAAA;QAEpC,IAAI,CAAC;YACJ,MAAM,cAAc,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,CAAC,CAAA;YACpF,MAAM,eAAe,CAAC,OAAO,EAAE,GAAG,OAAO,MAAM,EAAE,OAAO,CAAC,CAAA;YACzD,MAAM,mBAAmB,CAAC,OAAO,CAAC,CAAA;YAElC,OAAO,CAAC,IAAI,CAAC;gBACZ,OAAO;gBACP,QAAQ,EAAE,GAAG,OAAO,MAAM;gBAC1B,UAAU,EAAE,GAAG;gBACf,MAAM,EAAE,MAAM,UAAU,CAAC,OAAO,CAAC;gBACjC,KAAK,EAAE,CAAC,MAAM,eAAe,CAAC,OAAO,CAAC,CAAC,CAAC,UAAU;aAClD,CAAC,CAAA;YAEF,OAAO,EAAE,CAAA;QACV,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,mBAAmB,CAAC,OAAO,CAAC,CAAA;YAElC,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;YAEtE,8BAA8B;YAC9B,oCAAoC;YACpC,kCAAkC;YAClC,+DAA+D;YAC/D,IAAI,KAAK,YAAY,eAAe,IAAI,KAAK,CAAC,MAAM,KAAK,cAAc,EAAE,CAAC;gBACzE,MAAM,EAAE,CAAC,KAAK,OAAO,yDAAyD,CAAC,CAAA;gBAC/E,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;YAC1B,CAAC;iBAAM,CAAC;gBACP,MAAM,EAAE,CAAC,KAAK,OAAO,KAAK,OAAO,EAAE,CAAC,CAAA;YACrC,CAAC;YAED,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;QAC1B,CAAC;IACF,CAAC;IAED,MAAM,QAAQ,GAAyB;QACtC,MAAM,EAAE,IAAI;QACZ,QAAQ,EAAE,OAAO;QACjB,OAAO,EAAE,WAAW;QACpB,WAAW,EAAE,UAAU;QACvB,aAAa,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACvC,KAAK,EAAE,OAAO;QACd,eAAe,EAAE,cAAc,CAAC,QAAQ,EAAE;QAC1C,WAAW;QACX,oBAAoB,EAAE,kBAAkB,CAAC,QAAQ,EAAE;KACnD,CAAA;IAED,MAAM,aAAa,CAAC,OAAO,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC,CAAA;IAE/D,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,EAAE,WAAW,EAAE,cAAc,EAAE,CAAA;AAC5G,CAAC"}

package/out/tools/fetch/geonames/postal.d.ts

@@ -3,74 +3,39 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Fetch the GeoNames per-country postal-code exports — the only source in this family that carries a
- *   `(postcode, locality, region)` triple with the NAMES inline.
+ *   Fetch the GeoNames per-country postal-code exports — the only source in this family that includes a
+ *   `(postcode, locality, region)` triple with the names inline.
  *
  *   Source : https://download.geonames.org/export/zip/<CC>.zip
  *   License: CC-BY-4.0, attribute "GeoNames". Tier B.
  *
- *   ## Why this source and not a join
- *
- *   A postcode slice is only useful to the corpus if a postcode reaches a locality and a region. Two routes exist and
- *   only one of them works everywhere:
- *
- *   - **`parent_id`** — `postalcode-intl.db` carries a real parent that resolves in the admin gazetteer (measured: NL
- *     97.5% of rows linked, FR 90.7%, DE 66.1%, ES 34.9%, IT 27.4%, and 93.8–100% of those resolve to a
- *     `locality`/`localadmin`). It is also the ONLY slice that does: `postalcode-geonames-intl.db` and every
- *     `postalcode-<cc>-overture.db` carry `parent_id = 0` on every row, so five countries have this route and the rest
- *     have none.
- *   - **Nearest locality centroid** — the obvious fallback, and it does not work. Scored against the `parent_id` truth
- *     on 1,000–1,500 postcodes per country: NL 81.1%, DE 44.7%, ES 35.1%, FR 29.0%, IT 13.5%. A locality's centroid
- *     sits at its middle, so a postcode near the edge is routinely closer to a neighbouring town's centroid than to its
- *     own. Under 50% for four of the five, which is not a join.
- *
- *   The GeoNames export sidesteps both: columns 3 and 4 ARE the place and admin1 names, so there is nothing to join and
- *   nothing to approximate. `@mailwoman/corpus`'s `geonames-postal` adapter consumes it directly.
- *
- *   ## Coverage is not universal, and the gap is the point
- *
- *   GeoNames publishes ~80 countries, NOT all of them. Venezuela returns 404 — so a VE postcode slice cannot be built
- *   from this source at any effort, and that is an acquisition question rather than a build one. Ask for a country
- *   before assuming it is there; an absent country fails as one entry, never as the whole run.
- *
- *   ## Row counts from this source overstate, for some countries by exactly 2×
- *
- *   Countries whose postcode format contains a hyphen are published TWICE — once `3750-000`, once `3750000`. Measured
- *   on the slice built from this source: PT 395,544 rows over 197,772 distinct codes and PL 40,598 over 20,299, both
- *   exactly 2.00×, while AU, CZ and AT (no hyphen in the format) are 1.00×. A consumer sizing a slice from the row
- *   count doubles its estimate for those countries.
- *
- *   ## Why `downloadToFile` and not `APIClient`
- *
- *   Same split `AGENTS.md` draws and the `ourairports` sibling explains: these are static file transfers from a plain
- *   file host, run once per refresh. The pacing, retry and caching `APIClient` exists for have nothing to act on here.
- *
- *   Invoke via `mailwoman corpus fetch geonames-postal --countries pt,au,nz`.
+ *   GeoNames publishes roughly 80 countries. An absent country fails as one entry, never as the whole run.
  */
-import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download/index";
+import type { BaseFetchOptions, FetchSummary } from "#tools/fetch/download";
 /**
  * Countries fetched when the caller names none.
  *
- * These are the ones the corpus wants and cannot get from `postalcode-intl.db`'s `parent_id` route — see the header for
- * why that route covers exactly five countries. Venezuela is deliberately absent because GeoNames does not publish it.
+ * Venezuela is deliberately absent because GeoNames does not publish it.
  */
 export declare const GEONAMES_POSTAL_DEFAULT_COUNTRIES: readonly ["PT", "AU", "NZ", "IE", "BR", "ZA", "MX"];
 export interface FetchGeonamesPostalOptions extends BaseFetchOptions {
     /**
-     * ISO alpha-2 codes, in any casing. Defaults to {@linkcode GEONAMES_POSTAL_DEFAULT_COUNTRIES}.
+     * ISO alpha-2 codes in any casing.
+     *
+     * @defaultValue {@linkcode GEONAMES_POSTAL_DEFAULT_COUNTRIES}
      */
     countries?: readonly string[];
     /**
-     * Export directory to read from. Defaults to GeoNames' own. Exists so the 404-is-a-coverage-finding behaviour can be
-     * exercised against a local server rather than by asking GeoNames for a country it does not have.
+     * Export directory to read from.
+     *
+     * @defaultValue GeoNames' own, so the 404-is-coverage behavior can be exercised against a local server.
      */
     baseURL?: string;
 }
 /**
- * Download the requested GeoNames postal zips into `<outRoot>/geonames-postal/`, with a sibling `MANIFEST.json`
- * carrying each file's origin URL, sha256 and byte count, plus the countries the source does not publish.
- *
- * A country the source does not carry is counted as failed and named in `failedCodes` — it does not stop the rest.
+ * Download the requested GeoNames postal zips into `<outRoot>/geonames-postal/` with
+ * a sibling `manifest.json`; a country the source does not cover is counted as failed
+ * and recorded in `failedCodes` without stopping the rest.
  */
 export declare function fetchGeonamesPostal(options: FetchGeonamesPostalOptions, report?: (line: string) => void): Promise<FetchSummary>;
 //# sourceMappingURL=postal.d.ts.map

package/out/tools/fetch/geonames/postal.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"postal.d.ts","sourceRoot":"","sources":["../../../../lib/tools/fetch/geonames/postal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAMH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,6BAA6B,CAAA;AAejF;;;;;GAKG;AACH,eAAO,MAAM,iCAAiC,YAAI,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAU,CAAA;AAEpG,MAAM,WAAW,0BAA2B,SAAQ,gBAAgB;IACnE;;OAEG;IACH,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC7B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CAChB;AAwBD;;;;;GAKG;AACH,wBAAsB,mBAAmB,CACxC,OAAO,EAAE,0BAA0B,EACnC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAC7B,OAAO,CAAC,YAAY,CAAC,CA2DvB"}
+{"version":3,"file":"postal.d.ts","sourceRoot":"","sources":["../../../../lib/tools/fetch/geonames/postal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAgB3E;;;;GAIG;AACH,eAAO,MAAM,iCAAiC,YAAI,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAU,CAAA;AAEpG,MAAM,WAAW,0BAA2B,SAAQ,gBAAgB;IACnE;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC7B;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CAChB;AAyBD;;;;GAIG;AACH,wBAAsB,mBAAmB,CACxC,OAAO,EAAE,0BAA0B,EACnC,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,GAC7B,OAAO,CAAC,YAAY,CAAC,CA0DvB"}

package/out/tools/fetch/geonames/postal.js

@@ -3,78 +3,40 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Fetch the GeoNames per-country postal-code exports — the only source in this family that carries a
- *   `(postcode, locality, region)` triple with the NAMES inline.
+ *   Fetch the GeoNames per-country postal-code exports — the only source in this family that includes a
+ *   `(postcode, locality, region)` triple with the names inline.
  *
  *   Source : https://download.geonames.org/export/zip/<CC>.zip
  *   License: CC-BY-4.0, attribute "GeoNames". Tier B.
  *
- *   ## Why this source and not a join
- *
- *   A postcode slice is only useful to the corpus if a postcode reaches a locality and a region. Two routes exist and
- *   only one of them works everywhere:
- *
- *   - **`parent_id`** — `postalcode-intl.db` carries a real parent that resolves in the admin gazetteer (measured: NL
- *     97.5% of rows linked, FR 90.7%, DE 66.1%, ES 34.9%, IT 27.4%, and 93.8–100% of those resolve to a
- *     `locality`/`localadmin`). It is also the ONLY slice that does: `postalcode-geonames-intl.db` and every
- *     `postalcode-<cc>-overture.db` carry `parent_id = 0` on every row, so five countries have this route and the rest
- *     have none.
- *   - **Nearest locality centroid** — the obvious fallback, and it does not work. Scored against the `parent_id` truth
- *     on 1,000–1,500 postcodes per country: NL 81.1%, DE 44.7%, ES 35.1%, FR 29.0%, IT 13.5%. A locality's centroid
- *     sits at its middle, so a postcode near the edge is routinely closer to a neighbouring town's centroid than to its
- *     own. Under 50% for four of the five, which is not a join.
- *
- *   The GeoNames export sidesteps both: columns 3 and 4 ARE the place and admin1 names, so there is nothing to join and
- *   nothing to approximate. `@mailwoman/corpus`'s `geonames-postal` adapter consumes it directly.
- *
- *   ## Coverage is not universal, and the gap is the point
- *
- *   GeoNames publishes ~80 countries, NOT all of them. Venezuela returns 404 — so a VE postcode slice cannot be built
- *   from this source at any effort, and that is an acquisition question rather than a build one. Ask for a country
- *   before assuming it is there; an absent country fails as one entry, never as the whole run.
- *
- *   ## Row counts from this source overstate, for some countries by exactly 2×
- *
- *   Countries whose postcode format contains a hyphen are published TWICE — once `3750-000`, once `3750000`. Measured
- *   on the slice built from this source: PT 395,544 rows over 197,772 distinct codes and PL 40,598 over 20,299, both
- *   exactly 2.00×, while AU, CZ and AT (no hyphen in the format) are 1.00×. A consumer sizing a slice from the row
- *   count doubles its estimate for those countries.
- *
- *   ## Why `downloadToFile` and not `APIClient`
- *
- *   Same split `AGENTS.md` draws and the `ourairports` sibling explains: these are static file transfers from a plain
- *   file host, run once per refresh. The pacing, retry and caching `APIClient` exists for have nothing to act on here.
- *
- *   Invoke via `mailwoman corpus fetch geonames-postal --countries pt,au,nz`.
+ *   GeoNames publishes roughly 80 countries. An absent country fails as one entry, never as the whole run.
  */
 import { makeDirectories } from "@mailwoman/core/fs/writers";
 import { sha256File } from "@mailwoman/core/hash";
-import { join } from "path-ts";
-import { downloadToFile, HTTPStatusError, writeManifest } from "#tools/fetch/download/index";
+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".
+ * The status that means the source does not publish this country rather than that the transfer failed.
  */
 const HTTP_NOT_FOUND = 404;
 const SLUG = "geonames-postal";
 /**
- * GeoNames' own export directory. One zip per ISO alpha-2 code, each holding `<CC>.txt` plus the shared `readme.txt`.
+ * GeoNames' own export directory, one zip per ISO alpha-2 code holding `<CC>.txt`
+ * plus the shared `readme.txt`.
  */
 const BASE_URL = "https://download.geonames.org/export/zip";
 /**
  * Countries fetched when the caller names none.
  *
- * These are the ones the corpus wants and cannot get from `postalcode-intl.db`'s `parent_id` route — see the header for
- * why that route covers exactly five countries. Venezuela is deliberately absent because GeoNames does not publish it.
+ * Venezuela is deliberately absent because GeoNames does not publish it.
  */
 export const GEONAMES_POSTAL_DEFAULT_COUNTRIES = ["PT", "AU", "NZ", "IE", "BR", "ZA", "MX"];
 /**
- * Download the requested GeoNames postal zips into `<outRoot>/geonames-postal/`, with a sibling `MANIFEST.json`
- * carrying each file's origin URL, sha256 and byte count, plus the countries the source does not publish.
- *
- * A country the source does not carry is counted as failed and named in `failedCodes` — it does not stop the rest.
+ * Download the requested GeoNames postal zips into `<outRoot>/geonames-postal/` with
+ * a sibling `manifest.json`; a country the source does not cover is counted as failed
+ * and recorded in `failedCodes` without stopping the rest.
  */
 export async function fetchGeonamesPostal(options, report) {
-    const destDir = join(options.outRoot, SLUG);
+    const destDir = options.outRoot(SLUG);
     await makeDirectories(destDir);
     const countries = (options.countries ?? GEONAMES_POSTAL_DEFAULT_COUNTRIES).map((code) => code.trim().toUpperCase());
     const baseURL = options.baseURL ?? BASE_URL;
@@ -87,7 +49,7 @@ export async function fetchGeonamesPostal(options, report) {
     for (const country of countries) {
         const filename = `${country}.zip`;
         const url = `${baseURL}/${filename}`;
-        const dest = join(destDir, filename);
+        const dest = destDir(filename);
         report?.(`=== ${SLUG} / ${country}`);
         try {
             const { bytes } = await downloadToFile({ url, dest, timeoutMs: 300_000, retries: 2, retryDelayMs, report });
@@ -96,10 +58,9 @@ export async function fetchGeonamesPostal(options, report) {
         }
         catch (error) {
             const message = error instanceof Error ? error.message : String(error);
-            // A 404 here means GeoNames does not publish the country at all, which is a different finding from a failed
-            // transfer and the one a caller planning a slice needs to see. Branch on the TYPED status: matching message
-            // prose classified a 500 as "unpublished" whenever the URL happened to contain the substring 404 — an
-            // ephemeral test-server port did exactly that in CI.
+            // A 404 means GeoNames does not publish the country at all, a different
+            // finding from a failed transfer.
+            // Branch on the typed status rather than message prose.
             if (error instanceof HTTPStatusError && error.status === HTTP_NOT_FOUND) {
                 report?.(`✗ ${country}: GeoNames does not publish a postal export for this country`);
                 unavailable.push(country);
@@ -120,7 +81,7 @@ export async function fetchGeonamesPostal(options, report) {
         files: entries,
         unavailable,
     };
-    await writeManifest(join(destDir, "MANIFEST.json"), manifest);
+    await writeManifest(destDir("MANIFEST.json"), manifest);
     return { fetched, skipped: 0, failed, failedCodes };
 }
 //# sourceMappingURL=postal.js.map

package/out/tools/fetch/geonames/postal.js.map

@@ -1 +1 @@
-{"version":3,"file":"postal.js","sourceRoot":"","sources":["../../../../lib/tools/fetch/geonames/postal.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"postal.js","sourceRoot":"","sources":["../../../../lib/tools/fetch/geonames/postal.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAA;AAC5D,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAGjD,OAAO,EAAE,cAAc,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAA;AAEtF;;GAEG;AACH,MAAM,cAAc,GAAG,GAAG,CAAA;AAE1B,MAAM,IAAI,GAAG,iBAAiB,CAAA;AAE9B;;;GAGG;AACH,MAAM,QAAQ,GAAG,0CAA0C,CAAA;AAE3D;;;;GAIG;AACH,MAAM,CAAC,MAAM,iCAAiC,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,CAAU,CAAA;AAwCpG;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACxC,OAAmC,EACnC,MAA+B;IAE/B,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,CAAA;IACrC,MAAM,eAAe,CAAC,OAAO,CAAC,CAAA;IAE9B,MAAM,SAAS,GAAG,CAAC,OAAO,CAAC,SAAS,IAAI,iCAAiC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAA;IACnH,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,QAAQ,CAAA;IAC3C,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAA;IACzC,MAAM,OAAO,GAA8B,EAAE,CAAA;IAC7C,MAAM,WAAW,GAAa,EAAE,CAAA;IAChC,MAAM,WAAW,GAAa,EAAE,CAAA;IAChC,IAAI,OAAO,GAAG,CAAC,CAAA;IACf,IAAI,MAAM,GAAG,CAAC,CAAA;IAEd,KAAK,MAAM,OAAO,IAAI,SAAS,EAAE,CAAC;QACjC,MAAM,QAAQ,GAAG,GAAG,OAAO,MAAM,CAAA;QACjC,MAAM,GAAG,GAAG,GAAG,OAAO,IAAI,QAAQ,EAAE,CAAA;QACpC,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;QAE9B,MAAM,EAAE,CAAC,OAAO,IAAI,MAAM,OAAO,EAAE,CAAC,CAAA;QAEpC,IAAI,CAAC;YACJ,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,cAAc,CAAC,EAAE,GAAG,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,YAAY,EAAE,MAAM,EAAE,CAAC,CAAA;YAE3G,OAAO,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,CAAC,CAAA;YAE3F,OAAO,EAAE,CAAA;QACV,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YAChB,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;YAEtE,wEAAwE;YACxE,kCAAkC;YAClC,wDAAwD;YACxD,IAAI,KAAK,YAAY,eAAe,IAAI,KAAK,CAAC,MAAM,KAAK,cAAc,EAAE,CAAC;gBACzE,MAAM,EAAE,CAAC,KAAK,OAAO,8DAA8D,CAAC,CAAA;gBACpF,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;YAC1B,CAAC;iBAAM,CAAC;gBACP,MAAM,EAAE,CAAC,KAAK,OAAO,KAAK,OAAO,EAAE,CAAC,CAAA;YACrC,CAAC;YAED,WAAW,CAAC,IAAI,CAAC,OAAO,CAAC,CAAA;YAEzB,MAAM,EAAE,CAAA;QACT,CAAC;IACF,CAAC;IAED,MAAM,QAAQ,GAA2B;QACxC,MAAM,EAAE,uBAAuB;QAC/B,QAAQ,EAAE,OAAO;QACjB,OAAO,EAAE,WAAW;QACpB,WAAW,EAAE,UAAU;QACvB,aAAa,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;QACvC,KAAK,EAAE,OAAO;QACd,WAAW;KACX,CAAA;IAED,MAAM,aAAa,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,QAAQ,CAAC,CAAA;IAEvD,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,CAAA;AACpD,CAAC"}