@mailwoman/corpus 9.2.0 → 9.3.0

package/out/adapters/wof-admin-jp/adapter.js

@@ -0,0 +1,161 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `wof-admin-jp`: Japanese admin-hierarchy adapter.
+ *
+ *   PROTOTYPE — not yet wired into the Stage 3 training corpus. Demonstrates the JP address shape and
+ *   synthesizes BIO-labeled training rows from the global WOF SQLite.
+ *
+ *   JP addresses differ from US/EU in three ways:
+ *
+ *   1. **Reversed ordering** — region → county → locality → block → house_number "東京都世田谷区南町1-2-3" not
+ *        "1-2-3 Minamicho, Setagaya, Tokyo"
+ *   2. **No street names** — most JP addresses use a block/sub-block grid system. The "neighbourhood"
+ *        placetype (丁目) is the closest analog to a street but is actually a grid cell.
+ *   3. **Postcode-first convention** — addresses are often prefixed with `〒NNN-NNNN`.
+ *
+ *   Schema mapping to ComponentTags (subset of Stage 3 + JP-specific Phase 6 tags):
+ *
+ *   | JP concept | WOF placetype | ComponentTag (Phase 6) |
+ *   |-----------------|--------------------|-----------------------| | 都道府県 (prefecture) | region |
+ *   region (or prefecture) | | 市区町村 (city/ward) | county/locality | locality (or municipality) | |
+ *   丁目 (chome) | neighbourhood | block (Phase 6 tag) | | 番地 (banchi) | (synth) | sub_block | | 号
+ *   (gō) | (synth) | house_number | | 〒 (postcode prefix) | — | postcode |
+ *
+ *   This adapter currently emits only the admin chain (region → locality → block). House numbers and
+ *   sub-blocks require a different data source (JP postcode database or real-world address dumps
+ *   from MLIT/JapanPost).
+ */
+import { isPresent } from "@mailwoman/core/objects";
+import { allRows, getRow } from "@mailwoman/core/utils";
+import { DatabaseClient } from "@mailwoman/sqlite/client";
+/**
+ * Ancestry hops walked upward from a WOF record before giving up — deeper than any real JP admin chain.
+ */
+const MAX_ANCESTRY_DEPTH = 6;
+/**
+ * Registry id for this adapter. Stamped into every row it emits, so a corpus record can be traced back to the dataset
+ * it came from.
+ */
+export const WOF_ADMIN_JP_ADAPTER_ID = "wof-admin-jp";
+/**
+ * Walk parent chain up to 6 levels, over a place table already resident in memory.
+ *
+ * `resolve` is the override for a parent outside the preloaded set (a chain that leaves the country); it is a point
+ * query, so keeping the common case out of it is the whole point. The GeoJSON adapters' in-memory analogue is
+ * `buildAncestryIndex` (`#utils`); the two stay separate because this one's rows come from SQLite and a chain can leave
+ * the preloaded country set.
+ */
+function chainOf(byID, resolve, startID) {
+    const out = [];
+    let id = startID;
+    for (let i = 0; i < MAX_ANCESTRY_DEPTH && id > 0; i++) {
+        const row = byID.get(id) ?? resolve(id);
+        if (!row)
+            break;
+        out.push(row);
+        id = row.parent_id;
+    }
+    return out;
+}
+/**
+ * Pick the best display name for a place: prefer Japanese variant, fall back to English.
+ */
+function pickName(row, jpnNames) {
+    return jpnNames.get(row.id) ?? row.name;
+}
+/**
+ * Synthesize a JP address from a hierarchy chain.
+ *
+ * Format: `〒<postcode>? <region><locality><neighbourhood>?`
+ *
+ * No house numbers yet — needs MLIT data.
+ */
+export function synthesizeJpAddress(chain, jpnNames) {
+    const region = chain.find((r) => r.placetype === "region");
+    const locality = chain.find((r) => r.placetype === "locality" || r.placetype === "county");
+    if (!region || !locality)
+        return null;
+    const neighbourhood = chain.find((r) => r.placetype === "neighbourhood");
+    const regionName = pickName(region, jpnNames);
+    const localityName = pickName(locality, jpnNames);
+    const neighbourhoodName = neighbourhood ? pickName(neighbourhood, jpnNames) : null;
+    const components = {
+        region: regionName,
+        locality: localityName,
+        country: "JP",
+    };
+    if (neighbourhoodName) {
+        components.dependent_locality = neighbourhoodName;
+    }
+    const raw = [regionName, localityName, neighbourhoodName].filter(isPresent).join("");
+    return { raw, components };
+}
+/**
+ * Build the JP adapter. Reads from the unified global WOF SQLite, walks admin chains starting from neighbourhoods, and
+ * yields canonical rows.
+ */
+export function createWOFAdminJpAdapter() {
+    return {
+        id: WOF_ADMIN_JP_ADAPTER_ID,
+        defaultLicense: "CC-BY-4.0",
+        description: "Japanese admin hierarchy from WOF (synthesized addresses without house numbers).",
+        async *rows(opts) {
+            if (opts.country && opts.country !== "JP") {
+                throw new Error(`wof-admin-jp adapter: only JP supported, got country=${opts.country}`);
+            }
+            using db = new DatabaseClient(opts.inputPath, { readOnly: true });
+            const jpnNamesStmt = db.prepare(`SELECT id, name FROM names WHERE language = 'jpn'`);
+            const jpnNames = new Map();
+            for (const row of jpnNamesStmt.all()) {
+                if (!jpnNames.has(row.id)) {
+                    jpnNames.set(row.id, row.name);
+                }
+            }
+            // One read of the JP place table instead of a fresh `prepare` + up to six point queries per
+            // seed; there are tens of thousands of neighbourhood seeds.
+            const byID = new Map();
+            for (const row of allRows(db.prepare(`SELECT id, name, placetype, parent_id, country FROM spr WHERE country='JP'`))) {
+                byID.set(row.id, row);
+            }
+            const outsideStmt = db.prepare(`SELECT id, name, placetype, parent_id, country FROM spr WHERE id = ?`);
+            const resolveOutside = (id) => {
+                const row = getRow(outsideStmt, id);
+                if (row) {
+                    byID.set(id, row);
+                }
+                return row;
+            };
+            const seeds = [...byID.values()].filter((row) => row.placetype === "neighbourhood");
+            let emitted = 0;
+            for (const seed of seeds) {
+                if (opts.signal?.aborted)
+                    break;
+                if (opts.limit !== undefined && emitted >= opts.limit)
+                    break;
+                const chain = chainOf(byID, resolveOutside, seed.id);
+                const synth = synthesizeJpAddress(chain, jpnNames);
+                if (!synth)
+                    continue;
+                yield {
+                    raw: synth.raw,
+                    components: synth.components,
+                    country: "JP",
+                    locale: "ja-JP",
+                    source: WOF_ADMIN_JP_ADAPTER_ID,
+                    source_id: `${WOF_ADMIN_JP_ADAPTER_ID}-${seed.id}`,
+                    corpus_version: "",
+                    license: "CC-BY-4.0",
+                };
+                emitted++;
+            }
+        },
+    };
+}
+/**
+ * The configured adapter instance registered with the corpus builder.
+ */
+export const wofAdminJpAdapter = createWOFAdminJpAdapter();
+//# sourceMappingURL=adapter.js.map

package/out/adapters/wof-admin-jp/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../lib/adapters/wof-admin-jp/adapter.ts"],"names":[],"mappings":"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"}

package/out/adapters/wof-admin-json/adapter.d.ts

@@ -0,0 +1,79 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `wof-admin`: Who's On First admin GeoJSON-bundle adapter.
+ *
+ *   **Phase 1.5.1 pivot.** The original Phase 1.5 SQLite adapter (formerly at
+ *   `packages/corpus/lib/adapters/wof-admin/`, removed in this same change) was replaced by this
+ *   one because the SQLite distribution path was unworkable for the real corpus build:
+ *
+ *   1. `dist.whosonfirst.org/sqlite/` is dead (NXDOMAIN); the Geocode-Earth mirror is the only one.
+ *   2. The Geocode-Earth-hosted postalcode DB tags every row `mz:is_current = -1` ("unknown but treated
+ *        as active"); the SQLite adapter's `is_current = 1` predicate emitted zero rows.
+ *   3. The `names` table in the SQLite distribution is empty — localized `name:*` variants live in a
+ *        separate distribution. The St. Petersburg / Mt. Vernon / Ft. Lauderdale alternation cases
+ *        (the original Phase 1.5.1 motivator) cannot be solved on the SQLite path even with a
+ *        patched `is_current` predicate.
+ *
+ *   Input: a directory containing one or more cloned `whosonfirst-data-admin-<cc>` GitHub repos. Each
+ *   repo has `data/XXX/YYY/ZZZ/<wof-id>.geojson` files; `**\/*.geojson` walks the tree recursively.
+ *   Alternate-geometry siblings (`-alt-*`) are skipped — they're separate exports of the same
+ *   record, not new records.
+ *
+ *   Per record, the adapter emits one row per `(name-variant, hierarchy-variant)` pair:
+ *
+ *   - **Name variants**: the canonical `wof:name` (slot key `default`) plus every `name:*` localized
+ *       variant present on the feature (`name:eng_x_preferred`, `name:eng_x_colloquial`,
+ *       `name:rus_x_preferred`, ...). This is the Phase 1.5.1 fix for the St. Petersburg case:
+ *       `"Saint Petersburg"` (canonical) and `"St. Petersburg"` (eng_x_colloquial) both become
+ *       training rows for the same WOF id.
+ *   - **Hierarchy variants** (unchanged from the SQLite adapter): locality → 3 variants, region → 2,
+ *       country → 1, county → 1.
+ *
+ *   `source_id` is `wof-admin-<wof_id>-<name-slot>-<hierarchy-variant>`. The previous SQLite adapter
+ *   used `wof-admin-<wof_id>-<hierarchy-variant>` (no name slot); the new format adds a name-slot
+ *   segment so the colloquial / preferred / per-locale variants survive dedup independently.
+ *
+ *   License: CC0. The adapter stamps every row with `CC0-1.0`.
+ */
+import { type WOFVariantSpec } from "#adapters/wof-json-rows";
+import type { CorpusAdapter } from "#types";
+import { type WOFRecord } from "#utils";
+/**
+ * Compute the hierarchy variants for a record given its ancestry chain and the chosen `selfName`.
+ *
+ * `selfName` is the surface form to use for the record's own component (locality / region / country / subregion).
+ * Callers pass the canonical `wof:name` for the `"default"` slot and a `name:*` localized value for variant slots;
+ * ancestor names always come from the ancestor's canonical `wof:name`.
+ *
+ * Country variants substitute `COUNTRY_DISPLAY_NAME` for the default slot so the OpenCage template produces the
+ * canonicalized form (`"United States of America"`), matching the legacy SQLite adapter's behavior.
+ */
+export declare function variantsFor(row: WOFRecord, ancestry: WOFRecord[], selfName: string): WOFVariantSpec[];
+/**
+ * Build the per-record name-slot list. The canonical `"default"` slot uses the OpenCage-canonical country form when the
+ * record is itself a country (matches SQLite-adapter behavior); every other placetype's default slot uses `wof:name`
+ * verbatim.
+ */
+export declare function nameSlotsFor(rec: WOFRecord): Array<{
+    key: string;
+    value: string;
+}>;
+/**
+ * Registry id for this adapter. Stamped into every row it emits, so a corpus record can be traced back to the dataset
+ * it came from.
+ */
+export declare const WOF_ADMIN_ADAPTER_ID = "wof-admin";
+/**
+ * Construct the wof-admin JSON-bundle adapter. The adapter is stateless across runs; calling this twice with the same
+ * input directory produces byte-identical `canonical.jsonl` (records are emitted in sorted `wof:id` order to be
+ * insensitive to filesystem walk ordering).
+ */
+export declare function createWOFAdminAdapter(): CorpusAdapter;
+/**
+ * Single shared instance, suitable for `defaultAdapterRegistry`.
+ */
+export declare const wofAdminAdapter: CorpusAdapter;
+//# sourceMappingURL=adapter.d.ts.map

package/out/adapters/wof-admin-json/adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../../../lib/adapters/wof-admin-json/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAKH,OAAO,EAKN,KAAK,cAAc,EACnB,MAAM,yBAAyB,CAAA;AAChC,OAAO,KAAK,EAAgC,aAAa,EAAE,MAAM,QAAQ,CAAA;AACzE,OAAO,EAAoC,KAAK,SAAS,EAAE,MAAM,QAAQ,CAAA;AAgCzE;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CAAC,GAAG,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,QAAQ,EAAE,MAAM,GAAG,cAAc,EAAE,CAkErG;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,SAAS,GAAG,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAOlF;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,cAAc,CAAA;AAE/C;;;;GAIG;AACH,wBAAgB,qBAAqB,IAAI,aAAa,CAsCrD;AAED;;GAEG;AACH,eAAO,MAAM,eAAe,eAA0B,CAAA"}

package/out/adapters/wof-admin-json/adapter.js

@@ -0,0 +1,197 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `wof-admin`: Who's On First admin GeoJSON-bundle adapter.
+ *
+ *   **Phase 1.5.1 pivot.** The original Phase 1.5 SQLite adapter (formerly at
+ *   `packages/corpus/lib/adapters/wof-admin/`, removed in this same change) was replaced by this
+ *   one because the SQLite distribution path was unworkable for the real corpus build:
+ *
+ *   1. `dist.whosonfirst.org/sqlite/` is dead (NXDOMAIN); the Geocode-Earth mirror is the only one.
+ *   2. The Geocode-Earth-hosted postalcode DB tags every row `mz:is_current = -1` ("unknown but treated
+ *        as active"); the SQLite adapter's `is_current = 1` predicate emitted zero rows.
+ *   3. The `names` table in the SQLite distribution is empty — localized `name:*` variants live in a
+ *        separate distribution. The St. Petersburg / Mt. Vernon / Ft. Lauderdale alternation cases
+ *        (the original Phase 1.5.1 motivator) cannot be solved on the SQLite path even with a
+ *        patched `is_current` predicate.
+ *
+ *   Input: a directory containing one or more cloned `whosonfirst-data-admin-<cc>` GitHub repos. Each
+ *   repo has `data/XXX/YYY/ZZZ/<wof-id>.geojson` files; `**\/*.geojson` walks the tree recursively.
+ *   Alternate-geometry siblings (`-alt-*`) are skipped — they're separate exports of the same
+ *   record, not new records.
+ *
+ *   Per record, the adapter emits one row per `(name-variant, hierarchy-variant)` pair:
+ *
+ *   - **Name variants**: the canonical `wof:name` (slot key `default`) plus every `name:*` localized
+ *       variant present on the feature (`name:eng_x_preferred`, `name:eng_x_colloquial`,
+ *       `name:rus_x_preferred`, ...). This is the Phase 1.5.1 fix for the St. Petersburg case:
+ *       `"Saint Petersburg"` (canonical) and `"St. Petersburg"` (eng_x_colloquial) both become
+ *       training rows for the same WOF id.
+ *   - **Hierarchy variants** (unchanged from the SQLite adapter): locality → 3 variants, region → 2,
+ *       country → 1, county → 1.
+ *
+ *   `source_id` is `wof-admin-<wof_id>-<name-slot>-<hierarchy-variant>`. The previous SQLite adapter
+ *   used `wof-admin-<wof_id>-<hierarchy-variant>` (no name slot); the new format adds a name-slot
+ *   segment so the colloquial / preferred / per-locale variants survive dedup independently.
+ *
+ *   License: CC0. The adapter stamps every row with `CC0-1.0`.
+ */
+import { COUNTRY_DISPLAY_NAME, emitWOFJSONRows, LOCALE_BY_COUNTRY, nameSlotsFor as wofNameSlotsFor, } from "#adapters/wof-json-rows";
+import { buildAncestryIndex, walkFeatures } from "#utils";
+/**
+ * Map a WOF placetype to a Mailwoman `ComponentTag`, or `undefined` to skip.
+ *
+ * Per-adapter deliberately (the postalcode adapter carries its own): each table is a record FILTER for its adapter's
+ * emission set, not a shared vocabulary.
+ */
+function placetypeToTag(placetype) {
+    switch (placetype) {
+        case "country":
+        case "nation":
+            return "country";
+        case "macroregion":
+        case "region":
+            return "region";
+        case "macrocounty":
+        case "county":
+        case "localadmin":
+            return "subregion";
+        case "locality":
+            return "locality";
+        case "borough":
+        case "macrohood":
+        case "neighbourhood":
+        case "microhood":
+            return "dependent_locality";
+        default:
+            return undefined;
+    }
+}
+/**
+ * Compute the hierarchy variants for a record given its ancestry chain and the chosen `selfName`.
+ *
+ * `selfName` is the surface form to use for the record's own component (locality / region / country / subregion).
+ * Callers pass the canonical `wof:name` for the `"default"` slot and a `name:*` localized value for variant slots;
+ * ancestor names always come from the ancestor's canonical `wof:name`.
+ *
+ * Country variants substitute `COUNTRY_DISPLAY_NAME` for the default slot so the OpenCage template produces the
+ * canonicalized form (`"United States of America"`), matching the legacy SQLite adapter's behavior.
+ */
+export function variantsFor(row, ancestry, selfName) {
+    const selfTag = placetypeToTag(row.placetype);
+    if (!selfTag)
+        return [];
+    const region = ancestry.find((a) => placetypeToTag(a.placetype) === "region");
+    const country = ancestry.find((a) => placetypeToTag(a.placetype) === "country");
+    const countryDisplay = COUNTRY_DISPLAY_NAME[row.country] ?? country?.name ?? row.country;
+    const variants = [];
+    switch (selfTag) {
+        case "locality":
+        case "dependent_locality": {
+            variants.push({ suffix: "self", components: { [selfTag]: selfName } });
+            if (region) {
+                variants.push({
+                    suffix: "with-region",
+                    components: { [selfTag]: selfName, region: region.name },
+                });
+            }
+            if (region && country) {
+                variants.push({
+                    suffix: "with-region-country",
+                    components: { [selfTag]: selfName, region: region.name, country: countryDisplay },
+                });
+            }
+            else if (!region && country) {
+                variants.push({
+                    suffix: "with-country",
+                    components: { [selfTag]: selfName, country: countryDisplay },
+                });
+            }
+            return variants;
+        }
+        case "region": {
+            variants.push({ suffix: "self", components: { region: selfName } });
+            if (country) {
+                variants.push({
+                    suffix: "with-country",
+                    components: { region: selfName, country: countryDisplay },
+                });
+            }
+            return variants;
+        }
+        case "country": {
+            variants.push({ suffix: "self", components: { country: selfName } });
+            return variants;
+        }
+        case "subregion": {
+            variants.push({ suffix: "self", components: { subregion: selfName } });
+            return variants;
+        }
+        default:
+            return [];
+    }
+}
+/**
+ * Build the per-record name-slot list. The canonical `"default"` slot uses the OpenCage-canonical country form when the
+ * record is itself a country (matches SQLite-adapter behavior); every other placetype's default slot uses `wof:name`
+ * verbatim.
+ */
+export function nameSlotsFor(rec) {
+    return wofNameSlotsFor(rec, {
+        canonicalName: (record) => placetypeToTag(record.placetype) === "country"
+            ? (COUNTRY_DISPLAY_NAME[record.country] ?? record.name)
+            : record.name,
+    });
+}
+/**
+ * Registry id for this adapter. Stamped into every row it emits, so a corpus record can be traced back to the dataset
+ * it came from.
+ */
+export const WOF_ADMIN_ADAPTER_ID = "wof-admin";
+/**
+ * Construct the wof-admin JSON-bundle adapter. The adapter is stateless across runs; calling this twice with the same
+ * input directory produces byte-identical `canonical.jsonl` (records are emitted in sorted `wof:id` order to be
+ * insensitive to filesystem walk ordering).
+ */
+export function createWOFAdminAdapter() {
+    return {
+        id: WOF_ADMIN_ADAPTER_ID,
+        defaultLicense: "CC0-1.0",
+        description: "Who's On First admin GeoJSON bundles (countries, regions, counties, localities) — multi-name variants per record.",
+        async *rows(opts) {
+            // Pass 1: scan every GeoJSON file once, build the in-memory record index.
+            // We keep only records whose placetype maps to a ComponentTag — irrelevant placetypes
+            // (campus, county-region hybrids on which Mailwoman has no opinion) are dropped here so
+            // they don't inflate the ancestry index. Country-filtered runs prune to the matching
+            // country code too; the ancestors of a same-country record live in the same admin repo.
+            const byID = new Map();
+            for await (const rec of walkFeatures(opts.inputPath, { signal: opts.signal })) {
+                if (opts.signal?.aborted)
+                    return;
+                if (opts.country && rec.country !== opts.country)
+                    continue;
+                if (!placetypeToTag(rec.placetype))
+                    continue;
+                byID.set(rec.id, rec);
+            }
+            const ancestry = buildAncestryIndex(byID);
+            // Pass 2: emit rows in sorted-id order for deterministic JSONL.
+            yield* emitWOFJSONRows({
+                records: byID,
+                ancestry,
+                adapterOptions: opts,
+                adapterID: WOF_ADMIN_ADAPTER_ID,
+                localeByCountry: LOCALE_BY_COUNTRY,
+                nameSlotsFor,
+                variantsFor,
+            });
+        },
+    };
+}
+/**
+ * Single shared instance, suitable for `defaultAdapterRegistry`.
+ */
+export const wofAdminAdapter = createWOFAdminAdapter();
+//# sourceMappingURL=adapter.js.map

package/out/adapters/wof-admin-json/adapter.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"adapter.js","sourceRoot":"","sources":["../../../lib/adapters/wof-admin-json/adapter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAKH,OAAO,EACN,oBAAoB,EACpB,eAAe,EACf,iBAAiB,EACjB,YAAY,IAAI,eAAe,GAE/B,MAAM,yBAAyB,CAAA;AAEhC,OAAO,EAAE,kBAAkB,EAAE,YAAY,EAAkB,MAAM,QAAQ,CAAA;AAEzE;;;;;GAKG;AACH,SAAS,cAAc,CAAC,SAAwC;IAC/D,QAAQ,SAAS,EAAE,CAAC;QACnB,KAAK,SAAS,CAAC;QACf,KAAK,QAAQ;YACZ,OAAO,SAAS,CAAA;QACjB,KAAK,aAAa,CAAC;QACnB,KAAK,QAAQ;YACZ,OAAO,QAAQ,CAAA;QAChB,KAAK,aAAa,CAAC;QACnB,KAAK,QAAQ,CAAC;QACd,KAAK,YAAY;YAChB,OAAO,WAAW,CAAA;QACnB,KAAK,UAAU;YACd,OAAO,UAAU,CAAA;QAClB,KAAK,SAAS,CAAC;QACf,KAAK,WAAW,CAAC;QACjB,KAAK,eAAe,CAAC;QACrB,KAAK,WAAW;YACf,OAAO,oBAAoB,CAAA;QAC5B;YACC,OAAO,SAAS,CAAA;IAClB,CAAC;AACF,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,GAAc,EAAE,QAAqB,EAAE,QAAgB;IAClF,MAAM,OAAO,GAAG,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC,CAAA;IAE7C,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAA;IAEvB,MAAM,MAAM,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,QAAQ,CAAC,CAAA;IAC7E,MAAM,OAAO,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,cAAc,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,SAAS,CAAC,CAAA;IAC/E,MAAM,cAAc,GAAG,oBAAoB,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,OAAO,EAAE,IAAI,IAAI,GAAG,CAAC,OAAO,CAAA;IAExF,MAAM,QAAQ,GAAqB,EAAE,CAAA;IAErC,QAAQ,OAAO,EAAE,CAAC;QACjB,KAAK,UAAU,CAAC;QAChB,KAAK,oBAAoB,CAAC,CAAC,CAAC;YAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAA;YAEtE,IAAI,MAAM,EAAE,CAAC;gBACZ,QAAQ,CAAC,IAAI,CAAC;oBACb,MAAM,EAAE,aAAa;oBACrB,UAAU,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE;iBACxD,CAAC,CAAA;YACH,CAAC;YAED,IAAI,MAAM,IAAI,OAAO,EAAE,CAAC;gBACvB,QAAQ,CAAC,IAAI,CAAC;oBACb,MAAM,EAAE,qBAAqB;oBAC7B,UAAU,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,IAAI,EAAE,OAAO,EAAE,cAAc,EAAE;iBACjF,CAAC,CAAA;YACH,CAAC;iBAAM,IAAI,CAAC,MAAM,IAAI,OAAO,EAAE,CAAC;gBAC/B,QAAQ,CAAC,IAAI,CAAC;oBACb,MAAM,EAAE,cAAc;oBACtB,UAAU,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,EAAE;iBAC5D,CAAC,CAAA;YACH,CAAC;YAED,OAAO,QAAQ,CAAA;QAChB,CAAC;QAED,KAAK,QAAQ,CAAC,CAAC,CAAC;YACf,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAA;YAEnE,IAAI,OAAO,EAAE,CAAC;gBACb,QAAQ,CAAC,IAAI,CAAC;oBACb,MAAM,EAAE,cAAc;oBACtB,UAAU,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,OAAO,EAAE,cAAc,EAAE;iBACzD,CAAC,CAAA;YACH,CAAC;YAED,OAAO,QAAQ,CAAA;QAChB,CAAC;QAED,KAAK,SAAS,CAAC,CAAC,CAAC;YAChB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAA;YAEpE,OAAO,QAAQ,CAAA;QAChB,CAAC;QAED,KAAK,WAAW,CAAC,CAAC,CAAC;YAClB,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,EAAE,EAAE,SAAS,EAAE,QAAQ,EAAE,EAAE,CAAC,CAAA;YAEtE,OAAO,QAAQ,CAAA;QAChB,CAAC;QAED;YACC,OAAO,EAAE,CAAA;IACX,CAAC;AACF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,YAAY,CAAC,GAAc;IAC1C,OAAO,eAAe,CAAC,GAAG,EAAE;QAC3B,aAAa,EAAE,CAAC,MAAM,EAAE,EAAE,CACzB,cAAc,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,SAAS;YAC7C,CAAC,CAAC,CAAC,oBAAoB,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,MAAM,CAAC,IAAI,CAAC;YACvD,CAAC,CAAC,MAAM,CAAC,IAAI;KACf,CAAC,CAAA;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,WAAW,CAAA;AAE/C;;;;GAIG;AACH,MAAM,UAAU,qBAAqB;IACpC,OAAO;QACN,EAAE,EAAE,oBAAoB;QACxB,cAAc,EAAE,SAAS;QACzB,WAAW,EACV,mHAAmH;QAEpH,KAAK,CAAC,CAAC,IAAI,CAAC,IAAoB;YAC/B,0EAA0E;YAC1E,sFAAsF;YACtF,wFAAwF;YACxF,qFAAqF;YACrF,wFAAwF;YACxF,MAAM,IAAI,GAAG,IAAI,GAAG,EAAqB,CAAA;YAEzC,IAAI,KAAK,EAAE,MAAM,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC;gBAC/E,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO;oBAAE,OAAM;gBAEhC,IAAI,IAAI,CAAC,OAAO,IAAI,GAAG,CAAC,OAAO,KAAK,IAAI,CAAC,OAAO;oBAAE,SAAQ;gBAE1D,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC,SAAS,CAAC;oBAAE,SAAQ;gBAC5C,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,EAAE,GAAG,CAAC,CAAA;YACtB,CAAC;YAED,MAAM,QAAQ,GAAG,kBAAkB,CAAC,IAAI,CAAC,CAAA;YAEzC,gEAAgE;YAChE,KAAK,CAAC,CAAC,eAAe,CAAC;gBACtB,OAAO,EAAE,IAAI;gBACb,QAAQ;gBACR,cAAc,EAAE,IAAI;gBACpB,SAAS,EAAE,oBAAoB;gBAC/B,eAAe,EAAE,iBAAiB;gBAClC,YAAY;gBACZ,WAAW;aACX,CAAC,CAAA;QACH,CAAC;KACD,CAAA;AACF,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,qBAAqB,EAAE,CAAA"}

package/out/adapters/wof-json-rows.d.ts

@@ -0,0 +1,62 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Deterministic canonical-row emission shared by WOF GeoJSON adapters.
+ */
+import type { ComponentTag } from "@mailwoman/core/types";
+import type { AdapterOptions, CanonicalRow } from "#types";
+import { type WOFRecord } from "#utils";
+/**
+ * Display name for the country, keyed by ISO 3166-1 alpha-2.
+ *
+ * Must be the **OpenCage-canonical** surface form: the `address-formatter` library expands some country names en route
+ * to its output (e.g. `"United States"` → `"United States of America"`). If `components.country` and the formatted
+ * `raw` disagree, alignment will fail downstream. Keying off the canonical form keeps the two in lockstep.
+ *
+ * Phase 1 US + FR only; extend as new locales come online. Missing countries fall back to the country row's `wof:name`,
+ * accepting the alignment risk for non-canonicalized names.
+ */
+export declare const COUNTRY_DISPLAY_NAME: Record<string, string>;
+/**
+ * BCP-47 locale defaulting for the corpus row's `locale` field. Defaulted by country.
+ */
+export declare const LOCALE_BY_COUNTRY: Record<string, string>;
+export interface WOFVariantSpec {
+    suffix: string;
+    components: Partial<Record<ComponentTag, string>>;
+}
+export interface NameSlotOptions {
+    /**
+     * Canonical surface for the record's own `"default"` slot. Default `rec.name` verbatim; the admin adapter substitutes
+     * the OpenCage-canonical {@link COUNTRY_DISPLAY_NAME} for country records.
+     */
+    canonicalName?: (rec: WOFRecord) => string;
+}
+/**
+ * Build the per-record name-slot list: the canonical `"default"` slot, then every `name:*` variant deduplicated against
+ * it so a redundant `"default"`-equivalent row is not emitted under a localized key.
+ */
+export declare function nameSlotsFor(rec: WOFRecord, options?: NameSlotOptions): Array<{
+    key: string;
+    value: string;
+}>;
+interface EmitWOFJSONRowsOptions {
+    records: ReadonlyMap<number, WOFRecord>;
+    ancestry: ReadonlyMap<number, WOFRecord[]>;
+    adapterOptions: AdapterOptions;
+    adapterID: string;
+    localeByCountry: Readonly<Record<string, string>>;
+    shouldEmit?: (record: WOFRecord) => boolean;
+    nameSlotsFor: (record: WOFRecord) => Array<{
+        key: string;
+        value: string;
+    }>;
+    variantsFor: (record: WOFRecord, ancestry: WOFRecord[], selfName: string) => WOFVariantSpec[];
+}
+/**
+ * Emit aligned rows in WOF-id order, enforcing the adapter limit across all name and hierarchy variants.
+ */
+export declare function emitWOFJSONRows(options: EmitWOFJSONRowsOptions): Generator<CanonicalRow>;
+export {};
+//# sourceMappingURL=wof-json-rows.d.ts.map

package/out/adapters/wof-json-rows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wof-json-rows.d.ts","sourceRoot":"","sources":["../../lib/adapters/wof-json-rows.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AAGzD,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,QAAQ,CAAA;AAC1D,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,QAAQ,CAAA;AAEzD;;;;;;;;;GASG;AACH,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAGvD,CAAA;AAED;;GAEG;AACH,eAAO,MAAM,iBAAiB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAGpD,CAAA;AAED,MAAM,WAAW,cAAc;IAC9B,MAAM,EAAE,MAAM,CAAA;IACd,UAAU,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CAAA;CACjD;AAED,MAAM,WAAW,eAAe;IAC/B;;;OAGG;IACH,aAAa,CAAC,EAAE,CAAC,GAAG,EAAE,SAAS,KAAK,MAAM,CAAA;CAC1C;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,SAAS,EAAE,OAAO,GAAE,eAAoB,GAAG,KAAK,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC,CAajH;AAED,UAAU,sBAAsB;IAC/B,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,CAAC,CAAA;IACvC,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CAAA;IAC1C,cAAc,EAAE,cAAc,CAAA;IAC9B,SAAS,EAAE,MAAM,CAAA;IACjB,eAAe,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;IACjD,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,OAAO,CAAA;IAC3C,YAAY,EAAE,CAAC,MAAM,EAAE,SAAS,KAAK,KAAK,CAAC;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IAC1E,WAAW,EAAE,CAAC,MAAM,EAAE,SAAS,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE,QAAQ,EAAE,MAAM,KAAK,cAAc,EAAE,CAAA;CAC7F;AAED;;GAEG;AACH,wBAAiB,eAAe,CAAC,OAAO,EAAE,sBAAsB,GAAG,SAAS,CAAC,YAAY,CAAC,CA8CzF"}

package/out/adapters/wof-json-rows.js

@@ -0,0 +1,83 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ * @file Deterministic canonical-row emission shared by WOF GeoJSON adapters.
+ */
+import { formatAddress, reconcileComponents } from "@mailwoman/formatter";
+import { normalizeNameKey } from "#utils";
+/**
+ * Display name for the country, keyed by ISO 3166-1 alpha-2.
+ *
+ * Must be the **OpenCage-canonical** surface form: the `address-formatter` library expands some country names en route
+ * to its output (e.g. `"United States"` → `"United States of America"`). If `components.country` and the formatted
+ * `raw` disagree, alignment will fail downstream. Keying off the canonical form keeps the two in lockstep.
+ *
+ * Phase 1 US + FR only; extend as new locales come online. Missing countries fall back to the country row's `wof:name`,
+ * accepting the alignment risk for non-canonicalized names.
+ */
+export const COUNTRY_DISPLAY_NAME = {
+    US: "United States of America",
+    FR: "France",
+};
+/**
+ * BCP-47 locale defaulting for the corpus row's `locale` field. Defaulted by country.
+ */
+export const LOCALE_BY_COUNTRY = {
+    US: "en-US",
+    FR: "fr-FR",
+};
+/**
+ * Build the per-record name-slot list: the canonical `"default"` slot, then every `name:*` variant deduplicated against
+ * it so a redundant `"default"`-equivalent row is not emitted under a localized key.
+ */
+export function nameSlotsFor(rec, options = {}) {
+    const canonicalSelfName = options.canonicalName?.(rec) ?? rec.name;
+    const seen = new Set([canonicalSelfName]);
+    const slots = [{ key: "default", value: canonicalSelfName }];
+    for (const [rawKey, value] of rec.nameVariants) {
+        if (seen.has(value))
+            continue;
+        seen.add(value);
+        slots.push({ key: normalizeNameKey(rawKey), value });
+    }
+    return slots;
+}
+/**
+ * Emit aligned rows in WOF-id order, enforcing the adapter limit across all name and hierarchy variants.
+ */
+export function* emitWOFJSONRows(options) {
+    const { records, ancestry, adapterOptions, adapterID, localeByCountry, shouldEmit = () => true, nameSlotsFor: slotsForRecord, variantsFor, } = options;
+    let emitted = 0;
+    for (const id of [...records.keys()].toSorted((a, b) => a - b)) {
+        if (adapterOptions.signal?.aborted)
+            return;
+        const record = records.get(id);
+        if (!shouldEmit(record))
+            continue;
+        for (const slot of slotsForRecord(record)) {
+            for (const variant of variantsFor(record, ancestry.get(id) ?? [], slot.value)) {
+                if (adapterOptions.limit !== undefined && emitted >= adapterOptions.limit)
+                    return;
+                const raw = formatAddress(variant.components, record.country, { separator: ", " });
+                if (!raw)
+                    continue;
+                const components = reconcileComponents(variant.components, raw);
+                if (!Object.keys(components).length)
+                    continue;
+                yield {
+                    raw,
+                    components,
+                    country: record.country,
+                    locale: localeByCountry[record.country],
+                    source: adapterID,
+                    source_id: `${adapterID}-${record.id}-${slot.key}-${variant.suffix}`,
+                    corpus_version: "",
+                    license: "CC0-1.0",
+                };
+                emitted++;
+            }
+        }
+    }
+}
+//# sourceMappingURL=wof-json-rows.js.map

package/out/adapters/wof-json-rows.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wof-json-rows.js","sourceRoot":"","sources":["../../lib/adapters/wof-json-rows.ts"],"names":[],"mappings":"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"}