@finbheara/names 0.13.0 → 0.14.0

package/dist/cli/census.js

@@ -2,8 +2,8 @@
 import"../chunks/index-7vvt5hhy.js";
 import {
   createNameCensus2
-} from "../chunks/index-ztpxgcs1.js";
-import"../chunks/index-yf904dam.js";
+} from "../chunks/index-a15g2gp6.js";
+import"../chunks/index-ka8nzreg.js";
 import { createRequire } from "node:module";
 var __require = /* @__PURE__ */ createRequire(import.meta.url);
 

package/dist/index.js

@@ -90,7 +90,7 @@ import {
   readNameCell2,
   DEFAULT_NAME_FORMAT_THRESHOLD2,
   deriveNameFormat2
-} from "./chunks/index-wq6kn9jq.js";
+} from "./chunks/index-kw69ry3j.js";
 import"./chunks/index-qsznkk4s.js";
 import {
   composeEvalSet2,
@@ -102,7 +102,7 @@ import {
 } from "./chunks/index-ebebeamh.js";
 import {
   createNameCensus2
-} from "./chunks/index-ztpxgcs1.js";
+} from "./chunks/index-a15g2gp6.js";
 import {
   NAME_REFUSED2,
   stripEveryAside2,
@@ -147,7 +147,7 @@ import {
   defaultPersonNameFactory2,
   personName2,
   personNameFromIcao2
-} from "./chunks/index-yf904dam.js";
+} from "./chunks/index-ka8nzreg.js";
 import {
   TEAM_WORD2,
   TEAM_DESIGNATION_WORDS2,

package/dist/measure/index.js

@@ -4,8 +4,8 @@ import {
 } from "../chunks/index-pncn9y2r.js";
 import {
   createNameCensus2
-} from "../chunks/index-ztpxgcs1.js";
-import"../chunks/index-yf904dam.js";
+} from "../chunks/index-a15g2gp6.js";
+import"../chunks/index-ka8nzreg.js";
 import"../chunks/index-7vvt5hhy.js";
 export {
   composeEvalSet2 as composeEvalSet,

package/dist/normalize/index.js

@@ -49,7 +49,7 @@ import {
   readNameCell2,
   DEFAULT_NAME_FORMAT_THRESHOLD2,
   deriveNameFormat2
-} from "../chunks/index-wq6kn9jq.js";
+} from "../chunks/index-kw69ry3j.js";
 import"../chunks/index-kw6gbrnq.js";
 import {
   NAME_REFUSED2,
@@ -95,7 +95,7 @@ import {
   defaultPersonNameFactory2,
   personName2,
   personNameFromIcao2
-} from "../chunks/index-yf904dam.js";
+} from "../chunks/index-ka8nzreg.js";
 import {
   TEAM_WORD2,
   TEAM_DESIGNATION_WORDS2,

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

@@ -14,31 +14,42 @@
  * root never leaves this module: `sameGivenFamily` and `givenFamilyTable` answer about a
  * pair and neither returns a root, for that reason.
  *
- * THE GATE READS LESS THAN THE LANE. `families` is the Python lane's table, first root
- * wins, and the lane reads every form in it as evidence below an exact match. A GATE that
- * admits a pair is a stronger claim than a comparison level, so `sameGivenFamily` refuses
- * any pair through a form in `notAtGate`: a name in its own right (`Megan`, `Grace`), a
- * translation (`Sean`, `Padraig`) or another gender's name (`Michelle`, `Patricia`).
- * `Tom` and `Thomas`, `Jenny` and `Jennifer`, `Annie` and `Ann` meet; `Sean` and `John` do
- * not.
+ * SPELLINGS, FAMILIES AND THE GATE. Two different given names are related in one of three
+ * ways, and the answer says which:
+ *
+ *   - `given-variant`: two spellings of one name (`Connor` / `Conor`, `Sara` / `Sarah`). A
+ *     spelling is not a familiar form, so `variants` is its own table, and a gate admits it.
+ *   - `given-family`: after each spelling is read as its canonical, the two share a ROOT of
+ *     `families` (`Tom` / `Thomas`, `Kate` / `Katherine`), and a gate admits it.
+ *   - `given-family-not-gate`: they share a root, but only through a `notAtGate` form: a name in
+ *     its own right (`Megan`, `Grace`), a translation (`Sean`, `Padraig`), another gender's
+ *     name (`Michelle`, `Sam`) or a form of more than one root (`Ellie`, `Evie`). The lane
+ *     reads it as evidence below an exact match; a gate refuses it.
+ *
+ * EVERY ROOT, NEVER THE FIRST. A form under several roots meets each of them (`Evie` is
+ * Evelyn's, Genevieve's, Eve's and Eva's), and every such form is `notAtGate`, because the
+ * form alone cannot say which root its bearer carries. Sharing a root is not transitive:
+ * `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.
  */
 /**
  * Do two DIFFERENT given names (NN3, letters only) stand for one another at a gate?
  *
- * True exactly when both are in the table, share a root, and neither is a `notAtGate`
- * form. Two equal names answer `false`: equality is the caller's own test and this is the
- * tolerance past it, so a caller can tell which one admitted a pair.
+ * True exactly when `givenFamilyTable` relates them by a gate-safe answer: two spellings of
+ * one name, or one family through no `notAtGate` form. Two equal names answer `false`:
+ * equality is the caller's own test and this is the tolerance past it, so a caller can tell
+ * which one admitted a pair.
  */
 export declare function sameGivenFamily(a: string, b: string): boolean;
 /**
  * What the table says about two DIFFERENT given names (NN3, letters only), as a kinship
- * `via`: `given-family` where `sameGivenFamily` admits the pair, `given-family-not-gate`
- * where the two share a root but either is a `notAtGate` form, and `null` where the table
- * does not relate them. Two equal names answer `null`, for `sameGivenFamily`'s reason.
+ * `via`: `given-variant` for two spellings of one name, `given-family` where the two share a
+ * root and a gate admits the pair, `given-family-not-gate` where every root they share is
+ * reached through a `notAtGate` form, and `null` where the table does not relate them. Two
+ * equal names answer `null`, for `sameGivenFamily`'s reason.
  *
- * THE DEFAULT GIVEN-NAME PROVIDER of `createNameKinship` (`./name-kinship.ts`). It reads the
- * `ROOT` and `NOT_AT_GATE` that `sameGivenFamily` reads, and `sameGivenFamily` is defined as
- * its `given-family` answer, so the gate and the tolerant relation cannot disagree about a
- * pair.
+ * THE DEFAULT GIVEN-NAME PROVIDER of `createNameKinship` (`./name-kinship.ts`).
+ * `sameGivenFamily` is defined as its gate-safe answers, so the gate and the tolerant relation
+ * cannot disagree about a pair.
  */
-export declare function givenFamilyTable(a: string, b: string): "given-family" | "given-family-not-gate" | null;
+export declare function givenFamilyTable(a: string, b: string): "given-variant" | "given-family" | "given-family-not-gate" | null;

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

@@ -14,6 +14,7 @@
  * caller decides how much to accept:
  *
  *     Kate Smith    / Katherine Smith      candidate  via [given-family]
+ *     Connor Smith  / Conor Smith          candidate  via [given-variant]
  *     Mary Larson   / Mary Conley-Larson   candidate  via [surname-part]
  *     Kate M Smith  / Katherine Conley-Smith
  *                                           candidate  via [surname-part, given-family, middle-absent]
@@ -63,6 +64,11 @@ export declare const KINSHIP_VIAS: Readonly<{
         field: "surname";
         gateSafe: true;
     }>;
+    /** the two first given names are two spellings of one name (`Connor` / `Conor`) */
+    readonly "given-variant": Readonly<{
+        field: "given";
+        gateSafe: true;
+    }>;
     /** the given-name table relates the two first given names, and the gate admits them */
     readonly "given-family": Readonly<{
         field: "given";

package/docs/NAME-NORMALIZATION.md

@@ -468,8 +468,9 @@ interface NameKinship {
 | via | field | gate-safe | when |
 |---|---|---|---|
 | `surname-part` | surname | yes | one surname is a whole hyphen- or space-joined part of the other's compound |
+| `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 through a `notAtGate` form |
+| `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 |
 | `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,8 +487,8 @@ interface NameKinship {
   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) === "given-family"`. `[]` tolerates no given name.
+  `given-diminutives.json`; `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
@@ -495,9 +496,33 @@ interface NameKinship {
   suffix and middle rows are NN5's (`tailRelation`) and still veto.
 - A print that names no person is `different` from everything, itself included.
 
-Over the 261 forms of the current table (33,930 distinct pairs), `givenFamilyTable` answers
-`given-family` for 354 pairs, `given-family-not-gate` for 302, and `null` for the rest.
-`sameGivenFamily` answers as it did before the provider existed on every one of them.
+### The given-name table
+
+`given-diminutives.json` holds three things, each in NN3 upper case:
+
+- `variants`: one name's SPELLINGS, canonical first (`CONNOR` / `CONOR`, `SARAH` / `SARA`,
+  `MEGAN` / `MEGHAN` / `MEAGAN` / `MEAGHAN`). Two spellings are `given-variant`, and a gate
+  admits them. A spelling is read as its canonical before `families` is consulted, so
+  `Cate` meets `Katherine` as `Kate` does. A transposition or a typo (`Oliva`, `Cailtin`,
+  `Naimh`) is NOT a variant: a misprint tolerance is a separate provider.
+- `families`: root -> its familiar forms. Two names are one family when they SHARE A ROOT,
+  a root belonging to itself. A form may sit under several roots and meets EVERY one of
+  them: `Evie` is Evelyn's, Genevieve's, Eve's, Eva's and Evangeline's. Sharing a root is
+  not transitive, so `Eve` and `Eva` stay apart though `Evie` meets both.
+- `notAtGate`: forms a gate refuses — a name in its own right (`Josie`, `Gracie`, `Lily`),
+  a translation (`Sean`), another gender's name (`Sam`, `Charlie`, `Frankie`), and every
+  form under more than one root (`Ellie`, `Maddie`, `Ally`, `Kit`), because the form alone
+  cannot say which root its bearer carries. A pair through such a form is
+  `given-family-not-gate`. The flag refuses a name AS A FORM: where it is the root itself,
+  its own forms still meet it at a gate (`Caitlin` is Catherine's Irish form, refused
+  against `Katherine`, and still meets `Cait`).
+
+`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.
 
 ### The tolerant lookup
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@finbheara/names",
-	"version": "0.13.0",
+	"version": "0.14.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",