@mailwoman/resolver-wof-sqlite 2.1.0

package/out/build-coincident-roles-cli.js

@@ -0,0 +1,94 @@
+#!/usr/bin/env node
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman-wof-build-coincident-roles <path-to-admin.db>... [--drop]`
+ *
+ *   Operator-side one-shot CLI (#403, epic #402): derives the `coincident_roles` relation into an
+ *   existing admin gazetteer — the dual-role places (city-states, capital-seat provinces,
+ *   consolidated city-counties) the hierarchy-completion step (#405) consults. Additive +
+ *   idempotent; re-run after refreshing `spr`/`ancestors`. Mirrors `build-fts-cli.ts`. Should also
+ *   be invoked as a post-step of the main `scripts/build-unified-wof.ts`.
+ */
+import { existsSync } from "node:fs";
+import { exit, stderr } from "node:process";
+import { DatabaseSync } from "node:sqlite";
+import { buildCoincidentRoles } from "./coincident-roles.js";
+function printUsageAndExit(code) {
+    stderr.write([
+        "usage: mailwoman-wof-build-coincident-roles <path-to-admin.db>... [--drop]",
+        "",
+        "Derives the coincident_roles relation (dual-role places — city-states, capital-seat",
+        "provinces, consolidated city-counties) into one or more admin gazetteers. The",
+        "hierarchy-completion resolver step (#405) consults it. Additive + idempotent.",
+        "",
+        "  --drop   Drop and rebuild coincident_roles if it already exists (default: rebuild).",
+        "",
+        "Example:",
+        "  mailwoman-wof-build-coincident-roles /data/wof/admin-global-priority.db",
+        "",
+    ].join("\n"));
+    exit(code);
+}
+function buildOne(path, drop) {
+    if (!existsSync(path)) {
+        stderr.write(`mailwoman-wof-build-coincident-roles: file not found: ${path}\n`);
+        return 1;
+    }
+    stderr.write(`Opening ${path}…\n`);
+    const db = new DatabaseSync(path);
+    try {
+        const result = buildCoincidentRoles(db, {
+            drop,
+            onProgress: (phase, detail) => stderr.write(`  [${phase}]${detail ? ` — ${detail}` : ""}\n`),
+        });
+        const top = Object.entries(result.byCountry)
+            .sort((a, b) => b[1] - a[1])
+            .map(([cc, n]) => `${cc} ${n}`)
+            .join(", ");
+        stderr.write(`Built: ${result.rowCount} coincident-role rows (${(result.durationMs / 1000).toFixed(2)}s)\n  by country: ${top}\n`);
+        return 0;
+    }
+    catch (err) {
+        stderr.write(`mailwoman-wof-build-coincident-roles: ${err instanceof Error ? err.message : String(err)}\n`);
+        return 1;
+    }
+    finally {
+        db.close();
+    }
+}
+export function main(argv) {
+    const paths = [];
+    // The relation is a cheap (~2 s) derived table that must reflect the current spr/ancestors, so it
+    // rebuilds by default (idempotent). `--no-drop` appends instead — only useful for incremental tests.
+    let drop = true;
+    for (const a of argv) {
+        if (a === "--drop")
+            drop = true;
+        else if (a === "--no-drop")
+            drop = false;
+        else if (a === "--help" || a === "-h")
+            printUsageAndExit(0);
+        else if (a.startsWith("-")) {
+            stderr.write(`mailwoman-wof-build-coincident-roles: unknown flag ${JSON.stringify(a)}\n`);
+            printUsageAndExit(2);
+        }
+        else
+            paths.push(a);
+    }
+    if (paths.length === 0)
+        printUsageAndExit(2);
+    let worst = 0;
+    for (const path of paths) {
+        const rc = buildOne(path, drop);
+        if (rc > worst)
+            worst = rc;
+    }
+    return worst;
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+    exit(main(process.argv.slice(2)));
+}
+//# sourceMappingURL=build-coincident-roles-cli.js.map

package/out/build-coincident-roles-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-coincident-roles-cli.js","sourceRoot":"","sources":["../build-coincident-roles-cli.ts"],"names":[],"mappings":"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"}

package/out/build-fts-cli.d.ts

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman-wof-build-fts <path-to-wof.db>... [--drop]`
+ *
+ *   Operator-side one-shot CLI: takes one or more Who's On First SQLite distributions and adds the
+ *   `place_search` FTS5 + `place_bbox` R*Tree virtual tables needed by `WofSqlitePlaceLookup`. Run
+ *   this once per downloaded WOF shard so production callers can skip the (~minutes-long) lazy
+ *   build.
+ *
+ *   Multiple positional args process each DB in sequence — useful when you've just pulled the admin +
+ *   postcode shards in one go.
+ *
+ *   Why a plain-args CLI rather than Ink / Pastel: this is a one-shot operator script, not an
+ *   interactive TUI. The dep weight of inkjs / pastel would dominate the script's footprint and
+ *   doesn't match how operators expect to drive a build step (`script /path/to/db` + stderr
+ *   progress). Matches the spirit of `corpus/scripts/*.ts`.
+ */
+export declare function main(argv: readonly string[]): number;
+//# sourceMappingURL=build-fts-cli.d.ts.map

package/out/build-fts-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-fts-cli.d.ts","sourceRoot":"","sources":["../build-fts-cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;GAmBG;AA0FH,wBAAgB,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CASpD"}

package/out/build-fts-cli.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman-wof-build-fts <path-to-wof.db>... [--drop]`
+ *
+ *   Operator-side one-shot CLI: takes one or more Who's On First SQLite distributions and adds the
+ *   `place_search` FTS5 + `place_bbox` R*Tree virtual tables needed by `WofSqlitePlaceLookup`. Run
+ *   this once per downloaded WOF shard so production callers can skip the (~minutes-long) lazy
+ *   build.
+ *
+ *   Multiple positional args process each DB in sequence — useful when you've just pulled the admin +
+ *   postcode shards in one go.
+ *
+ *   Why a plain-args CLI rather than Ink / Pastel: this is a one-shot operator script, not an
+ *   interactive TUI. The dep weight of inkjs / pastel would dominate the script's footprint and
+ *   doesn't match how operators expect to drive a build step (`script /path/to/db` + stderr
+ *   progress). Matches the spirit of `corpus/scripts/*.ts`.
+ */
+import { existsSync } from "node:fs";
+import { exit, stderr } from "node:process";
+import { DatabaseSync } from "node:sqlite";
+import { buildPlaceSearchFts } from "./fts.js";
+function printUsageAndExit(code) {
+    stderr.write([
+        "usage: mailwoman-wof-build-fts <path-to-wof.db>... [--drop]",
+        "",
+        "Builds the place_search FTS5 + place_bbox R*Tree virtual tables in one or more",
+        "Who's On First SQLite distributions. Run this once per downloaded WOF shard so",
+        "production WofSqlitePlaceLookup instances skip the lazy-build cost at first open.",
+        "",
+        "  --drop   Drop and rebuild place_search + place_bbox if they already exist.",
+        "           Apply after refreshing the spr / names tables from a newer dump.",
+        "",
+        "Examples:",
+        "  mailwoman-wof-build-fts /data/wof/admin-us.db",
+        "  mailwoman-wof-build-fts /data/wof/admin-us.db /data/wof/postalcode-us.db",
+        "  mailwoman-wof-build-fts /data/wof/admin-us.db --drop",
+        "",
+        "See https://github.com/sister-software/mailwoman/tree/main/resolver-wof-sqlite for",
+        "the recommended WOF distribution sources + attribution requirements.",
+        "",
+    ].join("\n"));
+    exit(code);
+}
+function parseArgs(argv) {
+    const args = [];
+    let drop = false;
+    for (const a of argv) {
+        if (a === "--drop")
+            drop = true;
+        else if (a === "--help" || a === "-h")
+            printUsageAndExit(0);
+        else if (a.startsWith("-")) {
+            stderr.write(`mailwoman-wof-build-fts: unknown flag ${JSON.stringify(a)}\n`);
+            printUsageAndExit(2);
+        }
+        else
+            args.push(a);
+    }
+    if (args.length === 0) {
+        stderr.write(`mailwoman-wof-build-fts: expected at least one positional arg\n`);
+        printUsageAndExit(2);
+    }
+    return { databasePaths: args, drop };
+}
+/**
+ * Build indexes on a single DB. Returns 0 on success, 1 on failure. Errors are written to stderr
+ * but the call doesn't throw — `main()` aggregates the exit code across multi-DB invocations.
+ */
+function buildOne(path, drop) {
+    if (!existsSync(path)) {
+        stderr.write(`mailwoman-wof-build-fts: file not found: ${path}\n`);
+        return 1;
+    }
+    stderr.write(`Opening ${path}…\n`);
+    const db = new DatabaseSync(path);
+    try {
+        const result = buildPlaceSearchFts(db, {
+            drop,
+            onProgress: (phase, detail) => {
+                const suffix = detail ? ` — ${detail}` : "";
+                stderr.write(`  [${phase}]${suffix}\n`);
+            },
+        });
+        const verb = result.created ? "Built" : "Already present";
+        stderr.write(`${verb}: place_search has ${result.indexedRows.toLocaleString()} rows ` +
+            `(${(result.durationMs / 1000).toFixed(2)}s)\n`);
+        return 0;
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        stderr.write(`mailwoman-wof-build-fts: ${message}\n`);
+        return 1;
+    }
+    finally {
+        db.close();
+    }
+}
+export function main(argv) {
+    const args = parseArgs(argv);
+    // Process every DB; if any fail, the worst exit code wins (so CI / scripts see failure).
+    let worst = 0;
+    for (const path of args.databasePaths) {
+        const rc = buildOne(path, args.drop);
+        if (rc > worst)
+            worst = rc;
+    }
+    return worst;
+}
+// Entry point — only run when invoked directly, not when imported by tests.
+if (import.meta.url === `file://${process.argv[1]}`) {
+    exit(main(process.argv.slice(2)));
+}
+//# sourceMappingURL=build-fts-cli.js.map

package/out/build-fts-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-fts-cli.js","sourceRoot":"","sources":["../build-fts-cli.ts"],"names":[],"mappings":"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"}

package/out/build-slim-cli.d.ts

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman-wof-build-slim --in <wof.db>... --out <slim.db> [--top 1000] [--countries US]`
+ *
+ *   Operator-side one-shot CLI that produces a "slim" WOF SQLite distribution sized for the
+ *   browser-side mailwoman demo (Path B). Delegates to {@linkcode buildSlimWofDatabase}; the CLI is
+ *   just argument parsing + stderr progress.
+ */
+export declare function main(rawArgv: string[]): Promise<number>;
+//# sourceMappingURL=build-slim-cli.d.ts.map

package/out/build-slim-cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-slim-cli.d.ts","sourceRoot":"","sources":["../build-slim-cli.ts"],"names":[],"mappings":";AACA;;;;;;;;;;GAUG;AAmFH,wBAAsB,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,CAmC7D"}

package/out/build-slim-cli.js

@@ -0,0 +1,130 @@
+#!/usr/bin/env node
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   `mailwoman-wof-build-slim --in <wof.db>... --out <slim.db> [--top 1000] [--countries US]`
+ *
+ *   Operator-side one-shot CLI that produces a "slim" WOF SQLite distribution sized for the
+ *   browser-side mailwoman demo (Path B). Delegates to {@linkcode buildSlimWofDatabase}; the CLI is
+ *   just argument parsing + stderr progress.
+ */
+import { exit, stderr } from "node:process";
+import { buildSlimWofDatabase } from "./build-slim.js";
+function printUsageAndExit(code) {
+    stderr.write([
+        "usage: mailwoman-wof-build-slim --in <wof.db>... --out <slim.db> [--top N] [--countries US,CA,...] [--drop-names]",
+        "",
+        "Builds a trimmed WOF SQLite distribution for the browser-side demo. Default selection:",
+        "  - All ancestor placetypes (country/region/county/borough/macroregion) in scope",
+        "  - Top --top localities by population (from the source place_population table, default 1000)",
+        "  - All postalcodes in scope",
+        "  - All names + place_population rows for selected IDs (+ coincident_roles, filtered)",
+        "  - Fresh place_search FTS5 + place_bbox R*Tree (rebuilt from spr + names)",
+        "",
+        "--drop-names drops the names table after the FTS build (self-contained FTS5; ~2/3 size win,",
+        "the resolver never reads names at runtime — see #359). Empty --in values are skipped (pass",
+        '"" for a shard that isn\'t built yet).',
+        "",
+        "Examples:",
+        "  mailwoman-wof-build-slim --in admin-us.db --in postalcode-us.db --out wof-hot.db",
+        "  mailwoman-wof-build-slim --in admin-us.db --out wof-tiny.db --top 100",
+        "  mailwoman-wof-build-slim --in admin-na.db --out wof-na.db --countries US,CA,MX",
+        "",
+    ].join("\n"));
+    exit(code);
+}
+function parseArgs(argv) {
+    const out = { inputs: [], output: "", topLocalities: 1000, countries: ["US"], dropNames: false };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === "--in") {
+            // Consume the value even when empty — callers pass `--in ""` for a shard (e.g. a custom
+            // postcode DB) that isn't built yet. Push only non-empty paths; build-slim skips the rest.
+            const v = argv[++i];
+            if (v === undefined)
+                printUsageAndExit(2);
+            if (v)
+                out.inputs.push(v);
+        }
+        else if (a === "--out") {
+            const v = argv[++i];
+            if (!v)
+                printUsageAndExit(2);
+            out.output = v;
+        }
+        else if (a === "--top") {
+            const v = argv[++i];
+            if (!v)
+                printUsageAndExit(2);
+            const n = Number(v);
+            if (!Number.isFinite(n) || n <= 0) {
+                stderr.write(`--top must be a positive number; got '${v}'\n`);
+                exit(2);
+            }
+            out.topLocalities = n;
+        }
+        else if (a === "--countries") {
+            const v = argv[++i];
+            if (!v)
+                printUsageAndExit(2);
+            out.countries = v
+                .split(",")
+                .map((c) => c.trim())
+                .filter(Boolean);
+        }
+        else if (a === "--drop-names") {
+            out.dropNames = true;
+        }
+        else if (a === "--help" || a === "-h") {
+            printUsageAndExit(0);
+        }
+        else {
+            stderr.write(`unknown argument: '${a}'\n`);
+            printUsageAndExit(2);
+        }
+    }
+    if (out.inputs.length === 0 || !out.output)
+        printUsageAndExit(2);
+    return out;
+}
+export async function main(rawArgv) {
+    let args;
+    try {
+        args = parseArgs(rawArgv);
+    }
+    catch {
+        return 2;
+    }
+    const opts = {
+        inputs: args.inputs,
+        output: args.output,
+        countries: args.countries,
+        topLocalitiesPerCountry: args.topLocalities,
+        dropNames: args.dropNames,
+        onProgress: (phase, detail) => {
+            stderr.write(`[${phase}] ${detail}\n`);
+        },
+    };
+    try {
+        const result = await buildSlimWofDatabase(opts);
+        const mb = (result.outputBytes / 1024 / 1024).toFixed(1);
+        stderr.write(`\nBuilt ${result.outputPath} (${mb} MB)\n` +
+            `  spr=${result.rowCounts.spr}` +
+            `  names=${result.rowCounts.names}${args.dropNames ? " (dropped)" : ""}` +
+            `  fts=${result.rowCounts.placeSearch}` +
+            `  bbox=${result.rowCounts.placeBbox}` +
+            `  pop=${result.rowCounts.placePopulation}\n`);
+        return 0;
+    }
+    catch (err) {
+        stderr.write(`build-slim failed: ${err.message}\n`);
+        return 1;
+    }
+}
+// Run when invoked as a script (not when imported by tests).
+if (import.meta.url === `file://${process.argv[1]}`) {
+    main(process.argv.slice(2)).then((code) => exit(code));
+}
+//# sourceMappingURL=build-slim-cli.js.map

package/out/build-slim-cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-slim-cli.js","sourceRoot":"","sources":["../build-slim-cli.ts"],"names":[],"mappings":"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"}

package/out/build-slim.d.ts

@@ -0,0 +1,71 @@
+/**
+ * @copyright Sister Software
+ * @license AGPL-3.0
+ * @author Teffen Ellis, et al.
+ *
+ *   Build a "slim" Who's On First SQLite distribution that's small enough to ship as a static asset
+ *   for the browser-side mailwoman demo (Path B of the demo plan). The full admin distribution is
+ *   ~2 GB; the slim variant aims for the ~50–100 MB range by keeping only the places a public demo
+ *   will actually query for.
+ *
+ *   Selection policy (v1, US-focused):
+ *
+ *   - All countries / regions / counties / boroughs in the configured `countries` set, so the ancestor
+ *       chain a locality / postcode reports through `parent_id` stays intact.
+ *   - Top-K localities by population (read from the source's pre-built `place_population` aux table) in
+ *       those countries.
+ *   - All postcodes in those countries — they're small and addressing-relevant.
+ *   - All `names` + `place_population` rows for selected place IDs.
+ *   - The `coincident_roles` dual-role relation (#402), filtered to surviving spr ids.
+ *
+ *   No geojson, by design. The upstream WOF GeoJSON bodies live ONLY in the raw `whosonfirst-data-*`
+ *   repos; `scripts/build-unified-wof.ts` extracts `wof:population` straight into
+ *   `place_population` (and the bbox into `spr`) at ingest and never persists a `geojson` table. So
+ *   the source admin DB carries population in `place_population`, and this builder consumes it
+ *   directly — there is nothing to extract from, and nothing to drop.
+ *
+ *   The output DB has the resolver-facing schema: `spr`, `names`, `place_population`, plus the
+ *   `place_search` FTS5 / `place_bbox` R*Tree virtual tables rebuilt against the trimmed row set
+ *   (both derive purely from `spr` + `names` — see `fts.ts`). That means `WofSqlitePlaceLookup`
+ *   opens the slim DB without any code change — it sees a smaller universe, nothing more.
+ *
+ *   Multi-shard inputs (e.g. admin + postcode) are processed in sequence; selected rows accumulate
+ *   into the single output DB. The postcode shard contributes only postcodes; admin contributes
+ *   everything else. Empty / missing input paths are skipped (callers pass `""` when a shard, such
+ *   as a custom postcode DB, isn't built yet).
+ */
+export interface BuildSlimOptions {
+    /** Input WOF SQLite distributions. Each should already have spr / names / place_population tables. */
+    inputs: string[];
+    /** Output path for the slim DB. Will be overwritten if it exists. */
+    output: string;
+    /** Country codes to keep (ISO 2-letter). Defaults to `["US"]`. */
+    countries?: string[];
+    /** Cap on the number of localities to keep per country, by descending population. */
+    topLocalitiesPerCountry?: number;
+    /**
+     * Drop the `names` table after the FTS index is built (default false). `place_search` is a
+     * self-contained FTS5 (no external `content=`), so once it's built `names` is only the build-time
+     * source — the resolver queries `place_search` + `spr` + `place_population` + `coincident_roles`
+     * and never reads `names` at runtime. Dropping it is the single biggest size win (~2/3 of the
+     * file for a multi-locale build; see #359). A future consumer that needs raw alt-names at runtime
+     * should ship a SEPARATE shard rather than re-bloat the hot DB.
+     */
+    dropNames?: boolean;
+    /** Optional progress callback for CLI / test introspection. */
+    onProgress?: (phase: SlimBuildPhase, detail: string) => void;
+}
+export type SlimBuildPhase = "init" | "schema" | "country" | "region" | "county" | "locality" | "postcode" | "names" | "place_population" | "coincident_roles" | "place_abbr" | "fts" | "vacuum" | "done";
+export interface BuildSlimResult {
+    outputPath: string;
+    outputBytes: number;
+    rowCounts: {
+        spr: number;
+        names: number;
+        placeSearch: number;
+        placeBbox: number;
+        placePopulation: number;
+    };
+}
+export declare function buildSlimWofDatabase(opts: BuildSlimOptions): Promise<BuildSlimResult>;
+//# sourceMappingURL=build-slim.d.ts.map

package/out/build-slim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-slim.d.ts","sourceRoot":"","sources":["../build-slim.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAYH,MAAM,WAAW,gBAAgB;IAChC,sGAAsG;IACtG,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB,qEAAqE;IACrE,MAAM,EAAE,MAAM,CAAA;IACd,kEAAkE;IAClE,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB,qFAAqF;IACrF,uBAAuB,CAAC,EAAE,MAAM,CAAA;IAChC;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,CAAC,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,MAAM,KAAK,IAAI,CAAA;CAC5D;AAED,MAAM,MAAM,cAAc,GACvB,MAAM,GACN,QAAQ,GACR,SAAS,GACT,QAAQ,GACR,QAAQ,GACR,UAAU,GACV,UAAU,GACV,OAAO,GACP,kBAAkB,GAClB,kBAAkB,GAClB,YAAY,GACZ,KAAK,GACL,QAAQ,GACR,MAAM,CAAA;AAET,MAAM,WAAW,eAAe;IAC/B,UAAU,EAAE,MAAM,CAAA;IAClB,WAAW,EAAE,MAAM,CAAA;IACnB,SAAS,EAAE;QACV,GAAG,EAAE,MAAM,CAAA;QACX,KAAK,EAAE,MAAM,CAAA;QACb,WAAW,EAAE,MAAM,CAAA;QACnB,SAAS,EAAE,MAAM,CAAA;QACjB,eAAe,EAAE,MAAM,CAAA;KACvB,CAAA;CACD;AAgCD,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,eAAe,CAAC,CAiH3F"}