@auto-engineer/narrative 0.15.0 → 0.17.0

package/src/transformers/model-to-narrative/ordering.specs.ts

@@ -0,0 +1,104 @@
+import { describe, expect, it } from 'vitest';
+import { parseMessageKey, sortFilesByPath, sortImportsBySource, sortMessagesByKey, toMessageKey } from './ordering';
+
+describe('ordering utilities', () => {
+  describe('toMessageKey', () => {
+    it('creates key from kind and name', () => {
+      expect(toMessageKey('command', 'AddTodo')).toBe('command:AddTodo');
+      expect(toMessageKey('event', 'TodoAdded')).toBe('event:TodoAdded');
+      expect(toMessageKey('state', 'TodoList')).toBe('state:TodoList');
+    });
+  });
+
+  describe('parseMessageKey', () => {
+    it('parses key back to kind and name', () => {
+      expect(parseMessageKey('command:AddTodo')).toEqual({ kind: 'command', name: 'AddTodo' });
+      expect(parseMessageKey('event:TodoAdded')).toEqual({ kind: 'event', name: 'TodoAdded' });
+      expect(parseMessageKey('state:TodoList')).toEqual({ kind: 'state', name: 'TodoList' });
+    });
+
+    it('throws error for invalid format without colon', () => {
+      expect(() => parseMessageKey('invalid')).toThrow('Invalid message key format: invalid');
+    });
+
+    it('throws error for invalid kind', () => {
+      expect(() => parseMessageKey('unknown:SomeMessage')).toThrow('Invalid message kind: unknown');
+    });
+
+    it('handles names containing colons', () => {
+      expect(parseMessageKey('event:Foo:Bar')).toEqual({ kind: 'event', name: 'Foo:Bar' });
+    });
+  });
+
+  describe('sortMessagesByKey', () => {
+    it('sorts messages alphabetically by messageKey', () => {
+      const messages = [
+        { kind: 'state' as const, name: 'TodoList' },
+        { kind: 'command' as const, name: 'AddTodo' },
+        { kind: 'event' as const, name: 'TodoAdded' },
+        { kind: 'command' as const, name: 'DeleteTodo' },
+      ];
+
+      const sorted = sortMessagesByKey(messages);
+
+      expect(sorted).toEqual([
+        { kind: 'command', name: 'AddTodo' },
+        { kind: 'command', name: 'DeleteTodo' },
+        { kind: 'event', name: 'TodoAdded' },
+        { kind: 'state', name: 'TodoList' },
+      ]);
+    });
+
+    it('returns empty array for empty input', () => {
+      expect(sortMessagesByKey([])).toEqual([]);
+    });
+  });
+
+  describe('sortFilesByPath', () => {
+    it('sorts files alphabetically by path', () => {
+      const files = [
+        { path: 'src/users.narrative.ts', code: 'users' },
+        { path: 'generated.narrative.ts', code: 'default' },
+        { path: 'src/orders.narrative.ts', code: 'orders' },
+      ];
+
+      const sorted = sortFilesByPath(files);
+
+      expect(sorted.map((f) => f.path)).toEqual([
+        'generated.narrative.ts',
+        'src/orders.narrative.ts',
+        'src/users.narrative.ts',
+      ]);
+    });
+
+    it('returns empty array for empty input', () => {
+      expect(sortFilesByPath([])).toEqual([]);
+    });
+  });
+
+  describe('sortImportsBySource', () => {
+    it('sorts imports alphabetically by source path then by type names', () => {
+      const imports = [
+        { fromPath: './users', typeNames: ['CreateUser', 'UserCreated'] },
+        { fromPath: './orders', typeNames: ['PlaceOrder', 'OrderPlaced'] },
+        { fromPath: './shared', typeNames: ['BaseEvent'] },
+      ];
+
+      const sorted = sortImportsBySource(imports);
+
+      expect(sorted.map((i) => i.fromPath)).toEqual(['./orders', './shared', './users']);
+    });
+
+    it('sorts type names within each import', () => {
+      const imports = [{ fromPath: './types', typeNames: ['Zebra', 'Alpha', 'Beta'] }];
+
+      const sorted = sortImportsBySource(imports);
+
+      expect(sorted[0].typeNames).toEqual(['Alpha', 'Beta', 'Zebra']);
+    });
+
+    it('returns empty array for empty input', () => {
+      expect(sortImportsBySource([])).toEqual([]);
+    });
+  });
+});

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

@@ -0,0 +1,46 @@
+import type { MessageRef } from '../../index';
+import type { CrossModuleImport, GeneratedFile } from './types';
+
+type MessageKind = MessageRef['kind'];
+
+export function toMessageKey(kind: MessageKind, name: string): string {
+  return `${kind}:${name}`;
+}
+
+function isMessageKind(value: string): value is MessageKind {
+  return value === 'command' || value === 'event' || value === 'state';
+}
+
+export function parseMessageKey(key: string): MessageRef {
+  const colonIndex = key.indexOf(':');
+  if (colonIndex === -1) {
+    throw new Error(`Invalid message key format: ${key}`);
+  }
+  const kindStr = key.slice(0, colonIndex);
+  if (!isMessageKind(kindStr)) {
+    throw new Error(`Invalid message kind: ${kindStr}`);
+  }
+  const name = key.slice(colonIndex + 1);
+  return { kind: kindStr, name };
+}
+
+export function sortMessagesByKey<T extends MessageRef>(messages: T[]): T[] {
+  return [...messages].sort((a, b) => {
+    const keyA = toMessageKey(a.kind, a.name);
+    const keyB = toMessageKey(b.kind, b.name);
+    return keyA.localeCompare(keyB);
+  });
+}
+
+export function sortFilesByPath<T extends GeneratedFile>(files: T[]): T[] {
+  return [...files].sort((a, b) => a.path.localeCompare(b.path));
+}
+
+export function sortImportsBySource(imports: CrossModuleImport[]): CrossModuleImport[] {
+  return [...imports]
+    .map((imp) => ({
+      ...imp,
+      typeNames: [...imp.typeNames].sort((a, b) => a.localeCompare(b)),
+    }))
+    .sort((a, b) => a.fromPath.localeCompare(b.fromPath));
+}

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

@@ -0,0 +1,418 @@
+import { describe, expect, it } from 'vitest';
+import type { Narrative } from '../../index';
+import { collectMessageKeysFromNarratives } from './spec-traversal';
+
+describe('collectMessageKeysFromNarratives', () => {
+  it('returns empty set for empty narratives array', () => {
+    const keys = collectMessageKeysFromNarratives([]);
+
+    expect(keys.size).toBe(0);
+  });
+
+  it('returns empty set for narratives with no slices', () => {
+    const narratives: Narrative[] = [{ name: 'Empty', slices: [] }];
+
+    const keys = collectMessageKeysFromNarratives(narratives);
+
+    expect(keys.size).toBe(0);
+  });
+
+  it('ignores experience slices', () => {
+    const narratives: Narrative[] = [
+      {
+        name: 'Test',
+        slices: [
+          {
+            name: 'Homepage',
+            type: 'experience',
+            client: { specs: [] },
+          },
+        ],
+      },
+    ];
+
+    const keys = collectMessageKeysFromNarratives(narratives);
+
+    expect(keys.size).toBe(0);
+  });
+
+  it('collects command keys from When steps', () => {
+    const narratives: Narrative[] = [
+      {
+        name: 'Test',
+        slices: [
+          {
+            name: 'create order',
+            type: 'command',
+            client: { specs: [] },
+            server: {
+              description: 'Test',
+              specs: [
+                {
+                  type: 'gherkin',
+                  feature: 'Test',
+                  rules: [
+                    {
+                      name: 'test rule',
+                      examples: [
+                        {
+                          name: 'test example',
+                          steps: [{ keyword: 'When', text: 'CreateOrder' }],
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          },
+        ],
+      },
+    ];
+
+    const keys = collectMessageKeysFromNarratives(narratives);
+
+    expect(keys.has('command:CreateOrder')).toBe(true);
+  });
+
+  it('collects event and state keys from Given steps', () => {
+    const narratives: Narrative[] = [
+      {
+        name: 'Test',
+        slices: [
+          {
+            name: 'view order',
+            type: 'query',
+            client: { specs: [] },
+            server: {
+              description: 'Test',
+              specs: [
+                {
+                  type: 'gherkin',
+                  feature: 'Test',
+                  rules: [
+                    {
+                      name: 'test rule',
+                      examples: [
+                        {
+                          name: 'test example',
+                          steps: [{ keyword: 'Given', text: 'OrderCreated' }],
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          },
+        ],
+      },
+    ];
+
+    const keys = collectMessageKeysFromNarratives(narratives);
+
+    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[] = [
+      {
+        name: 'Test',
+        slices: [
+          {
+            name: 'test',
+            type: 'react',
+            server: {
+              description: 'Test',
+              specs: [
+                {
+                  type: 'gherkin',
+                  feature: 'Test',
+                  rules: [
+                    {
+                      name: 'test rule',
+                      examples: [
+                        {
+                          name: 'test example',
+                          steps: [{ keyword: 'And', text: 'UserLoggedIn' }],
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          },
+        ],
+      },
+    ];
+
+    const keys = collectMessageKeysFromNarratives(narratives);
+
+    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[] = [
+      {
+        name: 'Test',
+        slices: [
+          {
+            name: 'test',
+            type: 'command',
+            client: { specs: [] },
+            server: {
+              description: 'Test',
+              specs: [
+                {
+                  type: 'gherkin',
+                  feature: 'Test',
+                  rules: [
+                    {
+                      name: 'test rule',
+                      examples: [
+                        {
+                          name: 'test example',
+                          steps: [{ keyword: 'Then', text: 'OrderCompleted' }],
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          },
+        ],
+      },
+    ];
+
+    const keys = collectMessageKeysFromNarratives(narratives);
+
+    expect(keys.has('event:OrderCompleted')).toBe(true);
+    expect(keys.has('state:OrderCompleted')).toBe(true);
+  });
+
+  it('handles slices without server specs', () => {
+    const narratives: Narrative[] = [
+      {
+        name: 'Test',
+        slices: [
+          {
+            name: 'test',
+            type: 'experience',
+            client: { specs: [] },
+          },
+        ],
+      },
+    ];
+
+    const keys = collectMessageKeysFromNarratives(narratives);
+
+    expect(keys.size).toBe(0);
+  });
+
+  it('handles specs without rules', () => {
+    const narratives: Narrative[] = [
+      {
+        name: 'Test',
+        slices: [
+          {
+            name: 'test',
+            type: 'command',
+            client: { specs: [] },
+            server: {
+              description: 'Test',
+              specs: [{ type: 'gherkin', feature: 'Test', rules: [] }],
+            },
+          },
+        ],
+      },
+    ];
+
+    const keys = collectMessageKeysFromNarratives(narratives);
+
+    expect(keys.size).toBe(0);
+  });
+
+  it('handles rules without examples', () => {
+    const narratives: Narrative[] = [
+      {
+        name: 'Test',
+        slices: [
+          {
+            name: 'test',
+            type: 'command',
+            client: { specs: [] },
+            server: {
+              description: 'Test',
+              specs: [
+                {
+                  type: 'gherkin',
+                  feature: 'Test',
+                  rules: [{ name: 'empty rule', examples: [] }],
+                },
+              ],
+            },
+          },
+        ],
+      },
+    ];
+
+    const keys = collectMessageKeysFromNarratives(narratives);
+
+    expect(keys.size).toBe(0);
+  });
+
+  it('handles examples without steps', () => {
+    const narratives: Narrative[] = [
+      {
+        name: 'Test',
+        slices: [
+          {
+            name: 'test',
+            type: 'command',
+            client: { specs: [] },
+            server: {
+              description: 'Test',
+              specs: [
+                {
+                  type: 'gherkin',
+                  feature: 'Test',
+                  rules: [
+                    {
+                      name: 'rule',
+                      examples: [{ name: 'empty example', steps: [] }],
+                    },
+                  ],
+                },
+              ],
+            },
+          },
+        ],
+      },
+    ];
+
+    const keys = collectMessageKeysFromNarratives(narratives);
+
+    expect(keys.size).toBe(0);
+  });
+
+  it('handles steps with empty text', () => {
+    const narratives: Narrative[] = [
+      {
+        name: 'Test',
+        slices: [
+          {
+            name: 'test',
+            type: 'command',
+            client: { specs: [] },
+            server: {
+              description: 'Test',
+              specs: [
+                {
+                  type: 'gherkin',
+                  feature: 'Test',
+                  rules: [
+                    {
+                      name: 'rule',
+                      examples: [
+                        {
+                          name: 'example',
+                          steps: [{ keyword: 'When', text: '' }],
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          },
+        ],
+      },
+    ];
+
+    const keys = collectMessageKeysFromNarratives(narratives);
+
+    expect(keys.size).toBe(0);
+  });
+
+  it('collects keys from multiple narratives and slices', () => {
+    const narratives: Narrative[] = [
+      {
+        name: 'Orders',
+        slices: [
+          {
+            name: 'create',
+            type: 'command',
+            client: { specs: [] },
+            server: {
+              description: 'Test',
+              specs: [
+                {
+                  type: 'gherkin',
+                  feature: 'Test',
+                  rules: [
+                    {
+                      name: 'rule',
+                      examples: [
+                        {
+                          name: 'example',
+                          steps: [
+                            { keyword: 'When', text: 'CreateOrder' },
+                            { keyword: 'Then', text: 'OrderCreated' },
+                          ],
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          },
+        ],
+      },
+      {
+        name: 'Users',
+        slices: [
+          {
+            name: 'register',
+            type: 'command',
+            client: { specs: [] },
+            server: {
+              description: 'Test',
+              specs: [
+                {
+                  type: 'gherkin',
+                  feature: 'Test',
+                  rules: [
+                    {
+                      name: 'rule',
+                      examples: [
+                        {
+                          name: 'example',
+                          steps: [
+                            { keyword: 'When', text: 'RegisterUser' },
+                            { keyword: 'Then', text: 'UserRegistered' },
+                          ],
+                        },
+                      ],
+                    },
+                  ],
+                },
+              ],
+            },
+          },
+        ],
+      },
+    ];
+
+    const keys = collectMessageKeysFromNarratives(narratives);
+
+    expect(keys.has('command:CreateOrder')).toBe(true);
+    expect(keys.has('event:OrderCreated')).toBe(true);
+    expect(keys.has('command:RegisterUser')).toBe(true);
+    expect(keys.has('event:UserRegistered')).toBe(true);
+  });
+});

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

@@ -0,0 +1,63 @@
+import type { Narrative } from '../../index';
+
+export function collectMessageKeysFromNarratives(narratives: Narrative[]): Set<string> {
+  const usedKeys = new Set<string>();
+
+  for (const narrative of narratives) {
+    for (const slice of narrative.slices) {
+      collectMessageKeysFromSlice(slice, usedKeys);
+    }
+  }
+
+  return usedKeys;
+}
+
+function collectMessageKeysFromSlice(slice: Narrative['slices'][number], usedKeys: Set<string>): void {
+  if (slice.type !== 'command' && slice.type !== 'query' && slice.type !== 'react') {
+    return;
+  }
+
+  const specs = slice.server?.specs;
+  if (!Array.isArray(specs)) {
+    return;
+  }
+
+  for (const spec of specs) {
+    if (!spec.rules || !Array.isArray(spec.rules)) {
+      continue;
+    }
+
+    for (const rule of spec.rules) {
+      if (!rule.examples || !Array.isArray(rule.examples)) {
+        continue;
+      }
+
+      for (const example of rule.examples) {
+        if (!example.steps || !Array.isArray(example.steps)) {
+          continue;
+        }
+
+        for (const step of example.steps) {
+          collectMessageKeyFromStep(step, usedKeys);
+        }
+      }
+    }
+  }
+}
+
+function collectMessageKeyFromStep(step: { keyword?: string; text?: string }, usedKeys: Set<string>): void {
+  if (!('text' in step) || !step.text) {
+    return;
+  }
+
+  const keyword = step.keyword;
+  if (keyword === 'Given' || keyword === 'And') {
+    usedKeys.add(`event:${step.text}`);
+    usedKeys.add(`state:${step.text}`);
+  } else if (keyword === 'When') {
+    usedKeys.add(`command:${step.text}`);
+  } else if (keyword === 'Then') {
+    usedKeys.add(`event:${step.text}`);
+    usedKeys.add(`state:${step.text}`);
+  }
+}

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

@@ -0,0 +1,13 @@
+export interface GeneratedFile {
+  path: string;
+  code: string;
+}
+
+export interface GeneratedNarratives {
+  files: GeneratedFile[];
+}
+
+export interface CrossModuleImport {
+  fromPath: string;
+  typeNames: string[];
+}