@milaboratories/pl-middle-layer 1.66.19 → 1.67.0

package/src/model/project_helper_params_init.test.ts

@@ -0,0 +1,249 @@
+import { beforeAll, describe, expect, test } from "vitest";
+import { getQuickJS, type QuickJSWASMModule } from "quickjs-emscripten";
+import type { BlockConfig, ResultOrError } from "@platforma-sdk/model";
+import { BlockStorageFacadeCallbacks } from "@platforma-sdk/model";
+import { ProjectHelper } from "./project_helper";
+
+/**
+ * `ProjectHelper.getInitialStorageFromParamsInVM` — the middle layer's side of the
+ * params-to-storage callback.
+ *
+ * The block model is hand-written here rather than loaded from a built block: the
+ * method's whole job is the boundary (does the callback exist, what crosses it as
+ * text, how each failure is reported), and a hand-written model is the only way to
+ * drive every failure branch on purpose. What the SDK puts behind the callback is
+ * covered by `sdk/model/src/template_init.test.ts`.
+ */
+
+const HANDLE = BlockStorageFacadeCallbacks.StorageInitialFromParams;
+
+/**
+ * No entries created yet, which is what these tests want: relocation is the SDK's half of this
+ * callback and is covered where it lives (`pl-model-common`'s `relocateBlockIds`). What is
+ * being driven here is the boundary — does the callback exist, what crosses it as text, how
+ * each failure is reported — and an empty map keeps the params arriving as written.
+ */
+const NO_IDS: ReadonlyMap<string, string> = new Map();
+
+/**
+ * A block model whose params callback body is `body`.
+ *
+ * Registration mirrors what the SDK's `tryRegisterCallback` does inside a real
+ * bundle: write the function into the render context's callback registry, which is
+ * where the invoker looks it up by handle.
+ */
+function modelCode(body: string): string {
+  return `globalThis.cfgRenderCtx.callbackRegistry[${JSON.stringify(HANDLE)}] = ${body};`;
+}
+
+/**
+ * A config carrying `code` and declaring the callback.
+ *
+ * Only three fields are read on this path — `modelAPIVersion`, the callback handle,
+ * and `code` — so the rest of `BlockConfig` (outputs, sections, inputsValid) is left
+ * out and the cast stands in for it.
+ */
+function configWith(
+  code: string,
+  options: { declareCallback?: boolean; modelAPIVersion?: number } = {},
+): BlockConfig {
+  const { declareCallback = true, modelAPIVersion = 2 } = options;
+  return {
+    modelAPIVersion,
+    sdkVersion: "1.0.0",
+    code: { type: "plain", content: code },
+    blockLifecycleCallbacks: declareCallback ? { [HANDLE]: { handle: HANDLE } } : {},
+  } as unknown as BlockConfig;
+}
+
+/** The storage the callback produced, parsed. Fails the test if it errored instead. */
+function storageFrom(result: ResultOrError<string>): unknown {
+  if (result.error !== undefined) throw new Error(`expected storage, got: ${result.error.message}`);
+  return JSON.parse(result.value);
+}
+
+let helper: ProjectHelper;
+let quickJs: QuickJSWASMModule;
+
+beforeAll(async () => {
+  quickJs = await getQuickJS();
+  helper = new ProjectHelper(quickJs);
+});
+
+describe("getInitialStorageFromParamsInVM", () => {
+  test("params reach the block's callback and its storage comes back", () => {
+    // The model echoes what it was given, so this asserts both directions of the
+    // boundary at once: the params arrived as text, the storage came back as text.
+    const result = helper.getInitialStorageFromParamsInVM(
+      configWith(modelCode("(paramsJson) => ({ storageJson: paramsJson })")),
+      { numbers: [3, 1, 2], label: "run 1" },
+      NO_IDS,
+    );
+
+    expect(storageFrom(result)).toEqual({ numbers: [3, 1, 2], label: "run 1" });
+  });
+
+  test("a reference in params survives the crossing unchanged", () => {
+    // With no entries in the map there is nothing to repoint, so this asserts the crossing
+    // alone: a `__isRef` object must arrive byte-identical, since a mangled one would produce
+    // a block wired to nothing.
+    const ref = { __isRef: true, blockId: "11111111-1111-4111-8111-111111111111", name: "reads" };
+
+    const result = helper.getInitialStorageFromParamsInVM(
+      configWith(modelCode("(paramsJson) => ({ storageJson: paramsJson })")),
+      { source: ref },
+      NO_IDS,
+    );
+
+    expect(storageFrom(result)).toEqual({ source: ref });
+  });
+
+  test("absent params arrive as an empty object, never as the literal undefined", () => {
+    // `JSON.stringify(undefined)` is not a string at all, so the callback would be
+    // handed nothing and fail to parse. An entry with no params is supposed to go
+    // through the params-less initializer instead; this is the safety net.
+    const result = helper.getInitialStorageFromParamsInVM(
+      configWith(modelCode("(paramsJson) => ({ storageJson: paramsJson })")),
+      undefined,
+      NO_IDS,
+    );
+
+    expect(storageFrom(result)).toEqual({});
+  });
+
+  test("a block that does not support params is reported, with the way out", () => {
+    // The load-bearing case: the old block CAN be added to a project, so silently
+    // falling back to default initialization would produce a block that looks
+    // applied but ignores everything the template said about it.
+    //
+    // The wording is asserted because it is the whole value of this branch. Whoever
+    // applied the file did not build the block and cannot rebuild it, so a message
+    // about SDKs or callbacks would leave them with nothing to do.
+    const result = helper.getInitialStorageFromParamsInVM(
+      configWith(modelCode("(paramsJson) => ({ storageJson: paramsJson })"), {
+        declareCallback: false,
+      }),
+      { numbers: [1] },
+      NO_IDS,
+    );
+
+    expect(result.error?.message).toBe(
+      "This version of the block cannot be created from a template. Use a newer version " +
+        "of the block, or remove the pinned block version from the template entry so a " +
+        "supported one is chosen automatically.",
+    );
+  });
+
+  test("the callback's own error is passed through verbatim", () => {
+    // Params the block rejects — the expected failure for a hand-written template.
+    // The message is the block's, so it must not be wrapped or reworded.
+    const result = helper.getInitialStorageFromParamsInVM(
+      configWith(modelCode('() => ({ error: "numbers must not be empty" })')),
+      { numbers: [] },
+      NO_IDS,
+    );
+
+    expect(result.error?.message).toBe("numbers must not be empty");
+  });
+
+  test("a throwing model is reported with its reason in the message", () => {
+    // Not the same as the case above: this is the model failing rather than
+    // declining. The reason has to reach `message`, since that is all the layers
+    // between here and the user carry.
+    const result = helper.getInitialStorageFromParamsInVM(
+      configWith(modelCode('() => { throw new Error("boom"); }')),
+      { numbers: [1] },
+      NO_IDS,
+    );
+
+    expect(result.error?.message).toContain("Initial storage creation from params failed");
+    expect(result.error?.message).toContain("boom");
+  });
+
+  test("a v1 block is rejected outright", () => {
+    const result = helper.getInitialStorageFromParamsInVM(
+      configWith(modelCode("(paramsJson) => ({ storageJson: paramsJson })"), {
+        modelAPIVersion: 1,
+      }),
+      { numbers: [1] },
+      NO_IDS,
+    );
+
+    expect(result.error?.message).toMatch(/only supported for model API version 2/);
+  });
+});
+
+describe("validateTemplateParamsInVM", () => {
+  const VALIDATE = BlockStorageFacadeCallbacks.InitializationParamsValidate;
+
+  /** A model registering only the validate callback, with `body` as its implementation. */
+  const validatorConfig = (body: string, options: { declareCallback?: boolean } = {}) => {
+    const { declareCallback = true } = options;
+    return {
+      modelAPIVersion: 2,
+      sdkVersion: "1.0.0",
+      code: {
+        type: "plain",
+        content: `globalThis.cfgRenderCtx.callbackRegistry[${JSON.stringify(VALIDATE)}] = ${body};`,
+      },
+      blockLifecycleCallbacks: declareCallback ? { [VALIDATE]: { handle: VALIDATE } } : {},
+    } as unknown as BlockConfig;
+  };
+
+  test("params the kind accepts come back with no error and nothing else", () => {
+    // Every kind declares a parser, so a pass needs no flag saying whether anything ran:
+    // reaching here without an error means the params were held to the contract.
+    const result = helper.validateTemplateParamsInVM(validatorConfig("() => ({})"), {
+      numbers: [1, 2],
+    });
+
+    expect(result.error).toBeUndefined();
+  });
+
+  test("params the kind rejects come back with the kind's reason", () => {
+    // The whole point of the pre-flight: this is reported against the entry that
+    // carries the params, with no project created yet.
+    const result = helper.validateTemplateParamsInVM(
+      validatorConfig('() => ({ error: "numbers: Expected array, received string" })'),
+      { numbers: "1,2,3" },
+    );
+
+    expect(result.error?.message).toBe("numbers: Expected array, received string");
+  });
+
+  test("a block whose model predates the callback passes unchecked", () => {
+    // Unlike initialization, this creates nothing, so there is nothing to get wrong by
+    // proceeding — and such a block is refused outright at the point it is applied.
+    const result = helper.validateTemplateParamsInVM(
+      validatorConfig("() => ({})", { declareCallback: false }),
+      { numbers: [1] },
+    );
+
+    expect(result.error).toBeUndefined();
+  });
+
+  test("params reach the check as text, references included", () => {
+    // A reference id here may be a placeholder — the check runs before blocks exist —
+    // so what crosses must be the shape, unaltered.
+    const result = helper.validateTemplateParamsInVM(
+      validatorConfig("(paramsJson) => ({ error: paramsJson })"),
+      { source: { __isRef: true, blockId: "placeholder", name: "reads" } },
+    );
+
+    expect(JSON.parse(result.error!.message)).toEqual({
+      source: { __isRef: true, blockId: "placeholder", name: "reads" },
+    });
+  });
+
+  test("a check that throws is reported as failing to run", () => {
+    // Distinct from a rejection: the kind did not decline the params, its own code
+    // broke.
+    const result = helper.validateTemplateParamsInVM(
+      validatorConfig('() => { throw new Error("schema is broken"); }'),
+      { numbers: [1] },
+    );
+
+    expect(result.error?.message).toContain("Params check failed to run");
+    expect(result.error?.message).toContain("schema is broken");
+  });
+});

package/src/model/template_apply.test.ts

@@ -0,0 +1,65 @@
+import { describe, expect, test } from "vitest";
+import type {
+  BlockKindReference,
+  BlockKindSelectorReference,
+} from "@milaboratories/pl-model-common";
+import { kindMismatch } from "./template_apply";
+
+/**
+ * Whether the block prepared for an entry is the block that entry meant.
+ *
+ * Tested directly rather than through `applyTemplateToProject`, which needs a backend to
+ * prepare a block pack at all. It is a pure function for exactly that reason: the question
+ * does not need a project, and keeping it answerable without one is what makes it testable.
+ */
+
+const ASKED = "@platforma-open/milaboratories.demo.kind@^1.0.0" as BlockKindSelectorReference;
+const declares = (ref: string) => ref as BlockKindReference;
+
+describe("kindMismatch", () => {
+  test("a version inside the asked range serves the entry", () => {
+    const declared = declares("@platforma-open/milaboratories.demo.kind@1.4.0");
+
+    expect(kindMismatch(ASKED, declared)).toBeUndefined();
+  });
+
+  test("a version outside it does not, and the message names both sides", () => {
+    const message = kindMismatch(ASKED, declares("@platforma-open/milaboratories.demo.kind@2.0.0"));
+
+    expect(message).toContain("@platforma-open/milaboratories.demo.kind@^1.0.0");
+    expect(message).toContain("version 2.0.0");
+  });
+
+  test("a different kind entirely is refused by name", () => {
+    // What a location makes possible: the path still resolves, but what is there now is a
+    // different block than the one the params were written for.
+    const message = kindMismatch(
+      ASKED,
+      declares("@platforma-open/milaboratories.other.kind@1.0.0"),
+    );
+
+    expect(message).toContain("@platforma-open/milaboratories.demo.kind");
+    expect(message).toContain("@platforma-open/milaboratories.other.kind");
+  });
+
+  test("a block declaring no kind cannot serve an entry that names one", () => {
+    // Reachable through a pinned version, which names a package and says nothing about
+    // kinds — so the block it names may well be one built before kinds existed.
+    expect(kindMismatch(ASKED, undefined)).toMatch(/declares no kind/);
+  });
+
+  test("an unreadable declaration is refused rather than thrown", () => {
+    // The entry's own selector was checked when the document was parsed, so a failure here
+    // is the block's stored reference. One bad block must not break the whole apply.
+    expect(kindMismatch(ASKED, declares("no-version-here"))).toMatch(/unreadable kind/);
+  });
+
+  test("the message names no route, so the caller can name the one the entry took", () => {
+    // The check is asked once, of the prepared block, whichever of the three routes found
+    // it. Only the caller knows whether there is a locator to point the reader at.
+    const message = kindMismatch(ASKED, undefined)!;
+
+    expect(message).not.toContain("file:");
+    expect(message).not.toContain("location");
+  });
+});

package/src/model/template_apply.ts

@@ -0,0 +1,128 @@
+import type {
+  BlockKindReference,
+  BlockKindSelectorReference,
+} from "@milaboratories/pl-model-common";
+import { parseKindRef, parseKindSelectorReference } from "@milaboratories/pl-model-common";
+import { selectorToRange } from "@platforma-sdk/block-tools";
+import { ensureError } from "@platforma-sdk/model";
+import * as semver from "semver";
+
+/**
+ * One entry the file describes in a way this project cannot honour.
+ *
+ * Thrown, not returned, and that is the whole failure policy: an apply either creates every
+ * entry or creates none. It travels out through the open transaction, which is therefore
+ * never committed, so a rejected file leaves the project exactly as it was. The caller turns
+ * it into a {@link TemplateApplyProblem}; anything else reaching that caller is an outage
+ * rather than a statement about the file, and keeps propagating.
+ */
+export class TemplateEntryRejected extends Error {
+  constructor(
+    readonly entryId: string,
+    message: string,
+  ) {
+    super(message);
+    this.name = "TemplateEntryRejected";
+  }
+}
+
+/**
+ * Something that stopped one entry from being applied.
+ *
+ * Every stage of an apply reports in this shape — resolution, validation,
+ * construction — so a caller assembles one list and the reader sees which entry in
+ * their file each problem belongs to. `error` is a finished sentence for the person
+ * who applied the file, not a code.
+ */
+export type TemplateApplyProblem = {
+  /** The template-local id of the entry the problem belongs to. */
+  readonly entryId: string;
+  readonly error: string;
+};
+
+/** One entry that made it into the project. */
+export type AppliedEntry = {
+  /** The entry's id in the file. */
+  readonly templateLocalId: string;
+  /** The project-local id the block was given. */
+  readonly blockId: string;
+};
+
+/**
+ * What a whole apply — reading, checking, resolving, placing — left behind.
+ *
+ * One shape for every stage's findings, because the reader does not care which stage
+ * objected. `problems` empty means the project holds exactly what the document described;
+ * otherwise `added` is empty, because no stage creates anything until every entry has passed.
+ *
+ * A stage that checks reports every problem it found, so a file with three mistakes takes one
+ * pass to fix. Placement stops at the first one — hence at most one problem from there.
+ */
+export type TemplateApplyReport = {
+  readonly added: readonly AppliedEntry[];
+  readonly problems: readonly TemplateApplyProblem[];
+};
+
+/**
+ * Why the block prepared for an entry cannot serve it, or `undefined` when it can.
+ *
+ * An entry's `kind` is the contract its params are written against, so the block that ends up
+ * installed has to implement it. Only one of the three routes to a block gives that for free:
+ * kind resolution, where the kind's own projection picks the block. The two overrides do not —
+ * a location's folder can change without the file changing, and a pinned version names a
+ * package with no reference to a kind at all.
+ *
+ * So this belongs here, with the apply's other per-entry checks, and not in resolution: it is
+ * asked once, of the block that was actually prepared, whichever route found it. Resolution
+ * could answer it for a location — `byLocation` reads the block's config anyway — and doing so
+ * there would have been a second place stating the same invariant, with the pinned-version
+ * route still uncovered. One caller is the point.
+ *
+ * It is also the check that makes the params check meaningful, so it is asked first: params are
+ * checked by the INSTALLED block's kind parser, which against a block of the wrong kind would
+ * hold params written for one contract against another.
+ *
+ * Version comparison goes through the same selector-to-range translation the registry resolver
+ * uses, so "this resolves locally" and "this would resolve once published" cannot disagree
+ * about the version math.
+ *
+ * Messages name no route, so a caller adds whichever locator the entry carried.
+ */
+export function kindMismatch(
+  asked: BlockKindSelectorReference,
+  declared: BlockKindReference | undefined,
+): string | undefined {
+  if (declared === undefined) {
+    return (
+      "The block resolved for this entry declares no kind, so it cannot be the " +
+      "implementation it asks for"
+    );
+  }
+
+  let wanted: { name: string; selector: { op: "exact" | "patch" | "minor"; version: string } };
+  let has: { name: string; version: string };
+  try {
+    wanted = parseKindSelectorReference(asked);
+    has = parseKindRef(declared);
+  } catch (e) {
+    // The entry's own selector was checked when the document was parsed, so this is the
+    // block's stored reference being unreadable.
+    return `The block resolved for this entry declares an unreadable kind: ${ensureError(e).message}`;
+  }
+
+  if (wanted.name !== has.name) {
+    return (
+      `This entry asks for kind '${wanted.name}', but the block resolved for it ` +
+      `implements '${has.name}'`
+    );
+  }
+
+  if (!semver.satisfies(has.version, selectorToRange(wanted.selector))) {
+    return (
+      `This entry asks for '${asked}', but the block resolved for it implements ` +
+      `version ${has.version} of that kind`
+    );
+  }
+
+  return undefined;
+}