@auto-engineer/narrative 1.3.3 → 1.4.0

package/package.json

@@ -23,9 +23,9 @@
     "typescript": "^5.9.2",
     "zod": "^3.22.4",
     "zod-to-json-schema": "^3.22.3",
-    "@auto-engineer/file-store": "1.3.3",
-    "@auto-engineer/id": "1.3.3",
-    "@auto-engineer/message-bus": "1.3.3"
+    "@auto-engineer/file-store": "1.4.0",
+    "@auto-engineer/id": "1.4.0",
+    "@auto-engineer/message-bus": "1.4.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
@@ -35,7 +35,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "version": "1.3.3",
+  "version": "1.4.0",
   "scripts": {
     "build": "tsx scripts/build.ts",
     "test": "vitest run --reporter=dot",

package/src/index.ts

@@ -19,6 +19,7 @@ export type {
   Integration,
   MessageTarget,
   Origin,
+  Query,
   State,
 } from './types';
 export { createIntegration } from './types';
@@ -81,6 +82,7 @@ export {
   modelSchema,
   NarrativeNamesSchema as NarrativeNamesSystemSchema,
   NarrativeSchema,
+  QuerySchema,
   QuerySliceSchema,
   ReactSliceSchema,
   RuleSchema,
@@ -135,3 +137,5 @@ export type MessageRef = z.infer<typeof MessageRefSchema>;
 // ID assignment utilities
 export { addAutoIds, hasAllIds } from './id';
 export type { ClientSpecNode } from './schema';
+
+export { detectQueryAction, extractQueryNameFromRequest } from './transformers/narrative-to-model/spec-processors';

package/src/loader/ts-utils.ts

@@ -77,7 +77,7 @@ export function parseImports(ts: typeof import('typescript'), fileName: string,
 
 export interface TypeInfo {
   stringLiteral: string;
-  classification?: 'command' | 'event' | 'state';
+  classification?: 'command' | 'event' | 'state' | 'query';
   dataFields?: { name: string; type: string; required: boolean }[];
 }
 
@@ -93,7 +93,7 @@ export interface GivenTypeInfo {
   column: number;
   ordinal: number; // Sequential position within the file
   typeName: string;
-  classification: 'command' | 'event' | 'state';
+  classification: 'command' | 'event' | 'state' | 'query';
 }
 
 function extractDataFieldsFromTypeLiteral(
@@ -136,7 +136,7 @@ function processTypeAlias(
   const baseName = getBaseName(typeRef.typeName);
   if (typeof baseName !== 'string') return;
 
-  if (!['Command', 'Event', 'State'].includes(baseName)) return;
+  if (!['Command', 'Event', 'State', 'Query'].includes(baseName)) return;
 
   const typeArgs = typeRef.typeArguments ?? [];
   if (typeArgs.length === 0) return;
@@ -145,7 +145,7 @@ function processTypeAlias(
   if (!ts.isLiteralTypeNode(firstArg) || !ts.isStringLiteral(firstArg.literal)) return;
 
   const stringLiteral = firstArg.literal.text;
-  const classification = baseName.toLowerCase() as 'command' | 'event' | 'state';
+  const classification = baseName.toLowerCase() as 'command' | 'event' | 'state' | 'query';
 
   // Try to extract the data fields from the 2nd generic arg (if present)
   let dataFields: { name: string; type: string; required: boolean }[] | undefined;
@@ -271,7 +271,7 @@ function extractDataFields(
   return dataFields;
 }
 
-function inferClassificationFromName(stringLiteral: string): 'command' | 'event' | 'state' | undefined {
+function inferClassificationFromName(stringLiteral: string): 'command' | 'event' | 'state' | 'query' | undefined {
   const eventPatterns = ['ed', 'Created', 'Updated', 'Deleted', 'Placed', 'Added', 'Removed', 'Changed'];
   if (eventPatterns.some((pattern) => stringLiteral.endsWith(pattern))) {
     return 'event';
@@ -282,6 +282,11 @@ function inferClassificationFromName(stringLiteral: string): 'command' | 'event'
     return 'command';
   }
 
+  // Query patterns: View*, Get*, List*, Find*, Search*, Fetch*
+  if (/^(View|Get|List|Find|Search|Fetch)[A-Z]/.test(stringLiteral)) {
+    return 'query';
+  }
+
   const statePatterns = ['Summary', 'View', 'Items', 'List', 'Data', 'Info'];
   if (statePatterns.some((pattern) => stringLiteral.endsWith(pattern))) {
     return 'state';
@@ -463,7 +468,7 @@ function classifyBaseGeneric(
   ts: typeof import('typescript'),
   checker: import('typescript').TypeChecker,
   typeRef: import('typescript').TypeReferenceNode,
-): 'event' | 'command' | 'state' | null {
+): 'event' | 'command' | 'state' | 'query' | null {
   // Resolve base symbol (handles aliases and qualified names)
   let sym: import('typescript').Symbol | undefined;
   if (ts.isIdentifier(typeRef.typeName) || ts.isQualifiedName(typeRef.typeName)) {
@@ -476,6 +481,7 @@ function classifyBaseGeneric(
   if (base.endsWith('Event')) return 'event';
   if (base.endsWith('Command')) return 'command';
   if (base.endsWith('State')) return 'state';
+  if (base.endsWith('Query')) return 'query';
   return null;
 }
 
@@ -483,7 +489,7 @@ function tryUnwrapDirectGeneric(
   ts: typeof import('typescript'),
   typeArg: import('typescript').TypeReferenceNode,
   checker: import('typescript').TypeChecker,
-): { typeName: string; classification: 'event' | 'command' | 'state' } | null {
+): { typeName: string; classification: 'event' | 'command' | 'state' | 'query' } | null {
   if (typeArg.typeArguments === undefined || typeArg.typeArguments.length === 0) return null;
 
   const kind = classifyBaseGeneric(ts, checker, typeArg);
@@ -504,7 +510,7 @@ function tryUnwrapTypeAlias(
   typeArg: import('typescript').TypeReferenceNode,
   typeMap: Map<string, TypeInfo>,
   typesByFile: Map<string, Map<string, TypeInfo>>,
-): { typeName: string; classification: 'event' | 'command' | 'state' } | null {
+): { typeName: string; classification: 'event' | 'command' | 'state' | 'query' } | null {
   if (!ts.isIdentifier(typeArg.typeName)) return null;
 
   const typeName = typeArg.typeName.text;
@@ -526,7 +532,7 @@ function tryUnwrapGeneric(
   checker: import('typescript').TypeChecker,
   typeMap: Map<string, TypeInfo>,
   typesByFile: Map<string, Map<string, TypeInfo>>,
-): { typeName: string; classification: 'event' | 'command' | 'state' } | null {
+): { typeName: string; classification: 'event' | 'command' | 'state' | 'query' } | null {
   if (!ts.isTypeReferenceNode(typeArg)) return null;
 
   return tryUnwrapDirectGeneric(ts, typeArg, checker) ?? tryUnwrapTypeAlias(ts, typeArg, typeMap, typesByFile);
@@ -554,7 +560,7 @@ function createGivenTypeInfo(
   node: import('typescript').CallExpression,
   ordinal: number,
   typeName: string,
-  classification: 'event' | 'command' | 'state',
+  classification: 'event' | 'command' | 'state' | 'query',
 ): GivenTypeInfo {
   const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart());
   return {

package/src/model-to-narrative.specs.ts

@@ -658,6 +658,59 @@ narrative('Test Flow with Rule IDs', 'FLOW-456', () => {
 `);
   });
 
+  it('should correctly generate Query type alias for query messages', async () => {
+    const modelWithQueryMessage: Model = {
+      variant: 'specs',
+      narratives: [
+        {
+          name: 'Workout Flow',
+          id: 'FLOW-001',
+          slices: [],
+        },
+      ],
+      messages: [
+        {
+          type: 'query',
+          name: 'GetWorkoutHistory',
+          fields: [
+            { name: 'memberId', type: 'string', required: true },
+            { name: 'limit', type: 'number', required: false },
+          ],
+          metadata: { version: 1 },
+        },
+        {
+          type: 'event',
+          name: 'WorkoutRecorded',
+          fields: [{ name: 'workoutId', type: 'string', required: true }],
+          source: 'internal',
+          metadata: { version: 1 },
+        },
+      ],
+      integrations: [],
+      modules: [],
+    };
+
+    const code = getCode(await modelToNarrative(modelWithQueryMessage));
+
+    expect(code).toEqual(`import { narrative } from '@auto-engineer/narrative';
+import type { Event, Query } from '@auto-engineer/narrative';
+type GetWorkoutHistory = Query<
+  'GetWorkoutHistory',
+  {
+    memberId: string;
+    limit?: number;
+  }
+>;
+type WorkoutRecorded = Event<
+  'WorkoutRecorded',
+  {
+    workoutId: string;
+  }
+>;
+narrative('Workout Flow', 'FLOW-001', () => {});
+`);
+  });
+
   it('should correctly resolve Date types in messages', async () => {
     const modelWithDateTypes: Model = {
       variant: 'specs',
@@ -3370,4 +3423,74 @@ narrative('All Projection Types', 'ALL-PROJ', () => {
       expect(code).toContain("command('Perform Check-In'");
     });
   });
+
+  it('generates all declared types for authored modules regardless of usage analysis', async () => {
+    const model: Model = {
+      variant: 'specs',
+      narratives: [
+        {
+          id: 'narrative-1',
+          name: 'Gym Goal Setting',
+          slices: [
+            {
+              type: 'command',
+              name: 'Set Fitness Goal',
+              client: { specs: [] },
+              server: {
+                description: 'Set a fitness goal',
+                specs: [
+                  {
+                    type: 'gherkin',
+                    feature: 'Goal Setting',
+                    rules: [
+                      {
+                        name: 'Create goal',
+                        examples: [
+                          {
+                            name: 'Create fitness goal',
+                            steps: [
+                              { keyword: 'When', text: 'SetFitnessGoal', docString: { name: 'Lose weight' } },
+                              { keyword: 'Then', text: 'FitnessGoalCreated', docString: { goalId: '123' } },
+                            ],
+                          },
+                        ],
+                      },
+                    ],
+                  },
+                ],
+              },
+            },
+          ],
+          sourceFile: '/narratives/goal-setting.narrative.ts',
+        },
+      ],
+      messages: [
+        { type: 'command', name: 'SetFitnessGoal', fields: [] },
+        { type: 'event', name: 'FitnessGoalCreated', fields: [], source: 'internal' },
+        { type: 'state', name: 'FitnessGoalsView', fields: [] },
+      ],
+      modules: [
+        {
+          sourceFile: '/narratives/goal-setting.narrative.ts',
+          isDerived: false,
+          contains: { narrativeIds: ['narrative-1'] },
+          declares: {
+            messages: [
+              { kind: 'command', name: 'SetFitnessGoal' },
+              { kind: 'event', name: 'FitnessGoalCreated' },
+              { kind: 'state', name: 'FitnessGoalsView' },
+            ],
+          },
+        },
+      ],
+    };
+
+    const result = await modelToNarrative(model);
+    const code = getCode(result);
+
+    // All 3 declared types should be generated
+    expect(code).toContain("type SetFitnessGoal = Command<'SetFitnessGoal'");
+    expect(code).toContain("type FitnessGoalCreated = Event<'FitnessGoalCreated'");
+    expect(code).toContain("type FitnessGoalsView = State<'FitnessGoalsView'");
+  });
 });

package/src/schema.ts

@@ -3,7 +3,7 @@ import { z } from 'zod';
 // Message reference for module type ownership
 export const MessageRefSchema = z
   .object({
-    kind: z.enum(['command', 'event', 'state']).describe('Message kind'),
+    kind: z.enum(['command', 'event', 'state', 'query']).describe('Message kind'),
     name: z.string().describe('Message name'),
   })
   .describe('Reference to a message type');
@@ -174,7 +174,11 @@ const StateSchema = BaseMessageSchema.extend({
   type: z.literal('state'),
 }).describe('State/Read Model representing a view of data');
 
-const MessageSchema = z.discriminatedUnion('type', [CommandSchema, EventSchema, StateSchema]);
+const QuerySchema = BaseMessageSchema.extend({
+  type: z.literal('query'),
+}).describe('Query representing a read operation');
+
+const MessageSchema = z.discriminatedUnion('type', [CommandSchema, EventSchema, StateSchema, QuerySchema]);
 
 const BaseSliceSchema = z
   .object({
@@ -417,6 +421,7 @@ export {
   CommandSchema,
   EventSchema,
   StateSchema,
+  QuerySchema,
   IntegrationSchema,
   CommandSliceSchema,
   QuerySliceSchema,

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

@@ -35,6 +35,7 @@ export function buildImports(
     command: 'Command',
     event: 'Event',
     state: 'State',
+    query: 'Query',
   };
 
   const flowTypeNames = Array.from(usedMessageTypes)

package/src/transformers/model-to-narrative/generators/module-code.ts

@@ -102,13 +102,22 @@ function generateModuleCode(
 
   const usedMessages = messages.filter((msg) => {
     const isImportedFromIntegration = usedTypeIntegrationNames.includes(msg.name);
-    const isUsedInFlow = usageAnalysis.usedTypes.has(msg.name);
-    const hasEmptyFlowSlices = narratives.length === 0 || narratives.every((flow) => flow.slices.length === 0);
 
+    // Don't generate local definitions for types imported from integrations
     if (isImportedFromIntegration) {
       return false;
     }
 
+    // For authored modules, trust the declares list - all declared messages should be generated
+    // (messages is already filtered to only include declared messages at line 60-61)
+    if (!module.isDerived) {
+      return true;
+    }
+
+    // For derived modules, only include types that are actually used in flow code
+    // or when there's no flow code (hasEmptyFlowSlices)
+    const isUsedInFlow = usageAnalysis.usedTypes.has(msg.name);
+    const hasEmptyFlowSlices = narratives.length === 0 || narratives.every((flow) => flow.slices.length === 0);
     return isUsedInFlow || hasEmptyFlowSlices;
   });
 

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

@@ -2,7 +2,7 @@ import type tsNS from 'typescript';
 import { typeFromString } from '../ast/emit-helpers';
 
 type Message = {
-  type: 'command' | 'event' | 'state';
+  type: 'command' | 'event' | 'state' | 'query';
   name: string;
   fields: { name: string; type: string; required: boolean }[];
 };
@@ -33,10 +33,9 @@ export function buildTypeAliases(ts: typeof tsNS, messages: Message[]): tsNS.Sta
 
     const name = f.createIdentifier(m.name);
 
-    const rhs = f.createTypeReferenceNode(
-      m.type === 'event' ? 'Event' : m.type === 'command' ? 'Command' : 'State',
-      typeArgs,
-    );
+    const baseTypeName =
+      m.type === 'event' ? 'Event' : m.type === 'command' ? 'Command' : m.type === 'query' ? 'Query' : 'State';
+    const rhs = f.createTypeReferenceNode(baseTypeName, typeArgs);
 
     return f.createTypeAliasDeclaration(
       undefined, // No export keyword

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

@@ -12,7 +12,7 @@ import { resolveInferredType } from './type-inference';
 
 type TypeResolver = (
   t: string,
-  expected?: 'command' | 'event' | 'state',
+  expected?: 'command' | 'event' | 'state' | 'query',
   exampleData?: unknown,
 ) => { resolvedName: string; typeInfo: TypeInfo | undefined };
 
@@ -47,7 +47,7 @@ function getTypesForNarrative(
 function tryResolveFromNarrativeTypes(
   t: string,
   narrativeSpecificTypes: Map<string, TypeInfo>,
-  expected?: 'command' | 'event' | 'state',
+  expected?: 'command' | 'event' | 'state' | 'query',
   exampleData?: unknown,
 ): { resolvedName: string; typeInfo: TypeInfo | undefined } {
   if (t !== 'InferredType') {
@@ -68,7 +68,7 @@ function tryFallbackToUnionTypes(
   resolvedName: string,
   typeInfo: TypeInfo | undefined,
   unionTypes: Map<string, TypeInfo>,
-  expected?: 'command' | 'event' | 'state',
+  expected?: 'command' | 'event' | 'state' | 'query',
   exampleData?: unknown,
 ): { resolvedName: string; typeInfo: TypeInfo | undefined } {
   if (resolvedName !== 'InferredType' && typeInfo) {
@@ -88,7 +88,7 @@ function tryFallbackToUnionTypes(
 function tryResolveFromUnionTypes(
   t: string,
   unionTypes: Map<string, TypeInfo>,
-  expected?: 'command' | 'event' | 'state',
+  expected?: 'command' | 'event' | 'state' | 'query',
   exampleData?: unknown,
 ): { resolvedName: string; typeInfo: TypeInfo | undefined } {
   if (t !== 'InferredType') {
@@ -110,7 +110,7 @@ function createTypeResolver(
 ) {
   return (
     t: string,
-    expected?: 'command' | 'event' | 'state',
+    expected?: 'command' | 'event' | 'state' | 'query',
     exampleData?: unknown,
   ): { resolvedName: string; typeInfo: TypeInfo | undefined } => {
     if (narrativeSpecificTypes) {

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

@@ -1,9 +1,9 @@
 import type { Message } from '../../index';
 import type { TypeInfo } from '../../loader/ts-utils';
 
-function mapKindToMessageType(k: 'command' | 'query' | 'reaction'): 'command' | 'event' | 'state' {
+function mapKindToMessageType(k: 'command' | 'query' | 'reaction'): 'command' | 'event' | 'state' | 'query' {
   if (k === 'command') return 'command';
-  if (k === 'query') return 'state';
+  if (k === 'query') return 'query';
   return 'event';
 }
 
@@ -52,7 +52,7 @@ function processStateFields(
 export function createMessage(
   name: string,
   typeInfo: TypeInfo | undefined,
-  messageType: 'command' | 'event' | 'state',
+  messageType: 'command' | 'event' | 'state' | 'query',
 ): Message {
   let fields = buildInitialFields(typeInfo);
 
@@ -81,6 +81,15 @@ export function createMessage(
     };
   }
 
+  if (messageType === 'query') {
+    return {
+      type: 'query',
+      name,
+      fields,
+      metadata,
+    };
+  }
+
   return {
     type: 'state',
     name,