@forwardimpact/libuniverse 0.1.1 → 0.1.3

package/bin/fit-universe.js

@@ -52,7 +52,11 @@ async function main() {
     SUPABASE_SERVICE_ROLE_KEY: null,
   });
 
-  const mode = args.cached ? "cached" : args.generate ? "generate" : "no-prose";
+  const mode = args.noProse
+    ? "no-prose"
+    : args.generate
+      ? "generate"
+      : "cached";
 
   let llmApi = null;
   if (mode === "generate") {
@@ -75,7 +79,8 @@ async function main() {
 
   const monorepoRoot = resolve(__dirname, "../../..");
   const schemaDir = join(monorepoRoot, "products/map/schema/json");
-  const cachePath = join(__dirname, "..", ".prose-cache.json");
+  const cachePath =
+    args.cache || join(monorepoRoot, "data", "synthetic", "prose-cache.json");
 
   const libsyntheticproseDir = dirname(
     fileURLToPath(import.meta.resolve("@forwardimpact/libsyntheticprose")),
@@ -156,7 +161,7 @@ async function main() {
 
   const result = await pipeline.run({
     universePath:
-      args.universe || join(monorepoRoot, "examples", "universe.dsl"),
+      args.story || join(monorepoRoot, "data", "synthetic", "story.dsl"),
     only: args.only || null,
     schemaDir,
   });
@@ -190,26 +195,19 @@ async function main() {
       }
     } else if (!args.dryRun) {
       for (const [storagePath, content] of result.rawDocuments) {
-        const fullPath = join(
-          monorepoRoot,
-          "examples/activity/raw",
-          storagePath,
-        );
+        const fullPath = join(monorepoRoot, "data/activity/raw", storagePath);
         await mkdir(dirname(fullPath), { recursive: true });
         await writeFile(fullPath, content);
       }
       console.log(
-        `${result.rawDocuments.size} raw documents written to examples/activity/raw/`,
+        `${result.rawDocuments.size} raw documents written to data/activity/raw/`,
       );
     }
 
     // Write evidence directly (no raw source system for evidence)
     const evidence = result.entities.activity?.evidence;
     if (evidence && !args.dryRun && !args.load) {
-      const evidencePath = join(
-        monorepoRoot,
-        "examples/activity/evidence.json",
-      );
+      const evidencePath = join(monorepoRoot, "data/activity/evidence.json");
       await mkdir(dirname(evidencePath), { recursive: true });
       const formatted = await formatContent(
         evidencePath,
@@ -263,13 +261,14 @@ function parseArgs(argv) {
   const args = {};
   for (const arg of argv) {
     if (arg === "--help" || arg === "-h") args.help = true;
-    else if (arg === "--cached") args.cached = true;
+    else if (arg === "--no-prose") args.noProse = true;
     else if (arg === "--generate") args.generate = true;
     else if (arg === "--strict") args.strict = true;
     else if (arg === "--dry-run") args.dryRun = true;
     else if (arg === "--load") args.load = true;
     else if (arg.startsWith("--only=")) args.only = arg.slice(7);
-    else if (arg.startsWith("--universe=")) args.universe = arg.slice(11);
+    else if (arg.startsWith("--story=")) args.story = arg.slice(8);
+    else if (arg.startsWith("--cache=")) args.cache = arg.slice(8);
   }
   return args;
 }
@@ -281,32 +280,34 @@ Usage:
   npx fit-universe [options]
 
 Options:
-  --generate          Generate prose via LLM (requires LLM_TOKEN)
-  --cached            Use cached prose from .prose-cache.json
-  --strict            Fail on cache miss (use with --cached)
+  --generate          Generate prose via LLM and update cache (requires LLM_TOKEN)
+  --no-prose          Skip prose entirely (structural scaffolding only)
+  --strict            Fail on cache miss (use with default cached mode)
   --dry-run           Show what would be written without writing
   --load              Load raw documents to Supabase Storage
   --only=<type>       Render only one content type (html|pathway|raw|markdown)
-  --universe=<path>   Path to a custom universe DSL file
+  --story=<path>      Path to a custom story DSL file
+  --cache=<path>      Path to prose cache file
   -h, --help          Show this help message
 
 Prose modes:
-  (default)           Structural generation only, no LLM calls
-  --cached            Read prose from .prose-cache.json
-  --generate          Call LLM to generate prose, write to cache
+  (default)           Use cached prose from prose-cache.json
+  --generate          Call LLM to generate prose and update the cache
+  --no-prose          No prose — produces minimal structural data only
 
 Content types:
-  html                Organizational articles, guides, FAQs (examples/organizational)
-  pathway             YAML framework files (examples/pathway)
-  raw                 Roster, GitHub events, evidence (examples/activity)
-  markdown            Briefings, notes, KB content (examples/personal)
+  html                Organizational articles, guides, FAQs (data/knowledge)
+  pathway             YAML framework files (data/pathway)
+  raw                 Roster, GitHub events, evidence (data/activity)
+  markdown            Briefings, notes, KB content (data/personal)
 
 Examples:
-  npx fit-universe                           # Structural only
-  npx fit-universe --generate                # Full generation with LLM prose
-  npx fit-universe --cached --strict         # Cached prose, fail on miss
+  npx fit-universe                           # Cached prose (default)
+  npx fit-universe --generate                # Generate new prose via LLM
+  npx fit-universe --strict                  # Cached prose, fail on miss
+  npx fit-universe --no-prose                # Structural only, no prose
   npx fit-universe --only=pathway            # Generate pathway data only
-  npx fit-universe --universe=custom.dsl     # Use custom DSL file
+  npx fit-universe --story=custom.dsl        # Use custom DSL file
 `);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forwardimpact/libuniverse",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Synthetic data universe DSL and generation engine",
   "license": "Apache-2.0",
   "repository": {
@@ -27,8 +27,8 @@
     "@forwardimpact/libsyntheticrender": "^0.1.0",
     "@forwardimpact/libtelemetry": "^0.1.23",
     "@forwardimpact/libtemplate": "^0.2.0",
-    "@supabase/supabase-js": "^2.0.0",
-    "prettier": "^3.7.4"
+    "@supabase/supabase-js": "^2.100.1",
+    "prettier": "^3.8.1"
   },
   "engines": {
     "node": ">=18.0.0"

package/pipeline.js

@@ -66,7 +66,7 @@ export class Pipeline {
    * Run the full generation pipeline.
    *
    * @param {object} options
-   * @param {string} options.universePath - Path to the universe.dsl file
+   * @param {string} options.universePath - Path to the story DSL file
    * @param {string} [options.only=null] - Render only a specific content type
    * @param {string|null} [options.schemaDir=null] - Path to JSON schema directory
    * @returns {Promise<{files: Map<string,string>, rawDocuments: Map<string,string>, entities: object, validation: object, stats: {prose: {hits: number, misses: number, generated: number}, files: number, rawDocuments: number}}>}
@@ -138,25 +138,25 @@ export class Pipeline {
           entities.domain,
         );
         for (const [name, content] of enriched) {
-          files.set(join("examples/organizational", name), content);
+          files.set(join("data/knowledge", name), content);
         }
       } else {
         for (const [name, content] of htmlFiles) {
-          files.set(join("examples/organizational", name), content);
+          files.set(join("data/knowledge", name), content);
         }
       }
 
       files.set(
-        "examples/organizational/README.md",
+        "data/knowledge/README.md",
         this.renderer.renderReadme(entities, prose),
       );
       files.set(
-        "examples/organizational/ONTOLOGY.md",
+        "data/knowledge/ONTOLOGY.md",
         this.renderer.renderOntology(entities),
       );
 
       const htmlCount = [...files.keys()].filter((p) =>
-        p.startsWith("examples/organizational/"),
+        p.startsWith("data/knowledge/"),
       ).length;
       log.info("render", `HTML: ${htmlCount} files`);
     }
@@ -177,7 +177,7 @@ export class Pipeline {
         });
         const pathwayFiles = this.renderer.renderPathway(pathwayData);
         for (const [name, content] of pathwayFiles) {
-          files.set(`examples/pathway/${name}`, content);
+          files.set(`data/pathway/${name}`, content);
         }
         log.info("render", `Pathway: ${pathwayFiles.size} files`);
       }
@@ -192,7 +192,7 @@ export class Pipeline {
 
       const activityFiles = this.renderer.renderActivity(entities);
       for (const [name, content] of activityFiles) {
-        files.set(join("examples/activity", name), content);
+        files.set(join("data/activity", name), content);
       }
       log.info(
         "render",
@@ -204,7 +204,7 @@ export class Pipeline {
       log.info("render", "Rendering markdown");
       const md = this.renderer.renderMarkdown(entities, prose);
       for (const [name, content] of md) {
-        files.set(join("examples/personal", name), content);
+        files.set(join("data/personal", name), content);
       }
       log.info("render", `Markdown: ${md.size} files`);
     }
@@ -292,10 +292,7 @@ export class Pipeline {
 
       const orgFiles = new Map();
       for (const [path, content] of formattedFiles) {
-        if (
-          path.startsWith("examples/organizational/") &&
-          path.endsWith(".html")
-        ) {
+        if (path.startsWith("data/knowledge/") && path.endsWith(".html")) {
           orgFiles.set(path, content);
         }
       }

package/test/fixtures/minimal.dsl

@@ -0,0 +1,103 @@
+universe minimal {
+  domain "test.example"
+  industry "technology"
+  seed 42
+
+  org testorg {
+    name "Test Organization"
+  }
+
+  department eng {
+    name "Engineering"
+    parent testorg
+    headcount 5
+
+    team alpha {
+      name "Alpha Team"
+      size 5
+      manager @alpha_lead
+      repos ["alpha-service"]
+    }
+  }
+
+  people {
+    count 5
+    distribution {
+      L3 40%
+      L4 40%
+      L5 20%
+    }
+    disciplines {
+      software_engineering 100%
+    }
+  }
+
+  project testproj {
+    name "Test Project"
+    type "drug"
+    teams [alpha]
+    prose_topic "Testing synthetic generation"
+    prose_tone "technical"
+  }
+
+  framework {
+    proficiencies [awareness, foundational, working, practitioner, expert]
+    maturities [emerging, developing, practicing, role_modeling, exemplifying]
+    stages [specify, plan, code, review]
+
+    levels {
+      J040 { title "Software Engineer" rank 1 experience "0-2 years" }
+      J050 { title "Senior Engineer" rank 2 experience "2-5 years" }
+    }
+
+    capabilities {
+      coding { name "Coding" skills [python_dev, code_review] }
+    }
+
+    behaviours {
+      collaboration { name "Collaboration" }
+    }
+
+    disciplines {
+      software_engineering {
+        roleTitle "Software Engineer"
+        core [python_dev]
+        supporting [code_review]
+      }
+    }
+
+    tracks {
+      backend { name "Backend" }
+    }
+
+    drivers {
+      clear_direction {
+        name "Clear Direction"
+        skills [python_dev]
+        behaviours [collaboration]
+      }
+    }
+  }
+
+  scenario baseline {
+    name "Baseline Scenario"
+    timerange_start 2025-01
+    timerange_end 2025-06
+
+    affect alpha {
+      github_commits "moderate"
+      github_prs "moderate"
+      dx_drivers {
+        clear_direction { trajectory "rising" magnitude 3 }
+      }
+      evidence_skills [python_dev]
+      evidence_floor "foundational"
+    }
+  }
+
+  content guide_html {
+    courses 2
+    events 1
+    blogs 3
+  }
+}

package/test/pipeline.test.js

@@ -0,0 +1,106 @@
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import {
+  createDslParser,
+  createEntityGenerator,
+} from "@forwardimpact/libsyntheticgen";
+import { validateCrossContent } from "@forwardimpact/libsyntheticrender";
+import { readFileSync } from "fs";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const FIXTURE_PATH = join(__dirname, "fixtures", "minimal.dsl");
+
+function makeLogger() {
+  return {
+    info: () => {},
+    debug: () => {},
+    warn: () => {},
+    error: () => {},
+  };
+}
+
+describe("Pipeline integration", () => {
+  test("parses minimal DSL fixture", () => {
+    const source = readFileSync(FIXTURE_PATH, "utf-8");
+    const parser = createDslParser();
+    const ast = parser.parse(source);
+
+    assert.strictEqual(ast.domain, "test.example");
+    assert.strictEqual(ast.industry, "technology");
+    assert.ok(ast.people);
+    assert.ok(ast.teams.length > 0);
+    assert.ok(ast.projects.length > 0);
+  });
+
+  test("generates entities from minimal DSL", () => {
+    const source = readFileSync(FIXTURE_PATH, "utf-8");
+    const parser = createDslParser();
+    const ast = parser.parse(source);
+    const generator = createEntityGenerator(makeLogger());
+    const entities = generator.generate(ast);
+
+    assert.ok(entities.orgs.length > 0);
+    assert.ok(entities.departments.length > 0);
+    assert.ok(entities.teams.length > 0);
+    assert.ok(entities.people.length > 0);
+    assert.ok(entities.projects.length > 0);
+    assert.ok(entities.domain);
+  });
+
+  test("entity IRIs use consistent /id/ namespace", () => {
+    const source = readFileSync(FIXTURE_PATH, "utf-8");
+    const parser = createDslParser();
+    const ast = parser.parse(source);
+    const generator = createEntityGenerator(makeLogger());
+    const entities = generator.generate(ast);
+
+    for (const org of entities.orgs) {
+      assert.ok(org.iri.includes("/id/org/"), `Bad org IRI: ${org.iri}`);
+    }
+    for (const dept of entities.departments) {
+      assert.ok(
+        dept.iri.includes("/id/department/"),
+        `Bad dept IRI: ${dept.iri}`,
+      );
+    }
+    for (const team of entities.teams) {
+      assert.ok(team.iri.includes("/id/team/"), `Bad team IRI: ${team.iri}`);
+    }
+    for (const person of entities.people) {
+      assert.ok(
+        person.iri.includes("/id/person/"),
+        `Bad person IRI: ${person.iri}`,
+      );
+    }
+    for (const proj of entities.projects) {
+      assert.ok(
+        proj.iri.includes("/id/project/"),
+        `Bad project IRI: ${proj.iri}`,
+      );
+    }
+  });
+
+  test("cross-content validation passes on generated entities", () => {
+    const source = readFileSync(FIXTURE_PATH, "utf-8");
+    const parser = createDslParser();
+    const ast = parser.parse(source);
+    const generator = createEntityGenerator(makeLogger());
+    const entities = generator.generate(ast);
+    const result = validateCrossContent(entities);
+
+    // Minimal fixture has no snapshots block, so snapshot checks are expected to fail
+    const snapshotChecks = new Set([
+      "getdx_snapshots_list_response",
+      "getdx_snapshots_info_responses",
+    ]);
+    const failures = result.checks.filter(
+      (c) => !c.passed && !snapshotChecks.has(c.name),
+    );
+    if (failures.length > 0) {
+      const names = failures.map((f) => f.name).join(", ");
+      assert.fail(`Validation failures: ${names}`);
+    }
+  });
+});