@auto-engineer/narrative 0.11.11

package/src/transformers/narrative-to-model/type-inference.specs.ts

@@ -0,0 +1,176 @@
+import { describe, it, expect } from 'vitest';
+import { narrativesToModel } from './index';
+import type { Narrative } from '../../index';
+
+describe('Type inference in narrative-to-model transformer', () => {
+  it('should correctly extract command types from when clauses', () => {
+    const flows: Narrative[] = [
+      {
+        name: 'Test Flow',
+        id: 'FLOW-001',
+        slices: [
+          {
+            id: 'SLICE-001',
+            type: 'command',
+            name: 'Submit Answer Command',
+            client: { description: 'Submit answer client' },
+            server: {
+              description: 'Submit answer server',
+              specs: {
+                name: 'Submit Answer Specs',
+                rules: [
+                  {
+                    id: 'RULE-001',
+                    description: 'Should accept answer submission',
+                    examples: [
+                      {
+                        description: 'Valid answer submission',
+                        when: [
+                          {
+                            commandRef: 'AnswerQuestion',
+                            exampleData: {
+                              questionnaireId: 'q-001',
+                              participantId: 'participant-abc',
+                              questionId: 'q1',
+                              answer: 'Yes',
+                            },
+                          },
+                        ],
+                        then: [
+                          {
+                            eventRef: 'QuestionAnswered',
+                            exampleData: {
+                              questionnaireId: 'q-001',
+                              participantId: 'participant-abc',
+                              questionId: 'q1',
+                              answer: 'Yes',
+                              savedAt: new Date(),
+                            },
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          },
+          {
+            id: 'SLICE-002',
+            type: 'command',
+            name: 'Submit Questionnaire Command',
+            client: { description: 'Submit questionnaire client' },
+            server: {
+              description: 'Submit questionnaire server',
+              specs: {
+                name: 'Submit Questionnaire Specs',
+                rules: [
+                  {
+                    id: 'RULE-002',
+                    description: 'Should submit questionnaire',
+                    examples: [
+                      {
+                        description: 'Valid questionnaire submission',
+                        when: [
+                          {
+                            commandRef: 'SubmitQuestionnaire',
+                            exampleData: {
+                              questionnaireId: 'q-001',
+                              participantId: 'participant-abc',
+                            },
+                          },
+                        ],
+                        then: [
+                          {
+                            eventRef: 'QuestionnaireSubmitted',
+                            exampleData: {
+                              questionnaireId: 'q-001',
+                              participantId: 'participant-abc',
+                              submittedAt: new Date(),
+                            },
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          },
+        ],
+      },
+    ];
+
+    const model = narrativesToModel(flows);
+
+    // Should have the correct command messages extracted
+    expect(model.messages.some((msg) => msg.name === 'AnswerQuestion')).toBe(true);
+    expect(model.messages.some((msg) => msg.name === 'SubmitQuestionnaire')).toBe(true);
+    expect(model.messages.some((msg) => msg.name === 'QuestionAnswered')).toBe(true);
+    expect(model.messages.some((msg) => msg.name === 'QuestionnaireSubmitted')).toBe(true);
+
+    // Should NOT have InferredType fallback
+    expect(model.messages.some((msg) => msg.name === 'InferredType')).toBe(false);
+
+    // Verify the command messages have the correct structure
+    const answerQuestionMsg = model.messages.find((msg) => msg.name === 'AnswerQuestion');
+    expect(answerQuestionMsg?.type).toBe('command');
+    expect(answerQuestionMsg?.fields).toBeDefined();
+
+    const submitQuestionnaireMsg = model.messages.find((msg) => msg.name === 'SubmitQuestionnaire');
+    expect(submitQuestionnaireMsg?.type).toBe('command');
+    expect(submitQuestionnaireMsg?.fields).toBeDefined();
+  });
+
+  it('should handle single object when/then clauses correctly', () => {
+    const flows: Narrative[] = [
+      {
+        name: 'Single Object Flow',
+        id: 'FLOW-001',
+        slices: [
+          {
+            id: 'SLICE-001',
+            type: 'command',
+            name: 'Single Object Command',
+            client: { description: 'Single object client' },
+            server: {
+              description: 'Single object server',
+              specs: {
+                name: 'Single Object Specs',
+                rules: [
+                  {
+                    id: 'RULE-001',
+                    description: 'Should handle single object',
+                    examples: [
+                      {
+                        description: 'Single object example',
+                        // Single object, not array - this is what broke
+                        when: {
+                          commandRef: 'TestCommand',
+                          exampleData: { test: 'value' },
+                        },
+                        then: [
+                          {
+                            eventRef: 'TestEvent',
+                            exampleData: { result: 'success' },
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          },
+        ],
+      },
+    ];
+
+    const model = narrativesToModel(flows);
+
+    // Should extract the command and event types from single objects
+    expect(model.messages.some((msg) => msg.name === 'TestCommand')).toBe(true);
+    expect(model.messages.some((msg) => msg.name === 'TestEvent')).toBe(true);
+    expect(model.messages.some((msg) => msg.name === 'InferredType')).toBe(false);
+  });
+});

package/src/transformers/narrative-to-model/type-inference.ts

@@ -0,0 +1,127 @@
+import { TypeInfo } from '../../loader/ts-utils';
+
+function tryDataFieldMatch(typeInfo: TypeInfo, dataKeys: Set<string>): boolean {
+  const dataField = typeInfo.dataFields?.find((f) => f.name === 'data');
+  if (
+    dataField &&
+    typeof dataField.type === 'string' &&
+    dataField.type.startsWith('{') &&
+    dataField.type.endsWith('}')
+  ) {
+    const bodyMatch = dataField.type.match(/^\{\s*([^}]*)\s*\}$/);
+    if (bodyMatch && bodyMatch[1]) {
+      const body = bodyMatch[1];
+      const innerKeys = new Set<string>();
+      const re = /(\w+)(\?)?\s*:\s*([^;,]+)(?=[;,]|$)/g;
+      let m: RegExpExecArray | null;
+      while ((m = re.exec(body)) !== null) {
+        innerKeys.add(m[1]);
+      }
+
+      return dataKeys.size > 0 && Array.from(dataKeys).every((key) => innerKeys.has(key));
+    }
+  }
+  return false;
+}
+
+function tryTopLevelMatch(typeInfo: TypeInfo, dataKeys: Set<string>): boolean {
+  if (typeInfo.dataFields && typeInfo.dataFields.length > 0) {
+    const typeKeys = new Set(typeInfo.dataFields.map((f) => f.name));
+    if (dataKeys.size > 0 && typeKeys.size > 0) {
+      return dataKeys.size <= typeKeys.size && Array.from(dataKeys).every((key) => typeKeys.has(key));
+    }
+  }
+  return false;
+}
+
+function tryMatchCandidates(candidates: TypeInfo[], dataKeys: Set<string>): string | null {
+  let bestMatch: TypeInfo | null = null;
+  let bestScore = -1;
+
+  for (const typeInfo of candidates) {
+    if (typeInfo.dataFields && typeInfo.dataFields.length > 0) {
+      const dataFieldMatch = tryDataFieldMatch(typeInfo, dataKeys);
+      const topLevelMatch = tryTopLevelMatch(typeInfo, dataKeys);
+
+      if (dataFieldMatch || topLevelMatch) {
+        // Calculate a score: higher is better
+        // Exact field count match gets higher score than partial match
+        const typeKeys = new Set(typeInfo.dataFields.map((f) => f.name));
+        const isExactMatch = dataKeys.size === typeKeys.size;
+        const score = isExactMatch ? 100 : 50; // Prefer exact matches
+
+        if (score > bestScore) {
+          bestScore = score;
+          bestMatch = typeInfo;
+        }
+      }
+    }
+  }
+
+  return bestMatch?.stringLiteral ?? null;
+}
+
+function tryResolveByExampleData(
+  candidates: TypeInfo[],
+  all: TypeInfo[],
+  expectedMessageType: 'command' | 'event' | 'state' | undefined,
+  exampleData: unknown,
+): string | null {
+  if (exampleData === null || typeof exampleData !== 'object' || exampleData === undefined) {
+    return null;
+  }
+
+  const dataKeys = new Set(Object.keys(exampleData));
+  const match = tryMatchCandidates(candidates, dataKeys);
+  if (match !== null) return match;
+
+  if (expectedMessageType !== undefined) {
+    const fallbackMatch = tryMatchCandidates(all, dataKeys);
+    if (fallbackMatch !== null) return fallbackMatch;
+  }
+
+  return null;
+}
+
+function tryResolveByExpectedType(
+  candidates: TypeInfo[],
+  expectedMessageType: 'command' | 'event' | 'state' | undefined,
+): string | null {
+  if (!expectedMessageType || candidates.length === 0) {
+    return null;
+  }
+
+  const typeMatchedCandidate = candidates.find((c) => c.classification === expectedMessageType);
+  return typeMatchedCandidate ? typeMatchedCandidate.stringLiteral : null;
+}
+
+function resolveFromCandidates(
+  candidates: TypeInfo[],
+  all: TypeInfo[],
+  expectedMessageType?: 'command' | 'event' | 'state',
+  exampleData?: unknown,
+): string | null {
+  if (candidates.length === 1) return candidates[0].stringLiteral;
+
+  const exampleMatch = tryResolveByExampleData(candidates, all, expectedMessageType, exampleData);
+  if (exampleMatch !== null) return exampleMatch;
+
+  return tryResolveByExpectedType(candidates, expectedMessageType);
+}
+
+export function resolveInferredType(
+  typeName: string,
+  flowTypeMap?: Map<string, TypeInfo>,
+  expectedMessageType?: 'command' | 'event' | 'state',
+  exampleData?: unknown,
+): string {
+  if (typeName !== 'InferredType' || flowTypeMap === undefined) return typeName;
+
+  const all = [...flowTypeMap.values()];
+  if (all.length === 0) return typeName;
+
+  const candidates = expectedMessageType ? all.filter((t) => t.classification === expectedMessageType) : all;
+
+  const resolved = resolveFromCandidates(candidates, all, expectedMessageType, exampleData);
+  return resolved ?? typeName;
+}

package/src/transformers/narrative-to-model/zod-adapter.ts

@@ -0,0 +1,110 @@
+import { z } from 'zod';
+import { Message } from '../../index';
+
+function hasZodDef(obj: unknown): obj is { _def: unknown } {
+  return typeof obj === 'object' && obj !== null && '_def' in obj;
+}
+
+export const unwrapZod = (schema: z.ZodTypeAny): z.ZodTypeAny => {
+  let s = schema as unknown as Record<string, unknown>;
+  // Unwrap common wrappers: Optional, Nullable, Default, Effects
+  // Keep unwrapping until we hit a non-wrapper
+  while (hasZodDef(s)) {
+    const def = s._def as Record<string, unknown>;
+    const typeName = def.typeName;
+
+    if (
+      typeName === 'ZodOptional' ||
+      typeName === 'ZodNullable' ||
+      typeName === 'ZodDefault' ||
+      typeName === 'ZodEffects'
+    ) {
+      if (def.innerType !== undefined) {
+        s = def.innerType as Record<string, unknown>;
+      } else if (def.schema !== undefined) {
+        s = def.schema as Record<string, unknown>;
+      } else {
+        break;
+      }
+    } else {
+      break;
+    }
+  }
+  return s as z.ZodTypeAny;
+};
+
+function handleZodLiteral(base: z.ZodTypeAny): string {
+  if (!hasZodDef(base)) return 'unknown';
+  const def = base._def as Record<string, unknown>;
+  const val = def.value;
+  return typeof val === 'string' ? JSON.stringify(val) : JSON.stringify(val);
+}
+
+function handleZodArray(base: z.ZodTypeAny): string {
+  const elementType = extractZodType((base as z.ZodArray<z.ZodTypeAny>)._def.type);
+  return `Array<${elementType}>`;
+}
+
+function handleZodObject(base: z.ZodTypeAny): string {
+  const shape = (base as z.ZodObject<z.ZodRawShape>)._def.shape();
+  const entries = Object.entries(shape)
+    .map(([key, val]) => `${key}: ${extractZodType(val)}`)
+    .join(', ');
+  return `{${entries}}`;
+}
+
+function handleZodNullable(base: z.ZodTypeAny): string {
+  const inner = extractZodType((base as z.ZodNullable<z.ZodTypeAny>)._def.innerType);
+  return `${inner} | null`;
+}
+
+export const extractZodType = (schema: z.ZodTypeAny): string => {
+  const base = unwrapZod(schema);
+  if (!hasZodDef(base)) return 'unknown';
+  const def = base._def as Record<string, unknown>;
+  const typeName = def.typeName as string | undefined;
+
+  switch (typeName) {
+    case 'ZodString':
+      return 'string';
+    case 'ZodNumber':
+      return 'number';
+    case 'ZodBoolean':
+      return 'boolean';
+    case 'ZodDate':
+      return 'Date';
+    case 'ZodLiteral':
+      return handleZodLiteral(base);
+    case 'ZodArray':
+      return handleZodArray(base);
+    case 'ZodObject':
+      return handleZodObject(base);
+    case 'ZodNullable':
+      return handleZodNullable(base);
+    default:
+      return 'unknown';
+  }
+};
+
+export const zodSchemaToFields = (schema: z.ZodTypeAny): Message['fields'] => {
+  const base = unwrapZod(schema);
+  if (!hasZodDef(base)) return [];
+  const def = base._def as Record<string, unknown>;
+  if (def.typeName !== 'ZodObject') return [];
+
+  const shape = (base as z.ZodObject<z.ZodRawShape>)._def.shape();
+
+  return Object.entries(shape).map(([name, field]) => {
+    const unwrapped = unwrapZod(field);
+    // treat Optional/Nullable/Default as not required
+    const fieldWithDef = field;
+    const raw = hasZodDef(fieldWithDef) ? (fieldWithDef._def as Record<string, unknown>).typeName : undefined;
+    const required = raw !== 'ZodOptional' && raw !== 'ZodNullable' && raw !== 'ZodDefault';
+
+    return {
+      name,
+      type: extractZodType(unwrapped),
+      required,
+    };
+  });
+};

package/src/types.ts

@@ -0,0 +1,226 @@
+import { ZodTypeAny } from 'zod';
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+type IntegrationHandler = (...args: any[]) => Promise<any>;
+
+// Enhanced WithSchema type that includes schemas for each handler
+type WithSchema<T extends Record<string, IntegrationHandler>> = T & {
+  schema?: {
+    [K in keyof T]?: ZodTypeAny;
+  };
+};
+
+export interface Integration<
+  Type extends string = string,
+  Q extends Record<string, IntegrationHandler> = Record<string, IntegrationHandler>,
+  C extends Record<string, IntegrationHandler> = Record<string, IntegrationHandler>,
+  R extends Record<string, IntegrationHandler> = Record<string, IntegrationHandler>,
+> {
+  readonly __brand: 'Integration';
+  readonly type: Type;
+  readonly name: string;
+  readonly exportName?: string; // The name used when exporting this integration
+  readonly Queries?: WithSchema<Q>;
+  readonly Commands?: WithSchema<C>;
+  readonly Reactions?: WithSchema<R>;
+}
+
+export const createIntegration = <T extends string>(type: T, name: string): Integration<T> =>
+  ({
+    __brand: 'Integration' as const,
+    type,
+    name,
+  }) as Integration<T>;
+
+/**
+ * Helper function to set the export name on an integration
+ */
+export function withExportName<T extends Integration>(integration: T, exportName: string): T {
+  return {
+    ...integration,
+    exportName,
+  };
+}
+
+// Data flow types (keeping existing types)
+export interface MessageTarget {
+  type: 'Event' | 'Command' | 'State';
+  name: string;
+  fields?: Record<string, unknown>;
+}
+
+export interface StreamDestination {
+  type: 'stream';
+  pattern: string;
+}
+
+export interface IntegrationDestination {
+  type: 'integration';
+  systems: string[];
+  message?: {
+    name: string;
+    type: 'command' | 'query' | 'reaction';
+  };
+}
+
+export interface DatabaseDestination {
+  type: 'database';
+  collection: string;
+}
+
+export interface TopicDestination {
+  type: 'topic';
+  name: string;
+}
+
+export type Destination = StreamDestination | IntegrationDestination | DatabaseDestination | TopicDestination;
+
+// Helper functions to create destinations
+export const createStreamDestination = (pattern: string): StreamDestination => ({ type: 'stream', pattern });
+export const createIntegrationDestination = (systems: string[]): IntegrationDestination => ({
+  type: 'integration',
+  systems,
+});
+export const createDatabaseDestination = (collection: string): DatabaseDestination => ({
+  type: 'database',
+  collection,
+});
+export const createTopicDestination = (name: string): TopicDestination => ({ type: 'topic', name });
+
+export interface ProjectionOrigin {
+  type: 'projection';
+  name: string;
+}
+
+export interface ReadModelOrigin {
+  type: 'readModel';
+  name: string;
+}
+
+export interface DatabaseOrigin {
+  type: 'database';
+  collection: string;
+  query?: Record<string, unknown>;
+}
+
+export interface ApiOrigin {
+  type: 'api';
+  endpoint: string;
+  method?: string;
+}
+
+export interface IntegrationOrigin {
+  type: 'integration';
+  systems: string[];
+}
+
+export type Origin = ProjectionOriginWithId | ReadModelOrigin | DatabaseOrigin | ApiOrigin | IntegrationOrigin;
+
+export interface ProjectionOriginWithId {
+  type: 'projection';
+  name: string;
+  idField: string;
+}
+
+// Helper functions to create origins
+export const createProjectionOrigin = (name: string): ProjectionOrigin => ({ type: 'projection', name });
+export const createReadModelOrigin = (name: string): ReadModelOrigin => ({ type: 'readModel', name });
+export const createDatabaseOrigin = (collection: string, query?: Record<string, unknown>): DatabaseOrigin => ({
+  type: 'database',
+  collection,
+  query,
+});
+export const createApiOrigin = (endpoint: string, method?: string): ApiOrigin => ({ type: 'api', endpoint, method });
+export const createIntegrationOrigin = (systems: string[]): IntegrationOrigin => ({ type: 'integration', systems });
+
+export interface DataSink {
+  target: MessageTarget;
+  destination: Destination;
+  transform?: string;
+  _additionalInstructions?: string;
+  _withState?: DataSource;
+}
+
+export interface DataSource {
+  target: MessageTarget;
+  origin: Origin;
+  transform?: string;
+  _additionalInstructions?: string;
+}
+
+// Branded types for type safety in arrays
+export interface DataSinkItem extends DataSink {
+  readonly __type: 'sink';
+}
+
+export interface DataSourceItem extends DataSource {
+  readonly __type: 'source';
+}
+
+export interface DataItem {
+  __type: 'sink' | 'source';
+}
+
+type DefaultRecord = Record<string, unknown>;
+
+export type State<
+  StateType extends string = string,
+  StateData extends DefaultRecord = DefaultRecord,
+  EventMetaData extends DefaultRecord | undefined = undefined,
+> = Readonly<
+  EventMetaData extends undefined
+    ? {
+        type: StateType;
+        data: StateData;
+      }
+    : {
+        type: StateType;
+        data: StateData;
+        metadata: EventMetaData;
+      }
+> & {
+  readonly kind?: 'State';
+};
+
+export interface DefaultCommandMetadata extends Record<string, unknown> {
+  now: Date;
+}
+
+export type Command<
+  CommandType extends string = string,
+  CommandData extends DefaultRecord = DefaultRecord,
+  CommandMetaData extends DefaultRecord | undefined = undefined,
+> = Readonly<
+  CommandMetaData extends undefined
+    ? {
+        type: CommandType;
+        data: Readonly<CommandData>;
+        metadata?: DefaultCommandMetadata | undefined;
+      }
+    : {
+        type: CommandType;
+        data: CommandData;
+        metadata: CommandMetaData;
+      }
+> & {
+  readonly kind?: 'Command';
+};
+
+export type Event<
+  EventType extends string = string,
+  EventData extends DefaultRecord = DefaultRecord,
+  EventMetaData extends DefaultRecord | undefined = undefined,
+> = Readonly<
+  EventMetaData extends undefined
+    ? {
+        type: EventType;
+        data: EventData;
+      }
+    : {
+        type: EventType;
+        data: EventData;
+        metadata: EventMetaData;
+      }
+> & {
+  readonly kind?: 'Event';
+};

package/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "types": ["vitest/globals", "node"],
+    "lib": ["ES2022", "DOM"],
+    "composite": true
+  },
+  "include": ["src/**/*", "bin/**/*", "scripts/*.ts", "src/**/*.json"],
+  "exclude": ["node_modules", "dist"]
+}

package/tsconfig.test.json

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