@auto-engineer/narrative 1.138.0 → 1.140.0

package/src/transformers/model-to-narrative/spec-traversal.specs.ts

@@ -1,27 +1,27 @@
 import { describe, expect, it } from 'vitest';
-import type { Narrative } from '../../index';
-import { collectMessageKeysFromNarratives } from './spec-traversal';
+import type { Scene } from '../../index';
+import { collectMessageKeysFromScenes } from './spec-traversal';
 
-describe('collectMessageKeysFromNarratives', () => {
-  it('returns empty set for empty narratives array', () => {
-    const keys = collectMessageKeysFromNarratives([]);
+describe('collectMessageKeysFromScenes', () => {
+  it('returns empty set for empty scenes array', () => {
+    const keys = collectMessageKeysFromScenes([]);
 
     expect(keys.size).toBe(0);
   });
 
-  it('returns empty set for narratives with no slices', () => {
-    const narratives: Narrative[] = [{ name: 'Empty', slices: [] }];
+  it('returns empty set for scenes with no slices', () => {
+    const scenes: Scene[] = [{ name: 'Empty', moments: [] }];
 
-    const keys = collectMessageKeysFromNarratives(narratives);
+    const keys = collectMessageKeysFromScenes(scenes);
 
     expect(keys.size).toBe(0);
   });
 
   it('ignores experience slices', () => {
-    const narratives: Narrative[] = [
+    const scenes: Scene[] = [
       {
         name: 'Test',
-        slices: [
+        moments: [
           {
             name: 'Homepage',
             type: 'experience',
@@ -31,16 +31,16 @@ describe('collectMessageKeysFromNarratives', () => {
       },
     ];
 
-    const keys = collectMessageKeysFromNarratives(narratives);
+    const keys = collectMessageKeysFromScenes(scenes);
 
     expect(keys.size).toBe(0);
   });
 
   it('collects command keys from When steps', () => {
-    const narratives: Narrative[] = [
+    const scenes: Scene[] = [
       {
         name: 'Test',
-        slices: [
+        moments: [
           {
             name: 'create order',
             type: 'command',
@@ -70,16 +70,16 @@ describe('collectMessageKeysFromNarratives', () => {
       },
     ];
 
-    const keys = collectMessageKeysFromNarratives(narratives);
+    const keys = collectMessageKeysFromScenes(scenes);
 
     expect(keys.has('command:CreateOrder')).toBe(true);
   });
 
   it('collects event and state keys from Given steps', () => {
-    const narratives: Narrative[] = [
+    const scenes: Scene[] = [
       {
         name: 'Test',
-        slices: [
+        moments: [
           {
             name: 'view order',
             type: 'query',
@@ -109,17 +109,17 @@ describe('collectMessageKeysFromNarratives', () => {
       },
     ];
 
-    const keys = collectMessageKeysFromNarratives(narratives);
+    const keys = collectMessageKeysFromScenes(scenes);
 
     expect(keys.has('event:OrderCreated')).toBe(true);
     expect(keys.has('state:OrderCreated')).toBe(true);
   });
 
   it('collects event and state keys from And steps', () => {
-    const narratives: Narrative[] = [
+    const scenes: Scene[] = [
       {
         name: 'Test',
-        slices: [
+        moments: [
           {
             name: 'test',
             type: 'react',
@@ -148,17 +148,17 @@ describe('collectMessageKeysFromNarratives', () => {
       },
     ];
 
-    const keys = collectMessageKeysFromNarratives(narratives);
+    const keys = collectMessageKeysFromScenes(scenes);
 
     expect(keys.has('event:UserLoggedIn')).toBe(true);
     expect(keys.has('state:UserLoggedIn')).toBe(true);
   });
 
   it('collects event and state keys from Then steps', () => {
-    const narratives: Narrative[] = [
+    const scenes: Scene[] = [
       {
         name: 'Test',
-        slices: [
+        moments: [
           {
             name: 'test',
             type: 'command',
@@ -188,17 +188,17 @@ describe('collectMessageKeysFromNarratives', () => {
       },
     ];
 
-    const keys = collectMessageKeysFromNarratives(narratives);
+    const keys = collectMessageKeysFromScenes(scenes);
 
     expect(keys.has('event:OrderCompleted')).toBe(true);
     expect(keys.has('state:OrderCompleted')).toBe(true);
   });
 
   it('handles slices without server specs', () => {
-    const narratives: Narrative[] = [
+    const scenes: Scene[] = [
       {
         name: 'Test',
-        slices: [
+        moments: [
           {
             name: 'test',
             type: 'experience',
@@ -208,16 +208,16 @@ describe('collectMessageKeysFromNarratives', () => {
       },
     ];
 
-    const keys = collectMessageKeysFromNarratives(narratives);
+    const keys = collectMessageKeysFromScenes(scenes);
 
     expect(keys.size).toBe(0);
   });
 
   it('handles specs without rules', () => {
-    const narratives: Narrative[] = [
+    const scenes: Scene[] = [
       {
         name: 'Test',
-        slices: [
+        moments: [
           {
             name: 'test',
             type: 'command',
@@ -231,16 +231,16 @@ describe('collectMessageKeysFromNarratives', () => {
       },
     ];
 
-    const keys = collectMessageKeysFromNarratives(narratives);
+    const keys = collectMessageKeysFromScenes(scenes);
 
     expect(keys.size).toBe(0);
   });
 
   it('handles rules without examples', () => {
-    const narratives: Narrative[] = [
+    const scenes: Scene[] = [
       {
         name: 'Test',
-        slices: [
+        moments: [
           {
             name: 'test',
             type: 'command',
@@ -260,16 +260,16 @@ describe('collectMessageKeysFromNarratives', () => {
       },
     ];
 
-    const keys = collectMessageKeysFromNarratives(narratives);
+    const keys = collectMessageKeysFromScenes(scenes);
 
     expect(keys.size).toBe(0);
   });
 
   it('handles examples without steps', () => {
-    const narratives: Narrative[] = [
+    const scenes: Scene[] = [
       {
         name: 'Test',
-        slices: [
+        moments: [
           {
             name: 'test',
             type: 'command',
@@ -294,16 +294,16 @@ describe('collectMessageKeysFromNarratives', () => {
       },
     ];
 
-    const keys = collectMessageKeysFromNarratives(narratives);
+    const keys = collectMessageKeysFromScenes(scenes);
 
     expect(keys.size).toBe(0);
   });
 
   it('handles steps with empty text', () => {
-    const narratives: Narrative[] = [
+    const scenes: Scene[] = [
       {
         name: 'Test',
-        slices: [
+        moments: [
           {
             name: 'test',
             type: 'command',
@@ -333,16 +333,16 @@ describe('collectMessageKeysFromNarratives', () => {
       },
     ];
 
-    const keys = collectMessageKeysFromNarratives(narratives);
+    const keys = collectMessageKeysFromScenes(scenes);
 
     expect(keys.size).toBe(0);
   });
 
-  it('collects keys from multiple narratives and slices', () => {
-    const narratives: Narrative[] = [
+  it('collects keys from multiple scenes and slices', () => {
+    const scenes: Scene[] = [
       {
         name: 'Orders',
-        slices: [
+        moments: [
           {
             name: 'create',
             type: 'command',
@@ -375,7 +375,7 @@ describe('collectMessageKeysFromNarratives', () => {
       },
       {
         name: 'Users',
-        slices: [
+        moments: [
           {
             name: 'register',
             type: 'command',
@@ -408,7 +408,7 @@ describe('collectMessageKeysFromNarratives', () => {
       },
     ];
 
-    const keys = collectMessageKeysFromNarratives(narratives);
+    const keys = collectMessageKeysFromScenes(scenes);
 
     expect(keys.has('command:CreateOrder')).toBe(true);
     expect(keys.has('event:OrderCreated')).toBe(true);

package/src/transformers/model-to-narrative/spec-traversal.ts

@@ -1,18 +1,18 @@
-import type { Narrative } from '../../index';
+import type { Scene } from '../../index';
 
-export function collectMessageKeysFromNarratives(narratives: Narrative[]): Set<string> {
+export function collectMessageKeysFromScenes(scenes: Scene[]): Set<string> {
   const usedKeys = new Set<string>();
 
-  for (const narrative of narratives) {
-    for (const slice of narrative.slices) {
-      collectMessageKeysFromSlice(slice, usedKeys);
+  for (const scene of scenes) {
+    for (const slice of scene.moments) {
+      collectMessageKeysFromMoment(slice, usedKeys);
     }
   }
 
   return usedKeys;
 }
 
-function collectMessageKeysFromSlice(slice: Narrative['slices'][number], usedKeys: Set<string>): void {
+function collectMessageKeysFromMoment(slice: Scene['moments'][number], usedKeys: Set<string>): void {
   if (slice.type !== 'command' && slice.type !== 'query' && slice.type !== 'react') {
     return;
   }

package/src/transformers/model-to-narrative/types.ts

@@ -3,7 +3,7 @@ export interface GeneratedFile {
   code: string;
 }
 
-export interface GeneratedNarratives {
+export interface GeneratedScenes {
   files: GeneratedFile[];
 }
 

package/src/transformers/model-to-narrative/utils/integration-extractor.ts

@@ -44,14 +44,14 @@ function processDataItem(dataItem: Record<string, unknown>, set: Set<string>): v
  * @param flows Array of flow specifications to analyze
  * @returns Array of integration type names found in the flows
  */
-export function extractTypeIntegrationNames(flows: Array<{ name: string; slices: unknown[] }>): string[] {
+export function extractTypeIntegrationNames(flows: Array<{ name: string; moments: unknown[] }>): string[] {
   const set = new Set<string>();
 
   for (const fl of flows) {
-    const slices = fl.slices ?? [];
-    for (const sl of slices) {
-      const sliceData = sl as Record<string, unknown>;
-      const server = sliceData.server as Record<string, unknown> | undefined;
+    const moments = fl.moments ?? [];
+    for (const sl of moments) {
+      const momentData = sl as Record<string, unknown>;
+      const server = momentData.server as Record<string, unknown> | undefined;
       const data = server?.data as unknown[] | undefined;
 
       if (!Array.isArray(data)) continue;

package/src/transformers/model-to-narrative/validate-modules.ts

@@ -4,11 +4,11 @@ import { toMessageKey } from './ordering';
 export interface ValidationError {
   type:
     | 'duplicate_sourceFile'
-    | 'narrative_unassigned'
-    | 'narrative_multi_assigned'
+    | 'scene_unassigned'
+    | 'scene_multi_assigned'
     | 'message_multi_declared'
     | 'message_undeclared'
-    | 'narrative_not_found';
+    | 'scene_not_found';
   message: string;
 }
 
@@ -27,7 +27,7 @@ export function validateModules(model: Model): ValidationError[] {
     return errors;
   }
 
-  errors.push(...validateNarrativeAssignments(authoredModules, model));
+  errors.push(...validateSceneAssignments(authoredModules, model));
   errors.push(...validateMessageDeclarations(authoredModules, model));
 
   return errors;
@@ -53,42 +53,42 @@ function validateUniqueSourceFiles(modules: Model['modules']): ValidationError[]
   return errors;
 }
 
-function validateNarrativeAssignments(authoredModules: Model['modules'], model: Model): ValidationError[] {
+function validateSceneAssignments(authoredModules: Model['modules'], model: Model): ValidationError[] {
   const errors: ValidationError[] = [];
-  const narrativeAssignments = new Map<string, string[]>();
+  const sceneAssignments = new Map<string, string[]>();
 
   for (const module of authoredModules) {
-    for (const narrativeId of module.contains.narrativeIds) {
-      if (!narrativeAssignments.has(narrativeId)) {
-        narrativeAssignments.set(narrativeId, []);
+    for (const sceneId of module.contains.sceneIds) {
+      if (!sceneAssignments.has(sceneId)) {
+        sceneAssignments.set(sceneId, []);
       }
-      narrativeAssignments.get(narrativeId)!.push(module.sourceFile);
+      sceneAssignments.get(sceneId)!.push(module.sourceFile);
     }
   }
 
-  const modelNarrativeIds = new Set(model.narratives.map((n) => n.id).filter((id): id is string => id !== undefined));
+  const modelSceneIds = new Set(model.scenes.map((n) => n.id).filter((id): id is string => id !== undefined));
 
-  for (const [narrativeId, moduleSourceFiles] of narrativeAssignments) {
-    if (!modelNarrativeIds.has(narrativeId)) {
+  for (const [sceneId, moduleSourceFiles] of sceneAssignments) {
+    if (!modelSceneIds.has(sceneId)) {
       errors.push({
-        type: 'narrative_not_found',
-        message: `Narrative '${narrativeId}' referenced by module(s) [${moduleSourceFiles.join(', ')}] does not exist`,
+        type: 'scene_not_found',
+        message: `Scene '${sceneId}' referenced by module(s) [${moduleSourceFiles.join(', ')}] does not exist`,
       });
     }
     if (moduleSourceFiles.length > 1) {
       errors.push({
-        type: 'narrative_multi_assigned',
-        message: `Narrative '${narrativeId}' is assigned to multiple modules: [${moduleSourceFiles.join(', ')}]`,
+        type: 'scene_multi_assigned',
+        message: `Scene '${sceneId}' is assigned to multiple modules: [${moduleSourceFiles.join(', ')}]`,
       });
     }
   }
 
-  const assignedNarrativeIds = new Set(narrativeAssignments.keys());
-  for (const narrative of model.narratives) {
-    if (narrative.id && !assignedNarrativeIds.has(narrative.id)) {
+  const assignedSceneIds = new Set(sceneAssignments.keys());
+  for (const scene of model.scenes) {
+    if (scene.id && !assignedSceneIds.has(scene.id)) {
       errors.push({
-        type: 'narrative_unassigned',
-        message: `Narrative '${narrative.id}' (${narrative.name}) is not assigned to any module`,
+        type: 'scene_unassigned',
+        message: `Scene '${scene.id}' (${scene.name}) is not assigned to any module`,
       });
     }
   }

package/src/transformers/narrative-to-model/assemble.ts

@@ -1,15 +1,23 @@
-import type { Message, Model, Narrative } from '../../index';
+import type { Message, Model, Narrative, Scene } from '../../index';
 import { deriveModules } from './derive-modules';
 
-export function assembleSpecs(narratives: Narrative[], messages: unknown[], integrations: unknown[]): Model {
+export function assembleSpecs(scenes: Scene[], messages: unknown[], integrations: unknown[]): Model {
   const typedMessages = messages as Message[];
-  const modules = deriveModules(narratives, typedMessages);
+  const modules = deriveModules(scenes, typedMessages);
+
+  const narratives: Narrative[] = [
+    {
+      name: 'Default',
+      sceneIds: scenes.filter((s) => s.id).map((s) => s.id!),
+    },
+  ];
 
   return {
     variant: 'specs' as const,
-    narratives,
+    scenes,
     messages: typedMessages,
     integrations: integrations as Model['integrations'],
     modules,
+    narratives,
   };
 }

package/src/transformers/narrative-to-model/debug.ts

@@ -1,6 +1,6 @@
 import createDebug from 'debug';
 
-export const debugIntegrations = createDebug('auto:flow:getNarratives:integrations');
+export const debugIntegrations = createDebug('auto:flow:getScenes:integrations');
 if (typeof debugIntegrations === 'object' && debugIntegrations !== null && 'color' in debugIntegrations) {
   (debugIntegrations as { color: string }).color = '6';
 }

package/src/transformers/narrative-to-model/derive-modules.specs.ts

@@ -1,64 +1,64 @@
 import { describe, expect, it } from 'vitest';
-import type { Message, Narrative } from '../../index';
+import type { Message, Scene } from '../../index';
 import { deriveModules } from './derive-modules';
 
 describe('deriveModules', () => {
-  it('groups narratives by sourceFile into separate modules', () => {
-    const narratives: Narrative[] = [
-      { name: 'Orders', id: 'orders-1', sourceFile: 'orders.narrative.ts', slices: [] },
-      { name: 'Users', id: 'users-1', sourceFile: 'users.narrative.ts', slices: [] },
+  it('groups scenes by sourceFile into separate modules', () => {
+    const scenes: Scene[] = [
+      { name: 'Orders', id: 'orders-1', sourceFile: 'orders.narrative.ts', moments: [] },
+      { name: 'Users', id: 'users-1', sourceFile: 'users.narrative.ts', moments: [] },
     ];
     const messages: Message[] = [];
 
-    const modules = deriveModules(narratives, messages);
+    const modules = deriveModules(scenes, messages);
 
     expect(modules).toHaveLength(2);
     expect(modules.map((m) => m.sourceFile).sort()).toEqual(['orders.narrative.ts', 'users.narrative.ts']);
   });
 
-  it('uses default sourceFile when narrative has no sourceFile', () => {
-    const narratives: Narrative[] = [{ name: 'Default', id: 'default-1', slices: [] }];
+  it('uses default sourceFile when scene has no sourceFile', () => {
+    const scenes: Scene[] = [{ name: 'Default', id: 'default-1', moments: [] }];
     const messages: Message[] = [];
 
-    const modules = deriveModules(narratives, messages);
+    const modules = deriveModules(scenes, messages);
 
     expect(modules).toHaveLength(1);
     expect(modules[0].sourceFile).toBe('generated.narrative.ts');
   });
 
-  it('generates synthetic narrative IDs when narratives have no ID', () => {
-    const narratives: Narrative[] = [
-      { name: 'First', slices: [] },
-      { name: 'Second', slices: [] },
+  it('generates synthetic scene IDs when scenes have no ID', () => {
+    const scenes: Scene[] = [
+      { name: 'First', moments: [] },
+      { name: 'Second', moments: [] },
     ];
     const messages: Message[] = [];
 
-    const modules = deriveModules(narratives, messages);
+    const modules = deriveModules(scenes, messages);
 
     expect(modules).toHaveLength(1);
-    expect(modules[0].contains.narrativeIds).toEqual(['__derived_0_0_First', '__derived_0_1_Second']);
+    expect(modules[0].contains.sceneIds).toEqual(['__derived_0_0_First', '__derived_0_1_Second']);
   });
 
   it('sets isDerived to true for all generated modules', () => {
-    const narratives: Narrative[] = [{ name: 'Test', id: 'test-1', slices: [] }];
+    const scenes: Scene[] = [{ name: 'Test', id: 'test-1', moments: [] }];
     const messages: Message[] = [];
 
-    const modules = deriveModules(narratives, messages);
+    const modules = deriveModules(scenes, messages);
 
     expect(modules[0].isDerived).toBe(true);
   });
 
   it('includes all messages in declares for each module', () => {
-    const narratives: Narrative[] = [
-      { name: 'Orders', id: 'orders-1', sourceFile: 'orders.narrative.ts', slices: [] },
-      { name: 'Users', id: 'users-1', sourceFile: 'users.narrative.ts', slices: [] },
+    const scenes: Scene[] = [
+      { name: 'Orders', id: 'orders-1', sourceFile: 'orders.narrative.ts', moments: [] },
+      { name: 'Users', id: 'users-1', sourceFile: 'users.narrative.ts', moments: [] },
     ];
     const messages: Message[] = [
       { type: 'command', name: 'CreateOrder', fields: [] },
       { type: 'event', source: 'internal', name: 'OrderCreated', fields: [] },
     ];
 
-    const modules = deriveModules(narratives, messages);
+    const modules = deriveModules(scenes, messages);
 
     for (const mod of modules) {
       expect(mod.declares.messages).toEqual([
@@ -69,14 +69,14 @@ describe('deriveModules', () => {
   });
 
   it('sorts declared messages by kind:name', () => {
-    const narratives: Narrative[] = [{ name: 'Test', id: 'test-1', slices: [] }];
+    const scenes: Scene[] = [{ name: 'Test', id: 'test-1', moments: [] }];
     const messages: Message[] = [
       { type: 'state', name: 'ZState', fields: [] },
       { type: 'command', name: 'ACommand', fields: [] },
       { type: 'event', source: 'internal', name: 'MEvent', fields: [] },
     ];
 
-    const modules = deriveModules(narratives, messages);
+    const modules = deriveModules(scenes, messages);
 
     expect(modules[0].declares.messages).toEqual([
       { kind: 'command', name: 'ACommand' },
@@ -86,35 +86,35 @@ describe('deriveModules', () => {
   });
 
   it('creates independent message arrays for each module', () => {
-    const narratives: Narrative[] = [
-      { name: 'A', id: 'a', sourceFile: 'a.ts', slices: [] },
-      { name: 'B', id: 'b', sourceFile: 'b.ts', slices: [] },
+    const scenes: Scene[] = [
+      { name: 'A', id: 'a', sourceFile: 'a.ts', moments: [] },
+      { name: 'B', id: 'b', sourceFile: 'b.ts', moments: [] },
     ];
     const messages: Message[] = [{ type: 'event', source: 'internal', name: 'SharedEvent', fields: [] }];
 
-    const modules = deriveModules(narratives, messages);
+    const modules = deriveModules(scenes, messages);
 
     expect(modules[0].declares.messages).not.toBe(modules[1].declares.messages);
     expect(modules[0].declares.messages).toEqual(modules[1].declares.messages);
   });
 
-  it('returns empty array when no narratives provided', () => {
+  it('returns empty array when no scenes provided', () => {
     const modules = deriveModules([], []);
 
     expect(modules).toEqual([]);
   });
 
-  it('groups multiple narratives with same sourceFile into one module', () => {
-    const narratives: Narrative[] = [
-      { name: 'Flow1', id: 'flow-1', sourceFile: 'shared.ts', slices: [] },
-      { name: 'Flow2', id: 'flow-2', sourceFile: 'shared.ts', slices: [] },
-      { name: 'Flow3', id: 'flow-3', sourceFile: 'shared.ts', slices: [] },
+  it('groups multiple scenes with same sourceFile into one module', () => {
+    const scenes: Scene[] = [
+      { name: 'Flow1', id: 'flow-1', sourceFile: 'shared.ts', moments: [] },
+      { name: 'Flow2', id: 'flow-2', sourceFile: 'shared.ts', moments: [] },
+      { name: 'Flow3', id: 'flow-3', sourceFile: 'shared.ts', moments: [] },
     ];
     const messages: Message[] = [];
 
-    const modules = deriveModules(narratives, messages);
+    const modules = deriveModules(scenes, messages);
 
     expect(modules).toHaveLength(1);
-    expect(modules[0].contains.narrativeIds).toEqual(['flow-1', 'flow-2', 'flow-3']);
+    expect(modules[0].contains.sceneIds).toEqual(['flow-1', 'flow-2', 'flow-3']);
   });
 });

package/src/transformers/narrative-to-model/derive-modules.ts

@@ -1,12 +1,12 @@
-import type { Message, Module, Narrative } from '../../index';
+import type { Message, Module, Scene } from '../../index';
 
 const DEFAULT_SOURCE_FILE = 'generated.narrative.ts';
 
-export function deriveModules(narratives: Narrative[], messages: Message[]): Module[] {
-  const bySourceFile = groupNarrativesBySourceFile(narratives);
+export function deriveModules(scenes: Scene[], messages: Message[]): Module[] {
+  const bySourceFile = groupScenesBySourceFile(scenes);
 
-  return Array.from(bySourceFile.entries()).map(([sourceFile, narrs], index) => {
-    const narrativeIds = narrs.map((n, i) => n.id ?? `__derived_${index}_${i}_${n.name}`);
+  return Array.from(bySourceFile.entries()).map(([sourceFile, scns], index) => {
+    const sceneIds = scns.map((n, i) => n.id ?? `__derived_${index}_${i}_${n.name}`);
     const messageRefs = messages
       .map((m) => ({ kind: m.type, name: m.name }))
       .sort((a, b) => `${a.kind}:${a.name}`.localeCompare(`${b.kind}:${b.name}`));
@@ -14,21 +14,21 @@ export function deriveModules(narratives: Narrative[], messages: Message[]): Mod
     return {
       sourceFile,
       isDerived: true,
-      contains: { narrativeIds },
+      contains: { sceneIds },
       declares: { messages: messageRefs },
     };
   });
 }
 
-function groupNarrativesBySourceFile(narratives: Narrative[]): Map<string, Narrative[]> {
-  const groups = new Map<string, Narrative[]>();
+function groupScenesBySourceFile(scenes: Scene[]): Map<string, Scene[]> {
+  const groups = new Map<string, Scene[]>();
 
-  for (const narrative of narratives) {
-    const sourceFile = narrative.sourceFile ?? DEFAULT_SOURCE_FILE;
+  for (const scene of scenes) {
+    const sourceFile = scene.sourceFile ?? DEFAULT_SOURCE_FILE;
     if (!groups.has(sourceFile)) {
       groups.set(sourceFile, []);
     }
-    groups.get(sourceFile)!.push(narrative);
+    groups.get(sourceFile)!.push(scene);
   }
 
   return groups;