@auto-engineer/narrative 1.139.0 → 1.140.0

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

@@ -1,4 +1,4 @@
-import type { Message, Model, Narrative, Slice } from '../../index';
+import type { Message, Model, Moment, Scene } from '../../index';
 import { integrationExportRegistry } from '../../integration-export-registry';
 import { globalIntegrationRegistry } from '../../integration-registry';
 import type { TypeInfo } from '../../loader/ts-utils';
@@ -7,7 +7,7 @@ import { applyExampleShapeHints, type ExampleShapeHints } from './example-shapes
 import { inlineAllMessageFieldTypes } from './inlining';
 import { extractMessagesFromIntegrations, processDataItemIntegrations } from './integrations';
 import { processGiven, processThen, processWhen } from './spec-processors';
-import { matchesNarrativePattern } from './strings';
+import { matchesScenePattern } from './strings';
 import { buildTypeInfoFromMessages, resolveInferredType } from './type-inference';
 
 type TypeResolver = (
@@ -23,13 +23,13 @@ function buildUnionTypes(typesByFile?: Map<string, Map<string, TypeInfo>>): Map<
   return u.size ? u : undefined;
 }
 
-function getTypesForNarrative(
-  flow: Narrative,
+function getTypesForScene(
+  scene: Scene,
   typesByFile?: Map<string, Map<string, TypeInfo>>,
 ): Map<string, TypeInfo> | undefined {
   if (!typesByFile) return undefined;
 
-  const sf = (flow as Record<string, unknown>).sourceFile as string | undefined;
+  const sf = (scene as Record<string, unknown>).sourceFile as string | undefined;
   if (typeof sf === 'string') {
     const exact = typesByFile.get(sf) || typesByFile.get(sf.replace(/\\/g, '/'));
     if (exact && exact.size > 0) return exact;
@@ -37,30 +37,30 @@ function getTypesForNarrative(
 
   for (const [filePath, fileTypes] of typesByFile) {
     const fileName = filePath.toLowerCase();
-    if (matchesNarrativePattern(fileName, flow.name)) {
+    if (matchesScenePattern(fileName, scene.name)) {
       return fileTypes;
     }
   }
   return undefined;
 }
 
-function tryResolveFromNarrativeTypes(
+function tryResolveFromSceneTypes(
   t: string,
-  narrativeSpecificTypes: Map<string, TypeInfo>,
+  sceneSpecificTypes: Map<string, TypeInfo>,
   expected?: 'command' | 'event' | 'state' | 'query',
   exampleData?: unknown,
 ): { resolvedName: string; typeInfo: TypeInfo | undefined } {
   if (t !== 'InferredType') {
-    const typeInfo = narrativeSpecificTypes.get(t);
+    const typeInfo = sceneSpecificTypes.get(t);
     if (typeInfo) {
       return { resolvedName: t, typeInfo };
     }
-    const inferredName = resolveInferredType(t, narrativeSpecificTypes, expected, exampleData);
-    return { resolvedName: inferredName, typeInfo: narrativeSpecificTypes.get(inferredName) };
+    const inferredName = resolveInferredType(t, sceneSpecificTypes, expected, exampleData);
+    return { resolvedName: inferredName, typeInfo: sceneSpecificTypes.get(inferredName) };
   }
 
-  const inferredName = resolveInferredType(t, narrativeSpecificTypes, expected, exampleData);
-  return { resolvedName: inferredName, typeInfo: narrativeSpecificTypes.get(inferredName) };
+  const inferredName = resolveInferredType(t, sceneSpecificTypes, expected, exampleData);
+  return { resolvedName: inferredName, typeInfo: sceneSpecificTypes.get(inferredName) };
 }
 
 function tryFallbackToUnionTypes(
@@ -105,7 +105,7 @@ function tryResolveFromUnionTypes(
 }
 
 function createTypeResolver(
-  narrativeSpecificTypes: Map<string, TypeInfo> | undefined,
+  sceneSpecificTypes: Map<string, TypeInfo> | undefined,
   unionTypes: Map<string, TypeInfo> | undefined,
   messages: Map<string, Message>,
 ) {
@@ -116,8 +116,8 @@ function createTypeResolver(
   ): { resolvedName: string; typeInfo: TypeInfo | undefined } => {
     let result: { resolvedName: string; typeInfo: TypeInfo | undefined } | undefined;
 
-    if (narrativeSpecificTypes) {
-      const nr = tryResolveFromNarrativeTypes(t, narrativeSpecificTypes, expected, exampleData);
+    if (sceneSpecificTypes) {
+      const nr = tryResolveFromSceneTypes(t, sceneSpecificTypes, expected, exampleData);
       result = unionTypes
         ? tryFallbackToUnionTypes(t, nr.resolvedName, nr.typeInfo, unionTypes, expected, exampleData)
         : nr;
@@ -138,9 +138,9 @@ function createTypeResolver(
   };
 }
 
-function getServerSpecs(slice: Slice) {
-  if ('server' in slice && slice.server?.specs !== undefined) {
-    return slice.server.specs;
+function getServerSpecs(moment: Moment) {
+  if ('server' in moment && moment.server?.specs !== undefined) {
+    return moment.server.specs;
   }
   return undefined;
 }
@@ -164,7 +164,7 @@ function isStepWithError(step: Step): step is StepWithError {
 
 function processSteps(
   steps: Step[],
-  slice: Slice,
+  moment: Moment,
   resolveTypeAndInfo: TypeResolver,
   messages: Map<string, Message>,
   exampleShapeHints: ExampleShapeHints,
@@ -191,7 +191,7 @@ function processSteps(
     if (effectiveKeyword === 'Given') {
       processGiven([refItem], resolveTypeAndInfo, messages, exampleShapeHints);
     } else if (effectiveKeyword === 'When') {
-      processWhen([refItem], slice, resolveTypeAndInfo, messages, exampleShapeHints);
+      processWhen([refItem], moment, resolveTypeAndInfo, messages, exampleShapeHints);
     } else if (effectiveKeyword === 'Then') {
       processThen([refItem], resolveTypeAndInfo, messages, exampleShapeHints);
     }
@@ -210,7 +210,7 @@ function isSpecWithRules(spec: unknown): spec is SpecWithRules {
 
 function processRuleExamples(
   rule: { examples: Array<{ steps?: Step[] }> },
-  slice: Slice,
+  moment: Moment,
   resolveTypeAndInfo: TypeResolver,
   messages: Map<string, Message>,
   exampleShapeHints: ExampleShapeHints,
@@ -218,46 +218,46 @@ function processRuleExamples(
   if (!Array.isArray(rule.examples)) return;
   for (const example of rule.examples) {
     if (Array.isArray(example.steps)) {
-      processSteps(example.steps, slice, resolveTypeAndInfo, messages, exampleShapeHints);
+      processSteps(example.steps, moment, resolveTypeAndInfo, messages, exampleShapeHints);
     }
   }
 }
 
-function processSliceSpecs(
-  slice: Slice,
+function processMomentSpecs(
+  moment: Moment,
   resolveTypeAndInfo: TypeResolver,
   messages: Map<string, Message>,
   exampleShapeHints: ExampleShapeHints,
 ): void {
-  const serverSpecs = getServerSpecs(slice);
+  const serverSpecs = getServerSpecs(moment);
 
   if (serverSpecs === undefined || !Array.isArray(serverSpecs)) return;
 
   for (const spec of serverSpecs) {
     if (isSpecWithRules(spec)) {
       for (const rule of spec.rules) {
-        processRuleExamples(rule, slice, resolveTypeAndInfo, messages, exampleShapeHints);
+        processRuleExamples(rule, moment, resolveTypeAndInfo, messages, exampleShapeHints);
       }
     }
   }
 }
 
-function processSliceIntegrations(
-  slice: Slice,
+function processMomentIntegrations(
+  moment: Moment,
   integrations: Map<string, { name: string; description?: string; source: string }>,
   messages: Map<string, Message>,
 ): void {
   // Integrations: from data & via
-  if ('server' in slice && slice.server != null && 'data' in slice.server && slice.server.data !== undefined) {
-    const dataItems = slice.server.data.items;
+  if ('server' in moment && moment.server != null && 'data' in moment.server && moment.server.data !== undefined) {
+    const dataItems = moment.server.data.items;
     if (Array.isArray(dataItems)) {
       dataItems.forEach((d: unknown) => {
         processDataItemIntegrations(d, integrations, messages);
       });
     }
   }
-  if ('via' in slice && slice.via) {
-    slice.via.forEach((integrationName: string) => {
+  if ('via' in moment && moment.via) {
+    moment.via.forEach((integrationName: string) => {
       if (!integrations.has(integrationName)) {
         const sourcePath = integrationExportRegistry.getSourcePath(integrationName);
         if (sourcePath !== null && sourcePath !== undefined && sourcePath !== '') {
@@ -272,24 +272,24 @@ function processSliceIntegrations(
   }
 }
 
-function processNarrative(
-  flow: Narrative,
-  getNarrativeSpecificTypes: (narrative: Narrative) => Map<string, TypeInfo> | undefined,
+function processScene(
+  scene: Scene,
+  getSceneSpecificTypes: (scene: Scene) => Map<string, TypeInfo> | undefined,
   unionTypes: Map<string, TypeInfo> | undefined,
   messages: Map<string, Message>,
   integrations: Map<string, { name: string; description?: string; source: string }>,
   exampleShapeHints: ExampleShapeHints,
 ): void {
-  const narrativeSpecificTypes = getNarrativeSpecificTypes(flow);
-  const resolveTypeAndInfo = createTypeResolver(narrativeSpecificTypes, unionTypes, messages);
+  const sceneSpecificTypes = getSceneSpecificTypes(scene);
+  const resolveTypeAndInfo = createTypeResolver(sceneSpecificTypes, unionTypes, messages);
 
-  flow.slices.forEach((slice: Narrative['slices'][number]) => {
-    processSliceSpecs(slice, resolveTypeAndInfo, messages, exampleShapeHints);
-    processSliceIntegrations(slice, integrations, messages);
+  scene.moments.forEach((moment: Scene['moments'][number]) => {
+    processMomentSpecs(moment, resolveTypeAndInfo, messages, exampleShapeHints);
+    processMomentIntegrations(moment, integrations, messages);
   });
 }
 
-export const narrativesToModel = (narratives: Narrative[], typesByFile?: Map<string, Map<string, TypeInfo>>): Model => {
+export const scenesToModel = (scenes: Scene[], typesByFile?: Map<string, Map<string, TypeInfo>>): Model => {
   const messages = new Map<string, Message>();
   const integrations = new Map<
     string,
@@ -312,12 +312,12 @@ export const narrativesToModel = (narratives: Narrative[], typesByFile?: Map<str
   const unionTypes = buildUnionTypes(typesByFile);
 
   // pick the best map for a given flow
-  const getNarrativeSpecificTypes = (narrative: Narrative): Map<string, TypeInfo> | undefined => {
-    return getTypesForNarrative(narrative, typesByFile);
+  const getSceneSpecificTypes = (scene: Scene): Map<string, TypeInfo> | undefined => {
+    return getTypesForScene(scene, typesByFile);
   };
 
-  narratives.forEach((narrative) =>
-    processNarrative(narrative, getNarrativeSpecificTypes, unionTypes, messages, integrations, exampleShapeHints),
+  scenes.forEach((scene) =>
+    processScene(scene, getSceneSpecificTypes, unionTypes, messages, integrations, exampleShapeHints),
   );
   // Ensure all registered integrations are listed
   for (const integration of registeredIntegrations) {
@@ -340,5 +340,5 @@ export const narrativesToModel = (narratives: Narrative[], typesByFile?: Map<str
     inlineAllMessageFieldTypes(messages, unionTypes);
   }
 
-  return assembleSpecs(narratives, Array.from(messages.values()), Array.from(integrations.values()));
+  return assembleSpecs(scenes, Array.from(messages.values()), Array.from(integrations.values()));
 };

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

@@ -398,7 +398,7 @@ function processSingleWhen(
 
   log('DEBUG processSingleWhen:', {
     originalCommandRef,
-    sliceType: slice.type,
+    momentType: slice.type,
     expected,
     exampleData: when.exampleData,
   });

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

@@ -1,10 +1,10 @@
-export function matchesNarrativePattern(fileName: string, flowName: string): boolean {
-  const flowNameLower = flowName.toLowerCase();
+export function matchesScenePattern(fileName: string, sceneName: string): boolean {
+  const sceneNameLower = sceneName.toLowerCase();
   const patterns = [
-    flowNameLower.replace(/\s+/g, '-'),
-    flowNameLower.replace(/\s+/g, ''),
-    flowNameLower.replace(/\s+/g, '_'),
-    flowNameLower,
+    sceneNameLower.replace(/\s+/g, '-'),
+    sceneNameLower.replace(/\s+/g, ''),
+    sceneNameLower.replace(/\s+/g, '_'),
+    sceneNameLower,
   ];
 
   return patterns.some((pattern) => fileName.includes(pattern));

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

@@ -1,15 +1,15 @@
 import { describe, expect, it } from 'vitest';
-import type { Message, Narrative } from '../../index';
-import { narrativesToModel } from './index';
+import type { Message, Scene } from '../../index';
+import { scenesToModel } from './index';
 import { buildTypeInfoFromMessages, messageToTypeInfo } from './type-inference';
 
 describe('Type inference in narrative-to-model transformer', () => {
   it('should correctly extract command types from when clauses', () => {
-    const flows: Narrative[] = [
+    const flows: Scene[] = [
       {
         name: 'Test Flow',
         id: 'FLOW-001',
-        slices: [
+        moments: [
           {
             id: 'SLICE-001',
             type: 'command',
@@ -108,7 +108,7 @@ describe('Type inference in narrative-to-model transformer', () => {
       },
     ];
 
-    const model = narrativesToModel(flows);
+    const model = scenesToModel(flows);
 
     // Should have the correct command messages extracted
     expect(model.messages.some((msg) => msg.name === 'AnswerQuestion')).toBe(true);
@@ -130,11 +130,11 @@ describe('Type inference in narrative-to-model transformer', () => {
   });
 
   it('should handle single object when/then clauses correctly', () => {
-    const flows: Narrative[] = [
+    const flows: Scene[] = [
       {
         name: 'Single Object Flow',
         id: 'FLOW-001',
-        slices: [
+        moments: [
           {
             id: 'SLICE-001',
             type: 'command',
@@ -177,7 +177,7 @@ describe('Type inference in narrative-to-model transformer', () => {
       },
     ];
 
-    const model = narrativesToModel(flows);
+    const model = scenesToModel(flows);
 
     // Should extract the command and event types from single objects
     expect(model.messages.some((msg) => msg.name === 'TestCommand')).toBe(true);
@@ -188,11 +188,11 @@ describe('Type inference in narrative-to-model transformer', () => {
 
 describe('Messages-derived fallback in type resolution', () => {
   it('resolves InferredType in second example When step via messages populated by first example', () => {
-    const flows: Narrative[] = [
+    const flows: Scene[] = [
       {
         name: 'Booking Flow',
         id: 'FLOW-001',
-        slices: [
+        moments: [
           {
             id: 'SLICE-001',
             type: 'command',
@@ -250,7 +250,7 @@ describe('Messages-derived fallback in type resolution', () => {
       },
     ];
 
-    const model = narrativesToModel(flows);
+    const model = scenesToModel(flows);
 
     expect(model.messages.some((msg) => msg.name === 'InferredType')).toBe(false);
     expect(model.messages.some((msg) => msg.name === 'RequestBooking')).toBe(true);