@finbheara/domain 0.54.0 → 0.56.0

package/README.md

@@ -44,6 +44,7 @@ ESM, Node ≥ 22 or Bun ≥ 1.4.2. MIT. Not affiliated with or endorsed by any d
 | `@finbheara/domain/clrg-regions` | `REGIONS`, `regionOf`, `resolvePhrase` |
 | `@finbheara/domain/event` | `EVENT_REGISTER`, `EVENT_REGISTER_BY_CODE`, `EVENT_TIER`, `eventTier`, `isMajorEvent`, `eventCodeOfSlug`, the `EventRegisterRow` type: the CLRG championships of tier 1 to 3 (below) |
 | `@finbheara/domain/school` | `createSchoolNameReader`, `DEFAULT_SCHOOL_NAME_READER`, `compareSchoolNames`, `foldSchoolName`, `schoolEncoder`, `schoolColumns` |
+| `@finbheara/domain/school-graph` | `schoolGraph`, `FAMILY_EDGES`, `LINK_YEARS`, `ANY_PATH`, `FAMILY_PATH`, and the `SchoolLink`/`LinkPath`/`LinkPolicy` types: how two schools are linked, as candidate paths with flags (below) |
 | `@finbheara/domain/tune` | `tune()`, `tuneRelation`, `tempoLegal`, `settingAt`, `TUNE_NODES`: the CLRG set dance list, each tune with its time, speeds and bars |
 | `@finbheara/domain/ceili` | `ceili()`, `ceiliRelation`, `CEILI_NODES`: the céilí handbook dances |
 | `@finbheara/domain/dance` | `dance()`: a print read as a tune and a céilí dance, narrowed by its round |
@@ -269,6 +270,46 @@ invisible characters dropped and its whitespace collapsed; a `regex` is compiled
 flag and anchors itself. Your rows are asked before the shipped ones and the first match
 answers.
 
+## Link two schools
+
+A school is renamed, absorbs another, merges, splits, opens a site, or is linked to another in a
+way nobody has typed (`related`). Hand those edges in, and ask how two schools are linked. The
+answer is every simple path between them, each with its flags, never a yes or a no:
+
+```ts
+import { FAMILY_PATH, schoolGraph } from "@finbheara/domain/school-graph";
+
+const g = schoolGraph({
+  links: [
+    { from: "Alpha Academy", to: "Alpha Rince", shape: "rename", year: 2010 },
+    { from: "Alpha Rince", to: "Beta School", shape: "merger", year: 2016, provisional: true },
+    { from: "Beta School", to: "Gamma Dance", shape: "related", year: null },
+  ],
+});
+
+const r = g.links("Alpha Academy", "Gamma Dance", { year: 2018, policy: FAMILY_PATH });
+r.arm;                          // "linked"
+r.candidates[0].hops;           // 3
+r.candidates[0].flags;          // { relatedHops: 1, provisional: 1, maxYearGap: 8, ... }
+r.policy;                       // { name: "family", passes: false }
+
+g.within("Alpha Academy", FAMILY_PATH);   // ["Alpha Academy", "Alpha Rince", "Beta School"]
+g.line("Beta School").candidates.map((c) => c.school);  // every school on its line
+```
+
+A path's flags: `relatedHops` (steps of unknown type), `nonFamilyHops` (steps outside
+`FAMILY_EDGES`), `maxYearGap` (the widest gap between a step's year and the asked year),
+`datedAfter`, `undated`, `provisional`, `unbacked` (a step handed in with `decision: null`),
+`contradicted` (your own check of the data, handed in), `sites` and `redirected`. Its
+`confidence` is its weakest step's.
+
+A `LinkPolicy` is your reading over those flags: a step predicate (`keep`) and a hop limit
+(`maxHops`), or `anyOf` several. `passes` and `within` answer it as a reachability walk over the
+steps it keeps, so the verdict is exact, and `maxPaths` (and the `tooMany` it sets) only limits
+which candidate paths are listed. The shortest path, and the shortest one that passes, are always
+listed. An edge never makes two schools one: `arm` is `self` only where both ids reach one
+school through your `redirect`.
+
 ## Read a set dance
 
 `tune()` reads a spoken or printed set dance as the tunes of the official list it may name. A

package/dist/chunks/{place-bz7zr7a5.js → place-hrhzz95q.js}

@@ -80,6 +80,7 @@ class RoleRefusedName {
   suffixes = [];
   refusal;
   verdict;
+  corruption;
   role;
   sentinel;
   constructor(read, role, sentinel) {
@@ -87,6 +88,7 @@ class RoleRefusedName {
     this.sentinel = sentinel;
     this.nn0 = read.nn0;
     this.nn1 = read.nn1;
+    this.corruption = read.corruption;
     this.refusal = { rule: "placeholder", printed: read.nn0, value: NAME_REFUSED };
     this.verdict = { kind: "refused", refusal: this.refusal, rules: read.verdict.rules };
   }

package/dist/noun-index.js

@@ -1,7 +1,7 @@
 import"./chunks/place-tcgfvemw.js";
 import {
   roleName2
-} from "./chunks/place-bz7zr7a5.js";
+} from "./chunks/place-hrhzz95q.js";
 
 import {
   NAME_COLUMNS,

package/dist/person.js

@@ -10,7 +10,7 @@ import {
   seatName2,
   dancerName2,
   teacherName2
-} from "./chunks/place-bz7zr7a5.js";
+} from "./chunks/place-hrhzz95q.js";
 import {
   SHARED_ROW_SENTINELS2,
   sentinelIn2

package/dist/school-graph.js

@@ -0,0 +1,283 @@
+var FAMILY_EDGES = [
+  "rename",
+  "absorb",
+  "merger",
+  "split",
+  "branch",
+  "site-of"
+];
+var LINK_YEARS = 5;
+var ANY_PATH = { name: "any-path" };
+var FAMILY_PATH = { name: "family", keep: (s) => !s.flags.nonFamily };
+var stepFlags = (l, year, family, site) => ({
+  related: l.shape === "related",
+  nonFamily: !family.has(l.shape),
+  yearGap: year === null || l.year === null ? null : Math.abs(l.year - year),
+  datedAfter: year !== null && l.year !== null && l.year > year,
+  undated: l.year === null,
+  provisional: l.provisional === true,
+  unbacked: l.decision === null,
+  contradicted: l.contradicted === true,
+  site
+});
+var cmp = (x, y) => x < y ? -1 : x > y ? 1 : 0;
+function schoolGraph(input) {
+  const family = new Set(input.family ?? FAMILY_EDGES);
+  const all = [];
+  const siteLinks = new Set;
+  const arcs = new Map;
+  const add = (l, site) => {
+    all.push(l);
+    if (site)
+      siteLinks.add(l);
+    if (l.from === l.to)
+      return;
+    for (const [x, y] of [
+      [l.from, l.to],
+      [l.to, l.from]
+    ]) {
+      const list = arcs.get(x);
+      const arc = { next: y, link: l, site };
+      if (list === undefined)
+        arcs.set(x, [arc]);
+      else
+        list.push(arc);
+    }
+  };
+  for (const l of input.links)
+    add(l, false);
+  for (const [s, p] of input.sites ?? [])
+    add({ from: p, to: s, shape: "site-of", year: null, decision: undefined }, true);
+  for (const list of arcs.values())
+    list.sort((p, q) => cmp(p.next, q.next) || cmp(p.link.shape, q.link.shape) || (p.link.year ?? -1) - (q.link.year ?? -1));
+  const schools = [...arcs.keys()].sort(cmp);
+  const redirect = (id) => {
+    const seen = new Set([id]);
+    let at = id;
+    for (let n = input.redirect?.(at) ?? null;n !== null && !seen.has(n); ) {
+      seen.add(n);
+      at = n;
+      n = input.redirect?.(at) ?? null;
+    }
+    return at;
+  };
+  const stepOf = (at, arc, year) => ({
+    at,
+    next: arc.next,
+    link: arc.link,
+    flags: stepFlags(arc.link, year, family, arc.site)
+  });
+  const pathOf = (steps, to, redirected) => {
+    let maxYearGap = null;
+    let confidence = steps.length === 0 ? null : 1;
+    const f = {
+      relatedHops: 0,
+      nonFamilyHops: 0,
+      datedAfter: 0,
+      undated: 0,
+      provisional: 0,
+      unbacked: 0,
+      contradicted: 0,
+      sites: 0
+    };
+    for (const s of steps) {
+      const g = s.flags;
+      if (g.related)
+        f.relatedHops++;
+      if (g.nonFamily)
+        f.nonFamilyHops++;
+      if (g.datedAfter)
+        f.datedAfter++;
+      if (g.undated)
+        f.undated++;
+      if (g.provisional)
+        f.provisional++;
+      if (g.unbacked)
+        f.unbacked++;
+      if (g.contradicted)
+        f.contradicted++;
+      if (g.site)
+        f.sites++;
+      if (g.yearGap !== null && (maxYearGap === null || g.yearGap > maxYearGap))
+        maxYearGap = g.yearGap;
+      const c = s.link.confidence;
+      confidence = confidence === null || c === undefined || c === null ? null : Math.min(confidence, c);
+    }
+    return {
+      to,
+      steps,
+      hops: steps.length,
+      flags: { ...f, maxYearGap, redirected },
+      confidence
+    };
+  };
+  const pathPasses = (p, policy) => {
+    if ("anyOf" in policy)
+      return policy.anyOf.some((q) => pathPasses(p, q));
+    if (policy.maxHops !== undefined && p.hops > policy.maxHops)
+      return false;
+    const keep = policy.keep;
+    return keep === undefined || p.steps.every(keep);
+  };
+  const walk = (a, policy, year) => {
+    const reached = new Map([[a, []]]);
+    let frontier = [a];
+    for (let depth = 0;frontier.length > 0; depth++) {
+      if (policy.maxHops !== undefined && depth >= policy.maxHops)
+        break;
+      const next = [];
+      for (const at of frontier)
+        for (const arc of arcs.get(at) ?? []) {
+          if (reached.has(arc.next))
+            continue;
+          const s = stepOf(at, arc, year);
+          if (policy.keep !== undefined && !policy.keep(s))
+            continue;
+          reached.set(arc.next, [...reached.get(at), s]);
+          next.push(arc.next);
+        }
+      frontier = next;
+    }
+    return reached;
+  };
+  const reach = (a, policy, year) => {
+    if (!("anyOf" in policy))
+      return walk(a, policy, year);
+    const out = new Map;
+    for (const q of policy.anyOf)
+      for (const [s, steps] of reach(a, q, year)) {
+        const was = out.get(s);
+        if (was === undefined || steps.length < was.length)
+          out.set(s, steps);
+      }
+    return out;
+  };
+  const simplePaths = (a, b, year, max) => {
+    const paths = [];
+    let budget = 20000;
+    let more = false;
+    const on = new Set([a]);
+    const stack = [];
+    const go = (at) => {
+      for (const arc of arcs.get(at) ?? []) {
+        if (more)
+          return;
+        if (--budget < 0 || paths.length >= max) {
+          more = true;
+          return;
+        }
+        if (on.has(arc.next))
+          continue;
+        stack.push(stepOf(at, arc, year));
+        if (arc.next === b)
+          paths.push([...stack]);
+        else {
+          on.add(arc.next);
+          go(arc.next);
+          on.delete(arc.next);
+        }
+        stack.pop();
+      }
+    };
+    if (a !== b)
+      go(a);
+    return { paths, more };
+  };
+  const sameSteps = (x, y) => x.length === y.length && x.every((s, i) => s.link === y[i]?.link && s.next === y[i]?.next);
+  const rank = (p, q) => p.flags.contradicted - q.flags.contradicted || p.hops - q.hops || (q.confidence ?? -1) - (p.confidence ?? -1);
+  const candidatesTo = (a, b, year, max, redirected, policy, shortest, passing) => {
+    const { paths, more } = simplePaths(a, b, year, max);
+    for (const must of [passing, shortest])
+      if (must !== undefined && !paths.some((p) => sameSteps(p, must)))
+        paths.push(must);
+    const out = paths.map((steps) => {
+      const p = pathOf(steps, b, redirected);
+      return policy === undefined ? p : { ...p, passes: pathPasses(p, policy) };
+    });
+    out.sort(rank);
+    return { paths: out, tooMany: more };
+  };
+  const yearOf = (q) => q?.year ?? null;
+  return {
+    schools,
+    edges: all,
+    between: (a, b) => all.filter((l) => !siteLinks.has(l) && (l.from === a && l.to === b || l.from === b && l.to === a)),
+    passes: (a, b, policy, year = null) => reach(a, policy, year).has(b),
+    within: (a, policy, year = null) => [...reach(a, policy, year).keys()].sort(cmp),
+    links: (a0, b0, q) => {
+      const [a, b] = [redirect(a0), redirect(b0)];
+      const redirected = (a !== a0 ? 1 : 0) + (b !== b0 ? 1 : 0);
+      const year = yearOf(q);
+      const policy = q?.policy;
+      const verdict = policy === undefined ? undefined : { name: policy.name, passes: false };
+      if (a === b)
+        return {
+          asked: { a: a0, b: b0 },
+          a,
+          b,
+          arm: "self",
+          candidates: [],
+          tooMany: false,
+          ...verdict === undefined ? {} : { policy: { ...verdict, passes: true } }
+        };
+      const shortest = walk(a, ANY_PATH, year).get(b);
+      const passing = policy === undefined ? undefined : reach(a, policy, year).get(b);
+      if (verdict !== undefined)
+        verdict.passes = passing !== undefined;
+      if (shortest === undefined)
+        return {
+          asked: { a: a0, b: b0 },
+          a,
+          b,
+          arm: "none",
+          candidates: [],
+          tooMany: false,
+          ...verdict === undefined ? {} : { policy: verdict }
+        };
+      const { paths, tooMany } = candidatesTo(a, b, year, q?.maxPaths ?? 8, redirected, policy, shortest, passing);
+      return {
+        asked: { a: a0, b: b0 },
+        a,
+        b,
+        arm: "linked",
+        candidates: paths,
+        tooMany,
+        ...verdict === undefined ? {} : { policy: verdict }
+      };
+    },
+    line: (a0, q) => {
+      const a = redirect(a0);
+      const redirected = a !== a0 ? 1 : 0;
+      const year = yearOf(q);
+      const policy = q?.policy;
+      const any = walk(a, ANY_PATH, year);
+      const passing = policy === undefined ? undefined : reach(a, policy, year);
+      const candidates = [];
+      for (const [s, shortest] of any) {
+        if (s === a)
+          continue;
+        const { paths, tooMany } = candidatesTo(a, s, year, q?.maxPaths ?? 8, redirected, policy, shortest, passing?.get(s));
+        candidates.push({
+          school: s,
+          paths,
+          tooMany,
+          ...passing === undefined ? {} : { passes: passing.has(s) }
+        });
+      }
+      candidates.sort((x, y) => Number(y.passes ?? false) - Number(x.passes ?? false) || (x.paths[0]?.hops ?? 0) - (y.paths[0]?.hops ?? 0) || cmp(x.school, y.school));
+      return {
+        asked: a0,
+        school: a,
+        candidates,
+        ...policy === undefined ? {} : { policy: { name: policy.name } }
+      };
+    }
+  };
+}
+export {
+  ANY_PATH,
+  FAMILY_EDGES,
+  FAMILY_PATH,
+  LINK_YEARS,
+  schoolGraph
+};

package/dist/types/school-graph.d.ts

@@ -0,0 +1,111 @@
+export type LinkShape = "rename" | "absorb" | "merger" | "split" | "branch" | "related" | "site-of" | (string & {});
+export declare const FAMILY_EDGES: readonly LinkShape[];
+export declare const LINK_YEARS = 5;
+export interface SchoolLink {
+    from: string;
+    to: string;
+    shape: LinkShape;
+    year: number | null;
+    provisional?: boolean;
+    confidence?: number | null;
+    decision?: string | null;
+    contradicted?: boolean;
+}
+export interface StepFlags {
+    related: boolean;
+    nonFamily: boolean;
+    yearGap: number | null;
+    datedAfter: boolean;
+    undated: boolean;
+    provisional: boolean;
+    unbacked: boolean;
+    contradicted: boolean;
+    site: boolean;
+}
+export interface LinkStep {
+    at: string;
+    next: string;
+    link: SchoolLink;
+    flags: StepFlags;
+}
+export interface PathFlags {
+    relatedHops: number;
+    nonFamilyHops: number;
+    maxYearGap: number | null;
+    datedAfter: number;
+    undated: number;
+    provisional: number;
+    unbacked: number;
+    contradicted: number;
+    sites: number;
+    redirected: number;
+}
+export interface LinkPath {
+    to: string;
+    steps: LinkStep[];
+    hops: number;
+    flags: PathFlags;
+    confidence: number | null;
+    passes?: boolean;
+}
+export type LinkPolicy = StepPolicy | {
+    name: string;
+    anyOf: readonly LinkPolicy[];
+};
+export interface StepPolicy {
+    name: string;
+    keep?: (step: LinkStep) => boolean;
+    maxHops?: number;
+}
+export interface LinkQuery {
+    year?: number | null;
+    policy?: LinkPolicy;
+    maxPaths?: number;
+}
+export interface LinkAnswer {
+    asked: {
+        a: string;
+        b: string;
+    };
+    a: string;
+    b: string;
+    arm: "self" | "linked" | "none";
+    candidates: LinkPath[];
+    tooMany: boolean;
+    policy?: {
+        name: string;
+        passes: boolean;
+    };
+}
+export interface LineCandidate {
+    school: string;
+    paths: LinkPath[];
+    tooMany: boolean;
+    passes?: boolean;
+}
+export interface LineAnswer {
+    asked: string;
+    school: string;
+    candidates: LineCandidate[];
+    policy?: {
+        name: string;
+    };
+}
+export interface SchoolGraphInput {
+    links: Iterable<SchoolLink>;
+    sites?: Iterable<readonly [site: string, school: string]>;
+    redirect?: (id: string) => string | null;
+    family?: readonly LinkShape[];
+}
+export interface SchoolGraph {
+    readonly schools: readonly string[];
+    readonly edges: readonly SchoolLink[];
+    between(a: string, b: string): SchoolLink[];
+    links(a: string, b: string, q?: LinkQuery): LinkAnswer;
+    line(a: string, q?: LinkQuery): LineAnswer;
+    passes(a: string, b: string, policy: LinkPolicy, year?: number | null): boolean;
+    within(a: string, policy: LinkPolicy, year?: number | null): string[];
+}
+export declare const ANY_PATH: StepPolicy;
+export declare const FAMILY_PATH: StepPolicy;
+export declare function schoolGraph(input: SchoolGraphInput): SchoolGraph;

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@finbheara/domain",
-	"version": "0.54.0",
-	"description": "Places, CLRG regions and events, school names, ages, dances, competition titles, codes and schedules, and a person's print in its role, as they are printed: read, compared and told apart",
+	"version": "0.56.0",
+	"description": "Places, CLRG regions and events, school names and the links between schools, ages, dances, competition titles, codes and schedules, and a person's print in its role, as they are printed: read, compared and told apart",
 	"keywords": [
 		"places",
 		"regions",
@@ -81,6 +81,10 @@
 			"types": "./dist/types/event.d.ts",
 			"default": "./dist/event.js"
 		},
+		"./school-graph": {
+			"types": "./dist/types/school-graph.d.ts",
+			"default": "./dist/school-graph.js"
+		},
 		"./package.json": "./package.json"
 	},
 	"files": ["dist/*.js", "dist/chunks/*.js", "dist/types/**/*.d.ts", "README.md", "LICENSE"],
@@ -97,7 +101,7 @@
 		"prepublishOnly": "bun scripts/build.ts && bun scripts/guard-tarball.ts"
 	},
 	"dependencies": {
-		"@finbheara/names": "0.26.0"
+		"@finbheara/names": "0.28.0"
 	},
 	"devDependencies": {
 		"typescript": "7.0.2"