@pikku/inspector 0.12.74 → 0.12.81

package/src/utils/workflow/graph/convert-dsl-to-graph.ts

@@ -1,543 +0,0 @@
-/**
- * Converts DSL (Domain Specific Language) step-based format to graph node format
- */
-import type { WorkflowStepMeta, WorkflowsMeta } from '@pikku/core/workflow'
-import type {
-  SerializedGraphNode,
-  SerializedWorkflowGraph,
-  FunctionNode,
-  FlowNode,
-  DataRef,
-} from './workflow-graph.types.js'
-
-function makeNodeId(
-  step: WorkflowStepMeta,
-  index: number,
-  prefix: string
-): string {
-  if ('stepName' in step && step.stepName) {
-    return step.stepName
-  }
-  return `${prefix}_${index}`
-}
-
-/**
- * Check if a node is a terminal flow (no next step should follow)
- */
-function isTerminalFlow(node: SerializedGraphNode): boolean {
-  if ('flow' in node) {
-    // Cancel and return are terminal flows - they end execution
-    return node.flow === 'cancel' || node.flow === 'return'
-  }
-  return false
-}
-
-/**
- * Convert InputSource to DataRef
- */
-function convertInputSource(source: {
-  from: string
-  path?: string
-  name?: string
-  value?: unknown
-  parts?: string[]
-  expressions?: unknown[]
-}): unknown | DataRef {
-  if (source.from === 'literal') {
-    return source.value
-  }
-  if (source.from === 'input') {
-    return { $ref: 'trigger', path: source.path }
-  }
-  if (source.from === 'outputVar') {
-    return { $ref: source.name!, path: source.path }
-  }
-  if (source.from === 'item') {
-    return { $ref: '$item', path: source.path }
-  }
-  if (source.from === 'stateVar') {
-    return { $state: source.name!, path: source.path }
-  }
-  if (source.from === 'template') {
-    return {
-      $template: {
-        parts: source.parts,
-        expressions: source.expressions?.map((expr) =>
-          convertInputSource(expr as any)
-        ),
-      },
-    }
-  }
-  return source.value
-}
-
-/**
- * Convert a single DSL step to graph node(s)
- */
-function convertStepToNode(
-  step: WorkflowStepMeta,
-  index: number,
-  steps: WorkflowStepMeta[],
-  nodeIdPrefix: string = 'step'
-): SerializedGraphNode[] {
-  const nodeId = makeNodeId(step, index, nodeIdPrefix)
-  const nextNodeId =
-    index < steps.length - 1
-      ? makeNodeId(steps[index + 1], index + 1, nodeIdPrefix)
-      : undefined
-
-  switch (step.type) {
-    case 'rpc': {
-      const node: FunctionNode = {
-        nodeId,
-        rpcName: step.rpcName,
-        stepName: step.stepName,
-        next: nextNodeId,
-      }
-      if (step.actor) {
-        node.actor = step.actor
-      }
-      if (step.expectEventually) {
-        node.expectEventually = true
-      }
-      if (step.inputs) {
-        if (step.inputs === 'passthrough') {
-          // Entire data is passed through - store as reference to trigger
-          node.input = { $passthrough: { $ref: 'trigger' } }
-        } else {
-          node.input = {}
-          for (const [key, source] of Object.entries(step.inputs)) {
-            node.input[key] = convertInputSource(source as any)
-          }
-        }
-      }
-      if (step.outputVar) {
-        node.outputVar = step.outputVar
-      }
-      if (step.options) {
-        node.options = {
-          retries: step.options.retries,
-          retryDelay: step.options.retryDelay,
-        }
-      }
-      // An onError handler is written as an rpc name, but the graph routes to
-      // node ids — materialise a node for it so the console has something to
-      // draw the error edge to, exactly as in a hand-authored graph.
-      if (step.options?.onError) {
-        const handlerId = `${nodeId}_onError`
-        node.onError = handlerId
-        return [
-          node,
-          {
-            nodeId: handlerId,
-            rpcName: step.options.onError,
-            stepName: `${step.stepName} (on error)`,
-          } satisfies FunctionNode,
-        ]
-      }
-      return [node]
-    }
-
-    // A declared step is a function node like any other — the console draws it
-    // the same way, with the phase available for the "Given/When/Then" prose.
-    case 'scenarioStep': {
-      const node: FunctionNode = {
-        nodeId,
-        rpcName: step.stepFunc,
-        stepName: step.stepName,
-        scenarioStepPhase: step.phase,
-        next: nextNodeId,
-      }
-      if (step.actor) {
-        node.actor = step.actor
-      }
-      if (step.inputs) {
-        if (step.inputs === 'passthrough') {
-          node.input = { $passthrough: { $ref: 'trigger' } }
-        } else {
-          node.input = {}
-          for (const [key, source] of Object.entries(step.inputs)) {
-            node.input[key] = convertInputSource(source as any)
-          }
-        }
-      }
-      if (step.outputVar) {
-        node.outputVar = step.outputVar
-      }
-      if (step.options) {
-        node.options = {
-          retries: step.options.retries,
-          retryDelay: step.options.retryDelay,
-        }
-      }
-      return [node]
-    }
-
-    case 'sleep': {
-      const node: FlowNode = {
-        nodeId,
-        flow: 'sleep',
-        stepName: step.stepName,
-        duration: step.duration,
-        expression: step.expression,
-        next: nextNodeId,
-      }
-      return [node]
-    }
-
-    case 'suspend': {
-      // A suspend yields no value, but it must still be a node: the previous
-      // step's `next` points at it, so omitting it dead-ends traversal and
-      // silently deletes every step that follows.
-      const node: FlowNode = {
-        nodeId,
-        flow: 'suspend',
-        reason: step.reason,
-        next: nextNodeId,
-      }
-      return [node]
-    }
-
-    case 'approval': {
-      // Unlike `suspend` — which has no output and so is deliberately absent
-      // from the graph — an approval yields a value a later step can reference,
-      // so it must be a real node for $ref resolution and graphHash to see it.
-      const node: FlowNode = {
-        nodeId,
-        flow: 'approval',
-        reason: step.reason,
-        outputVar: step.outputVar,
-        expiry: step.expiry,
-        next: nextNodeId,
-      }
-      return [node]
-    }
-
-    case 'inline': {
-      const node: FlowNode = {
-        nodeId,
-        flow: 'inline',
-        description: step.description,
-        next: nextNodeId,
-      }
-      return [node]
-    }
-
-    case 'branch': {
-      // Convert all branch conditions (if/else-if chain)
-      const branchNodes: SerializedGraphNode[] = []
-      const branches: Array<{
-        condition: unknown
-        entry: string
-      }> = []
-
-      for (let i = 0; i < step.branches.length; i++) {
-        const branchSteps = convertStepsToNodes(
-          step.branches[i].steps,
-          `${nodeId}_branch${i}`
-        )
-        if (branchSteps.length > 0) {
-          branches.push({
-            condition: step.branches[i].condition,
-            entry: branchSteps[0].nodeId,
-          })
-          // Link last branch node back to next (unless terminal flow)
-          if (nextNodeId) {
-            const lastBranch = branchSteps[branchSteps.length - 1]
-            if (!lastBranch.next && !isTerminalFlow(lastBranch))
-              lastBranch.next = nextNodeId
-          }
-          branchNodes.push(...branchSteps)
-        }
-      }
-
-      // Convert else branch
-      const elseNodes = step.elseSteps
-        ? convertStepsToNodes(step.elseSteps, `${nodeId}_else`)
-        : []
-      if (elseNodes.length > 0 && nextNodeId) {
-        const lastElse = elseNodes[elseNodes.length - 1]
-        if (!lastElse.next && !isTerminalFlow(lastElse))
-          lastElse.next = nextNodeId
-      }
-
-      const node: FlowNode = {
-        nodeId,
-        flow: 'branch',
-        branches,
-        elseEntry: elseNodes.length > 0 ? elseNodes[0].nodeId : undefined,
-        next: nextNodeId,
-      }
-
-      return [node, ...branchNodes, ...elseNodes]
-    }
-
-    case 'switch': {
-      const caseNodes: SerializedGraphNode[] = []
-      const cases: Array<{
-        value?: unknown
-        expression?: string
-        entry: string
-      }> = []
-
-      // A case with no statements falls through to the next one. Dropping it
-      // would lose the value entirely, so it is held until an entry exists.
-      let fallingThrough: Array<{ value?: unknown; expression?: string }> = []
-
-      for (let i = 0; i < step.cases.length; i++) {
-        const caseSteps = convertStepsToNodes(
-          step.cases[i].steps,
-          `${nodeId}_case${i}`
-        )
-        if (caseSteps.length === 0) {
-          fallingThrough.push({
-            value: step.cases[i].value,
-            expression: step.cases[i].expression,
-          })
-          continue
-        }
-        {
-          const entry = caseSteps[0].nodeId
-          for (const pending of fallingThrough) {
-            cases.push({ ...pending, entry })
-          }
-          fallingThrough = []
-          cases.push({
-            value: step.cases[i].value,
-            expression: step.cases[i].expression,
-            entry,
-          })
-          // Link last case node to next (unless terminal flow)
-          if (nextNodeId) {
-            const lastCase = caseSteps[caseSteps.length - 1]
-            if (!lastCase.next && !isTerminalFlow(lastCase))
-              lastCase.next = nextNodeId
-          }
-          caseNodes.push(...caseSteps)
-        }
-      }
-
-      let defaultEntry: string | undefined
-      if (step.defaultSteps) {
-        const defaultNodes = convertStepsToNodes(
-          step.defaultSteps,
-          `${nodeId}_default`
-        )
-        if (defaultNodes.length > 0) {
-          defaultEntry = defaultNodes[0].nodeId
-          // Link last default node to next (unless terminal flow)
-          if (nextNodeId) {
-            const lastDefault = defaultNodes[defaultNodes.length - 1]
-            if (!lastDefault.next && !isTerminalFlow(lastDefault))
-              lastDefault.next = nextNodeId
-          }
-          caseNodes.push(...defaultNodes)
-        }
-      }
-
-      // Cases falling through past the last one land in default, or exit.
-      const trailingEntry = defaultEntry ?? nextNodeId
-      if (trailingEntry) {
-        for (const pending of fallingThrough) {
-          cases.push({ ...pending, entry: trailingEntry })
-        }
-      }
-
-      const node: FlowNode = {
-        nodeId,
-        flow: 'switch',
-        expression: step.expression,
-        cases,
-        defaultEntry,
-        next: nextNodeId,
-      }
-
-      return [node, ...caseNodes]
-    }
-
-    case 'parallel': {
-      // Convert children to nodes
-      const childNodes: SerializedGraphNode[] = []
-      const childEntries: string[] = []
-
-      for (let i = 0; i < step.children.length; i++) {
-        const childSteps = convertStepToNode(
-          step.children[i],
-          i,
-          step.children,
-          `${nodeId}_child`
-        )
-        if (childSteps.length > 0) {
-          childEntries.push(childSteps[0].nodeId)
-          childNodes.push(...childSteps)
-        }
-      }
-
-      const node: FlowNode = {
-        nodeId,
-        flow: 'parallel',
-        children: childEntries,
-        next: nextNodeId,
-      }
-
-      return [node, ...childNodes]
-    }
-
-    case 'fanout': {
-      // Convert the per-iteration body into a `next`-chained sequence
-      const childNodes: SerializedGraphNode[] = []
-      for (let i = 0; i < step.body.length; i++) {
-        childNodes.push(
-          ...convertStepToNode(step.body[i], i, step.body, `${nodeId}_item`)
-        )
-      }
-
-      const node: FlowNode = {
-        nodeId,
-        flow: 'fanout',
-        sourceVar: step.sourceVar,
-        itemVar: step.itemVar,
-        mode: step.mode,
-        childEntry: childNodes.length > 0 ? childNodes[0].nodeId : undefined,
-        timeBetween: step.timeBetween,
-        next: nextNodeId,
-      }
-
-      return [node, ...childNodes]
-    }
-
-    case 'filter': {
-      const node: FlowNode = {
-        nodeId,
-        flow: 'filter',
-        sourceVar: step.sourceVar,
-        itemVar: step.itemVar,
-        condition: step.condition,
-        outputVar: step.outputVar,
-        next: nextNodeId,
-      }
-      return [node]
-    }
-
-    case 'arrayPredicate': {
-      const node: FlowNode = {
-        nodeId,
-        flow: 'arrayPredicate',
-        mode: step.mode,
-        sourceVar: step.sourceVar,
-        itemVar: step.itemVar,
-        condition: step.condition,
-        outputVar: step.outputVar,
-        next: nextNodeId,
-      }
-      return [node]
-    }
-
-    case 'return': {
-      const node: FlowNode = {
-        nodeId,
-        flow: 'return',
-        outputs: step.outputs,
-        spread: step.spread,
-      }
-      return [node]
-    }
-
-    case 'cancel': {
-      const node: FlowNode = {
-        nodeId,
-        flow: 'cancel',
-        reason: step.reason,
-      }
-      return [node]
-    }
-
-    case 'set': {
-      const node: FlowNode = {
-        nodeId,
-        flow: 'set',
-        variable: step.variable,
-        value: step.value,
-        expression: step.expression,
-        next: nextNodeId,
-      }
-      return [node]
-    }
-
-    default:
-      return []
-  }
-}
-
-/**
- * Convert array of steps to graph nodes
- */
-function convertStepsToNodes(
-  steps: WorkflowStepMeta[],
-  nodeIdPrefix: string = 'step'
-): SerializedGraphNode[] {
-  const allNodes: SerializedGraphNode[] = []
-
-  for (let i = 0; i < steps.length; i++) {
-    const nodes = convertStepToNode(steps[i], i, steps, nodeIdPrefix)
-    allNodes.push(...nodes)
-  }
-
-  return allNodes
-}
-
-/**
- * Convert a DSL workflow to graph format
- */
-export function convertDslToGraph(
-  workflowName: string,
-  meta: WorkflowsMeta[string]
-): SerializedWorkflowGraph {
-  const nodes = convertStepsToNodes(meta.steps)
-  const nodesRecord: Record<string, SerializedGraphNode> = {}
-
-  for (const node of nodes) {
-    nodesRecord[node.nodeId] = node
-  }
-
-  const entryNodeIds = nodes.length > 0 ? [nodes[0].nodeId] : []
-
-  // Determine source type:
-  // - scenario: complex workflow whose steps run as actors (scenario)
-  // - dsl === true: pure DSL workflow, can be serialized
-  // - dsl === false: complex workflow with inline steps, not serializable
-  const source = meta.scenario
-    ? 'scenario'
-    : meta.dsl === false
-      ? 'complex'
-      : 'dsl'
-
-  return {
-    name: workflowName,
-    pikkuFuncId: meta.pikkuFuncId,
-    source,
-    title: meta.title,
-    description: meta.description,
-    tags: meta.tags,
-    skip: meta.skip,
-    actors: meta.actors,
-    context: meta.context,
-    nodes: nodesRecord,
-    entryNodeIds,
-  }
-}
-
-/**
- * Convert all DSL workflows to graph format
- */
-export function convertAllDslToGraphs(
-  workflowsMeta: WorkflowsMeta
-): Record<string, SerializedWorkflowGraph> {
-  const result: Record<string, SerializedWorkflowGraph> = {}
-
-  for (const [name, meta] of Object.entries(workflowsMeta)) {
-    result[name] = convertDslToGraph(name, meta)
-  }
-
-  return result
-}

package/src/utils/workflow/graph/fanout-node-identity.test.ts

@@ -1,105 +0,0 @@
-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'
-
-const STEP_FILE = [
-  "import { pikkuSessionlessFunc } from '@pikku/core'",
-  'export const notify = pikkuSessionlessFunc({',
-  "  func: async () => ({ id: 'n' }),",
-  '})',
-].join('\n')
-
-async function nodesFor(body: string): Promise<Record<string, any>> {
-  const logger = {
-    debug: () => {},
-    info: () => {},
-    warn: () => {},
-    error: () => {},
-    diagnostic: () => {},
-    critical: () => {},
-    hasCriticalErrors: () => false,
-  } as unknown as InspectorLogger
-
-  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-fid-'))
-  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(logger, [stepFile, wfFile], { rootDir })
-    const gm = state.workflows.graphMeta
-    const graph = (
-      gm instanceof Map ? [...gm.values()] : Object.values(gm)
-    )[0] as any
-    return graph?.nodes ?? {}
-  } finally {
-    await rm(rootDir, { recursive: true, force: true })
-  }
-}
-
-describe('fanout node identity — a body step must not overwrite its own loop', () => {
-  test('the fanout node survives alongside its named body step', async () => {
-    const nodes = await nodesFor(
-      [
-        '  await Promise.all(',
-        '    data.users.map(async (u: any) => {',
-        "      await workflow.do('Notify', 'notify', { id: u.id })",
-        '    })',
-        '  )',
-        '  return { ok: true }',
-      ].join('\n')
-    )
-
-    const fanout = Object.values(nodes).find(
-      (n: any) => n.flow === 'fanout'
-    ) as any
-    assert.ok(
-      fanout,
-      `the loop must be in the graph — without it the workflow renders as a single call, got: ${JSON.stringify(nodes)}`
-    )
-    assert.ok(
-      fanout.childEntry && nodes[fanout.childEntry],
-      'the fanout must point at a body entry node that exists'
-    )
-    assert.notEqual(
-      fanout.nodeId,
-      fanout.childEntry,
-      'a fanout and its body entry must not share a node id'
-    )
-    assert.equal((nodes[fanout.childEntry] as any).rpcName, 'notify')
-  })
-
-  test('the step following a fanout is still reachable', async () => {
-    const nodes = await nodesFor(
-      [
-        '  await Promise.all(',
-        '    data.users.map(async (u: any) => {',
-        "      await workflow.do('Notify', 'notify', { id: u.id })",
-        '    })',
-        '  )',
-        '  return { ok: true }',
-      ].join('\n')
-    )
-
-    const fanout = Object.values(nodes).find(
-      (n: any) => n.flow === 'fanout'
-    ) as any
-    assert.ok(fanout, 'a fanout node should exist')
-    assert.ok(
-      fanout.next && nodes[fanout.next],
-      `the return after the loop must stay reachable, got: ${JSON.stringify(nodes)}`
-    )
-  })
-})