@milaboratories/pl-model-common 1.47.3 → 1.49.0

package/src/template/template_relocate.test.ts

@@ -0,0 +1,239 @@
+import { describe, expect, test } from "vitest";
+import type { ColumnUniversalId } from "../drivers";
+import {
+  createColumnDiscoveredId,
+  createColumnFilteredId,
+  createColumnOverriddenId,
+} from "../drivers";
+import { canonicalizeJson } from "../json";
+import { createGlobalPObjectId, createLocalPObjectId } from "../pool";
+import { createPlRef } from "../ref";
+import { relocateBlockIds } from "./template_relocate";
+
+/**
+ * Pointing a block's params at the project being built.
+ *
+ * This is the whole of what a template does about references, so what these tests pin is not
+ * "the walk visits everything" but the two properties a textual rewrite could not have: a
+ * value that merely looks like an id is left alone, and an identifier comes back canonical.
+ */
+
+const leafId = (blockId: string, name: string) =>
+  createGlobalPObjectId(blockId, name) as ColumnUniversalId;
+
+const to = (from: string, into: string) => new Map([[from, into]]);
+
+describe("relocateBlockIds", () => {
+  test("a PlRef is repointed where it sits", () => {
+    const params = { input: createPlRef("old", "reads") };
+
+    expect(relocateBlockIds(params, to("old", "new"))).toEqual({
+      input: createPlRef("new", "reads"),
+    });
+  });
+
+  test("an identifier held as a canonical string is repointed too", () => {
+    const params = { anchor: leafId("old", "reads") };
+
+    expect(relocateBlockIds(params, to("old", "new"))).toEqual({ anchor: leafId("new", "reads") });
+  });
+
+  test("an id the map does not mention is left alone — that is the ordering rule", () => {
+    // A reference to an entry further down the file: the caller's map holds only entries
+    // already created, so this keeps its template-local id and the applied block reports
+    // itself as missing references instead of pointing at a block below it.
+    const params = { input: createPlRef("later", "reads") };
+
+    expect(relocateBlockIds(params, to("earlier", "new"))).toEqual(params);
+  });
+
+  test("a local leaf has no block id, and comes back the same string", () => {
+    const local = createLocalPObjectId("some/path") as ColumnUniversalId;
+
+    expect(relocateBlockIds({ column: local }, to("old", "new"))).toEqual({ column: local });
+  });
+
+  test("nothing to relocate means the very same params object", () => {
+    const params = { species: "hsa", numbers: [1, 2, 3], note: `see {"not":"an id"}` };
+
+    expect(relocateBlockIds(params, to("old", "new"))).toEqual(params);
+  });
+
+  test("an empty map hands the params back untouched", () => {
+    const params = { input: createPlRef("old", "reads") };
+
+    expect(relocateBlockIds(params, new Map())).toBe(params);
+  });
+
+  describe("what a textual rewrite got wrong", () => {
+    test("a value that merely equals a block id is NOT rewritten", () => {
+      // The whole reason this is structural. `producedBy` is spec data that happens to carry
+      // the same string; a textual pass over the payload rewrote it along with the reference.
+      const id = createColumnOverriddenId({
+        source: leafId("old", "clonotypes"),
+        specOverrides: { domain: { producedBy: "old", chain: "old" } },
+      });
+
+      const moved = relocateBlockIds({ a: id }, to("old", "new")) as { a: string };
+      const key = JSON.parse(moved.a) as { source: string; specOverrides: { domain: unknown } };
+
+      expect(key.source).toContain('"blockId":"new"');
+      expect(key.specOverrides.domain).toEqual({ producedBy: "old", chain: "old" });
+    });
+
+    test("an identifier in a map KEY is repointed, and the result is canonical again", () => {
+      // Rebuilding is what restores canonical order: the keys sort by their new values, so
+      // the result equals the id a fresh project would build for the same column.
+      const qual = [{ axis: { name: "sampleId" }, contextDomain: {} }];
+      const before = createColumnDiscoveredId({
+        column: leafId("src", "clonotypes"),
+        queriesQualifications: { [leafId("aaa", "x")]: qual, [leafId("zzz", "y")]: qual },
+      });
+
+      const moved = relocateBlockIds(
+        { a: before },
+        new Map([
+          ["src", "src2"],
+          ["aaa", "zz9"],
+          ["zzz", "aa1"],
+        ]),
+      ) as { a: string };
+
+      expect(moved.a).toBe(
+        createColumnDiscoveredId({
+          column: leafId("src2", "clonotypes"),
+          queriesQualifications: { [leafId("zz9", "x")]: qual, [leafId("aa1", "y")]: qual },
+        }),
+      );
+      expect(moved.a).toBe(canonicalizeJson(JSON.parse(moved.a)));
+    });
+  });
+
+  describe("a domain that qualifies an axis", () => {
+    // An axis a block produced names that block in its domain — `pl7.app/sampleId` is
+    // qualified by the block that defined the samples, a clonotype key by the run that called
+    // the clonotypes. A chart bound to such an axis is bound to a reference.
+    const axis = (runId: string) => ({
+      kind: "axis",
+      name: "pl7.app/vdj/clonotypeKey",
+      type: "String",
+      domain: { "pl7.app/vdj/chain": "IGHeavy", "pl7.app/vdj/clonotypingRunId": runId },
+    });
+
+    test("an entry naming one of this template's entries is repointed", () => {
+      expect(relocateBlockIds({ x: axis("old") }, to("old", "new"))).toEqual({ x: axis("new") });
+    });
+
+    test("an entry that is not an entry id is left alone", () => {
+      // The map is the whole test of what is a reference: nothing reads a value's shape, so an
+      // ordinary qualifier cannot be caught by it.
+      const moved = relocateBlockIds({ x: axis("old") }, to("old", "new")) as {
+        x: { domain: Record<string, string> };
+      };
+
+      expect(moved.x.domain["pl7.app/vdj/chain"]).toBe("IGHeavy");
+    });
+
+    test("a domain naming a block this template does not carry keeps it", () => {
+      // The ordering rule again: an entry created later is not in the map yet, and the applied
+      // block reports itself as missing references rather than pointing at the wrong block.
+      expect(relocateBlockIds({ x: axis("later") }, to("earlier", "new"))).toEqual({
+        x: axis("later"),
+      });
+    });
+
+    test("a qualifier that merely collides with an entry id is NOT a reference", () => {
+      // Entry ids are validated only as non-empty strings, so a hand-written template names its
+      // entries readably. `algo` is a qualifier of the data, and an entry called `closest` does
+      // not make it one: matching the map is not evidence, the key is.
+      const params = { method: { domain: { algo: "closest", chain: "IGHeavy" } } };
+
+      expect(relocateBlockIds(params, to("closest", "new"))).toEqual(params);
+    });
+
+    test("a domain INSIDE a recognized identifier is still spec data, and stays", () => {
+      // The boundary of the rule above. This id is taken apart by the structural remapper,
+      // which never descends to the generic object case, so its overrides are untouched.
+      const id = createColumnOverriddenId({
+        source: leafId("old", "clonotypes"),
+        specOverrides: { domain: { producedBy: "old" } },
+      });
+
+      const moved = relocateBlockIds({ a: id }, to("old", "new")) as { a: string };
+      const key = JSON.parse(moved.a) as { specOverrides: { domain: unknown } };
+
+      expect(key.specOverrides.domain).toEqual({ producedBy: "old" });
+    });
+  });
+
+  describe("depth", () => {
+    test("three nested forms are repointed at the bottom and rebuilt on the way up", () => {
+      const deep = (block: string) =>
+        createColumnFilteredId({
+          source: createColumnOverriddenId({
+            source: leafId(block, "clonotypes"),
+            specOverrides: { domain: { species: "hsa" } },
+          }),
+          axisFilters: [[0, "IGH"]],
+        });
+
+      expect(relocateBlockIds({ anchor: deep("old") }, to("old", "new"))).toEqual({
+        anchor: deep("new"),
+      });
+    });
+
+    test("a discovered column's linker path names other blocks, and each is repointed", () => {
+      // The case one wrapper around the whole identifier had to cover: several ids, from
+      // several blocks, at several depths.
+      const disc = (a: string, b: string, c: string) =>
+        createColumnDiscoveredId({
+          column: leafId(a, "clonotypes"),
+          path: [
+            { type: "linker", column: leafId(b, "cell-to-clone") },
+            { type: "linker", column: leafId(c, "clone-to-gene") },
+          ],
+        });
+
+      const moved = relocateBlockIds(
+        { anchor: disc("A", "B", "C") },
+        new Map([
+          ["A", "A2"],
+          ["B", "B2"],
+          ["C", "C2"],
+        ]),
+      );
+
+      expect(moved).toEqual({ anchor: disc("A2", "B2", "C2") });
+    });
+
+    test("escape padding is peeled and put back as it was found", () => {
+      const padded = (block: string) => JSON.stringify(leafId(block, "reads"));
+
+      expect(relocateBlockIds({ hit: padded("old") }, to("old", "new"))).toEqual({
+        hit: padded("new"),
+      });
+    });
+
+    test("identifiers are reached in arrays and nested objects alike", () => {
+      const params = {
+        inputs: [createPlRef("old", "a"), { nested: leafId("old", "b") }],
+        deeper: { list: [[createPlRef("old", "c")]] },
+      };
+
+      expect(relocateBlockIds(params, to("old", "new"))).toEqual({
+        inputs: [createPlRef("new", "a"), { nested: leafId("new", "b") }],
+        deeper: { list: [[createPlRef("new", "c")]] },
+      });
+    });
+
+    test("params keyed BY a column id have the key repointed", () => {
+      // A block may key its params by column — per-column settings. A key carries a
+      // reference exactly as much as a value does.
+      const params = { [leafId("old", "reads")]: { visible: true } };
+
+      expect(relocateBlockIds(params, to("old", "new"))).toEqual({
+        [leafId("new", "reads")]: { visible: true },
+      });
+    });
+  });
+});

package/src/template/template_relocate.ts

@@ -0,0 +1,89 @@
+import { isPlainObject } from "es-toolkit";
+
+import { BlockScopedDomain, isColumnUniversalKey, remapColumnIdBlockIds } from "../drivers";
+
+/**
+ * Point every column identifier in a block's params at the blocks of the project being built.
+ *
+ * The whole of what a template does about references, and it lives here — in the package the
+ * block's own bundle imports — because knowing which values carry block ids is knowing the
+ * reference system. The engine carrying the params neither marks them, reads them, nor
+ * rewrites them: it hands the block its params and this map, and takes back what comes out.
+ *
+ * Params travel verbatim precisely so that this is possible. A file holds a `PlRef` as the
+ * object the block stored and a column id as the canonical string the block stored, with no
+ * marker of any kind, and the identifiers are found here by recognizing them — the same way
+ * the project's own dependency detector finds them in live args.
+ *
+ * Rewriting is structural, never textual: an identifier is taken apart, its `blockId` fields
+ * are replaced, and it is rebuilt canonically. That is what keeps a value that merely *looks*
+ * like an id — an axis filter, a domain this package can see belongs to an identifier it
+ * knows — from being rewritten along with it, and what re-sorts a qualifications map whose
+ * keys are identifiers.
+ *
+ * A domain reached on its own is the exception, and `relocateDomain` below says why: an axis is
+ * qualified by the block that produced it. Only the domain keys known to name a block are
+ * repointed — matching an entry id is not on its own evidence of a reference.
+ *
+ * An id the map does not mention is left as it is. That is the ordering rule doing its work:
+ * a caller building the map as it creates blocks passes only the entries already created, so
+ * a reference to an entry further down the file stays pointing at a block that does not
+ * exist, and the applied block reports itself as missing references rather than being wired
+ * to something below it.
+ *
+ * @param params Whatever the block projected, as the document stored it
+ * @param blockIds template-local entry id → the block id that entry was given
+ */
+export function relocateBlockIds<T>(params: T, blockIds: ReadonlyMap<string, string>): T {
+  if (blockIds.size === 0) return params;
+  const remapBlockId = (blockId: string) => blockIds.get(blockId) ?? blockId;
+
+  const walk = (node: unknown): unknown => {
+    // Any string may be an identifier under any amount of escaping; one that is not comes
+    // back as the very same string, so this needs no test of its own here.
+    if (typeof node === "string") return remapColumnIdBlockIds(node, remapBlockId);
+
+    // Before the generic object case: an identifier IS an object, and descending into one
+    // would rewrite the strings nested in it piecemeal instead of rebuilding the whole id —
+    // losing the bottom-up canonicalization that keeps the result a valid identifier.
+    if (isColumnUniversalKey(node)) return remapColumnIdBlockIds(node, remapBlockId);
+
+    if (Array.isArray(node)) return node.map(walk);
+
+    if (typeof node === "object" && node !== null) {
+      // Keys as well as values: params may be keyed by column id — per-column settings, say
+      // — and a key is exactly as much of a reference as a value is.
+      return Object.fromEntries(
+        Object.entries(node).map(([key, value]) => [
+          remapColumnIdBlockIds(key, remapBlockId),
+          key === "domain" && isPlainObject(value) ? relocateDomain(value) : walk(value),
+        ]),
+      );
+    }
+
+    return node;
+  };
+
+  /**
+   * The block-naming entries of a domain, repointed at the project being built: an axis a block
+   * produced names that block in its domain, so those are references like any other.
+   *
+   * Only the keys {@link BlockScopedDomain} lists, because a template's entry ids are arbitrary
+   * non-empty strings — a hand-written template may name an entry `closest`, and a qualifier
+   * reading `closest` is not a reference to it. Matching the map is not on its own enough to
+   * tell one from the other; the key is.
+   *
+   * Reached only from the generic object case — inside an identifier this package recognizes a
+   * domain is spec data and stays as it is, which is what keeps an overridden column's
+   * `specOverrides.domain` untouched.
+   */
+  const relocateDomain = (domain: Record<string, unknown>): Record<string, unknown> =>
+    Object.fromEntries(
+      Object.entries(domain).map(([key, value]) => [
+        key,
+        typeof value === "string" && BlockScopedDomain.has(key) ? remapBlockId(value) : walk(value),
+      ]),
+    );
+
+  return walk(params) as T;
+}