@auto-engineer/narrative 0.15.0 → 0.17.0

package/src/transformers/model-to-narrative/cross-module-imports.specs.ts

@@ -0,0 +1,450 @@
+import { describe, expect, it } from 'vitest';
+import type { Model } from '../../index';
+import { computeCrossModuleImports, resolveRelativeImport } from './cross-module-imports';
+
+describe('resolveRelativeImport', () => {
+  it('resolves same directory imports', () => {
+    const result = resolveRelativeImport('src/orders.ts', 'src/types.ts');
+
+    expect(result).toBe('./types');
+  });
+
+  it('resolves parent directory imports with ../', () => {
+    const result = resolveRelativeImport('src/features/orders.ts', 'src/shared/types.ts');
+
+    expect(result).toBe('../shared/types');
+  });
+
+  it('resolves deeply nested imports', () => {
+    const result = resolveRelativeImport('src/a/b/c/file.ts', 'src/x/y/target.ts');
+
+    expect(result).toBe('../../../x/y/target');
+  });
+
+  it('strips file extension from target', () => {
+    const result = resolveRelativeImport('src/orders.narrative.ts', 'src/types.narrative.ts');
+
+    expect(result).toBe('./types.narrative');
+  });
+
+  it('resolves from child to parent directory', () => {
+    const result = resolveRelativeImport('src/features/orders.ts', 'src/types.ts');
+
+    expect(result).toBe('../types');
+  });
+
+  it('resolves from root to nested directory', () => {
+    const result = resolveRelativeImport('index.ts', 'src/types.ts');
+
+    expect(result).toBe('./src/types');
+  });
+});
+
+describe('computeCrossModuleImports', () => {
+  it('returns empty array for derived modules', () => {
+    const model: Model = {
+      variant: 'specs',
+      narratives: [],
+      messages: [],
+      integrations: [],
+      modules: [
+        {
+          id: 'derived.ts',
+          sourceFile: 'derived.ts',
+          isDerived: true,
+          contains: { narrativeIds: [] },
+          declares: { messages: [] },
+        },
+      ],
+    };
+
+    const imports = computeCrossModuleImports(model.modules[0], model.modules, model);
+
+    expect(imports).toEqual([]);
+  });
+
+  it('returns empty array when module declares all needed types', () => {
+    const model: Model = {
+      variant: 'specs',
+      narratives: [
+        {
+          name: 'Test',
+          id: 'test-1',
+          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: 'DoSomething' }],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [{ type: 'command', name: 'DoSomething', fields: [] }],
+      integrations: [],
+      modules: [
+        {
+          id: 'self-contained',
+          sourceFile: 'self-contained.ts',
+          isDerived: false,
+          contains: { narrativeIds: ['test-1'] },
+          declares: { messages: [{ kind: 'command', name: 'DoSomething' }] },
+        },
+      ],
+    };
+
+    const imports = computeCrossModuleImports(model.modules[0], model.modules, model);
+
+    expect(imports).toEqual([]);
+  });
+
+  it('returns empty array when needed type is not declared by any module', () => {
+    const model: Model = {
+      variant: 'specs',
+      narratives: [
+        {
+          name: 'Test',
+          id: 'test-1',
+          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: 'MissingCommand' }],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [{ type: 'command', name: 'MissingCommand', fields: [] }],
+      integrations: [],
+      modules: [
+        {
+          id: 'consumer',
+          sourceFile: 'consumer.ts',
+          isDerived: false,
+          contains: { narrativeIds: ['test-1'] },
+          declares: { messages: [] },
+        },
+      ],
+    };
+
+    const imports = computeCrossModuleImports(model.modules[0], model.modules, model);
+
+    expect(imports).toEqual([]);
+  });
+
+  it('generates import when type is declared by another authored module', () => {
+    const model: Model = {
+      variant: 'specs',
+      narratives: [
+        { name: 'Shared', id: 'shared-1', slices: [] },
+        {
+          name: 'Consumer',
+          id: 'consumer-1',
+          slices: [
+            {
+              name: 'test',
+              type: 'command',
+              client: { specs: [] },
+              server: {
+                description: 'Test',
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'Test',
+                    rules: [
+                      {
+                        name: 'rule',
+                        examples: [
+                          {
+                            name: 'example',
+                            steps: [{ keyword: 'Then', text: 'SharedEvent' }],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [{ type: 'event', source: 'internal', name: 'SharedEvent', fields: [] }],
+      integrations: [],
+      modules: [
+        {
+          id: 'shared',
+          sourceFile: 'shared/types.ts',
+          isDerived: false,
+          contains: { narrativeIds: ['shared-1'] },
+          declares: { messages: [{ kind: 'event', name: 'SharedEvent' }] },
+        },
+        {
+          id: 'consumer',
+          sourceFile: 'features/consumer.ts',
+          isDerived: false,
+          contains: { narrativeIds: ['consumer-1'] },
+          declares: { messages: [] },
+        },
+      ],
+    };
+
+    const consumerModule = model.modules[1];
+    const imports = computeCrossModuleImports(consumerModule, model.modules, model);
+
+    expect(imports).toEqual([{ fromPath: '../shared/types', typeNames: ['SharedEvent'] }]);
+  });
+
+  it('groups multiple types from same module into single import', () => {
+    const model: Model = {
+      variant: 'specs',
+      narratives: [
+        { name: 'Shared', id: 'shared-1', slices: [] },
+        {
+          name: 'Consumer',
+          id: 'consumer-1',
+          slices: [
+            {
+              name: 'test',
+              type: 'command',
+              client: { specs: [] },
+              server: {
+                description: 'Test',
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'Test',
+                    rules: [
+                      {
+                        name: 'rule',
+                        examples: [
+                          {
+                            name: 'example',
+                            steps: [
+                              { keyword: 'Given', text: 'EventA' },
+                              { keyword: 'Then', text: 'EventB' },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        { type: 'event', source: 'internal', name: 'EventA', fields: [] },
+        { type: 'event', source: 'internal', name: 'EventB', fields: [] },
+      ],
+      integrations: [],
+      modules: [
+        {
+          id: 'shared',
+          sourceFile: 'shared.ts',
+          isDerived: false,
+          contains: { narrativeIds: ['shared-1'] },
+          declares: {
+            messages: [
+              { kind: 'event', name: 'EventA' },
+              { kind: 'event', name: 'EventB' },
+            ],
+          },
+        },
+        {
+          id: 'consumer',
+          sourceFile: 'consumer.ts',
+          isDerived: false,
+          contains: { narrativeIds: ['consumer-1'] },
+          declares: { messages: [] },
+        },
+      ],
+    };
+
+    const consumerModule = model.modules[1];
+    const imports = computeCrossModuleImports(consumerModule, model.modules, model);
+
+    expect(imports).toHaveLength(1);
+    expect(imports[0].typeNames.sort()).toEqual(['EventA', 'EventB']);
+  });
+
+  it('ignores types declared by derived modules', () => {
+    const model: Model = {
+      variant: 'specs',
+      narratives: [
+        {
+          name: 'Consumer',
+          id: 'consumer-1',
+          slices: [
+            {
+              name: 'test',
+              type: 'command',
+              client: { specs: [] },
+              server: {
+                description: 'Test',
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'Test',
+                    rules: [
+                      {
+                        name: 'rule',
+                        examples: [
+                          {
+                            name: 'example',
+                            steps: [{ keyword: 'Then', text: 'DerivedEvent' }],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [{ type: 'event', source: 'internal', name: 'DerivedEvent', fields: [] }],
+      integrations: [],
+      modules: [
+        {
+          id: 'derived.ts',
+          sourceFile: 'derived.ts',
+          isDerived: true,
+          contains: { narrativeIds: [] },
+          declares: { messages: [{ kind: 'event', name: 'DerivedEvent' }] },
+        },
+        {
+          id: 'consumer',
+          sourceFile: 'consumer.ts',
+          isDerived: false,
+          contains: { narrativeIds: ['consumer-1'] },
+          declares: { messages: [] },
+        },
+      ],
+    };
+
+    const consumerModule = model.modules[1];
+    const imports = computeCrossModuleImports(consumerModule, model.modules, model);
+
+    expect(imports).toEqual([]);
+  });
+
+  it('sorts imports by source path', () => {
+    const model: Model = {
+      variant: 'specs',
+      narratives: [
+        { name: 'Types1', id: 'types-1', slices: [] },
+        { name: 'Types2', id: 'types-2', slices: [] },
+        {
+          name: 'Consumer',
+          id: 'consumer-1',
+          slices: [
+            {
+              name: 'test',
+              type: 'command',
+              client: { specs: [] },
+              server: {
+                description: 'Test',
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'Test',
+                    rules: [
+                      {
+                        name: 'rule',
+                        examples: [
+                          {
+                            name: 'example',
+                            steps: [
+                              { keyword: 'Given', text: 'ZEvent' },
+                              { keyword: 'Then', text: 'AEvent' },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+        },
+      ],
+      messages: [
+        { type: 'event', source: 'internal', name: 'ZEvent', fields: [] },
+        { type: 'event', source: 'internal', name: 'AEvent', fields: [] },
+      ],
+      integrations: [],
+      modules: [
+        {
+          id: 'z-types',
+          sourceFile: 'z-types.ts',
+          isDerived: false,
+          contains: { narrativeIds: ['types-1'] },
+          declares: { messages: [{ kind: 'event', name: 'ZEvent' }] },
+        },
+        {
+          id: 'a-types',
+          sourceFile: 'a-types.ts',
+          isDerived: false,
+          contains: { narrativeIds: ['types-2'] },
+          declares: { messages: [{ kind: 'event', name: 'AEvent' }] },
+        },
+        {
+          id: 'consumer',
+          sourceFile: 'consumer.ts',
+          isDerived: false,
+          contains: { narrativeIds: ['consumer-1'] },
+          declares: { messages: [] },
+        },
+      ],
+    };
+
+    const consumerModule = model.modules[2];
+    const imports = computeCrossModuleImports(consumerModule, model.modules, model);
+
+    expect(imports.map((i) => i.fromPath)).toEqual(['./a-types', './z-types']);
+  });
+});

package/src/transformers/model-to-narrative/cross-module-imports.ts

@@ -0,0 +1,83 @@
+import path from 'node:path';
+import type { Model, Module } from '../../index';
+import { parseMessageKey, sortImportsBySource, toMessageKey } from './ordering';
+import { collectMessageKeysFromNarratives } from './spec-traversal';
+import type { CrossModuleImport } from './types';
+
+export type { CrossModuleImport };
+
+export function computeCrossModuleImports(module: Module, allModules: Module[], model: Model): CrossModuleImport[] {
+  if (module.isDerived) {
+    return [];
+  }
+
+  const declaredKeys = new Set(module.declares.messages.map((m) => toMessageKey(m.kind, m.name)));
+  const usedKeys = collectUsedMessageKeysForModule(module, model);
+  const neededKeys = new Set([...usedKeys].filter((k) => !declaredKeys.has(k)));
+
+  if (neededKeys.size === 0) {
+    return [];
+  }
+
+  const importsByModule = new Map<string, string[]>();
+
+  for (const msgKey of neededKeys) {
+    const { name } = parseMessageKey(msgKey);
+    const declaringModule = findDeclaringModule(msgKey, allModules, module);
+
+    if (declaringModule) {
+      const modulePath = declaringModule.sourceFile;
+      if (!importsByModule.has(modulePath)) {
+        importsByModule.set(modulePath, []);
+      }
+      importsByModule.get(modulePath)!.push(name);
+    }
+  }
+
+  const imports: CrossModuleImport[] = [];
+  for (const [modulePath, typeNames] of importsByModule) {
+    const relativePath = resolveRelativeImport(module.sourceFile, modulePath);
+    imports.push({ fromPath: relativePath, typeNames });
+  }
+
+  return sortImportsBySource(imports);
+}
+
+export function resolveRelativeImport(fromPath: string, toPath: string): string {
+  const fromDir = path.dirname(fromPath);
+  const toDir = path.dirname(toPath);
+  const toFile = path.basename(toPath, path.extname(toPath));
+
+  const relativePath = path.relative(fromDir, toDir);
+  if (relativePath === '') {
+    return `./${toFile}`;
+  }
+  if (!relativePath.startsWith('.')) {
+    return `./${relativePath}/${toFile}`.replace(/\\/g, '/');
+  }
+
+  return path.join(relativePath, toFile).replace(/\\/g, '/');
+}
+
+function collectUsedMessageKeysForModule(module: Module, model: Model): Set<string> {
+  const narrativeIds = new Set(module.contains.narrativeIds);
+  const narratives = model.narratives.filter((n) => n.id && narrativeIds.has(n.id));
+
+  const usedKeys = collectMessageKeysFromNarratives(narratives);
+
+  const modelKeys = new Set(model.messages.map((m) => toMessageKey(m.type, m.name)));
+  return new Set([...usedKeys].filter((k) => modelKeys.has(k)));
+}
+
+function findDeclaringModule(messageKey: string, allModules: Module[], currentModule: Module): Module | undefined {
+  const authoredModules = allModules.filter((m) => !m.isDerived && m.id !== currentModule.id);
+
+  for (const mod of authoredModules) {
+    const declares = mod.declares.messages.some((m) => toMessageKey(m.kind, m.name) === messageKey);
+    if (declares) {
+      return mod;
+    }
+  }
+
+  return undefined;
+}

package/src/transformers/model-to-narrative/generators/flow.ts

@@ -1,27 +1,28 @@
 import type tsNS from 'typescript';
 import type { z } from 'zod';
+import type {
+  CommandSlice as CommandSliceType,
+  ExperienceSlice as ExperienceSliceType,
+  Narrative,
+  QuerySlice as QuerySliceType,
+  ReactSlice as ReactSliceType,
+} from '../../../index';
 import type {
   ClientSpecNode,
-  CommandSliceSchema,
   DataSinkSchema,
   DataSourceSchema,
   DestinationSchema,
   ExampleSchema,
-  ExperienceSliceSchema,
-  NarrativeSchema,
   OriginSchema,
-  QuerySliceSchema,
-  ReactSliceSchema,
 } from '../../../schema';
 import { jsonToExpr } from '../ast/emit-helpers';
 import { buildConsolidatedGwtSpecBlock, type GWTBlock } from './gwt';
 
-type CommandSlice = z.infer<typeof CommandSliceSchema>;
-type QuerySlice = z.infer<typeof QuerySliceSchema>;
-type ReactSlice = z.infer<typeof ReactSliceSchema>;
-type ExperienceSlice = z.infer<typeof ExperienceSliceSchema>;
+type CommandSlice = CommandSliceType;
+type QuerySlice = QuerySliceType;
+type ReactSlice = ReactSliceType;
+type ExperienceSlice = ExperienceSliceType;
 type Example = z.infer<typeof ExampleSchema>;
-type Narrative = z.infer<typeof NarrativeSchema>;
 type DataSinkItem = z.infer<typeof DataSinkSchema>;
 type DataSourceItem = z.infer<typeof DataSourceSchema>;
 type Destination = z.infer<typeof DestinationSchema>;