@auto-engineer/narrative 0.11.20 → 0.12.1

package/src/narrative-context.ts

@@ -1,7 +1,8 @@
 import createDebug from 'debug';
 import type { DataSinkItem, DataSourceItem, DataItem, DataSink, DataSource } from './types';
 import type { GivenTypeInfo } from './loader/ts-utils';
-import { Narrative, Slice, Example } from './index';
+import { Narrative, Slice, Example, CommandSlice, QuerySlice, ExperienceSlice } from './index';
+import type { ClientSpecNode } from './schema';
 
 function normalizeContext(context?: Partial<Record<string, string>>): Record<string, string> | undefined {
   if (!context) return undefined;
@@ -25,6 +26,7 @@ interface NarrativeContext {
   currentSpecIndex: number | null;
   currentRuleIndex: number | null;
   currentExampleIndex: number | null;
+  clientSpecStack: ClientSpecNode[];
 }
 
 let context: NarrativeContext | null = null;
@@ -65,6 +67,7 @@ export function startNarrative(name: string, id?: string): Narrative {
     currentSpecIndex: null,
     currentRuleIndex: null,
     currentExampleIndex: null,
+    clientSpecStack: [],
   };
   return narrative;
 }
@@ -88,13 +91,6 @@ export function addSlice(slice: Slice): void {
   context.currentSliceIndex = context.narrative.slices.length - 1;
 }
 
-function getClientSpecs(slice: Slice): { name: string; rules: string[] } | undefined {
-  if (slice.type === 'command' || slice.type === 'query') {
-    return slice.client.specs;
-  }
-  return undefined;
-}
-
 function getServerSpecs(
   slice: Slice,
 ): { name: string; rules: { id?: string; description: string; examples: Example[] }[] } | undefined {
@@ -104,21 +100,6 @@ function getServerSpecs(
   return undefined;
 }
 
-function getCurrentSpecs(
-  slice: Slice,
-): { name: string; rules: string[] | { id?: string; description: string; examples: Example[] }[] } | undefined {
-  if (!context?.currentSpecTarget) return undefined;
-
-  switch (context.currentSpecTarget) {
-    case 'client':
-      return getClientSpecs(slice);
-    case 'server':
-      return getServerSpecs(slice);
-    default:
-      return undefined;
-  }
-}
-
 function getCurrentExample(slice: Slice): Example | undefined {
   if (
     !context ||
@@ -129,39 +110,40 @@ function getCurrentExample(slice: Slice): Example | undefined {
     return undefined;
   }
 
-  const spec = getCurrentSpecs(slice);
+  const spec = getServerSpecs(slice);
   if (!spec) return undefined;
 
-  // Only server specs have object rules with examples
-  if (context.currentSpecTarget === 'server') {
-    const objectRules = spec.rules as { id?: string; description: string; examples: Example[] }[];
-    return objectRules[context.currentRuleIndex]?.examples[context.currentExampleIndex];
-  }
-
-  return undefined;
+  const objectRules = spec.rules as { id?: string; description: string; examples: Example[] }[];
+  return objectRules[context.currentRuleIndex]?.examples[context.currentExampleIndex];
 }
 
-export function startClientBlock(slice: Slice, description: string = ''): void {
+export function startClientBlock(slice: Slice): void {
   if (!context) throw new Error('No active flow context');
 
-  if (slice.type === 'command' || slice.type === 'query') {
-    slice.client = {
-      description,
-      specs: undefined,
-    };
-    context.currentSpecTarget = 'client';
-  } else if (slice.type === 'experience') {
+  if (slice.type === 'command' || slice.type === 'query' || slice.type === 'experience') {
     slice.client = {
-      description: description || undefined,
-      specs: undefined,
+      specs: [],
     };
     context.currentSpecTarget = 'client';
+    context.clientSpecStack = [];
   }
 }
 
 export function endClientBlock(): void {
   if (context) {
+    if (context.clientSpecStack.length > 0) {
+      const unclosedCount = context.clientSpecStack.length;
+      const unclosedTitles = context.clientSpecStack
+        .map((n) => {
+          if (n.title !== undefined && n.title !== '') return n.title;
+          if (n.id !== undefined && n.id !== '') return n.id;
+          return 'unnamed';
+        })
+        .join(', ');
+      throw new Error(`${unclosedCount} unclosed describe block(s): ${unclosedTitles}`);
+    }
     context.currentSpecTarget = null;
+    context.clientSpecStack = [];
   }
 }
 
@@ -197,23 +179,6 @@ export function endServerBlock(): void {
   }
 }
 
-function initializeClientSpecs(slice: Slice, description: string): void {
-  if (slice.type === 'command' || slice.type === 'query') {
-    slice.client.specs = {
-      name: description,
-      rules: [],
-    };
-  } else if (slice.type === 'experience') {
-    if (slice.client == null) {
-      slice.client = { description: '', specs: undefined };
-    }
-    slice.client.specs = {
-      name: description,
-      rules: [],
-    };
-  }
-}
-
 function initializeServerSpecs(slice: Slice, description: string): void {
   if ('server' in slice && slice.server != null) {
     slice.server.specs = {
@@ -229,31 +194,74 @@ export function pushSpec(description: string): void {
   const slice = getCurrentSlice();
   if (!slice) throw new Error('No active slice');
 
-  switch (context.currentSpecTarget) {
-    case 'client':
-      initializeClientSpecs(slice, description);
-      break;
-    case 'server':
-      initializeServerSpecs(slice, description);
-      break;
-  }
-}
-
-export function recordShouldBlock(description?: string): void {
-  if (typeof description === 'string' && context?.currentSpecTarget === 'client') {
-    const slice = getCurrentSlice();
-    if (slice && (slice.type === 'command' || slice.type === 'query' || slice.type === 'experience')) {
-      if (!slice.client.specs) {
-        slice.client.specs = {
-          name: '',
-          rules: [],
-        };
-      }
-      slice.client.specs.rules.push(description);
+  if (context.currentSpecTarget === 'server') {
+    initializeServerSpecs(slice, description);
+  }
+}
+
+export function pushDescribe(id?: string, title?: string): void {
+  if (!context) throw new Error('No active narrative context');
+
+  const describeNode: ClientSpecNode = {
+    type: 'describe',
+    ...(id !== undefined && id !== '' ? { id } : {}),
+    ...(title !== undefined && title !== '' ? { title } : {}),
+    children: [],
+  };
+
+  context.clientSpecStack.push(describeNode);
+}
+
+function validateSliceSupportsClientSpecs(slice: Slice): 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');
+  }
+}
+
+function addNodeToParentOrRoot(node: ClientSpecNode, slice: CommandSlice | QuerySlice | ExperienceSlice): void {
+  if (!context) return;
+
+  if (context.clientSpecStack.length === 0) {
+    slice.client.specs.push(node);
+  } else {
+    const parent = context.clientSpecStack[context.clientSpecStack.length - 1];
+    if (parent.type === 'describe') {
+      if (!parent.children) parent.children = [];
+      parent.children.push(node);
     }
   }
 }
 
+export function popDescribe(): void {
+  if (!context) throw new Error('No active narrative 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');
+
+  validateSliceSupportsClientSpecs(slice);
+  addNodeToParentOrRoot(completedDescribe, slice as CommandSlice | QuerySlice | ExperienceSlice);
+}
+
+export function recordIt(id?: string, title: string = ''): void {
+  if (!context) throw new Error('No active narrative context');
+
+  const itNode: ClientSpecNode = {
+    type: 'it',
+    ...(id !== undefined && id !== '' ? { id } : {}),
+    title,
+  };
+
+  const slice = getCurrentSlice();
+  if (!slice) throw new Error('No active slice');
+
+  validateSliceSupportsClientSpecs(slice);
+  addNodeToParentOrRoot(itNode, slice as CommandSlice | QuerySlice | ExperienceSlice);
+}
+
 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');
@@ -290,19 +298,16 @@ export function recordRule(description: string, id?: string): void {
   const slice = getCurrentSlice();
   if (!slice) throw new Error('No active slice');
 
-  const spec = getCurrentSpecs(slice);
+  const spec = getServerSpecs(slice);
   if (!spec) throw new Error('No active specs for current slice');
 
-  // Only server specs have object rules with examples
-  if (context.currentSpecTarget === 'server') {
-    const objectRules = spec.rules as { id?: string; description: string; examples: Example[] }[];
-    objectRules.push({
-      id,
-      description,
-      examples: [],
-    });
-    context.currentRuleIndex = objectRules.length - 1;
-  }
+  const objectRules = spec.rules as { id?: string; description: string; examples: Example[] }[];
+  objectRules.push({
+    id,
+    description,
+    examples: [],
+  });
+  context.currentRuleIndex = objectRules.length - 1;
 }
 
 export function recordExample(description: string): void {
@@ -312,19 +317,16 @@ export function recordExample(description: string): void {
   const slice = getCurrentSlice();
   if (!slice) throw new Error('No active slice');
 
-  const spec = getCurrentSpecs(slice);
+  const spec = getServerSpecs(slice);
   if (!spec) throw new Error('No active specs for current slice');
 
-  // Only server specs have object rules with examples
-  if (context.currentSpecTarget === 'server') {
-    const objectRules = spec.rules as { id?: string; description: string; examples: Example[] }[];
-    const rule = objectRules[context.currentRuleIndex];
-    rule.examples.push({
-      description,
-      then: [],
-    });
-    context.currentExampleIndex = rule.examples.length - 1;
-  }
+  const objectRules = spec.rules as { id?: string; description: string; examples: Example[] }[];
+  const rule = objectRules[context.currentRuleIndex];
+  rule.examples.push({
+    description,
+    then: [],
+  });
+  context.currentExampleIndex = rule.examples.length - 1;
 }
 
 function processItemWithASTMatch(

package/src/narrative.ts

@@ -8,7 +8,9 @@ import {
   startServerBlock,
   endServerBlock,
   pushSpec,
-  recordShouldBlock,
+  pushDescribe,
+  popDescribe,
+  recordIt,
   setSliceData,
   recordRule,
   recordExample,
@@ -45,7 +47,7 @@ export function narrative(name: string, idOrFn: string | (() => void), fn?: () =
 export const client = (fn: () => void) => {
   const slice = getCurrentSlice();
   if (slice) {
-    startClientBlock(slice, '');
+    startClientBlock(slice);
     fn();
     endClientBlock();
   }
@@ -64,9 +66,46 @@ export const request = (_query: unknown) => ({
   with: (..._dependencies: unknown[]) => {},
 });
 
-export const should = (description: string) => {
-  recordShouldBlock(description);
-};
+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') {
+    const slice = getCurrentSlice();
+    const inferredTitle = slice?.name ?? '';
+    pushDescribe(undefined, inferredTitle);
+    idOrTitleOrFn();
+    popDescribe();
+    return;
+  }
+
+  const hasId = typeof titleOrFn === 'string';
+  const id = hasId ? idOrTitleOrFn : undefined;
+  const title = hasId ? titleOrFn : idOrTitleOrFn;
+  const callback = hasId ? fn! : (titleOrFn as () => void);
+
+  pushDescribe(id, title);
+  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 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 specs(description: string, fn: () => void): void;
 export function specs(fn: () => void): void;
@@ -75,7 +114,6 @@ export function specs(descriptionOrFn: string | (() => void), fn?: () => void):
   const callback = typeof descriptionOrFn === 'function' ? descriptionOrFn : fn!;
 
   pushSpec(description);
-  recordShouldBlock();
   callback();
 }
 

package/src/samples/items.narrative.ts

@@ -1,4 +1,4 @@
-import { data, flow, should, specs, rule, example } from '../narrative';
+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';
@@ -33,8 +33,8 @@ flow('items', () => {
   command('Create item')
     .stream('item-${id}')
     .client(() => {
-      specs('A form that allows users to add items', () => {
-        should('have fields for id and description');
+      describe('A form that allows users to add items', () => {
+        it('have fields for id and description');
       });
     })
     .server(() => {
@@ -64,10 +64,10 @@ flow('items', () => {
       }
     `)
     .client(() => {
-      specs('view Items Screen', () => {
-        should('display all items');
-        should('show quantity selectors for each item');
-        should('allow removing items');
+      describe('view Items Screen', () => {
+        it('display all items');
+        it('show quantity selectors for each item');
+        it('allow removing items');
       });
     })
     .server(() => {

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

@@ -1,4 +1,4 @@
-import { flow, should, specs, rule, example } from '../narrative';
+import { flow, describe, it, specs, rule, example } from '../narrative';
 import { command } from '../fluent-builder';
 
 export interface OrderPlaced {
@@ -32,9 +32,9 @@ flow('Place order', () => {
   command('Submit order')
     .stream('order-${orderId}')
     .client(() => {
-      specs('Order submission form', () => {
-        should('allow product selection');
-        should('allow quantity input');
+      describe('Order submission form', () => {
+        it('allow product selection');
+        it('allow quantity input');
       });
     })
     .server(() => {

package/src/samples/questionnaires.narrative.ts

@@ -3,7 +3,8 @@ import {
   query,
   experience,
   flow,
-  should,
+  it,
+  describe,
   specs,
   rule,
   example,
@@ -96,10 +97,8 @@ type QuestionnaireProgress = State<
 
 flow('Questionnaires', 'AUTO-Q9m2Kp4Lx', () => {
   experience('Homepage', 'AUTO-H1a4Bn6Cy').client(() => {
-    specs(() => {
-      should('show a hero section with a welcome message');
-      should('allow user to start the questionnaire');
-    });
+    it('show a hero section with a welcome message');
+    it('allow user to start the questionnaire');
   });
 
   query('views the questionnaire', 'AUTO-V7n8Rq5M')
@@ -163,11 +162,11 @@ flow('Questionnaires', 'AUTO-Q9m2Kp4Lx', () => {
       }
     `)
     .client(() => {
-      specs('Questionnaire Progress', () => {
-        should('focus on the current question based on the progress state');
-        should('display the list of answered questions');
-        should('display the list of remaining questions');
-        should('show a progress indicator that is always visible as the user scrolls');
+      describe('Questionnaire Progress', () => {
+        it('focus on the current question based on the progress state');
+        it('display the list of answered questions');
+        it('display the list of remaining questions');
+        it('show a progress indicator that is always visible as the user scrolls');
       });
     });
 
@@ -223,9 +222,9 @@ flow('Questionnaires', 'AUTO-Q9m2Kp4Lx', () => {
       }
     `)
     .client(() => {
-      specs('Submissions', () => {
-        should('displays a success message when the answer is submitted');
-        should('display an error message when the answer submission is rejected');
+      describe('Submissions', () => {
+        it('displays a success message when the answer is submitted');
+        it('display an error message when the answer submission is rejected');
       });
     });
 
@@ -314,9 +313,9 @@ flow('Questionnaires', 'AUTO-Q9m2Kp4Lx', () => {
       }
     `)
     .client(() => {
-      specs('Submission Readiness', () => {
-        should('enable the submit button when all questions are answered');
-        should('disable the submit button when all questions have not been answered');
+      describe('Submission Readiness', () => {
+        it('enable the submit button when all questions are answered');
+        it('disable the submit button when all questions have not been answered');
       });
     });
 
@@ -346,8 +345,8 @@ flow('Questionnaires', 'AUTO-Q9m2Kp4Lx', () => {
       }
     `)
     .client(() => {
-      specs('Submission Confirmation', () => {
-        should('display a confirmation message upon successful submission');
+      describe('Submission Confirmation', () => {
+        it('display a confirmation message upon successful submission');
       });
     });
 });

package/src/samples/seasonal-assistant.schema.json

@@ -8,18 +8,20 @@
           "name": "enters shopping criteria into assistant",
           "type": "command",
           "client": {
-            "description": "",
-            "specs": {
-              "name": "Assistant Chat Interface",
-              "rules": [
-                "allow shopper to describe their shopping needs in natural language",
-                "provide a text input for entering criteria",
-                "show examples of what to include (age, interests, budget)",
-                "show a button to submit the criteria",
-                "generate a persisted session id for a visit",
-                "show the header on top of the page"
-              ]
-            }
+            "specs": [
+              {
+                "type": "describe",
+                "title": "Assistant Chat Interface",
+                "children": [
+                  { "type": "it", "title": "allow shopper to describe their shopping needs in natural language" },
+                  { "type": "it", "title": "provide a text input for entering criteria" },
+                  { "type": "it", "title": "show examples of what to include (age, interests, budget)" },
+                  { "type": "it", "title": "show a button to submit the criteria" },
+                  { "type": "it", "title": "generate a persisted session id for a visit" },
+                  { "type": "it", "title": "show the header on top of the page" }
+                ]
+              }
+            ]
           },
           "request": "mutation EnterShoppingCriteria($input: EnterShoppingCriteriaInput!) {\n  enterShoppingCriteria(input: $input) {\n    success\n    error {\n      type\n      message\n    }\n  }\n}",
           "server": {
@@ -250,16 +252,18 @@
           "name": "views suggested items",
           "type": "query",
           "client": {
-            "description": "",
-            "specs": {
-              "name": "Suggested Items Screen",
-              "rules": [
-                "display all suggested items with names and reasons",
-                "show quantity selectors for each item",
-                "have an \"Add to Cart\" button for selected items",
-                "allow removing items from the suggestions"
-              ]
-            }
+            "specs": [
+              {
+                "type": "describe",
+                "title": "Suggested Items Screen",
+                "children": [
+                  { "type": "it", "title": "display all suggested items with names and reasons" },
+                  { "type": "it", "title": "show quantity selectors for each item" },
+                  { "type": "it", "title": "have an \"Add to Cart\" button for selected items" },
+                  { "type": "it", "title": "allow removing items from the suggestions" }
+                ]
+              }
+            ]
           },
           "request": "query GetSuggestedItems($sessionId: ID!) {\n  suggestedItems(sessionId: $sessionId) {\n    items {\n      productId\n      name\n      quantity\n      reason\n    }\n  }\n}",
           "server": {
@@ -362,15 +366,17 @@
           "name": "accepts items and adds to their cart",
           "type": "command",
           "client": {
-            "description": "",
-            "specs": {
-              "name": "Suggested Items Screen",
-              "rules": [
-                "allow selecting specific items to add",
-                "update quantities before adding to cart",
-                "provide feedback when items are added"
-              ]
-            }
+            "specs": [
+              {
+                "type": "describe",
+                "title": "Suggested Items Screen",
+                "children": [
+                  { "type": "it", "title": "allow selecting specific items to add" },
+                  { "type": "it", "title": "update quantities before adding to cart" },
+                  { "type": "it", "title": "provide feedback when items are added" }
+                ]
+              }
+            ]
           },
           "server": {
             "description": "",