@auto-engineer/narrative 1.139.0 → 1.140.0

package/src/narrative-context.specs.ts

@@ -1,8 +1,8 @@
 import { afterEach, beforeEach, describe, expect, it } from 'vitest';
 
 import { command } from './fluent-builder';
-import type { CommandSlice } from './index';
-import { example, flow, describe as narrativeDescribe, it as narrativeIt, rule, should, specs } from './narrative';
+import type { CommandMoment } from './index';
+import { example, describe as narrativeDescribe, it as narrativeIt, rule, scene, should, specs } from './narrative';
 import { registry } from './narrative-registry';
 import type { Event, State } from './types';
 
@@ -45,7 +45,7 @@ describe('it and should with id parameter', () => {
   });
 
   it('should record it with title only', () => {
-    flow('test it title only', () => {
+    scene('test it title only', () => {
       command('test command').client(() => {
         narrativeDescribe('Test Section', () => {
           narrativeIt('displays todo list');
@@ -53,8 +53,8 @@ describe('it and should with id parameter', () => {
       });
     });
 
-    const narratives = registry.getAllNarratives();
-    const slice = narratives[0].slices[0] as CommandSlice;
+    const scenes = registry.getAllScenes();
+    const slice = scenes[0].moments[0] as CommandMoment;
     const describeNode = slice.client.specs[0];
 
     expect(describeNode.type).toBe('describe');
@@ -68,7 +68,7 @@ describe('it and should with id parameter', () => {
   });
 
   it('should record it with title and id (id at end)', () => {
-    flow('test it with id', () => {
+    scene('test it with id', () => {
       command('test command').client(() => {
         narrativeDescribe('Test Section', () => {
           narrativeIt('displays todo list', 'IT-001');
@@ -76,8 +76,8 @@ describe('it and should with id parameter', () => {
       });
     });
 
-    const narratives = registry.getAllNarratives();
-    const slice = narratives[0].slices[0] as CommandSlice;
+    const scenes = registry.getAllScenes();
+    const slice = scenes[0].moments[0] as CommandMoment;
     const describeNode = slice.client.specs[0];
     if (describeNode.type !== 'describe') throw new Error('Expected describe node');
     const itNode = describeNode.children![0];
@@ -88,7 +88,7 @@ describe('it and should with id parameter', () => {
   });
 
   it('should record should with title only', () => {
-    flow('test should title only', () => {
+    scene('test should title only', () => {
       command('test command').client(() => {
         narrativeDescribe('Test Section', () => {
           should('display todo list');
@@ -96,8 +96,8 @@ describe('it and should with id parameter', () => {
       });
     });
 
-    const narratives = registry.getAllNarratives();
-    const slice = narratives[0].slices[0] as CommandSlice;
+    const scenes = registry.getAllScenes();
+    const slice = scenes[0].moments[0] as CommandMoment;
     const describeNode = slice.client.specs[0];
     if (describeNode.type !== 'describe') throw new Error('Expected describe node');
     const itNode = describeNode.children![0];
@@ -108,7 +108,7 @@ describe('it and should with id parameter', () => {
   });
 
   it('should record should with title and id (id at end)', () => {
-    flow('test should with id', () => {
+    scene('test should with id', () => {
       command('test command').client(() => {
         narrativeDescribe('Test Section', () => {
           should('display todo list', 'SH-001');
@@ -116,8 +116,8 @@ describe('it and should with id parameter', () => {
       });
     });
 
-    const narratives = registry.getAllNarratives();
-    const slice = narratives[0].slices[0] as CommandSlice;
+    const scenes = registry.getAllScenes();
+    const slice = scenes[0].moments[0] as CommandMoment;
     const describeNode = slice.client.specs[0];
     if (describeNode.type !== 'describe') throw new Error('Expected describe node');
     const itNode = describeNode.children![0];
@@ -134,7 +134,7 @@ describe('describe with id parameter', () => {
   });
 
   it('should record describe with title and callback', () => {
-    flow('test describe title', () => {
+    scene('test describe title', () => {
       command('test command').client(() => {
         narrativeDescribe('Todo List', () => {
           narrativeIt('shows items');
@@ -142,8 +142,8 @@ describe('describe with id parameter', () => {
       });
     });
 
-    const narratives = registry.getAllNarratives();
-    const slice = narratives[0].slices[0] as CommandSlice;
+    const scenes = registry.getAllScenes();
+    const slice = scenes[0].moments[0] as CommandMoment;
     const describeNode = slice.client.specs[0];
 
     expect(describeNode.type).toBe('describe');
@@ -152,7 +152,7 @@ describe('describe with id parameter', () => {
   });
 
   it('should record describe with title, id, and callback (id at end)', () => {
-    flow('test describe with id', () => {
+    scene('test describe with id', () => {
       command('test command').client(() => {
         narrativeDescribe('Todo List', 'DESC-001', () => {
           narrativeIt('shows items');
@@ -160,8 +160,8 @@ describe('describe with id parameter', () => {
       });
     });
 
-    const narratives = registry.getAllNarratives();
-    const slice = narratives[0].slices[0] as CommandSlice;
+    const scenes = registry.getAllScenes();
+    const slice = scenes[0].moments[0] as CommandMoment;
     const describeNode = slice.client.specs[0];
 
     expect(describeNode.type).toBe('describe');
@@ -177,7 +177,7 @@ describe('Narrative DSL', () => {
 
   it('should support given() method in builder', () => {
     expect(() => {
-      flow('test flow with given', () => {
+      scene('test flow with given', () => {
         command('test command').server(() => {
           specs(() => {
             rule('test rule with given', () => {
@@ -212,7 +212,7 @@ describe('Narrative DSL', () => {
 
   it('should support when() method in builder', () => {
     expect(() => {
-      flow('test flow with when', () => {
+      scene('test flow with when', () => {
         command('test command').server(() => {
           specs(() => {
             rule('test rule', () => {
@@ -247,7 +247,7 @@ describe('Narrative DSL', () => {
 
   it('should support then() method in builder', () => {
     expect(() => {
-      flow('test flow with then', () => {
+      scene('test flow with then', () => {
         command('test command').server(() => {
           specs(() => {
             rule('test rule', () => {
@@ -282,7 +282,7 @@ describe('Narrative DSL', () => {
 
   it('should support full narrative DSL flow', () => {
     expect(() => {
-      flow('test full DSL flow', () => {
+      scene('test full DSL flow', () => {
         command('test preservation').server(() => {
           specs(() => {
             rule('full flow rule', () => {

package/src/narrative-context.ts

@@ -1,6 +1,6 @@
 import createDebug from 'debug';
 import type { z } from 'zod';
-import type { CommandSlice, ExperienceSlice, Narrative, QuerySlice, Slice } from './index';
+import type { CommandMoment, ExperienceMoment, Moment, QueryMoment, Scene } from './index';
 import type { GivenTypeInfo } from './loader/ts-utils';
 import type { ClientSpecNode, DataTarget, ExampleSchema, RuleSchema, SpecSchema, StepSchema } from './schema';
 import type { Data, DataSink, DataSource } from './types';
@@ -14,9 +14,9 @@ const debug = createDebug('auto:narrative:context:given-types');
 
 type MajorKeyword = 'Given' | 'When' | 'Then';
 
-interface NarrativeContext {
-  narrative: Narrative;
-  currentSliceIndex: number | null;
+interface SceneContext {
+  scene: Scene;
+  currentMomentIndex: number | null;
   currentSpecTarget: 'client' | 'server' | null;
   currentSpecIndex: number | null;
   currentRuleIndex: number | null;
@@ -25,7 +25,7 @@ interface NarrativeContext {
   lastMajorKeyword: MajorKeyword | null;
 }
 
-let context: NarrativeContext | null = null;
+let context: SceneContext | null = null;
 let givenTypesByFile: Map<string, GivenTypeInfo[]> = new Map();
 let whenTypesByFile: Map<string, GivenTypeInfo[]> = new Map();
 let thenTypesByFile: Map<string, GivenTypeInfo[]> = new Map();
@@ -52,7 +52,7 @@ export function setGivenTypesByFile(types: Map<string, GivenTypeInfo[]>): void {
   thenCallCounters.clear();
 }
 
-export function startNarrative(name: string, id?: string): Narrative {
+export function startScene(name: string, id?: string): Scene {
   const sourceFile = (globalThis as Record<string, unknown>).__aeCurrentModulePath as string | undefined;
   if (sourceFile !== null && sourceFile !== undefined && sourceFile !== '') {
     givenCallCounters.set(sourceFile, 0);
@@ -60,15 +60,15 @@ export function startNarrative(name: string, id?: string): Narrative {
     thenCallCounters.set(sourceFile, 0);
   }
 
-  const narrative: Narrative = {
+  const sceneObj: Scene = {
     name,
     id,
-    slices: [],
+    moments: [],
     ...(typeof sourceFile === 'string' ? { sourceFile } : {}),
   };
   context = {
-    narrative,
-    currentSliceIndex: null,
+    scene: sceneObj,
+    currentMomentIndex: null,
     currentSpecTarget: null,
     currentSpecIndex: null,
     currentRuleIndex: null,
@@ -76,43 +76,43 @@ export function startNarrative(name: string, id?: string): Narrative {
     clientSpecStack: [],
     lastMajorKeyword: null,
   };
-  return narrative;
+  return sceneObj;
 }
 
-export function getCurrentNarrative(): Narrative | null {
-  return context?.narrative ?? null;
+export function getCurrentScene(): Scene | null {
+  return context?.scene ?? null;
 }
 
-export function clearCurrentNarrative(): void {
+export function clearCurrentScene(): void {
   context = null;
 }
 
-export function getCurrentSlice(): Slice | null {
-  if (!context || context.currentSliceIndex === null) return null;
-  return context.narrative.slices[context.currentSliceIndex] ?? null;
+export function getCurrentMoment(): Moment | null {
+  if (!context || context.currentMomentIndex === null) return null;
+  return context.scene.moments[context.currentMomentIndex] ?? null;
 }
 
-export function addSlice(slice: Slice): void {
-  if (!context) throw new Error('No active narrative');
-  context.narrative.slices.push(slice);
-  context.currentSliceIndex = context.narrative.slices.length - 1;
+export function addMoment(moment: Moment): void {
+  if (!context) throw new Error('No active scene');
+  context.scene.moments.push(moment);
+  context.currentMomentIndex = context.scene.moments.length - 1;
 }
 
-function getServerSpecs(slice: Slice): Spec[] | undefined {
+function getServerSpecs(slice: Moment): Spec[] | undefined {
   if ('server' in slice) {
     return slice.server?.specs;
   }
   return undefined;
 }
 
-function getCurrentSpec(slice: Slice): Spec | undefined {
+function getCurrentSpec(slice: Moment): Spec | undefined {
   if (!context || context.currentSpecIndex === null) return undefined;
   const specs = getServerSpecs(slice);
   if (!specs) return undefined;
   return specs[context.currentSpecIndex];
 }
 
-function getCurrentExample(slice: Slice): Example | undefined {
+function getCurrentExample(slice: Moment): Example | undefined {
   if (
     !context ||
     context.currentSpecIndex === null ||
@@ -128,8 +128,8 @@ function getCurrentExample(slice: Slice): Example | undefined {
   return spec.rules[context.currentRuleIndex]?.examples[context.currentExampleIndex];
 }
 
-export function startClientBlock(slice: Slice): void {
-  if (!context) throw new Error('No active flow context');
+export function startClientBlock(slice: Moment): void {
+  if (!context) throw new Error('No active scene context');
 
   if (slice.type === 'command' || slice.type === 'query' || slice.type === 'experience') {
     slice.client = {
@@ -158,8 +158,8 @@ export function endClientBlock(): void {
   }
 }
 
-export function startServerBlock(slice: Slice, description: string = ''): void {
-  if (!context) throw new Error('No active flow context');
+export function startServerBlock(slice: Moment, description: string = ''): void {
+  if (!context) throw new Error('No active scene context');
 
   if (slice.type === 'command') {
     slice.server = {
@@ -190,7 +190,7 @@ export function endServerBlock(): void {
   }
 }
 
-function addServerSpec(slice: Slice, feature: string): void {
+function addServerSpec(slice: Moment, feature: string): void {
   if ('server' in slice && slice.server != null) {
     const newSpec: Spec = {
       type: 'gherkin',
@@ -204,8 +204,8 @@ function addServerSpec(slice: Slice, feature: string): void {
 
 export function pushSpec(feature: string): void {
   if (!context || !context.currentSpecTarget) throw new Error('No active spec target');
-  const slice = getCurrentSlice();
-  if (!slice) throw new Error('No active slice');
+  const slice = getCurrentMoment();
+  if (!slice) throw new Error('No active moment');
 
   if (context.currentSpecTarget === 'server') {
     addServerSpec(slice, feature);
@@ -213,7 +213,7 @@ export function pushSpec(feature: string): void {
 }
 
 export function pushDescribe(title?: string, id?: string): void {
-  if (!context) throw new Error('No active narrative context');
+  if (!context) throw new Error('No active scene context');
 
   const describeNode: ClientSpecNode = {
     type: 'describe',
@@ -225,13 +225,13 @@ export function pushDescribe(title?: string, id?: string): void {
   context.clientSpecStack.push(describeNode);
 }
 
-function validateSliceSupportsClientSpecs(slice: Slice): void {
+function validateMomentSupportsClientSpecs(slice: Moment): void {
   if (slice.type !== 'command' && slice.type !== 'query' && slice.type !== 'experience') {
-    throw new Error('Client specs can only be added to command, query, or experience slices');
+    throw new Error('Client specs can only be added to command, query, or experience moments');
   }
 }
 
-function addNodeToParentOrRoot(node: ClientSpecNode, slice: CommandSlice | QuerySlice | ExperienceSlice): void {
+function addNodeToParentOrRoot(node: ClientSpecNode, slice: CommandMoment | QueryMoment | ExperienceMoment): void {
   if (!context) return;
 
   if (context.clientSpecStack.length === 0) {
@@ -246,21 +246,21 @@ function addNodeToParentOrRoot(node: ClientSpecNode, slice: CommandSlice | Query
 }
 
 export function popDescribe(): void {
-  if (!context) throw new Error('No active narrative context');
+  if (!context) throw new Error('No active scene context');
   if (context.clientSpecStack.length === 0) throw new Error('No active describe block');
 
   const completedDescribe = context.clientSpecStack.pop();
   if (!completedDescribe) return;
 
-  const slice = getCurrentSlice();
-  if (!slice) throw new Error('No active slice');
+  const slice = getCurrentMoment();
+  if (!slice) throw new Error('No active moment');
 
-  validateSliceSupportsClientSpecs(slice);
-  addNodeToParentOrRoot(completedDescribe, slice as CommandSlice | QuerySlice | ExperienceSlice);
+  validateMomentSupportsClientSpecs(slice);
+  addNodeToParentOrRoot(completedDescribe, slice as CommandMoment | QueryMoment | ExperienceMoment);
 }
 
 export function recordIt(title: string, id?: string): void {
-  if (!context) throw new Error('No active narrative context');
+  if (!context) throw new Error('No active scene context');
 
   const itNode: ClientSpecNode = {
     type: 'it',
@@ -268,23 +268,23 @@ export function recordIt(title: string, id?: string): void {
     title,
   };
 
-  const slice = getCurrentSlice();
-  if (!slice) throw new Error('No active slice');
+  const slice = getCurrentMoment();
+  if (!slice) throw new Error('No active moment');
 
-  validateSliceSupportsClientSpecs(slice);
-  addNodeToParentOrRoot(itNode, slice as CommandSlice | QuerySlice | ExperienceSlice);
+  validateMomentSupportsClientSpecs(slice);
+  addNodeToParentOrRoot(itNode, slice as CommandMoment | QueryMoment | ExperienceMoment);
 }
 
 export function setQueryRequest(request: string): void {
-  const slice = getCurrentSlice();
-  if (!slice || slice.type !== 'query') throw new Error('Request can only be set on query slices');
+  const slice = getCurrentMoment();
+  if (!slice || slice.type !== 'query') throw new Error('Request can only be set on query moments');
   slice.request = request;
 }
 
-export function setSliceData(data: Data): void {
-  const slice = getCurrentSlice();
-  if (!slice) throw new Error('No active slice');
-  if (!('server' in slice)) throw new Error('Data can only be set on slices with a server');
+export function setMomentData(data: Data): void {
+  const slice = getCurrentMoment();
+  if (!slice) throw new Error('No active moment');
+  if (!('server' in slice)) throw new Error('Data can only be set on moments with a server');
 
   const items = data.items;
   if (items.length === 0) {
@@ -313,11 +313,11 @@ function stripTypeDiscriminator(items: (DataSink | DataSource | DataTarget)[]):
 
 export function recordRule(name: string, id?: string): void {
   if (!context || context.currentSpecIndex === null) throw new Error('No active spec context');
-  const slice = getCurrentSlice();
-  if (!slice) throw new Error('No active slice');
+  const slice = getCurrentMoment();
+  if (!slice) throw new Error('No active moment');
 
   const spec = getCurrentSpec(slice);
-  if (!spec) throw new Error('No active specs for current slice');
+  if (!spec) throw new Error('No active specs for current moment');
 
   const newRule: Rule = {
     id,
@@ -332,11 +332,11 @@ export function recordExample(name: string, id?: string): void {
   if (!context || context.currentSpecIndex === null || context.currentRuleIndex === null) {
     throw new Error('No active rule context');
   }
-  const slice = getCurrentSlice();
-  if (!slice) throw new Error('No active slice');
+  const slice = getCurrentMoment();
+  if (!slice) throw new Error('No active moment');
 
   const spec = getCurrentSpec(slice);
-  if (!spec) throw new Error('No active specs for current slice');
+  if (!spec) throw new Error('No active specs for current moment');
 
   const rule = spec.rules[context.currentRuleIndex];
   const newExample: Example = {
@@ -382,7 +382,7 @@ function getCountersForKeyword(keyword: MajorKeyword): Map<string, number> {
 }
 
 function getTypeNameFromAST(effectiveKeyword: MajorKeyword): string | null {
-  const sourceFile = context?.narrative.sourceFile;
+  const sourceFile = context?.scene.sourceFile;
   if (!isValidSourceFile(sourceFile)) {
     return null;
   }
@@ -420,10 +420,10 @@ function getActiveExampleContext(): { example: Example } {
   ) {
     throw new Error('No active example context');
   }
-  const slice = getCurrentSlice();
-  if (!slice) throw new Error('No active slice');
+  const slice = getCurrentMoment();
+  if (!slice) throw new Error('No active moment');
   const example = getCurrentExample(slice);
-  if (!example) throw new Error('No active example for current slice');
+  if (!example) throw new Error('No active example for current moment');
   return { example };
 }
 

package/src/narrative-registry.ts

@@ -1,6 +1,6 @@
 import createDebug from 'debug';
-import type { Narrative } from './index';
-import { NarrativeSchema } from './schema';
+import type { Scene } from './index';
+import { SceneSchema } from './schema';
 
 const debug = createDebug('auto:narrative:registry');
 // Set non-error-like colors for debug namespace
@@ -9,57 +9,57 @@ if ('color' in debug && typeof debug === 'object') {
   (debug as { color: string }).color = '6'; // cyan
 }
 
-class NarrativeRegistry {
-  private narratives: Narrative[] = [];
+class SceneRegistry {
+  private scenes: Scene[] = [];
   private instanceId = Math.random().toString(36).substring(7);
 
   constructor() {
-    debug('Creating new NarrativeRegistry instance: %s', this.instanceId);
+    debug('Creating new SceneRegistry instance: %s', this.instanceId);
   }
 
-  register(narrative: Narrative) {
-    debug('Registering narrative: %s on instance %s', narrative.name, this.instanceId);
-    debug('Narrative slices: %d', narrative.slices.length);
-    debug('Narratives array before push: %d', this.narratives.length);
-    debug('Array object ID before: %s', this.narratives);
-    const validated = NarrativeSchema.parse(narrative);
-    this.narratives.push(validated);
-    debug('Narratives array after push: %d', this.narratives.length);
-    debug('Array object ID after: %s', this.narratives);
+  register(scene: Scene) {
+    debug('Registering scene: %s on instance %s', scene.name, this.instanceId);
+    debug('Scene moments: %d', scene.moments.length);
+    debug('Scenes array before push: %d', this.scenes.length);
+    debug('Array object ID before: %s', this.scenes);
+    const validated = SceneSchema.parse(scene);
+    this.scenes.push(validated);
+    debug('Scenes array after push: %d', this.scenes.length);
+    debug('Array object ID after: %s', this.scenes);
     debug(
-      'Successfully registered narrative: %s on instance %s, total narratives: %d',
-      narrative.name,
+      'Successfully registered scene: %s on instance %s, total scenes: %d',
+      scene.name,
       this.instanceId,
-      this.narratives.length,
+      this.scenes.length,
     );
   }
 
-  getAllNarratives(): Narrative[] {
-    debug('Getting all narratives, count: %d', this.narratives.length);
+  getAllScenes(): Scene[] {
+    debug('Getting all scenes, count: %d', this.scenes.length);
     debug('Registry instance ID: %s', this.instanceId);
-    debug('Array object ID: %s', this.narratives);
+    debug('Array object ID: %s', this.scenes);
     debug('this === registry? %s', this === registry);
-    if (this.narratives.length > 0) {
+    if (this.scenes.length > 0) {
       debug(
-        'Narratives: %o',
-        this.narratives.map((f) => f.name),
+        'Scenes: %o',
+        this.scenes.map((f) => f.name),
       );
     }
-    return [...this.narratives];
+    return [...this.scenes];
   }
 
   clearAll() {
-    debug('Clearing all narratives on instance %s, current count: %d', this.instanceId, this.narratives.length);
-    if (this.narratives.length > 0) {
+    debug('Clearing all scenes on instance %s, current count: %d', this.instanceId, this.scenes.length);
+    if (this.scenes.length > 0) {
       debug(
-        'Clearing narratives on instance %s: %o',
+        'Clearing scenes on instance %s: %o',
         this.instanceId,
-        this.narratives.map((f) => f.name),
+        this.scenes.map((f) => f.name),
       );
     }
-    this.narratives = [];
-    debug('Cleared! Instance %s now has %d narratives', this.instanceId, this.narratives.length);
+    this.scenes = [];
+    debug('Cleared! Instance %s now has %d scenes', this.instanceId, this.scenes.length);
   }
 }
 
-export const registry = new NarrativeRegistry();
+export const registry = new SceneRegistry();