@forwardimpact/libsyntheticgen 0.1.1

package/test/rng.test.js

@@ -0,0 +1,236 @@
+import { describe, test } from "node:test";
+import assert from "node:assert";
+import { createSeededRNG } from "../engine/rng.js";
+
+describe("createSeededRNG", () => {
+  describe("determinism", () => {
+    test("same seed produces same sequence", () => {
+      const rng1 = createSeededRNG(42);
+      const rng2 = createSeededRNG(42);
+      const seq1 = Array.from({ length: 10 }, () => rng1.random());
+      const seq2 = Array.from({ length: 10 }, () => rng2.random());
+      assert.deepStrictEqual(seq1, seq2);
+    });
+
+    test("different seeds produce different sequences", () => {
+      const rng1 = createSeededRNG(42);
+      const rng2 = createSeededRNG(99);
+      const seq1 = Array.from({ length: 5 }, () => rng1.random());
+      const seq2 = Array.from({ length: 5 }, () => rng2.random());
+      assert.notDeepStrictEqual(seq1, seq2);
+    });
+
+    test("string seed is deterministic", () => {
+      const rng1 = createSeededRNG("hello");
+      const rng2 = createSeededRNG("hello");
+      assert.strictEqual(rng1.random(), rng2.random());
+    });
+  });
+
+  describe("random()", () => {
+    test("returns values in [0, 1)", () => {
+      const rng = createSeededRNG(42);
+      for (let i = 0; i < 100; i++) {
+        const val = rng.random();
+        assert.ok(val >= 0, `Expected >= 0, got ${val}`);
+        assert.ok(val < 1, `Expected < 1, got ${val}`);
+      }
+    });
+
+    test("returns different values on successive calls", () => {
+      const rng = createSeededRNG(42);
+      const a = rng.random();
+      const b = rng.random();
+      assert.notStrictEqual(a, b);
+    });
+  });
+
+  describe("randomInt(min, max)", () => {
+    test("returns integers within the specified range", () => {
+      const rng = createSeededRNG(42);
+      for (let i = 0; i < 100; i++) {
+        const val = rng.randomInt(1, 10);
+        assert.ok(Number.isInteger(val), `Expected integer, got ${val}`);
+        assert.ok(val >= 1, `Expected >= 1, got ${val}`);
+        assert.ok(val <= 10, `Expected <= 10, got ${val}`);
+      }
+    });
+
+    test("returns min when min equals max", () => {
+      const rng = createSeededRNG(42);
+      const val = rng.randomInt(5, 5);
+      assert.strictEqual(val, 5);
+    });
+
+    test("handles range of 0 to 0", () => {
+      const rng = createSeededRNG(42);
+      assert.strictEqual(rng.randomInt(0, 0), 0);
+    });
+
+    test("is deterministic for same seed", () => {
+      const rng1 = createSeededRNG(42);
+      const rng2 = createSeededRNG(42);
+      for (let i = 0; i < 20; i++) {
+        assert.strictEqual(rng1.randomInt(0, 100), rng2.randomInt(0, 100));
+      }
+    });
+  });
+
+  describe("pick(arr)", () => {
+    test("returns an element from the array", () => {
+      const rng = createSeededRNG(42);
+      const arr = ["a", "b", "c", "d", "e"];
+      for (let i = 0; i < 50; i++) {
+        const picked = rng.pick(arr);
+        assert.ok(arr.includes(picked), `Picked '${picked}' not in array`);
+      }
+    });
+
+    test("returns the only element for single-item arrays", () => {
+      const rng = createSeededRNG(42);
+      assert.strictEqual(rng.pick(["only"]), "only");
+    });
+
+    test("is deterministic for same seed", () => {
+      const rng1 = createSeededRNG(42);
+      const rng2 = createSeededRNG(42);
+      const arr = [1, 2, 3, 4, 5];
+      for (let i = 0; i < 10; i++) {
+        assert.strictEqual(rng1.pick(arr), rng2.pick(arr));
+      }
+    });
+  });
+
+  describe("shuffle(arr)", () => {
+    test("returns a new array with same elements", () => {
+      const rng = createSeededRNG(42);
+      const arr = [1, 2, 3, 4, 5];
+      const shuffled = rng.shuffle(arr);
+      assert.strictEqual(shuffled.length, arr.length);
+      assert.deepStrictEqual([...shuffled].sort(), [...arr].sort());
+    });
+
+    test("does not modify the original array", () => {
+      const rng = createSeededRNG(42);
+      const arr = [1, 2, 3, 4, 5];
+      const original = [...arr];
+      rng.shuffle(arr);
+      assert.deepStrictEqual(arr, original);
+    });
+
+    test("is deterministic for same seed", () => {
+      const rng1 = createSeededRNG(42);
+      const rng2 = createSeededRNG(42);
+      const arr = [1, 2, 3, 4, 5, 6, 7, 8, 9, 10];
+      assert.deepStrictEqual(rng1.shuffle(arr), rng2.shuffle(arr));
+    });
+
+    test("handles single-element arrays", () => {
+      const rng = createSeededRNG(42);
+      assert.deepStrictEqual(rng.shuffle([1]), [1]);
+    });
+
+    test("handles empty arrays", () => {
+      const rng = createSeededRNG(42);
+      assert.deepStrictEqual(rng.shuffle([]), []);
+    });
+  });
+
+  describe("weightedPick(weights)", () => {
+    test("returns a valid index", () => {
+      const rng = createSeededRNG(42);
+      const weights = [10, 20, 30];
+      for (let i = 0; i < 50; i++) {
+        const idx = rng.weightedPick(weights);
+        assert.ok(
+          idx >= 0 && idx < weights.length,
+          `Index ${idx} out of range`,
+        );
+      }
+    });
+
+    test("respects heavy weighting", () => {
+      const rng = createSeededRNG(42);
+      // Weight index 2 very heavily
+      const weights = [1, 1, 1000];
+      const counts = [0, 0, 0];
+      for (let i = 0; i < 200; i++) {
+        counts[rng.weightedPick(weights)]++;
+      }
+      // Index 2 should dominate
+      assert.ok(
+        counts[2] > counts[0] + counts[1],
+        `Expected index 2 to dominate: ${JSON.stringify(counts)}`,
+      );
+    });
+
+    test("returns only valid index for single-weight array", () => {
+      const rng = createSeededRNG(42);
+      assert.strictEqual(rng.weightedPick([100]), 0);
+    });
+
+    test("is deterministic for same seed", () => {
+      const rng1 = createSeededRNG(42);
+      const rng2 = createSeededRNG(42);
+      const weights = [10, 20, 30, 40];
+      for (let i = 0; i < 20; i++) {
+        assert.strictEqual(
+          rng1.weightedPick(weights),
+          rng2.weightedPick(weights),
+        );
+      }
+    });
+  });
+
+  describe("gaussian(mean, std)", () => {
+    test("produces values centered around the mean", () => {
+      const rng = createSeededRNG(42);
+      const mean = 50;
+      const std = 10;
+      const values = Array.from({ length: 1000 }, () =>
+        rng.gaussian(mean, std),
+      );
+      const avg = values.reduce((s, v) => s + v, 0) / values.length;
+      // Average should be reasonably close to mean
+      assert.ok(
+        Math.abs(avg - mean) < 3,
+        `Average ${avg} too far from mean ${mean}`,
+      );
+    });
+
+    test("produces reasonable spread", () => {
+      const rng = createSeededRNG(42);
+      const mean = 0;
+      const std = 1;
+      const values = Array.from({ length: 1000 }, () =>
+        rng.gaussian(mean, std),
+      );
+      // Most values should be within 3 standard deviations
+      const withinThreeSigma = values.filter(
+        (v) => v >= mean - 3 * std && v <= mean + 3 * std,
+      );
+      assert.ok(
+        withinThreeSigma.length > 990,
+        `Expected >99% within 3 sigma, got ${withinThreeSigma.length}/1000`,
+      );
+    });
+
+    test("is deterministic for same seed", () => {
+      const rng1 = createSeededRNG(42);
+      const rng2 = createSeededRNG(42);
+      for (let i = 0; i < 10; i++) {
+        assert.strictEqual(rng1.gaussian(0, 1), rng2.gaussian(0, 1));
+      }
+    });
+
+    test("respects custom mean and std", () => {
+      const rng = createSeededRNG(42);
+      const values = Array.from({ length: 500 }, () => rng.gaussian(100, 5));
+      const min = Math.min(...values);
+      const max = Math.max(...values);
+      // Should be roughly within 100 +/- 25 (5 sigma)
+      assert.ok(min > 70, `Min ${min} too low for mean=100, std=5`);
+      assert.ok(max < 130, `Max ${max} too high for mean=100, std=5`);
+    });
+  });
+});

package/test/sdv.test.js

@@ -0,0 +1,67 @@
+import { describe, test } from "node:test";
+import assert from "node:assert";
+import { SdvTool } from "../tools/sdv.js";
+
+const logger = { info() {}, error() {} };
+
+describe("SdvTool", () => {
+  test("requires all dependencies", () => {
+    assert.throws(() => new SdvTool({}), /requires logger/);
+    assert.throws(() => new SdvTool({ logger }), /requires execFileFn/);
+    assert.throws(
+      () => new SdvTool({ logger, execFileFn: async () => {} }),
+      /requires fsFns/,
+    );
+  });
+
+  test("checkAvailability throws when python/sdv missing", async () => {
+    const tool = new SdvTool({
+      logger,
+      execFileFn: async () => {
+        throw new Error("not found");
+      },
+      fsFns: { writeFile: async () => {}, rm: async () => {} },
+    });
+    await assert.rejects(
+      () => tool.checkAvailability(),
+      /SDV requires Python 3/,
+    );
+  });
+
+  test("parses subprocess output into datasets", async () => {
+    let _capturedConfig;
+    const stdout = [
+      JSON.stringify({ name: "orders", records: [{ id: 1, amount: 99.5 }] }),
+      JSON.stringify({
+        name: "items",
+        records: [{ id: 2, product: "widget" }],
+      }),
+    ].join("\n");
+
+    const tool = new SdvTool({
+      logger,
+      execFileFn: async (cmd, args) => {
+        _capturedConfig = args;
+        return { stdout };
+      },
+      fsFns: {
+        writeFile: async () => {},
+        rm: async () => {},
+      },
+    });
+
+    const datasets = await tool.generate({
+      name: "sales",
+      metadata: "meta.json",
+      data: { orders: "orders.csv", items: "items.csv" },
+      rows: 100,
+      seed: 42,
+    });
+
+    assert.strictEqual(datasets.length, 2);
+    assert.strictEqual(datasets[0].name, "sales_orders");
+    assert.strictEqual(datasets[0].records[0].amount, 99.5);
+    assert.strictEqual(datasets[0].metadata.tool, "sdv");
+    assert.strictEqual(datasets[1].name, "sales_items");
+  });
+});

package/test/synthea.test.js

@@ -0,0 +1,95 @@
+import { describe, test } from "node:test";
+import assert from "node:assert";
+import { SyntheaTool } from "../tools/synthea.js";
+
+const logger = { info() {}, error() {} };
+
+describe("SyntheaTool", () => {
+  test("requires all dependencies", () => {
+    assert.throws(() => new SyntheaTool({}), /requires logger/);
+    assert.throws(() => new SyntheaTool({ logger }), /requires syntheaJar/);
+    assert.throws(
+      () => new SyntheaTool({ logger, syntheaJar: "/path.jar" }),
+      /requires execFileFn/,
+    );
+    assert.throws(
+      () =>
+        new SyntheaTool({
+          logger,
+          syntheaJar: "/path.jar",
+          execFileFn: async () => {},
+        }),
+      /requires fsFns/,
+    );
+  });
+
+  test("checkAvailability throws when java missing", async () => {
+    const tool = new SyntheaTool({
+      logger,
+      syntheaJar: "/missing.jar",
+      execFileFn: async () => {
+        throw new Error("not found");
+      },
+      fsFns: { readFile: async () => Buffer.from("") },
+    });
+    await assert.rejects(
+      () => tool.checkAvailability(),
+      /Synthea requires Java/,
+    );
+  });
+
+  test("passes correct args to java", async () => {
+    let capturedArgs;
+    const fhirBundle = {
+      entry: [
+        { resource: { resourceType: "Patient", id: "p1", name: "Alice" } },
+        { resource: { resourceType: "Condition", id: "c1", code: "diabetes" } },
+      ],
+    };
+
+    const tool = new SyntheaTool({
+      logger,
+      syntheaJar: "/synthea.jar",
+      execFileFn: async (cmd, args) => {
+        capturedArgs = { cmd, args };
+        return { stdout: "" };
+      },
+      fsFns: {
+        readFile: async (path, _enc) => {
+          if (path === "/synthea.jar") return Buffer.from("");
+          return JSON.stringify(fhirBundle);
+        },
+        readdir: async () => ["patient1.json"],
+        mkdtemp: async () => "/tmp/synthea-abc",
+        rm: async () => {},
+      },
+    });
+
+    const datasets = await tool.generate({
+      name: "test",
+      population: 50,
+      modules: ["diabetes"],
+      seed: 42,
+    });
+
+    assert.strictEqual(capturedArgs.cmd, "java");
+    assert.ok(capturedArgs.args.includes("-jar"));
+    assert.ok(capturedArgs.args.includes("/synthea.jar"));
+    assert.ok(capturedArgs.args.includes("-p"));
+    assert.ok(capturedArgs.args.includes("50"));
+    assert.ok(capturedArgs.args.includes("-s"));
+    assert.ok(capturedArgs.args.includes("42"));
+    assert.ok(capturedArgs.args.includes("-m"));
+    assert.ok(capturedArgs.args.includes("diabetes"));
+
+    // Verify dataset flattening by resource type
+    assert.strictEqual(datasets.length, 2);
+    const names = datasets.map((d) => d.name).sort();
+    assert.deepStrictEqual(names, ["test_condition", "test_patient"]);
+
+    const patientDs = datasets.find((d) => d.name === "test_patient");
+    assert.strictEqual(patientDs.records.length, 1);
+    assert.strictEqual(patientDs.metadata.tool, "synthea");
+    assert.strictEqual(patientDs.metadata.resourceType, "Patient");
+  });
+});

package/test/tokenizer.test.js

@@ -0,0 +1,266 @@
+import { describe, test } from "node:test";
+import assert from "node:assert";
+import { tokenize } from "../dsl/tokenizer.js";
+
+describe("tokenize", () => {
+  describe("basic tokens", () => {
+    test("tokenizes keywords", () => {
+      const tokens = tokenize("universe domain industry seed");
+      assert.deepStrictEqual(
+        tokens.filter((t) => t.type !== "EOF"),
+        [
+          { type: "KEYWORD", value: "universe", line: 1 },
+          { type: "KEYWORD", value: "domain", line: 1 },
+          { type: "KEYWORD", value: "industry", line: 1 },
+          { type: "KEYWORD", value: "seed", line: 1 },
+        ],
+      );
+    });
+
+    test("tokenizes all structural keywords", () => {
+      const input = "org department team people project framework";
+      const tokens = tokenize(input).filter((t) => t.type !== "EOF");
+      assert.strictEqual(tokens.length, 6);
+      for (const t of tokens) {
+        assert.strictEqual(t.type, "KEYWORD");
+      }
+    });
+
+    test("tokenizes string literals", () => {
+      const tokens = tokenize('"hello world"');
+      assert.deepStrictEqual(tokens[0], {
+        type: "STRING",
+        value: "hello world",
+        line: 1,
+      });
+    });
+
+    test("tokenizes string with escape sequences", () => {
+      const tokens = tokenize('"line1\\nline2\\ttab\\\\"');
+      assert.strictEqual(tokens[0].value, "line1\nline2\ttab\\");
+    });
+
+    test("tokenizes integer numbers", () => {
+      const tokens = tokenize("42");
+      assert.deepStrictEqual(tokens[0], {
+        type: "NUMBER",
+        value: "42",
+        line: 1,
+      });
+    });
+
+    test("tokenizes decimal numbers", () => {
+      const tokens = tokenize("3.14");
+      assert.deepStrictEqual(tokens[0], {
+        type: "NUMBER",
+        value: "3.14",
+        line: 1,
+      });
+    });
+
+    test("tokenizes identifiers", () => {
+      const tokens = tokenize("myVar another_one");
+      assert.deepStrictEqual(tokens[0], {
+        type: "IDENT",
+        value: "myVar",
+        line: 1,
+      });
+      assert.deepStrictEqual(tokens[1], {
+        type: "IDENT",
+        value: "another_one",
+        line: 1,
+      });
+    });
+
+    test("distinguishes keywords from identifiers", () => {
+      const tokens = tokenize("universe myUniverse");
+      assert.strictEqual(tokens[0].type, "KEYWORD");
+      assert.strictEqual(tokens[1].type, "IDENT");
+    });
+  });
+
+  describe("special tokens", () => {
+    test("tokenizes @references", () => {
+      const tokens = tokenize("@apollo @themis");
+      assert.deepStrictEqual(tokens[0], {
+        type: "AT_IDENT",
+        value: "apollo",
+        line: 1,
+      });
+      assert.deepStrictEqual(tokens[1], {
+        type: "AT_IDENT",
+        value: "themis",
+        line: 1,
+      });
+    });
+
+    test("tokenizes percentages", () => {
+      const tokens = tokenize("50%");
+      assert.deepStrictEqual(tokens[0], {
+        type: "PERCENT",
+        value: "50",
+        line: 1,
+      });
+    });
+
+    test("tokenizes dates in YYYY-MM format", () => {
+      const tokens = tokenize("2024-01");
+      assert.deepStrictEqual(tokens[0], {
+        type: "DATE",
+        value: "2024-01",
+        line: 1,
+      });
+    });
+
+    test("tokenizes multiple dates", () => {
+      const tokens = tokenize("2024-01 2025-12");
+      assert.strictEqual(tokens[0].type, "DATE");
+      assert.strictEqual(tokens[0].value, "2024-01");
+      assert.strictEqual(tokens[1].type, "DATE");
+      assert.strictEqual(tokens[1].value, "2025-12");
+    });
+  });
+
+  describe("comments", () => {
+    test("skips single-line comments", () => {
+      const tokens = tokenize("universe // this is a comment\ndomain");
+      const nonEof = tokens.filter((t) => t.type !== "EOF");
+      assert.strictEqual(nonEof.length, 2);
+      assert.strictEqual(nonEof[0].value, "universe");
+      assert.strictEqual(nonEof[1].value, "domain");
+    });
+
+    test("skips multi-line comments", () => {
+      const tokens = tokenize("universe /* multi\nline\ncomment */ domain");
+      const nonEof = tokens.filter((t) => t.type !== "EOF");
+      assert.strictEqual(nonEof.length, 2);
+      assert.strictEqual(nonEof[0].value, "universe");
+      assert.strictEqual(nonEof[1].value, "domain");
+    });
+
+    test("tracks line numbers through multi-line comments", () => {
+      const tokens = tokenize("universe\n/* line 2\nline 3 */\ndomain");
+      const domainToken = tokens.find((t) => t.value === "domain");
+      assert.strictEqual(domainToken.line, 4);
+    });
+  });
+
+  describe("braces and brackets", () => {
+    test("tokenizes braces", () => {
+      const tokens = tokenize("{ }");
+      assert.strictEqual(tokens[0].type, "LBRACE");
+      assert.strictEqual(tokens[1].type, "RBRACE");
+    });
+
+    test("tokenizes brackets", () => {
+      const tokens = tokenize("[ ]");
+      assert.strictEqual(tokens[0].type, "LBRACKET");
+      assert.strictEqual(tokens[1].type, "RBRACKET");
+    });
+
+    test("tokenizes commas", () => {
+      const tokens = tokenize(",");
+      assert.strictEqual(tokens[0].type, "COMMA");
+    });
+
+    test("tokenizes mixed structural characters", () => {
+      const tokens = tokenize("[1, 2, 3]");
+      const types = tokens.filter((t) => t.type !== "EOF").map((t) => t.type);
+      assert.deepStrictEqual(types, [
+        "LBRACKET",
+        "NUMBER",
+        "COMMA",
+        "NUMBER",
+        "COMMA",
+        "NUMBER",
+        "RBRACKET",
+      ]);
+    });
+  });
+
+  describe("line tracking", () => {
+    test("tracks line numbers across newlines", () => {
+      const tokens = tokenize("universe\ndomain\nindustry");
+      assert.strictEqual(tokens[0].line, 1);
+      assert.strictEqual(tokens[1].line, 2);
+      assert.strictEqual(tokens[2].line, 3);
+    });
+
+    test("ignores carriage returns for line counting", () => {
+      const tokens = tokenize("universe\r\ndomain");
+      assert.strictEqual(tokens[0].line, 1);
+      assert.strictEqual(tokens[1].line, 2);
+    });
+  });
+
+  describe("edge cases", () => {
+    test("returns only EOF for empty input", () => {
+      const tokens = tokenize("");
+      assert.strictEqual(tokens.length, 1);
+      assert.strictEqual(tokens[0].type, "EOF");
+    });
+
+    test("returns only EOF for whitespace-only input", () => {
+      const tokens = tokenize("   \t\n  \n  ");
+      assert.strictEqual(tokens.length, 1);
+      assert.strictEqual(tokens[0].type, "EOF");
+    });
+
+    test("throws on unknown characters", () => {
+      assert.throws(() => tokenize("~"), /Unexpected character '~'/);
+    });
+
+    test("throws on unknown character with line number", () => {
+      assert.throws(() => tokenize("\n\n~"), /at line 3/);
+    });
+  });
+
+  describe("negative numbers", () => {
+    test("tokenizes negative integers", () => {
+      const tokens = tokenize("-5");
+      assert.deepStrictEqual(tokens[0], {
+        type: "NUMBER",
+        value: "-5",
+        line: 1,
+      });
+    });
+
+    test("tokenizes negative decimals", () => {
+      const tokens = tokenize("-3.14");
+      assert.deepStrictEqual(tokens[0], {
+        type: "NUMBER",
+        value: "-3.14",
+        line: 1,
+      });
+    });
+  });
+
+  describe("EOF token", () => {
+    test("always ends with EOF", () => {
+      const tokens = tokenize("universe");
+      assert.strictEqual(tokens[tokens.length - 1].type, "EOF");
+    });
+  });
+
+  describe("complex input", () => {
+    test("tokenizes a minimal universe declaration", () => {
+      const input = `universe test_co {
+        domain "engineering"
+        seed 42
+      }`;
+      const tokens = tokenize(input);
+      const types = tokens.map((t) => t.type);
+      assert.deepStrictEqual(types, [
+        "KEYWORD", // universe
+        "IDENT", // test_co
+        "LBRACE",
+        "KEYWORD", // domain
+        "STRING", // "engineering"
+        "KEYWORD", // seed
+        "NUMBER", // 42
+        "RBRACE",
+        "EOF",
+      ]);
+    });
+  });
+});