@auto-engineer/narrative 0.13.3 → 0.15.0

package/src/narrative-context.specs.ts

@@ -1,7 +1,10 @@
-import { describe, it, expect, beforeEach } from 'vitest';
-import { flow, example, rule, specs } from './narrative';
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+
 import { command } from './fluent-builder';
-import { type Event, type State } from './types';
+import type { CommandSlice } from './index';
+import { example, flow, describe as narrativeDescribe, it as narrativeIt, rule, should, specs } from './narrative';
+import { registry } from './narrative-registry';
+import type { Event, State } from './types';
 
 type QuestionnaireLinkSent = Event<
   'QuestionnaireLinkSent',
@@ -36,9 +39,140 @@ type QuestionnaireProgress = State<
   }
 >;
 
+describe('it and should with id parameter', () => {
+  afterEach(() => {
+    registry.clearAll();
+  });
+
+  it('should record it with title only', () => {
+    flow('test it title only', () => {
+      command('test command').client(() => {
+        narrativeDescribe('Test Section', () => {
+          narrativeIt('displays todo list');
+        });
+      });
+    });
+
+    const narratives = registry.getAllNarratives();
+    const slice = narratives[0].slices[0] as CommandSlice;
+    const describeNode = slice.client.specs[0];
+
+    expect(describeNode.type).toBe('describe');
+    if (describeNode.type !== 'describe') throw new Error('Expected describe node');
+    expect(describeNode.children).toHaveLength(1);
+
+    const itNode = describeNode.children![0];
+    expect(itNode.type).toBe('it');
+    expect(itNode.title).toBe('displays todo list');
+    expect(itNode.id).toBeUndefined();
+  });
+
+  it('should record it with title and id (id at end)', () => {
+    flow('test it with id', () => {
+      command('test command').client(() => {
+        narrativeDescribe('Test Section', () => {
+          narrativeIt('displays todo list', 'IT-001');
+        });
+      });
+    });
+
+    const narratives = registry.getAllNarratives();
+    const slice = narratives[0].slices[0] as CommandSlice;
+    const describeNode = slice.client.specs[0];
+    if (describeNode.type !== 'describe') throw new Error('Expected describe node');
+    const itNode = describeNode.children![0];
+
+    expect(itNode.type).toBe('it');
+    expect(itNode.title).toBe('displays todo list');
+    expect(itNode.id).toBe('IT-001');
+  });
+
+  it('should record should with title only', () => {
+    flow('test should title only', () => {
+      command('test command').client(() => {
+        narrativeDescribe('Test Section', () => {
+          should('display todo list');
+        });
+      });
+    });
+
+    const narratives = registry.getAllNarratives();
+    const slice = narratives[0].slices[0] as CommandSlice;
+    const describeNode = slice.client.specs[0];
+    if (describeNode.type !== 'describe') throw new Error('Expected describe node');
+    const itNode = describeNode.children![0];
+
+    expect(itNode.type).toBe('it');
+    expect(itNode.title).toBe('display todo list');
+    expect(itNode.id).toBeUndefined();
+  });
+
+  it('should record should with title and id (id at end)', () => {
+    flow('test should with id', () => {
+      command('test command').client(() => {
+        narrativeDescribe('Test Section', () => {
+          should('display todo list', 'SH-001');
+        });
+      });
+    });
+
+    const narratives = registry.getAllNarratives();
+    const slice = narratives[0].slices[0] as CommandSlice;
+    const describeNode = slice.client.specs[0];
+    if (describeNode.type !== 'describe') throw new Error('Expected describe node');
+    const itNode = describeNode.children![0];
+
+    expect(itNode.type).toBe('it');
+    expect(itNode.title).toBe('display todo list');
+    expect(itNode.id).toBe('SH-001');
+  });
+});
+
+describe('describe with id parameter', () => {
+  afterEach(() => {
+    registry.clearAll();
+  });
+
+  it('should record describe with title and callback', () => {
+    flow('test describe title', () => {
+      command('test command').client(() => {
+        narrativeDescribe('Todo List', () => {
+          narrativeIt('shows items');
+        });
+      });
+    });
+
+    const narratives = registry.getAllNarratives();
+    const slice = narratives[0].slices[0] as CommandSlice;
+    const describeNode = slice.client.specs[0];
+
+    expect(describeNode.type).toBe('describe');
+    expect(describeNode.title).toBe('Todo List');
+    expect(describeNode.id).toBeUndefined();
+  });
+
+  it('should record describe with title, id, and callback (id at end)', () => {
+    flow('test describe with id', () => {
+      command('test command').client(() => {
+        narrativeDescribe('Todo List', 'DESC-001', () => {
+          narrativeIt('shows items');
+        });
+      });
+    });
+
+    const narratives = registry.getAllNarratives();
+    const slice = narratives[0].slices[0] as CommandSlice;
+    const describeNode = slice.client.specs[0];
+
+    expect(describeNode.type).toBe('describe');
+    expect(describeNode.title).toBe('Todo List');
+    expect(describeNode.id).toBe('DESC-001');
+  });
+});
+
 describe('Narrative DSL', () => {
   beforeEach(async () => {
-    // Clean test state before each test
+    registry.clearAll();
   });
 
   it('should support given() method in builder', () => {

package/src/narrative-context.ts

@@ -1,10 +1,9 @@
 import createDebug from 'debug';
-import type { DataSinkItem, DataSourceItem, DataItem, DataSink, DataSource } from './types';
-import type { GivenTypeInfo } from './loader/ts-utils';
-import { Narrative, Slice, CommandSlice, QuerySlice, ExperienceSlice } from './index';
-import type { ClientSpecNode } from './schema';
 import type { z } from 'zod';
-import type { StepSchema, ExampleSchema, SpecSchema, RuleSchema } from './schema';
+import type { CommandSlice, ExperienceSlice, Narrative, QuerySlice, Slice } from './index';
+import type { GivenTypeInfo } from './loader/ts-utils';
+import type { ClientSpecNode, ExampleSchema, RuleSchema, SpecSchema, StepSchema } from './schema';
+import type { DataItem, DataSink, DataSinkItem, DataSource, DataSourceItem } from './types';
 
 type Step = z.infer<typeof StepSchema>;
 type Example = z.infer<typeof ExampleSchema>;
@@ -213,7 +212,7 @@ export function pushSpec(feature: string): void {
   }
 }
 
-export function pushDescribe(id?: string, title?: string): void {
+export function pushDescribe(title?: string, id?: string): void {
   if (!context) throw new Error('No active narrative context');
 
   const describeNode: ClientSpecNode = {
@@ -260,7 +259,7 @@ export function popDescribe(): void {
   addNodeToParentOrRoot(completedDescribe, slice as CommandSlice | QuerySlice | ExperienceSlice);
 }
 
-export function recordIt(id?: string, title: string = ''): void {
+export function recordIt(title: string, id?: string): void {
   if (!context) throw new Error('No active narrative context');
 
   const itNode: ClientSpecNode = {

package/src/narrative-registry.ts

@@ -1,6 +1,6 @@
-import { NarrativeSchema } from './schema';
-import { Narrative } from './index';
 import createDebug from 'debug';
+import type { Narrative } from './index';
+import { NarrativeSchema } from './schema';
 
 const debug = createDebug('auto:narrative:registry');
 // Set non-error-like colors for debug namespace

package/src/narrative.ts

@@ -1,24 +1,24 @@
-import { registry } from './narrative-registry';
+import createDebug from 'debug';
 import {
-  startNarrative,
   clearCurrentNarrative,
-  getCurrentSlice,
-  startClientBlock,
   endClientBlock,
-  startServerBlock,
   endServerBlock,
-  pushSpec,
-  pushDescribe,
+  getCurrentSlice,
   popDescribe,
+  pushDescribe,
+  pushSpec,
+  recordErrorStep,
+  recordExample,
   recordIt,
-  setSliceData,
   recordRule,
-  recordExample,
   recordStep,
-  recordErrorStep,
+  setSliceData,
+  startClientBlock,
+  startNarrative,
+  startServerBlock,
 } from './narrative-context';
+import { registry } from './narrative-registry';
 import type { DataItem } from './types';
-import createDebug from 'debug';
 
 const debug = createDebug('auto:narrative:narrative');
 if ('color' in debug && typeof debug === 'object') {
@@ -65,43 +65,37 @@ export const request = (_query: unknown) => ({
 
 export function describe(fn: () => void): void;
 export function describe(title: string, fn: () => void): void;
-export function describe(id: string, title: string, fn: () => void): void;
-export function describe(
-  idOrTitleOrFn: string | (() => void),
-  titleOrFn?: string | (() => void),
-  fn?: () => void,
-): void {
-  if (typeof idOrTitleOrFn === 'function') {
+export function describe(title: string, id: string, fn: () => void): void;
+export function describe(titleOrFn: string | (() => void), idOrFn?: string | (() => void), fn?: () => void): void {
+  if (typeof titleOrFn === 'function') {
     const slice = getCurrentSlice();
     const inferredTitle = slice?.name ?? '';
-    pushDescribe(undefined, inferredTitle);
-    idOrTitleOrFn();
+    pushDescribe(inferredTitle, undefined);
+    titleOrFn();
     popDescribe();
     return;
   }
 
-  const hasId = typeof titleOrFn === 'string';
-  const id = hasId ? idOrTitleOrFn : undefined;
-  const title = hasId ? titleOrFn : idOrTitleOrFn;
-  const callback = hasId ? fn! : (titleOrFn as () => void);
+  const title = titleOrFn;
+  const hasId = typeof idOrFn === 'string';
+  const id = hasId ? idOrFn : undefined;
+  const callback = hasId ? fn! : (idOrFn as () => void);
 
-  pushDescribe(id, title);
+  pushDescribe(title, id);
   callback();
   popDescribe();
 }
 
 export function it(title: string): void;
-export function it(id: string, title: string): void;
-export function it(idOrTitle: string, title?: string): void {
-  const hasId = title !== undefined;
-  recordIt(hasId ? idOrTitle : undefined, hasId ? title : idOrTitle);
+export function it(title: string, id: string): void;
+export function it(title: string, id?: string): void {
+  recordIt(title, id);
 }
 
 export function should(title: string): void;
-export function should(id: string, title: string): void;
-export function should(idOrTitle: string, title?: string): void {
-  const hasId = title !== undefined;
-  recordIt(hasId ? idOrTitle : undefined, hasId ? title : idOrTitle);
+export function should(title: string, id: string): void;
+export function should(title: string, id?: string): void {
+  recordIt(title, id);
 }
 
 export function specs(feature: string, fn: () => void): void;

package/src/node.ts

@@ -1,5 +1,3 @@
-export * from './index.js';
-
 export {
   commandHandler as exportSchemaCommandHandler,
   type ExportSchemaCommand,
@@ -7,6 +5,7 @@ export {
   type SchemaExportedEvent,
   type SchemaExportFailedEvent,
 } from './commands/export-schema.js';
+export * from './index.js';
 
 import { commandHandler as exportSchemaHandler } from './commands/export-schema.js';
 export const COMMANDS = [exportSchemaHandler];

package/src/samples/items.narrative.ts

@@ -1,8 +1,8 @@
-import { data, flow, describe, it, specs, rule, example } from '../narrative';
-import { command, query } from '../fluent-builder';
 import gql from 'graphql-tag';
 import { source } from '../data-narrative-builders';
-import { type Event, type Command, type State } from '../types';
+import { command, query } from '../fluent-builder';
+import { data, describe, example, flow, it, rule, specs } from '../narrative';
+import type { Command, Event, State } from '../types';
 
 type ItemCreated = Event<
   'ItemCreated',

package/src/samples/mixed-given-types.narrative.ts

@@ -1,6 +1,6 @@
-import { flow, specs, rule, example } from '../narrative';
 import { query } from '../fluent-builder';
-import { type Event, type State } from '../types';
+import { example, flow, rule, specs } from '../narrative';
+import type { Event, State } from '../types';
 
 type ConfigState = State<
   'ConfigState',

package/src/samples/place-order.narrative.ts

@@ -1,5 +1,5 @@
-import { flow, describe, it, specs, rule, example } from '../narrative';
 import { command } from '../fluent-builder';
+import { describe, example, flow, it, rule, specs } from '../narrative';
 
 export interface OrderPlaced {
   type: 'OrderPlaced';

package/src/samples/questionnaires.narrative.ts

@@ -1,20 +1,20 @@
 import {
+  type Command,
   command,
-  query,
+  data,
+  describe,
+  type Event,
+  example,
   experience,
   flow,
+  gql,
   it,
-  describe,
-  specs,
+  query,
   rule,
-  example,
-  gql,
-  source,
-  data,
-  sink,
-  type Command,
-  type Event,
   type State,
+  sink,
+  source,
+  specs,
 } from '@auto-engineer/narrative';
 
 type QuestionnaireLinkSent = Event<

package/src/samples/test-with-ids.narrative.ts

@@ -1,6 +1,6 @@
-import { flow, specs, rule, example, thenError } from '../narrative';
 import { command, query, react } from '../fluent-builder';
-import { type Event, type Command, type State } from '../types';
+import { example, flow, rule, specs, thenError } from '../narrative';
+import type { Command, Event, State } from '../types';
 
 type TestItemCreated = Event<
   'TestItemCreated',

package/src/schema-test.ts

@@ -1,5 +1,5 @@
-import { DataSinkSchema, DataSourceSchema, MessageTargetSchema } from './schema';
 import { sink, source } from './data-narrative-builders';
+import { DataSinkSchema, DataSourceSchema, MessageTargetSchema } from './schema';
 
 // Test that the builders produce output compatible with the schema
 const testSink = sink().event('TestEvent').fields({ id: true }).toStream('test-${id}');

package/src/slice-builder.ts

@@ -1,6 +1,6 @@
-import type { Integration } from './types';
-import { getCurrentNarrative, addSlice } from './narrative-context';
 import type { CommandSlice, QuerySlice, ReactSlice } from './index';
+import { addSlice, getCurrentNarrative } from './narrative-context';
+import type { Integration } from './types';
 
 export interface SliceConfig {
   integration?: Integration;

package/src/transformers/model-to-narrative/ast/emit-helpers.ts

@@ -1,4 +1,4 @@
-import tsNS from 'typescript';
+import type tsNS from 'typescript';
 
 /**
  * Type information for converting JSON values with proper Date handling

package/src/transformers/model-to-narrative/formatting/sort-types.ts

@@ -1,5 +1,5 @@
-import { collectTypeDeclarations } from '../analysis/type-decls';
 import { findCodeBoundaries, reconstructCode } from '../analysis/lint-helpers';
+import { collectTypeDeclarations } from '../analysis/type-decls';
 
 /**
  * Sorts TypeScript type declarations alphabetically, adds line breaks between them, and removes unused types.

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

@@ -1,11 +1,11 @@
 import ts from 'typescript';
-import { buildImports, ALL_FLOW_FUNCTION_NAMES } from './imports';
-import { buildTypeAliases } from './types';
-import { buildFlowStatements } from './flow';
+import type { Model } from '../../../index';
+import { analyzeCodeUsage } from '../analysis/usage';
 import { extractTypeIntegrationNames } from '../utils/integration-extractor';
 import { integrationNameToPascalCase } from '../utils/strings';
-import { analyzeCodeUsage } from '../analysis/usage';
-import { Model } from '../../../index';
+import { buildFlowStatements } from './flow';
+import { ALL_FLOW_FUNCTION_NAMES, buildImports } from './imports';
+import { buildTypeAliases } from './types';
 
 export function generateTypeScriptCode(schema: Model, opts: { flowImport: string; integrationImport: string }): string {
   const f = ts.factory;

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

@@ -1,20 +1,20 @@
 import type tsNS from 'typescript';
 import type { z } from 'zod';
-import { jsonToExpr } from '../ast/emit-helpers';
-import { buildConsolidatedGwtSpecBlock, type GWTBlock } from './gwt';
-import {
+import type {
+  ClientSpecNode,
   CommandSliceSchema,
-  QuerySliceSchema,
-  ReactSliceSchema,
-  ExperienceSliceSchema,
-  ExampleSchema,
-  NarrativeSchema,
   DataSinkSchema,
   DataSourceSchema,
   DestinationSchema,
+  ExampleSchema,
+  ExperienceSliceSchema,
+  NarrativeSchema,
   OriginSchema,
-  type ClientSpecNode,
+  QuerySliceSchema,
+  ReactSliceSchema,
 } from '../../../schema';
+import { jsonToExpr } from '../ast/emit-helpers';
+import { buildConsolidatedGwtSpecBlock, type GWTBlock } from './gwt';
 
 type CommandSlice = z.infer<typeof CommandSliceSchema>;
 type QuerySlice = z.infer<typeof QuerySliceSchema>;

package/src/transformers/model-to-narrative/generators/gwt.specs.ts

@@ -0,0 +1,157 @@
+import ts from 'typescript';
+import { describe, expect, it } from 'vitest';
+import { buildConsolidatedGwtSpecBlock, buildGwtSpecBlock, type GWTBlock } from './gwt';
+
+function printNode(node: ts.Node): string {
+  const printer = ts.createPrinter({ newLine: ts.NewLineKind.LineFeed });
+  const sourceFile = ts.createSourceFile('test.ts', '', ts.ScriptTarget.Latest, false, ts.ScriptKind.TS);
+  return printer.printNode(ts.EmitHint.Unspecified, node, sourceFile);
+}
+
+describe('buildGwtSpecBlock', () => {
+  it('generates builder chain pattern for when+then (no given)', () => {
+    const gwtBlock: GWTBlock & { ruleDescription: string; exampleDescription: string; ruleId: string } = {
+      when: { commandRef: 'AddTodo', exampleData: { todoId: 'todo-001', description: 'Buy groceries' } },
+      then: [
+        {
+          eventRef: 'TodoAdded',
+          exampleData: {
+            todoId: 'todo-001',
+            description: 'Buy groceries',
+            status: 'pending',
+            addedAt: '2030-01-01T09:00:00.000Z',
+          },
+        },
+      ],
+      ruleDescription: 'todos can be added to the list',
+      exampleDescription: 'adds a new todo successfully',
+      ruleId: 'r1B2Cp8Y',
+    };
+
+    const result = buildGwtSpecBlock(ts, ts.factory, gwtBlock, 'command');
+    const code = printNode(result);
+
+    expect(code).toContain('rule("todos can be added to the list"');
+    expect(code).toContain('"r1B2Cp8Y"');
+    expect(code).toContain('example("adds a new todo successfully")');
+    expect(code).toContain('.when<AddTodo>');
+    expect(code).toContain('.then<TodoAdded>');
+    expect(code).not.toMatch(/example\("[^"]+",\s*\(\)/);
+  });
+
+  it('generates builder chain pattern for given+when+then', () => {
+    const gwtBlock: GWTBlock & { ruleDescription: string; exampleDescription: string; ruleId: string } = {
+      given: [
+        {
+          eventRef: 'TodoAdded',
+          exampleData: {
+            todoId: 'todo-001',
+            description: 'Buy groceries',
+            status: 'pending',
+            addedAt: '2030-01-01T09:00:00.000Z',
+          },
+        },
+      ],
+      when: { commandRef: 'MarkTodoInProgress', exampleData: { todoId: 'todo-001' } },
+      then: [
+        {
+          eventRef: 'TodoMarkedInProgress',
+          exampleData: { todoId: 'todo-001', markedAt: '2030-01-01T10:00:00.000Z' },
+        },
+      ],
+      ruleDescription: 'todos can be moved to in progress',
+      exampleDescription: 'moves a pending todo to in progress',
+      ruleId: 'r2C3Dq9Z',
+    };
+
+    const result = buildGwtSpecBlock(ts, ts.factory, gwtBlock, 'command');
+    const code = printNode(result);
+
+    expect(code).toContain('example("moves a pending todo to in progress")');
+    expect(code).toContain('.given<TodoAdded>');
+    expect(code).toContain('.when<MarkTodoInProgress>');
+    expect(code).toContain('.then<TodoMarkedInProgress>');
+    expect(code).not.toMatch(/example\("[^"]+",\s*\(\)/);
+  });
+
+  it('generates builder chain with .and() for multiple given events', () => {
+    const gwtBlock: GWTBlock & { ruleDescription: string; exampleDescription: string; ruleId: string } = {
+      given: [
+        {
+          eventRef: 'TodoAdded',
+          exampleData: { todoId: 'todo-001', description: 'Buy groceries', status: 'pending' },
+        },
+        {
+          eventRef: 'TodoMarkedInProgress',
+          exampleData: { todoId: 'todo-001', markedAt: '2030-01-01T10:00:00.000Z' },
+        },
+      ],
+      when: { commandRef: 'MarkTodoComplete', exampleData: { todoId: 'todo-001' } },
+      then: [
+        {
+          eventRef: 'TodoMarkedComplete',
+          exampleData: { todoId: 'todo-001', completedAt: '2030-01-01T11:00:00.000Z' },
+        },
+      ],
+      ruleDescription: 'todos can be marked as complete',
+      exampleDescription: 'marks an in-progress todo as complete',
+      ruleId: 'r3D4Eq0A',
+    };
+
+    const result = buildGwtSpecBlock(ts, ts.factory, gwtBlock, 'command');
+    const code = printNode(result);
+
+    expect(code).toContain('.given<TodoAdded>');
+    expect(code).toContain('.and<TodoMarkedInProgress>');
+    expect(code).toContain('.when<MarkTodoComplete>');
+    expect(code).toContain('.then<TodoMarkedComplete>');
+    expect(code).not.toMatch(/example\("[^"]+",\s*\(\)/);
+  });
+
+  it('still wraps example in rule callback', () => {
+    const gwtBlock: GWTBlock & { ruleDescription: string; exampleDescription: string; ruleId: string } = {
+      when: { commandRef: 'AddTodo', exampleData: { todoId: 'todo-001' } },
+      then: [{ eventRef: 'TodoAdded', exampleData: { todoId: 'todo-001' } }],
+      ruleDescription: 'test rule',
+      exampleDescription: 'test example',
+      ruleId: 'testId',
+    };
+
+    const result = buildGwtSpecBlock(ts, ts.factory, gwtBlock, 'command');
+    const code = printNode(result);
+
+    expect(code).toMatch(/rule\([^)]+\)\s*=>/);
+  });
+});
+
+describe('buildConsolidatedGwtSpecBlock', () => {
+  it('generates multiple examples with builder chain pattern', () => {
+    const rule = { id: 'r3D4Eq0A', description: 'todos can be marked as complete' };
+    const gwtBlocks: Array<GWTBlock & { exampleDescription: string }> = [
+      {
+        given: [{ eventRef: 'TodoAdded', exampleData: { todoId: 'todo-001' } }],
+        when: { commandRef: 'MarkTodoComplete', exampleData: { todoId: 'todo-001' } },
+        then: [{ eventRef: 'TodoMarkedComplete', exampleData: { todoId: 'todo-001' } }],
+        exampleDescription: 'marks an in-progress todo as complete',
+      },
+      {
+        given: [{ eventRef: 'TodoAdded', exampleData: { todoId: 'todo-002' } }],
+        when: { commandRef: 'MarkTodoComplete', exampleData: { todoId: 'todo-002' } },
+        then: [{ eventRef: 'TodoMarkedComplete', exampleData: { todoId: 'todo-002' } }],
+        exampleDescription: 'marks a pending todo directly as complete',
+      },
+    ];
+
+    const result = buildConsolidatedGwtSpecBlock(ts, ts.factory, rule, gwtBlocks, 'command');
+    const code = printNode(result);
+
+    expect(code).toContain('rule("todos can be marked as complete"');
+    expect(code).toContain('"r3D4Eq0A"');
+    expect(code).toContain('example("marks an in-progress todo as complete")');
+    expect(code).toContain('example("marks a pending todo directly as complete")');
+    expect(code).toContain('.given<TodoAdded>');
+    expect(code).toContain('.when<MarkTodoComplete>');
+    expect(code).toContain('.then<TodoMarkedComplete>');
+    expect(code).not.toMatch(/example\("[^"]+",\s*\(\)/);
+  });
+});