@platforma-sdk/block-tools 2.10.13 → 2.10.15

package/src/structure/engine/__tests__/parsers-json.test.ts

@@ -0,0 +1,189 @@
+// JSON parser primitives — round trip, jsonPath set/get/has/delete,
+// top-level key reorder behaviour.
+
+import { describe, test, expect } from "vitest";
+import {
+  parseJson,
+  stringifyJson,
+  getAtPath,
+  hasAtPath,
+  setAtPath,
+  deleteAtPath,
+  reorderTopLevel,
+} from "../parsers/json";
+import type { JsonObject } from "../parsers/json";
+
+describe("JSON parser — round trip + jsonPath helpers", () => {
+  test("parse + stringify is stable on canonical input", () => {
+    const raw = '{\n  "a": 1,\n  "b": {\n    "c": 2\n  }\n}\n';
+    const parsed = parseJson(raw);
+    expect(stringifyJson(parsed)).toBe(raw);
+  });
+
+  test("stringify preserves source key order even when not alphabetical", () => {
+    // V8 / spec: JSON.parse + JSON.stringify preserve insertion order for
+    // string keys. The structurer's "no implicit ordering" guarantee
+    // depends on this — verify it here so a future runtime change is
+    // caught.
+    const raw = '{\n  "z": 1,\n  "a": 2,\n  "m": 3\n}\n';
+    const parsed = parseJson(raw);
+    expect(Object.keys(parsed as object)).toEqual(["z", "a", "m"]);
+    expect(stringifyJson(parsed)).toBe(raw);
+  });
+
+  test("collapse: arrays within print width go on one line, wide ones break", () => {
+    // oxfmt's generic-.json shape (tsconfig et al.): the object expands one
+    // property per line while a short array collapses onto its line. The
+    // single-element `include` array — the case that regressed output to
+    // non-oxfmt-clean under JSON.stringify (which expanded it) — must collapse.
+    const tsconfig = { extends: "@milaboratories/ts-configs/block/model", include: ["src/**/*"] };
+    expect(stringifyJson(tsconfig, { collapse: true })).toBe(
+      '{\n  "extends": "@milaboratories/ts-configs/block/model",\n  "include": ["src/**/*"]\n}\n',
+    );
+    // A line wider than PRINT_WIDTH (100) breaks one element per line.
+    const x = "x".repeat(40);
+    const y = "y".repeat(40);
+    const z = "z".repeat(40);
+    const wide = { a: [x, y, z] };
+    expect(stringifyJson(wide, { collapse: true })).toBe(
+      `{\n  "a": [\n    "${x}",\n    "${y}",\n    "${z}"\n  ]\n}\n`,
+    );
+  });
+
+  test("default (no collapse) keeps every container expanded — the package.json shape", () => {
+    // Without { collapse }, output is byte-identical to JSON.stringify(_, 2):
+    // package.json must stay fully expanded to match oxfmt's package.json
+    // formatting (which never collapses).
+    const value = { include: ["src/**/*"], deps: { a: "1.0.0" } };
+    expect(stringifyJson(value)).toBe(JSON.stringify(value, null, 2) + "\n");
+  });
+
+  test("collapse: empty containers stay compact, non-empty objects expand", () => {
+    // Empty `[]` / `{}` render inline; a non-empty object always breaks one
+    // property per line (oxfmt preserves the expanded object, arrays collapse
+    // by width).
+    expect(stringifyJson({ a: [], b: {}, c: { d: 1 } }, { collapse: true })).toBe(
+      '{\n  "a": [],\n  "b": {},\n  "c": {\n    "d": 1\n  }\n}\n',
+    );
+  });
+
+  test("getAtPath / hasAtPath", () => {
+    const obj: JsonObject = { a: { b: { c: 42 } } };
+    expect(getAtPath(obj, "a.b.c")).toBe(42);
+    expect(getAtPath(obj, "a.b")).toEqual({ c: 42 });
+    expect(getAtPath(obj, "missing")).toBeUndefined();
+    expect(hasAtPath(obj, "a.b.c")).toBe(true);
+    expect(hasAtPath(obj, "a.b.z")).toBe(false);
+  });
+
+  test("setAtPath auto-creates intermediate objects", () => {
+    const obj: JsonObject = {};
+    setAtPath(obj, "a.b.c", "x");
+    expect(obj).toEqual({ a: { b: { c: "x" } } });
+    setAtPath(obj, "a.b.c", "y");
+    expect(obj).toEqual({ a: { b: { c: "y" } } });
+  });
+
+  test("setAtPath refuses to overwrite a non-object on the way down", () => {
+    const obj: JsonObject = { a: 1 };
+    expect(() => setAtPath(obj, "a.b", 2)).toThrow(/non-object/);
+  });
+
+  test("deleteAtPath removes the leaf, no-op on missing", () => {
+    const obj: JsonObject = { a: { b: 1, c: 2 } };
+    deleteAtPath(obj, "a.b");
+    expect(obj).toEqual({ a: { c: 2 } });
+    deleteAtPath(obj, "a.b");
+    expect(obj).toEqual({ a: { c: 2 } });
+    deleteAtPath(obj, "missing.path");
+    expect(obj).toEqual({ a: { c: 2 } });
+  });
+});
+
+describe("reorderTopLevel — known keys ordered, unknowns ride preceding known", () => {
+  const ORDER = ["name", "version", "private", "scripts", "dependencies", "pnpm"];
+
+  test("worked example preserves grouping", () => {
+    const input: JsonObject = {
+      name: "x",
+      private: true,
+      myCustomA: 1,
+      scripts: {},
+      myCustomB: 2,
+      dependencies: {},
+    };
+    const out = reorderTopLevel(input, ORDER);
+    expect(Object.keys(out)).toEqual([
+      "name",
+      "private",
+      "myCustomA",
+      "scripts",
+      "myCustomB",
+      "dependencies",
+    ]);
+  });
+
+  test("known keys move into declared order", () => {
+    const input: JsonObject = {
+      scripts: {},
+      private: true,
+      name: "x",
+    };
+    const out = reorderTopLevel(input, ORDER);
+    expect(Object.keys(out)).toEqual(["name", "private", "scripts"]);
+  });
+
+  test("unknown leading keys go first, in source order", () => {
+    const input: JsonObject = {
+      leading: 1,
+      another: 2,
+      name: "x",
+    };
+    const out = reorderTopLevel(input, ORDER);
+    expect(Object.keys(out)).toEqual(["leading", "another", "name"]);
+  });
+
+  test("idempotent — second reorder is a no-op", () => {
+    const input: JsonObject = {
+      name: "x",
+      private: true,
+      myCustom: 1,
+      scripts: {},
+    };
+    const once = reorderTopLevel(input, ORDER);
+    const twice = reorderTopLevel(once, ORDER);
+    expect(twice).toEqual(once);
+  });
+
+  test("reorder survives stringify → parse → stringify round-trip", () => {
+    // The structurer writes a managed file via stringifyJson(parsed)
+    // after reordering. A subsequent run parses that file again and
+    // must observe the same key order — otherwise the engine would
+    // report a diff and the post-run recheck would fail. Lock the
+    // contract here.
+    const input: JsonObject = {
+      scripts: { build: "x" },
+      private: true,
+      myCustomA: 1,
+      name: "demo",
+      myCustomB: 2,
+      dependencies: { foo: "1.0.0" },
+    };
+    const reordered = reorderTopLevel(input, ORDER);
+    const serialised = stringifyJson(reordered);
+    const reparsed = parseJson(serialised) as JsonObject;
+    // Source: scripts, private, myCustomA, name, myCustomB, dependencies.
+    //   myCustomA followed `private` → rides private.
+    //   myCustomB followed `name`    → rides name.
+    expect(Object.keys(reparsed)).toEqual([
+      "name",
+      "myCustomB",
+      "private",
+      "myCustomA",
+      "scripts",
+      "dependencies",
+    ]);
+    // Second reorder + serialise must be byte-identical to the first.
+    expect(stringifyJson(reorderTopLevel(reparsed, ORDER))).toBe(serialised);
+  });
+});

package/src/structure/engine/__tests__/parsers-lines.test.ts

@@ -0,0 +1,44 @@
+// Line-list parser — round trip, comment + whitespace normalisation,
+// `containsEntry` semantics for .gitignore-style files.
+
+import { describe, test, expect } from "vitest";
+import {
+  parseLines,
+  serializeLines,
+  normaliseLine,
+  lineEqualsEntry,
+  containsEntry,
+} from "../parsers/lines";
+
+describe("line-list parser", () => {
+  test("round trip is stable on a canonical file", () => {
+    const raw = "a\nb\nc\n";
+    expect(serializeLines(parseLines(raw))).toBe(raw);
+  });
+
+  test("normaliseLine strips comments and whitespace", () => {
+    expect(normaliseLine("  node_modules/   # ignore deps")).toBe("node_modules/");
+    expect(normaliseLine("# pure comment")).toBe("");
+    expect(normaliseLine("dist/")).toBe("dist/");
+    expect(normaliseLine("")).toBe("");
+  });
+
+  test("lineEqualsEntry compares post-normalisation", () => {
+    expect(lineEqualsEntry("  dist/", "dist/")).toBe(true);
+    expect(lineEqualsEntry("dist/ # trailing", "dist/")).toBe(true);
+    expect(lineEqualsEntry("# dist/", "dist/")).toBe(false);
+    expect(lineEqualsEntry("dist/", "dist")).toBe(false);
+  });
+
+  test("containsEntry scans across a line list", () => {
+    const lines = parseLines("node_modules/\n# build artefacts\ndist/   # do not commit\n");
+    expect(containsEntry(lines, "dist/")).toBe(true);
+    expect(containsEntry(lines, "node_modules/")).toBe(true);
+    expect(containsEntry(lines, "missing/")).toBe(false);
+  });
+
+  test("missing trailing newline parses identically", () => {
+    expect(parseLines("a\nb")).toEqual(["a", "b"]);
+    expect(parseLines("a\nb\n")).toEqual(["a", "b"]);
+  });
+});

package/src/structure/engine/__tests__/parsers-yaml.test.ts

@@ -0,0 +1,90 @@
+// YAML parser primitives — round trip preserves comments around a
+// catalog block (the load-bearing case for `pnpm-workspace.yaml`).
+// Verifies get/set/has via jsonPath and that mutating one value leaves
+// surrounding comments intact.
+
+import { describe, test, expect } from "vitest";
+import { parseYaml, stringifyYaml, yamlGet, yamlHas, yamlSet, yamlDelete } from "../parsers/yaml";
+
+const CATALOG_YAML = `# pnpm workspace
+packages:
+  - .
+  - block
+  - model
+
+# Pinned SDK versions — bump via block-tools structure refresh --update-deps-only.
+catalog:
+  # SDK packages — keep alphabetical for diff friendliness.
+  "@platforma-sdk/model": 1.2.3
+  # Build tooling.
+  "@milaboratories/ts-builder": 0.5.0
+`;
+
+describe("YAML parser — comment-preserving round trip", () => {
+  test("identity round trip preserves all comments", () => {
+    const doc = parseYaml(CATALOG_YAML);
+    const out = stringifyYaml(doc);
+    expect(out).toContain("# pnpm workspace");
+    expect(out).toContain("# Pinned SDK versions");
+    expect(out).toContain("# SDK packages — keep alphabetical for diff friendliness.");
+    expect(out).toContain("# Build tooling.");
+  });
+
+  test("mutating one catalog entry preserves surrounding comments", () => {
+    const doc = parseYaml(CATALOG_YAML);
+    yamlSet(doc, "catalog.@platforma-sdk/model", "9.9.9");
+    const out = stringifyYaml(doc);
+    expect(out).toContain('"@platforma-sdk/model": 9.9.9');
+    expect(out).toContain("# Pinned SDK versions");
+    expect(out).toContain("# SDK packages — keep alphabetical for diff friendliness.");
+    expect(out).toContain("# Build tooling.");
+  });
+
+  test("yamlGet / yamlHas read scalar values", () => {
+    const doc = parseYaml(CATALOG_YAML);
+    // "1.2.3" is parsed as a plain string (not a YAML number).
+    expect(yamlGet(doc, "catalog.@platforma-sdk/model")).toBe("1.2.3");
+    expect(yamlHas(doc, "catalog.@platforma-sdk/model")).toBe(true);
+    expect(yamlHas(doc, "catalog.nope")).toBe(false);
+  });
+
+  test("yamlDelete removes a key; round trip drops it", () => {
+    const doc = parseYaml(CATALOG_YAML);
+    yamlDelete(doc, "catalog.@milaboratories/ts-builder");
+    const out = stringifyYaml(doc);
+    expect(out).not.toContain("@milaboratories/ts-builder");
+    // Sibling entries untouched.
+    expect(out).toContain("@platforma-sdk/model");
+  });
+
+  test("parse → stringify on minimal scalar map", () => {
+    const doc = parseYaml("a: 1\nb: 2\n");
+    expect(stringifyYaml(doc)).toBe("a: 1\nb: 2\n");
+  });
+
+  test("yamlGet with empty jsonPath returns the whole document as JS", () => {
+    const doc = parseYaml("a: 1\n");
+    expect(yamlGet(doc, "")).toEqual({ a: 1 });
+  });
+
+  test("yamlHas with empty jsonPath returns true", () => {
+    const doc = parseYaml("a: 1\n");
+    expect(yamlHas(doc, "")).toBe(true);
+  });
+
+  test("yamlSet with empty jsonPath throws", () => {
+    const doc = parseYaml("a: 1\n");
+    expect(() => yamlSet(doc, "", "x")).toThrow(/jsonPath must be non-empty/);
+  });
+
+  test("yamlDelete with empty jsonPath throws", () => {
+    const doc = parseYaml("a: 1\n");
+    expect(() => yamlDelete(doc, "")).toThrow(/jsonPath must be non-empty/);
+  });
+
+  test("yamlSet auto-creates intermediate maps", () => {
+    const doc = parseYaml("a: 1\n");
+    yamlSet(doc, "nested.key", "v");
+    expect(yamlGet(doc, "nested.key")).toBe("v");
+  });
+});

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

@@ -0,0 +1,99 @@
+// Post-run recheck — a non-idempotent managed body must surface as a
+// `RecheckError` carrying the failing item's (scope, path, primitive)
+// tuple.
+
+import { describe, test, expect } from "vitest";
+import { defineStructure, scope, managed, text } from "../api";
+import { ensureField } from "../content-rules";
+import { createRunContext } from "../ctx";
+import { MemoryFileSystem } from "../fs/memory";
+import { run, RecheckError } from "../runner";
+
+describe("post-run recheck", () => {
+  test("non-idempotent transform surfaces with (scope, path, primitive) tuple", async () => {
+    // A closure counter advances on every body invocation. First run
+    // writes counter=0; recheck dry-run sees the body produce
+    // counter=1 → non-empty diff → RecheckError.
+    let counter = 0;
+    const structure = defineStructure(() => {
+      scope("model", () => {
+        managed("drift.json", text("{}\n"), () => {
+          ensureField("counter", counter++);
+        });
+      });
+    });
+
+    const fs = new MemoryFileSystem();
+    const ctx = 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" }],
+    });
+
+    let thrown: unknown;
+    try {
+      run(structure, fs, ctx);
+    } catch (e) {
+      thrown = e;
+    }
+    expect(thrown).toBeInstanceOf(RecheckError);
+    const err = thrown as RecheckError;
+    expect(err.failing.scope).toBe("model");
+    expect(err.failing.path).toBe("model/drift.json");
+    expect(err.failing.primitive).toBe("managed");
+    expect(err.message).toMatch(/not idempotent/);
+  });
+
+  test("recheck is silent when the rule set converges", async () => {
+    // Idempotent body — ensureField with a fixed value.
+    const structure = defineStructure(() => {
+      scope("model", () => {
+        managed("ok.json", text("{}\n"), () => {
+          ensureField("type", "module");
+        });
+      });
+    });
+    const fs = new MemoryFileSystem();
+    const ctx = 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" }],
+    });
+    expect(run(structure, fs, ctx)).toBeDefined();
+  });
+
+  test("check mode skips recheck entirely", async () => {
+    let counter = 0;
+    const structure = defineStructure(() => {
+      scope("model", () => {
+        managed("drift.json", text("{}\n"), () => {
+          ensureField("counter", counter++);
+        });
+      });
+    });
+    const fs = new MemoryFileSystem();
+    const ctx = 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" }],
+      dryRun: true,
+    });
+    // dryRun=true: no recheck, no throw, body only runs once.
+    expect(run(structure, fs, ctx)).toBeDefined();
+  });
+});

package/src/structure/engine/__tests__/registry-lookup.test.ts

@@ -0,0 +1,49 @@
+// `buildRegistryLookupForNames` — the shared prefetch helper used by
+// `init` (names from the SDK pin map) and `refresh --update-deps-only`
+// (names from the on-disk catalog). Mocked client; no network.
+
+import { describe, test, expect } from "vitest";
+import {
+  buildRegistryLookupForNames,
+  matchesBumpPattern,
+  createMockRegistryClient,
+} from "../registry-client";
+
+describe("buildRegistryLookupForNames", () => {
+  test("empty name list → lookup resolves nothing, never touches the client", async () => {
+    // A client that would throw if asked — proves no call is made.
+    const throwing = createMockRegistryClient({});
+    const lookup = await buildRegistryLookupForNames([], throwing);
+    expect(lookup("@platforma-sdk/model")).toBeUndefined();
+  });
+
+  test("resolves each requested name to the client's latest", async () => {
+    const client = createMockRegistryClient({
+      "@platforma-sdk/model": "1.77.17",
+      "@platforma-sdk/test": "1.77.17",
+    });
+    const lookup = await buildRegistryLookupForNames(
+      ["@platforma-sdk/model", "@platforma-sdk/test"],
+      client,
+    );
+    expect(lookup("@platforma-sdk/model")).toBe("1.77.17");
+    expect(lookup("@platforma-sdk/test")).toBe("1.77.17");
+    expect(lookup("unknown")).toBeUndefined();
+  });
+
+  test("REJECTS when the registry fails — this is init's require-network abort path", async () => {
+    // Mock client throws for any unconfigured name (simulates registry down).
+    const down = createMockRegistryClient({});
+    await expect(buildRegistryLookupForNames(["@platforma-sdk/model"], down)).rejects.toThrow(
+      /no version configured/,
+    );
+  });
+
+  test("matchesBumpPattern selects the SDK families only", () => {
+    expect(matchesBumpPattern("@platforma-sdk/model")).toBe(true);
+    expect(matchesBumpPattern("@milaboratories/ts-builder")).toBe(true);
+    expect(matchesBumpPattern("turbo")).toBe(false);
+    expect(matchesBumpPattern("shx")).toBe(false);
+    expect(matchesBumpPattern("@platforma-open/milaboratories.runenv-python-3")).toBe(false);
+  });
+});

package/src/structure/engine/__tests__/runner-when-inside-managed.test.ts

@@ -0,0 +1,136 @@
+// End-to-end runner test: `when(...)` called inside a managed body
+// receives the post-structural-pass TriggerContext from the runner.
+//
+// Scenario mirrors the compound-migration pattern: a rename creates
+// `test-legacy/`; the managed body for `block/package.json` carries a
+// `when(pathExists("test-legacy/"), ...)` block that rewrites the dep
+// once the rename has landed.
+
+import { describe, test, expect } from "vitest";
+import { defineStructure, fixed, managed, rename, scope, text, generate, when } from "../api";
+import type { Structure } from "../ir";
+import { createRunContext } from "../ctx";
+import { MemoryFileSystem } from "../fs/memory";
+import { run } from "../runner";
+import { ensureDep, ensureField, removeDep } from "../content-rules";
+
+function migrationStructure(): Structure {
+  return defineStructure(() => {
+    // Migration: rename test/ → test-legacy/ once, idempotent via FS
+    // state. Wrapped in root scope (every leaf needs a scope frame).
+    scope("root", () => {
+      when(
+        ({ pathExists }) => pathExists("test/"),
+        () => {
+          rename("test/", "test-legacy/");
+        },
+      );
+    });
+
+    scope("block", () => {
+      fixed(".keep", text("ok\n"));
+      managed(
+        "package.json",
+        generate(() => ({ name: "demo.block", dependencies: { "old-test": "workspace:*" } })),
+        () => {
+          ensureField("type", "module");
+          // Inner when: rewrite dep target once the rename has landed.
+          // Runner builds the post-structural-pass snapshot, so
+          // `pathExists("test-legacy/")` is true on the same run.
+          when(
+            ({ pathExists }) => pathExists("test-legacy/"),
+            () => {
+              removeDep("old-test");
+              ensureDep("new-test", "workspace:*");
+            },
+          );
+        },
+      );
+    });
+  });
+}
+
+function ctxFor() {
+  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: "block", name: "@platforma-open/demo.block", path: "block" },
+    ],
+  });
+}
+
+describe("runner: inner when() sees post-structural-pass snapshot", () => {
+  test("rename + inner when fire together; deps rewritten in one refresh", async () => {
+    const fs = new MemoryFileSystem();
+    fs.write("test/a.ts", "// legacy");
+    fs.write(
+      "block/package.json",
+      JSON.stringify({ name: "demo.block", dependencies: { "old-test": "workspace:*" } }, null, 2) +
+        "\n",
+    );
+
+    const structure = migrationStructure();
+    run(structure, fs, ctxFor());
+
+    // Rename landed.
+    expect(fs.exists("test-legacy/a.ts")).toBe(true);
+    expect(fs.exists("test/a.ts")).toBe(false);
+
+    // Inner when fired → dep rewritten.
+    const pkgRaw = fs.read("block/package.json");
+    const pkg = JSON.parse(pkgRaw) as { dependencies: Record<string, string> };
+    expect(pkg.dependencies["old-test"]).toBeUndefined();
+    expect(pkg.dependencies["new-test"]).toBe("workspace:*");
+  });
+
+  test("second refresh is a no-op (idempotent)", async () => {
+    const fs = new MemoryFileSystem();
+    fs.write("test/a.ts", "// legacy");
+    fs.write(
+      "block/package.json",
+      JSON.stringify({ name: "demo.block", dependencies: { "old-test": "workspace:*" } }, null, 2) +
+        "\n",
+    );
+
+    const structure = migrationStructure();
+    run(structure, fs, ctxFor());
+    const snapshot1 = fs.read("block/package.json");
+
+    const result2 = run(structure, fs, ctxFor());
+    const snapshot2 = fs.read("block/package.json");
+
+    expect(snapshot2).toBe(snapshot1);
+    // No managed/structural changes the second time.
+    const managedOrStructural = result2.changes.filter(
+      (c) => c.primitive === "managed" || c.primitive === "rename",
+    );
+    expect(managedOrStructural).toEqual([]);
+  });
+
+  test("inner when skips when sibling path absent", async () => {
+    // No `test/` → no rename → no `test-legacy/` → inner when skips.
+    const fs = new MemoryFileSystem();
+    fs.write(
+      "block/package.json",
+      JSON.stringify({ name: "demo.block", dependencies: { "old-test": "workspace:*" } }, null, 2) +
+        "\n",
+    );
+
+    const structure = migrationStructure();
+    run(structure, fs, ctxFor());
+
+    const pkg = JSON.parse(fs.read("block/package.json")) as {
+      dependencies: Record<string, string>;
+    };
+    // Original dep survives unchanged.
+    expect(pkg.dependencies["old-test"]).toBe("workspace:*");
+    expect(pkg.dependencies["new-test"]).toBeUndefined();
+  });
+});