@finbheara/names 0.14.0 → 0.16.0

package/dist/normalize/index.js

@@ -2,6 +2,8 @@ import {
   repairMojibake2,
   sameGivenFamily2,
   givenFamilyTable2,
+  createGivenFamilyList2,
+  givenFamilyList2,
   comparePosition2,
   nameRelation2,
   MAX_READINGS2,
@@ -49,8 +51,8 @@ import {
   readNameCell2,
   DEFAULT_NAME_FORMAT_THRESHOLD2,
   deriveNameFormat2
-} from "../chunks/index-kw69ry3j.js";
-import"../chunks/index-kw6gbrnq.js";
+} from "../chunks/index-74fyytnh.js";
+import"../chunks/index-tqdbxd92.js";
 import {
   NAME_REFUSED2,
   stripEveryAside2,
@@ -95,7 +97,7 @@ import {
   defaultPersonNameFactory2,
   personName2,
   personNameFromIcao2
-} from "../chunks/index-ka8nzreg.js";
+} from "../chunks/index-tk01chxw.js";
 import {
   TEAM_WORD2,
   TEAM_DESIGNATION_WORDS2,
@@ -108,7 +110,7 @@ import {
 } from "../chunks/index-0phgwy52.js";
 import {
   lexiconKey2
-} from "../chunks/index-7vvt5hhy.js";
+} from "../chunks/index-0wpvbdgh.js";
 export {
   COMPOUND_SURNAMES2 as COMPOUND_SURNAMES,
   DEFAULT_NAME_FORMAT_THRESHOLD2 as DEFAULT_NAME_FORMAT_THRESHOLD,
@@ -140,6 +142,7 @@ export {
   composeReadings2 as composeReadings,
   compoundGiven2 as compoundGiven,
   createCachingPersonNameFactory2 as createCachingPersonNameFactory,
+  createGivenFamilyList2 as createGivenFamilyList,
   createNameClusters2 as createNameClusters,
   createNameIndex2 as createNameIndex,
   createNameKinship2 as createNameKinship,
@@ -152,6 +155,7 @@ export {
   foldNameKey2 as foldNameKey,
   formatPersonDisplay2 as formatPersonDisplay,
   givenAbbreviates2 as givenAbbreviates,
+  givenFamilyList2 as givenFamilyList,
   givenFamilyTable2 as givenFamilyTable,
   givenKeyAbbreviates2 as givenKeyAbbreviates,
   infeasibleClass2 as infeasibleClass,
@@ -214,5 +218,5 @@ export {
   traditionLookupOf2 as traditionLookupOf
 };
 
-//# debugId=6CAF39AD5BAB8B2064756E2164756E21
+//# debugId=9549507E34EB444A64756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/normalize/index.js.map

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

package/dist/types/classifier/bf/filters.d.ts

@@ -1,10 +1,15 @@
 /**
  * Bloom filters for name classification
- * Generated: 2026-01-03T00:32:31.659Z
+ * Built by scripts/build-blooms.ts from the source lists recorded in
+ * data/bloom/MANIFEST.json, which also holds each table's item count.
  * Target FPP: 0.01
- * Total items: 484,270
- * Total bits: 4,641,758 (566.6 KB)
  */
+/**
+ * The key a name table holds and is asked: lower-cased, NFD, combining marks dropped,
+ * the ASCII apostrophe dropped. `scripts/build-blooms.ts` builds the tables with it, so
+ * a lookup and a build cannot disagree.
+ */
+export declare function normalize(s: string): string;
 /** Check if word is a known surname (151k entries) */
 export declare function isSurname(word: string): boolean;
 /** Check if word is in the human names list (197k first+last names) */

package/dist/types/lexicon/flags.d.ts

@@ -2,19 +2,22 @@
  * The flag alphabet, typed, and the predicates over one entry's flag string.
  *
  * FLAGS ARE CASE-SENSITIVE. Upper case classifies; a digit is a tradition
- * footnote. `S` and `X` are marks that classify nothing.
+ * footnote. `S`, `X` and `D` are marks that classify nothing.
  *
  * A FLAGLESS ENTRY IS A FEMALE GIVEN NAME. The header says so outright, so every
  * predicate here reads `""` (or a string with no class letter) as `F`.
  */
 /** The classification namespace: what KIND of thing the entry is. */
 export declare const CLASS_FLAGS: "FMNLAGTCB";
-/** Marks: `S` a typo kept on purpose, `X` excluded from the renderer round trip. */
-export declare const MARK_FLAGS: "SX";
+/**
+ * Marks: `S` a typo kept on purpose, `X` excluded from the renderer round trip, `D` a given
+ * name in a diminutive table (`given-diminutives.json` or `given-families.json`).
+ */
+export declare const MARK_FLAGS: "SXD";
 /** Every letter the file issues. */
-export declare const CLASSIFICATION_FLAGS: "FMNLATGCBSX";
+export declare const CLASSIFICATION_FLAGS: "FMNLATGCBSXD";
 export type ClassFlag = "F" | "M" | "N" | "L" | "A" | "G" | "T" | "C" | "B";
-export type MarkFlag = "S" | "X";
+export type MarkFlag = "S" | "X" | "D";
 export type Flag = ClassFlag | MarkFlag;
 /**
  * The tradition namespace: a FOOTNOTE INDEX naming which onomastic tradition
@@ -53,6 +56,11 @@ export declare const isMultiWord: (flags: string) => boolean;
 export declare const isSuspicious: (flags: string) => boolean;
 /** `X`: excluded from the renderer round trip. */
 export declare const isRoundTripException: (flags: string) => boolean;
+/**
+ * `D`: a given name that a diminutive table holds, as a root, a form or a spelling. It says
+ * the tables know the name; which names it relates to is the tables' answer, never the flag's.
+ */
+export declare const isInDiminutiveTable: (flags: string) => boolean;
 /**
  * Any person class: `F`, `M`, `N`, `L` or `A`. An entry with no class at all is
  * a female given name and so a person.

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

@@ -0,0 +1,48 @@
+/**
+ * given-families.ts — THE EXTENDED GIVEN-NAME FAMILY LIST, read by the TypeScript side.
+ *
+ * `./given-families.json` is the list and this file is its reader; `scripts/given-families.ts`
+ * builds the list and `./given-families.MANIFEST.json` records its sources.
+ *
+ * TWO TIERS OF GIVEN-NAME KNOWLEDGE. `./given-diminutives.json` is the GATE tier: pairs this
+ * package is sure of, curated by hand, some of them admitted at an identity gate. This list
+ * is the EXTENDED tier: every family the sources record for English, Irish, Scottish, Welsh,
+ * French, Italian, Spanish, German, Dutch and Polish usage, about 2,600 names. A pair it
+ * relates MAY be one name, and the answer is `given-maybe`, which no gate admits.
+ *
+ * AN EXACT LIST, NOT A FILTER. A bloom filter of the same pairs at 8 KB answers about fifty
+ * false partners for every given name it is asked about; the exact list is a few KB more
+ * and answers none.
+ *
+ * A FAMILY IS CLOSED. Two names relate when they are a root and its form, or two forms of
+ * one root (`Kate` / `Katie`, both Catherine's). A form under several roots meets each
+ * root's family, and nothing is transitive across families: `Kit` meets Catherine's and
+ * Christopher's, and `Kate` / `Chris` stay apart.
+ *
+ * A TIER BOUNDS HOW RARE A FORM MAY BE. Each form carries 1 (common), 2 (uncommon) or 3
+ * (rare); a pair's tier is its rarer member's, the root counting as 1, and where two names
+ * share several families the commonest counts. `maxTier` admits pairs up to that tier.
+ */
+/** How common a form is: 1 common, 2 uncommon, 3 rare. */
+export type GivenFamilyTier = 1 | 2 | 3;
+export interface GivenFamilyListOptions {
+    /** The rarest tier admitted. Default 3: every pair the list holds. */
+    readonly maxTier?: GivenFamilyTier;
+    /**
+     * The families, one `ROOT,FORM:TIER,…` line each, NN3 upper case. Default: the shipped
+     * `given-families.json`. A caller with its own list passes it here.
+     */
+    readonly families?: readonly string[];
+}
+/** A given-name provider over the extended list: `given-maybe` or `null`. */
+export type GivenFamilyList = (a: string, b: string) => "given-maybe" | null;
+/**
+ * The extended list as a `GivenProvider` for `createNameKinship`: `given-maybe` where two
+ * DIFFERENT names (NN3) share a family within `maxTier`, `null` otherwise. Two equal names
+ * answer `null`, as `givenFamilyTable`'s do.
+ *
+ * The list is parsed on the first question, once per provider.
+ */
+export declare function createGivenFamilyList(options?: GivenFamilyListOptions): GivenFamilyList;
+/** The shipped list, every tier: the second given-name provider of `nameKinship`. */
+export declare const givenFamilyList: GivenFamilyList;

package/dist/types/normalize/index.d.ts

@@ -19,6 +19,7 @@ export { TEAM_DESIGNATION_WORDS, TEAM_WORD, type TeamSuffixPartition, canonicalT
 export { foldNameKey, nameFold } from "./name-fold.ts";
 export { COMPOUND_SURNAMES, isCompoundSurname } from "./compound-surnames.ts";
 export { givenFamilyTable, sameGivenFamily } from "./given-diminutives.ts";
+export { type GivenFamilyList, type GivenFamilyListOptions, type GivenFamilyTier, createGivenFamilyList, givenFamilyList, } from "./given-families.ts";
 export { type ClusterLinkage, type Clusters, type NameIndex, type NameIndexOptions, type NameMap, type NameMatch, type NameSet, createNameClusters, createNameIndex, createNameMap, createNameSet, nameCompare, probablySame, } from "./name-compare.ts";
 export { type NameReading, type NameRelation, type NameRelationReason, comparePosition, nameRelation, } from "./name-middle.ts";
 export { type GivenProvider, type GivenVia, KINSHIP_VIAS, type KinshipReason, type KinshipVia, type MiddleVia, type MiddleViasAreNn5Reasons, type NameKinship, type NameKinshipOptions, type NameKinshipRelation, createNameKinship, nameKinship, } from "./name-kinship.ts";

package/dist/types/normalize/name-kinship.d.ts

@@ -32,14 +32,14 @@
  * narrower: every tolerance used is one this package's own gate comparators already admit —
  * a middle name `probablySame(…, "nn5")` admits, a given-name family `sameGivenFamily`
  * admits, a compound the print itself carries. A table form that is a name in its own right
- * (`given-family-not-gate`) or a probabilistic source (`given-maybe`) is a lead for the rest
- * of the evidence and never a gate.
+ * (`given-family-not-gate`) or the extended family list (`given-maybe`) is a lead for the
+ * rest of the evidence and never a gate.
  *
  * ## THE GIVEN-NAME TOLERANCE IS INJECTED
  *
- * Which given names are one family is DATA, and the data will move: a probabilistic source
- * of diminutive pairs is expected beside the curated table, and the table may shrink. So the
- * relation asks an ordered list of `GivenProvider`s fixed by `createNameKinship`'s options,
+ * Which given names are one family is DATA, and the data will move: the curated table
+ * (`given-diminutives.json`) is the gate tier, the extended family list (`given-families.json`)
+ * stands beside it, and either may grow or shrink. So the relation asks an ordered list of `GivenProvider`s fixed by `createNameKinship`'s options,
  * and the core knows no table. A new provider is an option; a new kind of answer is one
  * line in `KINSHIP_VIAS`, which also carries its gate-safety, so no branch here changes.
  *
@@ -79,7 +79,7 @@ export declare const KINSHIP_VIAS: Readonly<{
         field: "given";
         gateSafe: false;
     }>;
-    /** a probabilistic source says the two MAY be one family; reserved for one */
+    /** the extended family list says the two MAY be one family (`./given-families.ts`) */
     readonly "given-maybe": Readonly<{
         field: "given";
         gateSafe: false;
@@ -136,7 +136,8 @@ export type GivenProvider = (a: string, b: string) => GivenVia | null;
 export interface NameKinshipOptions {
     /**
      * The given-name tolerances, asked in order; THE FIRST NON-NULL ANSWER WINS, so a caller
-     * lists its most trusted source first. Default `[givenFamilyTable]`; `[]` tolerates no
+     * lists its most trusted source first. Default `[givenFamilyTable, givenFamilyList]`: the
+     * curated table, then the extended list for what the table does not relate. `[]` tolerates no
      * given name.
      */
     readonly given?: readonly GivenProvider[];
@@ -158,7 +159,10 @@ export type NameKinshipRelation = (a: PersonName, b: PersonName) => NameKinship;
  * | otherwise | `candidate`, via every tolerance used |
  */
 export declare function createNameKinship(options?: NameKinshipOptions): NameKinshipRelation;
-/** The tolerant relation over the curated given-name table, `givenFamilyTable`. */
+/**
+ * The tolerant relation over the curated given-name table, `givenFamilyTable`, then the
+ * extended family list, `givenFamilyList`.
+ */
 export declare const nameKinship: NameKinshipRelation;
 /**
  * THE MIDDLE VIAS ARE NN5'S CANDIDATE REASONS, ASSERTED IN TYPECHECKED SOURCE. A middle

package/docs/NAME-NORMALIZATION.md

@@ -471,7 +471,7 @@ interface NameKinship {
 | `given-variant` | given | yes | the two first given names are two spellings of one name (`Connor` / `Conor`) |
 | `given-family` | given | yes | a provider says the two first given names are one family, and a gate admits them |
 | `given-family-not-gate` | given | no | the table relates them only through a `notAtGate` form |
-| `given-maybe` | given | no | a probabilistic source says they MAY be one family |
+| `given-maybe` | given | no | the extended family list says they MAY be one family |
 | `middle-absent` | middle | yes | NN5's: one side carries no middle |
 | `initial-agrees` | middle | yes | NN5's: an initial against a full middle that starts with it |
 
@@ -486,9 +486,10 @@ interface NameKinship {
 - The given-name tolerance is INJECTED: `createNameKinship({ given: [p1, p2, …] })` asks
   each `GivenProvider` in order and the first non-null answer wins. A provider is asked
   once per pair, with the two NN3 first given names in code-unit order, and never with two
-  equal names. The default is `[givenFamilyTable]`, which answers from
-  `given-diminutives.json`; `sameGivenFamily(a, b)` is exactly "`givenFamilyTable(a, b)` is
-  `given-variant` or `given-family`". `[]` tolerates no given name.
+  equal names. The default is `[givenFamilyTable, givenFamilyList]`: the curated table
+  (`given-diminutives.json`) first, then the extended family list (`given-families.json`) for
+  a pair the table does not relate. `sameGivenFamily(a, b)` is exactly "`givenFamilyTable(a, b)`
+  is `given-variant` or `given-family`". `[]` tolerates no given name.
 - A new kind of `via` is one entry in `KINSHIP_VIAS`, which carries its field and its
   gate-safety. The relation's rules do not change.
 - With no tolerance used, the answer is `nameRelation`'s. `head-differs` is split into
@@ -520,9 +521,37 @@ interface NameKinship {
 `Kate` and `Katie` are Catherine's, and `Katelyn` is a spelling of Caitlin. They meet below
 the gate through Caitlin as a form of Catherine, so `Kate` / `Katherine` keeps its gate.
 
-Over the 421 forms and spellings of the table (88,410 distinct pairs), `givenFamilyTable`
-answers `given-variant` for 90 pairs, `given-family` for 371, `given-family-not-gate` for 553,
-and `null` for the rest; `sameGivenFamily` admits 461.
+Over the 541 roots, forms and spellings of the table (146,070 distinct pairs),
+`givenFamilyTable` answers `given-variant` for 127 pairs, `given-family` for 540,
+`given-family-not-gate` for 725, and `null` for the rest; `sameGivenFamily` admits 667.
+
+### The extended family list
+
+The table is the GATE tier: pairs this package is sure of. `given-families.json` is the
+EXTENDED tier: every family its sources record for English, Irish, Scottish, Welsh, French,
+Italian, Spanish, German, Dutch and Polish usage — 1,171 families over 2,613 names, the table's
+own families and spellings among them. `givenFamilyList(a, b)` answers `given-maybe` where two
+names share a family, and `null` otherwise; no gate admits it.
+
+- One line per family, `ROOT,FORM:TIER,…`, NN3. A TIER says how common the form is: 1 common,
+  2 uncommon, 3 rare. `createGivenFamilyList({ maxTier })` admits pairs up to that tier; a
+  pair's tier is its rarer member's, the root counting as 1, and where two names share several
+  families the commonest counts. The default admits every tier.
+- A family is CLOSED: two forms of one root relate (`Kate` / `Katie`), as well as a root and
+  its form. Nothing is transitive across families: `Kit` meets Catherine's and Christopher's,
+  and `Kate` / `Chris` stay apart.
+- It is an exact list, not a filter. An 8 KB bloom filter of 6,980 such pairs, asked about
+  every pair of the 4,730 given names in the 0.14.0 `names.txt`, answered 50.6 false partners
+  per name; the list is 11.8 KB gzipped and answers none.
+- `given-families.MANIFEST.json` beside it records the sources, their tiers and the names it
+  excludes; `scripts/given-families.ts` rebuilds it from them.
+
+Every name either table holds is in `names.txt` as a given name carrying the `D` mark, and
+only those carry it (`test/golden.spec.ts`). A SURNAME STAYS A SURNAME: a name `names.txt`
+holds only as a surname (an `L` entry, none on its key with `F`, `M`, `N` or `A`) is in neither
+table, and every pair through it goes with it (`Ward:LT`, so `Ward` / `Eduard` is not related).
+A genuine given name is made one in `names.txt` first (`Henry:AMD`, read `L` before), and the
+list rebuilt.
 
 ### The tolerant lookup