@finbheara/names 0.14.0 → 0.16.0

package/README.md

@@ -145,8 +145,10 @@ name cells, one per line. The specification is `docs/NAME-NORMALIZATION.md`.
 ### How two names are related
 
 ```ts
-import { createNameIndex, createNameKinship, givenFamilyTable, nameKinship, personName }
-  from "@finbheara/names/normalize";
+import {
+  createGivenFamilyList, createNameIndex, createNameKinship, givenFamilyTable, nameKinship,
+  personName,
+} from "@finbheara/names/normalize";
 
 nameKinship(personName("Kate Smith"), personName("Katherine Smith"));
 // { relation: "candidate", via: ["given-family"], reason: "middles-equal", gateSafe: true }
@@ -157,13 +159,16 @@ nameKinship(personName("Kate M Smith"), personName("Katherine Conley-Smith")).vi
 nameKinship(personName("Connor Smith"), personName("Conor Smith")).via;       // ["given-variant"]
 nameKinship(personName("Evie Smith"), personName("Genevieve Smith"));
 // { relation: "candidate", via: ["given-family-not-gate"], reason: "middles-equal", gateSafe: false }
+nameKinship(personName("Beth Smith"), personName("Bethany Smith"));   // the extended family list
+// { relation: "candidate", via: ["given-maybe"], reason: "middles-equal", gateSafe: false }
 
 // the given-name tolerance is a list of providers, asked in order
-const withMaybe = createNameKinship({
-  given: [givenFamilyTable, (a, b) => (a === "NAIMH" && b === "NIAMH" ? "given-maybe" : null)],
+const tableOnly = createNameKinship({ given: [givenFamilyTable] });
+tableOnly(personName("Beth Smith"), personName("Bethany Smith")).reason;  // "given-differs"
+const common = createNameKinship({
+  given: [givenFamilyTable, createGivenFamilyList({ maxTier: 1 })],  // common forms only
 });
-withMaybe(personName("Naimh Smith"), personName("Niamh Smith"));
-// { relation: "candidate", via: ["given-maybe"], reason: "middles-equal", gateSafe: false }
+common(personName("Maggie Smith"), personName("Marjorie Smith")).reason;  // "given-differs"
 
 const index = createNameIndex<number>("nn3");   // a NameMap with a tolerant lookup
 index.set(personName("Mary Conley-Larson"), 1).set(personName("Mary Carlson"), 2);
@@ -242,6 +247,7 @@ given name. Flags are case-sensitive and combine (`Kelly:AF`, `New York:BG`).
 | `B` | multi-word entry (bigram or trigram) |
 | `S` | a known typo, kept so it is recognised |
 | `X` | excluded from the display renderer's round-trip check |
+| `D` | a given name a diminutive table holds (`Kate:FD`); a mark, like `S` and `X` |
 
 A digit after `L` or `A` is a **tradition footnote**: `1` Armenian, `2` Germanic,
 `3` Iberian, `4` Irish/Gaelic, `5` Nordic, `6` Slavic (`Kowalski:L6`). An index is

package/data/bloom/MANIFEST.json

@@ -1,40 +1,86 @@
 {
-	"about": "Bloom filters the phrase classifier consults. Each table: s = bits, h = hashes, d = seed, c = base64 bit content, n = items. Keys are lower-cased, accent-stripped, apostrophe-free. Built 2026-01-03, target false-positive rate 0.01. A table holds hashes of its source list, not the list; sources are recorded for rebuilding.",
+	"about": "Bloom filters the phrase classifier consults. Each table: s = bits, h = hashes, d = seed, c = base64 bit content, n = items. A table holds hashes of its source lists, not the lists; the lists are third-party files, recorded here for rebuilding. The four name tables are rebuilt by scripts/build-blooms.ts from the files named in their inputs; locations, us-locations and schools were built 2026-01-03 by a process that is not recorded, and are not rebuilt.",
+	"build": {
+		"script": "scripts/build-blooms.ts <source-dir> [--check]",
+		"seed": 78187493520,
+		"fpp": 0.01,
+		"sizing": "BloomFilter.create(n, fpp) from bloom-filters: s = ceil(-n ln(fpp) / ln(2)^2), h = ceil(s/n ln 2); n is the number of distinct keys",
+		"key": "normalize() in src/classifier/bf/filters.ts: lower-case, NFD, combining marks U+0300-U+036F removed, the ASCII apostrophe removed (U+2019 is kept). An empty key is dropped; a key repeated within or across inputs counts once",
+		"read": "a leading U+FEFF is stripped; lines split on LF or CRLF; format csv takes cell `column` after splitting the line on every comma (no quoting); header: the first line is skipped; trim: surrounding whitespace is removed before the key is taken"
+	},
 	"tables": {
 		"surnames.json": {
 			"items": 151671,
-			"source": "FiveThirtyEight most-common-name (surnames)",
-			"url": "https://github.com/fivethirtyeight/data/tree/master/most-common-name"
+			"inputs": [
+				{
+					"file": "most-common-name_surnames.csv",
+					"format": "csv",
+					"column": 0,
+					"header": true,
+					"source": "FiveThirtyEight most-common-name (surnames)",
+					"url": "https://github.com/fivethirtyeight/data/tree/master/most-common-name"
+				}
+			]
 		},
 		"human-names.json": {
 			"items": 197226,
-			"source": "human-names-list.txt (upstream not recorded)",
-			"url": null
+			"inputs": [
+				{
+					"file": "human-names-list.txt",
+					"format": "lines",
+					"source": "human-names-list.txt (upstream not recorded)",
+					"url": null
+				}
+			]
 		},
 		"first-names.json": {
-			"items": 133749,
-			"source": "name_gender_dataset.csv (upstream not recorded)",
-			"url": null
+			"items": 134399,
+			"inputs": [
+				{
+					"file": "name_gender_dataset.csv",
+					"format": "csv",
+					"column": 0,
+					"header": true,
+					"source": "Gender by Name, UCI Machine Learning Repository dataset 591 (doi:10.24432/C55G7X), CC BY 4.0; the file inside gender+by+name.zip",
+					"url": "https://archive.ics.uci.edu/dataset/591/gender+by+name"
+				},
+				{
+					"file": "diminutive-names.txt",
+					"format": "lines",
+					"source": "given-name diminutives and familiar forms, 3,511 spellings as printed, one per line, merged from: this package's given-diminutive table; diminutives.db (data public domain) at commit caae757f1f91bce2175a49942a6c466846ade50c; Behind the Name names tagged \"diminutives\", fetched 2026-10-05; the familiar-form pairs mined in this repository's issue #59. Non-western names are kept: the table answers only whether a word is a given name",
+					"url": null
+				}
+			]
 		},
 		"irish-surnames.json": {
 			"items": 1624,
-			"source": "Gaois sloinnte (Irish surnames database)",
-			"url": "https://github.com/gaois/sloinnte"
+			"inputs": [
+				{
+					"file": "irish_surnames.txt",
+					"format": "lines",
+					"trim": true,
+					"source": "Gaois sloinnte (Irish surnames database)",
+					"url": "https://github.com/gaois/sloinnte"
+				}
+			]
 		},
 		"locations.json": {
 			"items": 8527,
 			"source": "ISO 3166-1 and 3166-2; UN population centres; Wikipedia US cities; urban areas; FIPS; names.txt G entries; common Irish/UK/AU/NZ terms",
-			"url": null
+			"url": null,
+			"rebuild": "not reproducible: most of its source lists and its key rules are not recorded. Checked 2026-10-06: country names, official names and ISO alpha-2/alpha-3 codes from a public country list (geo_country.csv) are held (249/250, 248/250, 241/243, 242/243 distinct keys), but these are a small part of 8,527 keys"
 		},
 		"us-locations.json": {
 			"items": 23922,
 			"source": "CDC PLACES county and place data; US states and territories; common US regions",
-			"url": "https://www.cdc.gov/places/"
+			"url": "https://www.cdc.gov/places/",
+			"rebuild": "not reproducible: the states, territories and regions lists are not recorded. Checked 2026-10-06 against PLACES__County_Data__GIS_Friendly_Format___2020_release.csv and PLACES__Place_Data__GIS_Friendly_Format___2025_release.csv: every distinct key is held (1,839 county names, the same with ' County', 19,837 place names (LocationName), 51 state names, 51 state abbreviations), together 22,347 of the table's 23,922 keys; the other 1,575 are unaccounted for"
 		},
 		"schools.json": {
 			"items": 17342,
 			"source": "Irish dance school names: a curated school list and the school cells of a results corpus",
-			"url": null
+			"url": null,
+			"rebuild": "not reproducible: the sources are not public"
 		}
 	}
 }