@finbheara/names 0.16.0 → 0.17.0

package/dist/chunks/index-qmn87bdh.js.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["../src/normalize/given-diminutives.ts", "../src/normalize/given-families.ts"],
+  "sourcesContent": [
+    "/**\n * given-diminutives.ts — ONE GIVEN-NAME DIMINUTIVE TABLE, read by the TypeScript side.\n *\n * `./given-diminutives.json` is the table and this file is its reader. A consumer in another\n * language reads the table as `names tables given-name` prints it (`../cli/tables.ts`), never\n * this file, so the file's layout may change and no second copy exists. An earlier\n * adjudicator carried a `FAMILIAR` map of eight entries and said *\"the name primitives are\n * where it belongs once a second consumer wants one\"*; the teachers-directory gate is that\n * second consumer, and the eight entries are in the table.\n *\n * A RELATION OF A PAIR AND NEVER A KEY. Nothing here rewrites a given name: a stored key,\n * a filing key and every rendering keep the print's own spelling. A caller asks whether\n * TWO given names are one family, at the moment it compares them, and nowhere else, so the\n * root never leaves this module: `sameGivenFamily` and `givenFamilyTable` answer about a\n * pair and neither returns a root, for that reason.\n *\n * SPELLINGS, FAMILIES AND THE GATE. Two different given names are related in one of three\n * ways, and the answer says which:\n *\n *   - `given-variant`: two spellings of one name (`Connor` / `Conor`, `Sara` / `Sarah`). A\n *     spelling is not a familiar form, so `variants` is its own table, and a gate admits it.\n *   - `given-family`: after each spelling is read as its canonical, the two share a ROOT of\n *     `families` (`Tom` / `Thomas`, `Kate` / `Katherine`), and a gate admits it.\n *   - `given-family-not-gate`: they share a root, but only through a `notAtGate` form: a name in\n *     its own right (`Megan`, `Grace`), a translation (`Sean`, `Padraig`), another gender's\n *     name (`Michelle`, `Sam`) or a form of more than one root (`Ellie`, `Evie`). The lane\n *     reads it as evidence below an exact match; a gate refuses it.\n *\n * EVERY ROOT, NEVER THE FIRST. A form under several roots meets each of them (`Evie` is\n * Evelyn's, Genevieve's, Eve's and Eva's), and every such form is `notAtGate`, because the\n * form alone cannot say which root its bearer carries. Sharing a root is not transitive:\n * `Eve` and `Eva` share none, though `Evie` meets both. A `notAtGate` form is refused AS A\n * FORM: where it is the root itself (`Caitlin` / `Cait`), its own forms meet it at a gate.\n */\n\nimport table from \"./given-diminutives.json\";\n\ninterface Table {\n\tvariants: Record<string, readonly string[]>;\n\tfamilies: Record<string, readonly string[]>;\n\tnotAtGate: readonly string[];\n}\n\nconst TABLE = table as unknown as Table;\n\n/**\n * The table as this module reads it, for `names tables given-name`, which prints it. Not a\n * package export: the printed form is the contract, and this file's layout may change.\n */\nexport function givenDiminutiveTable(): {\n\treadonly variants: Readonly<Record<string, readonly string[]>>;\n\treadonly families: Readonly<Record<string, readonly string[]>>;\n\treadonly notAtGate: readonly string[];\n} {\n\treturn TABLE;\n}\n\n/** spelling -> its canonical spelling; a canonical maps to itself only by absence. */\nconst CANONICAL: ReadonlyMap<string, string> = (() => {\n\tconst out = new Map<string, string>();\n\tfor (const [canonical, spellings] of Object.entries(TABLE.variants))\n\t\tfor (const s of spellings) out.set(s, canonical);\n\treturn out;\n})();\n\n/** canonical name -> every root it belongs to: itself when it is a root, and each root it is a form of. */\nconst ROOTS: ReadonlyMap<string, ReadonlySet<string>> = (() => {\n\tconst out = new Map<string, Set<string>>();\n\tconst add = (form: string, root: string) => {\n\t\tlet roots = out.get(form);\n\t\tif (roots === undefined) out.set(form, (roots = new Set()));\n\t\troots.add(root);\n\t};\n\tfor (const [root, forms] of Object.entries(TABLE.families)) {\n\t\tadd(root, root);\n\t\tfor (const f of forms) add(f, root);\n\t}\n\treturn out;\n})();\n\nconst NOT_AT_GATE: ReadonlySet<string> = new Set(TABLE.notAtGate);\n\nconst canonical = (name: string): string => CANONICAL.get(name) ?? name;\n\n/** May `name` (canonical) meet the other side of a pair through `root` at a gate? */\nconst gateThrough = (name: string, root: string): boolean =>\n\tname === root || !NOT_AT_GATE.has(name);\n\n/**\n * Do two DIFFERENT given names (NN3, letters only) stand for one another at a gate?\n *\n * True exactly when `givenFamilyTable` relates them by a gate-safe answer: two spellings of\n * one name, or one family through no `notAtGate` form. Two equal names answer `false`:\n * equality is the caller's own test and this is the tolerance past it, so a caller can tell\n * which one admitted a pair.\n */\nexport function sameGivenFamily(a: string, b: string): boolean {\n\tconst via = givenFamilyTable(a, b);\n\treturn via === \"given-variant\" || via === \"given-family\";\n}\n\n/**\n * What the table says about two DIFFERENT given names (NN3, letters only), as a kinship\n * `via`: `given-variant` for two spellings of one name, `given-family` where the two share a\n * root and a gate admits the pair, `given-family-not-gate` where every root they share is\n * reached through a `notAtGate` form, and `null` where the table does not relate them. Two\n * equal names answer `null`, for `sameGivenFamily`'s reason.\n *\n * THE DEFAULT GIVEN-NAME PROVIDER of `createNameKinship` (`./name-kinship.ts`).\n * `sameGivenFamily` is defined as its gate-safe answers, so the gate and the tolerant relation\n * cannot disagree about a pair.\n */\nexport function givenFamilyTable(\n\ta: string,\n\tb: string,\n): \"given-variant\" | \"given-family\" | \"given-family-not-gate\" | null {\n\tif (a === b) return null;\n\tconst ca = canonical(a);\n\tconst cb = canonical(b);\n\tif (ca === cb) return \"given-variant\";\n\tconst ra = ROOTS.get(ca);\n\tconst rb = ROOTS.get(cb);\n\tif (ra === undefined || rb === undefined) return null;\n\tlet shared = false;\n\tfor (const root of ra) {\n\t\tif (!rb.has(root)) continue;\n\t\tif (gateThrough(ca, root) && gateThrough(cb, root)) return \"given-family\";\n\t\tshared = true;\n\t}\n\treturn shared ? \"given-family-not-gate\" : null;\n}\n",
+    "/**\n * given-families.ts — THE EXTENDED GIVEN-NAME FAMILY LIST, read by the TypeScript side.\n *\n * `./given-families.json` is the list and this file is its reader; `scripts/given-families.ts`\n * builds the list and `./given-families.MANIFEST.json` records its sources.\n *\n * TWO TIERS OF GIVEN-NAME KNOWLEDGE. `./given-diminutives.json` is the GATE tier: pairs this\n * package is sure of, curated by hand, some of them admitted at an identity gate. This list\n * is the EXTENDED tier: every family the sources record for English, Irish, Scottish, Welsh,\n * French, Italian, Spanish, German, Dutch and Polish usage, about 2,600 names. A pair it\n * relates MAY be one name, and the answer is `given-maybe`, which no gate admits.\n *\n * AN EXACT LIST, NOT A FILTER. A bloom filter of the same pairs at 8 KB answers about fifty\n * false partners for every given name it is asked about; the exact list is a few KB more\n * and answers none.\n *\n * A FAMILY IS CLOSED. Two names relate when they are a root and its form, or two forms of\n * one root (`Kate` / `Katie`, both Catherine's). A form under several roots meets each\n * root's family, and nothing is transitive across families: `Kit` meets Catherine's and\n * Christopher's, and `Kate` / `Chris` stay apart.\n *\n * A TIER BOUNDS HOW RARE A FORM MAY BE. Each form carries 1 (common), 2 (uncommon) or 3\n * (rare); a pair's tier is its rarer member's, the root counting as 1, and where two names\n * share several families the commonest counts. `maxTier` admits pairs up to that tier.\n */\n\nimport list from \"./given-families.json\";\n\n/** How common a form is: 1 common, 2 uncommon, 3 rare. */\nexport type GivenFamilyTier = 1 | 2 | 3;\n\nexport interface GivenFamilyListOptions {\n\t/** The rarest tier admitted. Default 3: every pair the list holds. */\n\treadonly maxTier?: GivenFamilyTier;\n\t/**\n\t * The families, one `ROOT,FORM:TIER,…` line each, NN3 upper case. Default: the shipped\n\t * `given-families.json`. A caller with its own list passes it here.\n\t */\n\treadonly families?: readonly string[];\n}\n\n/** A given-name provider over the extended list: `given-maybe` or `null`. */\nexport type GivenFamilyList = (a: string, b: string) => \"given-maybe\" | null;\n\n/** name -> root -> the name's tier in that root's family (a root's own is 1) */\ntype Memberships = ReadonlyMap<string, ReadonlyMap<string, number>>;\n\n/**\n * The lines, read. A malformed line throws: the list is data this package ships or a caller\n * supplies, and a line read wrong would relate names silently.\n */\nfunction parseFamilies(lines: readonly string[]): Memberships {\n\tconst out = new Map<string, Map<string, number>>();\n\tconst join = (name: string, root: string, tier: number) => {\n\t\tlet roots = out.get(name);\n\t\tif (roots === undefined) out.set(name, (roots = new Map()));\n\t\troots.set(root, Math.min(roots.get(root) ?? tier, tier));\n\t};\n\tfor (const line of lines) {\n\t\tconst [root, ...forms] = line.split(\",\");\n\t\tif (root === undefined || !/^[A-Z]+$/.test(root))\n\t\t\tthrow new Error(`given-families: bad root in \"${line}\"`);\n\t\tjoin(root, root, 1);\n\t\tfor (const entry of forms) {\n\t\t\tconst m = /^([A-Z]+):([123])$/.exec(entry);\n\t\t\tif (m === null) throw new Error(`given-families: bad form \"${entry}\" in \"${line}\"`);\n\t\t\tjoin(m[1] as string, root, Number(m[2]));\n\t\t}\n\t}\n\treturn out;\n}\n\n/**\n * The extended list as a `GivenProvider` for `createNameKinship`: `given-maybe` where two\n * DIFFERENT names (NN3) share a family within `maxTier`, `null` otherwise. Two equal names\n * answer `null`, as `givenFamilyTable`'s do.\n *\n * The list is parsed on the first question, once per provider.\n */\nexport function createGivenFamilyList(options: GivenFamilyListOptions = {}): GivenFamilyList {\n\tconst maxTier = options.maxTier ?? 3;\n\tconst lines = options.families ?? (list as { families: readonly string[] }).families;\n\tlet members: Memberships | undefined;\n\treturn (a, b) => {\n\t\tif (a === b) return null;\n\t\tmembers ??= parseFamilies(lines);\n\t\tconst ra = members.get(a);\n\t\tconst rb = members.get(b);\n\t\tif (ra === undefined || rb === undefined) return null;\n\t\tfor (const [root, ta] of ra) {\n\t\t\tconst tb = rb.get(root);\n\t\t\tif (tb !== undefined && Math.max(ta, tb) <= maxTier) return \"given-maybe\";\n\t\t}\n\t\treturn null;\n\t};\n}\n\n/**\n * The shipped list as root -> form -> tier, roots and forms sorted, for `names tables\n * given-name`, which prints it. Not a package export: the printed form is the contract.\n */\nexport function givenFamilyTiers(): Record<string, Record<string, GivenFamilyTier>> {\n\tconst byRoot = new Map<string, Map<string, GivenFamilyTier>>();\n\tfor (const [name, roots] of parseFamilies((list as { families: readonly string[] }).families))\n\t\tfor (const [root, tier] of roots) {\n\t\t\tif (name === root) continue;\n\t\t\tlet forms = byRoot.get(root);\n\t\t\tif (forms === undefined) byRoot.set(root, (forms = new Map()));\n\t\t\tforms.set(name, tier as GivenFamilyTier);\n\t\t}\n\tconst out: Record<string, Record<string, GivenFamilyTier>> = {};\n\tfor (const root of [...byRoot.keys()].sort())\n\t\tout[root] = Object.fromEntries([...byRoot.get(root)!].sort(([a], [b]) => (a < b ? -1 : 1)));\n\treturn out;\n}\n\n/** The shipped list, every tier: the second given-name provider of `nameKinship`. */\nexport const givenFamilyList: GivenFamilyList = createGivenFamilyList();\n"
+  ],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA2CA,IAAM,QAAQ;AAMP,SAAS,oBAAoB,GAIlC;AAAA,EACD,OAAO;AAAA;AAIR,IAAM,aAA0C,MAAM;AAAA,EACrD,MAAM,MAAM,IAAI;AAAA,EAChB,YAAY,WAAW,cAAc,OAAO,QAAQ,MAAM,QAAQ;AAAA,IACjE,WAAW,KAAK;AAAA,MAAW,IAAI,IAAI,GAAG,SAAS;AAAA,EAChD,OAAO;AAAA,GACL;AAGH,IAAM,SAAmD,MAAM;AAAA,EAC9D,MAAM,MAAM,IAAI;AAAA,EAChB,MAAM,MAAM,CAAC,MAAc,SAAiB;AAAA,IAC3C,IAAI,QAAQ,IAAI,IAAI,IAAI;AAAA,IACxB,IAAI,UAAU;AAAA,MAAW,IAAI,IAAI,MAAO,QAAQ,IAAI,GAAM;AAAA,IAC1D,MAAM,IAAI,IAAI;AAAA;AAAA,EAEf,YAAY,MAAM,UAAU,OAAO,QAAQ,MAAM,QAAQ,GAAG;AAAA,IAC3D,IAAI,MAAM,IAAI;AAAA,IACd,WAAW,KAAK;AAAA,MAAO,IAAI,GAAG,IAAI;AAAA,EACnC;AAAA,EACA,OAAO;AAAA,GACL;AAEH,IAAM,cAAmC,IAAI,IAAI,MAAM,SAAS;AAEhE,IAAM,YAAY,CAAC,SAAyB,UAAU,IAAI,IAAI,KAAK;AAGnE,IAAM,cAAc,CAAC,MAAc,SAClC,SAAS,QAAQ,CAAC,YAAY,IAAI,IAAI;AAUhC,SAAS,gBAAe,CAAC,GAAW,GAAoB;AAAA,EAC9D,MAAM,MAAM,kBAAiB,GAAG,CAAC;AAAA,EACjC,OAAO,QAAQ,mBAAmB,QAAQ;AAAA;AAcpC,SAAS,iBAAgB,CAC/B,GACA,GACoE;AAAA,EACpE,IAAI,MAAM;AAAA,IAAG,OAAO;AAAA,EACpB,MAAM,KAAK,UAAU,CAAC;AAAA,EACtB,MAAM,KAAK,UAAU,CAAC;AAAA,EACtB,IAAI,OAAO;AAAA,IAAI,OAAO;AAAA,EACtB,MAAM,KAAK,MAAM,IAAI,EAAE;AAAA,EACvB,MAAM,KAAK,MAAM,IAAI,EAAE;AAAA,EACvB,IAAI,OAAO,aAAa,OAAO;AAAA,IAAW,OAAO;AAAA,EACjD,IAAI,SAAS;AAAA,EACb,WAAW,QAAQ,IAAI;AAAA,IACtB,IAAI,CAAC,GAAG,IAAI,IAAI;AAAA,MAAG;AAAA,IACnB,IAAI,YAAY,IAAI,IAAI,KAAK,YAAY,IAAI,IAAI;AAAA,MAAG,OAAO;AAAA,IAC3D,SAAS;AAAA,EACV;AAAA,EACA,OAAO,SAAS,0BAA0B;AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AC9E3C,SAAS,aAAa,CAAC,OAAuC;AAAA,EAC7D,MAAM,MAAM,IAAI;AAAA,EAChB,MAAM,OAAO,CAAC,MAAc,MAAc,SAAiB;AAAA,IAC1D,IAAI,QAAQ,IAAI,IAAI,IAAI;AAAA,IACxB,IAAI,UAAU;AAAA,MAAW,IAAI,IAAI,MAAO,QAAQ,IAAI,GAAM;AAAA,IAC1D,MAAM,IAAI,MAAM,KAAK,IAAI,MAAM,IAAI,IAAI,KAAK,MAAM,IAAI,CAAC;AAAA;AAAA,EAExD,WAAW,QAAQ,OAAO;AAAA,IACzB,OAAO,SAAS,SAAS,KAAK,MAAM,GAAG;AAAA,IACvC,IAAI,SAAS,aAAa,CAAC,WAAW,KAAK,IAAI;AAAA,MAC9C,MAAM,IAAI,MAAM,gCAAgC,OAAO;AAAA,IACxD,KAAK,MAAM,MAAM,CAAC;AAAA,IAClB,WAAW,SAAS,OAAO;AAAA,MAC1B,MAAM,IAAI,qBAAqB,KAAK,KAAK;AAAA,MACzC,IAAI,MAAM;AAAA,QAAM,MAAM,IAAI,MAAM,6BAA6B,cAAc,OAAO;AAAA,MAClF,KAAK,EAAE,IAAc,MAAM,OAAO,EAAE,EAAE,CAAC;AAAA,IACxC;AAAA,EACD;AAAA,EACA,OAAO;AAAA;AAUD,SAAS,sBAAqB,CAAC,UAAkC,CAAC,GAAoB;AAAA,EAC5F,MAAM,UAAU,QAAQ,WAAW;AAAA,EACnC,MAAM,QAAQ,QAAQ,YAAa,uBAAyC;AAAA,EAC5E,IAAI;AAAA,EACJ,OAAO,CAAC,GAAG,MAAM;AAAA,IAChB,IAAI,MAAM;AAAA,MAAG,OAAO;AAAA,IACpB,YAAY,cAAc,KAAK;AAAA,IAC/B,MAAM,KAAK,QAAQ,IAAI,CAAC;AAAA,IACxB,MAAM,KAAK,QAAQ,IAAI,CAAC;AAAA,IACxB,IAAI,OAAO,aAAa,OAAO;AAAA,MAAW,OAAO;AAAA,IACjD,YAAY,MAAM,OAAO,IAAI;AAAA,MAC5B,MAAM,KAAK,GAAG,IAAI,IAAI;AAAA,MACtB,IAAI,OAAO,aAAa,KAAK,IAAI,IAAI,EAAE,KAAK;AAAA,QAAS,OAAO;AAAA,IAC7D;AAAA,IACA,OAAO;AAAA;AAAA;AAQF,SAAS,gBAAgB,GAAoD;AAAA,EACnF,MAAM,SAAS,IAAI;AAAA,EACnB,YAAY,MAAM,UAAU,cAAe,uBAAyC,QAAQ;AAAA,IAC3F,YAAY,MAAM,SAAS,OAAO;AAAA,MACjC,IAAI,SAAS;AAAA,QAAM;AAAA,MACnB,IAAI,QAAQ,OAAO,IAAI,IAAI;AAAA,MAC3B,IAAI,UAAU;AAAA,QAAW,OAAO,IAAI,MAAO,QAAQ,IAAI,GAAM;AAAA,MAC7D,MAAM,IAAI,MAAM,IAAuB;AAAA,IACxC;AAAA,EACD,MAAM,MAAuD,CAAC;AAAA,EAC9D,WAAW,QAAQ,CAAC,GAAG,OAAO,KAAK,CAAC,EAAE,KAAK;AAAA,IAC1C,IAAI,QAAQ,OAAO,YAAY,CAAC,GAAG,OAAO,IAAI,IAAI,CAAE,EAAE,KAAK,EAAE,KAAK,OAAQ,IAAI,IAAI,KAAK,CAAE,CAAC;AAAA,EAC3F,OAAO;AAAA;AAID,IAAM,mBAAmC,uBAAsB;",
+  "debugId": "0A72D6F5743D283A64756E2164756E21",
+  "names": []
+}

package/dist/cli/bin.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+import {
+  givenDiminutiveTable,
+  givenFamilyTiers
+} from "../chunks/index-qmn87bdh.js";
+
+// src/cli/tables.ts
+var TABLES = {
+  "given-name": { "1": givenNameV1 }
+};
+var OUTPUTS = ["json"];
+function givenNameV1() {
+  const gate = givenDiminutiveTable();
+  return {
+    $comment: [
+      "@finbheara/names given-name tables, schema 1. Every name is NN3: upper case, letters only.",
+      "`variants`: canonical -> its other spellings. Read each name as its canonical spelling first;",
+      "two names with one canonical are `given-variant`. `families` and `notAtGate` hold canonical",
+      "spellings only.",
+      "`families`: root -> its familiar forms, the curated gate tier. A root belongs to its own family.",
+      "A form may sit under several roots and meets EVERY one of them; nothing is transitive, so two",
+      "names relate only when they share a root. They are `given-family` when, for some shared root,",
+      "neither name is a `notAtGate` form of it (a name that IS the root always passes), else",
+      "`given-family-not-gate`, which an identity gate must refuse.",
+      "`extended`: root -> form -> tier (1 common, 2 uncommon, 3 rare), the extended list. Two names",
+      "relate when they share a root; the pair's tier is its rarer member's, the root counting as 1.",
+      "Every pair here is `given-maybe`: a lead, never a gate. It is asked after `families`.",
+      "Two equal names are none of these: equality is the caller's own test."
+    ],
+    table: "given-name",
+    schema: 1,
+    variants: gate.variants,
+    families: gate.families,
+    notAtGate: gate.notAtGate,
+    extended: givenFamilyTiers()
+  };
+}
+var USAGE = [
+  "usage: names tables <table> [--output json] [--schema N]",
+  `tables: ${Object.entries(TABLES).map(([t, v]) => `${t} (schemas ${Object.keys(v).join(", ")})`).join("; ")}`,
+  "defaults: --output json --schema 1"
+].join(`
+`);
+function tables(argv) {
+  const options = { output: "json", schema: "1" };
+  const positional = [];
+  for (let i = 0;i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--help" || a === "-h") {
+      console.log(USAGE);
+      return 0;
+    }
+    const m = /^--([a-z]+)(?:=(.*))?$/.exec(a);
+    if (m === null) {
+      positional.push(a);
+      continue;
+    }
+    const [, key, inline] = m;
+    if (!(key in options))
+      return fail(`unknown option --${key}`);
+    const value = inline ?? argv[++i];
+    if (value === undefined)
+      return fail(`--${key} needs a value`);
+    options[key] = value;
+  }
+  if (positional.length !== 1)
+    return fail("name one table");
+  const schemas = TABLES[positional[0]];
+  if (schemas === undefined)
+    return fail(`unknown table "${positional[0]}"`);
+  const print = schemas[options.schema];
+  if (print === undefined)
+    return fail(`${positional[0]} has no schema ${options.schema}`);
+  if (!OUTPUTS.includes(options.output))
+    return fail(`unknown output "${options.output}"`);
+  console.log(JSON.stringify(print(), null, "\t"));
+  return 0;
+}
+function fail(message) {
+  console.error(`names tables: ${message}
+${USAGE}`);
+  return 2;
+}
+
+// src/cli/bin.ts
+var COMMANDS = { tables };
+var USAGE2 = "usage: names tables <table> [--output json] [--schema N]";
+function main(argv) {
+  const [command, ...rest] = argv;
+  if (command === "--help" || command === "-h") {
+    console.log(USAGE2);
+    return 0;
+  }
+  if (command === undefined) {
+    console.error(USAGE2);
+    return 2;
+  }
+  const run = COMMANDS[command];
+  if (run === undefined) {
+    console.error(`names: unknown command "${command}"
+${USAGE2}`);
+    return 2;
+  }
+  return run(rest);
+}
+process.exitCode = main(process.argv.slice(2));
+
+//# debugId=E2CE232D305113AE64756E2164756E21
+//# sourceMappingURL=bin.js.map

package/dist/cli/bin.js.map

@@ -0,0 +1,11 @@
+{
+  "version": 3,
+  "sources": ["../src/cli/tables.ts", "../src/cli/bin.ts"],
+  "sourcesContent": [
+    "/**\n * tables.ts — the package's data tables, printed for a consumer in any language.\n *\n *   names tables given-name [--output json] [--schema 1] > given-name-tables.json\n *\n * THE PRINTED FORM IS THE CONTRACT, not the files the tables are stored in. Each table has\n * numbered schemas; a schema, once released, prints the same shape for as long as the\n * package offers it, and a new shape is a new schema. `--schema` defaults to 1 and\n * `--output` to `json`, so a command written against the first release keeps working.\n * (`--schema`, not `--version`: the number is the output's shape, not the package's.)\n */\n\nimport { givenDiminutiveTable } from \"../normalize/given-diminutives.ts\";\nimport { givenFamilyTiers } from \"../normalize/given-families.ts\";\n\n/** table -> schema -> its printed value */\nconst TABLES: Record<string, Record<string, () => unknown>> = {\n\t\"given-name\": { \"1\": givenNameV1 },\n};\n\nconst OUTPUTS = [\"json\"];\n\n/**\n * `given-name` schema 1: the curated gate table and the extended family list, with the\n * rules a reader needs to answer as `givenFamilyTable` and `givenFamilyList` do.\n */\nfunction givenNameV1() {\n\tconst gate = givenDiminutiveTable();\n\treturn {\n\t\t$comment: [\n\t\t\t\"@finbheara/names given-name tables, schema 1. Every name is NN3: upper case, letters only.\",\n\t\t\t\"`variants`: canonical -> its other spellings. Read each name as its canonical spelling first;\",\n\t\t\t\"two names with one canonical are `given-variant`. `families` and `notAtGate` hold canonical\",\n\t\t\t\"spellings only.\",\n\t\t\t\"`families`: root -> its familiar forms, the curated gate tier. A root belongs to its own family.\",\n\t\t\t\"A form may sit under several roots and meets EVERY one of them; nothing is transitive, so two\",\n\t\t\t\"names relate only when they share a root. They are `given-family` when, for some shared root,\",\n\t\t\t\"neither name is a `notAtGate` form of it (a name that IS the root always passes), else\",\n\t\t\t\"`given-family-not-gate`, which an identity gate must refuse.\",\n\t\t\t\"`extended`: root -> form -> tier (1 common, 2 uncommon, 3 rare), the extended list. Two names\",\n\t\t\t\"relate when they share a root; the pair's tier is its rarer member's, the root counting as 1.\",\n\t\t\t\"Every pair here is `given-maybe`: a lead, never a gate. It is asked after `families`.\",\n\t\t\t\"Two equal names are none of these: equality is the caller's own test.\",\n\t\t],\n\t\ttable: \"given-name\",\n\t\tschema: 1,\n\t\tvariants: gate.variants,\n\t\tfamilies: gate.families,\n\t\tnotAtGate: gate.notAtGate,\n\t\textended: givenFamilyTiers(),\n\t};\n}\n\nconst USAGE = [\n\t\"usage: names tables <table> [--output json] [--schema N]\",\n\t`tables: ${Object.entries(TABLES)\n\t\t.map(([t, v]) => `${t} (schemas ${Object.keys(v).join(\", \")})`)\n\t\t.join(\"; \")}`,\n\t\"defaults: --output json --schema 1\",\n].join(\"\\n\");\n\n/** `names tables …`: prints one table to stdout. Returns the exit code. */\nexport function tables(argv: readonly string[]): number {\n\tconst options: Record<string, string> = { output: \"json\", schema: \"1\" };\n\tconst positional: string[] = [];\n\tfor (let i = 0; i < argv.length; i++) {\n\t\tconst a = argv[i]!;\n\t\tif (a === \"--help\" || a === \"-h\") {\n\t\t\tconsole.log(USAGE);\n\t\t\treturn 0;\n\t\t}\n\t\tconst m = /^--([a-z]+)(?:=(.*))?$/.exec(a);\n\t\tif (m === null) {\n\t\t\tpositional.push(a);\n\t\t\tcontinue;\n\t\t}\n\t\tconst [, key, inline] = m as unknown as [string, string, string | undefined];\n\t\tif (!(key in options)) return fail(`unknown option --${key}`);\n\t\tconst value = inline ?? argv[++i];\n\t\tif (value === undefined) return fail(`--${key} needs a value`);\n\t\toptions[key] = value;\n\t}\n\tif (positional.length !== 1) return fail(\"name one table\");\n\tconst schemas = TABLES[positional[0]!];\n\tif (schemas === undefined) return fail(`unknown table \"${positional[0]}\"`);\n\tconst print = schemas[options.schema!];\n\tif (print === undefined) return fail(`${positional[0]} has no schema ${options.schema}`);\n\tif (!OUTPUTS.includes(options.output!)) return fail(`unknown output \"${options.output}\"`);\n\tconsole.log(JSON.stringify(print(), null, \"\\t\"));\n\treturn 0;\n}\n\nfunction fail(message: string): number {\n\tconsole.error(`names tables: ${message}\\n${USAGE}`);\n\treturn 2;\n}\n",
+    "#!/usr/bin/env node\n/**\n * names — the package's command, run as `npx @finbheara/names …` or `bunx @finbheara/names …`.\n *\n *   names tables <table> [--output json] [--schema N]   print a data table\n *\n * Runs under Node or Bun. (`bun run names` in this repository is the lexicon curation CLI,\n * `./names.ts`, which is not shipped.)\n */\n\nimport { tables } from \"./tables.ts\";\n\nconst COMMANDS: Record<string, (argv: readonly string[]) => number> = { tables };\n\nconst USAGE = \"usage: names tables <table> [--output json] [--schema N]\";\n\nfunction main(argv: readonly string[]): number {\n\tconst [command, ...rest] = argv;\n\tif (command === \"--help\" || command === \"-h\") {\n\t\tconsole.log(USAGE);\n\t\treturn 0;\n\t}\n\tif (command === undefined) {\n\t\tconsole.error(USAGE);\n\t\treturn 2;\n\t}\n\tconst run = COMMANDS[command];\n\tif (run === undefined) {\n\t\tconsole.error(`names: unknown command \"${command}\"\\n${USAGE}`);\n\t\treturn 2;\n\t}\n\treturn run(rest);\n}\n\n// Run unconditionally: this module is only ever the entry (a `.bin` symlink makes an\n// `import.meta.url === argv[1]` test unreliable).\nprocess.exitCode = main(process.argv.slice(2));\n"
+  ],
+  "mappings": "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",
+  "debugId": "E2CE232D305113AE64756E2164756E21",
+  "names": []
+}

package/dist/index.js

@@ -42,10 +42,6 @@ import {
 import"./chunks/index-jwx1mm4k.js";
 import {
   repairMojibake2,
-  sameGivenFamily2,
-  givenFamilyTable2,
-  createGivenFamilyList2,
-  givenFamilyList2,
   comparePosition2,
   nameRelation2,
   MAX_READINGS2,
@@ -93,12 +89,18 @@ import {
   readNameCell2,
   DEFAULT_NAME_FORMAT_THRESHOLD2,
   deriveNameFormat2
-} from "./chunks/index-74fyytnh.js";
+} from "./chunks/index-n6fpj92s.js";
 import"./chunks/index-qsznkk4s.js";
 import {
   composeEvalSet2,
   evaluateClassifier2
 } from "./chunks/index-a6f2y4aa.js";
+import {
+  sameGivenFamily2,
+  givenFamilyTable2,
+  createGivenFamilyList2,
+  givenFamilyList2
+} from "./chunks/index-qmn87bdh.js";
 import"./chunks/index-tqdbxd92.js";
 import {
   doubleMetaphone2
@@ -326,5 +328,5 @@ export {
   traditionOf2 as traditionOf
 };
 
-//# debugId=C060D5DD49C57FA364756E2164756E21
+//# debugId=CCF455D45E820EC364756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -4,6 +4,6 @@
   "sourcesContent": [
   ],
   "mappings": "",
-  "debugId": "C060D5DD49C57FA364756E2164756E21",
+  "debugId": "CCF455D45E820EC364756E2164756E21",
   "names": []
 }

package/dist/normalize/index.js

@@ -1,9 +1,5 @@
 import {
   repairMojibake2,
-  sameGivenFamily2,
-  givenFamilyTable2,
-  createGivenFamilyList2,
-  givenFamilyList2,
   comparePosition2,
   nameRelation2,
   MAX_READINGS2,
@@ -51,7 +47,13 @@ import {
   readNameCell2,
   DEFAULT_NAME_FORMAT_THRESHOLD2,
   deriveNameFormat2
-} from "../chunks/index-74fyytnh.js";
+} from "../chunks/index-n6fpj92s.js";
+import {
+  sameGivenFamily2,
+  givenFamilyTable2,
+  createGivenFamilyList2,
+  givenFamilyList2
+} from "../chunks/index-qmn87bdh.js";
 import"../chunks/index-tqdbxd92.js";
 import {
   NAME_REFUSED2,
@@ -218,5 +220,5 @@ export {
   traditionLookupOf2 as traditionLookupOf
 };
 
-//# debugId=9549507E34EB444A64756E2164756E21
+//# debugId=5AFE7A2DCFBC721064756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/normalize/index.js.map

@@ -4,6 +4,6 @@
   "sourcesContent": [
   ],
   "mappings": "",
-  "debugId": "9549507E34EB444A64756E2164756E21",
+  "debugId": "5AFE7A2DCFBC721064756E2164756E21",
   "names": []
 }

package/dist/types/cli/bin.d.ts

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+/**
+ * names — the package's command, run as `npx @finbheara/names …` or `bunx @finbheara/names …`.
+ *
+ *   names tables <table> [--output json] [--schema N]   print a data table
+ *
+ * Runs under Node or Bun. (`bun run names` in this repository is the lexicon curation CLI,
+ * `./names.ts`, which is not shipped.)
+ */
+export {};

package/dist/types/cli/tables.d.ts

@@ -0,0 +1,13 @@
+/**
+ * tables.ts — the package's data tables, printed for a consumer in any language.
+ *
+ *   names tables given-name [--output json] [--schema 1] > given-name-tables.json
+ *
+ * THE PRINTED FORM IS THE CONTRACT, not the files the tables are stored in. Each table has
+ * numbered schemas; a schema, once released, prints the same shape for as long as the
+ * package offers it, and a new shape is a new schema. `--schema` defaults to 1 and
+ * `--output` to `json`, so a command written against the first release keeps working.
+ * (`--schema`, not `--version`: the number is the output's shape, not the package's.)
+ */
+/** `names tables …`: prints one table to stdout. Returns the exit code. */
+export declare function tables(argv: readonly string[]): number;

package/dist/types/normalize/given-diminutives.d.ts

@@ -1,12 +1,12 @@
 /**
  * given-diminutives.ts — ONE GIVEN-NAME DIMINUTIVE TABLE, read by the TypeScript side.
  *
- * `./given-diminutives.json` is the table and this file is its reader. A Python linkage
- * lane reads the same JSON for its `givenRoot` comparison level, so the two languages
- * share one copy and no second one exists. An earlier adjudicator carried a `FAMILIAR`
- * map of eight entries and said *"the name primitives are where it belongs once a second
- * consumer wants one"*; the teachers-directory gate is that second consumer, and the eight
- * entries are in the table.
+ * `./given-diminutives.json` is the table and this file is its reader. A consumer in another
+ * language reads the table as `names tables given-name` prints it (`../cli/tables.ts`), never
+ * this file, so the file's layout may change and no second copy exists. An earlier
+ * adjudicator carried a `FAMILIAR` map of eight entries and said *"the name primitives are
+ * where it belongs once a second consumer wants one"*; the teachers-directory gate is that
+ * second consumer, and the eight entries are in the table.
  *
  * A RELATION OF A PAIR AND NEVER A KEY. Nothing here rewrites a given name: a stored key,
  * a filing key and every rendering keep the print's own spelling. A caller asks whether
@@ -32,6 +32,15 @@
  * `Eve` and `Eva` share none, though `Evie` meets both. A `notAtGate` form is refused AS A
  * FORM: where it is the root itself (`Caitlin` / `Cait`), its own forms meet it at a gate.
  */
+/**
+ * The table as this module reads it, for `names tables given-name`, which prints it. Not a
+ * package export: the printed form is the contract, and this file's layout may change.
+ */
+export declare function givenDiminutiveTable(): {
+    readonly variants: Readonly<Record<string, readonly string[]>>;
+    readonly families: Readonly<Record<string, readonly string[]>>;
+    readonly notAtGate: readonly string[];
+};
 /**
  * Do two DIFFERENT given names (NN3, letters only) stand for one another at a gate?
  *

package/dist/types/normalize/given-families.d.ts

@@ -44,5 +44,10 @@ export type GivenFamilyList = (a: string, b: string) => "given-maybe" | null;
  * The list is parsed on the first question, once per provider.
  */
 export declare function createGivenFamilyList(options?: GivenFamilyListOptions): GivenFamilyList;
+/**
+ * The shipped list as root -> form -> tier, roots and forms sorted, for `names tables
+ * given-name`, which prints it. Not a package export: the printed form is the contract.
+ */
+export declare function givenFamilyTiers(): Record<string, Record<string, GivenFamilyTier>>;
 /** The shipped list, every tier: the second given-name provider of `nameKinship`. */
 export declare const givenFamilyList: GivenFamilyList;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@finbheara/names",
-	"version": "0.16.0",
+	"version": "0.17.0",
 	"description": "A curated lexicon of personal, school and place names, the surname-particle vocabulary, a phrase classifier and a person-name normalizer",
 	"keywords": [
 		"names",
@@ -88,6 +88,7 @@
 		"typescript": "7.0.2"
 	},
 	"bin": {
+		"names": "./dist/cli/bin.js",
 		"names-census": "./dist/cli/census.js"
 	}
 }