@auto-engineer/narrative 1.3.3 → 1.4.0

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

@@ -0,0 +1,241 @@
+import { describe, expect, it } from 'vitest';
+import type { Message } from '../../index';
+import type { ExampleShapeHints } from './example-shapes';
+import { detectQueryAction, extractQueryNameFromRequest, processWhen } from './spec-processors';
+
+describe('spec-processors', () => {
+  describe('extractQueryNameFromRequest', () => {
+    it('should extract query name from simple GraphQL query', () => {
+      const request = 'query ViewWorkoutPlan { workoutPlan { id } }';
+      expect(extractQueryNameFromRequest(request)).toBe('ViewWorkoutPlan');
+    });
+
+    it('should extract query name from GraphQL query with variables', () => {
+      const request = 'query ViewWorkoutPlan($workoutId: ID!) { workoutPlan(id: $workoutId) { id name } }';
+      expect(extractQueryNameFromRequest(request)).toBe('ViewWorkoutPlan');
+    });
+
+    it('should extract query name case-insensitively', () => {
+      const request = 'QUERY GetUserProfile { user { id } }';
+      expect(extractQueryNameFromRequest(request)).toBe('GetUserProfile');
+    });
+
+    it('should return null for undefined request', () => {
+      expect(extractQueryNameFromRequest(undefined)).toBe(null);
+    });
+
+    it('should return null for empty string', () => {
+      expect(extractQueryNameFromRequest('')).toBe(null);
+    });
+
+    it('should return null for mutation', () => {
+      const request = 'mutation CreateWorkout { createWorkout { id } }';
+      expect(extractQueryNameFromRequest(request)).toBe(null);
+    });
+
+    it('should extract query name from JSON AST format', () => {
+      const ast = {
+        kind: 'Document',
+        definitions: [
+          {
+            kind: 'OperationDefinition',
+            operation: 'query',
+            name: { value: 'ListWorkouts' },
+          },
+        ],
+      };
+      expect(extractQueryNameFromRequest(JSON.stringify(ast))).toBe('ListWorkouts');
+    });
+  });
+
+  describe('detectQueryAction', () => {
+    it('should return true when whenText exactly matches query name from request', () => {
+      const slice = { type: 'query', request: 'query ViewWorkoutPlan($id: ID!) { workoutPlan { id } }' };
+      expect(detectQueryAction('ViewWorkoutPlan', slice)).toBe(true);
+    });
+
+    it('should return true when whenText matches query name case-insensitively', () => {
+      const slice = { type: 'query', request: 'query viewWorkoutPlan { workoutPlan { id } }' };
+      expect(detectQueryAction('ViewWorkoutPlan', slice)).toBe(true);
+    });
+
+    it('should return false for command slices', () => {
+      const slice = { type: 'command', request: 'mutation CreateWorkout { createWorkout { id } }' };
+      expect(detectQueryAction('ViewWorkoutPlan', slice)).toBe(false);
+    });
+
+    it('should return false when no request field is provided (no naming convention fallback)', () => {
+      const slice = { type: 'query' };
+      // Without request field, cannot determine if it's a query action
+      expect(detectQueryAction('ViewWorkoutPlan', slice)).toBe(false);
+      expect(detectQueryAction('GetUserProfile', slice)).toBe(false);
+      expect(detectQueryAction('ListWorkouts', slice)).toBe(false);
+      expect(detectQueryAction('FindUserById', slice)).toBe(false);
+      expect(detectQueryAction('SearchProducts', slice)).toBe(false);
+      expect(detectQueryAction('FetchOrders', slice)).toBe(false);
+    });
+
+    it('should return false for event names in query slices', () => {
+      const slice = { type: 'query', request: 'query ViewWorkoutPlan { workoutPlan { id } }' };
+      expect(detectQueryAction('WorkoutPlanCreated', slice)).toBe(false);
+    });
+
+    it('should return true for case-insensitive match to query name from request', () => {
+      const slice = { type: 'query', request: 'query ViewWorkoutPlan { workoutPlan { id } }' };
+      // Case-insensitive matching works when request field is present
+      expect(detectQueryAction('viewWorkoutPlan', slice)).toBe(true);
+    });
+
+    it('should return false for empty whenText', () => {
+      const slice = { type: 'query', request: 'query ViewWorkoutPlan { workoutPlan { id } }' };
+      expect(detectQueryAction('', slice)).toBe(false);
+    });
+  });
+
+  describe('processWhen', () => {
+    const mockTypeResolver = (t: string) => ({
+      resolvedName: t,
+      typeInfo: undefined,
+    });
+
+    const createEmptyHints = (): ExampleShapeHints => new Map();
+
+    describe('query action detection', () => {
+      it('should create a query message when When is a query action matching request', () => {
+        const messages: Map<string, Message> = new Map();
+        const slice = { type: 'query', request: 'query ViewWorkoutPlan($id: ID!) { workoutPlan { id } }' };
+        const when = { commandRef: 'ViewWorkoutPlan', exampleData: { workoutId: 'wrk_123' } };
+
+        processWhen(when, slice, mockTypeResolver, messages, createEmptyHints());
+
+        // Query message should be created for query actions
+        expect(messages.size).toBe(1);
+        expect(messages.has('ViewWorkoutPlan')).toBe(true);
+        expect(messages.get('ViewWorkoutPlan')?.type).toBe('query');
+      });
+
+      it('should create a message when no request field (cannot detect query action)', () => {
+        const messages: Map<string, Message> = new Map();
+        const slice = { type: 'query' }; // No request field
+        const when = { commandRef: 'ViewWorkoutHistory', exampleData: { userId: 'user_456' } };
+
+        processWhen(when, slice, mockTypeResolver, messages, createEmptyHints());
+
+        // Without request field, cannot detect query action - treats as event
+        expect(messages.size).toBe(1);
+        expect(messages.has('ViewWorkoutHistory')).toBe(true);
+      });
+
+      it('should create a query message when When matches query name from request', () => {
+        const messages: Map<string, Message> = new Map();
+        const slice = { type: 'query', request: 'query GetUserProfile { user { id } }' };
+        const when = { commandRef: 'GetUserProfile', exampleData: { userId: 'user_123' } };
+
+        processWhen(when, slice, mockTypeResolver, messages, createEmptyHints());
+
+        // Query action detected via request field - query message created
+        expect(messages.size).toBe(1);
+        expect(messages.has('GetUserProfile')).toBe(true);
+        expect(messages.get('GetUserProfile')?.type).toBe('query');
+      });
+
+      it('should create a message when When is an event name in query slice', () => {
+        const messages: Map<string, Message> = new Map();
+        const slice = { type: 'query', request: 'query ViewWorkoutPlan { workoutPlan { id } }' };
+        const when = { commandRef: 'WorkoutPlanUpdated', exampleData: { workoutId: 'wrk_123' } };
+
+        processWhen(when, slice, mockTypeResolver, messages, createEmptyHints());
+
+        // Event messages SHOULD be created
+        expect(messages.size).toBe(1);
+        expect(messages.has('WorkoutPlanUpdated')).toBe(true);
+      });
+
+      it('should create a message for command slices regardless of naming', () => {
+        const messages: Map<string, Message> = new Map();
+        const slice = { type: 'command' };
+        const when = { commandRef: 'ViewWorkoutPlan', exampleData: { workoutId: 'wrk_123' } };
+
+        processWhen(when, slice, mockTypeResolver, messages, createEmptyHints());
+
+        // Command messages SHOULD be created even if it looks like a query action name
+        expect(messages.size).toBe(1);
+        expect(messages.has('ViewWorkoutPlan')).toBe(true);
+      });
+    });
+
+    describe('array of When items', () => {
+      it('should create query messages for query action items matching request', () => {
+        const messages: Map<string, Message> = new Map();
+        const slice = { type: 'query', request: 'query ViewWorkoutPlan { workoutPlan { id } }' };
+        const when = [{ commandRef: 'ViewWorkoutPlan', exampleData: { workoutId: 'wrk_123' } }];
+
+        processWhen(when, slice, mockTypeResolver, messages, createEmptyHints());
+
+        // Query action matches request - query message created
+        expect(messages.size).toBe(1);
+        expect(messages.has('ViewWorkoutPlan')).toBe(true);
+        expect(messages.get('ViewWorkoutPlan')?.type).toBe('query');
+      });
+
+      it('should create messages when no request field (cannot detect query action)', () => {
+        const messages: Map<string, Message> = new Map();
+        const slice = { type: 'query' }; // No request field
+        const when = [{ commandRef: 'ViewWorkoutPlan', exampleData: { workoutId: 'wrk_123' } }];
+
+        processWhen(when, slice, mockTypeResolver, messages, createEmptyHints());
+
+        // Without request field, cannot detect query action - message created
+        expect(messages.size).toBe(1);
+        expect(messages.has('ViewWorkoutPlan')).toBe(true);
+      });
+
+      it('should create messages for event items in array', () => {
+        const messages: Map<string, Message> = new Map();
+        const slice = { type: 'query', request: 'query ViewWorkoutPlan { workoutPlan { id } }' };
+        const when = [
+          { commandRef: 'WorkoutPlanCreated', exampleData: { workoutId: 'wrk_123' } },
+          { commandRef: 'WorkoutPlanUpdated', exampleData: { workoutId: 'wrk_123' } },
+        ];
+
+        processWhen(when, slice, mockTypeResolver, messages, createEmptyHints());
+
+        expect(messages.size).toBe(2);
+        expect(messages.has('WorkoutPlanCreated')).toBe(true);
+        expect(messages.has('WorkoutPlanUpdated')).toBe(true);
+      });
+
+      it('should create query message for query action and event message in mixed array', () => {
+        const messages: Map<string, Message> = new Map();
+        const slice = { type: 'query', request: 'query ViewWorkoutPlan { workoutPlan { id } }' };
+        const when = [
+          { commandRef: 'ViewWorkoutPlan', exampleData: { workoutId: 'wrk_123' } }, // Query action - create query message
+          { commandRef: 'WorkoutPlanUpdated', exampleData: { workoutId: 'wrk_123' } }, // Event - create event message
+        ];
+
+        processWhen(when, slice, mockTypeResolver, messages, createEmptyHints());
+
+        expect(messages.size).toBe(2);
+        expect(messages.has('ViewWorkoutPlan')).toBe(true);
+        expect(messages.get('ViewWorkoutPlan')?.type).toBe('query');
+        expect(messages.has('WorkoutPlanUpdated')).toBe(true);
+      });
+    });
+
+    describe('example shape hints collection', () => {
+      it('should collect example hints for query actions', () => {
+        const messages: Map<string, Message> = new Map();
+        const slice = { type: 'query', request: 'query ViewWorkoutPlan { workoutPlan { id } }' };
+        const when = { commandRef: 'ViewWorkoutPlan', exampleData: { workoutId: 'wrk_123', userId: 'user_456' } };
+        const hints = createEmptyHints();
+
+        processWhen(when, slice, mockTypeResolver, messages, hints);
+
+        // Query message created and hints should be collected
+        expect(messages.size).toBe(1);
+        expect(messages.get('ViewWorkoutPlan')?.type).toBe('query');
+        expect(hints.has('ViewWorkoutPlan')).toBe(true);
+      });
+    });
+  });
+});

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

@@ -7,9 +7,62 @@ import { preferNewFields } from './normalize';
 
 const log = debug('auto:flow:spec-processors');
 
+/**
+ * Extracts the query name from a GraphQL request string.
+ * Supports both SDL strings and JSON-serialized AST.
+ */
+export function extractQueryNameFromRequest(request: string | undefined): string | null {
+  if (!request) return null;
+  const queryMatch = request.match(/query\s+(\w+)/i);
+  if (queryMatch) {
+    return queryMatch[1];
+  }
+  if (request.startsWith('{') && request.includes('"kind"')) {
+    try {
+      const ast = JSON.parse(request) as unknown;
+      if (
+        typeof ast === 'object' &&
+        ast !== null &&
+        'definitions' in ast &&
+        Array.isArray((ast as { definitions: unknown[] }).definitions)
+      ) {
+        const definitions = (ast as { definitions: Array<{ kind?: string; name?: { value?: string } }> }).definitions;
+        const opDef = definitions.find((d) => d.kind === 'OperationDefinition');
+        if (opDef?.name?.value) {
+          return opDef.name.value;
+        }
+      }
+    } catch {}
+  }
+
+  return null;
+}
+
+/**
+ * Detects if the "When" text in a query slice represents a query action (query name)
+ * rather than an event name.
+ *
+ * Detection is based solely on matching the query name extracted from slice.request.
+ * If no query name can be extracted, returns false (treats as event - safe default).
+ *
+ * @param whenText - The text from the "When" step
+ * @param slice - The slice object containing type and optional request field
+ * @returns true if the "When" text matches the query name from slice.request
+ */
+export function detectQueryAction(whenText: string, slice: { type: string; request?: string }): boolean {
+  if (slice.type !== 'query') return false;
+  if (!whenText) return false;
+
+  const queryName = extractQueryNameFromRequest(slice.request);
+  if (!queryName) return false;
+
+  // Exact match or case-insensitive match
+  return whenText === queryName || whenText.toLowerCase() === queryName.toLowerCase();
+}
+
 type TypeResolver = (
   t: string,
-  expected?: 'command' | 'event' | 'state',
+  expected?: 'command' | 'event' | 'state' | 'query',
   exampleData?: unknown,
 ) => { resolvedName: string; typeInfo: TypeInfo | undefined };
 
@@ -316,7 +369,7 @@ function processSingleWhen(
     stateRef?: string;
     exampleData?: unknown;
   },
-  slice: { type: string },
+  slice: { type: string; request?: string },
   resolveTypeAndInfo: TypeResolver,
   messages: Map<string, Message>,
   exampleShapeHints: ExampleShapeHints,
@@ -326,6 +379,23 @@ function processSingleWhen(
   }
 
   const originalCommandRef = when.commandRef;
+
+  // Check if this is a query action
+  // Query actions represent the act of executing the query - create a query message for them
+  if (detectQueryAction(originalCommandRef, slice)) {
+    log('DEBUG processSingleWhen: detected query action, creating query message:', originalCommandRef);
+    const { typeInfo } = resolveTypeAndInfo(originalCommandRef, 'query', when.exampleData);
+    const msg = createMessage(originalCommandRef, typeInfo, 'query');
+    const existing = messages.get(originalCommandRef);
+    if (!existing || preferNewFields(msg.fields, existing.fields)) {
+      messages.set(originalCommandRef, msg);
+    }
+    if (when.exampleData !== undefined) {
+      collectExampleHintsForData(originalCommandRef, when.exampleData, exampleShapeHints);
+    }
+    return;
+  }
+
   const expected = slice.type === 'command' ? 'command' : 'event';
 
   log('DEBUG processSingleWhen:', {
@@ -418,7 +488,7 @@ function processCommandRefInArray(
     stateRef?: string;
     exampleData?: unknown;
   },
-  slice: { type: string },
+  slice: { type: string; request?: string },
   resolveTypeAndInfo: TypeResolver,
   messages: Map<string, Message>,
   exampleShapeHints: ExampleShapeHints,
@@ -428,6 +498,23 @@ function processCommandRefInArray(
   }
 
   const originalCommandRef = item.commandRef;
+
+  // Check if this is a query action (query name like ViewWorkoutPlan)
+  // Query actions represent the act of executing the query - create a query message for them
+  if (detectQueryAction(originalCommandRef, slice)) {
+    log('DEBUG processCommandRefInArray: detected query action, creating query message:', originalCommandRef);
+    const { typeInfo } = resolveTypeAndInfo(originalCommandRef, 'query', item.exampleData);
+    const msg = createMessage(originalCommandRef, typeInfo, 'query');
+    const existing = messages.get(originalCommandRef);
+    if (!existing || preferNewFields(msg.fields, existing.fields)) {
+      messages.set(originalCommandRef, msg);
+    }
+    if (item.exampleData !== undefined) {
+      collectExampleHintsForData(originalCommandRef, item.exampleData, exampleShapeHints);
+    }
+    return;
+  }
+
   const expected = slice.type === 'command' ? 'command' : 'event';
   const { resolvedName, typeInfo } = resolveTypeAndInfo(originalCommandRef, expected, item.exampleData);
 
@@ -497,7 +584,7 @@ export function processWhen(
         stateRef?: string;
         exampleData?: unknown;
       }>,
-  slice: { type: string },
+  slice: { type: string; request?: string },
   resolveTypeAndInfo: TypeResolver,
   messages: Map<string, Message>,
   exampleShapeHints: ExampleShapeHints,

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

@@ -64,7 +64,7 @@ function tryMatchCandidates(candidates: TypeInfo[], dataKeys: Set<string>): stri
 function tryResolveByExampleData(
   candidates: TypeInfo[],
   all: TypeInfo[],
-  expectedMessageType: 'command' | 'event' | 'state' | undefined,
+  expectedMessageType: 'command' | 'event' | 'state' | 'query' | undefined,
   exampleData: unknown,
 ): string | null {
   if (exampleData === null || typeof exampleData !== 'object' || exampleData === undefined) {
@@ -85,7 +85,7 @@ function tryResolveByExampleData(
 
 function tryResolveByExpectedType(
   candidates: TypeInfo[],
-  expectedMessageType: 'command' | 'event' | 'state' | undefined,
+  expectedMessageType: 'command' | 'event' | 'state' | 'query' | undefined,
 ): string | null {
   if (!expectedMessageType || candidates.length === 0) {
     return null;
@@ -98,7 +98,7 @@ function tryResolveByExpectedType(
 function resolveFromCandidates(
   candidates: TypeInfo[],
   all: TypeInfo[],
-  expectedMessageType?: 'command' | 'event' | 'state',
+  expectedMessageType?: 'command' | 'event' | 'state' | 'query',
   exampleData?: unknown,
 ): string | null {
   if (candidates.length === 1) return candidates[0].stringLiteral;
@@ -112,7 +112,7 @@ function resolveFromCandidates(
 export function resolveInferredType(
   typeName: string,
   flowTypeMap?: Map<string, TypeInfo>,
-  expectedMessageType?: 'command' | 'event' | 'state',
+  expectedMessageType?: 'command' | 'event' | 'state' | 'query',
   exampleData?: unknown,
 ): string {
   if (typeName !== 'InferredType' || flowTypeMap === undefined) return typeName;

package/src/types.ts

@@ -228,4 +228,9 @@ export type Event<
   readonly kind?: 'Event';
 };
 
+export type Query<QueryType extends string, QueryData extends Record<string, unknown> = Record<string, unknown>> = {
+  type: QueryType;
+  data: QueryData;
+};
+
 export type ExtractStateData<T> = T extends State<string, infer Data, DefaultRecord | undefined> ? Data : never;