@auto-engineer/narrative 0.13.0 → 0.13.1

package/src/index.ts

@@ -44,7 +44,8 @@ export type { FieldSelector } from './data-narrative-builders';
 
 // Narrative language functions
 export { narrative, narrative as flow } from './narrative';
-export { client, server, specs, describe, it, should, request, data, rule, example } from './narrative';
+export { client, server, specs, describe, it, should, request, data, rule, example, thenError } from './narrative';
+export type { ExampleBuilder, GivenBuilder, WhenBuilder, ThenBuilder } from './narrative';
 export type { SliceTypeValueInterface } from './narrative';
 export { SliceType } from './narrative';
 
@@ -55,7 +56,7 @@ export { modelToNarrative } from './transformers/model-to-narrative';
 export type { ExportSchemaEvents } from './commands/export-schema';
 
 // Testing helpers
-export { createNarrativeSpec, given, when } from './testing';
+export { createNarrativeSpec, given as testGiven, when as testWhen } from './testing';
 
 // Schema definitions for progressive narrative creation
 export {
@@ -76,21 +77,19 @@ export {
   SliceSchema,
   NarrativeSchema,
   modelSchema,
-  EventExampleSchema,
-  CommandExampleSchema,
   ExampleSchema,
   RuleSchema,
   SpecSchema,
+  StepSchema,
+  StepErrorSchema,
+  StepWithDocStringSchema,
+  StepWithErrorSchema,
 } from './schema';
 
 import {
-  CommandExampleSchema,
-  ErrorExampleSchema,
-  EventExampleSchema,
   NarrativeSchema,
   SliceSchema,
   modelSchema,
-  StateExampleSchema,
   QuerySliceSchema,
   ReactSliceSchema,
   ExperienceSliceSchema,
@@ -100,14 +99,11 @@ import {
   ExampleSchema,
   RuleSchema,
   SpecSchema,
+  StepSchema,
 } from './schema';
 export type Model = z.infer<typeof modelSchema>;
 export type Narrative = z.infer<typeof NarrativeSchema>;
-export type CommandExample = z.infer<typeof CommandExampleSchema>;
-export type EventExample = z.infer<typeof EventExampleSchema>;
 export type Slice = z.infer<typeof SliceSchema>;
-export type StateExample = z.infer<typeof StateExampleSchema>;
-export type ErrorExample = z.infer<typeof ErrorExampleSchema>;
 export type QuerySlice = z.infer<typeof QuerySliceSchema>;
 export type ReactSlice = z.infer<typeof ReactSliceSchema>;
 export type CommandSlice = z.infer<typeof CommandSliceSchema>;
@@ -117,6 +113,7 @@ export type Example = z.infer<typeof ExampleSchema>;
 export type MessageField = z.infer<typeof MessageFieldSchema>;
 export type Rule = z.infer<typeof RuleSchema>;
 export type Spec = z.infer<typeof SpecSchema>;
+export type Step = z.infer<typeof StepSchema>;
 export type { ClientSpecNode } from './schema';
 
 // ID assignment utilities

package/src/loader/graph.ts

@@ -8,6 +8,7 @@ import {
   parseIntegrationImports,
   parseGivenTypeArguments,
   parseWhenTypeArguments,
+  parseThenTypeArguments,
   patchImportMeta,
   transpileToCjs,
   TypeInfo,
@@ -312,8 +313,12 @@ export async function buildGraph(
   function extractTypeInfoFromProgram(
     program: import('typescript').Program,
     checker: import('typescript').TypeChecker,
-  ): Map<string, import('./ts-utils').GivenTypeInfo[]> {
+  ): {
+    whenTypes: Map<string, import('./ts-utils').GivenTypeInfo[]>;
+    thenTypes: Map<string, import('./ts-utils').GivenTypeInfo[]>;
+  } {
     const whenTypesByFile: Map<string, import('./ts-utils').GivenTypeInfo[]> = new Map();
+    const thenTypesByFile: Map<string, import('./ts-utils').GivenTypeInfo[]> = new Map();
 
     for (const sourceFile of program.getSourceFiles()) {
       const posixPath = toPosix(sourceFile.fileName);
@@ -322,24 +327,35 @@ export async function buildGraph(
       const fileTypeMap = typesByFile.get(posixPath) || new Map();
       const extractedGivenTypes = parseGivenTypeArguments(ts, checker, sourceFile, fileTypeMap, typesByFile);
       const extractedWhenTypes = parseWhenTypeArguments(ts, checker, sourceFile, fileTypeMap, typesByFile);
+      const extractedThenTypes = parseThenTypeArguments(ts, checker, sourceFile, fileTypeMap, typesByFile);
 
       if (extractedGivenTypes.length > 0) {
         givenTypesByFile.set(posixPath, extractedGivenTypes);
-        debug('[given-types] extracted %d .given<T>() calls from %s', extractedGivenTypes.length, posixPath);
+        debug('[given-types] extracted %d given<T>() calls from %s', extractedGivenTypes.length, posixPath);
       }
 
       if (extractedWhenTypes.length > 0) {
         whenTypesByFile.set(posixPath, extractedWhenTypes);
         debug(
-          '[when-types] extracted %d .when<T>() calls from %s: %o',
+          '[when-types] extracted %d when<T>() calls from %s: %o',
           extractedWhenTypes.length,
           posixPath,
           extractedWhenTypes.map((t) => ({ typeName: t.typeName, classification: t.classification })),
         );
       }
+
+      if (extractedThenTypes.length > 0) {
+        thenTypesByFile.set(posixPath, extractedThenTypes);
+        debug(
+          '[then-types] extracted %d then<T>() calls from %s: %o',
+          extractedThenTypes.length,
+          posixPath,
+          extractedThenTypes.map((t) => ({ typeName: t.typeName, classification: t.classification })),
+        );
+      }
     }
 
-    return whenTypesByFile;
+    return { whenTypes: whenTypesByFile, thenTypes: thenTypesByFile };
   }
 
   for (const entry of entryFiles) {
@@ -352,9 +368,10 @@ export async function buildGraph(
   const program = ts.createProgram([...sourceFiles.keys()], compilerOptions, host);
   const checker = program.getTypeChecker();
 
-  const whenTypesByFile = extractTypeInfoFromProgram(program, checker);
+  const { whenTypes, thenTypes } = extractTypeInfoFromProgram(program, checker);
 
-  givenTypesByFile.set('__whenTypes', whenTypesByFile as unknown as import('./ts-utils').GivenTypeInfo[]);
+  givenTypesByFile.set('__whenTypes', whenTypes as unknown as import('./ts-utils').GivenTypeInfo[]);
+  givenTypesByFile.set('__thenTypes', thenTypes as unknown as import('./ts-utils').GivenTypeInfo[]);
 
   const result: BuildGraphResult = {
     graph,

package/src/loader/ts-utils.ts

@@ -660,14 +660,13 @@ export function parseWhenTypeArguments(
   const whenTypes: GivenTypeInfo[] = [];
 
   const visit = (node: import('typescript').Node): void => {
-    if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
-      const method = node.expression.name.getText();
-      if (method === 'when') {
+    if (ts.isCallExpression(node)) {
+      if (ts.isIdentifier(node.expression) && node.expression.text === 'when') {
         if (node.typeArguments && node.typeArguments.length > 0) {
           const typeArg = node.typeArguments[0];
           const typeArgText = typeArg.getText(sourceFile);
           debug(
-            '[when-types] found .when<%s> at line %d, will process as ordinal %d',
+            '[when-types] found when<%s> at line %d, will process as ordinal %d',
             typeArgText,
             sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1,
             whenTypes.length,
@@ -676,7 +675,7 @@ export function parseWhenTypeArguments(
         } else {
           const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
           debug(
-            '[when-types] found .when() without type argument at line %d, adding placeholder at ordinal %d',
+            '[when-types] found when() without type argument at line %d, adding placeholder at ordinal %d',
             line + 1,
             whenTypes.length,
           );
@@ -690,6 +689,38 @@ export function parseWhenTypeArguments(
           });
         }
       }
+      // Handle property access (fluent API): .when<T>({...})
+      else if (ts.isPropertyAccessExpression(node.expression)) {
+        const method = node.expression.name.getText();
+        if (method === 'when') {
+          if (node.typeArguments && node.typeArguments.length > 0) {
+            const typeArg = node.typeArguments[0];
+            const typeArgText = typeArg.getText(sourceFile);
+            debug(
+              '[when-types] found .when<%s> at line %d, will process as ordinal %d',
+              typeArgText,
+              sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1,
+              whenTypes.length,
+            );
+            processWhenCallExpression(ts, node, checker, sourceFile, typeMap, typesByFile, whenTypes, whenTypes.length);
+          } else {
+            const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+            debug(
+              '[when-types] found .when() without type argument at line %d, adding placeholder at ordinal %d',
+              line + 1,
+              whenTypes.length,
+            );
+            whenTypes.push({
+              fileName: sourceFile.fileName,
+              line: line + 1,
+              column: character + 1,
+              ordinal: whenTypes.length,
+              typeName: '',
+              classification: 'command',
+            });
+          }
+        }
+      }
     }
     ts.forEachChild(node, visit);
   };
@@ -699,6 +730,43 @@ export function parseWhenTypeArguments(
   return whenTypes;
 }
 
+function processStandaloneGivenCall(
+  ts: typeof import('typescript'),
+  node: import('typescript').CallExpression,
+  checker: import('typescript').TypeChecker,
+  sourceFile: import('typescript').SourceFile,
+  typeMap: Map<string, TypeInfo>,
+  typesByFile: Map<string, Map<string, TypeInfo>>,
+  givenTypes: GivenTypeInfo[],
+  processedNodes: Set<import('typescript').CallExpression>,
+): void {
+  if (node.typeArguments !== undefined && node.typeArguments.length > 0) {
+    processGivenOrAndCallExpression(ts, node, checker, sourceFile, typeMap, typesByFile, givenTypes, givenTypes.length);
+    processedNodes.add(node);
+  }
+}
+
+function processFluentGivenChain(
+  ts: typeof import('typescript'),
+  node: import('typescript').CallExpression,
+  checker: import('typescript').TypeChecker,
+  sourceFile: import('typescript').SourceFile,
+  typeMap: Map<string, TypeInfo>,
+  typesByFile: Map<string, Map<string, TypeInfo>>,
+  givenTypes: GivenTypeInfo[],
+  processedNodes: Set<import('typescript').CallExpression>,
+): void {
+  const chain = collectChainFromStart(ts, node);
+  let ordinal = givenTypes.length;
+
+  for (const chainNode of chain) {
+    if (chainNode.typeArguments !== undefined && chainNode.typeArguments.length > 0) {
+      processGivenOrAndCallExpression(ts, chainNode, checker, sourceFile, typeMap, typesByFile, givenTypes, ordinal++);
+      processedNodes.add(chainNode);
+    }
+  }
+}
+
 export function parseGivenTypeArguments(
   ts: typeof import('typescript'),
   checker: import('typescript').TypeChecker,
@@ -709,31 +777,14 @@ export function parseGivenTypeArguments(
   const givenTypes: GivenTypeInfo[] = [];
   const processedNodes = new Set<import('typescript').CallExpression>();
 
-  // First pass: find all given/and chain starts
   const visit = (node: import('typescript').Node): void => {
     if (ts.isCallExpression(node) && !processedNodes.has(node)) {
-      if (ts.isPropertyAccessExpression(node.expression)) {
+      if (ts.isIdentifier(node.expression) && node.expression.text === 'given') {
+        processStandaloneGivenCall(ts, node, checker, sourceFile, typeMap, typesByFile, givenTypes, processedNodes);
+      } else if (ts.isPropertyAccessExpression(node.expression)) {
         const method = node.expression.name.getText();
         if (method === 'given' && isChainStart(ts, node)) {
-          // Found a chain start, collect the entire chain
-          const chain = collectChainFromStart(ts, node);
-          let ordinal = givenTypes.length;
-
-          for (const chainNode of chain) {
-            if (chainNode.typeArguments !== undefined && chainNode.typeArguments.length > 0) {
-              processGivenOrAndCallExpression(
-                ts,
-                chainNode,
-                checker,
-                sourceFile,
-                typeMap,
-                typesByFile,
-                givenTypes,
-                ordinal++,
-              );
-              processedNodes.add(chainNode);
-            }
-          }
+          processFluentGivenChain(ts, node, checker, sourceFile, typeMap, typesByFile, givenTypes, processedNodes);
         }
       }
     }
@@ -744,6 +795,98 @@ export function parseGivenTypeArguments(
   return givenTypes;
 }
 
+function processThenCallWithTypeArg(
+  ts: typeof import('typescript'),
+  node: import('typescript').CallExpression,
+  checker: import('typescript').TypeChecker,
+  sourceFile: import('typescript').SourceFile,
+  typeMap: Map<string, TypeInfo>,
+  typesByFile: Map<string, Map<string, TypeInfo>>,
+  thenTypes: GivenTypeInfo[],
+  debugPrefix: string,
+): void {
+  const typeArg = node.typeArguments![0];
+  const typeArgText = typeArg.getText(sourceFile);
+  debug(
+    '[then-types] found %s<%s> at line %d, will process as ordinal %d',
+    debugPrefix,
+    typeArgText,
+    sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1,
+    thenTypes.length,
+  );
+  const genericResult = tryUnwrapGeneric(ts, typeArg, checker, typeMap, typesByFile);
+  if (genericResult !== undefined && genericResult !== null) {
+    thenTypes.push(
+      createGivenTypeInfo(sourceFile, node, thenTypes.length, genericResult.typeName, genericResult.classification),
+    );
+  }
+}
+
+function processThenCallWithoutTypeArg(
+  sourceFile: import('typescript').SourceFile,
+  node: import('typescript').CallExpression,
+  thenTypes: GivenTypeInfo[],
+  debugPrefix: string,
+): void {
+  const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
+  debug(
+    '[then-types] found %s without type argument at line %d, adding placeholder at ordinal %d',
+    debugPrefix,
+    line + 1,
+    thenTypes.length,
+  );
+  thenTypes.push({
+    fileName: sourceFile.fileName,
+    line: line + 1,
+    column: character + 1,
+    ordinal: thenTypes.length,
+    typeName: '',
+    classification: 'event',
+  });
+}
+
+function processThenCall(
+  ts: typeof import('typescript'),
+  node: import('typescript').CallExpression,
+  checker: import('typescript').TypeChecker,
+  sourceFile: import('typescript').SourceFile,
+  typeMap: Map<string, TypeInfo>,
+  typesByFile: Map<string, Map<string, TypeInfo>>,
+  thenTypes: GivenTypeInfo[],
+  debugPrefix: string,
+): void {
+  if (node.typeArguments !== undefined && node.typeArguments.length > 0) {
+    processThenCallWithTypeArg(ts, node, checker, sourceFile, typeMap, typesByFile, thenTypes, debugPrefix);
+  } else {
+    processThenCallWithoutTypeArg(sourceFile, node, thenTypes, debugPrefix);
+  }
+}
+
+export function parseThenTypeArguments(
+  ts: typeof import('typescript'),
+  checker: import('typescript').TypeChecker,
+  sourceFile: import('typescript').SourceFile,
+  typeMap: Map<string, TypeInfo>,
+  typesByFile: Map<string, Map<string, TypeInfo>>,
+): GivenTypeInfo[] {
+  const thenTypes: GivenTypeInfo[] = [];
+
+  const visit = (node: import('typescript').Node): void => {
+    if (ts.isCallExpression(node)) {
+      if (ts.isIdentifier(node.expression) && node.expression.text === 'then') {
+        processThenCall(ts, node, checker, sourceFile, typeMap, typesByFile, thenTypes, 'then');
+      } else if (ts.isPropertyAccessExpression(node.expression) && node.expression.name.getText() === 'then') {
+        processThenCall(ts, node, checker, sourceFile, typeMap, typesByFile, thenTypes, '.then');
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+
+  visit(sourceFile);
+  debug('[then-types] total then types extracted: %d', thenTypes.length);
+  return thenTypes;
+}
+
 export function transpileToCjs(ts: typeof import('typescript'), fileName: string, source: string): string {
   const out = ts.transpileModule(source, {
     compilerOptions: {