@auto-engineer/narrative 0.11.20 → 0.12.1

package/src/schema.ts

@@ -215,17 +215,38 @@ const SpecSchema = z
   })
   .describe('Specification with business rules');
 
+const ItNode = z
+  .object({
+    type: z.literal('it'),
+    id: z.string().optional(),
+    title: z.string(),
+  })
+  .strict();
+
+type ClientSpecNode =
+  | { type: 'it'; id?: string; title: string }
+  | { type: 'describe'; id?: string; title?: string; children?: ClientSpecNode[] };
+
+export const ClientSpecNodeSchema: z.ZodType<ClientSpecNode> = z.lazy(() =>
+  z.union([
+    ItNode,
+    z
+      .object({
+        type: z.literal('describe'),
+        id: z.string().optional(),
+        title: z.string().optional(),
+        children: z.array(ClientSpecNodeSchema).default([]),
+      })
+      .strict(),
+  ]),
+);
+
+export const ClientSpecSchema = z.array(ClientSpecNodeSchema).default([]);
+
 const CommandSliceSchema = BaseSliceSchema.extend({
   type: z.literal('command'),
   client: z.object({
-    description: z.string(),
-    specs: z
-      .object({
-        name: z.string().describe('Spec group name'),
-        rules: z.array(z.string()).describe('UI specifications (should statements)'),
-      })
-      .optional()
-      .describe('Client-side specifications'),
+    specs: ClientSpecSchema,
   }),
   request: z.string().describe('Command request (GraphQL, REST endpoint, or other query format)').optional(),
   server: z.object({
@@ -238,14 +259,7 @@ const CommandSliceSchema = BaseSliceSchema.extend({
 const QuerySliceSchema = BaseSliceSchema.extend({
   type: z.literal('query'),
   client: z.object({
-    description: z.string(),
-    specs: z
-      .object({
-        name: z.string().describe('Spec group name'),
-        rules: z.array(z.string()).describe('UI specifications (should statements)'),
-      })
-      .optional()
-      .describe('Client-side specifications'),
+    specs: ClientSpecSchema,
   }),
   request: z.string().describe('Query request (GraphQL, REST endpoint, or other query format)').optional(),
   server: z.object({
@@ -270,14 +284,7 @@ const ReactSliceSchema = BaseSliceSchema.extend({
 const ExperienceSliceSchema = BaseSliceSchema.extend({
   type: z.literal('experience'),
   client: z.object({
-    description: z.string().optional(),
-    specs: z
-      .object({
-        name: z.string().describe('Spec group name'),
-        rules: z.array(z.string()).describe('UI specifications (should statements)'),
-      })
-      .optional()
-      .describe('Client-side specifications'),
+    specs: ClientSpecSchema,
   }),
 }).describe('Experience slice for user interactions and UI behavior');
 
@@ -387,6 +394,8 @@ export const modelSchema = z
   })
   .describe('Complete system specification with all implementation details');
 
+export type { ClientSpecNode };
+
 export {
   StateExampleSchema,
   MessageFieldSchema,

package/src/slice-builder.ts

@@ -47,7 +47,7 @@ export const createSliceBuilder = (config: SliceConfig = {}): SliceBuilder => ({
     const slice: CommandSlice = {
       type: 'command',
       name,
-      client: { description: '', specs: undefined },
+      client: { specs: [] },
       server: { description: '', specs: { name: '', rules: [] }, data: undefined },
       // Optional fields
       ...(config.eventStream != null && { stream: config.eventStream }),
@@ -66,7 +66,7 @@ export const createSliceBuilder = (config: SliceConfig = {}): SliceBuilder => ({
     const slice: QuerySlice = {
       type: 'query',
       name,
-      client: { description: '', specs: undefined },
+      client: { specs: [] },
       server: { description: '', specs: { name: '', rules: [] }, data: undefined },
       // Optional fields
       ...(config.eventStream != null && { stream: config.eventStream }),

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

@@ -13,6 +13,7 @@ import {
   DataSourceSchema,
   DestinationSchema,
   OriginSchema,
+  type ClientSpecNode,
 } from '../../../schema';
 
 type CommandSlice = z.infer<typeof CommandSliceSchema>;
@@ -27,33 +28,55 @@ type Destination = z.infer<typeof DestinationSchema>;
 type Origin = z.infer<typeof OriginSchema>;
 type Slice = CommandSlice | QuerySlice | ReactSlice | ExperienceSlice;
 
-function buildClientSpecs(
+function buildClientSpecNode(
   ts: typeof import('typescript'),
   f: tsNS.NodeFactory,
-  specs: { name: string; rules: string[] },
-) {
-  const shouldCalls = specs.rules.map((txt) =>
-    f.createExpressionStatement(
-      f.createCallExpression(f.createIdentifier('should'), undefined, [f.createStringLiteral(txt)]),
-    ),
-  );
+  node: ClientSpecNode,
+): tsNS.Statement {
+  if (node.type === 'it') {
+    const args: tsNS.Expression[] = [];
 
-  const arrowFunction = f.createArrowFunction(
-    undefined,
-    undefined,
-    [],
-    undefined,
-    f.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
-    f.createBlock(shouldCalls, true),
-  );
+    if (node.id !== undefined && node.id !== '') {
+      args.push(f.createStringLiteral(node.id));
+      args.push(f.createStringLiteral(node.title));
+    } else {
+      args.push(f.createStringLiteral(node.title));
+    }
+
+    return f.createExpressionStatement(f.createCallExpression(f.createIdentifier('it'), undefined, args));
+  } else {
+    const childStatements = (node.children || []).map((child) => buildClientSpecNode(ts, f, child));
+
+    const args: tsNS.Expression[] = [];
+
+    if (node.id !== undefined && node.id !== '') {
+      args.push(f.createStringLiteral(node.id));
+      args.push(f.createStringLiteral(node.title ?? ''));
+    } else {
+      args.push(f.createStringLiteral(node.title ?? ''));
+    }
+
+    args.push(
+      f.createArrowFunction(
+        undefined,
+        undefined,
+        [],
+        undefined,
+        f.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
+        f.createBlock(childStatements, true),
+      ),
+    );
 
-  const args: tsNS.Expression[] = [];
-  if (specs.name && specs.name.trim() !== '') {
-    args.push(f.createStringLiteral(specs.name));
+    return f.createExpressionStatement(f.createCallExpression(f.createIdentifier('describe'), undefined, args));
   }
-  args.push(arrowFunction);
+}
 
-  return f.createExpressionStatement(f.createCallExpression(f.createIdentifier('specs'), undefined, args));
+function buildClientSpecs(
+  ts: typeof import('typescript'),
+  f: tsNS.NodeFactory,
+  specs: ClientSpecNode[],
+): tsNS.Statement[] {
+  return specs.map((node) => buildClientSpecNode(ts, f, node));
 }
 
 function buildInitialChain(
@@ -347,7 +370,14 @@ function addClientToChain(
   chain: tsNS.Expression,
   slice: CommandSlice | QuerySlice | ReactSlice | ExperienceSlice,
 ): tsNS.Expression {
-  if ('client' in slice && slice.client !== null && slice.client !== undefined && slice.client.specs) {
+  if (
+    'client' in slice &&
+    slice.client !== null &&
+    slice.client !== undefined &&
+    'specs' in slice.client &&
+    slice.client.specs !== undefined &&
+    slice.client.specs.length > 0
+  ) {
     return f.createCallExpression(f.createPropertyAccessExpression(chain, f.createIdentifier('client')), undefined, [
       f.createArrowFunction(
         undefined,
@@ -355,7 +385,7 @@ function addClientToChain(
         [],
         undefined,
         f.createToken(ts.SyntaxKind.EqualsGreaterThanToken),
-        f.createBlock([buildClientSpecs(ts, f, slice.client.specs)], true),
+        f.createBlock(buildClientSpecs(ts, f, slice.client.specs), true),
       ),
     ]);
   }

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

@@ -6,7 +6,8 @@ export const ALL_FLOW_FUNCTION_NAMES = [
   'react',
   'experience',
   'narrative',
-  'should',
+  'describe',
+  'it',
   'specs',
   'rule',
   'example',

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

@@ -129,11 +129,9 @@ function createTypeResolver(
   };
 }
 
-function getSliceSpecs(slice: Slice) {
+function getServerSpecs(slice: Slice) {
   if ('server' in slice && slice.server?.specs !== undefined) {
     return slice.server.specs;
-  } else if ('client' in slice && slice.client?.specs !== undefined) {
-    return slice.client.specs;
   }
   return undefined;
 }
@@ -144,11 +142,10 @@ function processSliceSpecs(
   messages: Map<string, Message>,
   exampleShapeHints: ExampleShapeHints,
 ): void {
-  const spec = getSliceSpecs(slice);
+  const serverSpec = getServerSpecs(slice);
 
-  if (spec !== undefined && Array.isArray(spec.rules)) {
-    spec.rules.forEach((rule: unknown) => {
-      // Only process rule objects (server specs), not string rules (client specs)
+  if (serverSpec !== undefined && Array.isArray(serverSpec.rules)) {
+    serverSpec.rules.forEach((rule: unknown) => {
       if (
         typeof rule === 'object' &&
         rule !== null &&

package/src/transformers/narrative-to-model/type-inference.specs.ts

@@ -13,7 +13,7 @@ describe('Type inference in narrative-to-model transformer', () => {
             id: 'SLICE-001',
             type: 'command',
             name: 'Submit Answer Command',
-            client: { description: 'Submit answer client' },
+            client: { specs: [] },
             server: {
               description: 'Submit answer server',
               specs: {
@@ -59,7 +59,7 @@ describe('Type inference in narrative-to-model transformer', () => {
             id: 'SLICE-002',
             type: 'command',
             name: 'Submit Questionnaire Command',
-            client: { description: 'Submit questionnaire client' },
+            client: { specs: [] },
             server: {
               description: 'Submit questionnaire server',
               specs: {
@@ -132,7 +132,7 @@ describe('Type inference in narrative-to-model transformer', () => {
             id: 'SLICE-001',
             type: 'command',
             name: 'Single Object Command',
-            client: { description: 'Single object client' },
+            client: { specs: [] },
             server: {
               description: 'Single object server',
               specs: {