@platforma-sdk/block-tools 2.10.14 → 2.10.16

package/src/structure/engine/__tests__/content-rules/require-field.test.ts

@@ -0,0 +1,40 @@
+import { describe, test, expect } from "vitest";
+import { requireField, withManagedBody, type JsonObject } from "../../content-rules";
+
+function run(input: JsonObject, body: () => void): JsonObject {
+  return withManagedBody(input, body);
+}
+
+describe("requireField", () => {
+  test("no-op when the field is present", () => {
+    const out = run({ name: "x" }, () => requireField("name"));
+    expect(out).toEqual({ name: "x" });
+  });
+
+  test("throws default message when the field is absent", () => {
+    expect(() =>
+      run({}, () => {
+        requireField("name");
+      }),
+    ).toThrow(/requireField: missing field 'name'/);
+  });
+
+  test("throws custom message when supplied", () => {
+    expect(() =>
+      run({}, () => {
+        requireField("name", "block name is required");
+      }),
+    ).toThrow(/block name is required/);
+  });
+
+  test("accepts a nested field via dotted path", () => {
+    const out = run({ engines: { node: ">=18" } }, () => requireField("engines.node"));
+    expect(out).toEqual({ engines: { node: ">=18" } });
+  });
+
+  test("idempotent — running twice on a present field is a no-op", () => {
+    const once = run({ name: "x" }, () => requireField("name"));
+    const twice = run(JSON.parse(JSON.stringify(once)), () => requireField("name"));
+    expect(twice).toEqual(once);
+  });
+});

package/src/structure/engine/__tests__/content-rules/transform-at.test.ts

@@ -0,0 +1,33 @@
+import { describe, test, expect } from "vitest";
+import { transformAt, withManagedBody, type JsonObject } from "../../content-rules";
+
+function run(input: JsonObject, body: () => void): JsonObject {
+  return withManagedBody(input, body);
+}
+
+describe("transformAt", () => {
+  test("replaces a primitive at the given path", () => {
+    const out = run({ count: 1 }, () => transformAt<number>("count", (v) => (v ?? 0) + 1));
+    expect(out).toEqual({ count: 2 });
+  });
+
+  test("replaces a nested object at the given path", () => {
+    const out = run({ block: { foo: 1 } }, () =>
+      transformAt<{ foo: number }>("block", (v) => ({ ...v, bar: 2 }) as { foo: number }),
+    );
+    expect(out).toEqual({ block: { foo: 1, bar: 2 } });
+  });
+
+  test("auto-creates intermediate objects for missing nested paths", () => {
+    const out = run({}, () => transformAt<string | undefined>("nested.key", () => "ok"));
+    expect(out).toEqual({ nested: { key: "ok" } });
+  });
+
+  test("idempotent — when the lambda is a fixed point, second run is a no-op", () => {
+    const fix = (v: number | undefined) => ((v ?? 0) > 5 ? v! : 5);
+    const once = run({ count: 1 }, () => transformAt<number>("count", fix));
+    const twice = run(JSON.parse(JSON.stringify(once)), () => transformAt<number>("count", fix));
+    expect(once).toEqual({ count: 5 });
+    expect(twice).toEqual(once);
+  });
+});

package/src/structure/engine/__tests__/content-rules/when-inner.test.ts

@@ -0,0 +1,244 @@
+// Unified `when()` — same symbol dispatches by active state.
+//
+// Outer mode (inside `defineStructure`) is covered by existing
+// builders/runner tests. This file covers inner-mode dispatch:
+// `when()` called inside a managed(...) body evaluates the trigger
+// against the runner-supplied TriggerContext and runs / skips the
+// body synchronously.
+
+import { describe, test, expect } from "vitest";
+import { when } from "../../builders";
+import {
+  ensureField,
+  ensureCatalogVersion,
+  ensureGitignoreEntries,
+  removeDep,
+  ensureDep,
+  withManagedBody,
+  withManagedLines,
+  withManagedYaml,
+  type JsonObject,
+} from "../../content-rules";
+import { parseYaml } from "../../parsers/yaml";
+import { createRunContext } from "../../ctx";
+import type { BlockVars, RunContext } from "../../api";
+import type { TriggerContext } from "../../ir";
+
+const vars: BlockVars = {
+  facadeName: "@platforma-open/demo.x",
+  baseName: "demo.x",
+  npmOrg: "@platforma-open",
+  orgScope: "demo",
+  shortName: "x",
+};
+
+const ctx: RunContext = createRunContext({ blockVars: vars, modules: [] });
+
+function makeTctx(
+  opts: {
+    paths?: ReadonlySet<string>;
+    version?: number;
+  } = {},
+): TriggerContext {
+  const paths = opts.paths ?? new Set<string>();
+  return {
+    ctx,
+    version: opts.version ?? 1,
+    pathExists: (p) => paths.has(p),
+    pathMissing: (p) => !paths.has(p),
+    filesMatch: () => false,
+  };
+}
+
+describe("when() — inner-mode dispatch inside managed bodies", () => {
+  test("predicate=true runs the body (JSON state)", () => {
+    const out = withManagedBody(
+      { name: "x" } as JsonObject,
+      () => {
+        when(
+          ({ pathExists }) => pathExists("test-legacy/"),
+          () => {
+            ensureField("flag", "fired");
+          },
+        );
+      },
+      { triggerContext: makeTctx({ paths: new Set(["test-legacy/"]) }) },
+    );
+    expect(out.flag).toBe("fired");
+  });
+
+  test("predicate=false skips the body", () => {
+    const out = withManagedBody(
+      { name: "x" } as JsonObject,
+      () => {
+        when(
+          ({ pathExists }) => pathExists("test-legacy/"),
+          () => {
+            ensureField("flag", "fired");
+          },
+        );
+      },
+      { triggerContext: makeTctx({ paths: new Set() }) },
+    );
+    expect(out.flag).toBeUndefined();
+  });
+
+  test("inner when works inside a YAML managed body", () => {
+    const doc = parseYaml("catalog: {}\n");
+    withManagedYaml(
+      doc,
+      () => {
+        when(
+          ({ ctx }) => !ctx.isSdkInternal,
+          () => {
+            ensureCatalogVersion("@platforma-sdk/model", "1.2.3");
+          },
+        );
+      },
+      { triggerContext: makeTctx() },
+    );
+    const cat = (doc.toJSON() as { catalog: Record<string, string> }).catalog;
+    expect(cat["@platforma-sdk/model"]).toBe("1.2.3");
+  });
+
+  test("inner when works inside a lines managed body", () => {
+    const out = withManagedLines(
+      [],
+      () => {
+        when(
+          ({ version }) => version >= 1,
+          () => {
+            ensureGitignoreEntries(["node_modules/"]);
+          },
+        );
+      },
+      { triggerContext: makeTctx({ version: 1 }) },
+    );
+    expect(out).toEqual(["node_modules/"]);
+  });
+
+  test("inner when nests: outer predicate false short-circuits inner", () => {
+    const seen: string[] = [];
+    withManagedBody(
+      {} as JsonObject,
+      () => {
+        when(
+          () => false,
+          () => {
+            seen.push("outer");
+            when(
+              () => true,
+              () => {
+                seen.push("inner");
+              },
+            );
+          },
+        );
+      },
+      { triggerContext: makeTctx() },
+    );
+    expect(seen).toEqual([]);
+  });
+
+  test("inner when nests: both true → both bodies run", () => {
+    const seen: string[] = [];
+    withManagedBody(
+      {} as JsonObject,
+      () => {
+        when(
+          () => true,
+          () => {
+            seen.push("outer");
+            when(
+              () => true,
+              () => {
+                seen.push("inner");
+              },
+            );
+          },
+        );
+      },
+      { triggerContext: makeTctx() },
+    );
+    expect(seen).toEqual(["outer", "inner"]);
+  });
+
+  test("inner when exposes ctx via the predicate", () => {
+    const out = withManagedBody(
+      {} as JsonObject,
+      () => {
+        when(
+          ({ ctx }) => ctx.blockVars.shortName === "x",
+          () => {
+            ensureField("matched", true);
+          },
+        );
+      },
+      { triggerContext: makeTctx() },
+    );
+    expect(out.matched).toBe(true);
+  });
+
+  test("compound migration pattern: rewrite dep when sibling path exists", () => {
+    const out = withManagedBody(
+      { dependencies: { "test-old": "workspace:*" } } as JsonObject,
+      () => {
+        ensureField("type", "module");
+        when(
+          ({ pathExists }) => pathExists("test-legacy/"),
+          () => {
+            removeDep("test-old");
+            ensureDep("test-legacy", "workspace:*");
+          },
+        );
+      },
+      { triggerContext: makeTctx({ paths: new Set(["test-legacy/"]) }) },
+    );
+    expect(out).toEqual({
+      type: "module",
+      dependencies: { "test-legacy": "workspace:*" },
+    });
+  });
+
+  test("inner when inside a body throws if triggerContext was not supplied", () => {
+    expect(() =>
+      withManagedBody({}, () => {
+        when(
+          () => true,
+          () => {
+            ensureField("x", 1);
+          },
+        );
+      }),
+    ).toThrow(/requires a triggerContext/);
+  });
+
+  test("when() called outside any context throws", () => {
+    expect(() =>
+      when(
+        () => true,
+        () => {},
+      ),
+    ).toThrow(/outside defineStructure.*outside any managed/);
+  });
+
+  test("idempotent — double-run yields the same parsed state", () => {
+    const body = () => {
+      ensureField("type", "module");
+      when(
+        ({ pathExists }) => pathExists("legacy/"),
+        () => {
+          ensureField("legacy-flag", true);
+        },
+      );
+    };
+    const tctx = makeTctx({ paths: new Set(["legacy/"]) });
+    const once = withManagedBody({} as JsonObject, body, {
+      triggerContext: tctx,
+    });
+    const twice = withManagedBody(JSON.parse(JSON.stringify(once)) as JsonObject, body, {
+      triggerContext: tctx,
+    });
+    expect(twice).toEqual(once);
+  });
+});

package/src/structure/engine/__tests__/content-rules/workspace-module-paths.test.ts

@@ -0,0 +1,53 @@
+import { describe, test, expect } from "vitest";
+import { ensureWorkspaceModulePaths, withManagedYaml } from "../../content-rules";
+import { parseYaml, stringifyYaml } from "../../parsers/yaml";
+import { createRunContext } from "../../ctx";
+import type { Module, BlockVars } from "../../api";
+
+const vars: BlockVars = {
+  facadeName: "@platforma-open/demo.feature",
+  baseName: "demo.feature",
+  npmOrg: "@platforma-open",
+  orgScope: "demo",
+  shortName: "feature",
+};
+
+const modules: Module[] = [
+  { scope: "root", name: "@platforma-open/demo.feature", path: "" },
+  { scope: "block", name: "@platforma-open/demo.feature.block", path: "block" },
+  { scope: "model", name: "@platforma-open/demo.feature.model", path: "model" },
+  { scope: "ui", name: "@platforma-open/demo.feature.ui", path: "ui" },
+  { scope: "workflow", name: "@platforma-open/demo.feature.workflow", path: "workflow" },
+  { scope: "test", name: "@platforma-open/demo.feature.test", path: "test" },
+];
+
+const ctx = createRunContext({ blockVars: vars, modules });
+
+describe("ensureWorkspaceModulePaths", () => {
+  // The root module ("") is discovered implicitly and is NEVER written
+  // to `packages:` — listing "." there would break turbo's task graph.
+  const nonRootModules = modules.filter((m) => m.path !== "");
+
+  test("writes a sorted packages list of non-root modules (root excluded)", () => {
+    const doc = parseYaml("packages: []\n");
+    withManagedYaml(doc, () => ensureWorkspaceModulePaths(), { ctx });
+    const json = doc.toJSON() as { packages: string[] };
+    expect(json.packages).toEqual(["block", "model", "test", "ui", "workflow"]);
+  });
+
+  test("creates packages list if missing", () => {
+    const doc = parseYaml("# empty\n");
+    withManagedYaml(doc, () => ensureWorkspaceModulePaths(), { ctx });
+    const json = doc.toJSON() as { packages: string[] };
+    expect(json.packages.length).toBe(nonRootModules.length);
+  });
+
+  test("idempotent — second run leaves the YAML output unchanged", () => {
+    const doc = parseYaml("packages: []\n");
+    withManagedYaml(doc, () => ensureWorkspaceModulePaths(), { ctx });
+    const once = stringifyYaml(doc);
+    withManagedYaml(doc, () => ensureWorkspaceModulePaths(), { ctx });
+    const twice = stringifyYaml(doc);
+    expect(twice).toBe(once);
+  });
+});

package/src/structure/engine/__tests__/discovery.test.ts

@@ -0,0 +1,160 @@
+// Workspace-package classification — covers all 7 detection rules
+// plus the block-scope override and the unclassified-error path.
+
+import { describe, test, expect } from "vitest";
+import { classifyOne, discoverModules, DiscoveryError, type WorkspacePackage } from "../discovery";
+
+function pkg(path: string, data: WorkspacePackage["pkg"]): WorkspacePackage {
+  return { path, pkg: data };
+}
+
+describe("discovery — single-package classification", () => {
+  test("rule 1: software via block-software field", () => {
+    const wp = pkg("software", {
+      name: "x.software",
+      "block-software": {},
+    });
+    expect(classifyOne(wp, new Set())).toBe("software");
+  });
+
+  test("rule 1 alt: software via package-builder + runenv dep", () => {
+    const wp = pkg("software-py", {
+      name: "x.software-py",
+      dependencies: {
+        "@platforma-sdk/package-builder": "catalog:",
+        "@platforma-open/runenv-python-3": "catalog:",
+      },
+    });
+    expect(classifyOne(wp, new Set())).toBe("software");
+  });
+
+  test("rule 2: workflow via workflow-tengo dep", () => {
+    const wp = pkg("workflow", {
+      name: "x.workflow",
+      dependencies: { "@platforma-sdk/workflow-tengo": "catalog:" },
+    });
+    expect(classifyOne(wp, new Set())).toBe("workflow");
+  });
+
+  test("rule 3: ui via ui-vue dep and no main", () => {
+    const wp = pkg("ui", {
+      name: "x.ui",
+      dependencies: { "@platforma-sdk/ui-vue": "catalog:" },
+    });
+    expect(classifyOne(wp, new Set())).toBe("ui");
+  });
+
+  test("rule 4: block via block-tools + sibling model/ui/workflow", () => {
+    const siblings = new Set(["x.model", "x.ui", "x.workflow"]);
+    const wp = pkg("block", {
+      name: "x.block",
+      dependencies: {
+        "@platforma-sdk/block-tools": "catalog:",
+        "x.model": "workspace:*",
+        "x.ui": "workspace:*",
+      },
+    });
+    expect(classifyOne(wp, siblings)).toBe("block");
+  });
+
+  test("rule 4 fallback: files=[index.d.ts,index.js] + block-tools", () => {
+    const wp = pkg("block", {
+      name: "x.block",
+      files: ["index.d.ts", "index.js"],
+      dependencies: { "@platforma-sdk/block-tools": "catalog:" },
+    });
+    expect(classifyOne(wp, new Set())).toBe("block");
+  });
+
+  test("rule 5: model via model dep + main", () => {
+    const wp = pkg("model", {
+      name: "x.model",
+      main: "dist/index.js",
+      dependencies: { "@platforma-sdk/model": "catalog:" },
+    });
+    expect(classifyOne(wp, new Set())).toBe("model");
+  });
+
+  test("rule 6: test via @platforma-sdk/test dep", () => {
+    const wp = pkg("test", {
+      name: "x.test",
+      devDependencies: { "@platforma-sdk/test": "catalog:" },
+    });
+    expect(classifyOne(wp, new Set())).toBe("test");
+  });
+
+  test("rule 7: root as catch-all", () => {
+    const wp = pkg("", { name: "x" });
+    expect(classifyOne(wp, new Set())).toBe("root");
+  });
+
+  test("override: block-scope wins over detection", () => {
+    const wp = pkg("strange-dir", {
+      name: "x.strange",
+      "block-scope": "software",
+      dependencies: { "@platforma-sdk/workflow-tengo": "catalog:" },
+    });
+    expect(classifyOne(wp, new Set())).toBe("software");
+  });
+
+  test("override: bad value throws DiscoveryError", () => {
+    const wp = pkg("x", {
+      name: "x",
+      "block-scope": "nope",
+    });
+    expect(() => classifyOne(wp, new Set())).toThrow(DiscoveryError);
+  });
+
+  test("unclassified non-root throws DiscoveryError", () => {
+    const wp = pkg("orphan", { name: "x.orphan" });
+    expect(() => discoverModules([wp])).toThrow(DiscoveryError);
+  });
+});
+
+describe("discovery — full workspace", () => {
+  test("classifies an example workspace", () => {
+    const packages: WorkspacePackage[] = [
+      pkg("", { name: "x" }),
+      pkg("model", {
+        name: "x.model",
+        main: "dist/index.js",
+        dependencies: { "@platforma-sdk/model": "catalog:" },
+      }),
+      pkg("ui", {
+        name: "x.ui",
+        dependencies: { "@platforma-sdk/ui-vue": "catalog:" },
+      }),
+      pkg("workflow", {
+        name: "x.workflow",
+        dependencies: { "@platforma-sdk/workflow-tengo": "catalog:" },
+      }),
+      pkg("test", {
+        name: "x.test",
+        devDependencies: { "@platforma-sdk/test": "catalog:" },
+      }),
+      pkg("block", {
+        name: "x.block",
+        dependencies: {
+          "@platforma-sdk/block-tools": "catalog:",
+          "x.model": "workspace:*",
+          "x.ui": "workspace:*",
+          "x.workflow": "workspace:*",
+        },
+      }),
+      pkg("software-py", {
+        name: "x.software-py",
+        dependencies: {
+          "@platforma-sdk/package-builder": "catalog:",
+          "@platforma-open/runenv-python-3": "catalog:",
+        },
+      }),
+    ];
+    const mods = discoverModules(packages);
+    const byScope = Object.fromEntries(mods.map((m) => [m.scope, m]));
+    expect(Object.keys(byScope).sort()).toEqual(
+      ["block", "model", "root", "software", "test", "ui", "workflow"].sort(),
+    );
+    expect(byScope.root!.path).toBe("");
+    expect(byScope.software!.path).toBe("software-py");
+  });
+});

package/src/structure/engine/__tests__/fs-memory.test.ts

@@ -0,0 +1,59 @@
+// In-memory FileSystem round-trip.
+//
+// Covers read/write, exists for files and synthesised directories,
+// recursive listing, move (file + directory), and recursive delete.
+
+import { describe, test, expect } from "vitest";
+import { MemoryFileSystem } from "../fs/memory";
+
+describe("MemoryFileSystem", () => {
+  test("write + read + exists", async () => {
+    const fs = new MemoryFileSystem();
+    expect(fs.exists("a.json")).toBe(false);
+    fs.write("a.json", "{}");
+    expect(fs.read("a.json")).toBe("{}");
+    expect(fs.exists("a.json")).toBe(true);
+  });
+
+  test("directory exists when a child file is present", async () => {
+    const fs = new MemoryFileSystem({ "model/package.json": "{}" });
+    expect(fs.exists("model")).toBe(true);
+    expect(fs.exists("model/")).toBe(true);
+    expect(fs.exists("ui")).toBe(false);
+  });
+
+  test("list recurses", async () => {
+    const fs = new MemoryFileSystem({
+      "a.txt": "1",
+      "b/c.txt": "2",
+      "b/d/e.txt": "3",
+    });
+    expect(fs.list("")).toEqual(["a.txt", "b/c.txt", "b/d/e.txt"]);
+    expect(fs.list("b")).toEqual(["b/c.txt", "b/d/e.txt"]);
+    expect(fs.list("missing")).toEqual([]);
+  });
+
+  test("move renames directory subtrees", async () => {
+    const fs = new MemoryFileSystem({
+      "test/a.ts": "x",
+      "test/b/c.ts": "y",
+      "keep.txt": "z",
+    });
+    fs.move("test", "test-legacy");
+    expect(fs.exists("test")).toBe(false);
+    expect(fs.read("test-legacy/a.ts")).toBe("x");
+    expect(fs.read("test-legacy/b/c.ts")).toBe("y");
+    expect(fs.read("keep.txt")).toBe("z");
+  });
+
+  test("delete is recursive and idempotent", async () => {
+    const fs = new MemoryFileSystem({
+      "x/y.ts": "1",
+      "x/z.ts": "2",
+    });
+    fs.delete("x");
+    expect(fs.exists("x")).toBe(false);
+    fs.delete("x"); // no-op
+    expect(fs.exists("x")).toBe(false);
+  });
+});

package/src/structure/engine/__tests__/glob.test.ts

@@ -0,0 +1,43 @@
+import { describe, test, expect } from "vitest";
+import { matchesGlob } from "../glob";
+
+describe("matchesGlob", () => {
+  test("`*` matches within a segment, not across `/`", () => {
+    expect(matchesGlob("src/*.test.ts", "src/foo.test.ts")).toBe(true);
+    expect(matchesGlob("src/*.test.ts", "src/foo.ts")).toBe(false);
+    // `*` does not cross a slash
+    expect(matchesGlob("src/*.test.ts", "src/sub/foo.test.ts")).toBe(false);
+  });
+
+  test("`**/` matches any depth, including zero segments", () => {
+    expect(matchesGlob("src/**/*.test.ts", "src/foo.test.ts")).toBe(true);
+    expect(matchesGlob("src/**/*.test.ts", "src/sub/foo.test.ts")).toBe(true);
+    expect(matchesGlob("src/**/*.test.ts", "src/a/b/c/foo.test.ts")).toBe(true);
+    expect(matchesGlob("src/**/*.test.ts", "src/foo.ts")).toBe(false);
+    expect(matchesGlob("src/**/*.test.ts", "other/foo.test.ts")).toBe(false);
+  });
+
+  test("module-relative prefixes compose (as the runner resolves them)", () => {
+    expect(matchesGlob("model/src/**/*.test.ts", "model/src/label.test.ts")).toBe(true);
+    expect(matchesGlob("model/src/**/*.test.ts", "ui/src/label.test.ts")).toBe(false);
+    expect(matchesGlob("workflow/src/**/*.test.ts", "workflow/src/test/columns.test.ts")).toBe(
+      true,
+    );
+  });
+
+  test("literal dots are not wildcards", () => {
+    expect(matchesGlob("a.b", "axb")).toBe(false);
+    expect(matchesGlob("a.b", "a.b")).toBe(true);
+  });
+
+  test("`?` matches exactly one non-slash char", () => {
+    expect(matchesGlob("src/?.ts", "src/a.ts")).toBe(true);
+    expect(matchesGlob("src/?.ts", "src/ab.ts")).toBe(false);
+    expect(matchesGlob("src/?.ts", "src//.ts")).toBe(false);
+  });
+
+  test("whole-path anchored (no partial matches)", () => {
+    expect(matchesGlob("src/*.ts", "x/src/foo.ts")).toBe(false);
+    expect(matchesGlob("src/*.ts", "src/foo.ts.bak")).toBe(false);
+  });
+});