@platforma-sdk/block-tools 2.10.13 → 2.10.15

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

@@ -0,0 +1,136 @@
+// Engine runner — structural pass, managed pass, mode semantics.
+//
+// Covers:
+//   - init (fresh FS): structural + managed primitives all fire.
+//   - refresh (post-init same FS): idempotent — second run is no-op.
+//   - check (dryRun): no writes; same changes reported as refresh would.
+//   - .structure is written only in refresh default mode (not check,
+//     not --update-deps-only).
+
+import { describe, test, expect } from "vitest";
+import { defineStructure, scope, managed, fixed, remove, text, generate } from "../api";
+import type { Structure } from "../ir";
+import type { RunContext } from "../api";
+import { createRunContext } from "../ctx";
+import { MemoryFileSystem } from "../fs/memory";
+import { run } from "../runner";
+import { ensureField } from "../content-rules";
+import { STRUCTURE_META_FILE, STRUCTURE_VERSION } from "../version";
+
+function syntheticStructure(): Structure {
+  return defineStructure(() => {
+    scope("root", () => {
+      fixed("turbo.json", text('{ "$schema": "https://turbo.build/schema.json" }\n'));
+      remove("legacy.txt");
+      managed(
+        "package.json",
+        generate(() => ({ name: "demo", version: "1.0.0" })),
+        () => {
+          ensureField("type", "module");
+          ensureField("scripts.build", "echo build");
+        },
+      );
+    });
+    scope("model", () => {
+      fixed("tsconfig.json", text('{ "extends": "../tsconfig.base.json" }\n'));
+    });
+  });
+}
+
+function ctxFor(opts: Partial<RunContext> = {}): RunContext {
+  return createRunContext({
+    blockVars: {
+      facadeName: "@platforma-open/demo",
+      baseName: "demo",
+      npmOrg: "@platforma-open",
+      orgScope: "demo",
+      shortName: "demo",
+    },
+    modules: [
+      { scope: "root", name: "@platforma-open/demo", path: "" },
+      { scope: "model", name: "@platforma-open/demo.model", path: "model" },
+    ],
+    ...opts,
+  });
+}
+
+describe("runner — init + refresh + check", () => {
+  test("init (fresh FS): structural + managed primitives all fire", async () => {
+    const fs = new MemoryFileSystem();
+    const ctx = ctxFor();
+    const result = run(syntheticStructure(), fs, ctx);
+    // Expected changes: fixed root/turbo.json + managed root/package.json
+    // + fixed model/tsconfig.json. remove("legacy.txt") is no-op (file
+    // never existed). Plus the .structure-version write at end (not in
+    // change list).
+    const paths = result.changes.map((c) => c.path).sort();
+    expect(paths).toContain("turbo.json");
+    expect(paths).toContain("package.json");
+    expect(paths).toContain("model/tsconfig.json");
+    expect(paths).not.toContain("legacy.txt");
+
+    // Files actually written.
+    expect(fs.exists("turbo.json")).toBe(true);
+    expect(fs.exists("model/tsconfig.json")).toBe(true);
+    const pkg = JSON.parse(fs.read("package.json"));
+    expect(pkg.type).toBe("module");
+    expect(pkg.scripts.build).toBe("echo build");
+    // .structure-version written.
+    expect(fs.exists(STRUCTURE_META_FILE)).toBe(true);
+    expect(JSON.parse(fs.read(STRUCTURE_META_FILE))).toEqual({
+      version: STRUCTURE_VERSION,
+    });
+  });
+
+  test("refresh (second run on same FS): idempotent — zero changes", async () => {
+    const fs = new MemoryFileSystem();
+    const ctx = ctxFor();
+    run(syntheticStructure(), fs, ctx);
+    const second = run(syntheticStructure(), fs, ctx);
+    expect(second.changes).toEqual([]);
+  });
+
+  test("check (dryRun): no writes; reports what refresh would do", async () => {
+    const fs = new MemoryFileSystem();
+    const ctx = ctxFor({ dryRun: true });
+    const result = run(syntheticStructure(), fs, ctx);
+    // Reports the same primitives that refresh would apply.
+    const paths = result.changes.map((c) => c.path).sort();
+    expect(paths).toContain("turbo.json");
+    expect(paths).toContain("package.json");
+    expect(paths).toContain("model/tsconfig.json");
+    // No actual writes.
+    expect(fs.exists("turbo.json")).toBe(false);
+    expect(fs.exists(STRUCTURE_META_FILE)).toBe(false);
+  });
+
+  test("refresh removes a file that does exist", async () => {
+    const fs = new MemoryFileSystem({ "legacy.txt": "x" });
+    const ctx = ctxFor();
+    const result = run(syntheticStructure(), fs, ctx);
+    const removed = result.changes.find((c) => c.primitive === "remove");
+    expect(removed).toBeDefined();
+    expect(removed!.path).toBe("legacy.txt");
+    expect(fs.exists("legacy.txt")).toBe(false);
+  });
+});
+
+describe("runner — .structure write gated by mode", () => {
+  test("refresh default mode writes .structure", async () => {
+    const fs = new MemoryFileSystem();
+    run(syntheticStructure(), fs, ctxFor());
+    expect(fs.exists(STRUCTURE_META_FILE)).toBe(true);
+  });
+
+  test("check (dryRun) does NOT write .structure", async () => {
+    const fs = new MemoryFileSystem();
+    run(syntheticStructure(), fs, ctxFor({ dryRun: true }));
+    expect(fs.exists(STRUCTURE_META_FILE)).toBe(false);
+  });
+
+  test("refresh --update-deps-only does NOT write .structure", async () => {
+    const fs = new MemoryFileSystem();
+    run(syntheticStructure(), fs, ctxFor({ updateDepsOnly: true }));
+    expect(fs.exists(STRUCTURE_META_FILE)).toBe(false);
+  });
+});

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

@@ -0,0 +1,153 @@
+// Synthetic-fixture round trip through the IR.
+//
+// Exercises module-global builders: `defineStructure(() => { ... })`
+// with builders imported by name. Covers a scope frame, a when frame, both
+// mode frames (`onUpdateDeps` and `onInitOrUpdate`), a rename. Asserts IR
+// shape, the post-flatten ordered list (including the per-leaf `modes`
+// set), and that two independent build invocations produce
+// structurally-equal trees (the active-context machinery resets cleanly
+// between runs).
+
+import { describe, test, expect } from "vitest";
+import {
+  defineStructure,
+  scope,
+  when,
+  onUpdateDeps,
+  onInitOrUpdate,
+  fixed,
+  managed,
+  remove,
+  rename,
+  file,
+} from "../api";
+import type { Structure } from "../ir";
+import { flatten } from "../flatten";
+import { createRunContext } from "../ctx";
+
+function buildStructure(): Structure {
+  return defineStructure(() => {
+    scope("root", () => {
+      fixed("turbo.json", file("root/turbo.json"));
+      remove(".prettierrc");
+      managed("package.json", file("root/package.json"), () => {
+        /* body — stub */
+      });
+      when(
+        ({ ctx }) => !ctx.isSdkInternal,
+        () => {
+          rename("test/", "test-legacy/");
+        },
+      );
+    });
+    scope("model", () => {
+      fixed("tsconfig.json", file("model/tsconfig.json"));
+    });
+    onUpdateDeps(() => {
+      scope("root", () => {
+        managed("pnpm-workspace.yaml", file("root/pnpm-workspace.yaml"), () => {
+          /* update-deps-only catalog bumps live here */
+        });
+      });
+    });
+    onInitOrUpdate(() => {
+      scope("root", () => {
+        managed("catalog.yaml", file("root/catalog.yaml"), () => {
+          /* init + update-deps version resolution lives here */
+        });
+      });
+    });
+  });
+}
+
+describe("synthetic fixture", () => {
+  test("IR shape matches expectation", () => {
+    const s = buildStructure();
+    expect(s.children.length).toBe(4);
+    const rootFrame = s.children[0]!;
+    expect(rootFrame.kind).toBe("scope");
+    if (rootFrame.kind !== "scope") throw new Error("unreachable");
+    expect(rootFrame.scope).toBe("root");
+    expect(rootFrame.children.length).toBe(4);
+    expect(rootFrame.children[0]!.kind).toBe("fixed");
+    expect(rootFrame.children[1]!.kind).toBe("remove");
+    expect(rootFrame.children[2]!.kind).toBe("managed");
+    expect(rootFrame.children[3]!.kind).toBe("when");
+    // Both mode frames flatten to `kind: "mode"`, distinguished by `modes`.
+    const updFrame = s.children[2]!;
+    const initUpdFrame = s.children[3]!;
+    expect(updFrame.kind).toBe("mode");
+    expect(initUpdFrame.kind).toBe("mode");
+    if (updFrame.kind !== "mode" || initUpdFrame.kind !== "mode") throw new Error("unreachable");
+    expect(updFrame.modes).toEqual(["updateDeps"]);
+    expect(initUpdFrame.modes).toEqual(["init", "updateDeps"]);
+  });
+
+  test("flatten produces expected flat-item list (per-leaf modes tagged)", () => {
+    const s = buildStructure();
+    const ctx = createRunContext({
+      blockVars: {
+        facadeName: "@platforma-open/x.demo",
+        baseName: "x.demo",
+        npmOrg: "@platforma-open",
+        orgScope: "x",
+        shortName: "demo",
+      },
+      modules: [
+        { scope: "root", name: "@platforma-open/x.demo", path: "" },
+        { scope: "model", name: "@platforma-open/x.demo.model", path: "model" },
+      ],
+    });
+    const flat = flatten(s, ctx);
+    // 4 leaves in root scope + 1 in model + 1 in onUpdateDeps→root + 1 in
+    // onInitOrUpdate→root.
+    expect(flat.length).toBe(7);
+    expect(flat[0]!.resolvedPath).toBe("turbo.json");
+    // A normal leaf fires on default refresh/check + init, never update-deps.
+    expect(flat[0]!.modes).toEqual(["default", "init"]);
+
+    const renameItem = flat.find((f) => f.leaf.kind === "rename");
+    expect(renameItem).toBeDefined();
+    expect(renameItem!.resolvedPath).toBe("test/");
+    expect(renameItem!.resolvedTo).toBe("test-legacy/");
+    expect(renameItem!.triggers.length).toBe(1);
+
+    const updOnly = flat.find((f) => f.resolvedPath === "pnpm-workspace.yaml");
+    expect(updOnly!.modes).toEqual(["updateDeps"]);
+
+    const initOrUpd = flat.find((f) => f.resolvedPath === "catalog.yaml");
+    expect(initOrUpd!.modes).toEqual(["init", "updateDeps"]);
+
+    // Leaves that fire in update-deps mode = both mode-framed leaves.
+    const updItems = flat.filter((f) => f.modes.includes("updateDeps"));
+    expect(updItems.map((f) => f.resolvedPath).sort()).toEqual([
+      "catalog.yaml",
+      "pnpm-workspace.yaml",
+    ]);
+  });
+
+  test("two builds produce structurally-equal trees", () => {
+    const a = buildStructure();
+    const b = buildStructure();
+    // Functions inside the tree (trigger, body, generate) won't
+    // compare deep-equal across builds — strip them for the shape
+    // check.
+    const strip = (val: unknown): unknown => {
+      if (typeof val === "function") return "[fn]";
+      if (Array.isArray(val)) return val.map(strip);
+      if (val && typeof val === "object") {
+        const out: Record<string, unknown> = {};
+        for (const [k, v] of Object.entries(val as object)) {
+          out[k] = strip(v);
+        }
+        return out;
+      }
+      return val;
+    };
+    expect(strip(a)).toEqual(strip(b));
+  });
+
+  test("builder called outside defineStructure throws", () => {
+    expect(() => fixed("oops.json", file("nope"))).toThrow(/defineStructure/);
+  });
+});

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

@@ -0,0 +1,44 @@
+// `.structure` metadata file handling: read default, read parsed
+// value, write, floor enforcement.
+
+import { describe, test, expect } from "vitest";
+import { MemoryFileSystem } from "../fs/memory";
+import {
+  readStructureVersion,
+  writeStructureVersion,
+  assertVersionAboveFloor,
+  STRUCTURE_VERSION,
+  StructureVersionFloorError,
+} from "../version";
+
+describe(".structure metadata file", () => {
+  test("missing file reads as 0", async () => {
+    const fs = new MemoryFileSystem();
+    expect(await readStructureVersion(fs)).toBe(0);
+  });
+
+  test("write then read round-trips", async () => {
+    const fs = new MemoryFileSystem();
+    await writeStructureVersion(fs, 3);
+    expect(await readStructureVersion(fs)).toBe(3);
+    const written = fs.read(".structure");
+    expect(JSON.parse(written)).toEqual({ version: 3 });
+  });
+
+  test("default write uses STRUCTURE_VERSION", async () => {
+    const fs = new MemoryFileSystem();
+    await writeStructureVersion(fs);
+    expect(await readStructureVersion(fs)).toBe(STRUCTURE_VERSION);
+  });
+
+  test("floor check throws below floor", () => {
+    expect(() => assertVersionAboveFloor(2, 3)).toThrow(StructureVersionFloorError);
+    expect(() => assertVersionAboveFloor(3, 3)).not.toThrow();
+    expect(() => assertVersionAboveFloor(0, 0)).not.toThrow();
+  });
+
+  test("invalid JSON reads as 0", async () => {
+    const fs = new MemoryFileSystem({ ".structure": "not-json" });
+    expect(await readStructureVersion(fs)).toBe(0);
+  });
+});

package/src/structure/engine/__tests__/when-files-exist.test.ts

@@ -0,0 +1,89 @@
+// `whenFilesExist` resolves its glob MODULE-RELATIVE to the leaf's bound
+// module, so the same predicate gates differently per scope when a scope
+// frame fans out. Drives the real runner so the per-item TriggerContext
+// threading (modulePath -> filesMatch) is exercised end-to-end.
+
+import { describe, test, expect } from "vitest";
+import { defineStructure, managed, scope, generate, when, whenFilesExist } from "../api";
+import type { Structure } from "../ir";
+import { createRunContext } from "../ctx";
+import { MemoryFileSystem } from "../fs/memory";
+import { run } from "../runner";
+import { ensureField } from "../content-rules";
+
+function structure(): Structure {
+  return defineStructure(() => {
+    for (const s of ["model", "ui"] as const) {
+      scope(s, () => {
+        managed(
+          "tsconfig.json",
+          generate(() => ({ extends: "base" })),
+          () => {
+            when(whenFilesExist("src/**/*.test.ts"), () => {
+              ensureField("compilerOptions.types", ["node"]);
+            });
+          },
+        );
+      });
+    }
+  });
+}
+
+function ctx() {
+  return createRunContext({
+    blockVars: {
+      facadeName: "@platforma-open/demo",
+      baseName: "demo",
+      npmOrg: "@platforma-open",
+      orgScope: "demo",
+      shortName: "demo",
+    },
+    modules: [
+      { scope: "model", name: "@platforma-open/demo.model", path: "model" },
+      { scope: "ui", name: "@platforma-open/demo.ui", path: "ui" },
+    ],
+  });
+}
+
+async function typesOf(fs: MemoryFileSystem, scopePath: string): Promise<unknown> {
+  const json = JSON.parse(fs.read(`${scopePath}/tsconfig.json`)) as {
+    compilerOptions?: { types?: unknown };
+  };
+  return json.compilerOptions?.types;
+}
+
+describe("whenFilesExist — module-relative gating via the runner", () => {
+  test("gates per module: only the scope whose own src has a test file fires", async () => {
+    const fs = new MemoryFileSystem();
+    // A co-located test under model/, none under ui/.
+    fs.write("model/src/label.test.ts", "// test");
+    fs.write("ui/src/main.ts", "// not a test");
+
+    run(structure(), fs, ctx());
+
+    expect(await typesOf(fs, "model")).toEqual(["node"]);
+    // ui has no test file -> predicate false -> no node types.
+    expect(await typesOf(fs, "ui")).toBeUndefined();
+  });
+
+  test("nested test path (src/test/*.test.ts) still matches via **", async () => {
+    const fs = new MemoryFileSystem();
+    fs.write("ui/src/test/import.test.ts", "// nested test");
+
+    run(structure(), fs, ctx());
+
+    expect(await typesOf(fs, "ui")).toEqual(["node"]);
+    expect(await typesOf(fs, "model")).toBeUndefined();
+  });
+
+  test("no test files anywhere -> neither scope gets node types", async () => {
+    const fs = new MemoryFileSystem();
+    fs.write("model/src/index.ts", "// source");
+    fs.write("ui/src/main.ts", "// source");
+
+    run(structure(), fs, ctx());
+
+    expect(await typesOf(fs, "model")).toBeUndefined();
+    expect(await typesOf(fs, "ui")).toBeUndefined();
+  });
+});

package/src/structure/engine/api.ts

@@ -0,0 +1,131 @@
+// Public API of the structurer engine.
+//
+// `defineStructure(() => { ... })` is the single entry point. Inside
+// the lambda, rule authors call builders imported by name from this
+// module — `scope`, `when`, `fixed`, `managed`, `scaffold`, `seed`,
+// `remove`, `rename`, `onUpdateDeps`, plus the content-form helpers
+// `file` / `text` / `tpl` / `generate`. Builders read a module-global
+// active context (set up by `defineStructure`) and append to its tree.
+// Calling a builder outside `defineStructure` throws at runtime.
+
+import type { ContentForm, ManagedBody, RunMode, Structure, TriggerFn } from "./ir";
+
+export type Scope = "root" | "block" | "model" | "ui" | "workflow" | "test" | "software";
+
+/** Variables describing a block — populated by `init` or parsed by
+ *  `check`/`refresh` from the block's package.json `name`. */
+export type BlockVars = {
+  /** e.g. `@platforma-open/my-org.mixcr-clonotyping` */
+  facadeName: string;
+  /** e.g. `my-org.mixcr-clonotyping` */
+  baseName: string;
+  /** e.g. `@platforma-open` */
+  npmOrg: string;
+  /** e.g. `my-org` */
+  orgScope: string;
+  /** e.g. `mixcr-clonotyping` */
+  shortName: string;
+  /** Platform picked at init for the (single) software sub-package.
+   *  Only populated by `init`; absent on `check` / `refresh`. Blocks
+   *  that legitimately have multiple software modules (encountered via
+   *  DISCOVERY on refresh) are not affected — this field only governs
+   *  what `init` scaffolds. */
+  softwarePlatform?: string;
+};
+
+/** Discovered workspace module. */
+export type Module = {
+  scope: Scope;
+  /** Package name from the module's package.json. */
+  name: string;
+  /** Block-relative path of the module ("" for workspace root). */
+  path: string;
+};
+
+/** Run context — passed into engine.run and surfaced inside trigger
+ *  predicates as the `ctx` field. */
+export type RunContext = {
+  /** `--sdk-internal` flag. */
+  isSdkInternal: boolean;
+  /** `--update-deps-only` flag. When true, the run is in mode
+   *  `"updateDeps"`: only `onUpdateDeps` / `onInitOrUpdate` leaves fire;
+   *  all default-mode leaves are skipped. The caller is then expected to
+   *  run `pnpm install` and re-invoke `refresh` without the flag for the
+   *  default-mode rules to apply against the updated dep set. */
+  updateDepsOnly: boolean;
+  /** Discovered modules (every scope). */
+  modules: Module[];
+  /** Block vars; on `init` populated from flags/prompts, on
+   *  `check`/`refresh` parsed from block/package.json. */
+  blockVars: BlockVars;
+  /** Layout version read from `.structure`. */
+  version: number;
+  /** True for `check` mode and the post-run recheck. */
+  dryRun: boolean;
+};
+
+export type { ContentForm, ManagedBody, RunMode, Structure, TriggerFn };
+
+export {
+  defineStructure,
+  scope,
+  when,
+  whenFilesExist,
+  onUpdateDeps,
+  onInitOrUpdate,
+  fixed,
+  managed,
+  scaffold,
+  seed,
+  remove,
+  rename,
+  file,
+  binaryFile,
+  text,
+  tpl,
+  generate,
+  blockVars,
+} from "./builders";
+
+export {
+  // JSON managed builders
+  ensureField,
+  removeField,
+  requireField,
+  ensureFieldEntries,
+  ensureScript,
+  removeScript,
+  ensureDep,
+  ensureDevDep,
+  ensurePeerDep,
+  ensureOptionalDep,
+  removeDep,
+  ensureDeps,
+  ensureDevDeps,
+  ensurePeerDeps,
+  ensureOptionalDeps,
+  ensureWorkspaceScopeDeps,
+  ensureWorkspaceScopeDevDeps,
+  ensureWorkspaceScopePeerDeps,
+  pruneKeysMatching,
+  pruneKeysMatchingAt,
+  enforceFieldOrder,
+  enforceFieldOrderAt,
+  enforceAlphabeticalOrder,
+  transformAt,
+  // YAML managed builders
+  ensureWorkspaceModulePaths,
+  ensureCatalogVersion,
+  pinCatalogTo,
+  ensureCatalogLatest,
+  ensureCatalogAbsent,
+  // Lines managed builders
+  ensureGitignoreEntries,
+  removeGitignoreEntries,
+  // Active-state wrappers (engine-internal but exported for tests).
+  withManagedBody,
+  withManagedYaml,
+  withManagedLines,
+} from "./content-rules";
+
+export type { DepVersion } from "./content-rules";