@platforma-sdk/model 1.65.9 → 1.66.2

package/src/filters/distill.test.ts

@@ -188,4 +188,95 @@ describe("distillFilterSpec", () => {
     const filter: F = { type: "and", filters: [a, b] };
     expect(distillFilterSpec(filter)).toBeNull();
   });
+
+  // --- per-type required-field checks ---
+
+  it("keeps patternFuzzyContainSubsequence without optional fields", () => {
+    const filter: F = { type: "patternFuzzyContainSubsequence", column: "c1", value: "abc" };
+    expect(distillFilterSpec(filter)).toEqual(filter);
+  });
+
+  it("keeps patternFuzzyContainSubsequence when optional fields undefined", () => {
+    const filter: F = {
+      type: "patternFuzzyContainSubsequence",
+      column: "c1",
+      value: "abc",
+      maxEdits: undefined,
+      substitutionsOnly: undefined,
+      wildcard: undefined,
+    };
+    expect(distillFilterSpec(filter)).toEqual(filter);
+  });
+
+  it("preserves optional fields on patternFuzzyContainSubsequence when filled", () => {
+    const filter: F = {
+      type: "patternFuzzyContainSubsequence",
+      column: "c1",
+      value: "abc",
+      maxEdits: 2,
+      substitutionsOnly: true,
+      wildcard: "*",
+    };
+    expect(distillFilterSpec(filter)).toEqual(filter);
+  });
+
+  it("keeps lessThanColumn without optional minDiff", () => {
+    const filter: F = { type: "lessThanColumn", column: "c1", rhs: "c2" };
+    expect(distillFilterSpec(filter)).toEqual(filter);
+  });
+
+  it("returns null for lessThanColumn with missing required rhs", () => {
+    const filter: F = {
+      type: "lessThanColumn",
+      column: "c1",
+      rhs: undefined as unknown as string,
+    };
+    expect(distillFilterSpec(filter)).toBeNull();
+  });
+
+  it("returns null for ifNa with missing required replacement", () => {
+    const filter: F = {
+      type: "ifNa",
+      column: "c1",
+      replacement: undefined as unknown as string,
+    };
+    expect(distillFilterSpec(filter)).toBeNull();
+  });
+
+  // --- isFilledValue edge cases ---
+
+  it("returns null for empty-string value after trim", () => {
+    const filter: F = { type: "patternEquals", column: "c1", value: "   " };
+    expect(distillFilterSpec(filter)).toBeNull();
+  });
+
+  it("returns null for inSet with empty array", () => {
+    const filter: F = { type: "inSet", column: "c1", value: [] };
+    expect(distillFilterSpec(filter)).toBeNull();
+  });
+
+  it("returns null for inSet with array containing empty string", () => {
+    const filter: F = { type: "inSet", column: "c1", value: ["a", "  "] };
+    expect(distillFilterSpec(filter)).toBeNull();
+  });
+
+  it("keeps inSet with non-empty string items", () => {
+    const filter: F = { type: "inSet", column: "c1", value: ["a", "b"] };
+    expect(distillFilterSpec(filter)).toEqual(filter);
+  });
+
+  it("keeps equal with x=0 (falsy but filled)", () => {
+    const filter: F = { type: "equal", column: "c1", x: 0 };
+    expect(distillFilterSpec(filter)).toEqual(filter);
+  });
+
+  it("keeps isNA (single required column)", () => {
+    const filter: F = { type: "isNA", column: "c1" };
+    expect(distillFilterSpec(filter)).toEqual(filter);
+  });
+
+  it("returns null for isNA with missing column", () => {
+    const filter: F = { type: "isNA", column: undefined as unknown as string };
+    expect(distillFilterSpec(filter)).toBeNull();
+  });
 });

package/src/filters/distill.ts

@@ -1,4 +1,4 @@
-import { DistributiveKeys, UnionToTuples } from "@milaboratories/helpers";
+import { DistributiveKeys, isNil, UnionToTuples } from "@milaboratories/helpers";
 import {
   RootFilterSpec,
   type FilterSpec,
@@ -8,51 +8,6 @@ import { traverseFilterSpec } from "./traverse";
 import { InferFilterSpecLeaf } from "@milaboratories/pl-model-common";
 import { isEmpty } from "es-toolkit/compat";
 
-/** All possible field names that can appear in any FilterSpecLeaf variant. */
-type FilterSpecLeafKey = DistributiveKeys<FilterSpecLeaf<string>>;
-
-/** Compile-time check: every key in the tuple is a valid leaf key (via satisfies). */
-const KNOWN_LEAF_KEYS_TUPLE: UnionToTuples<FilterSpecLeafKey> = [
-  "n",
-  "x",
-  "rhs",
-  "type",
-  "value",
-  "column",
-  "minDiff",
-  "maxEdits",
-  "wildcard",
-  "replacement",
-  "substitutionsOnly",
-];
-const KNOWN_LEAF_KEYS: Set<FilterSpecLeafKey> = new Set(KNOWN_LEAF_KEYS_TUPLE);
-
-/** Returns true if the leaf is filled — type is defined and no required fields are undefined. */
-function isFilledLeaf<T>(node: FilterSpecLeaf<T>): boolean {
-  if (node.type == null) return false;
-  return !Object.values(node).some((value) => {
-    switch (typeof value) {
-      case "number":
-      case "boolean":
-        return false;
-      case "string":
-        return value.trim() === "";
-      default: // undefined, null, empty objects/arrays
-        return isEmpty(value);
-    }
-  });
-}
-
-function distillLeaf<T>(node: FilterSpecLeaf<T>): FilterSpecLeaf<T> {
-  const result: Record<string, unknown> = {};
-  for (const [key, value] of Object.entries(node)) {
-    if (KNOWN_LEAF_KEYS.has(key as FilterSpecLeafKey)) {
-      result[key] = value;
-    }
-  }
-  return result as FilterSpecLeaf<T>;
-}
-
 /**
  * Strips non-FilterSpec metadata (whitelist approach) and removes
  * unfilled leaves (type is undefined or any required field is undefined).
@@ -80,3 +35,104 @@ export function distillFilterSpec<
     not: (result) => (result === null ? null : ({ type: "not", filter: result } as R)),
   });
 }
+
+function distillLeaf<T>(node: FilterSpecLeaf<T>): FilterSpecLeaf<T> {
+  const result: Record<string, unknown> = {};
+  for (const [key, value] of Object.entries(node)) {
+    if (KNOWN_LEAF_KEYS.has(key as FilterSpecLeafKey)) {
+      result[key] = value;
+    }
+  }
+  return result as FilterSpecLeaf<T>;
+}
+
+/** Returns true if the leaf is filled — type is defined and every required field per-type is filled. */
+function isFilledLeaf<T>(node: FilterSpecLeaf<T>): boolean {
+  if (isNil(node.type)) return false;
+  const required = REQUIRED_KEYS_BY_TYPE[node.type];
+  const record = node as Record<string, unknown>;
+  return required.every((key) => isFilledValue(record[key]));
+}
+
+/**
+ * Returns true if the value is considered "filled":
+ * - primitives (number, boolean): always true
+ * - string: non-empty after trim
+ * - array: non-empty AND every item is filled
+ * - plain object: non-empty AND every field value is filled
+ * - null/undefined: false
+ */
+function isFilledValue(value: unknown): boolean {
+  if (isNil(value)) return false;
+  switch (typeof value) {
+    case "number":
+    case "boolean":
+      return true;
+    case "string":
+      return value.trim() !== "";
+    default:
+      if (isEmpty(value)) return false;
+      if (Array.isArray(value)) return value.every(isFilledValue);
+      return Object.values(value as Record<string, unknown>).every(isFilledValue);
+  }
+}
+
+/** All possible field names that can appear in any FilterSpecLeaf variant. */
+type FilterSpecLeafKey = DistributiveKeys<FilterSpecLeaf<string>>;
+
+/** Leaf type discriminators (excludes the placeholder `undefined` variant). */
+type FilterSpecLeafType = Exclude<FilterSpecLeaf<unknown>, { type: undefined }>["type"];
+
+type LeafOfType<T extends FilterSpecLeafType> = Extract<FilterSpecLeaf<unknown>, { type: T }>;
+
+type RequiredKeys<O> = { [K in keyof O]-?: {} extends Pick<O, K> ? never : K }[keyof O];
+
+/** Required field keys of a given leaf variant (excluding the `type` discriminator). */
+type RequiredLeafKeys<T extends FilterSpecLeafType> = Exclude<RequiredKeys<LeafOfType<T>>, "type">;
+
+/** Exact per-type shape — adding a key not required by that variant becomes a type error. */
+type RequiredKeysByType = { readonly [T in FilterSpecLeafType]: readonly RequiredLeafKeys<T>[] };
+
+/** Compile-time check: every key in the tuple is a valid leaf key (via satisfies). */
+const KNOWN_LEAF_KEYS_TUPLE: UnionToTuples<FilterSpecLeafKey> = [
+  "n",
+  "x",
+  "rhs",
+  "type",
+  "value",
+  "column",
+  "minDiff",
+  "maxEdits",
+  "wildcard",
+  "replacement",
+  "substitutionsOnly",
+];
+const KNOWN_LEAF_KEYS: Set<FilterSpecLeafKey> = new Set(KNOWN_LEAF_KEYS_TUPLE);
+
+/** Required fields per leaf type. Optional fields (e.g. minDiff, maxEdits) excluded. */
+const REQUIRED_KEYS_BY_TYPE = {
+  isNA: ["column"],
+  isNotNA: ["column"],
+  ifNa: ["column", "replacement"],
+  patternEquals: ["column", "value"],
+  patternNotEquals: ["column", "value"],
+  patternContainSubsequence: ["column", "value"],
+  patternNotContainSubsequence: ["column", "value"],
+  patternMatchesRegularExpression: ["column", "value"],
+  patternFuzzyContainSubsequence: ["column", "value"],
+  inSet: ["column", "value"],
+  notInSet: ["column", "value"],
+  topN: ["column", "n"],
+  bottomN: ["column", "n"],
+  equal: ["column", "x"],
+  notEqual: ["column", "x"],
+  lessThan: ["column", "x"],
+  greaterThan: ["column", "x"],
+  lessThanOrEqual: ["column", "x"],
+  greaterThanOrEqual: ["column", "x"],
+  equalToColumn: ["column", "rhs"],
+  lessThanColumn: ["column", "rhs"],
+  greaterThanColumn: ["column", "rhs"],
+  lessThanColumnOrEqual: ["column", "rhs"],
+  greaterThanColumnOrEqual: ["column", "rhs"],
+} as const satisfies RequiredKeysByType;

package/src/labels/derive_distinct_tooltips.test.ts

@@ -0,0 +1,233 @@
+import {
+  Annotation,
+  type AxisQualification,
+  type PColumnSpec,
+  type PObjectId,
+} from "@milaboratories/pl-model-common";
+import { describe, expect, test } from "vitest";
+import { deriveDistinctTooltips, type TooltipEntry } from "./derive_distinct_tooltips";
+import type { ColumnSnapshot, MatchVariant } from "../columns";
+
+function createSpec(name: string, label?: string): PColumnSpec {
+  return {
+    kind: "PColumn",
+    name,
+    valueType: "Int",
+    axesSpec: [],
+    annotations: label !== undefined ? { [Annotation.Label]: label } : {},
+  } as PColumnSpec;
+}
+
+function axisQualification(
+  axisName: string,
+  contextDomain: Record<string, string>,
+): AxisQualification {
+  return { axis: { name: axisName }, contextDomain };
+}
+
+function linkerSnapshot(name: string, label?: string): ColumnSnapshot<PObjectId> {
+  return {
+    id: `linker-${name}` as PObjectId,
+    spec: createSpec(name, label),
+    dataStatus: "ready",
+    data: undefined,
+  };
+}
+
+function pathStep(
+  linkerName: string,
+  qualifications: AxisQualification[],
+  label?: string,
+): MatchVariant["path"][number] {
+  return { linker: linkerSnapshot(linkerName, label), qualifications };
+}
+
+describe("deriveDistinctTooltips", () => {
+  test("empty entry (no qualifications, no linker path) → undefined", () => {
+    const entries: TooltipEntry[] = [{ spec: createSpec("col1") }];
+    expect(deriveDistinctTooltips(entries)).toEqual([undefined]);
+  });
+
+  test("only header info but no sections → undefined (single section filtered)", () => {
+    const entries: TooltipEntry[] = [
+      {
+        spec: createSpec("col1", "Column 1"),
+        variantIndex: 1,
+        variantCount: 1,
+      },
+    ];
+    expect(deriveDistinctTooltips(entries)).toEqual([undefined]);
+  });
+
+  test("linker path produces Origin path section", () => {
+    const entries: TooltipEntry[] = [
+      {
+        spec: createSpec("hit_col", "Hit Col"),
+        linkerPath: [
+          pathStep("linker_a", [axisQualification("sample", { batch: "A" })], "Linker A"),
+        ],
+      },
+    ];
+    const [tooltip] = deriveDistinctTooltips(entries);
+    expect(tooltip).toBeDefined();
+    expect(tooltip).toContain("Origin path");
+    expect(tooltip).toContain("linker 1: Linker A");
+    expect(tooltip).toContain("qualifies: sample context: batch=A");
+    expect(tooltip).toContain("hit column: Hit Col");
+  });
+
+  test("qualifications.forQueries produces Anchors section", () => {
+    const entries: TooltipEntry[] = [
+      {
+        spec: createSpec("col1", "Col 1"),
+        qualifications: {
+          forQueries: {
+            ["main" as PObjectId]: [axisQualification("sample", { batch: "A" })],
+            ["other" as PObjectId]: [axisQualification("gene", { source: "X" })],
+          },
+          forHit: [],
+        },
+      },
+    ];
+    const [tooltip] = deriveDistinctTooltips(entries);
+    expect(tooltip).toContain("Anchors (bound via this variant)");
+    expect(tooltip).toContain("main   sample context: batch=A");
+    expect(tooltip).toContain("other   gene context: source=X");
+  });
+
+  test("qualifications.forHit produces Hit section", () => {
+    const entries: TooltipEntry[] = [
+      {
+        spec: createSpec("col1", "Col 1"),
+        qualifications: {
+          forQueries: {},
+          forHit: [axisQualification("sample", { batch: "B" })],
+        },
+      },
+    ];
+    const [tooltip] = deriveDistinctTooltips(entries);
+    expect(tooltip).toContain("Hit column qualifications");
+    expect(tooltip).toContain("sample context: batch=B");
+  });
+
+  test("distinctiveQualifications produces Distinctive section", () => {
+    const entries: TooltipEntry[] = [
+      {
+        spec: createSpec("col1", "Col 1"),
+        distinctiveQualifications: {
+          forQueries: { ["main" as PObjectId]: [axisQualification("sample", { batch: "A" })] },
+          forHit: [axisQualification("gene", { source: "Y" })],
+        },
+      },
+    ];
+    const [tooltip] = deriveDistinctTooltips(entries);
+    expect(tooltip).toContain("Distinctive (what separates this variant)");
+    expect(tooltip).toContain("main: sample context: batch=A");
+    expect(tooltip).toContain("hit: gene context: source=Y");
+  });
+
+  test("variantCount > 1 adds Variant N of M line in header", () => {
+    const entries: TooltipEntry[] = [
+      {
+        spec: createSpec("col1", "Col 1"),
+        variantIndex: 1,
+        variantCount: 2,
+        qualifications: {
+          forQueries: { ["main" as PObjectId]: [axisQualification("sample", { batch: "A" })] },
+          forHit: [],
+        },
+      },
+    ];
+    const [tooltip] = deriveDistinctTooltips(entries);
+    expect(tooltip).toContain("Variant: 1 of 2");
+  });
+
+  test("axis qualification with empty contextDomain shows only axis name", () => {
+    const entries: TooltipEntry[] = [
+      {
+        spec: createSpec("col1", "Col 1"),
+        qualifications: {
+          forQueries: { ["main" as PObjectId]: [axisQualification("sample", {})] },
+          forHit: [],
+        },
+      },
+    ];
+    const [tooltip] = deriveDistinctTooltips(entries);
+    expect(tooltip).toContain("main   sample");
+    expect(tooltip).not.toContain("context:");
+  });
+
+  test("empty forQueries object → no Anchors section", () => {
+    const entries: TooltipEntry[] = [
+      {
+        spec: createSpec("col1", "Col 1"),
+        qualifications: { forQueries: {}, forHit: [] },
+        linkerPath: [pathStep("linker_a", [], "Linker A")],
+      },
+    ];
+    const [tooltip] = deriveDistinctTooltips(entries);
+    expect(tooltip).not.toContain("Anchors");
+  });
+
+  test("multi-step linker path numbers sequentially", () => {
+    const entries: TooltipEntry[] = [
+      {
+        spec: createSpec("hit_col", "Hit Col"),
+        linkerPath: [
+          pathStep("linker_a", [], "Linker A"),
+          pathStep("linker_b", [axisQualification("sample", { batch: "B" })], "Linker B"),
+        ],
+      },
+    ];
+    const [tooltip] = deriveDistinctTooltips(entries);
+    expect(tooltip).toContain("linker 1: Linker A");
+    expect(tooltip).toContain("linker 2: Linker B");
+  });
+
+  test("all sections compose with double-newline separators", () => {
+    const entries: TooltipEntry[] = [
+      {
+        spec: createSpec("hit_col", "Hit"),
+        variantIndex: 2,
+        variantCount: 2,
+        linkerPath: [pathStep("linker_a", [axisQualification("sample", { batch: "B" })], "LA")],
+        qualifications: {
+          forQueries: { ["main" as PObjectId]: [axisQualification("sample", { batch: "B" })] },
+          forHit: [axisQualification("sample", { batch: "B" })],
+        },
+        distinctiveQualifications: {
+          forQueries: { ["main" as PObjectId]: [axisQualification("sample", { batch: "B" })] },
+          forHit: [],
+        },
+      },
+    ];
+    const [tooltip] = deriveDistinctTooltips(entries);
+    expect(tooltip).toBeDefined();
+    const sections = tooltip!.split("\n\n");
+    expect(sections.length).toBe(5);
+    expect(sections[0]).toContain("Variant: 2 of 2");
+    expect(sections[1]).toContain("Origin path");
+    expect(sections[2]).toContain("Anchors");
+    expect(sections[3]).toContain("Hit column qualifications");
+    expect(sections[4]).toContain("Distinctive");
+  });
+
+  test("parallel results — array aligns with input", () => {
+    const entries: TooltipEntry[] = [
+      { spec: createSpec("a") },
+      {
+        spec: createSpec("b", "B"),
+        qualifications: {
+          forQueries: { ["main" as PObjectId]: [axisQualification("sample", { batch: "A" })] },
+          forHit: [],
+        },
+      },
+      { spec: createSpec("c") },
+    ];
+    const result = deriveDistinctTooltips(entries);
+    expect(result.length).toBe(3);
+    expect(result[0]).toBeUndefined();
+    expect(result[1]).toBeDefined();
+    expect(result[2]).toBeUndefined();
+  });
+});

package/src/labels/derive_distinct_tooltips.ts

@@ -0,0 +1,130 @@
+import {
+  Annotation,
+  PObjectId,
+  readAnnotation,
+  type AxisQualification,
+  type PColumnSpec,
+} from "@milaboratories/pl-model-common";
+import { isNil } from "es-toolkit";
+import type { MatchQualifications, MatchVariant } from "../columns";
+
+export type TooltipEntry = {
+  /** Main column spec — used for column-name fallback when no label. */
+  spec: PColumnSpec;
+  /** Full qualifications carried by this variant. */
+  qualifications?: MatchQualifications;
+  /** Minimal qualifications that separate this variant from its siblings. */
+  distinctiveQualifications?: MatchQualifications;
+  /** Linker steps traversed to reach the hit column. */
+  linkerPath?: MatchVariant["path"];
+  /** Position of this variant within the same physical column (1-based). */
+  variantIndex?: number;
+  /** Total variants for the same physical column. */
+  variantCount?: number;
+};
+
+/** Format tooltip strings for each entry. Returns `undefined` when nothing useful. */
+export function deriveDistinctTooltips(entries: TooltipEntry[]): (undefined | string)[] {
+  return entries.map(formatTooltip);
+}
+
+function formatTooltip(entry: TooltipEntry): undefined | string {
+  const sections: string[] = [];
+
+  const header = formatHeader(entry);
+  if (header !== undefined) sections.push(header);
+
+  const origin = formatOriginPath(entry);
+  if (origin !== undefined) sections.push(origin);
+
+  const anchors = formatAnchors(entry.qualifications);
+  if (anchors !== undefined) sections.push(anchors);
+
+  const hit = formatHit(entry.qualifications);
+  if (hit !== undefined) sections.push(hit);
+
+  const distinctive = formatDistinctive(entry.distinctiveQualifications);
+  if (distinctive !== undefined) sections.push(distinctive);
+
+  if (sections.length <= 1) return undefined;
+  return sections.join("\n\n");
+}
+
+const BULLET_1 = "  • ";
+const SUB_BULLET = "      ";
+
+function formatHeader(entry: TooltipEntry): undefined | string {
+  const lines: string[] = [];
+  if (entry.variantCount !== undefined && entry.variantCount > 1) {
+    lines.push(`Variant: ${entry.variantIndex ?? "?"} of ${entry.variantCount}`);
+  }
+  return lines.join("\n");
+}
+
+function formatOriginPath(entry: TooltipEntry): undefined | string {
+  const path = entry.linkerPath ?? [];
+  if (path.length === 0) return undefined;
+
+  const lines = ["Origin path"];
+  path.forEach((step, i) => {
+    const label =
+      readAnnotation(step.linker.spec, Annotation.LinkLabel) ??
+      readAnnotation(step.linker.spec, Annotation.Label) ??
+      step.linker.spec.name;
+    lines.push(`${BULLET_1}linker ${i + 1}: ${label}`);
+    const qs = formatAxisQualifications(step.qualifications);
+    if (qs !== undefined) lines.push(`${SUB_BULLET}qualifies: ${qs}`);
+  });
+  const hitName = readAnnotation(entry.spec, Annotation.Label) ?? entry.spec.name;
+  lines.push(`${BULLET_1}hit column: ${hitName}`);
+  return lines.join("\n");
+}
+
+function formatAnchors(q: undefined | MatchQualifications): undefined | string {
+  if (isNil(q)) return undefined;
+  const ids = Object.keys(q.forQueries);
+  if (ids.length === 0) return undefined;
+
+  const lines = [];
+  for (const id of ids) {
+    const item = q.forQueries[id as PObjectId];
+    if (item.length === 0) continue;
+    const rendered = formatAxisQualifications(item);
+    lines.push(`${BULLET_1}${id}${rendered !== undefined ? `   ${rendered}` : ""}`);
+  }
+  return lines.length > 0
+    ? ["Anchors (bound via this variant)"].concat(lines).join("\n")
+    : undefined;
+}
+
+function formatHit(q: undefined | MatchQualifications): undefined | string {
+  if (isNil(q) || q.forHit.length === 0) return undefined;
+  const rendered = formatAxisQualifications(q.forHit);
+  if (rendered === undefined) return undefined;
+  return ["Hit column qualifications", `${BULLET_1}${rendered}`].join("\n");
+}
+
+function formatDistinctive(q: undefined | MatchQualifications): undefined | string {
+  if (isNil(q)) return undefined;
+  const bullets: string[] = [];
+  for (const id of Object.keys(q.forQueries)) {
+    for (const item of q.forQueries[id as PObjectId])
+      bullets.push(`${BULLET_1}${id}: ${formatQualification(item)}`);
+  }
+  for (const item of q.forHit) bullets.push(`${BULLET_1}hit: ${formatQualification(item)}`);
+  if (bullets.length === 0) return undefined;
+  return ["Distinctive (what separates this variant)", ...bullets].join("\n");
+}
+
+function formatAxisQualifications(qs: AxisQualification[]): undefined | string {
+  if (qs.length === 0) return undefined;
+  return qs.map(formatQualification).join("; ");
+}
+
+function formatQualification(q: AxisQualification): string {
+  const axisName = typeof q.axis === "string" ? q.axis : (q.axis.name ?? JSON.stringify(q.axis));
+  const entries = Object.entries(q.contextDomain);
+  if (entries.length === 0) return axisName;
+  const kv = entries.map(([k, v]) => `${k}=${v}`).join(", ");
+  return `${axisName} context: ${kv}`;
+}

package/src/labels/index.ts

@@ -1 +1,2 @@
 export * from "./derive_distinct_labels";
+export * from "./derive_distinct_tooltips";