@platforma-sdk/model 1.68.8 → 1.70.0

package/src/components/PlDatasetSelector/enrichment_discovery.ts

@@ -0,0 +1,111 @@
+import { Annotation, createEnrichmentRef } from "@milaboratories/pl-model-common";
+import type {
+  EnrichmentStep,
+  LabeledEnrichmentRef,
+  LabeledEnrichmentRefs,
+  MultiColumnSelector,
+  PObjectId,
+  PObjectSpec,
+} from "@milaboratories/pl-model-common";
+import type {
+  AnchoredColumnCollection,
+  ColumnVariant,
+} from "../../columns/column_collection_builder";
+import {
+  deriveDistinctLabels,
+  type DeriveLabelsOptions,
+  type Entry,
+} from "../../labels/derive_distinct_labels";
+
+/**
+ * True for global-form ids — `canonicalize({__isRef: true, blockId, name})` —
+ * which the workflow can resolve via bquery. Local-form ids (`resolvePath`)
+ * fail this check and are excluded from auto-discovery; prerun/outputs hops
+ * must be supplied as resolved `{spec, data}` instead.
+ */
+function isGloballyAddressable(id: PObjectId): boolean {
+  try {
+    const decoded = JSON.parse(id);
+    return (
+      typeof decoded === "object" &&
+      decoded !== null &&
+      decoded.__isRef === true &&
+      typeof decoded.blockId === "string" &&
+      typeof decoded.name === "string"
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Linker-reached hits attached to the anchor primary. Drops zero-hop variants
+ * (filters / the primary itself) and structural hits (subset, linker, label
+ * columns). Narrow further with `include` selectors or a `predicate`.
+ */
+export function findEnrichmentColumns(
+  collection: AnchoredColumnCollection,
+  options?: {
+    maxHops?: number;
+    include?: MultiColumnSelector | MultiColumnSelector[];
+    predicate?: (spec: PObjectSpec) => boolean;
+  },
+): ColumnVariant[] {
+  const include =
+    options?.include === undefined
+      ? undefined
+      : Array.isArray(options.include)
+        ? options.include
+        : [options.include];
+  const variants = collection.findColumnVariants({
+    mode: "enrichment",
+    maxHops: options?.maxHops ?? 4,
+    include,
+    exclude: [
+      { annotations: { [Annotation.IsSubset]: "true" } },
+      { annotations: { [Annotation.IsLinkerColumn]: "true" } },
+      { name: Annotation.Label },
+    ],
+  });
+  const predicate = options?.predicate;
+  return variants.filter((v) => {
+    if (v.path.length === 0) return false;
+    if (predicate !== undefined && !predicate(v.column.spec)) return false;
+    if (!isGloballyAddressable(v.column.id)) return false;
+    if (v.path.some((p) => !isGloballyAddressable(p.linker.id))) return false;
+    return true;
+  });
+}
+
+/**
+ * Pair each variant with a path-disambiguated label (so export headers stay
+ * unique) and carry hit/linker `PObjectId`s through verbatim. Propagates
+ * `qualifications.forHit`; `forQueries` is re-derived by the table builder.
+ */
+export function enrichmentVariantsToRefs(
+  variants: ColumnVariant[],
+  labelOptions?: DeriveLabelsOptions,
+): LabeledEnrichmentRefs {
+  if (variants.length === 0) return [];
+
+  const entries: Entry[] = variants.map((variant) => ({
+    spec: variant.column.spec,
+    linkerPath: variant.path.map((p) => ({ spec: p.linker.spec })),
+    qualifications: variant.qualifications,
+  }));
+  const labels = deriveDistinctLabels(entries, labelOptions);
+
+  return variants.map((variant, i): LabeledEnrichmentRef => {
+    const path: EnrichmentStep[] = variant.path.map((step) => ({
+      type: "linker",
+      linker: step.linker.id,
+    }));
+    return {
+      ref: createEnrichmentRef(variant.column.id, {
+        path,
+        qualifications: variant.qualifications.forHit,
+      }),
+      label: labels[i],
+    };
+  });
+}

package/src/components/PlDatasetSelector/index.ts

@@ -1,2 +1,3 @@
+export * from "./dataset_selection";
 export * from "./filter_discovery";
 export * from "./build_dataset_options";

package/src/labels/derive_distinct_tooltips.test.ts

@@ -34,12 +34,8 @@ function linkerSnapshot(name: string, label?: string): ColumnSnapshot<PObjectId>
   };
 }
 
-function pathStep(
-  linkerName: string,
-  qualifications: AxisQualification[],
-  label?: string,
-): MatchVariant["path"][number] {
-  return { linker: linkerSnapshot(linkerName, label), qualifications };
+function pathStep(linkerName: string, label?: string): MatchVariant["path"][number] {
+  return { linker: linkerSnapshot(linkerName, label) };
 }
 
 describe("deriveDistinctTooltips", () => {
@@ -63,16 +59,13 @@ describe("deriveDistinctTooltips", () => {
     const entries: TooltipEntry[] = [
       {
         spec: createSpec("hit_col", "Hit Col"),
-        linkerPath: [
-          pathStep("linker_a", [axisQualification("sample", { batch: "A" })], "Linker A"),
-        ],
+        linkerPath: [pathStep("linker_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");
   });
 
@@ -146,7 +139,7 @@ describe("deriveDistinctTooltips", () => {
       {
         spec: createSpec("col1", "Col 1"),
         qualifications: { forQueries: {}, forHit: [] },
-        linkerPath: [pathStep("linker_a", [], "Linker A")],
+        linkerPath: [pathStep("linker_a", "Linker A")],
       },
     ];
     const [tooltip] = deriveDistinctTooltips(entries);
@@ -157,10 +150,7 @@ describe("deriveDistinctTooltips", () => {
     const entries: TooltipEntry[] = [
       {
         spec: createSpec("hit_col", "Hit Col"),
-        linkerPath: [
-          pathStep("linker_a", [], "Linker A"),
-          pathStep("linker_b", [axisQualification("sample", { batch: "B" })], "Linker B"),
-        ],
+        linkerPath: [pathStep("linker_a", "Linker A"), pathStep("linker_b", "Linker B")],
       },
     ];
     const [tooltip] = deriveDistinctTooltips(entries);
@@ -174,7 +164,7 @@ describe("deriveDistinctTooltips", () => {
         spec: createSpec("hit_col", "Hit"),
         variantIndex: 2,
         variantCount: 2,
-        linkerPath: [pathStep("linker_a", [axisQualification("sample", { batch: "B" })], "LA")],
+        linkerPath: [pathStep("linker_a", "LA")],
         qualifications: {
           forQueries: { ["main" as PObjectId]: [axisQualification("sample", { batch: "B" })] },
           forHit: [axisQualification("sample", { batch: "B" })],

package/src/labels/derive_distinct_tooltips.ts

@@ -46,7 +46,6 @@ function formatTooltip(entry: TooltipEntry): undefined | string {
 }
 
 const BULLET_1 = "  • ";
-const SUB_BULLET = "      ";
 
 function formatHeader(entry: TooltipEntry): undefined | string {
   const lines: string[] = [];
@@ -67,8 +66,6 @@ function formatOriginPath(entry: TooltipEntry): undefined | string {
       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}`);