@suluk/journeys 0.3.0 → 0.4.0

package/src/promote.ts

@@ -0,0 +1,226 @@
+/**
+ * Promote-into-Zod (C040, P4). A tester marks an `Examples:` block `@public`; this lifts the block's first row into the
+ * matching Zod schema's source as `.meta({ examples: [ … ] })`, provenance-stamped — so Zod stays the LITERAL home for
+ * every example (the operator's fork), and the promoted value flows into the rendered docs as the request `.example`.
+ *
+ * SOURCE-WRITE SAFETY (this edits the maintainer's source file): the edit is MARKED (`@suluk-public`), IDEMPOTENT
+ * (re-promoting replaces the marked block, never double-appends), and NEVER CLOBBERS a hand-authored example (if the
+ * schema already carries an unmarked top-level `.meta({ examples })`, it REFUSES and asks the maintainer to resolve).
+ * The functions here are PURE (string in → string out); the consumer's bin runs `mizan_check_action_safety` before
+ * writing and the maintainer reviews the git diff. Reuses @suluk/examples' coercion shape; never invents a value.
+ */
+import type { Feature } from "./gherkin";
+import type { JsonSchema } from "@suluk/examples";
+
+const PUBLIC_MARK = "@suluk-public";
+
+export interface PublicExampleRow {
+  scenario: string;
+  headers: string[];
+  /** the FIRST row of the `@public`-tagged Examples block — the canonical public example. */
+  row: string[];
+}
+
+/** Every `@public`-tagged Examples block's first row (the tester's curated public example). Pure. */
+export function extractPublicRows(features: Feature[]): PublicExampleRow[] {
+  const out: PublicExampleRow[] = [];
+  for (const f of features) {
+    for (const sc of f.scenarios) {
+      const ex = sc.examples;
+      const isPublic = !!ex && (ex.tags?.includes("public") || sc.tags?.includes("public"));
+      if (ex && isPublic && ex.headers.length && ex.rows.length) {
+        out.push({ scenario: sc.name, headers: ex.headers, row: ex.rows[0] });
+      }
+    }
+  }
+  return out;
+}
+
+/** Coerce a table cell to a concrete value by the field's declared type; with no schema, infer from the cell content. */
+function coerce(cell: string, fieldSchema?: JsonSchema): unknown {
+  const t = fieldSchema && typeof fieldSchema === "object" ? fieldSchema.type : undefined;
+  const type = Array.isArray(t) ? t[0] : t;
+  if ((type === "integer" || type === "number") && cell.trim() !== "" && Number.isFinite(Number(cell))) return Number(cell);
+  if (type === "boolean" && (cell === "true" || cell === "false")) return cell === "true";
+  if (type) return cell; // a declared string/other type stays a string verbatim
+  // no schema: infer a number/boolean from the content, else keep the string.
+  if (/^-?\d+(\.\d+)?$/.test(cell.trim())) return Number(cell);
+  if (cell === "true" || cell === "false") return cell === "true";
+  return cell;
+}
+
+/**
+ * Build a concrete public example object from a row, coercing by the body schema's field types. A WIRING TOKEN cell
+ * (`<op.select>`) is skipped — a public docs example holds concrete values, not a chaining instruction.
+ */
+export function buildExampleObject(headers: string[], row: string[], bodySchema?: JsonSchema): Record<string, unknown> {
+  const props = (bodySchema?.properties ?? {}) as Record<string, JsonSchema>;
+  const out: Record<string, unknown> = {};
+  headers.forEach((h, i) => {
+    const cell = (row[i] ?? "").trim();
+    if (/^<[^>]+>$/.test(cell)) return; // a sourced wiring token is not a concrete public value
+    out[h] = coerce(cell, props[h]);
+  });
+  return out;
+}
+
+// ---- the source-editing core (string-aware paren/bracket scanning; never regex-balances JSON) ----
+
+const escapeRe = (s: string) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+
+/** From `(` at `open`, the index of the matching `)`, skipping string literals. -1 if unbalanced. */
+function matchParen(text: string, open: number): number {
+  let depth = 0;
+  let str: string | null = null;
+  for (let i = open; i < text.length; i++) {
+    const ch = text[i];
+    if (str) {
+      if (ch === "\\") i++;
+      else if (ch === str) str = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") str = ch;
+    else if (ch === "(") depth++;
+    else if (ch === ")" && --depth === 0) return i;
+  }
+  return -1;
+}
+
+/** The index of the top-level `;` ending the expression that starts at `from`, skipping strings + nested brackets. */
+function statementEnd(text: string, from: number): number {
+  let depth = 0;
+  let str: string | null = null;
+  for (let i = from; i < text.length; i++) {
+    const ch = text[i];
+    if (str) {
+      if (ch === "\\") i++;
+      else if (ch === str) str = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") str = ch;
+    else if (ch === "(" || ch === "{" || ch === "[") depth++;
+    else if (ch === ")" || ch === "}" || ch === "]") depth--;
+    else if (ch === ";" && depth === 0) return i;
+  }
+  return -1;
+}
+
+/** The LAST top-level `.meta(…)` call in `expr` (depth 0 — not a property's `.meta`), or null. */
+function topLevelMeta(expr: string): { start: number; end: number; marked: boolean; hasExamples: boolean } | null {
+  let depth = 0;
+  let str: string | null = null;
+  let last: { start: number; end: number; marked: boolean; hasExamples: boolean } | null = null;
+  for (let i = 0; i < expr.length; i++) {
+    const ch = expr[i];
+    if (str) {
+      if (ch === "\\") i++;
+      else if (ch === str) str = null;
+      continue;
+    }
+    if (ch === '"' || ch === "'" || ch === "`") {
+      str = ch;
+      continue;
+    }
+    if (ch === "." && depth === 0 && expr.startsWith(".meta(", i)) {
+      const end = matchParen(expr, i + 5);
+      if (end > 0) {
+        const content = expr.slice(i, end + 1);
+        last = { start: i, end, marked: content.includes(PUBLIC_MARK), hasExamples: /\bexamples\b/.test(content) };
+        i = end;
+        continue;
+      }
+    }
+    if (ch === "(" || ch === "{" || ch === "[") depth++;
+    else if (ch === ")" || ch === "}" || ch === "]") depth--;
+  }
+  return last;
+}
+
+const renderMeta = (example: unknown, provenance: string) => `.meta(/* ${PUBLIC_MARK}: ${provenance} */ { examples: [${JSON.stringify(example)}] })`;
+
+export interface PromoteResult {
+  source: string;
+  changed: boolean;
+  reason: string;
+}
+
+/**
+ * Promote `example` into the source of the Zod schema bound to `const <schemaVar> = …`. Idempotent (re-promote replaces
+ * the marked block), marked, and refuses to clobber a hand-authored top-level `.meta({ examples })`.
+ */
+export function promoteExampleIntoZod(source: string, schemaVar: string, example: unknown, provenance: string): PromoteResult {
+  const decl = new RegExp(`(^|[\\n;{])\\s*(export\\s+)?const\\s+${escapeRe(schemaVar)}\\s*=`);
+  const m = decl.exec(source);
+  if (!m) return { source, changed: false, reason: `schema \`${schemaVar}\` not found` };
+  const eqIdx = m.index + m[0].length - 1; // the "="
+  const exprStart = eqIdx + 1;
+  const semi = statementEnd(source, exprStart);
+  if (semi < 0) return { source, changed: false, reason: `could not find the end of \`${schemaVar}\`'s declaration` };
+
+  const expr = source.slice(exprStart, semi);
+  const meta = renderMeta(example, provenance);
+  const top = topLevelMeta(expr);
+
+  let newExpr: string;
+  if (top?.marked) {
+    newExpr = expr.slice(0, top.start) + meta + expr.slice(top.end + 1); // idempotent replace of the promoted block
+  } else if (top?.hasExamples) {
+    return { source, changed: false, reason: `\`${schemaVar}\` already has a hand-authored .meta({ examples }) — not clobbering; merge the public example manually` };
+  } else if (top) {
+    newExpr = expr.slice(0, top.end + 1) + " " + meta + expr.slice(top.end + 1); // append after a non-example .meta (merges safely)
+  } else {
+    const trimmed = expr.replace(/\s+$/, "").length;
+    newExpr = expr.slice(0, trimmed) + meta + expr.slice(trimmed);
+  }
+
+  if (newExpr === expr) return { source, changed: false, reason: "no change" };
+  return {
+    source: source.slice(0, exprStart) + newExpr + source.slice(semi),
+    changed: true,
+    reason: top?.marked ? `updated the promoted example on \`${schemaVar}\`` : `promoted a public example into \`${schemaVar}\``,
+  };
+}
+
+export interface PromoteTarget {
+  /** the Zod `const` name to edit. */
+  schemaVar: string;
+  /** the op's request body schema (for typed cell coercion); optional. */
+  bodySchema?: JsonSchema;
+}
+
+export interface PromoteFeatureResult {
+  source: string;
+  applied: { scenario: string; schemaVar: string; reason: string }[];
+  skipped: { scenario: string; reason: string }[];
+}
+
+/**
+ * Orchestrate promotion for a whole feature set: for each `@public` Examples row, resolve its target (the consumer maps
+ * scenario → schemaVar + body schema — the app knows that wiring), build the example, and apply it. Adapter-seam shaped.
+ */
+export function promoteFeatureExamples(
+  source: string,
+  features: Feature[],
+  resolveTarget: (scenario: string) => PromoteTarget | null,
+  provenancePrefix = "promoted from",
+): PromoteFeatureResult {
+  let src = source;
+  const applied: PromoteFeatureResult["applied"] = [];
+  const skipped: PromoteFeatureResult["skipped"] = [];
+  for (const pub of extractPublicRows(features)) {
+    const target = resolveTarget(pub.scenario);
+    if (!target) {
+      skipped.push({ scenario: pub.scenario, reason: "no target schema resolved for this scenario" });
+      continue;
+    }
+    const example = buildExampleObject(pub.headers, pub.row, target.bodySchema);
+    const r = promoteExampleIntoZod(src, target.schemaVar, example, `${provenancePrefix} ${pub.scenario}`);
+    if (r.changed) {
+      src = r.source;
+      applied.push({ scenario: pub.scenario, schemaVar: target.schemaVar, reason: r.reason });
+    } else {
+      skipped.push({ scenario: pub.scenario, reason: r.reason });
+    }
+  }
+  return { source: src, applied, skipped };
+}

package/test/audit.test.ts

@@ -0,0 +1,90 @@
+import { test, expect, describe } from "bun:test";
+import { buildAudit } from "../src/cli";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * C043 — the unified `journeys audit`: harden SECURITY + harden READINESS + journeys COVERAGE, folded by letter via
+ * harden's combineGrades. Coverage is journeys-owned (needs the features); harden never depends on journeys.
+ */
+const docJson = JSON.stringify({
+  openapi: "4.0.0-candidate",
+  info: { title: "Billing" },
+  paths: {
+    "/charge": {
+      requests: {
+        charge: {
+          method: "post",
+          contentSchema: {
+            type: "object",
+            additionalProperties: false,
+            required: ["amountCents", "balance"],
+            properties: {
+              amountCents: { type: "integer" }, // no maximum → a SECURITY finding
+              balance: { type: "integer", "x-suluk-origin": "computed" }, // required+computed → a READINESS finding
+            },
+          },
+        },
+      },
+    },
+    "/health": { requests: { health: { method: "get", responses: { "200": { status: 200 } } } } },
+  },
+});
+const feature = "Feature: f\n  Scenario: charge it\n    When I charge\n    Then it succeeds\n";
+
+describe("buildAudit", () => {
+  test("doc-only: security + readiness dimensions, no coverage, combined of 2", () => {
+    const a = buildAudit(docJson);
+    expect(a.combined.grades).toHaveLength(2);
+    expect(a.coverage).toBeUndefined();
+    expect(a.readiness.findings.some((f) => f.rule === "computed-required")).toBe(true);
+    expect(a.security.findings.some((f) => f.rule === "number-maximum")).toBe(true);
+  });
+
+  test("with features: coverage dimension included (combined of 3), uncovered ops surfaced", () => {
+    const a = buildAudit(docJson, [feature]);
+    expect(a.combined.grades).toHaveLength(3);
+    expect(a.coverage).toBeDefined();
+    expect(a.coverage!.covered).toBe(1); // charge covered
+    expect(a.coverage!.uncovered).toContain("health"); // health is a gap → generate an outline
+  });
+
+  test("the combined worst is the lowest dimension (the safe gate value)", () => {
+    const a = buildAudit(docJson, [feature]);
+    const ORDER = ["F", "D", "C", "B", "A"];
+    const min = a.combined.grades.reduce((w, g) => (ORDER.indexOf(g) < ORDER.indexOf(w) ? g : w), "A");
+    expect(a.combined.worst).toBe(min);
+  });
+});
+
+describe("bin: `journeys audit` end-to-end", () => {
+  const bin = join(import.meta.dir, "..", "bin", "journeys.ts");
+
+  test("prints all three dimensions + a combined grade; --min gates", () => {
+    const dir = mkdtempSync(join(tmpdir(), "journeys-audit-"));
+    try {
+      const docPath = join(dir, "openapi.json");
+      const featDir = join(dir, "features");
+      mkdirSync(featDir);
+      writeFileSync(docPath, docJson);
+      writeFileSync(join(featDir, "billing.feature"), feature);
+
+      const run = Bun.spawnSync(["bun", bin, "audit", "--doc", docPath, "--features", featDir]);
+      expect(run.exitCode).toBe(0);
+      const out = run.stdout.toString();
+      expect(out).toContain("security");
+      expect(out).toContain("readiness");
+      expect(out).toContain("coverage");
+      expect(out).toContain("combined");
+      expect(out).toContain("uncovered");
+
+      // gate on an impossible-to-meet minimum → non-zero exit
+      const gated = Bun.spawnSync(["bun", bin, "audit", "--doc", docPath, "--features", featDir, "--min", "A"]);
+      expect(gated.exitCode).toBe(1);
+      expect(gated.stderr.toString()).toContain("below the required A");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+});

package/test/cli.test.ts

@@ -0,0 +1,78 @@
+import { test, expect, describe } from "bun:test";
+import { buildDemoFiles } from "../src/cli";
+import { mkdtempSync, rmSync, existsSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * C042 CLI — `journeys demos` compiles `.feature` files into a Bruno/Postman demo collection on disk. buildDemoFiles is
+ * the pure core (no fs); the bin is thin IO around it. Both are exercised here (unit + an end-to-end spawn).
+ */
+const docJson = JSON.stringify({
+  openapi: "4.0.0-candidate",
+  info: { title: "Billing" },
+  paths: {
+    "/subs": { requests: { createSubscription: { method: "post", contentSchema: { type: "object", required: ["plan"], properties: { plan: { type: "string" } } }, responses: { "200": { status: 200 } }, "x-suluk-access": { requires: "authenticated" } } } },
+    "/charge": { requests: { charge: { method: "post", contentSchema: { type: "object", required: ["amountCents", "subscriptionId"], properties: { amountCents: { type: "integer", minimum: 100 }, subscriptionId: { type: "string", "x-suluk-origin": "sourced", "x-suluk-from": { op: "createSubscription", select: "id" } } } }, responses: { "200": { status: 200 } }, "x-suluk-access": { requires: "authenticated" } } } },
+  },
+});
+const featureText = "Feature: billing demo\n  Scenario: subscribe then charge\n    When I create subscription\n    And I charge\n";
+
+describe("buildDemoFiles", () => {
+  test("format bruno → a Bruno file map (chaining preserved)", () => {
+    const r = buildDemoFiles(docJson, [featureText], { format: "bruno", baseUrl: "https://api.example.com" });
+    expect([r.scenarios, r.requests]).toEqual([1, 2]);
+    expect(r.files["bruno.json"]).toBeDefined();
+    expect(r.files["environments/prod.bru"]).toContain("https://api.example.com");
+    expect(r.files["subscribe-then-charge/2-charge.bru"]).toContain('"subscriptionId": "{{createSubscription_id}}"');
+  });
+
+  test("format postman → a single v2.1 collection json", () => {
+    const r = buildDemoFiles(docJson, [featureText], { format: "postman", name: "Billing" });
+    expect(Object.keys(r.files)).toEqual(["billing.postman_collection.json"]);
+    expect(JSON.parse(r.files["billing.postman_collection.json"]).info.schema).toContain("v2.1.0");
+  });
+
+  test("format both → bruno/ and postman/ prefixed, no collision", () => {
+    const r = buildDemoFiles(docJson, [featureText], { format: "both", name: "Billing" });
+    expect(r.files["bruno/bruno.json"]).toBeDefined();
+    expect(r.files["postman/billing.postman_collection.json"]).toBeDefined();
+  });
+
+  test("name defaults to the contract's info.title", () => {
+    const r = buildDemoFiles(docJson, [featureText], { format: "postman" });
+    expect(r.files["billing.postman_collection.json"]).toBeDefined();
+  });
+});
+
+describe("bin: `journeys demos` end-to-end on disk", () => {
+  test("writes the collection files to --out (real spawn)", () => {
+    const dir = mkdtempSync(join(tmpdir(), "journeys-cli-"));
+    try {
+      const docPath = join(dir, "openapi.json");
+      const featDir = join(dir, "features");
+      const outDir = join(dir, "out");
+      mkdirSync(featDir);
+      writeFileSync(docPath, docJson);
+      writeFileSync(join(featDir, "billing.feature"), featureText);
+
+      const bin = join(import.meta.dir, "..", "bin", "journeys.ts");
+      const proc = Bun.spawnSync(["bun", bin, "demos", "--doc", docPath, "--features", featDir, "--out", outDir, "--format", "bruno", "--base-url", "https://api.example.com"]);
+
+      expect(proc.exitCode).toBe(0);
+      expect(proc.stdout.toString()).toContain("1 scenario(s), 2 request(s)");
+      expect(existsSync(join(outDir, "bruno.json"))).toBe(true);
+      const charge = join(outDir, "subscribe-then-charge", "2-charge.bru");
+      expect(existsSync(charge)).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("missing required flags → non-zero exit + usage", () => {
+    const bin = join(import.meta.dir, "..", "bin", "journeys.ts");
+    const proc = Bun.spawnSync(["bun", bin, "demos", "--doc", "x.json"]);
+    expect(proc.exitCode).toBe(1);
+    expect(proc.stderr.toString()).toContain("required");
+  });
+});

package/test/demos.test.ts

@@ -0,0 +1,126 @@
+import { test, expect, describe } from "bun:test";
+import { generateVocabulary } from "../src/vocabulary";
+import { parseFeature } from "../src/gherkin";
+import { compileDemos, renderPostman, renderBruno } from "../src/demos";
+import type { OpenAPIv4Document } from "@suluk/core";
+
+/**
+ * C042 — compile a bound feature into a Bruno/Postman DEMO collection: ordered requests, body from the Examples row (or
+ * synthesized), sourced fields wired to request CHAINING (capture → {{var}}), auth + a {{baseUrl}} that a developer
+ * points at localhost first and the presenter switches to prod for the live call.
+ */
+const doc = {
+  openapi: "4.0.0-candidate",
+  info: { title: "Billing" },
+  paths: {
+    "/subs": {
+      requests: {
+        createSubscription: {
+          method: "post",
+          contentSchema: { type: "object", required: ["plan"], properties: { plan: { type: "string" } } },
+          responses: { ok: { status: 200 } },
+          "x-suluk-access": { requires: "authenticated" },
+        },
+      },
+    },
+    "/charge": {
+      requests: {
+        charge: {
+          method: "post",
+          contentSchema: {
+            type: "object",
+            required: ["amountCents", "subscriptionId"],
+            properties: {
+              amountCents: { type: "integer", minimum: 100 },
+              subscriptionId: { type: "string", "x-suluk-origin": "sourced", "x-suluk-from": { op: "createSubscription", select: "id" } },
+            },
+          },
+          responses: { ok: { status: 200 } },
+          "x-suluk-access": { requires: "authenticated" },
+        },
+      },
+    },
+  },
+} as unknown as OpenAPIv4Document;
+
+const feature = parseFeature(
+  ["Feature: billing demo", "  Scenario: subscribe then charge", "    When I create subscription", "    And I charge"].join("\n"),
+);
+const demos = compileDemos(doc, generateVocabulary(doc), [feature]);
+
+describe("compileDemos — the IR", () => {
+  test("ordered requests per scenario, method + path from the contract", () => {
+    expect(demos).toHaveLength(1);
+    expect(demos[0].requests.map((r) => [r.method, r.path])).toEqual([
+      ["POST", "/subs"],
+      ["POST", "/charge"],
+    ]);
+  });
+
+  test("the body is synthesized when there's no Examples table; computed dropped", () => {
+    expect(demos[0].requests[0].body).toEqual({ plan: { kind: "literal", value: "plan" } });
+  });
+
+  test("a sourced field becomes a {{var}} reference, and the SOURCE request captures it", () => {
+    const charge = demos[0].requests[1];
+    expect(charge.body!.subscriptionId).toEqual({ kind: "var", name: "createSubscription_id" });
+    const create = demos[0].requests[0];
+    expect(create.captures).toEqual([{ var: "createSubscription_id", from: "id" }]);
+  });
+
+  test("auth is flagged from x-suluk-access", () => {
+    expect(demos[0].requests.every((r) => r.needsAuth)).toBe(true);
+  });
+});
+
+describe("renderPostman", () => {
+  const json = renderPostman(demos, { name: "Billing demo", baseUrl: "https://api.example.com" });
+  const collection = JSON.parse(json);
+
+  test("a v2.1 collection with baseUrl (local-first) + prodBaseUrl + token variables", () => {
+    expect(collection.info.schema).toContain("v2.1.0");
+    const vars = Object.fromEntries(collection.variable.map((v: any) => [v.key, v.value]));
+    expect(vars.baseUrl).toBe("http://localhost:8787"); // dev-first
+    expect(vars.prodBaseUrl).toBe("https://api.example.com");
+    expect(vars).toHaveProperty("token");
+  });
+
+  test("the charge request body references the chained var, and create captures it via a test script", () => {
+    const folder = collection.item[0];
+    const create = folder.item[0];
+    const charge = folder.item[1];
+    expect(charge.request.body.raw).toContain('"subscriptionId": "{{createSubscription_id}}"');
+    const createScript = create.event.find((e: any) => e.listen === "test").script.exec.join("\n");
+    expect(createScript).toContain('pm.collectionVariables.set("createSubscription_id", pm.response.json().id)');
+  });
+
+  test("auth'd requests carry a bearer header + a 2xx test", () => {
+    const create = collection.item[0].item[0];
+    expect(create.request.header).toContainEqual({ key: "Authorization", value: "Bearer {{token}}" });
+    expect(create.event[0].script.exec.join("\n")).toContain("below(300)");
+  });
+});
+
+describe("renderBruno", () => {
+  const files = renderBruno(demos, { name: "Billing demo", baseUrl: "https://api.example.com" });
+
+  test("emits a collection manifest + BOTH local and prod environments", () => {
+    expect(files["bruno.json"]).toContain('"name": "Billing demo"');
+    expect(files["environments/local.bru"]).toContain("baseUrl: http://localhost:8787");
+    expect(files["environments/prod.bru"]).toContain("baseUrl: https://api.example.com");
+  });
+
+  test("a .bru file per request, sequenced, with method/url/body", () => {
+    const create = files["subscribe-then-charge/1-createsubscription.bru"];
+    const charge = files["subscribe-then-charge/2-charge.bru"];
+    expect(create).toContain("post {\n  url: {{baseUrl}}/subs");
+    expect(create).toContain("auth: bearer");
+    expect(charge).toContain('"subscriptionId": "{{createSubscription_id}}"');
+  });
+
+  test("the source request captures the chained var via a post-response script", () => {
+    const create = files["subscribe-then-charge/1-createsubscription.bru"];
+    expect(create).toContain('bru.setVar("createSubscription_id", res.body.id);');
+    expect(create).toContain("res.status: lt 300");
+  });
+});

package/test/emit-outline.test.ts

@@ -0,0 +1,95 @@
+import { test, expect, describe } from "bun:test";
+import { generateVocabulary } from "../src/vocabulary";
+import { parseFeature } from "../src/gherkin";
+import { emitRunnableSuite } from "../src/emit";
+import type { OpenAPIv4Document } from "@suluk/core";
+
+/**
+ * C040-P1 (runnable half) — a Scenario Outline runs PER Examples row through the generated SDK client; an `input` cell
+ * is a coerced literal, a `sourced` cell <op.select> is RESOLVED from a prior step's captured response (chaining across
+ * a multi-step journey). Each bound When's result is captured under its op.name so a later sourced field reads it.
+ */
+const doc = {
+  openapi: "4.0.0-candidate",
+  info: { title: "Billing" },
+  paths: {
+    "/subs": {
+      requests: {
+        createSubscription: {
+          method: "post",
+          contentSchema: { type: "object", required: ["plan"], properties: { plan: { type: "string" } } },
+          responses: { ok: { status: 200 } },
+        },
+      },
+    },
+    "/charge": {
+      requests: {
+        charge: {
+          method: "post",
+          contentSchema: {
+            type: "object",
+            required: ["amountCents", "subscriptionId"],
+            properties: {
+              amountCents: { type: "integer", minimum: 100 },
+              subscriptionId: { type: "string", "x-suluk-origin": "sourced", "x-suluk-from": { op: "createSubscription", select: "id" } },
+            },
+          },
+          responses: { ok: { status: 200 } },
+        },
+      },
+    },
+  },
+} as unknown as OpenAPIv4Document;
+
+const feature = parseFeature(
+  [
+    "Feature: billing journeys",
+    "  Scenario Outline: subscribe then charge",
+    "    When I create subscription",
+    "    And I charge",
+    "    Examples:",
+    "      | plan | amountCents | subscriptionId          |",
+    "      | pro  | 100         | <createSubscription.id> |",
+    "      | team | 250         | <createSubscription.id> |",
+  ].join("\n"),
+);
+
+describe("emitRunnableSuite — outline rows + sourced chaining", () => {
+  const suite = emitRunnableSuite(doc, generateVocabulary(doc), [feature]);
+
+  test("unrolls one test per Examples row", () => {
+    expect(suite).toContain('test("subscribe then charge — example 1"');
+    expect(suite).toContain('test("subscribe then charge — example 2"');
+  });
+
+  test("inlines the pick() helper + a per-row captured bag", () => {
+    expect(suite).toContain("const pick =");
+    expect(suite).toContain("const captured: Record<string, any> = {}");
+  });
+
+  test("builds each When op's body from the row, mapping columns to that op's fields by name", () => {
+    expect(suite).toContain('{ plan: "pro" }'); // createSubscription gets only its own field
+    expect(suite).toContain("amountCents: 100"); // input cell coerced to a number literal (its type)
+  });
+
+  test("a sourced cell resolves from the prior captured response (chaining), not a literal", () => {
+    expect(suite).toContain('subscriptionId: pick(captured, "createSubscription", "id")');
+  });
+
+  test("captures each bound When's result under its op.name for downstream chaining", () => {
+    expect(suite).toContain('captured["createSubscription"] = result1');
+    expect(suite).toContain('captured["charge"] = result2');
+  });
+
+  test("row 2 uses its own input value", () => {
+    expect(suite).toContain("amountCents: 250");
+  });
+
+  test("a plain (non-outline) scenario still emits a single test with a provide-input placeholder", () => {
+    const plain = parseFeature("Feature: f\n\n  Scenario: just charge\n    When I charge\n    Then it succeeds\n");
+    const out = emitRunnableSuite(doc, generateVocabulary(doc), [plain]);
+    expect(out).toContain('test("just charge"');
+    expect(out).toContain("/* provide input */");
+    expect(out).not.toContain("const captured");
+  });
+});

package/test/examples-wall.test.ts

@@ -0,0 +1,31 @@
+import { test, expect, describe } from "bun:test";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+
+/**
+ * THE VALUE WALL (C040) — the mirror of the C039 hatch wall, one layer over. Examples are request/response VALUES, and
+ * `examples.ts` SYNTHESIZES them. The deterministic PROJECTOR CORE (the vocabulary projection + the binder + the parser
+ * + normalization) names only contract FACTS and must never reach the value-synthesis layer — otherwise a value could
+ * leak into a place the D1 wall keeps fact-only. Subpath/module naming is not compiler-enforced, so this asserts it over
+ * the source. It also pins `examples.ts` as SELF-CONTAINED (no journeys-internal, no external import) so it stays a
+ * one-file extraction if @suluk/reference / @suluk/sdk later want the resolver.
+ */
+const src = (rel: string) => readFileSync(join(import.meta.dir, "..", "src", rel), "utf8");
+
+// The pure projector core — produces contract-derived FACTS and the bind decision. It must not import the value layer.
+const PROJECTOR_CORE = ["vocabulary.ts", "bind.ts", "gherkin.ts", "normalize.ts"];
+const NO_EXAMPLES = /from\s+["']\.{1,2}\/examples["']/;
+
+describe("C040 value wall — the projector core never imports the example/value synthesis layer", () => {
+  for (const file of PROJECTOR_CORE) {
+    test(`src/${file}: does not import ./examples`, () => {
+      expect(NO_EXAMPLES.test(src(file))).toBe(false);
+    });
+  }
+
+  test("src/examples.ts is a pure re-export of the shared @suluk/examples leaf (no relative value-layer import)", () => {
+    const body = src("examples.ts");
+    expect(/export\s+\*\s+from\s+["']@suluk\/examples["']/.test(body)).toBe(true);
+    expect(/from\s+["']\.{1,2}\//.test(body)).toBe(false); // the impl lives in the leaf, not a journeys-relative file
+  });
+});