@suluk/journeys 0.3.0 → 0.4.0

package/src/emit.ts

@@ -1,6 +1,6 @@
 /**
- * The RUNNABLE emitter (C038): a bound feature set → a self-contained `bun:test` suite that drives each scenario
- * through the consumer's GENERATED @suluk/sdk client (+ its reactive stores), against a LIVE deployment.
+ * The RUNNABLE emitter (C038 + C040-P1): a bound feature set → a self-contained `bun:test` suite that drives each
+ * scenario through the consumer's GENERATED @suluk/sdk client (+ its reactive stores), against a LIVE deployment.
  *
  * Why the SDK client and not raw HTTP (the distinction from @suluk/testgen, which calls a raw `fetch(BASE+path)`
  * harness): the SDK client is the SAME one a Suluk frontend ships on, so a green scenario exercises the real frontend
@@ -8,11 +8,16 @@
  * invalidation/refetch. HONEST BOUNDARY (emitted as a literal header in the suite): it tests
  * client + contract + wire + the store data layer, NOT rendered UI / layout / visual — there is no DOM in a bun:test.
  *
+ * SCENARIO OUTLINES (C040-P1): a scenario with an `Examples:` table is unrolled to ONE test PER ROW; the bound When op's
+ * request body is built FROM THE ROW (an Examples column = a request field of that op, by name). An `input` cell is used
+ * as a literal (coerced to the field's type); a `sourced` cell `<op.select>` is RESOLVED from a prior step's captured
+ * response via the inlined `pick` (carried-data across a journey — `resolveSourced`'s shape). Each bound When's result
+ * is captured under its `op.name`, so a later sourced field chains from it. Where a value isn't supplied (no Examples
+ * table, or an op with path/query args not yet outline-wired) the emitter writes a "provide input" placeholder — a real
+ * gap, never an invented value (the never-launder-thin discipline).
+ *
  * The call site is lowered with @suluk/sdk's OWN `resolveOps` + `clientAccessor` — the single source of accessor
- * identity — so the emitted `client.<ns>.<member>(…)` can NEVER drift from the method `generateSdk` actually emits.
- * Journeys keeps `op.name@path` as the stable handle for IDENTITY; the SDK accessor (which `resolveOps` mutates) is
- * used ONLY here, at the late call-site lowering. Where an operation needs a request value the emitter writes a
- * "provide input" placeholder (a real NEEDS-DEV-GLUE), never an invented value (the never-launder-thin discipline).
+ * identity — so the emitted `client.<ns>.<member>(…)` can NEVER drift from the method `generateSdk` emits.
  */
 import type { OpenAPIv4Document } from "@suluk/core";
 import { resolveOps, clientAccessor, type OpInfo } from "@suluk/sdk";
@@ -31,6 +36,35 @@ export interface EmitOptions extends BindOptions {
   tokenEnv?: string;
 }
 
+const JS_ID = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const jsKey = (k: string) => (JS_ID.test(k) ? k : JSON.stringify(k));
+/** A `sourced` Examples cell: the wiring token `<op.select>` (e.g. `<createSubscription.id>`). */
+const SOURCED_CELL = /^<([A-Za-z_][\w]*)\.(.+)>$/;
+
+/** An Examples cell → a TS literal: a `<op.select>` token → `pick(captured,…)`; else coerced by the field's type. */
+function cellLiteral(cell: string, fieldSchema: unknown): string {
+  const m = SOURCED_CELL.exec(cell.trim());
+  if (m) return `pick(captured, ${JSON.stringify(m[1])}, ${JSON.stringify(m[2])})`;
+  const t = fieldSchema && typeof fieldSchema === "object" ? (fieldSchema as { type?: unknown }).type : undefined;
+  const type = Array.isArray(t) ? t[0] : t;
+  if ((type === "integer" || type === "number") && cell.trim() !== "" && Number.isFinite(Number(cell))) return String(Number(cell));
+  if (type === "boolean" && (cell === "true" || cell === "false")) return cell;
+  return JSON.stringify(cell);
+}
+
+/** The call args for an outline row, or null if the op needs path/query args (not yet outline-wired → placeholder). */
+function buildCallArgs(op: OpInfo, cells: Record<string, string>): string | null {
+  if (op.pathParams.length || op.queryRaw != null) return null;
+  if (op.bodyRaw == null) return "";
+  const props = (op.bodyRaw && typeof op.bodyRaw === "object" ? (op.bodyRaw as { properties?: Record<string, unknown> }).properties : undefined) ?? {};
+  const entries: string[] = [];
+  for (const [h, cell] of Object.entries(cells)) {
+    if (!(h in props)) continue; // a column belonging to ANOTHER When op in a multi-step journey
+    entries.push(`${jsKey(h)}: ${cellLiteral(cell, (props as Record<string, unknown>)[h])}`);
+  }
+  return `{ ${entries.join(", ")} }`;
+}
+
 /** Emit a runnable bun:test suite (a string) from a parsed, bound feature set, lowered to the real SDK client. */
 export function emitRunnableSuite(doc: OpenAPIv4Document, vocab: Vocabulary, features: Feature[], opts: EmitOptions = {}): string {
   const clientModule = opts.clientModule ?? "./sdk";
@@ -39,6 +73,9 @@ export function emitRunnableSuite(doc: OpenAPIv4Document, vocab: Vocabulary, fea
   const tokenEnv = opts.tokenEnv ?? "SULUK_USER_TOKEN";
 
   const report = bindFeatures(vocab, features, opts);
+  // report.scenarios is pushed in feature→scenario order, so it aligns 1:1 with the flattened source scenarios; the
+  // source carries the Examples table the binder does not.
+  const sourceScenarios = features.flatMap((f) => f.scenarios);
   // accessor identity comes from @suluk/sdk itself, keyed by the STABLE handle (name@uri — neither is mutated by resolveOps).
   const { ops } = resolveOps(doc);
   const opByHandle = new Map<string, OpInfo>(ops.map((op) => [`${op.name}@${op.uri}`, op]));
@@ -49,6 +86,9 @@ export function emitRunnableSuite(doc: OpenAPIv4Document, vocab: Vocabulary, fea
     `import { test, expect } from "bun:test";`,
     `import { ${clientFactory} } from "${clientModule}";`,
     ``,
+    `// resolve a \`sourced\` Examples cell <op.select> from a prior step's captured response (carried-data across a journey).`,
+    `const pick = (captured: Record<string, any>, op: string, sel: string) => sel.split(".").reduce((v: any, k) => (v == null ? undefined : v[k]), captured[op]);`,
+    ``,
     `const client = ${clientFactory}({`,
     `  baseURL: process.env.${baseUrlEnv},`,
     `  token: () => process.env.${tokenEnv} ?? null, // bearer; cookie auth also works via credentials:"include"`,
@@ -57,14 +97,13 @@ export function emitRunnableSuite(doc: OpenAPIv4Document, vocab: Vocabulary, fea
   ];
 
   const body: string[] = [];
-  for (const sc of report.scenarios) {
-    // emit a call for EACH bound When (a composed / multi-step journey drives several actions in order).
-    const bound = sc.results.filter((r) => r.state === "BOUND" && r.step.kind === "when");
-    if (!bound.length) continue;
-    body.push(`test(${JSON.stringify(sc.scenario)}, async () => {`);
+
+  /** Emit the bound When calls (+ outcome assertions) for one scenario run. `cells` non-null ⇒ an outline row (build
+   *  the body + capture for chaining); null ⇒ the plain path (a "provide input" placeholder). */
+  const emitCalls = (results: typeof report.scenarios[number]["results"], cells: Record<string, string> | null) => {
     let n = 0;
     let current: OpInfo | undefined;
-    for (const r of sc.results) {
+    for (const r of results) {
       if (r.state !== "BOUND") continue;
       if (r.step.kind === "when") {
         current = opByHandle.get(r.handle);
@@ -72,15 +111,44 @@ export function emitRunnableSuite(doc: OpenAPIv4Document, vocab: Vocabulary, fea
           body.push(`  // skipped ${r.handle} — not an SDK-surfaced operation (e.g. a webhook); bind via raw HTTP.`);
           continue;
         }
-        const acc = clientAccessor(current); // e.g. "billing.checkout", "credits.get"
+        const acc = clientAccessor(current);
         body.push(`  // ${current.method.toUpperCase()} ${current.uri}${current.requires !== "anyone" ? `  (requires ${current.requires}: set ${tokenEnv})` : ""}`);
-        body.push(`  const result${++n} = await client.${acc}(/* provide input */);`);
+        n++;
+        if (cells) {
+          const args = buildCallArgs(current, cells);
+          body.push(args === null
+            ? `  const result${n} = await client.${acc}(/* provide input — path/query args not yet outline-wired */);`
+            : `  const result${n} = await client.${acc}(${args});`);
+          body.push(`  captured[${JSON.stringify(current.name)}] = result${n};`);
+        } else {
+          body.push(`  const result${n} = await client.${acc}(/* provide input */);`);
+        }
       } else if (r.step.kind === "then" && current) {
         if (/succeed/i.test(r.step.text) && n) body.push(`  expect(result${n}).toBeDefined();`);
         if (/refresh/i.test(r.step.text)) for (const key of current.store?.invalidates ?? []) body.push(`  // store: expect $${key} to have refreshed after this mutation`);
       }
     }
-    body.push(`});`, ``);
+  };
+
+  for (let i = 0; i < report.scenarios.length; i++) {
+    const sc = report.scenarios[i];
+    if (!sc.results.some((r) => r.state === "BOUND" && r.step.kind === "when")) continue;
+    const ex = sourceScenarios[i]?.examples;
+
+    if (ex && ex.headers.length && ex.rows.length) {
+      // OUTLINE: one test per Examples row, body built from the row + sourced cells chained via `captured`.
+      ex.rows.forEach((row, ri) => {
+        const cells = Object.fromEntries(ex.headers.map((h, ci) => [h, row[ci] ?? ""]));
+        body.push(`test(${JSON.stringify(`${sc.scenario} — example ${ri + 1}`)}, async () => {`);
+        body.push(`  const captured: Record<string, any> = {};`);
+        emitCalls(sc.results, cells);
+        body.push(`});`, ``);
+      });
+    } else {
+      body.push(`test(${JSON.stringify(sc.scenario)}, async () => {`);
+      emitCalls(sc.results, null);
+      body.push(`});`, ``);
+    }
   }
 
   if (!body.length) body.push("// No scenario bound a When-operation yet — author steps from the generated phrasebook.");

package/src/examples.ts

@@ -0,0 +1,6 @@
+/**
+ * Example precedence + origin-aware synthesis. The implementation moved to the shared zero-dep leaf `@suluk/examples`
+ * (so `@suluk/sdk` can read it too — journeys depends on sdk, so the reader had to sit below both). journeys keeps this
+ * re-export so its public API and the projector-core wall (which forbids importing this VALUE layer) are unchanged.
+ */
+export * from "@suluk/examples";

package/src/gherkin.ts

@@ -25,6 +25,11 @@ export interface Scenario {
   rule?: string;
   steps: FeatureStep[];
   line: number;
+  /** tags on this scenario (the leading `@` stripped), e.g. ["public"]. */
+  tags?: string[];
+  /** the captured `Examples:` table of a Scenario Outline (C040-P1); absent for a plain Scenario. `tags` are from a
+   *  `@public`-style line directly above the `Examples:` keyword (C040-P4 promote selection). */
+  examples?: { headers: string[]; rows: string[][]; tags?: string[] };
 }
 
 export interface Feature {
@@ -32,19 +37,41 @@ export interface Feature {
   scenarios: Scenario[];
 }
 
-const KW = /^(Feature|Background|Rule|Scenario|Scenario Outline|Given|When|Then|And|But|Examples)\b:?\s*(.*)$/i;
+// NB: `Scenario Outline` MUST precede `Scenario` — alternation is ordered, else "Scenario Outline: x" matches the
+// shorter `Scenario` and mis-parses the name as "Outline: x".
+const KW = /^(Feature|Background|Rule|Scenario Outline|Scenario|Given|When|Then|And|But|Examples)\b:?\s*(.*)$/i;
 
 export function parseFeature(src: string): Feature {
   let feature = "";
   let rule: string | undefined;
   let cur: Scenario | null = null;
   let last: StepKind = "given";
+  let collectingExamples = false;
+  let pendingTags: string[] = [];
   const scenarios: Scenario[] = [];
   const lines = src.split("\n");
 
   lines.forEach((raw, i) => {
     const t = raw.trim();
     if (!t || t.startsWith("#")) return;
+
+    // a tag line (`@public @smoke …`) — attaches to the NEXT Scenario or Examples block.
+    if (t.startsWith("@")) {
+      pendingTags.push(...t.split(/\s+/).filter((x) => x.startsWith("@")).map((x) => x.slice(1)));
+      return;
+    }
+
+    // a `|` table row — captured ONLY while inside an Examples block (a Scenario Outline's table); otherwise ignored.
+    if (t.startsWith("|")) {
+      const c = cur;
+      if (collectingExamples && c?.examples) {
+        const cells = t.split("|").slice(1, -1).map((s) => s.trim());
+        if (c.examples.headers.length === 0) c.examples.headers = cells;
+        else c.examples.rows.push(cells);
+      }
+      return;
+    }
+
     const m = KW.exec(t);
     if (!m) return;
     const kw = m[1].toLowerCase();
@@ -52,17 +79,31 @@ export function parseFeature(src: string): Feature {
     switch (kw) {
       case "feature":
         feature = rest;
+        collectingExamples = false;
+        pendingTags = [];
         return;
       case "rule":
         rule = rest;
+        collectingExamples = false;
+        pendingTags = [];
         return;
       case "background":
+        collectingExamples = false;
+        pendingTags = [];
+        return;
       case "examples":
+        if (cur) {
+          cur.examples = { headers: [], rows: [], ...(pendingTags.length ? { tags: pendingTags } : {}) };
+          collectingExamples = true;
+        }
+        pendingTags = [];
         return;
       case "scenario":
       case "scenario outline":
-        cur = { name: rest, rule, steps: [], line: i + 1 };
+        collectingExamples = false;
+        cur = { name: rest, rule, steps: [], line: i + 1, ...(pendingTags.length ? { tags: pendingTags } : {}) };
         scenarios.push(cur);
+        pendingTags = [];
         return;
     }
     // a step keyword

package/src/hatch/index.ts

@@ -13,6 +13,7 @@
  *
  * Runtime IO only — provably outside the deterministic core (bind.ts / vocabulary.ts), enforced by hatch-wall.test.ts.
  */
+export { runScope, type RunScope, type RunScopeOptions } from "./runscope";
 export { resolveBackend, localD1, remoteD1, type BackendSpec } from "./backends";
 export { stateHatch, type StateHatchOptions } from "./state";
 export { signInAs, type SignInAsOptions, type SignedInSession, type CleanupTarget } from "./auth";

package/src/hatch/runscope.ts

@@ -0,0 +1,40 @@
+/**
+ * runScope (C039) — a per-process RUN SCOPE so parallel git worktrees / CI shards / agents can run the SAME BDD suite
+ * without clashing. The only things that clash are SHARED mutable state with a FIXED name; this makes both unique:
+ *
+ *  - `d1Path` is a unique file in the OS temp dir (NOT in the repo), so git/worktrees/.wrangler never see or contend
+ *    on it — each run opens its own local sqlite.
+ *  - `scopeId`/`email` are unique, so even against a SHARED backend (prod-as-test-users) the hatch's test-user scoping
+ *    means a run only ever seeds/cleans ITS OWN rows.
+ *
+ * `runId = <pid>_<uuid8>` is globally unique across processes and worktrees. Pair it with a hatch `scope: { value:
+ * scopeId }` (state hatch) and the `email` (auth hatch) for a fully isolated, parallel-safe run.
+ */
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export interface RunScope {
+  runId: string;
+  /** the test-user id — the state hatch forces every seeded row's owner to this; cleanup deletes only these rows. */
+  scopeId: string;
+  email: string;
+  /** an isolated local sqlite path in the OS temp dir (outside any worktree). */
+  d1Path: string;
+}
+
+export interface RunScopeOptions {
+  /** filename prefix for the temp DB (default "suluk-bdd"). */
+  prefix?: string;
+  /** email domain for the synthetic test user (default "example.test"). */
+  emailDomain?: string;
+}
+
+export function runScope(opts: RunScopeOptions = {}): RunScope {
+  const runId = `${process.pid}_${crypto.randomUUID().slice(0, 8)}`;
+  return {
+    runId,
+    scopeId: `testuser_${runId}`,
+    email: `bdd+${runId}@${opts.emailDomain ?? "example.test"}`,
+    d1Path: join(tmpdir(), `${opts.prefix ?? "suluk-bdd"}-${runId}.sqlite`),
+  };
+}

package/src/index.ts

@@ -22,6 +22,25 @@ export {
 
 export { parseFeature, type Feature, type Scenario, type FeatureStep } from "./gherkin";
 
+export {
+  buildScenarioOutlines,
+  renderScenarioOutlines,
+  type ScenarioOutline,
+  type OutlineColumn,
+  type OutlineRenderOptions,
+} from "./outline";
+
+export {
+  extractPublicRows,
+  buildExampleObject,
+  promoteExampleIntoZod,
+  promoteFeatureExamples,
+  type PublicExampleRow,
+  type PromoteResult,
+  type PromoteTarget,
+  type PromoteFeatureResult,
+} from "./promote";
+
 export {
   bindFeatures,
   detectUndefined,
@@ -38,3 +57,55 @@ export {
 } from "./bind";
 
 export { emitRunnableSuite, type EmitOptions } from "./emit";
+
+export {
+  compileDemos,
+  renderPostman,
+  renderBruno,
+  type DemoScenario,
+  type DemoRequest,
+  type DemoValue,
+  type DemoCapture,
+  type CompileDemoOptions,
+  type RenderOptions,
+} from "./demos";
+
+export {
+  buildDemoFiles,
+  planPromotions,
+  parseTargetSpec,
+  miniDiff,
+  buildAudit,
+  type DemoFormat,
+  type BuildDemoFilesOptions,
+  type DemoFilesResult,
+  type PromoteTargetSpec,
+  type PromotionPlan,
+  type PromotionRow,
+  type PromotionFileResult,
+  type AuditResult,
+  type DimensionAudit,
+} from "./cli";
+
+export { coverageGrade, type CoverageGrade } from "./coverage";
+
+export {
+  resolveExample,
+  synthesize,
+  fieldOrigin,
+  describeInputs,
+  asSourceRef,
+  resolveSourced,
+  ORIGIN_KEYWORD,
+  FROM_KEYWORD,
+  type JsonSchema,
+  type ExampleTier,
+  type ExampleSources,
+  type ResolvedExample,
+  type FieldOrigin,
+  type SourceRef,
+  type FieldSource,
+  type FieldDescriptor,
+  type SynthDirection,
+  type SynthOptions,
+} from "./examples";

package/src/outline.ts

@@ -0,0 +1,102 @@
+/**
+ * Scenario Outline generator (C040, P1). Per operation, project a Gherkin `Scenario Outline:` whose `Examples:` columns
+ * are the request's CLIENT-FACING input fields (origin `input` or `sourced`; `computed`/server-set fields are dropped —
+ * a client never sends them), and whose first seed row comes from the C041-origin-aware resolver:
+ *   • an `input` cell  → a deterministic synthesized value the tester edits;
+ *   • a `sourced` cell → the WIREABLE TOKEN `<op.select>` (e.g. `<createSubscription.id>`), not a value — so the tester
+ *     sees it is wired from a prior step, and the runnable emitter resolves it via `resolveSourced` (the follow-on).
+ *
+ * The tester EXPANDS the table (adds rows / edits cells); the binder + emitter then run each row. This is an authoring
+ * surface, so it lives on the VALUE side (it imports the synth) — never read by the matcher.
+ */
+import type { OpenAPIv4Document } from "@suluk/core";
+import { describeInputs, resolveExample, type FieldOrigin, type JsonSchema } from "@suluk/examples";
+import { generateVocabulary, opHandle } from "./vocabulary";
+
+export interface OutlineColumn {
+  name: string;
+  origin: FieldOrigin;
+  /** the seed cell for the first Examples row: a synthesized value (`input`) or a `<op.select>` wiring token (`sourced`). */
+  seed: string;
+}
+
+export interface ScenarioOutline {
+  /** the operation's v4 by-name handle. */
+  op: string;
+  method: string;
+  uri: string;
+  /** the `When` step text (placeholders reference the Examples columns). */
+  whenPhrase: string;
+  /** client-facing input columns (computed fields dropped). Empty ⇒ a plain Scenario, no Examples table. */
+  columns: OutlineColumn[];
+}
+
+interface RawReq {
+  method: string;
+  contentSchema?: unknown;
+  parameterSchema?: { body?: unknown };
+}
+
+/** Escape a synthesized value for a Gherkin table cell. */
+function cell(v: unknown): string {
+  const s = typeof v === "string" ? v : typeof v === "number" || typeof v === "boolean" ? String(v) : JSON.stringify(v ?? null);
+  return s.replace(/\\/g, "\\\\").replace(/\|/g, "\\|").replace(/\r?\n/g, " ");
+}
+
+/** Build the structured outlines for every operation that has a client-facing request body. */
+export function buildScenarioOutlines(doc: OpenAPIv4Document): ScenarioOutline[] {
+  // the When uses the contract's OWN generated phrase (so the outline BINDS); the Examples columns carry the request
+  // body — a Suluk convention: for a Scenario Outline, an Examples column = a request field of the bound When op.
+  const whenByHandle = new Map(generateVocabulary(doc).steps.filter((s) => s.kind === "when").map((s) => [s.handle, s.phrase.replace(/^When\s+/i, "")]));
+  const outlines: ScenarioOutline[] = [];
+  for (const [uri, piRaw] of Object.entries(doc.paths ?? {})) {
+    const pi = piRaw as { requests?: Record<string, RawReq> };
+    for (const [name, req] of Object.entries(pi.requests ?? {})) {
+      const body = (req.contentSchema ?? req.parameterSchema?.body) as JsonSchema | undefined;
+      const props = (body?.properties ?? {}) as Record<string, JsonSchema>;
+      const columns: OutlineColumn[] = [];
+      for (const d of describeInputs(body)) {
+        if (d.origin === "computed") continue; // a client never sends a server-computed field
+        const seed =
+          d.origin === "sourced"
+            ? `<${d.source ? `${d.source.op}.${d.source.select ?? "id"}` : d.name}>` // wired, not a value
+            : cell(resolveExample(props[d.name], {}, d.name, { direction: "request" }).value);
+        columns.push({ name: d.name, origin: d.origin, seed });
+      }
+      const whenPhrase = whenByHandle.get(opHandle(name, uri)) ?? `I ${name}`;
+      outlines.push({ op: name, method: req.method.toLowerCase(), uri, whenPhrase, columns });
+    }
+  }
+  return outlines;
+}
+
+/** Render a left-aligned, padded Gherkin table (6-space indent, matching the step indent + 2). */
+function renderTable(headers: string[], rows: string[][]): string {
+  const widths = headers.map((h, i) => Math.max(h.length, ...rows.map((r) => (r[i] ?? "").length)));
+  const line = (cells: string[]) => "      | " + cells.map((c, i) => (c ?? "").padEnd(widths[i])).join(" | ") + " |";
+  return [line(headers), ...rows.map(line)].join("\n");
+}
+
+export interface OutlineRenderOptions {
+  /** only render these operations (by name); default all. */
+  only?: string[];
+  feature?: string;
+}
+
+/**
+ * Render the generated outlines as a `.feature` SIDECAR a tester expands. A column-bearing op becomes a `Scenario
+ * Outline:` + a one-row `Examples:` table; a body-less op becomes a plain `Scenario:`.
+ */
+export function renderScenarioOutlines(doc: OpenAPIv4Document, opts: OutlineRenderOptions = {}): string {
+  const title = opts.feature ?? `${doc.info?.title ?? "API"} — generated scenario outlines (expand the Examples rows)`;
+  const want = opts.only ? new Set(opts.only) : null;
+  const blocks = buildScenarioOutlines(doc)
+    .filter((o) => !want || want.has(o.op))
+    .map((o) => {
+      const head = `  Scenario${o.columns.length ? " Outline" : ""}: ${o.op}\n    When ${o.whenPhrase}\n    Then it succeeds`;
+      if (!o.columns.length) return head;
+      const table = renderTable(o.columns.map((c) => c.name), [o.columns.map((c) => c.seed)]);
+      return `${head}\n\n    Examples:\n${table}`;
+    });
+  return `Feature: ${title}\n\n${blocks.join("\n\n")}\n`;
+}