@milaboratories/pl-model-common 1.47.3 → 1.49.0

package/src/drivers/pframe/spec/spec.ts

@@ -83,6 +83,37 @@ export const Domain = {
   },
 } as const;
 
+/**
+ * Domain keys whose value is the id of a block, rather than a qualifier of the data.
+ *
+ * Applying a template repoints these at the blocks of the project being built: an axis a block
+ * produced names that block in its domain, so an axis left naming the exported-from project
+ * resolves to nothing. Listing the keys is what makes that safe — a template's entry ids are
+ * arbitrary non-empty strings, so a hand-written template may name an entry `closest`, and a
+ * qualifier that happens to read `closest` must not be mistaken for a reference to it.
+ *
+ * A key absent from here is simply left alone, which is the behaviour from before relocation
+ * reached domains at all. Adding one is therefore safe; omitting one costs only that a template
+ * carrying it applies still pointing at the project it came from.
+ */
+export const BlockScopedDomain: ReadonlySet<string> = new Set<string>([
+  "pl7.app/blockId",
+  "pl7.app/block",
+  "pl7.app/redefined-by",
+  "pl7.app/annotationRunId",
+  "pl7.app/clonotypeAnnotationRunId",
+  "pl7.app/clustering/blockId",
+  "pl7.app/umap/blockId",
+  "pl7.app/peptide/extractionRunId",
+  "pl7.app/repertoire/extractionRunId",
+  "pl7.app/antibodyVariantDesigner/designRunId",
+  "pl7.app/vdj/clonotypingRunId",
+  "pl7.app/vdj/clustering/blockId",
+  "pl7.app/vdj/integration/blockId",
+  "pl7.app/vdj/spatiotemporalAnalysis/blockId",
+  "pl7.app/vdj/libraryId",
+]);
+
 export type Domain = Metadata &
   Partial<{
     [Domain.Alphabet]: "nucleotide" | "aminoacid" | (string & {});

package/src/flags/block_flags.ts

@@ -13,7 +13,7 @@ export type BlockCodeFeatureFlags = Record<`supports${string}`, boolean | number
   Record<`requires${string}`, boolean | number | undefined>;
 
 /**
- * Known block flags. Flags are set during model compilation, see `BlockModel.create` for more details and for initial values.
+ * Known block flags. Flags are set during model compilation, see `BlockModelV3` feature flags for more details and for initial values.
  */
 export type BlockCodeKnownFeatureFlags = {
   readonly supportsLazyState?: boolean;

package/src/index.ts

@@ -23,3 +23,4 @@ export * from "./services";
 export * from "./pool_entry";
 export * from "./project_id";
 export * from "./columns";
+export * from "./template";

package/src/plid.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
 import { base32Encode } from "./base32_encode";
+import { Branded } from "@milaboratories/helpers";
 
 /** Number of raw bytes in the PlId. */
 export const PlIdBytes = 15;
@@ -9,19 +10,18 @@ export const PlIdLength = 24; // = 15 bytes * 8 bits / 5 bits per char in base32
 export const PlId = z
   .string()
   .length(PlIdLength)
-  .regex(/[ABCDEFGHIJKLMNOPQRSTUVWXYZ234567]/) // RFC4648
-  .brand("PlId");
-export type PlId = z.infer<typeof PlId>;
+  .regex(/[ABCDEFGHIJKLMNOPQRSTUVWXYZ234567]/); // RFC4648
+export type PlId = Branded<z.infer<typeof PlId>, "PlId">;
 
 export function uniquePlId(): PlId {
   const data = new Uint8Array(PlIdBytes);
   crypto.getRandomValues(data);
-  return PlId.parse(base32Encode(data, "RFC4648"));
+  return PlId.parse(base32Encode(data, "RFC4648")) as PlId;
 }
 
 export function plId(bytes: Uint8Array): PlId {
   if (bytes.length !== PlIdBytes) throw new Error(`Wrong number of bytes: ${bytes.length}`);
-  return PlId.parse(base32Encode(bytes, "RFC4648"));
+  return PlId.parse(base32Encode(bytes, "RFC4648")) as PlId;
 }
 
 export async function digestPlId(data: string): Promise<PlId> {

package/src/template/index.ts

@@ -0,0 +1,4 @@
+export * from "./kind_selector";
+export * from "./project_template_v1";
+export * from "./template_ref_form";
+export * from "./template_relocate";

package/src/template/kind_selector.ts

@@ -0,0 +1,126 @@
+import type { Branded } from "@milaboratories/helpers";
+import type { BlockKindReference } from "../bmodel/block_kind_ref";
+import { parseKindRef, splitVersionedName } from "../bmodel/block_kind_ref";
+
+/**
+ * Version-selection tier of a template entry's `kind` field.
+ *
+ * - `exact` — `X.Y.Z`: this version and no other.
+ * - `patch` — `~X.Y.Z`: patch floor, behavior frozen.
+ * - `minor` — `^X.Y.Z`: minor floor, behavior floats.
+ */
+export type KindSelectorOp = "exact" | "patch" | "minor";
+
+/** The version half of a `{name}@{selector}` kind reference, split into parts. */
+export type KindSelector = {
+  readonly op: KindSelectorOp;
+  readonly version: string;
+};
+
+/**
+ * On-wire reference to a *set* of block kind versions: `{name}@{selector}`, e.g.
+ * `@platforma-open/milaboratories.mixcr-clonotyping.kind@~1.2.0`.
+ *
+ * The template-file form of a kind reference, and the only form the
+ * `template-v1` schema accepts in an entry's `kind` field. It is the same string
+ * shape as {@link BlockKindReference} widened by the `~`/`^` tiers, but branded
+ * separately so a *resolved* kind reference is never silently passed where a
+ * selector is expected, or vice versa. Widen an exact reference explicitly with
+ * {@link kindReferenceToSelectorReference}.
+ */
+export type BlockKindSelectorReference = Branded<string, "BlockKindSelectorReference">;
+
+/** `X.Y.Z` with optional semver prerelease and build metadata. */
+const semVerRegex =
+  /^\d+\.\d+\.\d+(?:-[\dA-Za-z-]+(?:\.[\dA-Za-z-]+)*)?(?:\+[\dA-Za-z-]+(?:\.[\dA-Za-z-]+)*)?$/;
+
+/**
+ * Split a raw selector string (`1.2.0`, `~1.2.0`, `^1.2.0`) into its parts.
+ *
+ * The version is validated as `X.Y.Z`, so a range that is legal npm but not part
+ * of the kind grammar (`>=1.0.0`, `1.x`, `latest`) is rejected here rather than
+ * reaching resolution. Note the deliberate divergence from
+ * `tools/block-tools`'s `parseSelector`, which additionally tolerates a leading
+ * `@` as `exact`: after the `{name}@{selector}` split a leading `@` can only
+ * come from a doubled separator, which is malformed.
+ *
+ * Mapping a selector onto a concrete version is resolution, not parsing, and
+ * lives with the resolver (`kind_resolver.selectorToRange`).
+ *
+ * @throws if the version part is not `X.Y.Z`
+ */
+export function parseKindSelector(raw: string): KindSelector {
+  const s = raw.trim();
+  const op: KindSelectorOp = s.startsWith("~") ? "patch" : s.startsWith("^") ? "minor" : "exact";
+  const version = op === "exact" ? s : s.slice(1);
+  if (!semVerRegex.test(version)) {
+    throw new Error(
+      `Malformed kind version selector (expected 'X.Y.Z', '~X.Y.Z' or '^X.Y.Z'): ${raw}`,
+    );
+  }
+  return { op, version };
+}
+
+/** Render a {@link KindSelector} back to its on-wire string. */
+export function formatKindSelector(sel: KindSelector): string {
+  switch (sel.op) {
+    case "exact":
+      return sel.version;
+    case "patch":
+      return `~${sel.version}`;
+    case "minor":
+      return `^${sel.version}`;
+  }
+}
+
+/**
+ * Split a {@link BlockKindSelectorReference} into `{ name, selector }`.
+ *
+ * @throws if the reference carries no version segment, or the selector is
+ *   outside the `X.Y.Z` / `~X.Y.Z` / `^X.Y.Z` grammar
+ */
+export function parseKindSelectorReference(ref: BlockKindSelectorReference): {
+  name: string;
+  selector: KindSelector;
+} {
+  const { name, version } = splitVersionedName(ref, "kind selector reference", "{name}@{selector}");
+  return { name, selector: parseKindSelector(version) };
+}
+
+/**
+ * Compose a {@link BlockKindSelectorReference} from a name and selector.
+ *
+ * A formatter, not a validator — pass a selector that came from
+ * {@link parseKindSelector} or that you constructed from a known-good version.
+ */
+export function formatKindSelectorReference(k: {
+  name: string;
+  selector: KindSelector;
+}): BlockKindSelectorReference {
+  return `${k.name}@${formatKindSelector(k.selector)}` as BlockKindSelectorReference;
+}
+
+/**
+ * Widen a resolved {@link BlockKindReference} to its `exact`-tier selector form.
+ *
+ * The export direction: a block implements exactly one kind version, so export
+ * always emits `{name}@X.Y.Z`. Validates on the way through, so a
+ * malformed stored reference fails at the boundary rather than in the file.
+ */
+export function kindReferenceToSelectorReference(
+  ref: BlockKindReference,
+): BlockKindSelectorReference {
+  const { name, version } = parseKindRef(ref);
+  return formatKindSelectorReference({ name, selector: parseKindSelector(version) });
+}
+
+/** Whether `value` is a well-formed `{name}@{selector}` string. */
+export function isBlockKindSelectorReference(value: unknown): value is BlockKindSelectorReference {
+  if (typeof value !== "string") return false;
+  try {
+    parseKindSelectorReference(value as BlockKindSelectorReference);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/template/project_template_v1.test.ts

@@ -0,0 +1,315 @@
+import { describe, expect, expectTypeOf, test } from "vitest";
+import type { BlockKindReference } from "../bmodel/block_kind_ref";
+import { formatKindRef } from "../bmodel/block_kind_ref";
+import {
+  formatKindSelector,
+  formatKindSelectorReference,
+  isBlockKindSelectorReference,
+  kindReferenceToSelectorReference,
+  parseKindSelector,
+  parseKindSelectorReference,
+  type BlockKindSelectorReference,
+} from "./kind_selector";
+import {
+  parseBlockPackLocation,
+  parseBlockPackReference,
+  parseProjectTemplateV1,
+  readProjectTemplateV1,
+  type BlockPackLocationReference,
+  type BlockPackReference,
+  type ProjectTemplateV1,
+} from "./project_template_v1";
+
+//
+// The reference example for the format, as the value a YAML reader hands back:
+//
+//   schema: template-v1
+//   blocks:
+//     - id: samples
+//       kind: "@platforma-open/milaboratories.samples-and-data.kind@^1.0.0"
+//       params:
+//         dataset: bulk-rna
+//     - id: mixcr
+//       kind: "@platforma-open/milaboratories.mixcr-clonotyping.kind@~1.2.0"
+//       params:
+//         input: { __isRef: true, blockId: samples, name: reads }
+//         species: human
+//         preset: milab-human-tcr-rna
+//     - id: browser
+//       kind: "@platforma-open/milaboratories.clonotype-browser.kind@1.0.0"
+//       block: "@platforma-open/milaboratories.clonotype-browser@2.4.1"
+//       params:
+//         clonotypes: { __isRef: true, blockId: mixcr, name: clonotypes }
+//
+// The YAML text <-> value step is not this package's job (no `yaml` dependency);
+// byte-level round-tripping belongs to the middle-layer serializer.
+//
+const referenceExample = {
+  schema: "template-v1",
+  blocks: [
+    {
+      id: "samples",
+      kind: "@platforma-open/milaboratories.samples-and-data.kind@^1.0.0",
+      params: { dataset: "bulk-rna" },
+    },
+    {
+      id: "mixcr",
+      kind: "@platforma-open/milaboratories.mixcr-clonotyping.kind@~1.2.0",
+      params: {
+        input: { __isRef: true, blockId: "samples", name: "reads" },
+        species: "human",
+        preset: "milab-human-tcr-rna",
+      },
+    },
+    {
+      id: "browser",
+      kind: "@platforma-open/milaboratories.clonotype-browser.kind@1.0.0",
+      block: "@platforma-open/milaboratories.clonotype-browser@2.4.1",
+      params: {
+        clonotypes: { __isRef: true, blockId: "mixcr", name: "clonotypes" },
+      },
+    },
+  ],
+};
+
+describe("kind selector grammar", () => {
+  test("the three tiers round-trip", () => {
+    expect(parseKindSelector("1.2.0")).toEqual({ op: "exact", version: "1.2.0" });
+    expect(parseKindSelector("~1.2.0")).toEqual({ op: "patch", version: "1.2.0" });
+    expect(parseKindSelector("^1.2.0")).toEqual({ op: "minor", version: "1.2.0" });
+
+    for (const raw of ["1.2.0", "~1.2.0", "^1.2.0"]) {
+      expect(formatKindSelector(parseKindSelector(raw))).toBe(raw);
+    }
+  });
+
+  test("prerelease and build metadata survive", () => {
+    expect(parseKindSelector("~1.2.0-rc.1")).toEqual({ op: "patch", version: "1.2.0-rc.1" });
+    expect(parseKindSelector("1.2.0+build.5")).toEqual({ op: "exact", version: "1.2.0+build.5" });
+  });
+
+  test("npm ranges outside the kind grammar are rejected", () => {
+    for (const raw of [">=1.0.0", "1.x", "1.2", "latest", "*", ""]) {
+      expect(() => parseKindSelector(raw)).toThrow(/Malformed kind version selector/);
+    }
+  });
+
+  test("a scoped npm name keeps its leading @", () => {
+    const ref = "@platforma-open/milaboratories.mixcr-clonotyping.kind@~1.2.0";
+    expect(parseKindSelectorReference(ref as BlockKindSelectorReference)).toEqual({
+      name: "@platforma-open/milaboratories.mixcr-clonotyping.kind",
+      selector: { op: "patch", version: "1.2.0" },
+    });
+    expect(
+      formatKindSelectorReference({
+        name: "@platforma-open/milaboratories.mixcr-clonotyping.kind",
+        selector: { op: "patch", version: "1.2.0" },
+      }),
+    ).toBe(ref);
+  });
+
+  test("a reference with no version segment is malformed", () => {
+    expect(() =>
+      parseKindSelectorReference("@platforma-open/foo.kind" as BlockKindSelectorReference),
+    ).toThrow(/Malformed kind selector reference/);
+    expect(isBlockKindSelectorReference("@platforma-open/foo.kind")).toBe(false);
+    expect(isBlockKindSelectorReference(42)).toBe(false);
+    expect(isBlockKindSelectorReference("@platforma-open/foo.kind@1.0.0")).toBe(true);
+  });
+
+  test("an exact kind reference widens to the exact selector tier", () => {
+    // The export direction: a block implements exactly one version.
+    const resolved: BlockKindReference = formatKindRef({
+      name: "@platforma-open/milaboratories.clonotype-browser.kind",
+      version: "1.0.0",
+    });
+    const selector = kindReferenceToSelectorReference(resolved);
+
+    expect(selector).toBe("@platforma-open/milaboratories.clonotype-browser.kind@1.0.0");
+    expect(parseKindSelectorReference(selector).selector.op).toBe("exact");
+  });
+});
+
+describe("block pack override", () => {
+  test("parses an exact reference", () => {
+    expect(
+      parseBlockPackReference(
+        "@platforma-open/milaboratories.clonotype-browser@2.4.1" as BlockPackReference,
+      ),
+    ).toEqual({
+      name: "@platforma-open/milaboratories.clonotype-browser",
+      version: "2.4.1",
+    });
+  });
+
+  test("rejects a range — an override must pin", () => {
+    expect(() =>
+      parseBlockPackReference("@platforma-open/foo@^2.4.1" as BlockPackReference),
+    ).toThrow(/must pin an exact version/);
+  });
+});
+
+describe("block pack location", () => {
+  const location = (raw: string) => parseBlockPackLocation(raw as BlockPackLocationReference);
+
+  test("reads the scheme, which is all this layer needs to know", () => {
+    // Everything past the scheme belongs to whoever can reach it: this layer cannot
+    // know which schemes a given environment serves, and must not decide for it.
+    expect(location("file:///Users/dev/blocks/enter-numbers/block")).toEqual({ scheme: "file" });
+    expect(location("https://blocks.internal/enter-numbers")).toEqual({ scheme: "https" });
+  });
+
+  test("the scheme is compared case-insensitively", () => {
+    expect(location("FILE:///Users/dev/blocks/x")).toEqual({ scheme: "file" });
+  });
+
+  test("a bare path is rejected, because it would be read against the wrong directory", () => {
+    // The whole point of a locator is removing the question "relative to what".
+    expect(() => location("/Users/dev/blocks/enter-numbers/block")).toThrow(
+      /absolute URI with a scheme/,
+    );
+    expect(() => location("./blocks/enter-numbers")).toThrow(/absolute URI with a scheme/);
+  });
+
+  test("a Windows path is rejected rather than read as a one-letter scheme", () => {
+    // `C:\blocks\x` satisfies the URI scheme grammar with scheme `c`, so without the
+    // two-character floor it would be accepted here and fail somewhere unrelated.
+    expect(() => location("C:\\blocks\\enter-numbers")).toThrow(/absolute URI with a scheme/);
+    expect(location("file:///C:/blocks/enter-numbers")).toEqual({ scheme: "file" });
+  });
+});
+
+describe("parseProjectTemplateV1", () => {
+  test("parses the reference example unchanged", () => {
+    const doc = parseProjectTemplateV1(referenceExample);
+
+    expect(doc).toEqual(referenceExample);
+    expect(doc.blocks.map((b) => b.id)).toEqual(["samples", "mixcr", "browser"]);
+    expect(doc.blocks[2].block).toBe("@platforma-open/milaboratories.clonotype-browser@2.4.1");
+  });
+
+  test("params may be omitted in the file, and reads as `{}`", () => {
+    // The one field the parser fills in. Every reader past it gets a mapping, so none of
+    // them carries a `?? {}` that one of them would eventually forget.
+    const doc = parseProjectTemplateV1({
+      schema: "template-v1",
+      blocks: [{ id: "samples", kind: "@platforma-open/foo.kind@^1.0.0" }],
+    });
+
+    expect(doc.blocks[0].params).toEqual({});
+  });
+
+  test("kind is required — it carries the params contract", () => {
+    expect(() =>
+      parseProjectTemplateV1({
+        schema: "template-v1",
+        blocks: [{ id: "samples", params: { dataset: "bulk-rna" } }],
+      }),
+    ).toThrow(/kind/);
+  });
+
+  test("an entry may pin where its implementation comes from", () => {
+    const doc = parseProjectTemplateV1({
+      schema: "template-v1",
+      blocks: [
+        {
+          id: "9f3c",
+          kind: "@milaboratories/milaboratories.test-enter-numbers.kind@^1.0.0",
+          location: "file:///Users/dev/blocks/enter-numbers/block",
+          params: { numbers: [1, 2, 3] },
+        },
+      ],
+    });
+
+    expect(doc.blocks[0].location).toBe("file:///Users/dev/blocks/enter-numbers/block");
+    // The kind stays required alongside it: the locator says where to get the
+    // implementation, not what contract the params are written against.
+    expect(doc.blocks[0].kind).toBe(
+      "@milaboratories/milaboratories.test-enter-numbers.kind@^1.0.0",
+    );
+  });
+
+  test("an entry cannot pin both a version and a place", () => {
+    // Two different statements with nothing to reconcile them, so it is refused
+    // rather than settled by precedence.
+    const result = readProjectTemplateV1({
+      schema: "template-v1",
+      blocks: [
+        {
+          id: "a",
+          kind: "@o/a.kind@1.0.0",
+          block: "@o/a@1.0.0",
+          location: "file:///blocks/a",
+        },
+      ],
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.issues[0].path).toEqual(["blocks", 0, "location"]);
+    expect(result.issues[0].message).toMatch(/cannot carry both 'block' and 'location'/);
+  });
+
+  test("a malformed location is reported on its own path", () => {
+    const result = readProjectTemplateV1({
+      schema: "template-v1",
+      blocks: [{ id: "a", kind: "@o/a.kind@1.0.0", location: "/blocks/a" }],
+    });
+
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.issues[0].path).toEqual(["blocks", 0, "location"]);
+    // The grammar's own message, reported as it comes rather than restated.
+    expect(result.issues[0].message).toMatch(/absolute URI with a scheme/);
+  });
+
+  test("the format marker is checked", () => {
+    expect(() => parseProjectTemplateV1({ schema: "template-v2", blocks: [] })).toThrow();
+    expect(() => parseProjectTemplateV1({ blocks: [] })).toThrow();
+  });
+
+  test("unknown fields are rejected at both levels", () => {
+    // No `label` field: a template does not name block instances for display.
+    expect(() =>
+      parseProjectTemplateV1({
+        schema: "template-v1",
+        blocks: [{ id: "a", kind: "@o/a.kind@1.0.0", label: "Samples" }],
+      }),
+    ).toThrow(/label/);
+
+    expect(() =>
+      parseProjectTemplateV1({ schema: "template-v1", blocks: [], metadata: {} }),
+    ).toThrow(/metadata/);
+  });
+
+  test("a malformed kind selector is reported on its own path", () => {
+    const result = readProjectTemplateV1({
+      schema: "template-v1",
+      blocks: [{ id: "a", kind: "@o/a.kind@>=1.0.0" }],
+    });
+
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.issues[0].path).toEqual(["blocks", 0, "kind"]);
+      expect(result.issues[0].message).toMatch(/Malformed kind version selector/);
+    }
+  });
+
+  test("duplicate template-local ids are rejected", () => {
+    expect(() =>
+      parseProjectTemplateV1({
+        schema: "template-v1",
+        blocks: [
+          { id: "a", kind: "@o/a.kind@1.0.0" },
+          { id: "a", kind: "@o/b.kind@1.0.0" },
+        ],
+      }),
+    ).toThrow(/Duplicate template-local id: a/);
+  });
+});
+
+test("the parser's output type is exactly ProjectTemplateV1", () => {
+  // NOTE: vitest runs without `--typecheck` and tsconfig excludes *.test.ts, so this
+  // assertion is authoring-time only; it is verified by running tsc over this file.
+  expectTypeOf<ReturnType<typeof parseProjectTemplateV1>>().toEqualTypeOf<ProjectTemplateV1>();
+});