@mailwoman/corpus 10.0.0 → 10.1.0

package/out/tools/golden/relabel-street/row.d.ts

@@ -3,61 +3,11 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Golden-set street-suffix relabel — v0.1.2 → v0.1.3.
- *
- *   ## Why this exists
- *
- *   The golden answer key and the training corpus disagreed about ONE thing, and the v9.0.0
- *   promotion eval read the disagreement as a model regression (`us.street` 87.4 vs a floor of
- *   87.8). The corpus SPLITS a US street into `street` + `street_suffix` — TIGER's adapter
- *   decomposes at `corpus/src/adapters/tiger/street-decompose.ts`, the `street-affix` slice recipe
- *   teaches it from USPS Pub-28, and `ComponentTag` carries `street_suffix` as a first-class tag.
- *   The golden set FOLDED it: 2,216 US rows carry a `street`, and exactly 2 of them label a
- *   `street_suffix`. Operator ruling, 2026-08-06: **the split is canonical**; the golden is the
- *   stale side. This tool moves the answer key onto the corpus convention.
- *
- *   ## The instrument
- *
- *   `matchTrailingSuffix` from `@mailwoman/codex/us` — the USPS Pub-28 Appendix C table, which is
- *   also what the corpus slice recipe splits on. The table is NOT re-implemented here, and the
- *   libpostal dictionary TIGER reads is deliberately not used: measured on this golden set the two
- *   disagree on 51 US rows, and the disagreements run in the codex table's favour (libpostal's
- *   `directionals.txt` lists `center|c`, so TIGER reads the `C` of "C STREET" as a directional
- *   prefix and then emits no suffix at all).
- *
- *   ## What it changes, and what it refuses to
- *
- *   Applied only to rows whose `country` is `US`. Three branches, mirroring the SHAPE of TIGER's
- *   `decomposeStreet` on codex tables:
- *
- *   - **street type** — the last whitespace-separated word is a Pub-28 suffix, and something is left
- *       over: "Main St" → `street: "Main"`, `street_suffix: "St"` (1,559 rows).
- *   - **street type + post-directional** — the last word is a directional AND the one before it is a
- *       Pub-28 suffix: "Pennsylvania Avenue NW" → `street: "Pennsylvania"`,
- *       `street_suffix: "Avenue NW"` (347 rows). The post-directional joins the suffix rather than
- *       becoming a tag of its own, because that is what the corpus adapter emits; there is no
- *       `street_postfix` tag to move it to.
- *   - **everything else is left folded** and reported. In particular a BARE post-directional tail
- *       ("Seymour East", "BROADWAY N" — 16 rows) is NOT split: a directional is not a Pub-28 suffix,
- *       and the observed rows in that class are unit-contaminated ("1ST AVE SW BOX E", where the
- *       trailing "E" is a box letter).
- *
- *   FR rows are untouched, deliberately and permanently as far as this tool is concerned. French
- *   street typology puts the type FIRST ("Rue de la Paix") and the golden labels only 7 of 665 FR
- *   street rows with a `street_prefix`; whether FR should split at all is a different question with
- *   a different table behind it, and nothing here should be read as having answered it.
- *
- *   ## Surface bytes
- *
- *   The split is a break at a whitespace run in the ORIGINAL string — no trimming, no case
- *   normalization, no re-joining of tokens. `street + gap + street_suffix` reconstructs the input
- *   byte-for-byte, so the whitespace between them belongs to neither span (the same shape the corpus
- *   adapter's spans have). The tool asserts this per row and refuses to write a file if it ever
- *   fails.
+ *   Splits the street span of US golden rows into `street_prefix`, `street` and `street_suffix` with the USPS Pub-28 table.
  */
 /**
- * A golden-set row, as stored one-per-line in `us.jsonl` / `fr.jsonl` / `adversarial.jsonl`. Only the fields this tool
- * reads are modeled; every other key rides through untouched.
+ * The golden row fields that the relabeler reads.
+ * Other fields are copied unchanged.
  */
 export interface GoldenStreetRow {
     raw: string;
@@ -68,34 +18,32 @@ export interface GoldenStreetRow {
     [key: string]: unknown;
 }
 /**
- * What the tool decided about one row. Every value except the two `split-*` classes means "left folded".
+ * The relabel outcome class for one row.
  */
 export type GoldenRelabelClass = "split-suffix" | "split-suffix-postdirectional" | "split-prefix-only" | "already-split" | "single-token" | "suffix-only-street" | "postdirectional-tail-only" | "no-suffix-match" | "no-street" | "not-us" | "untrimmed-street";
 /**
- * A review trigger on a row the tool DID change. A flag is never an adjudication — it marks the row for the operator's
- * deck, and the split is applied either way.
+ * A review note attached to a changed row.
+ * The relabel decision ignores it.
  */
 export interface GoldenRelabelFlag {
     kind: "name-prone-suffix" | "venue-context" | "remainder-is-affix";
     detail: string;
 }
 /**
- * Row-level relabel outcome.
+ * The relabel result for one row.
  */
 export interface GoldenRelabelResult {
     /**
-     * The row to write. Identical object reference when nothing changed.
+     * The row to write.
+     * This is the input object itself when no field changed.
      */
     row: GoldenStreetRow;
     changed: boolean;
     rowClass: GoldenRelabelClass;
     flags: GoldenRelabelFlag[];
-    /**
-     * A leading directional was lifted into `street_prefix` on this row.
-     */
     prefixSplit: boolean;
     /**
-     * The street span as it stood in the parent version — recorded for the review deck.
+     * The original street span of a changed row, for review.
      */
     beforeStreet?: string;
 }
@@ -104,18 +52,18 @@ export interface GoldenRelabelResult {
  */
 export interface RelabelStreetRowOptions {
     /**
-     * Also lift a folded LEADING directional out into `street_prefix`. Default true.
+     * Whether to also move a leading directional into `street_prefix`.
      *
-     * On by default because the fold applies both ways and the answer key has to be corrected on both, or the correction
-     * is not a correction: 207 of the 1,682 split dev rows (12.3%) still opened with a directional after the suffix move
-     * — "N Desmet Avenue" would have graded `street: "N Desmet"` against a model that says `street_prefix: "N", street:
-     * "Desmet"`. Turn it OFF only to measure what the prefix fold alone costs.
+     * Defaults to `true`; without it `N Desmet Avenue` grades as `street: "N Desmet"`
+     * against a model that emits a prefix.
      */
     splitPrefix?: boolean;
 }
 /**
- * Decide, and apply, the US street-span split for ONE golden row. Pure: never mutates its argument, and returns the
- * same object reference when the row is left alone.
+ * Splits the street span of one US golden row without mutating its argument,
+ * returning it when no field changes.
+ *
+ * @throws When the split spans do not rebuild the original street byte for byte.
  */
 export declare function relabelGoldenStreetRow(row: GoldenStreetRow, options?: RelabelStreetRowOptions): GoldenRelabelResult;
 //# sourceMappingURL=row.d.ts.map

package/out/tools/golden/relabel-street/row.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"row.d.ts","sourceRoot":"","sources":["../../../../lib/tools/golden/relabel-street/row.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwDG;AAYH;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAClC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAC3B,cAAc,GACd,8BAA8B,GAC9B,mBAAmB,GACnB,eAAe,GACf,cAAc,GACd,oBAAoB,GACpB,2BAA2B,GAC3B,iBAAiB,GACjB,WAAW,GACX,QAAQ,GACR,kBAAkB,CAAA;AAErB;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,mBAAmB,GAAG,eAAe,GAAG,oBAAoB,CAAA;IAClE,MAAM,EAAE,MAAM,CAAA;CACd;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC;;OAEG;IACH,GAAG,EAAE,eAAe,CAAA;IACpB,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,kBAAkB,CAAA;IAC5B,KAAK,EAAE,iBAAiB,EAAE,CAAA;IAC1B;;OAEG;IACH,WAAW,EAAE,OAAO,CAAA;IACpB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACrB;AAkFD;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;CACrB;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CACrC,GAAG,EAAE,eAAe,EACpB,OAAO,GAAE,uBAA4B,GACnC,mBAAmB,CAmIrB"}
+{"version":3,"file":"row.d.ts","sourceRoot":"","sources":["../../../../lib/tools/golden/relabel-street/row.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAWH;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC/B,GAAG,EAAE,MAAM,CAAA;IACX,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAClC,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACtB;AAED;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAC3B,cAAc,GACd,8BAA8B,GAC9B,mBAAmB,GACnB,eAAe,GACf,cAAc,GACd,oBAAoB,GACpB,2BAA2B,GAC3B,iBAAiB,GACjB,WAAW,GACX,QAAQ,GACR,kBAAkB,CAAA;AAErB;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IACjC,IAAI,EAAE,mBAAmB,GAAG,eAAe,GAAG,oBAAoB,CAAA;IAClE,MAAM,EAAE,MAAM,CAAA;CACd;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IACnC;;;OAGG;IACH,GAAG,EAAE,eAAe,CAAA;IACpB,OAAO,EAAE,OAAO,CAAA;IAChB,QAAQ,EAAE,kBAAkB,CAAA;IAC5B,KAAK,EAAE,iBAAiB,EAAE,CAAA;IAC1B,WAAW,EAAE,OAAO,CAAA;IACpB;;OAEG;IACH,YAAY,CAAC,EAAE,MAAM,CAAA;CACrB;AA+DD;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACvC;;;;;OAKG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;CACrB;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACrC,GAAG,EAAE,eAAe,EACpB,OAAO,GAAE,uBAA4B,GACnC,mBAAmB,CA6HrB"}

package/out/tools/golden/relabel-street/row.js

@@ -3,64 +3,13 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   Golden-set street-suffix relabel — v0.1.2 → v0.1.3.
- *
- *   ## Why this exists
- *
- *   The golden answer key and the training corpus disagreed about ONE thing, and the v9.0.0
- *   promotion eval read the disagreement as a model regression (`us.street` 87.4 vs a floor of
- *   87.8). The corpus SPLITS a US street into `street` + `street_suffix` — TIGER's adapter
- *   decomposes at `corpus/src/adapters/tiger/street-decompose.ts`, the `street-affix` slice recipe
- *   teaches it from USPS Pub-28, and `ComponentTag` carries `street_suffix` as a first-class tag.
- *   The golden set FOLDED it: 2,216 US rows carry a `street`, and exactly 2 of them label a
- *   `street_suffix`. Operator ruling, 2026-08-06: **the split is canonical**; the golden is the
- *   stale side. This tool moves the answer key onto the corpus convention.
- *
- *   ## The instrument
- *
- *   `matchTrailingSuffix` from `@mailwoman/codex/us` — the USPS Pub-28 Appendix C table, which is
- *   also what the corpus slice recipe splits on. The table is NOT re-implemented here, and the
- *   libpostal dictionary TIGER reads is deliberately not used: measured on this golden set the two
- *   disagree on 51 US rows, and the disagreements run in the codex table's favour (libpostal's
- *   `directionals.txt` lists `center|c`, so TIGER reads the `C` of "C STREET" as a directional
- *   prefix and then emits no suffix at all).
- *
- *   ## What it changes, and what it refuses to
- *
- *   Applied only to rows whose `country` is `US`. Three branches, mirroring the SHAPE of TIGER's
- *   `decomposeStreet` on codex tables:
- *
- *   - **street type** — the last whitespace-separated word is a Pub-28 suffix, and something is left
- *       over: "Main St" → `street: "Main"`, `street_suffix: "St"` (1,559 rows).
- *   - **street type + post-directional** — the last word is a directional AND the one before it is a
- *       Pub-28 suffix: "Pennsylvania Avenue NW" → `street: "Pennsylvania"`,
- *       `street_suffix: "Avenue NW"` (347 rows). The post-directional joins the suffix rather than
- *       becoming a tag of its own, because that is what the corpus adapter emits; there is no
- *       `street_postfix` tag to move it to.
- *   - **everything else is left folded** and reported. In particular a BARE post-directional tail
- *       ("Seymour East", "BROADWAY N" — 16 rows) is NOT split: a directional is not a Pub-28 suffix,
- *       and the observed rows in that class are unit-contaminated ("1ST AVE SW BOX E", where the
- *       trailing "E" is a box letter).
- *
- *   FR rows are untouched, deliberately and permanently as far as this tool is concerned. French
- *   street typology puts the type FIRST ("Rue de la Paix") and the golden labels only 7 of 665 FR
- *   street rows with a `street_prefix`; whether FR should split at all is a different question with
- *   a different table behind it, and nothing here should be read as having answered it.
- *
- *   ## Surface bytes
- *
- *   The split is a break at a whitespace run in the ORIGINAL string — no trimming, no case
- *   normalization, no re-joining of tokens. `street + gap + street_suffix` reconstructs the input
- *   byte-for-byte, so the whitespace between them belongs to neither span (the same shape the corpus
- *   adapter's spans have). The tool asserts this per row and refuses to write a file if it ever
- *   fails.
+ *   Splits the street span of US golden rows into `street_prefix`, `street` and `street_suffix` with the USPS Pub-28 table.
  */
 import { isStreetDirectionalToken, matchTrailingSuffix, NAME_PRONE_US_SUFFIXES, } from "@mailwoman/codex/us";
+import { stringifyJSON } from "@mailwoman/core/json";
 import { escapeRegExp } from "@mailwoman/core/strings/regexp";
 /**
- * Split `s` at its LAST whitespace run, returning the three pieces verbatim. Null when there is no interior whitespace,
- * when the head would be empty, or when `s` carries leading/trailing whitespace (a golden row is stored trimmed; an
- * untrimmed one is reported rather than silently normalized).
+ * Splits `s` at its last whitespace run, or returns `null` for an empty, untrimmed, or single-token string.
  */
 function splitLastWord(s) {
     if (s !== s.trim() || !s)
@@ -71,8 +20,7 @@ function splitLastWord(s) {
     return { head: match[1], gap: match[2], tail: match[3] };
 }
 /**
- * Split `s` at its FIRST whitespace run — the leading-directional counterpart of {@link splitLastWord}. `head` is the
- * first word, `tail` the rest, both verbatim.
+ * Splits `s` at its first whitespace run, with the same `null` cases as {@link splitLastWord}.
  */
 function splitFirstWord(s) {
     if (s !== s.trim() || !s)
@@ -82,10 +30,8 @@ function splitFirstWord(s) {
         return null;
     return { head: match[1], gap: match[2], tail: match[3] };
 }
-// ── Row-level relabel ──────────────────────────────────────────────────────
 /**
- * Rebuild `components` with `street_suffix` inserted immediately after `street`, so the written row reads in address
- * order rather than with the new tag appended at the end.
+ * Rebuilds `components` with the street spans in place of `street`, so the keys stay in address order.
  */
 function withStreetSpans(components, spans) {
     const out = {};
@@ -107,8 +53,10 @@ function withStreetSpans(components, spans) {
     return out;
 }
 /**
- * Decide, and apply, the US street-span split for ONE golden row. Pure: never mutates its argument, and returns the
- * same object reference when the row is left alone.
+ * Splits the street span of one US golden row without mutating its argument,
+ * returning it when no field changes.
+ *
+ * @throws When the split spans do not rebuild the original street byte for byte.
  */
 export function relabelGoldenStreetRow(row, options = {}) {
     const splitPrefix = options.splitPrefix ?? true;
@@ -139,8 +87,8 @@ export function relabelGoldenStreetRow(row, options = {}) {
         rowClass = matchTrailingSuffix(street) ? "suffix-only-street" : "single-token";
     }
     else if (isStreetDirectionalToken(split.tail)) {
-        // Street type + post-directional ("Pennsylvania Avenue NW"). The corpus adapter emits the pair as
-        // ONE suffix span, and there is no post-directional tag to move it to.
+        // A street type and a post-directional, as in "Pennsylvania Avenue NW",
+        // form one suffix span because no post-directional tag exists.
         const inner = splitLastWord(split.head);
         const typeMatch = inner ? matchTrailingSuffix(inner.tail) : null;
         if (!inner || !typeMatch) {
@@ -167,8 +115,6 @@ export function relabelGoldenStreetRow(row, options = {}) {
             canonical = typeMatch.canonical;
         }
     }
-    // Leading directional → street_prefix, on whatever name survived the suffix move. Independent of the
-    // suffix branch, because "N Main" is as folded as "N Main St" is.
     let prefix;
     let prefixGap = "";
     if (splitPrefix && !row.components.street_prefix) {
@@ -184,11 +130,9 @@ export function relabelGoldenStreetRow(row, options = {}) {
     if (!suffix) {
         rowClass = "split-prefix-only";
     }
-    // The invariant this tool exists to keep: the spans plus the whitespace between them ARE the original
-    // span, byte for byte. Anything else means a token was rewritten.
     const rebuilt = `${prefix ? prefix + prefixGap : ""}${name}${suffix ? suffixGap + suffix : ""}`;
     if (rebuilt !== street) {
-        throw new Error(`golden-relabel: span reconstruction failed for ${JSON.stringify(street)}`);
+        throw new Error(`golden-relabel: span reconstruction failed for ${stringifyJSON(street)}`);
     }
     if (canonical && NAME_PRONE_US_SUFFIXES.has(canonical)) {
         flags.push({
@@ -200,17 +144,15 @@ export function relabelGoldenStreetRow(row, options = {}) {
     if (suffix && venue && new RegExp(`(^|\\W)${escapeRegExp(suffix)}(\\W|$)`, "i").test(venue)) {
         flags.push({
             kind: "venue-context",
-            detail: `venue ${JSON.stringify(venue)} also carries ${JSON.stringify(suffix)}`,
+            detail: `venue ${stringifyJSON(venue)} also carries ${stringifyJSON(suffix)}`,
         });
     }
-    // Narrow on purpose: a name that happens to be a Pub-28 canonical is NOT interesting ("Mountain Rd",
-    // "Valley Dr", "Mills Ln" are ordinary streets, and flagging them buried the deck — 108 rows of noise
-    // on the first run). A name that is a bare DIRECTIONAL is: "East Rd" leaves `street: "East"`, which is
-    // a direction, not a name.
+    // Only a bare directional remainder is flagged, as in "East Rd"; a Pub-28 suffix
+    // word like "Valley Dr" is an ordinary street.
     if (isStreetDirectionalToken(name)) {
         flags.push({
             kind: "remainder-is-affix",
-            detail: `street would become the bare directional ${JSON.stringify(name)}`,
+            detail: `street would become the bare directional ${stringifyJSON(name)}`,
         });
     }
     return {

package/out/tools/golden/relabel-street/row.js.map

@@ -1 +1 @@
-{"version":3,"file":"row.js","sourceRoot":"","sources":["../../../../lib/tools/golden/relabel-street/row.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"row.js","sourceRoot":"","sources":["../../../../lib/tools/golden/relabel-street/row.ts"],"names":[],"mappings":"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"}

package/out/tools/golden/{relabel-street/index.d.ts → relabel-street.d.ts}

@@ -6,4 +6,4 @@
  */
 export * from "#tools/golden/relabel-street/directory";
 export * from "#tools/golden/relabel-street/row";
-//# sourceMappingURL=index.d.ts.map
+//# sourceMappingURL=relabel-street.d.ts.map

package/out/tools/golden/relabel-street.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relabel-street.d.ts","sourceRoot":"","sources":["../../../lib/tools/golden/relabel-street.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,wCAAwC,CAAA;AACtD,cAAc,kCAAkC,CAAA"}

package/out/tools/golden/{relabel-street/index.js → relabel-street.js}

@@ -6,4 +6,4 @@
  */
 export * from "#tools/golden/relabel-street/directory";
 export * from "#tools/golden/relabel-street/row";
-//# sourceMappingURL=index.js.map
+//# sourceMappingURL=relabel-street.js.map

package/out/tools/golden/relabel-street.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"relabel-street.js","sourceRoot":"","sources":["../../../lib/tools/golden/relabel-street.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,wCAAwC,CAAA;AACtD,cAAc,kCAAkC,CAAA"}

package/out/tools/ingest-csv.d.ts

@@ -3,12 +3,13 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   CSV → SQLite ingestion utility. Ported from isp-nexus's `sdk/data/csv.ts`.
+ * CSV → SQLite ingest tool.
  *
- *   Reads a CSV file, infers column types from a sample of rows, creates a SQLite table, and imports
- *   the data. Handles quoted fields, NULL normalization, and duplicate column name disambiguation.
+ * The tool reads a CSV and samples rows to infer column types.
+ * It creates a SQLite table and imports all rows.
+ * It handles quoted fields, null-like values and duplicate column names.
  *
- *   ## Usage
+ * ## Usage
  *
  *   ```sh
  *   mailwoman corpus ingest-csv \
@@ -17,15 +18,19 @@
  *   --output /data/corpus/sources/usgov-nppes/nppes.db
  * ```
  *
- *   Options: --input <path> CSV file to ingest (required) --table <name> SQLite table name (default:
- *   derived from input filename) --output <path> SQLite database path (default: input dir /
- *   table.db) --sample <n> Rows to sample for type inference (default: 100) --separator <char>
- *   Field separator (default: ,) --skip <n> Lines to skip before header (default: 0) --no-header
- *   CSV has no header row — columns will be col_0, col_1, etc. --dry-run Infer schema and print
- *   CREATE TABLE, but don't import
+ * Options:
+ * --input <path> Required CSV path
+ * --table <name> Table name (default: from filename)
+ * --output <path> DB path (default: input dir/<table>.db)
+ * --sample <n> Rows used for type inference (default: 100)
+ * --separator <char> Field delimiter (default: ,)
+ * --skip <n> Lines to skip before header (default: 0)
+ * --no-header Treat CSV as headerless (col_0, col_1, ...)
+ * --dry-run Print inferred schema, skip import
  */
 /**
- * Flag-shaped options for {@linkcode ingestCSV} — `table`/`output` derive from `input` when omitted.
+ * Options for {@linkcode ingestCSV}.
+ * `table` and `output` default from `input`.
  */
 export interface IngestCSVOptions {
     input: string;
@@ -38,10 +43,9 @@ export interface IngestCSVOptions {
     dryRun?: boolean;
 }
 /**
- * Ingest a CSV into SQLite: infer column types from a sample, create the table, import the rows. Throws when `input` is
- * missing. NOTE(phase1): progress narration still writes stderr directly — this predates the report-callback contract
- * and the write sites are deep in the type-inference helpers; thread a report param if a caller ever needs to capture
- * it.
+ * Ingest a CSV into SQLite: infer column types from a sample, create the table, import the rows.
+ *
+ * @throws When `input` does not exist.
  */
 export declare function ingestCSV(options: IngestCSVOptions): Promise<void>;
 //# sourceMappingURL=ingest-csv.d.ts.map

package/out/tools/ingest-csv.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ingest-csv.d.ts","sourceRoot":"","sources":["../../lib/tools/ingest-csv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAuTH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,MAAM,CAAC,EAAE,OAAO,CAAA;CAChB;AAED;;;;;GAKG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBxE"}
+{"version":3,"file":"ingest-csv.d.ts","sourceRoot":"","sources":["../../lib/tools/ingest-csv.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAgTH;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAChC,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,MAAM,CAAC,EAAE,OAAO,CAAA;CAChB;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAiBxE"}

package/out/tools/ingest-csv.js

@@ -3,12 +3,13 @@
  * @license AGPL-3.0
  * @author Teffen Ellis, et al.
  *
- *   CSV → SQLite ingestion utility. Ported from isp-nexus's `sdk/data/csv.ts`.
+ * CSV → SQLite ingest tool.
  *
- *   Reads a CSV file, infers column types from a sample of rows, creates a SQLite table, and imports
- *   the data. Handles quoted fields, NULL normalization, and duplicate column name disambiguation.
+ * The tool reads a CSV and samples rows to infer column types.
+ * It creates a SQLite table and imports all rows.
+ * It handles quoted fields, null-like values and duplicate column names.
  *
- *   ## Usage
+ * ## Usage
  *
  *   ```sh
  *   mailwoman corpus ingest-csv \
@@ -17,21 +18,25 @@
  *   --output /data/corpus/sources/usgov-nppes/nppes.db
  * ```
  *
- *   Options: --input <path> CSV file to ingest (required) --table <name> SQLite table name (default:
- *   derived from input filename) --output <path> SQLite database path (default: input dir /
- *   table.db) --sample <n> Rows to sample for type inference (default: 100) --separator <char>
- *   Field separator (default: ,) --skip <n> Lines to skip before header (default: 0) --no-header
- *   CSV has no header row — columns will be col_0, col_1, etc. --dry-run Infer schema and print
- *   CREATE TABLE, but don't import
+ * Options:
+ * --input <path> Required CSV path
+ * --table <name> Table name (default: from filename)
+ * --output <path> DB path (default: input dir/<table>.db)
+ * --sample <n> Rows used for type inference (default: 100)
+ * --separator <char> Field delimiter (default: ,)
+ * --skip <n> Lines to skip before header (default: 0)
+ * --no-header Treat CSV as headerless (col_0, col_1, ...)
+ * --dry-run Print inferred schema, skip import
  */
 import { ByteFormatter } from "@mailwoman/core/fs/formatters";
 import { tryStat, pathExists } from "@mailwoman/core/fs/readers";
 import { makeDirectories, writeLocalJSONFile } from "@mailwoman/core/fs/writers";
-import { basename, dirname, extname, join } from "path-ts";
+import { basename, dirname, extname, PathBuilder } from "path-ts";
 import { CSVSpliterator } from "spliterator";
-//#region Column name normalization
+// #region Column name normalization
 /**
- * @deprecated belongs in core, if really needed. spliterator should handle this.
+ * @deprecated This helper may belong in core.
+ * Keep it here until then.
  */
 function normalizeColumnName(raw) {
     return (raw
@@ -85,17 +90,14 @@ function inferColumnType(samples) {
     return { name: "", type, nullable: nullCount / total >= 0.5 };
 }
 async function runIngest(opts) {
-    // `header: false` with `drop` is what expresses `--skip N`: the spliterator's own header handling consumes the
-    // FIRST row as the header, and `drop` counts from the row after it, so a preamble before the header has to be
-    // dropped here and the header row taken by hand. Quote handling is end-to-end (quoted delimiters, doubled quotes);
-    // `skipEmpty` drops blank lines that readline would have turned into all-null rows. The early `break` closes the
-    // file descriptor.
+    // Keep parser header handling off so `--skip` works predictably.
+    // We read the header row ourselves.
     const rows = () => CSVSpliterator.fromAsync(opts.inputPath, {
         header: false,
         columnDelimiter: opts.separator,
         drop: opts.skipLines,
     });
-    // Read the header and sample rows before inferring the SQLite schema.
+    // Read header + sample rows to infer schema.
     process.stderr.write(`Reading ${opts.inputPath} for schema inference...\n`);
     let headerRow = null;
     const sampleRows = [];
@@ -114,18 +116,18 @@ async function runIngest(opts) {
     if (!headerRow && opts.hasHeader) {
         throw new Error("No header line found in CSV");
     }
-    // Normalize and deduplicate the input column names.
+    // Normalize and dedupe column names.
     let rawHeaders;
     if (opts.hasHeader && headerRow) {
         rawHeaders = headerRow;
     }
     else {
-        // Auto-generate column names: col_0, col_1, ...
+        // No header: generate col_0, col_1, ...
         const numCols = sampleRows[0]?.length ?? 0;
         rawHeaders = Array.from({ length: numCols }, (_, i) => `col_${i}`);
     }
     const colNames = dedupColumns(rawHeaders.map(normalizeColumnName));
-    // Infer each column's SQLite type from its sample values.
+    // Infer each column type from samples.
     const columns = colNames.map((name, i) => {
         const samples = sampleRows.map((row) => {
             const raw = row[i] ?? "";
@@ -135,10 +137,9 @@ async function runIngest(opts) {
         info.name = name;
         return info;
     });
-    // Generate the table definition and insert statement from the inferred schema.
+    // Build CREATE TABLE and INSERT SQL.
     const colDefs = columns.map((c) => `"${c.name}" ${c.type}`).join(",\n  ");
-    // Raw DDL by design: the column set + types are INFERRED from the CSV at runtime (colDefs above),
-    // so a Kysely builder loop would just wrap the same dynamic strings with ceremony and no type safety.
+    // Raw SQL is intentional: columns and types are dynamic at runtime.
     const createTableSQL = `CREATE TABLE IF NOT EXISTS "${opts.tableName}" (\n  ${colDefs}\n);`;
     const tempCols = columns.map((c) => `"${c.name}"`).join(", ");
     process.stderr.write(`\nSchema inferred from ${sampleRows.length} sample rows:\n`);
@@ -147,25 +148,21 @@ async function runIngest(opts) {
         process.stderr.write("--dry-run: stopping before import\n");
         return;
     }
-    // Create the database, then import every input row.
+    // Create database and import rows.
     const { DatabaseClient } = await import("@mailwoman/sqlite/client");
     await makeDirectories(dirname(opts.outputPath));
-    // `Database` — the EMPTY schema — deliberately, not by default: `createTableSQL` is built from the columns and
-    // types inferred from the CSV at runtime, so there is no table this file could name at compile time. Every write
-    // below goes through `exec`/`prepare` for the same reason.
+    // Empty schema type is intentional: table shape is runtime-generated.
     using db = new DatabaseClient(opts.outputPath);
     db.exec("PRAGMA journal_mode = OFF"); // faster for bulk import
     db.exec("PRAGMA synchronous = OFF");
     db.exec(createTableSQL);
-    // Use the .import approach via a temp table, then INSERT INTO ... SELECT to handle
-    // NULL normalization and type coercion.
-    // better-sqlite3 doesn't support .import natively, so we use a different approach:
-    // Read the CSV line-by-line and INSERT in a transaction.
+    // Insert line-by-line in batches (no native .import here).
     process.stderr.write(`Importing rows...\n`);
     const insertStmt = db.prepare(`INSERT INTO "${opts.tableName}" (${tempCols}) VALUES (${columns.map(() => "?").join(", ")})`);
     let imported = 0;
     let headerSkipped = false;
-    // node:sqlite has no `db.transaction(fn)` wrapper; use raw BEGIN/COMMIT around the batch.
+    // node:sqlite has no transaction helper.
+    // The code uses BEGIN/COMMIT.
     const doInsert = () => {
         db.exec("BEGIN");
         try {
@@ -197,7 +194,7 @@ async function runIngest(opts) {
                 return Number.parseFloat(v);
             return v;
         });
-        // Pad or truncate to column count
+        // Pad or trim to expected column count.
         while (values.length < columns.length) {
             values.push(null);
         }
@@ -212,13 +209,13 @@ async function runIngest(opts) {
             }
         }
     }
-    // Flush remaining
+    // Flush remaining rows.
     if (batch.length) {
         doInsert();
         imported += batch.length;
     }
     process.stderr.write(`  Imported ${imported.toLocaleString()} rows into "${opts.tableName}"\n`);
-    // Build a basic index on the first TEXT column (likely the primary key)
+    // Create a simple index on the first text column.
     const firstTextCol = columns.find((c) => c.type === "TEXT");
     if (firstTextCol) {
         process.stderr.write(`Building index on "${firstTextCol.name}"...\n`);
@@ -238,10 +235,9 @@ async function runIngest(opts) {
     process.stderr.write(`Done. ${imported.toLocaleString()} rows → ${opts.outputPath} (${ByteFormatter.formatIEC(stat.size)})\n`);
 }
 /**
- * Ingest a CSV into SQLite: infer column types from a sample, create the table, import the rows. Throws when `input` is
- * missing. NOTE(phase1): progress narration still writes stderr directly — this predates the report-callback contract
- * and the write sites are deep in the type-inference helpers; thread a report param if a caller ever needs to capture
- * it.
+ * Ingest a CSV into SQLite: infer column types from a sample, create the table, import the rows.
+ *
+ * @throws When `input` does not exist.
  */
 export async function ingestCSV(options) {
     if (!(await pathExists(options.input))) {
@@ -251,7 +247,7 @@ export async function ingestCSV(options) {
     await runIngest({
         inputPath: options.input,
         tableName: options.table ?? csvName.replaceAll(/[^a-zA-Z0-9_]/g, "_"),
-        outputPath: options.output ?? join(dirname(options.input), csvName + ".db"),
+        outputPath: options.output ?? PathBuilder.from(options.input).dirname()(`${csvName}.db`).toString(),
         sampleSize: options.sample ?? 100,
         separator: options.separator ?? ",",
         skipLines: options.skip ?? 0,
@@ -259,5 +255,5 @@ export async function ingestCSV(options) {
         dryRun: options.dryRun ?? false,
     });
 }
-//#endregion
+// #endregion
 //# sourceMappingURL=ingest-csv.js.map