@finbheara/domain 0.9.0 → 0.11.0

package/README.md

@@ -43,6 +43,7 @@ ESM, Node ≥ 22 or Bun ≥ 1.4.2. MIT. Not affiliated with or endorsed by any d
 | `@finbheara/domain/noun-index` | `createIndex`, `indexSchema`, `personEncoder`, and the `SqlHandle`/`NounEncoder` types: a database-backed name map (below) |
 | `@finbheara/domain/dance-types` | `danceTypes()`, `DANCE_TYPES`, `rhythmOfTime`, and the shared `DanceMatch`/`DanceRelation`/`SetRhythm`/`TimeSignature` types |
 | `@finbheara/domain/promotion` | `samePromotedRow`, `samePromotedSchool`, `samePromotedHeir`, `samePromotedName`, `questionMarksRead`, `foldCharSynonyms`: is a row the same row after a promotion (below) |
+| `@finbheara/domain/person` | `seatName`, `dancerName`, `teacherName`, `roleName`, `roleSentinelOf`, the role lists and `SHARED_ROW_SENTINELS`: a person's print read in its role (below) |
 
 The library does no I/O and installs nothing process-wide. Every reader has a default and a
 factory: build your own with options when the default is not what you want.
@@ -457,6 +458,31 @@ Anything else is another row: a different surname or given name, one letter prin
 another, a `?` over an ASCII letter, a school that differs anywhere but a trailing `: location`.
 The caller pairs the card; nothing here reads an address.
 
+## Read a person's print in its role
+
+A person is printed in a role: an adjudicator's seat on a panel sheet, a dancer's name cell, a
+teacher in a school's listing. Each role prints its own sentinels where no one is named, and a
+person-name reader cannot anticipate them. Each role here has its own not-a-name list, asked
+FIRST; a print on no list is handed to `@finbheara/names` unchanged.
+
+```ts
+import { dancerName, seatName, teacherName } from "@finbheara/domain/person";
+
+seatName("Withdrawn Adjudicator").isPerson();        // false: the seat's own sentinel
+dancerName("Withdrawn Adjudicator").isPerson();      // true: no dancer list holds it
+dancerName("Test Dancer", "given-first").isPerson(); // false: the dancer's own sentinel
+teacherName("N/A").printsNoName();                   // true: a shared row sentinel
+seatName("Aoife Mhaolvarna").nn2;                    // "Mhaolvarna<<Aoife": names' own parse
+```
+
+- **A refused print is still a `PersonName`**: `isPerson()` is false, `printsNoName()` is true,
+  `refusal.rule` is `"placeholder"`, the print levels keep the print, and every level from NN2
+  down is names' refused value. Ask the type, never the string.
+- **One shared list** (`SHARED_ROW_SENTINELS`: `N/A`, `TBA`, `Unknown`) opens every role's list
+  and the school cell's (`SCHOOL_CELL_SENTINELS` on `/school`, asked by the school reader before
+  its own register), so a sentinel a whole row prints has one definition.
+- Each row is the folded print (`foldNameKey`), what it stands for, and where it was seen.
+
 ## Known gaps
 
 - `place()` reads `"Derry in Ireland"` and `"Calgary in Western Canada"` as `unread`: it does

package/dist/chunks/place-tcgfvemw.js

@@ -0,0 +1,30 @@
+import { foldNameKey } from "@finbheara/names/normalize";
+var SHARED_ROW_SENTINELS2 = [
+  {
+    print: "n a",
+    authority: "`#N/A`, a spreadsheet's missing-value mark: 66 name cells and 66 school cells of one transcribed sheet set"
+  },
+  {
+    print: "tba",
+    authority: "`TBA`: 1 name cell and 1 school cell"
+  },
+  {
+    print: "unknown",
+    authority: "`Unknown`, `unknown`, `*Unknown*`: 4 name cells and 186 school cells"
+  }
+];
+function sentinelIn2(list) {
+  const exact = new Map;
+  for (const row of list)
+    if (row.match === undefined && !exact.has(row.print))
+      exact.set(row.print, row);
+  const prefix = list.filter((row) => row.match === "prefix");
+  return (print) => {
+    const folded = foldNameKey(print);
+    if (folded === "")
+      return;
+    return exact.get(folded) ?? prefix.find((row) => folded === row.print || folded.startsWith(`${row.print} `));
+  };
+}
+
+export { SHARED_ROW_SENTINELS2, sentinelIn2 };

package/dist/chunks/{place-h7tvdfyp.js → place-tv86hmps.js}

@@ -199,14 +199,16 @@ var PLACE_NODES = [
     geo: "USA",
     admin: "IDTANA",
     prints: [
+      "idtama",
       "lar mheiricea",
       "mid america",
       "mid america region",
       "mid america region usa",
+      "mid american region",
       "reigiun lar meiricea",
       "usa mid america region"
     ],
-    codes: ["MAO"],
+    codes: ["IDTAMA", "MAO"],
     truncations: ["mid am"],
     oireachtas: "MAO"
   },
@@ -243,6 +245,7 @@ var PLACE_NODES = [
     geo: "USA",
     admin: "IDTANA",
     prints: [
+      "idtana sr",
       "reigiun an deiscirt",
       "s usa",
       "so usa",
@@ -4994,6 +4997,15 @@ var PLACE_NODES = [
     prints: ["essex"],
     codes: []
   },
+  {
+    id: "GBR-ENG/surrey",
+    kind: "city",
+    name: "Surrey",
+    geo: "GBR-ENG",
+    admin: "ENG_SOUTH",
+    prints: ["surrey"],
+    codes: []
+  },
   {
     id: "GBR-ENG/leeds",
     kind: "city",
@@ -6800,7 +6812,7 @@ function createPlaceReader2(options = {}) {
     return s.normalize("NFD").replace(/\p{M}+/gu, "").toLowerCase().replace(/[^\p{L}\p{N}]+/gu, " ").trim();
   }
   function repair(print) {
-    const s = print.normalize("NFC").replace(/\s+/g, " ").trim();
+    const s = print.normalize("NFC").replace(/\p{Cf}+/gu, "").replace(/\p{Cc}+/gu, " ").replace(/\s+/g, " ").trim();
     const opens = (s.match(/[([{]/g) ?? []).length;
     const closes = (s.match(/[)\]}]/g) ?? []).length;
     if (opens === closes)
@@ -7407,6 +7419,41 @@ function createPlaceReader2(options = {}) {
     const found = (idx().byRunPrint.get(fold(piece)) ?? []).filter((n) => subs.some((s) => n.id !== s.id && isAncestor(s, n)));
     return found.length === 1 ? found[0] : undefined;
   }
+  function continentOf(n) {
+    const seen = new Set;
+    for (let at = n;at !== undefined && !seen.has(at.id); ) {
+      if (at.kind === "continent")
+        return at;
+      seen.add(at.id);
+      at = at.geo === null ? undefined : idx().byId.get(at.geo);
+    }
+    return;
+  }
+  const POSTAL_COUNTRIES = new Set(["USA", "CAN"]);
+  function qualifierAlone(left, right) {
+    if (left.length === 0 || right.length === 0)
+      return;
+    if (left.some((l) => right.some((r) => relates(l, r))))
+      return;
+    const postal = right.filter((r) => r.kind === "subdivision" && POSTAL_COUNTRIES.has(countryOf(r)?.id ?? ""));
+    if (postal.length > 0) {
+      const theirs = new Set(postal.map((r) => countryOf(r)?.id));
+      const fits = left.every((l) => l.kind === "city" || (l.kind === "country" || l.kind === "subdivision") && !theirs.has(countryOf(l)?.id));
+      return fits ? postal : undefined;
+    }
+    if (!right.every((r) => r.kind === "country" || r.kind === "subdivision"))
+      return;
+    const continents = new Set(right.map((r) => continentOf(r)?.id));
+    if (continents.has(undefined))
+      return;
+    const abroad = left.every((l) => {
+      if (l.kind !== "city")
+        return false;
+      const c = continentOf(l)?.id;
+      return c !== undefined && !continents.has(c);
+    });
+    return abroad ? right : undefined;
+  }
   function read(print, declared = false, smushed = true) {
     const core = unbracket(repair(print));
     if (fold(core) === "")
@@ -7432,6 +7479,7 @@ function createPlaceReader2(options = {}) {
     const seen = new Set;
     for (const split of subsets) {
       const parts = [];
+      const before = [null];
       let space = tokens[0] ?? "";
       let conj = space;
       for (let i = 0;i < seps.length; i++) {
@@ -7439,6 +7487,7 @@ function createPlaceReader2(options = {}) {
         const next = tokens[i + 1] ?? "";
         if (split.includes(k)) {
           parts.push({ space, conj });
+          before.push(k);
           space = next;
           conj = next;
         } else {
@@ -7466,6 +7515,21 @@ function createPlaceReader2(options = {}) {
             refusal: null
           };
       }
+      const qualified = (k) => k === "comma" || k === "space";
+      const settled = reads.map((r, n) => {
+        const prev = reads[n - 1];
+        if (prev === undefined || !qualified(before[n]) || r.truncated)
+          return;
+        if (n - 1 > 0 && (qualified(before[n - 1]) || !qualified(before[n - 2])))
+          return;
+        return qualifierAlone(prev.heads, r.heads);
+      });
+      settled.forEach((heads, n) => {
+        if (heads === undefined)
+          return;
+        reads[n - 1] = { ...reads[n - 1], heads };
+        reads[n] = { ...reads[n], heads };
+      });
       if (reads.some((r) => r.heads.length === 0 || r.refusal !== null))
         continue;
       const together = combine(reads);

package/dist/person.js

@@ -0,0 +1,128 @@
+import {
+  SHARED_ROW_SENTINELS2,
+  sentinelIn2
+} from "./chunks/place-tcgfvemw.js";
+
+import {
+  NAME_REFUSED,
+  personName
+} from "@finbheara/names/normalize";
+var ADJUDICATOR_SENTINELS = [
+  {
+    print: "withdrawn adjudicator",
+    authority: "`Withdrawn Adjudicator`: 180 seat cells, one panel sheet's empty seat"
+  },
+  {
+    print: "no school judge",
+    authority: "`No School Judge`: an entry form's option for an adjudicator's entry"
+  }
+];
+var DANCER_SENTINELS = [
+  {
+    print: "name withheld",
+    authority: "`Name Withheld`: 136 name cells, the entry platform printed that the name was withheld"
+  },
+  {
+    print: "test dancer",
+    authority: "`Test Dancer`: 7 name cells, an entry platform's test entry"
+  },
+  {
+    print: "none none",
+    authority: "`none none`: 4 name cells, the sentinel `none` typed into both name fields"
+  },
+  {
+    print: "not known",
+    authority: "`Not known`: 1 name cell"
+  },
+  {
+    print: "don t know",
+    authority: "`Don't Know`: 1 name cell"
+  }
+];
+var TEACHER_SENTINELS = [];
+var ROLE_SENTINELS = {
+  adjudicator: [...SHARED_ROW_SENTINELS2, ...ADJUDICATOR_SENTINELS],
+  dancer: [...SHARED_ROW_SENTINELS2, ...DANCER_SENTINELS],
+  teacher: [...SHARED_ROW_SENTINELS2, ...TEACHER_SENTINELS]
+};
+var MATCHERS = {
+  adjudicator: sentinelIn2(ROLE_SENTINELS.adjudicator),
+  dancer: sentinelIn2(ROLE_SENTINELS.dancer),
+  teacher: sentinelIn2(ROLE_SENTINELS.teacher)
+};
+function roleSentinelOf(role, print) {
+  return MATCHERS[role](print);
+}
+var NO_PART = Object.freeze({ particles: [], base: "", parts: [], tradition: null });
+
+class RoleRefusedName {
+  [Symbol.toStringTag] = "PersonName";
+  nn0;
+  nn1;
+  nn2 = NAME_REFUSED;
+  nn3 = NAME_REFUSED;
+  nn4 = NAME_REFUSED;
+  surname = NO_PART;
+  given = [];
+  suffixes = [];
+  refusal;
+  verdict;
+  role;
+  sentinel;
+  constructor(read, role, sentinel) {
+    this.role = role;
+    this.sentinel = sentinel;
+    this.nn0 = read.nn0;
+    this.nn1 = read.nn1;
+    this.refusal = { rule: "placeholder", printed: read.nn0, value: NAME_REFUSED };
+    this.verdict = { kind: "refused", refusal: this.refusal, rules: read.verdict.rules };
+  }
+  toString() {
+    return this.nn2;
+  }
+  get length() {
+    return this.nn2.length;
+  }
+  surnameKey() {
+    return "";
+  }
+  givenFields() {
+    return [];
+  }
+  givenName() {
+    return "";
+  }
+  isTeam() {
+    return false;
+  }
+  isPerson() {
+    return false;
+  }
+  isEmpty() {
+    return false;
+  }
+  printsNoName() {
+    return true;
+  }
+}
+function roleName(role, print, order) {
+  const read = personName(print, order);
+  const sentinel = MATCHERS[role](print);
+  return sentinel === undefined ? read : new RoleRefusedName(read, role, sentinel);
+}
+var seatName = (print) => roleName("adjudicator", print, "given-first");
+var dancerName = (print, order) => roleName("dancer", print, order);
+var teacherName = (print, order) => roleName("teacher", print, order);
+export {
+  ADJUDICATOR_SENTINELS,
+  DANCER_SENTINELS,
+  ROLE_SENTINELS,
+  SHARED_ROW_SENTINELS2 as SHARED_ROW_SENTINELS,
+  TEACHER_SENTINELS,
+  dancerName,
+  roleName,
+  roleSentinelOf,
+  seatName,
+  sentinelIn2 as sentinelIn,
+  teacherName
+};

package/dist/place.js

@@ -15,7 +15,7 @@ import {
   placesRelation2,
   probablySamePlace2,
   sameReading2
-} from "./chunks/place-h7tvdfyp.js";
+} from "./chunks/place-tv86hmps.js";
 export {
   DEFAULT_PLACE_CAPACITY2 as DEFAULT_PLACE_CAPACITY,
   DEFAULT_PLACE_READER2 as DEFAULT_PLACE_READER,

package/dist/school.js

@@ -8,16 +8,41 @@ import {
   areAllPlaceTokens2,
   placeRelation2,
   sameReading2
-} from "./chunks/place-h7tvdfyp.js";
+} from "./chunks/place-tv86hmps.js";
+import {
+  SHARED_ROW_SENTINELS2,
+  sentinelIn2
+} from "./chunks/place-tcgfvemw.js";
 import {
   validity
 } from "./chunks/place-q9kwsmzd.js";
 
-import { normalizeApostrophes } from "@finbheara/names/lexicon";
+import { normalizeApostrophes as normalizeApostrophes2 } from "@finbheara/names/lexicon";
 import { SURNAME_SEPARATOR, lexiconKey, titleCaseNamePart } from "@finbheara/names/normalize";
 import { personName } from "@finbheara/names/normalize";
 
 import { placeholderOf } from "@finbheara/names/normalize";
+
+var SCHOOL_CELL_OWN_SENTINELS = [
+  {
+    print: "no school",
+    authority: "`No School`: 76 school cells, the dancer entered with no school"
+  },
+  {
+    print: "independent",
+    authority: "`Independent`, `independent`, `Independent?`: 5 school cells, no school by the dancer's own description"
+  },
+  {
+    print: "independent dancer",
+    authority: "`Independent Dancer`, `Independent dancer`, `Independent Dancer?`: 8 school cells"
+  }
+];
+var SCHOOL_CELL_SENTINELS = [
+  ...SHARED_ROW_SENTINELS2,
+  ...SCHOOL_CELL_OWN_SENTINELS
+];
+var schoolCellSentinelOf = sentinelIn2(SCHOOL_CELL_SENTINELS);
+
 var SCHOOL_NAME_EXCEPTIONS = [
   {
     phrase: "the academy",
@@ -257,7 +282,7 @@ function notASchoolIn(rows) {
     const text = normalizeForRefusal(print);
     if (text === "")
       return;
-    const placeholder = placeholderOf(text);
+    const placeholder = schoolCellSentinelOf(text) ?? placeholderOf(text);
     if (placeholder !== undefined)
       return placeholderRow(placeholder);
     for (const row of rows) {
@@ -873,6 +898,7 @@ function truncatedInstitution(tail) {
   return found;
 }
 
+import { normalizeApostrophes } from "@finbheara/names/lexicon";
 var SCHOOL_FLUFF_WORDS = new Set([
   "academy",
   "irish",
@@ -929,12 +955,11 @@ function isDiscardedAnyway(token) {
 function distinctiveTokens(tokens) {
   return tokens.filter((t) => t.length > 2 && !SCHOOL_FLUFF_WORDS.has(t));
 }
-var APOSTROPHE_VARIANTS = /['`´‘’“”’]/g;
 function foldSchoolName(raw) {
   let s = raw.toLowerCase();
   s = s.normalize("NFD").replace(/[̀-ͯ]/g, "");
   s = s.replace(/ß/g, "ss").replace(/æ/g, "ae").replace(/œ/g, "oe").replace(/ø/g, "o");
-  s = s.replace(APOSTROPHE_VARIANTS, "'");
+  s = normalizeApostrophes(s);
   s = s.replace(/'/g, "");
   const words = [];
   for (const word of s.split(/[^a-z0-9]+/)) {
@@ -1057,7 +1082,7 @@ function createSchoolNameReader(options = {}) {
     return print.replace(SPACING_ACUTE_AFTER_VOWEL, "$1́").replace(SPACING_ACUTE, "'");
   }
   function renderSn1(print) {
-    return normalizeApostrophes(readSpacingAcute(repairMojibake(print)).normalize("NFKC")).replace(/\p{Cf}+/gu, "").replace(/\p{Cc}+/gu, " ").replace(/\s+/gu, " ").trim();
+    return normalizeApostrophes2(readSpacingAcute(repairMojibake(print)).normalize("NFKC")).replace(/\p{Cf}+/gu, "").replace(/\p{Cc}+/gu, " ").replace(/\s+/gu, " ").trim();
   }
   const COMPOUND_OPENERS = new Set([
     "hyphen",
@@ -2137,8 +2162,11 @@ export {
   DEFAULT_SCHOOL_NAME_CAPACITY,
   DEFAULT_SCHOOL_NAME_READER,
   NOT_A_SCHOOL,
+  SCHOOL_CELL_OWN_SENTINELS,
+  SCHOOL_CELL_SENTINELS,
   SCHOOL_LEVEL_COLUMNS,
   SCHOOL_NAME_EXCEPTIONS,
+  SHARED_ROW_SENTINELS2 as SHARED_ROW_SENTINELS,
   compareSchoolNames,
   compareSchools,
   createSchoolNameReader,
@@ -2152,6 +2180,7 @@ export {
   realWords,
   realWordsInPrintOrder,
   sameInEveryPart,
+  schoolCellSentinelOf,
   schoolColumns,
   schoolCompare,
   schoolEncoder,

package/dist/types/person.d.ts

@@ -0,0 +1,14 @@
+import { type ParseOrder, type PersonName } from "@finbheara/names/normalize";
+import { type RowSentinel } from "./row-sentinels.ts";
+export { SHARED_ROW_SENTINELS, sentinelIn } from "./row-sentinels.ts";
+export type { RowSentinel } from "./row-sentinels.ts";
+export type PersonRole = "adjudicator" | "dancer" | "teacher";
+export declare const ADJUDICATOR_SENTINELS: readonly RowSentinel[];
+export declare const DANCER_SENTINELS: readonly RowSentinel[];
+export declare const TEACHER_SENTINELS: readonly RowSentinel[];
+export declare const ROLE_SENTINELS: Readonly<Record<PersonRole, readonly RowSentinel[]>>;
+export declare function roleSentinelOf(role: PersonRole, print: string): RowSentinel | undefined;
+export declare function roleName(role: PersonRole, print: string, order?: ParseOrder): PersonName;
+export declare const seatName: (print: string) => PersonName;
+export declare const dancerName: (print: string, order?: ParseOrder) => PersonName;
+export declare const teacherName: (print: string, order?: ParseOrder) => PersonName;

package/dist/types/row-sentinels.d.ts

@@ -0,0 +1,4 @@
+import { type NamePlaceholder } from "@finbheara/names/normalize";
+export type RowSentinel = NamePlaceholder;
+export declare const SHARED_ROW_SENTINELS: readonly RowSentinel[];
+export declare function sentinelIn(list: readonly RowSentinel[]): (print: string) => RowSentinel | undefined;

package/dist/types/school-cell-sentinels.d.ts

@@ -0,0 +1,4 @@
+import { type RowSentinel } from "./row-sentinels.ts";
+export declare const SCHOOL_CELL_OWN_SENTINELS: readonly RowSentinel[];
+export declare const SCHOOL_CELL_SENTINELS: readonly RowSentinel[];
+export declare const schoolCellSentinelOf: (print: string) => RowSentinel | undefined;

package/dist/types/school.d.ts

@@ -8,5 +8,8 @@ export { compareSchoolNames, compareSchools } from "./school-identity.ts";
 export type { IdentityResult, IdentityVerdict } from "./school-identity.ts";
 export { foldSchoolName, hasSpecificToken, schoolKeyTokens } from "./school-match-key.ts";
 export { NOT_A_SCHOOL, SCHOOL_NAME_EXCEPTIONS, } from "./school-exception-vocabulary.ts";
+export { SCHOOL_CELL_OWN_SENTINELS, SCHOOL_CELL_SENTINELS, schoolCellSentinelOf, } from "./school-cell-sentinels.ts";
+export { SHARED_ROW_SENTINELS } from "./row-sentinels.ts";
+export type { RowSentinel } from "./row-sentinels.ts";
 export type { EmptyReason, Validated } from "./validated.ts";
 export type { NotASchool, RefusalReason, SchoolNameException, } from "./school-exception-vocabulary.ts";

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@finbheara/domain",
-	"version": "0.9.0",
-	"description": "Places, CLRG regions, school names, ages and dances as they are printed: read, compared and told apart",
+	"version": "0.11.0",
+	"description": "Places, CLRG regions, school names, ages, dances and a person's print in its role, as they are printed: read, compared and told apart",
 	"keywords": [
 		"places",
 		"regions",
@@ -57,6 +57,10 @@
 			"types": "./dist/types/promotion.d.ts",
 			"default": "./dist/promotion.js"
 		},
+		"./person": {
+			"types": "./dist/types/person.d.ts",
+			"default": "./dist/person.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"files": ["dist/*.js", "dist/chunks/*.js", "dist/types/**/*.d.ts", "README.md", "LICENSE"],