@pikku/inspector 0.12.43 → 0.12.44

package/src/utils/workflow/dsl/deserialize-roundtrip.test.ts

@@ -0,0 +1,145 @@
+import { strict as assert } from 'assert'
+import { describe, test } from 'node:test'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { inspect } from '../../../inspector.js'
+import type { InspectorLogger } from '../../../types.js'
+import { deserializeDslWorkflow } from './deserialize-dsl-workflow.js'
+
+function makeLogger(): InspectorLogger {
+  return {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    diagnostic: () => {},
+    critical: () => {},
+    hasCriticalErrors: () => false,
+  } as any
+}
+
+const STEP_FILE = [
+  "import { pikkuSessionlessFunc } from '@pikku/core'",
+  'export const discount = pikkuSessionlessFunc({',
+  '  func: async () => ({ amount: 1 }),',
+  '})',
+  'export const notifySales = pikkuSessionlessFunc({',
+  '  func: async () => ({ ok: true }),',
+  '})',
+  'export const provision = pikkuSessionlessFunc({',
+  '  func: async () => ({ ok: true }),',
+  '})',
+  'export const auditLog = pikkuSessionlessFunc({',
+  '  func: async () => ({ ok: true }),',
+  '})',
+].join('\n')
+
+/** Extract a workflow from source, then regenerate its code from the graph. */
+async function roundTrip(body: string): Promise<string> {
+  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-rt-'))
+  const stepFile = join(rootDir, 'w.steps.ts')
+  const wfFile = join(rootDir, 'w.workflow.ts')
+  await writeFile(stepFile, STEP_FILE)
+  await writeFile(
+    wfFile,
+    [
+      "import { pikkuWorkflowFunc } from '@pikku/core/workflow'",
+      'export const wf = pikkuWorkflowFunc(async (_, data: any, { workflow }) => {',
+      body,
+      '})',
+    ].join('\n')
+  )
+  try {
+    const state: any = await inspect(makeLogger(), [stepFile, wfFile], {
+      rootDir,
+    })
+    const gm = state.workflows.graphMeta
+    const graph = (
+      gm instanceof Map ? [...gm.values()] : Object.values(gm)
+    )[0] as any
+    assert.ok(graph, 'a graph should have been produced')
+    return deserializeDslWorkflow(graph)
+  } finally {
+    await rm(rootDir, { recursive: true, force: true })
+  }
+}
+
+describe('DSL round-trip — code must survive graph regeneration', () => {
+  test('every step inside an if-branch survives', async () => {
+    const code = await roundTrip(
+      [
+        '  if (data.total > 100) {',
+        "    await workflow.do('Apply discount', 'discount', {})",
+        "    await workflow.do('Notify sales', 'notifySales', {})",
+        '  }',
+        '  return { ok: true }',
+      ].join('\n')
+    )
+
+    assert.ok(code.includes("'discount'"), 'first branch step should survive')
+    assert.ok(
+      code.includes("'notifySales'"),
+      `second branch step must not be deleted, got:\n${code}`
+    )
+  })
+
+  test('every step inside a switch case survives', async () => {
+    const code = await roundTrip(
+      [
+        '  switch (data.kind) {',
+        "    case 'premium':",
+        "      await workflow.do('Provision premium', 'provision', {})",
+        "      await workflow.do('Audit premium', 'auditLog', {})",
+        '      break',
+        '  }',
+        '  return { ok: true }',
+      ].join('\n')
+    )
+
+    assert.ok(code.includes("'provision'"), 'first case step should survive')
+    assert.ok(
+      code.includes("'auditLog'"),
+      `second case step must not be deleted, got:\n${code}`
+    )
+  })
+
+  test('step names survive — they are the durable replay cache key', async () => {
+    const code = await roundTrip(
+      [
+        "  await workflow.do('Apply discount', 'discount', {})",
+        '  return { ok: true }',
+      ].join('\n')
+    )
+
+    assert.ok(
+      code.includes("'Apply discount'"),
+      `the authored step name must be preserved, got:\n${code}`
+    )
+    assert.ok(
+      !code.includes("'Call discount'"),
+      'the step must not be renamed to the Call <rpc> fallback'
+    )
+  })
+
+  test('a suspend does not dead-end the graph and delete the steps after it', async () => {
+    const code = await roundTrip(
+      [
+        "  await workflow.do('Create draft', 'discount', {})",
+        "  await workflow.suspend('await legal review')",
+        "  await workflow.do('Publish', 'notifySales', {})",
+        '  return { ok: true }',
+      ].join('\n')
+    )
+
+    assert.ok(code.includes("'discount'"), 'step before suspend should survive')
+    assert.ok(
+      code.includes("workflow.suspend('await legal review')"),
+      `the suspend itself must be regenerated, got:\n${code}`
+    )
+    assert.ok(
+      code.includes("'notifySales'"),
+      `steps after a suspend must not be deleted, got:\n${code}`
+    )
+  })
+})

package/src/utils/workflow/dsl/extract-dsl-workflow.ts

@@ -8,6 +8,7 @@ import type {
   FanoutStepMeta,
   CancelStepMeta,
   SuspendStepMeta,
+  SleepStepMeta,
   ApprovalStepMeta,
   SetStepMeta,
   SwitchStepMeta,
@@ -322,12 +323,16 @@ function extractVariableDeclaration(
 ): WorkflowStepMeta | null {
   const declList = statement.declarationList
   if (declList.declarations.length !== 1) {
+    context.errors.push({
+      message: `A single declaration statement may only declare one variable in DSL workflows. Split '${statement.getText().slice(0, 60)}' into separate statements.`,
+      node: statement,
+    })
     return null
   }
 
   const decl = declList.declarations[0]
   if (!ts.isIdentifier(decl.name)) {
-    return null
+    return extractDestructuredDeclaration(statement, decl, context)
   }
 
   const varName = decl.name.text
@@ -437,6 +442,70 @@ function extractVariableDeclaration(
   return null
 }
 
+/**
+ * Extract a declaration whose binding is a destructuring pattern.
+ *
+ * `const [a, b] = await Promise.all([...])` is the idiomatic way to run steps
+ * in parallel and keep both results, so each element of the pattern is bound to
+ * the matching child step's output. Every other destructuring shape reports a
+ * diagnostic rather than silently dropping the step.
+ */
+function extractDestructuredDeclaration(
+  statement: ts.VariableStatement,
+  decl: ts.VariableDeclaration,
+  context: ExtractionContext
+): WorkflowStepMeta | null {
+  const init = decl.initializer
+
+  if (
+    init &&
+    ts.isAwaitExpression(init) &&
+    ts.isCallExpression(init.expression) &&
+    isParallelGroup(init.expression) &&
+    ts.isArrayBindingPattern(decl.name)
+  ) {
+    const elements = decl.name.elements
+    const allSimple = elements.every(
+      (el) =>
+        ts.isBindingElement(el) &&
+        ts.isIdentifier(el.name) &&
+        !el.dotDotDotToken
+    )
+
+    if (allSimple) {
+      const step = extractParallelGroup(init.expression, context)
+      if (step) {
+        if (elements.length !== step.children.length) {
+          context.errors.push({
+            message: `Destructuring binds ${elements.length} name(s) but Promise.all has ${step.children.length} step(s). They must match so each result can be bound to its step.`,
+            node: statement,
+          })
+          return null
+        }
+
+        elements.forEach((el, i) => {
+          const name = (el as ts.BindingElement).name as ts.Identifier
+          const varName = name.text
+          step.children[i].outputVar = varName
+          const type = context.checker.getTypeAtLocation(name)
+          context.outputVars.set(varName, { type, node: name })
+          if (isArrayType(type, context.checker)) {
+            context.arrayVars.add(varName)
+          }
+        })
+
+        return step
+      }
+    }
+  }
+
+  context.errors.push({
+    message: `Destructuring a step result is not supported in DSL workflows. Assign it to a variable first (e.g. \`const result = await workflow.do(...)\`) and read its properties.`,
+    node: statement,
+  })
+  return null
+}
+
 /**
  * Extract expression statement (await workflow.do(...) without assignment)
  */
@@ -478,11 +547,11 @@ function extractExpressionStatement(
               value: literalValue,
             } as SetStepMeta
           }
-          // Non-literal assignment to context var - use expression as string
+          // Non-literal assignment to context var - keep the source expression
           return {
             type: 'set',
             variable: outputVar,
-            value: getSourceText(expr.right),
+            expression: getSourceText(expr.right),
           } as SetStepMeta
         }
       }
@@ -677,6 +746,16 @@ function extractStepOptions(
         } catch {
           // Ignore extraction errors for retryDelay
         }
+      } else if (propName === 'onError') {
+        if (ts.isStringLiteral(prop.initializer)) {
+          options.onError = prop.initializer.text
+        } else {
+          context.errors.push({
+            message:
+              'onError must be a literal RPC name so it can be wired and drawn in the graph.',
+            node: prop.initializer,
+          })
+        }
       } else if (propName === 'description') {
         try {
           options.description = extractStringLiteral(
@@ -714,7 +793,19 @@ function extractSleepStep(
     if (numValue !== null) {
       duration = numValue
     } else {
-      duration = extractStringLiteral(args[1], context.checker)
+      try {
+        duration = extractStringLiteral(args[1], context.checker)
+      } catch {
+        // A duration computed at runtime (a loop variable, a field off the
+        // input) is legal: the closure evaluates it. Record the source text so
+        // the graph can show what it waits on, rather than failing the workflow.
+        return {
+          type: 'sleep',
+          stepName,
+          duration: '',
+          expression: args[1].getText(),
+        }
+      }
     }
 
     return {
@@ -1103,6 +1194,92 @@ function extractArrayPredicate(
   }
 }
 
+/**
+ * Extract an ordered list of workflow.do steps from a per-iteration body.
+ *
+ * Unlike if/switch blocks, a fanout body is a real per-iteration scope, so
+ * `const x = await workflow.do(...)` is meaningful here: the binding is
+ * registered on the child context so later steps in the same iteration can
+ * reference it.
+ */
+function extractFanoutBodyStep(
+  stmt: ts.Statement,
+  childContext: ExtractionContext,
+  body: Array<RpcStepMeta | SleepStepMeta | SuspendStepMeta>
+): void {
+  if (ts.isVariableStatement(stmt)) {
+    const declList = stmt.declarationList
+    if (declList.declarations.length !== 1) {
+      return
+    }
+    const decl = declList.declarations[0]
+    const init = decl.initializer
+    if (
+      !init ||
+      !ts.isAwaitExpression(init) ||
+      !ts.isCallExpression(init.expression)
+    ) {
+      return
+    }
+    const call = init.expression
+    if (!isWorkflowDoCall(call, childContext.checker)) {
+      return
+    }
+    const varName = ts.isIdentifier(decl.name) ? decl.name.text : undefined
+    const step = extractRpcStep(call, childContext, varName)
+    if (!step) {
+      return
+    }
+    if (varName) {
+      const type = childContext.checker.getTypeAtLocation(decl)
+      childContext.outputVars.set(varName, { type, node: decl })
+      if (isArrayType(type, childContext.checker)) {
+        childContext.arrayVars.add(varName)
+      }
+    }
+    body.push(step)
+    return
+  }
+
+  if (ts.isExpressionStatement(stmt) || ts.isReturnStatement(stmt)) {
+    const expr = ts.isReturnStatement(stmt) ? stmt.expression : stmt.expression
+    if (!expr) {
+      return
+    }
+    const call = ts.isAwaitExpression(expr)
+      ? ts.isCallExpression(expr.expression)
+        ? expr.expression
+        : null
+      : ts.isCallExpression(expr)
+        ? expr
+        : null
+    if (!call) {
+      return
+    }
+    if (isWorkflowSleepCall(call, childContext.checker)) {
+      const sleepStep = extractSleepStep(call, childContext)
+      if (sleepStep && sleepStep.type === 'sleep') {
+        body.push(sleepStep)
+      }
+      return
+    }
+    if (isWorkflowSuspendCall(call, childContext.checker)) {
+      const suspendStep = extractSuspendStep(call, childContext)
+      if (suspendStep && suspendStep.type === 'suspend') {
+        body.push(suspendStep)
+      }
+      return
+    }
+    if (!isWorkflowDoCall(call, childContext.checker)) {
+      return
+    }
+    const step = extractRpcStep(call, childContext)
+    if (step) {
+      body.push(step)
+    }
+  }
+}
+
 /**
  * Extract parallel fanout from Promise.all(array.map(...))
  */
@@ -1141,66 +1318,49 @@ function extractParallelFanout(
 
   const itemVar = itemParam.name.text
 
-  // Extract workflow.do call from map body
-  let doCall: ts.CallExpression | null = null
-
-  if (ts.isCallExpression(mapFn.body)) {
-    doCall = mapFn.body
-  } else if (ts.isAwaitExpression(mapFn.body)) {
-    // Handle: async (email) => await workflow.do(...)
-    if (ts.isCallExpression(mapFn.body.expression)) {
-      doCall = mapFn.body.expression
-    }
-  } else if (ts.isBlock(mapFn.body)) {
-    // Look for workflow.do in block
-    for (const stmt of mapFn.body.statements) {
-      if (ts.isExpressionStatement(stmt)) {
-        // Handle: await workflow.do(...)
-        if (
-          ts.isAwaitExpression(stmt.expression) &&
-          ts.isCallExpression(stmt.expression.expression)
-        ) {
-          doCall = stmt.expression.expression
-          break
-        }
-      } else if (ts.isReturnStatement(stmt) && stmt.expression) {
-        if (ts.isCallExpression(stmt.expression)) {
-          doCall = stmt.expression
-          break
-        } else if (ts.isAwaitExpression(stmt.expression)) {
-          // Handle: return await workflow.do(...)
-          if (ts.isCallExpression(stmt.expression.expression)) {
-            doCall = stmt.expression.expression
-            break
-          }
-        }
-      }
-    }
-  }
-
-  if (!doCall || !isWorkflowDoCall(doCall, context.checker)) {
-    return null
-  }
-
-  // Create a temporary context for the child step with the loop variable
+  // Create a temporary context for the child steps with the loop variable
   const childContext: ExtractionContext = {
     ...context,
     outputVars: new Map(context.outputVars),
+    arrayVars: new Set(context.arrayVars),
     loopVars: new Set([...context.loopVars, itemVar]),
   }
 
-  const childStep = extractRpcStep(doCall, childContext)
-  if (!childStep) {
+  const body: FanoutStepMeta['body'] = []
+
+  if (ts.isBlock(mapFn.body)) {
+    for (const stmt of mapFn.body.statements) {
+      extractFanoutBodyStep(stmt, childContext, body)
+    }
+  } else {
+    // Concise body: (item) => workflow.do(...) / async (item) => await workflow.do(...)
+    const expr = mapFn.body
+    const doCall = ts.isAwaitExpression(expr)
+      ? ts.isCallExpression(expr.expression)
+        ? expr.expression
+        : null
+      : ts.isCallExpression(expr)
+        ? expr
+        : null
+
+    if (doCall && isWorkflowDoCall(doCall, context.checker)) {
+      const step = extractRpcStep(doCall, childContext)
+      if (step) {
+        body.push(step)
+      }
+    }
+  }
+
+  if (body.length === 0) {
     return null
   }
 
   return {
     type: 'fanout',
-    stepName: childStep.stepName,
     sourceVar,
     itemVar,
     mode: 'parallel',
-    child: childStep,
+    body,
   }
 }
 
@@ -1255,65 +1415,34 @@ function extractSequentialFanout(
 
   const { itemVar, sourceVar } = vars
 
-  // Extract child step and optional sleep from loop body
-  if (!ts.isBlock(statement.statement)) {
-    return null
-  }
+  // Extract child steps and optional sleep from the loop body. A brace-less
+  // body (`for (const x of xs) await workflow.do(...)`) is a single statement
+  // rather than a block, and must still be extracted.
+  const bodyStatements = ts.isBlock(statement.statement)
+    ? statement.statement.statements
+    : [statement.statement]
 
-  let childStep: RpcStepMeta | null = null
+  const body: FanoutStepMeta['body'] = []
   let timeBetween: string | undefined = undefined
 
   // Create a child context with the loop variable added
   const childContext: ExtractionContext = {
     ...context,
     outputVars: new Map(context.outputVars),
+    arrayVars: new Set(context.arrayVars),
     loopVars: new Set([...context.loopVars, itemVar]),
   }
 
-  let workflowDoCount = 0
+  for (const stmt of bodyStatements) {
+    extractFanoutBodyStep(stmt, childContext, body)
 
-  for (const stmt of statement.statement.statements) {
-    // Look for workflow.do in VariableStatement (const x = await workflow.do(...))
-    if (ts.isVariableStatement(stmt)) {
-      const declList = stmt.declarationList
-      if (declList.declarations.length === 1) {
-        const decl = declList.declarations[0]
-        const init = decl.initializer
-        if (
-          init &&
-          ts.isAwaitExpression(init) &&
-          ts.isCallExpression(init.expression)
-        ) {
-          const call = init.expression
-          if (isWorkflowDoCall(call, context.checker)) {
-            workflowDoCount++
-            const varName = ts.isIdentifier(decl.name)
-              ? decl.name.text
-              : undefined
-            const step = extractRpcStep(call, childContext, varName)
-            if (step) {
-              childStep = step
-            }
-          }
-        }
-      }
-    }
-
-    // Look for workflow.do in ExpressionStatement (await workflow.do(...))
+    // Look for workflow.sleep in ExpressionStatement
     if (ts.isExpressionStatement(stmt)) {
       const expr = stmt.expression
 
       if (ts.isAwaitExpression(expr) && ts.isCallExpression(expr.expression)) {
         const call = expr.expression
 
-        if (isWorkflowDoCall(call, context.checker)) {
-          workflowDoCount++
-          const step = extractRpcStep(call, childContext)
-          if (step) {
-            childStep = step
-          }
-        }
-
         if (isWorkflowSleepCall(call, context.checker)) {
           // Extract duration for timeBetween
           const args = call.arguments
@@ -1371,26 +1500,16 @@ function extractSequentialFanout(
     }
   }
 
-  if (!childStep) {
-    return null
-  }
-
-  // If there are multiple workflow.do calls, the loop is too complex for DSL
-  if (workflowDoCount > 1) {
-    context.errors.push({
-      message: `For-of loop has ${workflowDoCount} workflow.do calls but DSL only supports 1. Use pikkuWorkflowComplexFunc for complex loops.`,
-      node: statement,
-    })
+  if (body.length === 0) {
     return null
   }
 
   return {
     type: 'fanout',
-    stepName: childStep.stepName,
     sourceVar,
     itemVar,
     mode: 'sequential',
-    child: childStep,
+    body,
     timeBetween,
   }
 }
@@ -1493,11 +1612,21 @@ function extractReturn(
     }
   }
 
+  // `return r` returns every field of r — record it as a spread of one.
+  if (ts.isIdentifier(statement.expression)) {
+    const varName = statement.expression.text
+    if (context.outputVars.has(varName) || context.contextVars.has(varName)) {
+      return { type: 'return', outputs: {}, spread: [varName] }
+    }
+    return null
+  }
+
   if (!ts.isObjectLiteralExpression(statement.expression)) {
     return null
   }
 
   const outputs: Record<string, OutputBinding> = {}
+  const spread: string[] = []
 
   for (const prop of statement.expression.properties) {
     if (
@@ -1528,16 +1657,22 @@ function extractReturn(
       if (binding) {
         outputs[propName] = binding
       }
+    } else if (
+      ts.isSpreadAssignment(prop) &&
+      ts.isIdentifier(prop.expression)
+    ) {
+      spread.push(prop.expression.text)
     }
   }
 
-  if (Object.keys(outputs).length === 0) {
+  if (Object.keys(outputs).length === 0 && spread.length === 0) {
     return null
   }
 
   return {
     type: 'return',
     outputs,
+    ...(spread.length > 0 ? { spread } : {}),
   }
 }
 
@@ -1652,6 +1787,11 @@ function extractInputSource(
         return { from: 'input', path: propName }
       }
 
+      // A field of the fanout item: users.map((u) => do(..., { id: u.id }))
+      if (context.loopVars.has(objName)) {
+        return { from: 'item', path: propName }
+      }
+
       if (context.outputVars.has(objName)) {
         return { from: 'outputVar', name: objName, path: propName }
       }