@auto-engineer/narrative 0.16.0 → 0.17.0

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

@@ -0,0 +1,159 @@
+import type { Model } from '../../index';
+import { toMessageKey } from './ordering';
+
+export interface ValidationError {
+  type:
+    | 'duplicate_id'
+    | 'derived_id_mismatch'
+    | 'narrative_unassigned'
+    | 'narrative_multi_assigned'
+    | 'message_multi_declared'
+    | 'message_undeclared'
+    | 'narrative_not_found';
+  message: string;
+}
+
+export function validateModules(model: Model): ValidationError[] {
+  const errors: ValidationError[] = [];
+  const modules = model.modules ?? [];
+
+  if (modules.length === 0) {
+    return errors;
+  }
+
+  errors.push(...validateUniqueModuleIds(modules));
+  errors.push(...validateDerivedModuleIds(modules));
+
+  const authoredModules = modules.filter((m) => !m.isDerived);
+  if (authoredModules.length === 0) {
+    return errors;
+  }
+
+  errors.push(...validateNarrativeAssignments(authoredModules, model));
+  errors.push(...validateMessageDeclarations(authoredModules, model));
+
+  return errors;
+}
+
+function validateUniqueModuleIds(modules: Model['modules']): ValidationError[] {
+  const errors: ValidationError[] = [];
+  const idCounts = new Map<string, number>();
+
+  for (const module of modules) {
+    idCounts.set(module.id, (idCounts.get(module.id) ?? 0) + 1);
+  }
+
+  for (const [id, count] of idCounts) {
+    if (count > 1) {
+      errors.push({
+        type: 'duplicate_id',
+        message: `Module ID '${id}' is used by ${count} modules`,
+      });
+    }
+  }
+
+  return errors;
+}
+
+function validateDerivedModuleIds(modules: Model['modules']): ValidationError[] {
+  const errors: ValidationError[] = [];
+
+  for (const module of modules) {
+    if (module.isDerived && module.id !== module.sourceFile) {
+      errors.push({
+        type: 'derived_id_mismatch',
+        message: `Derived module ID '${module.id}' must equal sourceFile '${module.sourceFile}'`,
+      });
+    }
+  }
+
+  return errors;
+}
+
+function validateNarrativeAssignments(authoredModules: Model['modules'], model: Model): ValidationError[] {
+  const errors: ValidationError[] = [];
+  const narrativeAssignments = new Map<string, string[]>();
+
+  for (const module of authoredModules) {
+    for (const narrativeId of module.contains.narrativeIds) {
+      if (!narrativeAssignments.has(narrativeId)) {
+        narrativeAssignments.set(narrativeId, []);
+      }
+      narrativeAssignments.get(narrativeId)!.push(module.id);
+    }
+  }
+
+  const modelNarrativeIds = new Set(model.narratives.map((n) => n.id).filter((id): id is string => id !== undefined));
+
+  for (const [narrativeId, moduleIds] of narrativeAssignments) {
+    if (!modelNarrativeIds.has(narrativeId)) {
+      errors.push({
+        type: 'narrative_not_found',
+        message: `Narrative '${narrativeId}' referenced by module(s) [${moduleIds.join(', ')}] does not exist`,
+      });
+    }
+    if (moduleIds.length > 1) {
+      errors.push({
+        type: 'narrative_multi_assigned',
+        message: `Narrative '${narrativeId}' is assigned to multiple modules: [${moduleIds.join(', ')}]`,
+      });
+    }
+  }
+
+  const assignedNarrativeIds = new Set(narrativeAssignments.keys());
+  for (const narrative of model.narratives) {
+    if (narrative.id && !assignedNarrativeIds.has(narrative.id)) {
+      errors.push({
+        type: 'narrative_unassigned',
+        message: `Narrative '${narrative.id}' (${narrative.name}) is not assigned to any module`,
+      });
+    }
+  }
+
+  return errors;
+}
+
+function validateMessageDeclarations(authoredModules: Model['modules'], model: Model): ValidationError[] {
+  const errors: ValidationError[] = [];
+  const messageDeclarations = new Map<string, string[]>();
+
+  for (const module of authoredModules) {
+    for (const msg of module.declares.messages) {
+      const key = toMessageKey(msg.kind, msg.name);
+      if (!messageDeclarations.has(key)) {
+        messageDeclarations.set(key, []);
+      }
+      messageDeclarations.get(key)!.push(module.id);
+    }
+  }
+
+  for (const [msgKey, moduleIds] of messageDeclarations) {
+    if (moduleIds.length > 1) {
+      errors.push({
+        type: 'message_multi_declared',
+        message: `Message '${msgKey}' is declared by multiple modules: [${moduleIds.join(', ')}]`,
+      });
+    }
+  }
+
+  const declaredMessages = new Set(messageDeclarations.keys());
+  const modelMessageKeys = new Set(model.messages.map((m) => toMessageKey(m.type, m.name)));
+
+  for (const msgKey of modelMessageKeys) {
+    if (!declaredMessages.has(msgKey)) {
+      errors.push({
+        type: 'message_undeclared',
+        message: `Message '${msgKey}' exists in model but is not declared by any authored module`,
+      });
+    }
+  }
+
+  return errors;
+}
+
+export function throwOnValidationErrors(errors: ValidationError[]): void {
+  if (errors.length > 0) {
+    const messages = errors.map((e) => `  - ${e.message}`).join('\n');
+    throw new Error(`Module validation failed:\n${messages}`);
+  }
+}

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

@@ -1,10 +1,15 @@
-import type { Model, Narrative } from '../../index';
+import type { Message, Model, Narrative } from '../../index';
+import { deriveModules } from './derive-modules';
 
 export function assembleSpecs(narratives: Narrative[], messages: unknown[], integrations: unknown[]): Model {
+  const typedMessages = messages as Message[];
+  const modules = deriveModules(narratives, typedMessages);
+
   return {
     variant: 'specs' as const,
     narratives,
-    messages: messages as Model['messages'],
+    messages: typedMessages,
     integrations: integrations as Model['integrations'],
+    modules,
   };
 }

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

@@ -0,0 +1,121 @@
+import { describe, expect, it } from 'vitest';
+import type { Message, Narrative } 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: [] },
+    ];
+    const messages: Message[] = [];
+
+    const modules = deriveModules(narratives, 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: [] }];
+    const messages: Message[] = [];
+
+    const modules = deriveModules(narratives, messages);
+
+    expect(modules).toHaveLength(1);
+    expect(modules[0].sourceFile).toBe('generated.narrative.ts');
+    expect(modules[0].id).toBe('generated.narrative.ts');
+  });
+
+  it('generates synthetic narrative IDs when narratives have no ID', () => {
+    const narratives: Narrative[] = [
+      { name: 'First', slices: [] },
+      { name: 'Second', slices: [] },
+    ];
+    const messages: Message[] = [];
+
+    const modules = deriveModules(narratives, messages);
+
+    expect(modules).toHaveLength(1);
+    expect(modules[0].contains.narrativeIds).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 messages: Message[] = [];
+
+    const modules = deriveModules(narratives, 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 messages: Message[] = [
+      { type: 'command', name: 'CreateOrder', fields: [] },
+      { type: 'event', source: 'internal', name: 'OrderCreated', fields: [] },
+    ];
+
+    const modules = deriveModules(narratives, messages);
+
+    for (const mod of modules) {
+      expect(mod.declares.messages).toEqual([
+        { kind: 'command', name: 'CreateOrder' },
+        { kind: 'event', name: 'OrderCreated' },
+      ]);
+    }
+  });
+
+  it('sorts declared messages by kind:name', () => {
+    const narratives: Narrative[] = [{ name: 'Test', id: 'test-1', slices: [] }];
+    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);
+
+    expect(modules[0].declares.messages).toEqual([
+      { kind: 'command', name: 'ACommand' },
+      { kind: 'event', name: 'MEvent' },
+      { kind: 'state', name: 'ZState' },
+    ]);
+  });
+
+  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 messages: Message[] = [{ type: 'event', source: 'internal', name: 'SharedEvent', fields: [] }];
+
+    const modules = deriveModules(narratives, 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', () => {
+    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: [] },
+    ];
+    const messages: Message[] = [];
+
+    const modules = deriveModules(narratives, messages);
+
+    expect(modules).toHaveLength(1);
+    expect(modules[0].contains.narrativeIds).toEqual(['flow-1', 'flow-2', 'flow-3']);
+  });
+});

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

@@ -0,0 +1,36 @@
+import type { Message, Module, Narrative } from '../../index';
+
+const DEFAULT_SOURCE_FILE = 'generated.narrative.ts';
+
+export function deriveModules(narratives: Narrative[], messages: Message[]): Module[] {
+  const bySourceFile = groupNarrativesBySourceFile(narratives);
+
+  return Array.from(bySourceFile.entries()).map(([sourceFile, narrs], index) => {
+    const narrativeIds = narrs.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}`));
+
+    return {
+      id: sourceFile,
+      sourceFile,
+      isDerived: true,
+      contains: { narrativeIds },
+      declares: { messages: messageRefs },
+    };
+  });
+}
+
+function groupNarrativesBySourceFile(narratives: Narrative[]): Map<string, Narrative[]> {
+  const groups = new Map<string, Narrative[]>();
+
+  for (const narrative of narratives) {
+    const sourceFile = narrative.sourceFile ?? DEFAULT_SOURCE_FILE;
+    if (!groups.has(sourceFile)) {
+      groups.set(sourceFile, []);
+    }
+    groups.get(sourceFile)!.push(narrative);
+  }
+
+  return groups;
+}

package/tsconfig.test.json

@@ -2,8 +2,9 @@
   "extends": "./tsconfig.json",
   "compilerOptions": {
     "composite": false,
+    "rootDir": ".",
     "types": ["vitest/globals", "node"]
   },
-  "include": ["src/**/*", "**/*.specs.ts", "**/*.spec.ts", "**/*.test.ts"],
+  "include": ["src/**/*"],
   "exclude": ["node_modules", "dist"]
 }