@auto-engineer/narrative 1.157.0 → 1.158.0

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

@@ -0,0 +1,140 @@
+import type tsNS from 'typescript';
+import type { Model, Narrative } from '../../../index';
+import { jsonToExpr } from '../ast/emit-helpers';
+
+export function buildAssumptionsCall(
+  ts: typeof import('typescript'),
+  f: tsNS.NodeFactory,
+  items: string[],
+): tsNS.Statement {
+  return f.createExpressionStatement(
+    f.createCallExpression(
+      f.createIdentifier('assumptions'),
+      undefined,
+      items.map((s) => f.createStringLiteral(s)),
+    ),
+  );
+}
+
+export function buildRequirementsCall(f: tsNS.NodeFactory, doc: string): tsNS.Statement {
+  return f.createExpressionStatement(
+    f.createCallExpression(f.createIdentifier('requirements'), undefined, [f.createStringLiteral(doc)]),
+  );
+}
+
+function buildActorCall(
+  ts: typeof import('typescript'),
+  f: tsNS.NodeFactory,
+  actorDef: Model['actors'] extends (infer T)[] | undefined ? T : never,
+): tsNS.Statement {
+  return f.createExpressionStatement(
+    f.createCallExpression(f.createIdentifier('actor'), undefined, [jsonToExpr(ts, f, actorDef)]),
+  );
+}
+
+function buildEntityCall(
+  ts: typeof import('typescript'),
+  f: tsNS.NodeFactory,
+  entityDef: Model['entities'] extends (infer T)[] | undefined ? T : never,
+): tsNS.Statement {
+  return f.createExpressionStatement(
+    f.createCallExpression(f.createIdentifier('entity'), undefined, [jsonToExpr(ts, f, entityDef)]),
+  );
+}
+
+export function buildModelMetadataStatements(ts: typeof import('typescript'), model: Model): tsNS.Statement[] {
+  const f = ts.factory;
+  const statements: tsNS.Statement[] = [];
+
+  if (model.actors?.length) {
+    for (const a of model.actors) statements.push(buildActorCall(ts, f, a));
+  }
+
+  if (model.entities?.length) {
+    for (const e of model.entities) statements.push(buildEntityCall(ts, f, e));
+  }
+
+  if (model.assumptions?.length) {
+    statements.push(buildAssumptionsCall(ts, f, model.assumptions));
+  }
+
+  if (model.requirements) {
+    statements.push(buildRequirementsCall(f, model.requirements));
+  }
+
+  return statements;
+}
+
+function buildNarrativeCall(
+  ts: typeof import('typescript'),
+  f: tsNS.NodeFactory,
+  nar: Narrative,
+  sceneIdToName: Map<string, string>,
+): tsNS.Statement {
+  const configProps: tsNS.ObjectLiteralElementLike[] = [];
+
+  if (nar.outcome) configProps.push(f.createPropertyAssignment('outcome', f.createStringLiteral(nar.outcome)));
+  if (nar.impact) configProps.push(f.createPropertyAssignment('impact', f.createStringLiteral(nar.impact)));
+  if (nar.actors?.length) configProps.push(f.createPropertyAssignment('actors', jsonToExpr(ts, f, nar.actors)));
+  if (nar.sceneIds.length > 0) {
+    const sceneNames = nar.sceneIds.map((id) => sceneIdToName.get(id) ?? id);
+    configProps.push(f.createPropertyAssignment('scenes', jsonToExpr(ts, f, sceneNames)));
+  }
+  if (nar.assumptions?.length)
+    configProps.push(f.createPropertyAssignment('assumptions', jsonToExpr(ts, f, nar.assumptions)));
+  if (nar.requirements)
+    configProps.push(f.createPropertyAssignment('requirements', f.createStringLiteral(nar.requirements)));
+
+  const args: tsNS.Expression[] = [f.createStringLiteral(nar.name)];
+  if (nar.id) args.push(f.createStringLiteral(nar.id));
+  args.push(f.createObjectLiteralExpression(configProps, configProps.length > 2));
+
+  return f.createExpressionStatement(f.createCallExpression(f.createIdentifier('narrative'), undefined, args));
+}
+
+function hasNarrativeMetadata(nar: Narrative): boolean {
+  return (
+    nar.outcome !== undefined ||
+    nar.impact !== undefined ||
+    (nar.actors?.length ?? 0) > 0 ||
+    (nar.assumptions?.length ?? 0) > 0 ||
+    nar.requirements !== undefined
+  );
+}
+
+function modelHasMetadata(model: Model): boolean {
+  return (
+    (model.actors?.length ?? 0) > 0 ||
+    (model.entities?.length ?? 0) > 0 ||
+    (model.assumptions?.length ?? 0) > 0 ||
+    model.requirements !== undefined ||
+    model.narratives?.some(hasNarrativeMetadata)
+  );
+}
+
+export function buildAllMetadataStatements(
+  ts: typeof import('typescript'),
+  model: Model,
+): { statements: tsNS.Statement[]; usedFunctions: Set<string> } | null {
+  if (!modelHasMetadata(model)) return null;
+
+  const f = ts.factory;
+  const usedFunctions = new Set<string>();
+  const modelStatements = buildModelMetadataStatements(ts, model);
+
+  if (model.actors?.length) usedFunctions.add('actor');
+  if (model.entities?.length) usedFunctions.add('entity');
+  if (model.assumptions?.length) usedFunctions.add('assumptions');
+  if (model.requirements) usedFunctions.add('requirements');
+
+  const sceneIdToName = new Map(model.scenes.map((s) => [s.id ?? s.name, s.name]));
+  const narrativeStatements: tsNS.Statement[] = [];
+  for (const nar of model.narratives) {
+    if (hasNarrativeMetadata(nar)) {
+      narrativeStatements.push(buildNarrativeCall(ts, f, nar, sceneIdToName));
+      usedFunctions.add('narrative');
+    }
+  }
+
+  return { statements: [...modelStatements, ...narrativeStatements], usedFunctions };
+}

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

@@ -1,7 +1,10 @@
+import ts from 'typescript';
 import type { Model } from '../../index';
 import { formatWithPrettier } from './formatting/prettier';
+import { buildImports } from './generators/imports';
+import { buildAllMetadataStatements } from './generators/metadata';
 import { generateAllModulesCode } from './generators/module-code';
-import type { GeneratedScenes } from './types';
+import type { GeneratedFile, GeneratedScenes } from './types';
 
 /**
  * Converts a schema specification to TypeScript flow DSL code files.
@@ -17,7 +20,9 @@ export async function modelToNarrative(model: Model): Promise<GeneratedScenes> {
   const flowImport = '@auto-engineer/narrative';
   const integrationImport = extractIntegrationImportFromModel(model);
 
-  const rawFiles = generateAllModulesCode(model, { flowImport, integrationImport });
+  const moduleFiles = generateAllModulesCode(model, { flowImport, integrationImport });
+  const metadataFile = generateMetadataFile(model, flowImport);
+  const rawFiles = metadataFile ? [metadataFile, ...moduleFiles] : moduleFiles;
 
   const formattedFiles = await Promise.all(
     rawFiles.map(async (file) => ({
@@ -29,6 +34,24 @@ export async function modelToNarrative(model: Model): Promise<GeneratedScenes> {
   return { files: formattedFiles };
 }
 
+function generateMetadataFile(model: Model, flowImport: string): GeneratedFile | null {
+  const result = buildAllMetadataStatements(ts, model);
+  if (!result) return null;
+
+  const f = ts.factory;
+  const { statements, usedFunctions } = result;
+
+  const imports = buildImports(ts, { flowImport, integrationImport: '' }, [], [], [], Array.from(usedFunctions));
+  const allStatements: ts.Statement[] = [];
+  if (imports.importFlowValues) allStatements.push(imports.importFlowValues);
+  allStatements.push(...statements);
+
+  const file = f.createSourceFile(allStatements, f.createToken(ts.SyntaxKind.EndOfFileToken), ts.NodeFlags.None);
+  const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });
+
+  return { path: 'model.narrative.ts', code: printer.printFile(file) };
+}
+
 function extractIntegrationImportFromModel(model: Model): string {
   if (model.integrations && model.integrations.length > 0) {
     return model.integrations[0].source;

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

@@ -0,0 +1,82 @@
+import { describe, expect, it } from 'vitest';
+import type { NarrativeDefinition } from '../../model-level-registry';
+import { assembleSpecs } from './assemble';
+
+describe('assembleSpecs', () => {
+  it('backward compat: no metadata produces Default narrative', () => {
+    const scenes = [{ name: 'Step', id: 's-1', moments: [] }];
+    const messages = [{ type: 'command' as const, name: 'DoIt', fields: [] }];
+
+    const model = assembleSpecs(scenes, messages);
+
+    expect(model).toEqual({
+      variant: 'specs',
+      scenes,
+      messages,
+      integrations: undefined,
+      modules: expect.any(Array),
+      narratives: [{ name: 'Default', sceneIds: ['s-1'] }],
+    });
+  });
+
+  it('passes through model-level metadata', () => {
+    const model = assembleSpecs([], [], undefined, {
+      actors: [{ name: 'Op', kind: 'person' as const, description: 'Runs it' }],
+      entities: [{ name: 'Item', description: 'A thing' }],
+      assumptions: ['Always online'],
+      requirements: 'Must be fast',
+    });
+
+    expect(model.actors).toEqual([{ name: 'Op', kind: 'person', description: 'Runs it' }]);
+    expect(model.entities).toEqual([{ name: 'Item', description: 'A thing' }]);
+    expect(model.assumptions).toEqual(['Always online']);
+    expect(model.requirements).toBe('Must be fast');
+  });
+
+  it('resolves narrative sceneNames to sceneIds', () => {
+    const scenes = [
+      { name: 'Add to Cart', id: 'n-1', moments: [] },
+      { name: 'Payment', id: 'n-2', moments: [] },
+    ];
+    const defs: NarrativeDefinition[] = [
+      {
+        name: 'Checkout',
+        outcome: 'Items purchased',
+        impact: 'critical',
+        actors: ['Buyer'],
+        scenes: ['Add to Cart', 'Payment'],
+        assumptions: ['Gateway up'],
+        requirements: 'PCI',
+      },
+    ];
+
+    const model = assembleSpecs(scenes, [], undefined, undefined, defs);
+
+    expect(model.narratives).toEqual([
+      {
+        name: 'Checkout',
+        sceneIds: ['n-1', 'n-2'],
+        outcome: 'Items purchased',
+        impact: 'critical',
+        actors: ['Buyer'],
+        assumptions: ['Gateway up'],
+        requirements: 'PCI',
+      },
+    ]);
+  });
+
+  it('creates Default narrative for uncovered scenes', () => {
+    const scenes = [
+      { name: 'Covered', id: 'n-1', moments: [] },
+      { name: 'Uncovered', id: 'n-2', moments: [] },
+    ];
+    const defs: NarrativeDefinition[] = [{ name: 'Flow', scenes: ['Covered'] }];
+
+    const model = assembleSpecs(scenes, [], undefined, undefined, defs);
+
+    expect(model.narratives).toEqual([
+      { name: 'Flow', sceneIds: ['n-1'] },
+      { name: 'Default', sceneIds: ['n-2'] },
+    ]);
+  });
+});

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

@@ -1,23 +1,72 @@
-import type { Message, Model, Narrative, Scene } from '../../index';
+import type { Actor, Entity, Message, Model, Narrative, Scene } from '../../index';
+import type { NarrativeDefinition } from '../../model-level-registry';
 import { deriveModules } from './derive-modules';
 
-export function assembleSpecs(scenes: Scene[], messages: unknown[], integrations: unknown[]): Model {
-  const typedMessages = messages as Message[];
-  const modules = deriveModules(scenes, typedMessages);
+type ModelMetadata = {
+  actors?: Actor[];
+  entities?: Entity[];
+  assumptions?: string[];
+  requirements?: string;
+};
 
-  const narratives: Narrative[] = [
-    {
-      name: 'Default',
-      sceneIds: scenes.filter((s) => s.id).map((s) => s.id!),
-    },
-  ];
+export function assembleSpecs(
+  scenes: Scene[],
+  messages: Message[],
+  integrations?: Model['integrations'],
+  modelMetadata?: ModelMetadata,
+  narrativeDefinitions?: NarrativeDefinition[],
+): Model {
+  const modules = deriveModules(scenes, messages);
+
+  const narratives = buildNarratives(scenes, narrativeDefinitions);
 
   return {
     variant: 'specs' as const,
     scenes,
-    messages: typedMessages,
-    integrations: integrations as Model['integrations'],
+    messages,
+    integrations,
     modules,
     narratives,
+    ...(modelMetadata?.actors?.length ? { actors: modelMetadata.actors } : {}),
+    ...(modelMetadata?.entities?.length ? { entities: modelMetadata.entities } : {}),
+    ...(modelMetadata?.assumptions?.length ? { assumptions: modelMetadata.assumptions } : {}),
+    ...(modelMetadata?.requirements ? { requirements: modelMetadata.requirements } : {}),
   };
 }
+
+function buildNarratives(scenes: Scene[], definitions?: NarrativeDefinition[]): Narrative[] {
+  if (!definitions || definitions.length === 0) {
+    return [
+      {
+        name: 'Default',
+        sceneIds: scenes.filter((s) => s.id).map((s) => s.id!),
+      },
+    ];
+  }
+
+  const nameToId = new Map(scenes.filter((s) => s.id).map((s) => [s.name, s.id!]));
+  const coveredSceneIds = new Set<string>();
+
+  const narratives: Narrative[] = definitions.map((def) => {
+    const sceneIds = (def.scenes ?? [])
+      .map((name) => nameToId.get(name))
+      .filter((id): id is string => id !== undefined);
+    for (const id of sceneIds) coveredSceneIds.add(id);
+
+    const nar: Narrative = { name: def.name, sceneIds };
+    if (def.id) nar.id = def.id;
+    if (def.outcome) nar.outcome = def.outcome;
+    if (def.impact) nar.impact = def.impact;
+    if (def.actors?.length) nar.actors = def.actors;
+    if (def.assumptions?.length) nar.assumptions = def.assumptions;
+    if (def.requirements) nar.requirements = def.requirements;
+    return nar;
+  });
+
+  const uncoveredIds = scenes.filter((s) => s.id && !coveredSceneIds.has(s.id)).map((s) => s.id!);
+  if (uncoveredIds.length > 0) {
+    narratives.push({ name: 'Default', sceneIds: uncoveredIds });
+  }
+
+  return narratives;
+}

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

@@ -2,6 +2,7 @@ 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';
+import { modelLevelRegistry } from '../../model-level-registry';
 import { assembleSpecs } from './assemble';
 import { applyExampleShapeHints, type ExampleShapeHints } from './example-shapes';
 import { inlineAllMessageFieldTypes } from './inlining';
@@ -340,5 +341,25 @@ export const scenesToModel = (scenes: Scene[], typesByFile?: Map<string, Map<str
     inlineAllMessageFieldTypes(messages, unionTypes);
   }
 
-  return assembleSpecs(scenes, Array.from(messages.values()), Array.from(integrations.values()));
+  const {
+    actors,
+    entities,
+    assumptions: modelAssumptions,
+    requirements: modelRequirements,
+    narrativeDefinitions,
+  } = modelLevelRegistry.getAll();
+  const modelMetadata = {
+    ...(actors.length > 0 ? { actors } : {}),
+    ...(entities.length > 0 ? { entities } : {}),
+    ...(modelAssumptions.length > 0 ? { assumptions: modelAssumptions } : {}),
+    ...(modelRequirements ? { requirements: modelRequirements } : {}),
+  };
+
+  return assembleSpecs(
+    scenes,
+    Array.from(messages.values()),
+    Array.from(integrations.values()),
+    Object.keys(modelMetadata).length > 0 ? modelMetadata : undefined,
+    narrativeDefinitions.length > 0 ? narrativeDefinitions : undefined,
+  );
 };