/** * Structural postfix derivation for linked columns (phase 2 of `deriveDistinctLabels`). * * A linked column is * reached by a CHAIN of linkers, and we distinguish two such columns by the same ideology the main * algorithm uses — "find the minimal difference, escalate until unique" — over two dimensions: * * - root: the single source axis of the chain, derived from `linkers[0]` (one of its axesSpec). * This is "the source" — it's what we prefer to show ("difference of sources"). * - linkers: the linker chain itself (by `LinkLabel`), a per-step fallback used only where roots * coincide. * * Nothing is stored redundantly: the caller passes the linker path (`linkers`) and the hit spec; * root and every token are computed on the fly. The caller also supplies the `stem` (label+trace+ * quals from the existing single-entity machinery); this module only adds the path postfix, and * only where stems collide. */ import { Annotation, canonicalizeJson, getAxisId, readAnnotation, type AxisSpec, type PColumnSpec, } from "@milaboratories/pl-model-common"; import { isNil } from "es-toolkit"; /** * One entry to label: its stem plus the linker path that reached it (`linkers[0]` source-most) and * the hit spec used to orient the chain. Plain columns pass neither. Entries with different markers * (something the UI shows beside the label) never collide. */ export type PostfixEntry = { stem: string; hit?: PColumnSpec; linkers?: PColumnSpec[]; marker?: string; }; /** * One distinguishing piece of the postfix: the full source spec (axis or linker column — no info * lost) plus `text`, the minimal text that sets it apart from the siblings (a label, or only the * differing domain keys). Custom formatters may use `spec` freely; `text` is the default rendering. */ export type LinkerPart = { spec: Spec; text: string }; /** The distinguishing source of one column: its root axis (when it differs) + the linker chain. */ export type LinkerParts = { root?: LinkerPart; linkers: LinkerPart[]; }; /** * Renders the postfix zone from the distinguishing sources. Default: * `via ${[root, linkers.join(" > ")].filter(Boolean).join(" ")}` (using each piece's `text`). * Returning `undefined` — or the empty string `""` — suppresses the postfix entirely (the column * keeps just its stem); the two are treated identically. */ export type LinkerFormatter = ( parts: LinkerParts, hit: PColumnSpec | undefined, index: number, ) => string | undefined; function defaultLinkerFormatter(parts: LinkerParts): string { const chain = parts.linkers.map((l) => l.text).join(" > "); const pieces = [parts.root?.text, chain || undefined].filter((p): p is string => !isNil(p)); return pieces.length === 0 ? "" : `via ${pieces.join(" ")}`; } type AxisIdentity = { label?: string } & Pick; function extractAxisIdentity(axis: AxisSpec): AxisIdentity { const id = getAxisId(axis); return { label: readAnnotation(axis, Annotation.Label)?.trim() || undefined, name: id.name, domain: id.domain, contextDomain: id.contextDomain, }; } /** * A linker is named ONLY by its human label (`LinkLabel`/`Label`) — never by its technical column * name. Returns `undefined` for an unlabeled linker, which callers treat as "not renderable": such a * step is skipped, and disambiguation falls to another step or the root. */ function extractLinkerIdentity(linker: PColumnSpec): AxisIdentity | undefined { const label = ( readAnnotation(linker, Annotation.LinkLabel) ?? readAnnotation(linker, Annotation.Label) )?.trim(); return label ? { label, name: label } : undefined; } /** Domain keys where `mine` differs from at least one competitor. */ function differingKeys( mine: Record | undefined, others: (Record | undefined)[], ): string[] { const my = mine ?? {}; const diffKeys = new Set(); for (const o of others) { const od = o ?? {}; for (const k of Object.keys(my)) { if (my[k] !== od[k]) { diffKeys.add(k); } } for (const k of Object.keys(od)) { if (my[k] !== od[k]) { diffKeys.add(k); } } } return [...diffKeys]; } function renderWithDomain( base: string, keys: string[], domain: Record | undefined, ): string { if (keys.length === 0) return base; const d = domain ?? {}; const pairs = keys.map((k) => `${k}=${d[k] ?? "∅"}`).join(", "); return `${base}[${pairs}]`; } /** * Minimal token distinguishing `mine` from `others`: label → name → only the differing domain keys. * Falls back to the bare label/name when indistinguishable at this dimension (another one covers it). */ function deriveToken(mine: AxisIdentity, others: AxisIdentity[]): string { const base = mine.label ?? mine.name; if (mine.label !== undefined && others.every((o) => o.label !== mine.label)) return mine.label; if (others.every((o) => o.name !== mine.name)) return base; const dk = differingKeys( mine.domain, others.map((o) => o.domain), ); if (dk.length > 0) return renderWithDomain(base, dk, mine.domain); const ck = differingKeys( mine.contextDomain, others.map((o) => o.contextDomain), ); if (ck.length > 0) return renderWithDomain(base, ck, mine.contextDomain); return base; } /** * The chain's single root: the source-side axis of `linkers[0]`. A linker bridges two axis groups; * the side facing the next hop (`linkers[1]`, or the hit for a single-linker chain) is the target, * the other side is the source → its axis is the root. `undefined` if `linkers[0]` is not a * well-formed two-group linker. */ export function extractRoot(hit: PColumnSpec, linkers: PColumnSpec[]): AxisSpec | undefined { const first = linkers[0]; if (first === undefined) return undefined; const axes = first.axesSpec; if (axes.length !== 2) return undefined; const second = linkers[1] ?? hit; return axes.find((a) => !second.axesSpec.some((b) => b.name === a.name)); } type Slot = { kind: "root" } | { kind: "linker"; i: number }; const ABSENT = "__ABSENT__"; // sentinel for "this row has no value at this slot" /** A colliding group: entries + their derived roots + original indices + the postfix formatter. */ type Group = { entries: PostfixEntry[]; roots: (AxisSpec | undefined)[]; indices: number[]; format: LinkerFormatter; }; function deriveSlotKey(group: Group, slot: Slot, row: number): string { if (slot.kind === "root") { const r = group.roots[row]; return r === undefined ? ABSENT : canonicalizeJson(getAxisId(r)); } else { const l = group.entries[row].linkers?.[slot.i]; const id = l && extractLinkerIdentity(l); return isNil(id) ? ABSENT : canonicalizeJson(id); } } function deriveSlotToken(group: Group, slot: Slot, row: number): string | undefined { if (slot.kind === "root") { const r = group.roots[row]; if (r === undefined) return undefined; const comp = group.roots .filter((o, j) => j !== row && !isNil(o)) .map((o) => extractAxisIdentity(o!)); return deriveToken(extractAxisIdentity(r), comp); } const l = group.entries[row].linkers?.[slot.i]; const id = l && extractLinkerIdentity(l); if (isNil(id)) return undefined; // unlabeled / absent linker → not renderable, skip const comp = group.entries .filter((_, j) => j !== row) .map((e) => e.linkers?.[slot.i]) .map((x) => (x ? extractLinkerIdentity(x) : undefined)) .filter((x): x is AxisIdentity => !isNil(x)); return deriveToken(id, comp); } function getDiscriminates(group: Group, slot: Slot): boolean { return new Set(group.entries.map((_, r) => deriveSlotKey(group, slot, r))).size > 1; } /** Render one row against a chosen slot set: the distinguishing root + linker pieces, formatted. */ function renderRow(group: Group, slots: Slot[], row: number): string { const rootSpec = group.roots[row]; const rootText = slots.some((s) => s.kind === "root") ? deriveSlotToken(group, { kind: "root" }, row) : undefined; const root: LinkerPart | undefined = rootSpec !== undefined && rootText !== undefined ? { spec: rootSpec, text: rootText } : undefined; const linkers = slots .filter((s): s is { kind: "linker"; i: number } => s.kind === "linker") .sort((a, b) => a.i - b.i) .map((s) => { const spec = group.entries[row].linkers?.[s.i]; const text = deriveSlotToken(group, s, row); return spec !== undefined && text !== undefined ? { spec, text } : undefined; }) .filter((l): l is LinkerPart => !isNil(l)); // No distinguishing pieces for this row → no postfix (don't invoke the formatter with empties). if (root === undefined && linkers.length === 0) return ""; // A formatter may suppress the postfix by returning `undefined` or `""`; `|| ""` collapses both // to the same empty value so neither counts as a distinguishing token during slot escalation. return group.format({ root, linkers }, group.entries[row].hit, group.indices[row]) || ""; } function renderAll(group: Group, slots: Slot[]): string[] { return group.entries.map((_, r) => renderRow(group, slots, r)); } function allUnique(rendered: string[]): boolean { return new Set(rendered).size === rendered.length; } /** * Minimal slot set that makes the group unique. Escalate by priority (root, then linkers by step), * then drop any redundant slot; render every row symmetrically against the result. * * KNOWN LIMITATION (review point): symmetric render can over-decorate a row in a mixed group (e.g. * `via Sample MapperA` where `via Sample` alone is already unique for that row). Per-row trimming is * a generalized `dropRedundantLinkerSuffix`; naive greedy trimming is unstable, so it's deferred. */ function resolveGroup( entries: PostfixEntry[], indices: number[], format: LinkerFormatter, ): string[] { const group: Group = { entries, roots: entries.map((e) => e.hit && e.linkers?.length ? extractRoot(e.hit, e.linkers) : undefined, ), indices, format, }; const maxLen = Math.max(0, ...entries.map((e) => e.linkers?.length ?? 0)); const slots: Slot[] = [ { kind: "root" }, ...Array.from({ length: maxLen }, (_, i): Slot => ({ kind: "linker", i })), ]; const escalated = slots.reduce( (acc, slot) => allUnique(renderAll(group, acc)) || !getDiscriminates(group, slot) ? acc : (acc.push(slot), acc), [], ); const chosen = escalated.reduce((acc, slot) => { const trial = acc.filter((s) => s !== slot); return allUnique(renderAll(group, trial)) ? trial : acc; }, escalated); return renderAll(group, chosen); } /** * Full label per entry: `stem` plus, where stems collide, a minimal postfix distinguishing the * linked columns by the difference between their sources. */ export function derivePostfixes( entries: PostfixEntry[], format: LinkerFormatter = defaultLinkerFormatter, ): string[] { const groups = entries.reduce>((acc, e, idx) => { const key = `${e.stem}\u0000${e.marker ?? ""}`; return acc.set(key, [...(acc.get(key) ?? []), idx]); }, new Map()); const postfix = [...groups.values()].reduce>((acc, idxs) => { if (idxs.length < 2) return acc; // no other entry shares this stem and marker — no postfix const resolved = resolveGroup( idxs.map((i) => entries[i]), idxs, format, ); return idxs.reduce((m, i, k) => m.set(i, resolved[k]), acc); }, new Map()); return entries.map((e, i) => { const p = postfix.get(i); return p ? `${e.stem} ${p}` : e.stem; }); }