@auto-engineer/narrative 1.128.1 → 1.129.0

package/ketchup-plan.md

@@ -1,4 +1,4 @@
-# Ketchup Plan: DataTarget Schema — Target-Only Event Items
+# Ketchup Plan: Fix Scaffolder ListType Handling + node:crypto Protocol
 
 ## TODO
 
@@ -6,7 +6,5 @@
 
 ## DONE
 
-- [x] Burst 1: Add DataTargetSchema to schema.ts, DataTarget type, DataTargetItem, exports (81188d6b)
-- [x] Burst 2: Add target() builder factory in data-narrative-builders.ts (757b8475)
-- [x] Burst 3: Update stripTypeDiscriminator — completed in burst 1 (type change propagated)
-- [x] Burst 4: Update flow code generator to handle target-only items (057c6e56)
+- [x] Burst 1: Add isArray to getTypeName, handle ListType kind, update parseGraphQlRequest tsType wrapping — with test cases for [String!], [String!]!, [CustomType] (db71f007)
+- [x] Burst 2: Change 'crypto' to 'node:crypto' in handle.ts.ejs template

package/package.json

@@ -26,9 +26,9 @@
     "typescript": "^5.9.2",
     "zod": "^3.22.4",
     "zod-to-json-schema": "^3.22.3",
-    "@auto-engineer/file-store": "1.128.1",
-    "@auto-engineer/id": "1.128.1",
-    "@auto-engineer/message-bus": "1.128.1"
+    "@auto-engineer/file-store": "1.129.0",
+    "@auto-engineer/id": "1.129.0",
+    "@auto-engineer/message-bus": "1.129.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -38,7 +38,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.128.1",
+  "version": "1.129.0",
   "scripts": {
     "build": "tsx scripts/build.ts",
     "test": "vitest run --reporter=dot",

package/src/getNarratives.specs.ts

@@ -3,7 +3,7 @@ import { fileURLToPath } from 'node:url';
 import { InMemoryFileStore } from '@auto-engineer/file-store';
 import { NodeFileStore } from '@auto-engineer/file-store/node';
 import { beforeEach, describe, expect, it } from 'vitest';
-import { getNarratives } from './getNarratives';
+import { clearGetNarrativesCache, getNarratives } from './getNarratives';
 import { type Example, type Model, modelToNarrative, type Narrative, type QuerySlice } from './index';
 import { modelSchema } from './schema';
 
@@ -1781,3 +1781,511 @@ flow('Data Item IDs', () => {
     }
   });
 });
+
+describe('round-trip: model -> narrative code -> VFS -> getNarratives -> toModel', { timeout: 30_000 }, () => {
+  it('preserves step text values through full round-trip', async () => {
+    const inputModel: Model = {
+      variant: 'specs',
+      narratives: [
+        {
+          name: 'Stay management',
+          slices: [
+            {
+              type: 'command',
+              name: 'Publish stay',
+              stream: 'stay-${stayId}',
+              client: { specs: [] },
+              server: {
+                description: '',
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'Publishing stays',
+                    rules: [
+                      {
+                        name: 'A valid stay can be published',
+                        examples: [
+                          {
+                            name: 'publish a draft stay',
+                            steps: [
+                              {
+                                keyword: 'Given',
+                                text: 'StayCreated',
+                                docString: { stayId: 'stay_1', title: 'Beach house' },
+                              },
+                              {
+                                keyword: 'When',
+                                text: 'PublishStay',
+                                docString: { stayId: 'stay_1' },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'StayPublished',
+                                docString: { stayId: 'stay_1', publishedAt: '2024-06-01T00:00:00.000Z' },
+                              },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+                data: undefined,
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        {
+          type: 'event',
+          name: 'StayCreated',
+          fields: [
+            { name: 'stayId', type: 'string', required: true },
+            { name: 'title', type: 'string', required: true },
+          ],
+        },
+        {
+          type: 'command',
+          name: 'PublishStay',
+          fields: [{ name: 'stayId', type: 'string', required: true }],
+        },
+        {
+          type: 'event',
+          name: 'StayPublished',
+          fields: [
+            { name: 'stayId', type: 'string', required: true },
+            { name: 'publishedAt', type: 'string', required: true },
+          ],
+        },
+      ],
+      modules: [],
+    };
+
+    const generated = await modelToNarrative(inputModel);
+
+    const vfs = new InMemoryFileStore();
+    clearGetNarrativesCache();
+
+    for (const file of generated.files) {
+      const filePath = `/project/${file.path}`;
+      await vfs.write(filePath, new TextEncoder().encode(file.code));
+    }
+
+    const result = await getNarratives({
+      vfs,
+      root: '/project',
+      pattern: /\.(narrative)\.(ts)$/,
+      fastFsScan: true,
+    });
+
+    const roundTrippedModel = result.toModel();
+
+    const stayNarrative = roundTrippedModel.narratives.find((n) => n.name === 'Stay management');
+    const publishSlice = stayNarrative!.slices.find((s) => s.name === 'Publish stay');
+    expect(publishSlice!.type).toBe('command');
+
+    if (publishSlice?.type === 'command') {
+      const example = publishSlice.server.specs[0].rules[0].examples[0];
+      expect(example.steps).toEqual([
+        { keyword: 'Given', text: 'StayCreated', docString: { stayId: 'stay_1', title: 'Beach house' } },
+        { keyword: 'When', text: 'PublishStay', docString: { stayId: 'stay_1' } },
+        {
+          keyword: 'Then',
+          text: 'StayPublished',
+          docString: { stayId: 'stay_1', publishedAt: '2024-06-01T00:00:00.000Z' },
+        },
+      ]);
+    }
+  });
+
+  it('preserves step text with multiple given events and multiple examples', async () => {
+    const inputModel: Model = {
+      variant: 'specs',
+      narratives: [
+        {
+          name: 'Order processing',
+          slices: [
+            {
+              type: 'command',
+              name: 'Complete order',
+              stream: 'order-${orderId}',
+              client: { specs: [] },
+              server: {
+                description: '',
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'Completing orders',
+                    rules: [
+                      {
+                        name: 'An order with items can be completed',
+                        examples: [
+                          {
+                            name: 'complete an order with payment',
+                            steps: [
+                              {
+                                keyword: 'Given',
+                                text: 'OrderCreated',
+                                docString: { orderId: 'ord_1', customerId: 'cust_1' },
+                              },
+                              {
+                                keyword: 'And',
+                                text: 'PaymentReceived',
+                                docString: { orderId: 'ord_1', amount: 100 },
+                              },
+                              {
+                                keyword: 'When',
+                                text: 'CompleteOrder',
+                                docString: { orderId: 'ord_1' },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'OrderCompleted',
+                                docString: { orderId: 'ord_1', completedAt: '2024-06-01T00:00:00.000Z' },
+                              },
+                            ],
+                          },
+                          {
+                            name: 'reject order without payment',
+                            steps: [
+                              {
+                                keyword: 'Given',
+                                text: 'OrderCreated',
+                                docString: { orderId: 'ord_2', customerId: 'cust_2' },
+                              },
+                              {
+                                keyword: 'When',
+                                text: 'CompleteOrder',
+                                docString: { orderId: 'ord_2' },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'OrderRejected',
+                                docString: { orderId: 'ord_2', reason: 'no payment' },
+                              },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+                data: undefined,
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        {
+          type: 'event',
+          name: 'OrderCreated',
+          fields: [
+            { name: 'orderId', type: 'string', required: true },
+            { name: 'customerId', type: 'string', required: true },
+          ],
+        },
+        {
+          type: 'event',
+          name: 'PaymentReceived',
+          fields: [
+            { name: 'orderId', type: 'string', required: true },
+            { name: 'amount', type: 'number', required: true },
+          ],
+        },
+        {
+          type: 'command',
+          name: 'CompleteOrder',
+          fields: [{ name: 'orderId', type: 'string', required: true }],
+        },
+        {
+          type: 'event',
+          name: 'OrderCompleted',
+          fields: [
+            { name: 'orderId', type: 'string', required: true },
+            { name: 'completedAt', type: 'string', required: true },
+          ],
+        },
+        {
+          type: 'event',
+          name: 'OrderRejected',
+          fields: [
+            { name: 'orderId', type: 'string', required: true },
+            { name: 'reason', type: 'string', required: true },
+          ],
+        },
+      ],
+      modules: [],
+    };
+
+    const generated = await modelToNarrative(inputModel);
+
+    const vfs = new InMemoryFileStore();
+    clearGetNarrativesCache();
+
+    for (const file of generated.files) {
+      const filePath = `/project/${file.path}`;
+      await vfs.write(filePath, new TextEncoder().encode(file.code));
+    }
+
+    const result = await getNarratives({
+      vfs,
+      root: '/project',
+      pattern: /\.(narrative)\.(ts)$/,
+      fastFsScan: true,
+    });
+
+    const roundTrippedModel = result.toModel();
+
+    const orderNarrative = roundTrippedModel.narratives.find((n) => n.name === 'Order processing');
+    const completeSlice = orderNarrative!.slices.find((s) => s.name === 'Complete order');
+    expect(completeSlice!.type).toBe('command');
+
+    if (completeSlice?.type === 'command') {
+      const examples = completeSlice.server.specs[0].rules[0].examples;
+
+      expect(examples[0].steps).toEqual([
+        { keyword: 'Given', text: 'OrderCreated', docString: { orderId: 'ord_1', customerId: 'cust_1' } },
+        { keyword: 'And', text: 'PaymentReceived', docString: { orderId: 'ord_1', amount: 100 } },
+        { keyword: 'When', text: 'CompleteOrder', docString: { orderId: 'ord_1' } },
+        {
+          keyword: 'Then',
+          text: 'OrderCompleted',
+          docString: { orderId: 'ord_1', completedAt: '2024-06-01T00:00:00.000Z' },
+        },
+      ]);
+
+      expect(examples[1].steps).toEqual([
+        { keyword: 'Given', text: 'OrderCreated', docString: { orderId: 'ord_2', customerId: 'cust_2' } },
+        { keyword: 'When', text: 'CompleteOrder', docString: { orderId: 'ord_2' } },
+        { keyword: 'Then', text: 'OrderRejected', docString: { orderId: 'ord_2', reason: 'no payment' } },
+      ]);
+    }
+  });
+
+  it('preserves step text with multiple narratives in separate modules', async () => {
+    const inputModel: Model = {
+      variant: 'specs',
+      narratives: [
+        {
+          name: 'Stays',
+          sourceFile: 'stays.narrative.ts',
+          slices: [
+            {
+              type: 'command',
+              name: 'Create stay',
+              stream: 'stay-${stayId}',
+              client: { specs: [] },
+              server: {
+                description: '',
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'Creating stays',
+                    rules: [
+                      {
+                        name: 'A valid stay can be created',
+                        examples: [
+                          {
+                            name: 'create a new stay',
+                            steps: [
+                              {
+                                keyword: 'When',
+                                text: 'CreateStay',
+                                docString: { stayId: 'stay_1', title: 'Cozy cabin' },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'StayCreated',
+                                docString: { stayId: 'stay_1', title: 'Cozy cabin' },
+                              },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+                data: undefined,
+              },
+            },
+          ],
+        },
+        {
+          name: 'Bookings',
+          sourceFile: 'bookings.narrative.ts',
+          slices: [
+            {
+              type: 'command',
+              name: 'Book stay',
+              stream: 'booking-${bookingId}',
+              client: { specs: [] },
+              server: {
+                description: '',
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'Booking stays',
+                    rules: [
+                      {
+                        name: 'A published stay can be booked',
+                        examples: [
+                          {
+                            name: 'book a published stay',
+                            steps: [
+                              {
+                                keyword: 'Given',
+                                text: 'StayPublished',
+                                docString: { stayId: 'stay_1', publishedAt: '2024-01-01T00:00:00.000Z' },
+                              },
+                              {
+                                keyword: 'When',
+                                text: 'BookStay',
+                                docString: { stayId: 'stay_1', guestId: 'guest_1' },
+                              },
+                              {
+                                keyword: 'Then',
+                                text: 'StayBooked',
+                                docString: {
+                                  stayId: 'stay_1',
+                                  guestId: 'guest_1',
+                                  bookedAt: '2024-02-01T00:00:00.000Z',
+                                },
+                              },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+                data: undefined,
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        {
+          type: 'command',
+          name: 'CreateStay',
+          fields: [
+            { name: 'stayId', type: 'string', required: true },
+            { name: 'title', type: 'string', required: true },
+          ],
+        },
+        {
+          type: 'event',
+          name: 'StayCreated',
+          fields: [
+            { name: 'stayId', type: 'string', required: true },
+            { name: 'title', type: 'string', required: true },
+          ],
+        },
+        {
+          type: 'event',
+          name: 'StayPublished',
+          fields: [
+            { name: 'stayId', type: 'string', required: true },
+            { name: 'publishedAt', type: 'string', required: true },
+          ],
+        },
+        {
+          type: 'command',
+          name: 'BookStay',
+          fields: [
+            { name: 'stayId', type: 'string', required: true },
+            { name: 'guestId', type: 'string', required: true },
+          ],
+        },
+        {
+          type: 'event',
+          name: 'StayBooked',
+          fields: [
+            { name: 'stayId', type: 'string', required: true },
+            { name: 'guestId', type: 'string', required: true },
+            { name: 'bookedAt', type: 'string', required: true },
+          ],
+        },
+      ],
+      modules: [
+        {
+          sourceFile: 'stays.narrative.ts',
+          isDerived: true,
+          contains: { narrativeIds: [] },
+          declares: {
+            messages: [
+              { kind: 'command', name: 'CreateStay' },
+              { kind: 'event', name: 'StayCreated' },
+            ],
+          },
+        },
+        {
+          sourceFile: 'bookings.narrative.ts',
+          isDerived: true,
+          contains: { narrativeIds: [] },
+          declares: {
+            messages: [
+              { kind: 'event', name: 'StayPublished' },
+              { kind: 'command', name: 'BookStay' },
+              { kind: 'event', name: 'StayBooked' },
+            ],
+          },
+        },
+      ],
+    };
+
+    const generated = await modelToNarrative(inputModel);
+
+    const vfs = new InMemoryFileStore();
+    clearGetNarrativesCache();
+
+    for (const file of generated.files) {
+      const filePath = `/project/${file.path}`;
+      await vfs.write(filePath, new TextEncoder().encode(file.code));
+    }
+
+    const result = await getNarratives({
+      vfs,
+      root: '/project',
+      pattern: /\.(narrative)\.(ts)$/,
+      fastFsScan: true,
+    });
+
+    const roundTrippedModel = result.toModel();
+
+    const bookingsNarrative = roundTrippedModel.narratives.find((n) => n.name === 'Bookings');
+    const bookSlice = bookingsNarrative!.slices.find((s) => s.name === 'Book stay');
+    expect(bookSlice!.type).toBe('command');
+
+    if (bookSlice?.type === 'command') {
+      const example = bookSlice.server.specs[0].rules[0].examples[0];
+      expect(example.steps).toEqual([
+        {
+          keyword: 'Given',
+          text: 'StayPublished',
+          docString: { stayId: 'stay_1', publishedAt: '2024-01-01T00:00:00.000Z' },
+        },
+        { keyword: 'When', text: 'BookStay', docString: { stayId: 'stay_1', guestId: 'guest_1' } },
+        {
+          keyword: 'Then',
+          text: 'StayBooked',
+          docString: { stayId: 'stay_1', guestId: 'guest_1', bookedAt: '2024-02-01T00:00:00.000Z' },
+        },
+      ]);
+    }
+
+    const staysNarrative = roundTrippedModel.narratives.find((n) => n.name === 'Stays');
+    const createSlice = staysNarrative!.slices.find((s) => s.name === 'Create stay');
+    expect(createSlice!.type).toBe('command');
+
+    if (createSlice?.type === 'command') {
+      const example = createSlice.server.specs[0].rules[0].examples[0];
+      expect(example.steps).toEqual([
+        { keyword: 'When', text: 'CreateStay', docString: { stayId: 'stay_1', title: 'Cozy cabin' } },
+        { keyword: 'Then', text: 'StayCreated', docString: { stayId: 'stay_1', title: 'Cozy cabin' } },
+      ]);
+    }
+  });
+});

package/src/loader/ts-utils.specs.ts

@@ -1,6 +1,32 @@
 import ts from 'typescript';
 import { describe, expect, it } from 'vitest';
-import { parseTypeDefinitions } from './ts-utils';
+import {
+  parseGivenTypeArguments,
+  parseThenTypeArguments,
+  parseTypeDefinitions,
+  parseWhenTypeArguments,
+} from './ts-utils';
+import { createVfsCompilerHost } from './vfs-compiler-host';
+
+function createProgramFromSource(source: string, fileName: string = '/test.ts') {
+  const sourceFile = ts.createSourceFile(fileName, source, ts.ScriptTarget.ES2020, true, ts.ScriptKind.TS);
+  const sourceFiles = new Map<string, ts.SourceFile>([[fileName, sourceFile]]);
+  const host = createVfsCompilerHost(ts, sourceFiles);
+  const program = ts.createProgram(
+    [fileName],
+    {
+      target: ts.ScriptTarget.ES2020,
+      module: ts.ModuleKind.ESNext,
+      strict: true,
+      skipLibCheck: true,
+      skipDefaultLibCheck: true,
+    },
+    host,
+  );
+  const checker = program.getTypeChecker();
+  const programSourceFile = program.getSourceFile(fileName)!;
+  return { checker, sourceFile: programSourceFile };
+}
 
 describe('parseTypeDefinitions', () => {
   it('extracts data fields with Array<T> generic syntax', () => {
@@ -23,3 +49,69 @@ describe('parseTypeDefinitions', () => {
     });
   });
 });
+
+describe('parseGivenTypeArguments fallback', () => {
+  it('uses raw type text when tryUnwrapGeneric fails to resolve', () => {
+    const source = `
+      example('test')
+        .given<UnresolvableType>({ id: '1' })
+        .when<AnotherUnresolvable>({ name: 'foo' });
+    `;
+    const { checker, sourceFile } = createProgramFromSource(source);
+    const typeMap = new Map();
+    const typesByFile = new Map();
+
+    const result = parseGivenTypeArguments(ts, checker, sourceFile, typeMap, typesByFile);
+
+    expect(result).toEqual([expect.objectContaining({ ordinal: 0, typeName: 'UnresolvableType' })]);
+  });
+
+  it('preserves ordinal alignment when some types resolve and others do not', () => {
+    const source = `
+      type KnownEvent = Event<'KnownEvent', { id: string }>;
+      example('test')
+        .given<KnownEvent>({ id: '1' })
+        .and<UnknownType>({ name: 'foo' });
+    `;
+    const typeMap = parseTypeDefinitions(ts, '/test.ts', source);
+    const typesByFile = new Map([['/test.ts', typeMap]]);
+    const { checker, sourceFile } = createProgramFromSource(source);
+
+    const result = parseGivenTypeArguments(ts, checker, sourceFile, typeMap, typesByFile);
+
+    expect(result).toEqual([
+      expect.objectContaining({ ordinal: 0, typeName: 'KnownEvent', classification: 'event' }),
+      expect.objectContaining({ ordinal: 1, typeName: 'UnknownType' }),
+    ]);
+  });
+});
+
+describe('parseWhenTypeArguments fallback', () => {
+  it('uses raw type text when tryUnwrapGeneric fails to resolve', () => {
+    const source = `
+      example('test')
+        .when<UnresolvableCommand>({ id: '1' });
+    `;
+    const { checker, sourceFile } = createProgramFromSource(source);
+
+    const result = parseWhenTypeArguments(ts, checker, sourceFile, new Map(), new Map());
+
+    expect(result).toEqual([expect.objectContaining({ ordinal: 0, typeName: 'UnresolvableCommand' })]);
+  });
+});
+
+describe('parseThenTypeArguments fallback', () => {
+  it('uses raw type text when tryUnwrapGeneric fails to resolve', () => {
+    const source = `
+      example('test')
+        .given<SomeType>({ id: '1' })
+        .when<SomeCommand>({ name: 'foo' })
+        .then<UnresolvableResult>({ status: 'ok' });
+    `;
+    const { checker, sourceFile } = createProgramFromSource(source);
+
+    const result = parseThenTypeArguments(ts, checker, sourceFile, new Map(), new Map());
+
+    expect(result).toEqual([expect.objectContaining({ ordinal: 0, typeName: 'UnresolvableResult' })]);
+  });
+});

package/src/loader/ts-utils.ts

@@ -594,6 +594,9 @@ function processGivenOrAndCallExpression(
     givenTypes.push(
       createGivenTypeInfo(sourceFile, node, ordinal, genericResult.typeName, genericResult.classification),
     );
+  } else {
+    const rawText = typeArg.getText(sourceFile);
+    givenTypes.push(createGivenTypeInfo(sourceFile, node, ordinal, rawText, 'event'));
   }
 }
 
@@ -656,6 +659,9 @@ function processWhenCallExpression(
     whenTypes.push(
       createGivenTypeInfo(sourceFile, node, ordinal, genericResult.typeName, genericResult.classification),
     );
+  } else {
+    const rawText = typeArg.getText(sourceFile);
+    whenTypes.push(createGivenTypeInfo(sourceFile, node, ordinal, rawText, 'command'));
   }
 }
 
@@ -828,6 +834,8 @@ function processThenCallWithTypeArg(
     thenTypes.push(
       createGivenTypeInfo(sourceFile, node, thenTypes.length, genericResult.typeName, genericResult.classification),
     );
+  } else {
+    thenTypes.push(createGivenTypeInfo(sourceFile, node, thenTypes.length, typeArgText, 'event'));
   }
 }