@auto-engineer/narrative 0.13.0 → 0.13.1

package/src/narrative.ts

@@ -14,11 +14,8 @@ import {
   setSliceData,
   recordRule,
   recordExample,
-  recordGivenData,
-  recordAndGivenData,
-  recordWhenData,
-  recordThenData,
-  recordAndThenData,
+  recordStep,
+  recordErrorStep,
 } from './narrative-context';
 import type { DataItem } from './types';
 import createDebug from 'debug';
@@ -26,7 +23,7 @@ import createDebug from 'debug';
 const debug = createDebug('auto:narrative:narrative');
 if ('color' in debug && typeof debug === 'object') {
   (debug as { color: string }).color = '6';
-} // cyan
+}
 
 export function narrative(name: string, fn: () => void): void;
 export function narrative(name: string, id: string, fn: () => void): void;
@@ -107,159 +104,112 @@ export function should(idOrTitle: string, title?: string): void {
   recordIt(hasId ? idOrTitle : undefined, hasId ? title : idOrTitle);
 }
 
-export function specs(description: string, fn: () => void): void;
+export function specs(feature: string, fn: () => void): void;
 export function specs(fn: () => void): void;
-export function specs(descriptionOrFn: string | (() => void), fn?: () => void): void {
-  const description = typeof descriptionOrFn === 'string' ? descriptionOrFn : '';
-  const callback = typeof descriptionOrFn === 'function' ? descriptionOrFn : fn!;
+export function specs(featureOrFn: string | (() => void), fn?: () => void): void {
+  const feature = typeof featureOrFn === 'string' ? featureOrFn : '';
+  const callback = typeof featureOrFn === 'function' ? featureOrFn : fn!;
 
-  pushSpec(description);
+  pushSpec(feature);
   callback();
 }
 
-export function rule(description: string, fn: () => void): void;
-export function rule(description: string, id: string, fn: () => void): void;
-export function rule(description: string, idOrFn: string | (() => void), fn?: () => void): void {
+export function rule(name: string, fn: () => void): void;
+export function rule(name: string, id: string, fn: () => void): void;
+export function rule(name: string, idOrFn: string | (() => void), fn?: () => void): void {
   const id = typeof idOrFn === 'string' ? idOrFn : undefined;
-  const callback = typeof idOrFn === 'function' ? idOrFn : fn;
-
-  if (!callback) {
-    throw new Error(`rule() requires a callback function. Got: ${typeof idOrFn}, ${typeof fn}`);
-  }
-
-  recordRule(description, id);
+  const callback = typeof idOrFn === 'function' ? idOrFn : fn!;
+  recordRule(name, id);
   callback();
 }
 
-export const example = (description: string): TypedExampleBuilder => {
-  recordExample(description);
-  return createExampleBuilder();
-};
-
 type ExtractData<T> = T extends { data: infer D } ? D : T;
-type ContextFor<T> = Partial<Record<keyof ExtractData<T>, string>>;
-
-function normalizeContext(context?: Partial<Record<string, string>>): Record<string, string> | undefined {
-  if (!context) return undefined;
-
-  const filtered: Record<string, string> = {};
-  for (const [key, value] of Object.entries(context)) {
-    if (value !== undefined) {
-      filtered[key] = value;
-    }
-  }
-
-  return Object.keys(filtered).length > 0 ? filtered : undefined;
-}
-
-interface TypedExampleBuilder {
-  given<T>(data: ExtractData<T> | ExtractData<T>[], context?: ContextFor<T>): TypedGivenBuilder<T>;
-  when<W>(data: ExtractData<W> | ExtractData<W>[], context?: ContextFor<W>): TypedWhenBuilder<W>;
-}
 
-interface TypedGivenBuilder<G> {
-  and<U>(data: ExtractData<U> | ExtractData<U>[], context?: ContextFor<U>): TypedGivenBuilder<G | U>;
-  when<W>(data: ExtractData<W> | ExtractData<W>[], context?: ContextFor<W>): TypedGivenWhenBuilder<G, W>;
-  then<T>(data: ExtractData<T> | ExtractData<T>[], context?: ContextFor<T>): TypedGivenThenBuilder<G, never, T>;
+export interface ThenBuilder {
+  and<T>(data: ExtractData<T>): ThenBuilder;
 }
 
-interface TypedWhenBuilder<W> {
-  then<T>(data: ExtractData<T> | ExtractData<T>[], context?: ContextFor<T>): TypedThenBuilder<W, T>;
+export interface WhenBuilder {
+  then<T>(data: ExtractData<T>): ThenBuilder;
+  and<T>(data: ExtractData<T>): WhenBuilder;
 }
 
-interface TypedGivenWhenBuilder<G, W> {
-  then<T>(data: ExtractData<T> | ExtractData<T>[], context?: ContextFor<T>): TypedGivenThenBuilder<G, W, T>;
+export interface GivenBuilder {
+  and<T>(data: ExtractData<T>): GivenBuilder;
+  when<W>(data: ExtractData<W>): WhenBuilder;
+  then<T>(data: ExtractData<T>): ThenBuilder;
 }
 
-interface TypedThenBuilder<W, T> {
-  and<A>(data: ExtractData<A> | ExtractData<A>[], context?: ContextFor<A>): TypedThenBuilder<W, T | A>;
+export interface ExampleBuilder {
+  given<T>(data: ExtractData<T>): GivenBuilder;
+  when<W>(data: ExtractData<W>): WhenBuilder;
 }
 
-interface TypedGivenThenBuilder<G, W, T> {
-  and<A>(data: ExtractData<A> | ExtractData<A>[], context?: ContextFor<A>): TypedGivenThenBuilder<G, W, T | A>;
+function createThenBuilder(): ThenBuilder {
+  return {
+    and<T>(data: ExtractData<T>): ThenBuilder {
+      recordStep('And', 'InferredType', data);
+      return createThenBuilder();
+    },
+  };
 }
 
-function createThenBuilder<W, T>(): TypedThenBuilder<W, T> {
+function createWhenBuilder(): WhenBuilder {
   return {
-    and<A>(data: ExtractData<A> | ExtractData<A>[], context?: ContextFor<A>): TypedThenBuilder<W, T | A> {
-      const andItems = Array.isArray(data) ? data : [data];
-      recordAndThenData(andItems, normalizeContext(context as Partial<Record<string, string>>));
-      return createThenBuilder<W, T | A>();
+    then<T>(data: ExtractData<T>): ThenBuilder {
+      recordStep('Then', 'InferredType', data);
+      return createThenBuilder();
+    },
+    and<T>(data: ExtractData<T>): WhenBuilder {
+      recordStep('And', 'InferredType', data);
+      return createWhenBuilder();
     },
   };
 }
 
-function createGivenBuilder<G>(): TypedGivenBuilder<G> {
+function createGivenBuilder(): GivenBuilder {
   return {
-    and<U>(data: ExtractData<U> | ExtractData<U>[], context?: ContextFor<U>): TypedGivenBuilder<G | U> {
-      const andItems = Array.isArray(data) ? data : [data];
-      recordAndGivenData(andItems, normalizeContext(context as Partial<Record<string, string>>));
-      return createGivenBuilder<G | U>();
+    and<T>(data: ExtractData<T>): GivenBuilder {
+      recordStep('And', 'InferredType', data);
+      return createGivenBuilder();
     },
-    when<W>(data: ExtractData<W> | ExtractData<W>[], context?: ContextFor<W>): TypedGivenWhenBuilder<G, W> {
-      const whenData = Array.isArray(data) ? data : [data];
-      recordWhenData(
-        whenData.length === 1 ? whenData[0] : whenData,
-        normalizeContext(context as Partial<Record<string, string>>),
-      );
-      return {
-        then<T>(data: ExtractData<T> | ExtractData<T>[], context?: ContextFor<T>): TypedGivenThenBuilder<G, W, T> {
-          const thenItems = Array.isArray(data) ? data : [data];
-          recordThenData(thenItems, normalizeContext(context as Partial<Record<string, string>>));
-          return {
-            and<A>(
-              data: ExtractData<A> | ExtractData<A>[],
-              context?: ContextFor<A>,
-            ): TypedGivenThenBuilder<G, W, T | A> {
-              const andItems = Array.isArray(data) ? data : [data];
-              recordAndThenData(andItems, normalizeContext(context as Partial<Record<string, string>>));
-              return createThenBuilder<W, T | A>() as TypedGivenThenBuilder<G, W, T | A>;
-            },
-          };
-        },
-      };
+    when<W>(data: ExtractData<W>): WhenBuilder {
+      recordStep('When', 'InferredType', data);
+      return createWhenBuilder();
     },
-    then<T>(data: ExtractData<T> | ExtractData<T>[], context?: ContextFor<T>): TypedGivenThenBuilder<G, never, T> {
-      const thenItems = Array.isArray(data) ? data : [data];
-      recordThenData(thenItems, normalizeContext(context as Partial<Record<string, string>>));
-      return {
-        and<A>(
-          data: ExtractData<A> | ExtractData<A>[],
-          context?: ContextFor<A>,
-        ): TypedGivenThenBuilder<G, never, T | A> {
-          const andItems = Array.isArray(data) ? data : [data];
-          recordAndThenData(andItems, normalizeContext(context as Partial<Record<string, string>>));
-          return createThenBuilder<never, T | A>() as TypedGivenThenBuilder<G, never, T | A>;
-        },
-      };
+    then<T>(data: ExtractData<T>): ThenBuilder {
+      recordStep('Then', 'InferredType', data);
+      return createThenBuilder();
     },
   };
 }
 
-function createExampleBuilder(): TypedExampleBuilder {
+function createExampleBuilder(): ExampleBuilder {
   return {
-    given<T>(data: ExtractData<T> | ExtractData<T>[], context?: ContextFor<T>): TypedGivenBuilder<T> {
-      const items = Array.isArray(data) ? data : [data];
-      recordGivenData(items, normalizeContext(context as Partial<Record<string, string>>));
-      return createGivenBuilder<T>();
+    given<T>(data: ExtractData<T>): GivenBuilder {
+      recordStep('Given', 'InferredType', data);
+      return createGivenBuilder();
     },
-    when<W>(data: ExtractData<W> | ExtractData<W>[], context?: ContextFor<W>): TypedWhenBuilder<W> {
-      const whenData = Array.isArray(data) ? data : [data];
-      recordWhenData(
-        whenData.length === 1 ? whenData[0] : whenData,
-        normalizeContext(context as Partial<Record<string, string>>),
-      );
-      return {
-        then<Z>(data: ExtractData<Z> | ExtractData<Z>[], context?: ContextFor<Z>): TypedThenBuilder<W, Z> {
-          const thenItems = Array.isArray(data) ? data : [data];
-          recordThenData(thenItems, normalizeContext(context as Partial<Record<string, string>>));
-          return createThenBuilder<W, Z>();
-        },
-      };
+    when<W>(data: ExtractData<W>): WhenBuilder {
+      recordStep('When', 'InferredType', data);
+      return createWhenBuilder();
     },
   };
 }
 
+export function example(name: string): ExampleBuilder;
+export function example(name: string, id: string): ExampleBuilder;
+export function example(name: string, id?: string): ExampleBuilder {
+  recordExample(name, id);
+  return createExampleBuilder();
+}
+
+type ErrorType = 'IllegalStateError' | 'ValidationError' | 'NotFoundError';
+
+export function thenError(errorType: ErrorType, message?: string): void {
+  recordErrorStep(errorType, message);
+}
+
 export const SliceType = {
   COMMAND: 'command' as const,
   QUERY: 'query' as const,

package/src/samples/test-with-ids.narrative.ts

@@ -1,4 +1,4 @@
-import { flow, specs, rule, example } from '../narrative';
+import { flow, specs, rule, example, thenError } from '../narrative';
 import { command, query, react } from '../fluent-builder';
 import { type Event, type Command, type State } from '../types';
 
@@ -27,6 +27,14 @@ type TestItemState = State<
   }
 >;
 
+type SendNotification = Event<
+  'SendNotification',
+  {
+    message: string;
+    recipientId: string;
+  }
+>;
+
 flow('Test Flow with IDs', 'FLOW-001', () => {
   command('Create test item', 'SLICE-001')
     .client(() => {})
@@ -46,17 +54,11 @@ flow('Test Flow with IDs', 'FLOW-001', () => {
         });
 
         rule('Invalid test items should be rejected', 'RULE-002', () => {
-          example('User tries to create item with empty name')
-            .when<CreateTestItem>({
-              itemId: 'test_456',
-              name: '',
-            })
-            .then([
-              {
-                errorType: 'ValidationError' as const,
-                message: 'Item name cannot be empty',
-              },
-            ]);
+          example('User tries to create item with empty name').when<CreateTestItem>({
+            itemId: 'test_456',
+            name: '',
+          });
+          thenError('ValidationError', 'Item name cannot be empty');
         });
       });
     });
@@ -84,25 +86,15 @@ flow('Test Flow with IDs', 'FLOW-001', () => {
     specs('Test event reaction specs', () => {
       rule('System should react to test item creation', 'RULE-004', () => {
         example('Notification sent when test item is created')
-          .when([
-            {
-              eventRef: 'TestItemCreated',
-              exampleData: {
-                id: 'test_789',
-                name: 'Another Test Item',
-                createdAt: new Date('2024-01-16T10:00:00Z'),
-              },
-            },
-          ])
-          .then([
-            {
-              commandRef: 'SendNotification',
-              exampleData: {
-                message: 'New test item created: Another Test Item',
-                recipientId: 'admin',
-              },
-            },
-          ]);
+          .when<TestItemCreated>({
+            id: 'test_789',
+            name: 'Another Test Item',
+            createdAt: new Date('2024-01-16T10:00:00Z'),
+          })
+          .then<SendNotification>({
+            message: 'New test item created: Another Test Item',
+            recipientId: 'admin',
+          });
       });
     });
   });

package/src/schema.ts

@@ -141,30 +141,6 @@ const StateSchema = BaseMessageSchema.extend({
 
 const MessageSchema = z.discriminatedUnion('type', [CommandSchema, EventSchema, StateSchema]);
 
-export const EventExampleSchema = z
-  .object({
-    eventRef: z.string().describe('Reference to event message by name'),
-    exampleData: z.record(z.unknown()).describe('Example data matching the event schema'),
-    context: z.record(z.string()).optional().describe('Optional field descriptions and context'),
-  })
-  .describe('Event example with reference and data');
-
-export const CommandExampleSchema = z
-  .object({
-    commandRef: z.string().describe('Reference to command message by name'),
-    exampleData: z.record(z.unknown()).describe('Example data matching the command schema'),
-    context: z.record(z.string()).optional().describe('Optional field descriptions and context'),
-  })
-  .describe('Command example with reference and data');
-
-const StateExampleSchema = z
-  .object({
-    stateRef: z.string().describe('Reference to state message by name'),
-    exampleData: z.record(z.unknown()).describe('Example data matching the state schema'),
-    context: z.record(z.string()).optional().describe('Optional field descriptions and context'),
-  })
-  .describe('State example with reference and data');
-
 const BaseSliceSchema = z
   .object({
     name: z.string(),
@@ -176,44 +152,47 @@ const BaseSliceSchema = z
   })
   .describe('Base properties shared by all slice types');
 
-const ErrorExampleSchema = z
-  .object({
-    errorType: z.enum(['IllegalStateError', 'ValidationError', 'NotFoundError']).describe('Expected error'),
-    message: z.string().optional().describe('Optional error message'),
-  })
-  .describe('Error outcome');
+const StepErrorSchema = z.object({
+  type: z.enum(['IllegalStateError', 'ValidationError', 'NotFoundError']).describe('Error type'),
+  message: z.string().optional().describe('Optional error message'),
+});
+
+const StepWithDocStringSchema = z.object({
+  keyword: z.enum(['Given', 'When', 'Then', 'And']).describe('Gherkin keyword'),
+  text: z.string().describe('The type name (e.g., AddTodo, TodoAdded)'),
+  docString: z.record(z.unknown()).optional().describe('The example data'),
+});
+
+const StepWithErrorSchema = z.object({
+  keyword: z.literal('Then').describe('Error steps use Then keyword'),
+  error: StepErrorSchema.describe('Error details'),
+});
+
+const StepSchema = z.union([StepWithDocStringSchema, StepWithErrorSchema]).describe('A Gherkin step');
 
 const ExampleSchema = z
   .object({
-    description: z.string().describe('Example description'),
-    given: z
-      .array(z.union([EventExampleSchema, StateExampleSchema]))
-      .optional()
-      .describe('Given conditions'),
-    when: z
-      .union([CommandExampleSchema, EventExampleSchema, z.array(CommandExampleSchema), z.array(EventExampleSchema)])
-      .optional()
-      .describe('When action or events occur'),
-    then: z
-      .array(z.union([EventExampleSchema, StateExampleSchema, CommandExampleSchema, ErrorExampleSchema]))
-      .describe('Then expected outcomes'),
+    id: z.string().optional().describe('Unique example identifier'),
+    name: z.string().describe('Example name'),
+    steps: z.array(StepSchema).describe('Gherkin steps for this example'),
   })
-  .describe('BDD example with given-when-then structure');
+  .describe('BDD example with Gherkin steps');
 
 const RuleSchema = z
   .object({
-    id: z.string().optional().describe('Optional rule identifier'),
-    description: z.string().describe('Rule description'),
+    id: z.string().optional().describe('Unique rule identifier'),
+    name: z.string().describe('Rule name'),
     examples: z.array(ExampleSchema).describe('Examples demonstrating the rule'),
   })
   .describe('Business rule with examples');
 
 const SpecSchema = z
   .object({
-    name: z.string().describe('Spec name/feature name'),
+    type: z.literal('gherkin').describe('Specification type'),
+    feature: z.string().describe('Feature name'),
     rules: z.array(RuleSchema).describe('Business rules for this spec'),
   })
-  .describe('Specification with business rules');
+  .describe('Gherkin specification with business rules');
 
 const ItNode = z
   .object({
@@ -252,7 +231,7 @@ const CommandSliceSchema = BaseSliceSchema.extend({
   server: z.object({
     description: z.string(),
     data: z.array(DataSinkSchema).optional().describe('Data sinks for command slices'),
-    specs: SpecSchema.describe('Server-side specifications with rules and examples'),
+    specs: z.array(SpecSchema).describe('Server-side specifications with rules and examples'),
   }),
 }).describe('Command slice handling user actions and business logic');
 
@@ -265,7 +244,7 @@ const QuerySliceSchema = BaseSliceSchema.extend({
   server: z.object({
     description: z.string(),
     data: z.array(DataSourceSchema).optional().describe('Data sources for query slices'),
-    specs: SpecSchema.describe('Server-side specifications with rules and examples'),
+    specs: z.array(SpecSchema).describe('Server-side specifications with rules and examples'),
   }),
 }).describe('Query slice for reading data and maintaining projections');
 
@@ -277,7 +256,7 @@ const ReactSliceSchema = BaseSliceSchema.extend({
       .array(z.union([DataSinkSchema, DataSourceSchema]))
       .optional()
       .describe('Data items for react slices (mix of sinks and sources)'),
-    specs: SpecSchema.describe('Server-side specifications with rules and examples'),
+    specs: z.array(SpecSchema).describe('Server-side specifications with rules and examples'),
   }),
 }).describe('React slice for automated responses to events');
 
@@ -397,9 +376,7 @@ export const modelSchema = z
 export type { ClientSpecNode };
 
 export {
-  StateExampleSchema,
   MessageFieldSchema,
-  ErrorExampleSchema,
   MessageSchema,
   CommandSchema,
   EventSchema,
@@ -416,4 +393,8 @@ export {
   SpecSchema,
   DataSinkSchema,
   DataSourceSchema,
+  StepSchema,
+  StepErrorSchema,
+  StepWithDocStringSchema,
+  StepWithErrorSchema,
 };

package/src/slice-builder.ts

@@ -48,7 +48,7 @@ export const createSliceBuilder = (config: SliceConfig = {}): SliceBuilder => ({
       type: 'command',
       name,
       client: { specs: [] },
-      server: { description: '', specs: { name: '', rules: [] }, data: undefined },
+      server: { description: '', specs: [], data: undefined },
       // Optional fields
       ...(config.eventStream != null && { stream: config.eventStream }),
       ...(config.integration && { via: [config.integration.name] }),
@@ -67,7 +67,7 @@ export const createSliceBuilder = (config: SliceConfig = {}): SliceBuilder => ({
       type: 'query',
       name,
       client: { specs: [] },
-      server: { description: '', specs: { name: '', rules: [] }, data: undefined },
+      server: { description: '', specs: [], data: undefined },
       // Optional fields
       ...(config.eventStream != null && { stream: config.eventStream }),
       ...(config.integration && { via: [config.integration.name] }),
@@ -88,7 +88,7 @@ export const createSliceBuilder = (config: SliceConfig = {}): SliceBuilder => ({
     const slice: ReactSlice = {
       type: 'react',
       name,
-      server: { specs: { name: '', rules: [] }, data: undefined },
+      server: { specs: [], data: undefined },
       // Optional fields
       ...(config.eventStream != null && { stream: config.eventStream }),
       ...(config.integration && { via: [config.integration.name] }),