@auto-engineer/narrative 0.11.12 → 0.11.14

package/src/{model-to-flow.specs.ts → model-to-narrative.specs.ts}

@@ -501,7 +501,9 @@ narrative('Test Flow with IDs', 'FLOW-123', () => {
         should('allow filtering');
       });
     })
-    .server(() => {});
+    .server(() => {
+      specs('Product data specs', () => {});
+    });
 });
 `);
   });
@@ -1819,4 +1821,610 @@ narrative('Response Analytics', () => {
 });
 `);
   });
+
+  it('should omit .when({}) when given has multiple items and when is empty', async () => {
+    const modelWithEmptyWhen: Model = {
+      variant: 'specs',
+      narratives: [
+        {
+          name: 'Todo List Summary',
+          id: 'TODO-001',
+          slices: [
+            {
+              name: 'views completion summary',
+              id: 'SUMMARY-001',
+              type: 'query',
+              client: {
+                description: 'Summary view client',
+              },
+              server: {
+                description: 'Summary calculation server',
+                specs: {
+                  name: 'Summary Statistics',
+                  rules: [
+                    {
+                      id: 'RULE-SUMMARY',
+                      description: 'summary shows overall todo list statistics',
+                      examples: [
+                        {
+                          description: 'calculates summary from multiple todos',
+                          given: [
+                            {
+                              eventRef: 'TodoAdded',
+                              exampleData: {
+                                todoId: 'todo-001',
+                                description: 'Buy groceries',
+                                status: 'pending',
+                                addedAt: new Date('2030-01-01T09:00:00.000Z'),
+                              },
+                            },
+                            {
+                              eventRef: 'TodoAdded',
+                              exampleData: {
+                                todoId: 'todo-002',
+                                description: 'Write report',
+                                status: 'pending',
+                                addedAt: new Date('2030-01-01T09:10:00.000Z'),
+                              },
+                            },
+                            {
+                              eventRef: 'TodoMarkedInProgress',
+                              exampleData: {
+                                todoId: 'todo-001',
+                                markedAt: new Date('2030-01-01T10:00:00.000Z'),
+                              },
+                            },
+                            {
+                              eventRef: 'TodoMarkedComplete',
+                              exampleData: {
+                                todoId: 'todo-002',
+                                completedAt: new Date('2030-01-01T11:00:00.000Z'),
+                              },
+                            },
+                          ],
+                          when: {
+                            eventRef: '',
+                            exampleData: {},
+                          },
+                          then: [
+                            {
+                              stateRef: 'TodoListSummary',
+                              exampleData: {
+                                summaryId: 'main-summary',
+                                totalTodos: 2,
+                                pendingCount: 0,
+                                inProgressCount: 1,
+                                completedCount: 1,
+                                completionPercentage: 50,
+                              },
+                            },
+                          ],
+                        },
+                      ],
+                    },
+                  ],
+                },
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        {
+          type: 'event',
+          name: 'TodoAdded',
+          fields: [
+            { name: 'todoId', type: 'string', required: true },
+            { name: 'description', type: 'string', required: true },
+            { name: 'status', type: 'string', required: true },
+            { name: 'addedAt', type: 'Date', required: true },
+          ],
+          source: 'internal',
+          metadata: { version: 1 },
+        },
+        {
+          type: 'event',
+          name: 'TodoMarkedInProgress',
+          fields: [
+            { name: 'todoId', type: 'string', required: true },
+            { name: 'markedAt', type: 'Date', required: true },
+          ],
+          source: 'internal',
+          metadata: { version: 1 },
+        },
+        {
+          type: 'event',
+          name: 'TodoMarkedComplete',
+          fields: [
+            { name: 'todoId', type: 'string', required: true },
+            { name: 'completedAt', type: 'Date', required: true },
+          ],
+          source: 'internal',
+          metadata: { version: 1 },
+        },
+        {
+          type: 'state',
+          name: 'TodoListSummary',
+          fields: [
+            { name: 'summaryId', type: 'string', required: true },
+            { name: 'totalTodos', type: 'number', required: true },
+            { name: 'pendingCount', type: 'number', required: true },
+            { name: 'inProgressCount', type: 'number', required: true },
+            { name: 'completedCount', type: 'number', required: true },
+            { name: 'completionPercentage', type: 'number', required: true },
+          ],
+          metadata: { version: 1 },
+        },
+      ],
+      integrations: [],
+    };
+
+    const code = await modelToNarrative(modelWithEmptyWhen);
+
+    expect(code).toEqual(`import { example, narrative, query, rule, specs } from '@auto-engineer/narrative';
+import type { Event, State } from '@auto-engineer/narrative';
+type TodoAdded = Event<
+  'TodoAdded',
+  {
+    todoId: string;
+    description: string;
+    status: string;
+    addedAt: Date;
+  }
+>;
+type TodoMarkedInProgress = Event<
+  'TodoMarkedInProgress',
+  {
+    todoId: string;
+    markedAt: Date;
+  }
+>;
+type TodoMarkedComplete = Event<
+  'TodoMarkedComplete',
+  {
+    todoId: string;
+    completedAt: Date;
+  }
+>;
+type TodoListSummary = State<
+  'TodoListSummary',
+  {
+    summaryId: string;
+    totalTodos: number;
+    pendingCount: number;
+    inProgressCount: number;
+    completedCount: number;
+    completionPercentage: number;
+  }
+>;
+narrative('Todo List Summary', 'TODO-001', () => {
+  query('views completion summary', 'SUMMARY-001').server(() => {
+    specs('Summary Statistics', () => {
+      rule('summary shows overall todo list statistics', 'RULE-SUMMARY', () => {
+        example('calculates summary from multiple todos')
+          .given<TodoAdded>({
+            todoId: 'todo-001',
+            description: 'Buy groceries',
+            status: 'pending',
+            addedAt: new Date('2030-01-01T09:00:00.000Z'),
+          })
+          .and<TodoAdded>({
+            todoId: 'todo-002',
+            description: 'Write report',
+            status: 'pending',
+            addedAt: new Date('2030-01-01T09:10:00.000Z'),
+          })
+          .and<TodoMarkedInProgress>({ todoId: 'todo-001', markedAt: new Date('2030-01-01T10:00:00.000Z') })
+          .and<TodoMarkedComplete>({ todoId: 'todo-002', completedAt: new Date('2030-01-01T11:00:00.000Z') })
+          .then<TodoListSummary>({
+            summaryId: 'main-summary',
+            totalTodos: 2,
+            pendingCount: 0,
+            inProgressCount: 1,
+            completedCount: 1,
+            completionPercentage: 50,
+          });
+      });
+    });
+  });
+});
+`);
+
+    expect(code).not.toContain('.when({})');
+    expect(code).not.toContain('.when<');
+  });
+
+  describe('projection DSL generation', () => {
+    it('should generate fromSingletonProjection for singleton projections', async () => {
+      const modelWithSingletonProjection: Model = {
+        variant: 'specs',
+        narratives: [
+          {
+            name: 'Todo Summary Flow',
+            id: 'TODO-SUMMARY',
+            slices: [
+              {
+                name: 'views todo summary',
+                id: 'SUMMARY-SLICE',
+                type: 'query',
+                client: {
+                  description: 'Summary client',
+                },
+                server: {
+                  description: 'Summary server',
+                  data: [
+                    {
+                      target: {
+                        type: 'State',
+                        name: 'TodoListSummary',
+                      },
+                      origin: {
+                        type: 'projection',
+                        name: 'TodoSummary',
+                        singleton: true,
+                      },
+                    },
+                  ],
+                  specs: {
+                    name: 'Summary Rules',
+                    rules: [],
+                  },
+                },
+              },
+            ],
+          },
+        ],
+        messages: [
+          {
+            type: 'state',
+            name: 'TodoListSummary',
+            fields: [
+              { name: 'summaryId', type: 'string', required: true },
+              { name: 'totalTodos', type: 'number', required: true },
+            ],
+            metadata: { version: 1 },
+          },
+        ],
+        integrations: [],
+      };
+
+      const code = await modelToNarrative(modelWithSingletonProjection);
+
+      expect(code).toEqual(`import { data, narrative, query, source, specs } from '@auto-engineer/narrative';
+import type { State } from '@auto-engineer/narrative';
+type TodoListSummary = State<
+  'TodoListSummary',
+  {
+    summaryId: string;
+    totalTodos: number;
+  }
+>;
+narrative('Todo Summary Flow', 'TODO-SUMMARY', () => {
+  query('views todo summary', 'SUMMARY-SLICE').server(() => {
+    data([source().state('TodoListSummary').fromSingletonProjection('TodoSummary')]);
+    specs('Summary Rules', () => {});
+  });
+});
+`);
+    });
+
+    it('should generate fromProjection with single idField for regular projections', async () => {
+      const modelWithRegularProjection: Model = {
+        variant: 'specs',
+        narratives: [
+          {
+            name: 'Todo Flow',
+            id: 'TODO-FLOW',
+            slices: [
+              {
+                name: 'views todo',
+                id: 'TODO-SLICE',
+                type: 'query',
+                client: {
+                  description: 'Todo client',
+                },
+                server: {
+                  description: 'Todo server',
+                  data: [
+                    {
+                      target: {
+                        type: 'State',
+                        name: 'TodoState',
+                      },
+                      origin: {
+                        type: 'projection',
+                        name: 'Todos',
+                        idField: 'todoId',
+                      },
+                    },
+                  ],
+                  specs: {
+                    name: 'Todo Rules',
+                    rules: [],
+                  },
+                },
+              },
+            ],
+          },
+        ],
+        messages: [
+          {
+            type: 'state',
+            name: 'TodoState',
+            fields: [
+              { name: 'todoId', type: 'string', required: true },
+              { name: 'description', type: 'string', required: true },
+            ],
+            metadata: { version: 1 },
+          },
+        ],
+        integrations: [],
+      };
+
+      const code = await modelToNarrative(modelWithRegularProjection);
+
+      expect(code).toEqual(`import { data, narrative, query, source, specs } from '@auto-engineer/narrative';
+import type { State } from '@auto-engineer/narrative';
+type TodoState = State<
+  'TodoState',
+  {
+    todoId: string;
+    description: string;
+  }
+>;
+narrative('Todo Flow', 'TODO-FLOW', () => {
+  query('views todo', 'TODO-SLICE').server(() => {
+    data([source().state('TodoState').fromProjection('Todos', 'todoId')]);
+    specs('Todo Rules', () => {});
+  });
+});
+`);
+    });
+
+    it('should generate fromCompositeProjection with array idField for composite key projections', async () => {
+      const modelWithCompositeProjection: Model = {
+        variant: 'specs',
+        narratives: [
+          {
+            name: 'User Project Flow',
+            id: 'USER-PROJECT-FLOW',
+            slices: [
+              {
+                name: 'views user project',
+                id: 'USER-PROJECT-SLICE',
+                type: 'query',
+                client: {
+                  description: 'User project client',
+                },
+                server: {
+                  description: 'User project server',
+                  data: [
+                    {
+                      target: {
+                        type: 'State',
+                        name: 'UserProjectState',
+                      },
+                      origin: {
+                        type: 'projection',
+                        name: 'UserProjects',
+                        idField: ['userId', 'projectId'],
+                      },
+                    },
+                  ],
+                  specs: {
+                    name: 'User Project Rules',
+                    rules: [],
+                  },
+                },
+              },
+            ],
+          },
+        ],
+        messages: [
+          {
+            type: 'state',
+            name: 'UserProjectState',
+            fields: [
+              { name: 'userId', type: 'string', required: true },
+              { name: 'projectId', type: 'string', required: true },
+              { name: 'role', type: 'string', required: true },
+            ],
+            metadata: { version: 1 },
+          },
+        ],
+        integrations: [],
+      };
+
+      const code = await modelToNarrative(modelWithCompositeProjection);
+
+      expect(code).toEqual(`import { data, narrative, query, source, specs } from '@auto-engineer/narrative';
+import type { State } from '@auto-engineer/narrative';
+type UserProjectState = State<
+  'UserProjectState',
+  {
+    userId: string;
+    projectId: string;
+    role: string;
+  }
+>;
+narrative('User Project Flow', 'USER-PROJECT-FLOW', () => {
+  query('views user project', 'USER-PROJECT-SLICE').server(() => {
+    data([source().state('UserProjectState').fromCompositeProjection('UserProjects', ['userId', 'projectId'])]);
+    specs('User Project Rules', () => {});
+  });
+});
+`);
+    });
+
+    it('should generate all three projection types in a single narrative', async () => {
+      const modelWithAllProjectionTypes: Model = {
+        variant: 'specs',
+        narratives: [
+          {
+            name: 'All Projection Types',
+            id: 'ALL-PROJ',
+            slices: [
+              {
+                name: 'views summary',
+                id: 'SUMMARY-SLICE',
+                type: 'query',
+                client: {
+                  description: 'Summary client',
+                },
+                server: {
+                  description: 'Summary server',
+                  data: [
+                    {
+                      target: {
+                        type: 'State',
+                        name: 'TodoListSummary',
+                      },
+                      origin: {
+                        type: 'projection',
+                        name: 'TodoSummary',
+                        singleton: true,
+                      },
+                    },
+                  ],
+                  specs: {
+                    name: 'Summary Rules',
+                    rules: [],
+                  },
+                },
+              },
+              {
+                name: 'views todo',
+                id: 'TODO-SLICE',
+                type: 'query',
+                client: {
+                  description: 'Todo client',
+                },
+                server: {
+                  description: 'Todo server',
+                  data: [
+                    {
+                      target: {
+                        type: 'State',
+                        name: 'TodoState',
+                      },
+                      origin: {
+                        type: 'projection',
+                        name: 'Todos',
+                        idField: 'todoId',
+                      },
+                    },
+                  ],
+                  specs: {
+                    name: 'Todo Rules',
+                    rules: [],
+                  },
+                },
+              },
+              {
+                name: 'views user project todos',
+                id: 'USER-PROJECT-SLICE',
+                type: 'query',
+                client: {
+                  description: 'User project client',
+                },
+                server: {
+                  description: 'User project server',
+                  data: [
+                    {
+                      target: {
+                        type: 'State',
+                        name: 'UserProjectTodos',
+                      },
+                      origin: {
+                        type: 'projection',
+                        name: 'UserProjectTodos',
+                        idField: ['userId', 'projectId'],
+                      },
+                    },
+                  ],
+                  specs: {
+                    name: 'User Project Rules',
+                    rules: [],
+                  },
+                },
+              },
+            ],
+          },
+        ],
+        messages: [
+          {
+            type: 'state',
+            name: 'TodoListSummary',
+            fields: [
+              { name: 'summaryId', type: 'string', required: true },
+              { name: 'totalTodos', type: 'number', required: true },
+            ],
+            metadata: { version: 1 },
+          },
+          {
+            type: 'state',
+            name: 'TodoState',
+            fields: [
+              { name: 'todoId', type: 'string', required: true },
+              { name: 'description', type: 'string', required: true },
+            ],
+            metadata: { version: 1 },
+          },
+          {
+            type: 'state',
+            name: 'UserProjectTodos',
+            fields: [
+              { name: 'userId', type: 'string', required: true },
+              { name: 'projectId', type: 'string', required: true },
+              { name: 'todos', type: 'Array<string>', required: true },
+            ],
+            metadata: { version: 1 },
+          },
+        ],
+        integrations: [],
+      };
+
+      const code = await modelToNarrative(modelWithAllProjectionTypes);
+
+      expect(code).toEqual(`import { data, narrative, query, source, specs } from '@auto-engineer/narrative';
+import type { State } from '@auto-engineer/narrative';
+type TodoListSummary = State<
+  'TodoListSummary',
+  {
+    summaryId: string;
+    totalTodos: number;
+  }
+>;
+type TodoState = State<
+  'TodoState',
+  {
+    todoId: string;
+    description: string;
+  }
+>;
+type UserProjectTodos = State<
+  'UserProjectTodos',
+  {
+    userId: string;
+    projectId: string;
+    todos: string[];
+  }
+>;
+narrative('All Projection Types', 'ALL-PROJ', () => {
+  query('views summary', 'SUMMARY-SLICE').server(() => {
+    data([source().state('TodoListSummary').fromSingletonProjection('TodoSummary')]);
+    specs('Summary Rules', () => {});
+  });
+  query('views todo', 'TODO-SLICE').server(() => {
+    data([source().state('TodoState').fromProjection('Todos', 'todoId')]);
+    specs('Todo Rules', () => {});
+  });
+  query('views user project todos', 'USER-PROJECT-SLICE').server(() => {
+    data([source().state('UserProjectTodos').fromCompositeProjection('UserProjectTodos', ['userId', 'projectId'])]);
+    specs('User Project Rules', () => {});
+  });
+});
+`);
+    });
+  });
 });

package/src/narrative-context.ts

@@ -321,7 +321,6 @@ export function recordExample(description: string): void {
     const rule = objectRules[context.currentRuleIndex];
     rule.examples.push({
       description,
-      when: { commandRef: '', exampleData: {} }, // Default, will be updated
       then: [],
     });
     context.currentExampleIndex = rule.examples.length - 1;

package/src/narrative.ts

@@ -93,7 +93,7 @@ export function rule(description: string, idOrFn: string | (() => void), fn?: ()
   callback();
 }
 
-export const example = (description: string) => {
+export const example = (description: string): TypedExampleBuilder => {
   recordExample(description);
   return createExampleBuilder();
 };
@@ -122,6 +122,7 @@ interface TypedExampleBuilder {
 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>;
 }
 
 interface TypedWhenBuilder<W> {
@@ -180,6 +181,20 @@ function createGivenBuilder<G>(): TypedGivenBuilder<G> {
         },
       };
     },
+    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>;
+        },
+      };
+    },
   };
 }
 

package/src/samples/mixed-given-types.narrative.ts

@@ -58,7 +58,6 @@ flow('Mixed Given Types', 'FLOW-MGT', () => {
               itemId: 'item-002',
               addedAt: new Date('2024-01-01T10:02:00Z'),
             })
-            .when({}) // empty when clause
             .then<SystemStatus>({
               systemId: 'system-001',
               itemCount: 2,

package/src/samples/questionnaires.narrative.ts

@@ -135,7 +135,6 @@ flow('Questionnaires', 'AUTO-Q9m2Kp4Lx', () => {
               link: 'https://app.example.com/q/q-001?participant=participant-abc',
               sentAt: new Date('2030-01-01T09:00:00Z'),
             })
-            .when({})
             .then<QuestionnaireProgress>({
               questionnaireId: 'q-001',
               participantId: 'participant-abc',
@@ -259,7 +258,6 @@ flow('Questionnaires', 'AUTO-Q9m2Kp4Lx', () => {
               answer: 'No',
               savedAt: new Date('2030-01-01T09:05:00Z'),
             })
-            .when({}) // FIX ME
             .then<QuestionnaireProgress>({
               questionnaireId: 'q-001',
               participantId: 'participant-abc',