@auto-engineer/narrative 0.15.0 → 0.17.0

package/package.json

@@ -23,9 +23,9 @@
     "typescript": "^5.9.2",
     "zod": "^3.22.4",
     "zod-to-json-schema": "^3.22.3",
-    "@auto-engineer/file-store": "0.15.0",
-    "@auto-engineer/message-bus": "0.15.0",
-    "@auto-engineer/id": "0.15.0"
+    "@auto-engineer/id": "0.17.0",
+    "@auto-engineer/file-store": "0.17.0",
+    "@auto-engineer/message-bus": "0.17.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -35,10 +35,11 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "0.15.0",
+  "version": "0.17.0",
   "scripts": {
     "build": "tsx scripts/build.ts",
     "test": "vitest run --reporter=dot",
+    "test:coverage": "vitest run --reporter=dot --coverage --coverage.reporter=text",
     "type-check": "tsc --noEmit",
     "convert-narrative": "tsx scripts/convert-narrative.ts",
     "link:dev": "pnpm build && pnpm link --global",

package/src/getNarratives.specs.ts

@@ -660,7 +660,8 @@ flow('questionnaires-test', () => {
     });
 
     const model = flows.toModel();
-    const code = await modelToNarrative(model);
+    const result = await modelToNarrative(model);
+    const code = result.files.map((f) => f.code).join('\n');
 
     expect(code).not.toMatch(/\.when<>\(\{\}\)/);
     expect(code).not.toMatch(/\.when<\s*\{\s*}\s*>\(\{}\)/);
@@ -1241,6 +1242,218 @@ function validateThenEvents(example: unknown): void {
   }
 }
 
+describe('modules in toModel()', () => {
+  it('should derive modules from narratives with different sourceFiles', async () => {
+    const memoryVfs = new InMemoryFileStore();
+
+    const ordersContent = `
+import { flow, command, specs, rule, example, type Command, type Event } from '@auto-engineer/narrative';
+
+type CreateOrder = Command<'CreateOrder', { orderId: string }>;
+type OrderCreated = Event<'OrderCreated', { orderId: string; createdAt: Date }>;
+
+flow('Orders', () => {
+  command('create order')
+    .server(() => {
+      specs(() => {
+        rule('creates an order', () => {
+          example('order created')
+            .when<CreateOrder>({ orderId: 'order-001' })
+            .then<OrderCreated>({ orderId: 'order-001', createdAt: new Date('2030-01-01T09:00:00Z') });
+        });
+      });
+    });
+});
+`;
+
+    const usersContent = `
+import { flow, command, specs, rule, example, type Command, type Event } from '@auto-engineer/narrative';
+
+type CreateUser = Command<'CreateUser', { userId: string; name: string }>;
+type UserCreated = Event<'UserCreated', { userId: string; name: string; createdAt: Date }>;
+
+flow('Users', () => {
+  command('create user')
+    .server(() => {
+      specs(() => {
+        rule('creates a user', () => {
+          example('user created')
+            .when<CreateUser>({ userId: 'user-001', name: 'Alice' })
+            .then<UserCreated>({ userId: 'user-001', name: 'Alice', createdAt: new Date('2030-01-01T09:00:00Z') });
+        });
+      });
+    });
+});
+`;
+
+    await memoryVfs.write('/test/orders.narrative.ts', new TextEncoder().encode(ordersContent));
+    await memoryVfs.write('/test/users.narrative.ts', new TextEncoder().encode(usersContent));
+
+    const flows = await getNarratives({
+      vfs: memoryVfs,
+      root: '/test',
+      pattern: /\.narrative\.ts$/,
+      fastFsScan: true,
+    });
+    const model = flows.toModel();
+
+    expect(model.modules).toBeDefined();
+    expect(model.modules.length).toBe(2);
+
+    const sourceFiles = model.modules.map((m) => m.sourceFile);
+    expect(sourceFiles.some((sf) => sf.includes('orders.narrative.ts'))).toBe(true);
+    expect(sourceFiles.some((sf) => sf.includes('users.narrative.ts'))).toBe(true);
+
+    const ordersModule = model.modules.find((m) => m.sourceFile.includes('orders.narrative.ts'));
+    const usersModule = model.modules.find((m) => m.sourceFile.includes('users.narrative.ts'));
+
+    expect(ordersModule).toBeDefined();
+    expect(ordersModule?.isDerived).toBe(true);
+
+    expect(usersModule).toBeDefined();
+    expect(usersModule?.isDerived).toBe(true);
+  });
+
+  it('should include all messages in derived module declarations', async () => {
+    const memoryVfs = new InMemoryFileStore();
+
+    const content = `
+import { flow, command, specs, rule, example, type Command, type Event } from '@auto-engineer/narrative';
+
+type CreateOrder = Command<'CreateOrder', { orderId: string }>;
+type OrderCreated = Event<'OrderCreated', { orderId: string }>;
+
+flow('Orders', () => {
+  command('create order')
+    .server(() => {
+      specs(() => {
+        rule('creates order', () => {
+          example('order created')
+            .when<CreateOrder>({ orderId: 'order-001' })
+            .then<OrderCreated>({ orderId: 'order-001' });
+        });
+      });
+    });
+});
+`;
+
+    await memoryVfs.write('/test/orders.narrative.ts', new TextEncoder().encode(content));
+
+    const flows = await getNarratives({
+      vfs: memoryVfs,
+      root: '/test',
+      pattern: /\.narrative\.ts$/,
+      fastFsScan: true,
+    });
+    const model = flows.toModel();
+
+    expect(model.modules).toHaveLength(1);
+    const mod = model.modules[0];
+
+    const declaredNames = mod.declares.messages.map((m) => m.name);
+    expect(declaredNames).toContain('CreateOrder');
+    expect(declaredNames).toContain('OrderCreated');
+  });
+
+  it('should group narratives from same sourceFile into one module', async () => {
+    const memoryVfs = new InMemoryFileStore();
+
+    const content = `
+import { flow, command, query, specs, rule, example, type Command, type Event, type State } from '@auto-engineer/narrative';
+
+type CreateTodo = Command<'CreateTodo', { todoId: string }>;
+type TodoCreated = Event<'TodoCreated', { todoId: string }>;
+type TodoList = State<'TodoList', { todos: string[] }>;
+
+flow('Create Todos', () => {
+  command('add todo')
+    .server(() => {
+      specs(() => {
+        rule('adds todo', () => {
+          example('todo added')
+            .when<CreateTodo>({ todoId: 'todo-001' })
+            .then<TodoCreated>({ todoId: 'todo-001' });
+        });
+      });
+    });
+});
+
+flow('View Todos', () => {
+  query('list todos')
+    .server(() => {
+      specs(() => {
+        rule('shows todos', () => {
+          example('todos listed')
+            .given<TodoCreated>({ todoId: 'todo-001' })
+            .when({})
+            .then<TodoList>({ todos: ['todo-001'] });
+        });
+      });
+    });
+});
+`;
+
+    await memoryVfs.write('/test/todos.narrative.ts', new TextEncoder().encode(content));
+
+    const flows = await getNarratives({
+      vfs: memoryVfs,
+      root: '/test',
+      pattern: /\.narrative\.ts$/,
+      fastFsScan: true,
+    });
+    const model = flows.toModel();
+
+    expect(model.modules).toHaveLength(1);
+    expect(model.modules[0].contains.narrativeIds).toHaveLength(2);
+
+    const narrativeNames = model.narratives.map((n) => n.name);
+    expect(narrativeNames).toContain('Create Todos');
+    expect(narrativeNames).toContain('View Todos');
+  });
+
+  it('should validate model with modules passes schema', async () => {
+    const memoryVfs = new InMemoryFileStore();
+
+    const content = `
+import { flow, command, specs, rule, example, type Command, type Event } from '@auto-engineer/narrative';
+
+type DoSomething = Command<'DoSomething', { id: string }>;
+type SomethingDone = Event<'SomethingDone', { id: string }>;
+
+flow('Test', () => {
+  command('do something')
+    .server(() => {
+      specs(() => {
+        rule('does something', () => {
+          example('something done')
+            .when<DoSomething>({ id: '001' })
+            .then<SomethingDone>({ id: '001' });
+        });
+      });
+    });
+});
+`;
+
+    await memoryVfs.write('/test/test.narrative.ts', new TextEncoder().encode(content));
+
+    const flows = await getNarratives({
+      vfs: memoryVfs,
+      root: '/test',
+      pattern: /\.narrative\.ts$/,
+      fastFsScan: true,
+    });
+    const model = flows.toModel();
+
+    const parseResult = modelSchema.safeParse(model);
+    if (!parseResult.success) {
+      console.error('Schema validation errors:', parseResult.error.format());
+    }
+    expect(parseResult.success).toBe(true);
+    expect(parseResult.data?.modules).toBeDefined();
+    expect(parseResult.data?.modules.length).toBeGreaterThan(0);
+  });
+});
+
 describe('projection DSL methods', () => {
   it('should generate correct origin for singleton projection', async () => {
     const memoryVfs = new InMemoryFileStore();

package/src/getNarratives.ts

@@ -151,7 +151,7 @@ export const getNarratives = async (
       typeMap: new Map(),
       typesByFile: new Map(),
       givenTypesByFile: new Map(),
-      toModel: () => ({ variant: 'specs' as const, narratives: [], messages: [] }),
+      toModel: () => ({ variant: 'specs' as const, narratives: [], messages: [], modules: [] }),
     };
   }
 

package/src/id/addAutoIds.specs.ts

@@ -79,6 +79,7 @@ describe('addAutoIds', () => {
     ],
     messages: [],
     integrations: [],
+    modules: [],
   };
 
   const AUTO_ID_REGEX = /^[A-Za-z0-9_]{9}$/;
@@ -161,6 +162,7 @@ describe('addAutoIds', () => {
       ],
       messages: [],
       integrations: [],
+      modules: [],
     };
 
     const result = addAutoIds(modelWithoutServer);
@@ -207,6 +209,7 @@ describe('addAutoIds', () => {
       ],
       messages: [],
       integrations: [],
+      modules: [],
     };
 
     const result = addAutoIds(modelWithExperienceSlice);
@@ -262,6 +265,7 @@ describe('addAutoIds', () => {
       ],
       messages: [],
       integrations: [],
+      modules: [],
     };
 
     const result = addAutoIds(modelWithMultipleFlowsSameSource);
@@ -320,6 +324,7 @@ describe('addAutoIds', () => {
       ],
       messages: [],
       integrations: [],
+      modules: [],
     };
 
     const result = addAutoIds(modelWithSpecs);
@@ -372,6 +377,7 @@ describe('addAutoIds', () => {
       ],
       messages: [],
       integrations: [],
+      modules: [],
     };
 
     const result = addAutoIds(modelWithSteps);
@@ -427,6 +433,7 @@ describe('addAutoIds', () => {
       ],
       messages: [],
       integrations: [],
+      modules: [],
     };
 
     const result = addAutoIds(modelWithExistingExampleId);
@@ -480,6 +487,7 @@ describe('addAutoIds', () => {
       ],
       messages: [],
       integrations: [],
+      modules: [],
     };
 
     const result = addAutoIds(modelWithErrorSteps);
@@ -515,6 +523,7 @@ describe('addAutoIds', () => {
       ],
       messages: [],
       integrations: [],
+      modules: [],
     };
 
     const result = addAutoIds(modelWithClientSpecs);
@@ -557,6 +566,7 @@ describe('addAutoIds', () => {
       ],
       messages: [],
       integrations: [],
+      modules: [],
     };
 
     const result = addAutoIds(modelWithDescribe);
@@ -603,6 +613,7 @@ describe('addAutoIds', () => {
       ],
       messages: [],
       integrations: [],
+      modules: [],
     };
 
     const result = addAutoIds(modelWithNestedSpecs);
@@ -647,6 +658,7 @@ describe('addAutoIds', () => {
       ],
       messages: [],
       integrations: [],
+      modules: [],
     };
 
     const originalSpec = modelWithClientSpecs.narratives[0].slices[0];
@@ -656,4 +668,172 @@ describe('addAutoIds', () => {
       expect(originalSpec.client.specs[0].id).toBeUndefined();
     }
   });
+
+  describe('module ID generation', () => {
+    const AUTO_ID_REGEX = /^[A-Za-z0-9_]{9}$/;
+
+    it('should assign ID to derived module equal to sourceFile', () => {
+      const model: Model = {
+        variant: 'specs',
+        narratives: [],
+        messages: [],
+        integrations: [],
+        modules: [
+          {
+            id: '',
+            sourceFile: 'orders.narrative.ts',
+            isDerived: true,
+            contains: { narrativeIds: [] },
+            declares: { messages: [] },
+          },
+        ],
+      };
+
+      const result = addAutoIds(model);
+
+      expect(result.modules[0].id).toBe('orders.narrative.ts');
+    });
+
+    it('should generate auto ID for authored module without ID', () => {
+      const model: Model = {
+        variant: 'specs',
+        narratives: [],
+        messages: [],
+        integrations: [],
+        modules: [
+          {
+            id: '',
+            sourceFile: 'features/orders.ts',
+            isDerived: false,
+            contains: { narrativeIds: [] },
+            declares: { messages: [] },
+          },
+        ],
+      };
+
+      const result = addAutoIds(model);
+
+      expect(result.modules[0].id).toMatch(AUTO_ID_REGEX);
+    });
+
+    it('should preserve existing ID for authored module', () => {
+      const model: Model = {
+        variant: 'specs',
+        narratives: [],
+        messages: [],
+        integrations: [],
+        modules: [
+          {
+            id: 'EXISTING-MODULE-001',
+            sourceFile: 'features/orders.ts',
+            isDerived: false,
+            contains: { narrativeIds: [] },
+            declares: { messages: [] },
+          },
+        ],
+      };
+
+      const result = addAutoIds(model);
+
+      expect(result.modules[0].id).toBe('EXISTING-MODULE-001');
+    });
+
+    it('should not mutate original modules', () => {
+      const model: Model = {
+        variant: 'specs',
+        narratives: [],
+        messages: [],
+        integrations: [],
+        modules: [
+          {
+            id: '',
+            sourceFile: 'test.ts',
+            isDerived: false,
+            contains: { narrativeIds: [] },
+            declares: { messages: [] },
+          },
+        ],
+      };
+
+      const originalId = model.modules[0].id;
+      addAutoIds(model);
+
+      expect(model.modules[0].id).toBe(originalId);
+    });
+
+    it('should generate unique IDs for multiple authored modules', () => {
+      const model: Model = {
+        variant: 'specs',
+        narratives: [],
+        messages: [],
+        integrations: [],
+        modules: [
+          {
+            id: '',
+            sourceFile: 'orders.ts',
+            isDerived: false,
+            contains: { narrativeIds: [] },
+            declares: { messages: [] },
+          },
+          {
+            id: '',
+            sourceFile: 'users.ts',
+            isDerived: false,
+            contains: { narrativeIds: [] },
+            declares: { messages: [] },
+          },
+        ],
+      };
+
+      const result = addAutoIds(model);
+
+      expect(result.modules[0].id).toMatch(AUTO_ID_REGEX);
+      expect(result.modules[1].id).toMatch(AUTO_ID_REGEX);
+      expect(result.modules[0].id).not.toBe(result.modules[1].id);
+    });
+
+    it('should handle mixed derived and authored modules', () => {
+      const model: Model = {
+        variant: 'specs',
+        narratives: [],
+        messages: [],
+        integrations: [],
+        modules: [
+          {
+            id: '',
+            sourceFile: 'derived.narrative.ts',
+            isDerived: true,
+            contains: { narrativeIds: [] },
+            declares: { messages: [] },
+          },
+          {
+            id: '',
+            sourceFile: 'authored.ts',
+            isDerived: false,
+            contains: { narrativeIds: [] },
+            declares: { messages: [] },
+          },
+        ],
+      };
+
+      const result = addAutoIds(model);
+
+      expect(result.modules[0].id).toBe('derived.narrative.ts');
+      expect(result.modules[1].id).toMatch(AUTO_ID_REGEX);
+    });
+
+    it('should handle empty modules array', () => {
+      const model: Model = {
+        variant: 'specs',
+        narratives: [],
+        messages: [],
+        integrations: [],
+        modules: [],
+      };
+
+      const result = addAutoIds(model);
+
+      expect(result.modules).toEqual([]);
+    });
+  });
 });

package/src/id/addAutoIds.ts

@@ -1,4 +1,4 @@
-import type { ClientSpecNode, Example, Model, Rule, Slice, Spec, Step } from '../index';
+import type { ClientSpecNode, Example, Model, Module, Rule, Slice, Spec, Step } from '../index';
 import { generateAutoId } from './generators';
 
 function ensureId(item: { id?: string }): void {
@@ -85,6 +85,18 @@ function processSlice(slice: Slice): Slice {
   return sliceCopy;
 }
 
+function processModules(modules: Module[]): Module[] {
+  return modules.map((module) => {
+    const moduleCopy = { ...module };
+    if (module.isDerived) {
+      moduleCopy.id = module.sourceFile;
+    } else {
+      ensureId(moduleCopy);
+    }
+    return moduleCopy;
+  });
+}
+
 export function addAutoIds(specs: Model): Model {
   const result = structuredClone(specs);
   result.narratives = result.narratives.map((narrative) => {
@@ -93,5 +105,8 @@ export function addAutoIds(specs: Model): Model {
     narrativeCopy.slices = narrative.slices.map(processSlice);
     return narrativeCopy;
   });
+  if (result.modules) {
+    result.modules = processModules(result.modules);
+  }
   return result;
 }

package/src/id/hasAllIds.specs.ts

@@ -34,6 +34,7 @@ describe('hasAllIds', () => {
     ],
     messages: [],
     integrations: [],
+    modules: [],
   });
 
   const createModelWithIds = (): Model => ({
@@ -71,6 +72,7 @@ describe('hasAllIds', () => {
     ],
     messages: [],
     integrations: [],
+    modules: [],
   });
 
   const createModelWithFullIds = (): Model => ({
@@ -131,6 +133,7 @@ describe('hasAllIds', () => {
     ],
     messages: [],
     integrations: [],
+    modules: [],
   });
 
   const createMultipleFlowsModel = (includeAllIds: boolean, includeAllSliceIds: boolean): Model => ({
@@ -178,6 +181,7 @@ describe('hasAllIds', () => {
     ],
     messages: [],
     integrations: [],
+    modules: [],
   });
 
   it('should return false for models without IDs', () => {
@@ -310,6 +314,7 @@ describe('hasAllIds', () => {
       ],
       messages: [],
       integrations: [],
+      modules: [],
     };
     expect(hasAllIds(model)).toBe(false);
   });
@@ -335,6 +340,7 @@ describe('hasAllIds', () => {
       ],
       messages: [],
       integrations: [],
+      modules: [],
     };
     expect(hasAllIds(model)).toBe(false);
   });
@@ -366,6 +372,7 @@ describe('hasAllIds', () => {
       ],
       messages: [],
       integrations: [],
+      modules: [],
     };
     expect(hasAllIds(model)).toBe(false);
   });
@@ -398,6 +405,7 @@ describe('hasAllIds', () => {
       ],
       messages: [],
       integrations: [],
+      modules: [],
     };
     expect(hasAllIds(model)).toBe(false);
   });
@@ -438,7 +446,86 @@ describe('hasAllIds', () => {
       ],
       messages: [],
       integrations: [],
+      modules: [],
     };
     expect(hasAllIds(model)).toBe(true);
   });
+
+  describe('module ID validation', () => {
+    it('should return true when all modules have IDs', () => {
+      const model: Model = {
+        variant: 'specs',
+        narratives: [],
+        messages: [],
+        integrations: [],
+        modules: [
+          {
+            id: 'module-1',
+            sourceFile: 'test.ts',
+            isDerived: false,
+            contains: { narrativeIds: [] },
+            declares: { messages: [] },
+          },
+        ],
+      };
+      expect(hasAllIds(model)).toBe(true);
+    });
+
+    it('should return false when module has empty ID', () => {
+      const model: Model = {
+        variant: 'specs',
+        narratives: [],
+        messages: [],
+        integrations: [],
+        modules: [
+          {
+            id: '',
+            sourceFile: 'test.ts',
+            isDerived: false,
+            contains: { narrativeIds: [] },
+            declares: { messages: [] },
+          },
+        ],
+      };
+      expect(hasAllIds(model)).toBe(false);
+    });
+
+    it('should return false when any module is missing ID among valid narratives', () => {
+      const model: Model = {
+        variant: 'specs',
+        narratives: [{ name: 'Test', id: 'FLOW-001', slices: [] }],
+        messages: [],
+        integrations: [],
+        modules: [
+          {
+            id: '',
+            sourceFile: 'test.ts',
+            isDerived: true,
+            contains: { narrativeIds: ['FLOW-001'] },
+            declares: { messages: [] },
+          },
+        ],
+      };
+      expect(hasAllIds(model)).toBe(false);
+    });
+
+    it('should return true for derived module with valid ID', () => {
+      const model: Model = {
+        variant: 'specs',
+        narratives: [],
+        messages: [],
+        integrations: [],
+        modules: [
+          {
+            id: 'derived.ts',
+            sourceFile: 'derived.ts',
+            isDerived: true,
+            contains: { narrativeIds: [] },
+            declares: { messages: [] },
+          },
+        ],
+      };
+      expect(hasAllIds(model)).toBe(true);
+    });
+  });
 });