@pikku/inspector 0.12.43 → 0.12.45

package/src/add/add-workflow-edge-cases.test.ts

@@ -0,0 +1,201 @@
+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 '../utils/workflow/dsl/deserialize-dsl-workflow.js'
+
+const STEP_FILE = [
+  "import { pikkuSessionlessFunc } from '@pikku/core'",
+  'export const chargeCard = pikkuSessionlessFunc({',
+  "  func: async () => ({ id: 'c' }),",
+  '})',
+  'export const refundOrder = pikkuSessionlessFunc({',
+  "  func: async () => ({ id: 'r' }),",
+  '})',
+  'export const notify = pikkuSessionlessFunc({',
+  "  func: async () => ({ id: 'n' }),",
+  '})',
+  'export const audit = pikkuSessionlessFunc({',
+  "  func: async () => ({ id: 'a' }),",
+  '})',
+].join('\n')
+
+async function run(body: string): Promise<{
+  nodes: Record<string, any>
+  diags: string[]
+  code: string
+}> {
+  const diags: string[] = []
+  const logger = {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    diagnostic: (...a: any[]) => diags.push(a.map(String).join(' ')),
+    critical: (...a: any[]) => diags.push(a.map(String).join(' ')),
+    hasCriticalErrors: () => false,
+  } as unknown as InspectorLogger
+
+  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-edge-'))
+  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 {
+      nodes: graph?.nodes ?? {},
+      diags,
+      code: graph ? deserializeDslWorkflow(graph) : '',
+    }
+  } finally {
+    await rm(rootDir, { recursive: true, force: true })
+  }
+}
+
+describe('onError — edge cases', () => {
+  test('the handler is not also emitted as a step that always runs', async () => {
+    const { code } = await run(
+      [
+        "  await workflow.do('Charge', 'chargeCard', {}, { onError: 'refundOrder' })",
+        '  return { ok: true }',
+      ].join('\n')
+    )
+
+    const refundCalls = code.match(/'refundOrder'/g) ?? []
+    assert.equal(
+      refundCalls.length,
+      1,
+      `the handler must appear only as onError, never as its own sequential step, got:\n${code}`
+    )
+  })
+
+  test('a non-literal onError is reported, not silently ignored', async () => {
+    const { diags } = await run(
+      [
+        '  const target = data.handler',
+        "  await workflow.do('Charge', 'chargeCard', {}, { onError: target })",
+        '  return { ok: true }',
+      ].join('\n')
+    )
+
+    assert.ok(
+      diags.some((d) => d.includes('onError')),
+      `a non-literal onError must be diagnosed, got: ${JSON.stringify(diags)}`
+    )
+  })
+
+  test('onError inside a branch still resolves', async () => {
+    const { nodes } = await run(
+      [
+        '  if (data.paid) {',
+        "    await workflow.do('Charge', 'chargeCard', {}, { onError: 'refundOrder' })",
+        '  }',
+        '  return { ok: true }',
+      ].join('\n')
+    )
+
+    const charge = Object.values(nodes).find(
+      (n: any) => n.rpcName === 'chargeCard'
+    ) as any
+    assert.ok(
+      charge?.onError,
+      'a branch step should still carry its error route'
+    )
+    assert.equal((nodes[charge.onError] as any)?.rpcName, 'refundOrder')
+  })
+})
+
+describe('switch — fall-through to default', () => {
+  test('a trailing empty case routes to the default body', async () => {
+    const { nodes } = await run(
+      [
+        '  switch (data.kind) {',
+        "    case 'a':",
+        "      await workflow.do('Notify', 'notify', {})",
+        '      break',
+        "    case 'b':",
+        '    default:',
+        "      await workflow.do('Audit', 'audit', {})",
+        '  }',
+        '  return { ok: true }',
+      ].join('\n')
+    )
+
+    const sw = Object.values(nodes).find((n: any) => n.flow === 'switch') as any
+    assert.ok(sw, 'a switch node should exist')
+    const caseB = (sw.cases ?? []).find((c: any) => c.value === 'b')
+    assert.ok(
+      caseB,
+      `a case falling through to default must not be dropped, got: ${JSON.stringify(sw.cases)}`
+    )
+    assert.equal(
+      caseB.entry,
+      sw.defaultEntry,
+      'it should route to the default body it falls into'
+    )
+  })
+})
+
+describe('options — numeric values keep their type', () => {
+  test('a numeric retryDelay is not quoted', async () => {
+    const { code } = await run(
+      [
+        "  await workflow.do('Charge', 'chargeCard', {}, { retries: 2, retryDelay: 500 })",
+        '  return { ok: true }',
+      ].join('\n')
+    )
+
+    assert.ok(
+      code.includes('retryDelay: 500'),
+      `a numeric retryDelay must stay numeric, got:\n${code}`
+    )
+  })
+})
+
+describe('sequential fanout — for..of bodies', () => {
+  test('a multi-step for..of body keeps every step', async () => {
+    const { nodes } = await run(
+      [
+        '  for (const u of data.users) {',
+        "    const c = await workflow.do('Charge', 'chargeCard', { id: u.id })",
+        "    await workflow.do('Notify', 'notify', { id: c.id })",
+        '  }',
+        '  return { ok: true }',
+      ].join('\n')
+    )
+
+    const fanout = Object.values(nodes).find(
+      (n: any) => n.flow === 'fanout'
+    ) as any
+    assert.ok(fanout, 'a for..of should produce a fanout node')
+    assert.notEqual(
+      fanout.nodeId,
+      fanout.childEntry,
+      'the loop and its body entry must not share an id'
+    )
+
+    const rpcs = Object.values(nodes)
+      .filter((n: any) => n.rpcName)
+      .map((n: any) => n.rpcName)
+    assert.ok(
+      rpcs.includes('chargeCard') && rpcs.includes('notify'),
+      `both body steps must survive, got: ${JSON.stringify(rpcs)}`
+    )
+  })
+})

package/src/add/add-workflow-fanout.test.ts

@@ -103,4 +103,64 @@ describe('addWorkflow — Promise.all fanout RPC detection', () => {
       await rm(rootDir, { recursive: true, force: true })
     }
   })
+
+  test('registers every RPC in a multi-step map body, including a `const`-captured step feeding the next', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-fanout-multi-'))
+    const wfFile = join(rootDir, 'digest.workflow.ts')
+    const stepFile = join(rootDir, 'digest.steps.ts')
+
+    await writeFile(
+      stepFile,
+      [
+        "import { pikkuSessionlessFunc } from '@pikku/core'",
+        'export const getDigestData = pikkuSessionlessFunc({',
+        '  func: async ({ logger }) => ({ dealsByStage: {}, totalDealValue: 0 }),',
+        '})',
+        'export const sendDigestEmail = pikkuSessionlessFunc({',
+        '  func: async ({ logger }) => ({ sent: true }),',
+        '})',
+      ].join('\n')
+    )
+    await writeFile(
+      wfFile,
+      [
+        "import { pikkuWorkflowFunc } from '@pikku/core/workflow'",
+        'export const dailyDigestWorkflow = pikkuWorkflowFunc(async (_, data, { workflow }) => {',
+        '  const users = [{ id: "1", email: "a@b.c" }]',
+        '  await Promise.all(',
+        '    users.map(async (u) => {',
+        '      const digestData = await workflow.do(',
+        '        `Get pipeline for ${u.email}`,',
+        "        'getDigestData',",
+        '        { userId: u.id },',
+        '      )',
+        "      await workflow.do(`Send digest to ${u.email}`, 'sendDigestEmail', {",
+        '        email: u.email,',
+        '        dealsByStage: digestData.dealsByStage,',
+        '        totalDealValue: digestData.totalDealValue,',
+        '      })',
+        '    }),',
+        '  )',
+        '  return { sent: users.length }',
+        '})',
+      ].join('\n')
+    )
+
+    const criticals: Array<{ code: string; message: string }> = []
+    try {
+      const state = await inspect(makeLogger(criticals), [stepFile, wfFile], {
+        rootDir,
+      })
+      assert.ok(
+        state.rpc.invokedFunctions.has('sendDigestEmail'),
+        'sendDigestEmail should be registered'
+      )
+      assert.ok(
+        state.rpc.invokedFunctions.has('getDigestData'),
+        'getDigestData should be registered — a `const`-captured workflow.do inside the map body must not be dropped'
+      )
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
 })

package/src/add/add-workflow-on-error.test.ts

@@ -0,0 +1,118 @@
+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 '../utils/workflow/dsl/deserialize-dsl-workflow.js'
+
+const STEP_FILE = [
+  "import { pikkuSessionlessFunc } from '@pikku/core'",
+  'export const chargeCard = pikkuSessionlessFunc({',
+  "  func: async () => ({ id: 'c' }),",
+  '})',
+  'export const refundOrder = pikkuSessionlessFunc({',
+  "  func: async () => ({ id: 'r' }),",
+  '})',
+].join('\n')
+
+const WORKFLOW_BODY = [
+  "  await workflow.do('Charge', 'chargeCard', { id: data.id }, {",
+  '    retries: 3,',
+  "    onError: 'refundOrder',",
+  '  })',
+  '  return { ok: true }',
+].join('\n')
+
+async function inspectWorkflow(body: string): Promise<{
+  nodes: Record<string, any>
+  invoked: string[]
+  code: string
+}> {
+  const logger = {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    diagnostic: () => {},
+    critical: () => {},
+    hasCriticalErrors: () => false,
+  } as unknown as InspectorLogger
+
+  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-oe-'))
+  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
+    assert.ok(graph, 'a graph should have been produced')
+    return {
+      nodes: graph.nodes,
+      invoked: [...(state.rpc?.invokedFunctions ?? [])],
+      code: deserializeDslWorkflow(graph),
+    }
+  } finally {
+    await rm(rootDir, { recursive: true, force: true })
+  }
+}
+
+describe('DSL onError — compensation is part of the graph', () => {
+  test('the handler becomes a node the failing step points at', async () => {
+    const { nodes } = await inspectWorkflow(WORKFLOW_BODY)
+
+    const charge = Object.values(nodes).find(
+      (n: any) => n.rpcName === 'chargeCard'
+    ) as any
+    assert.ok(charge, 'the charging step should exist')
+    assert.ok(
+      charge.onError,
+      `the step must record its error route so the graph can render it, got: ${JSON.stringify(charge)}`
+    )
+
+    const handlerId = Array.isArray(charge.onError)
+      ? charge.onError[0]
+      : charge.onError
+    const handler = nodes[handlerId]
+    assert.ok(
+      handler,
+      `onError must point at a real node so an edge can be drawn, got id '${handlerId}' in ${JSON.stringify(Object.keys(nodes))}`
+    )
+    assert.equal(handler.rpcName, 'refundOrder')
+  })
+
+  test('the handler RPC is registered as invoked so it gets wired', async () => {
+    const { invoked } = await inspectWorkflow(WORKFLOW_BODY)
+
+    assert.ok(
+      invoked.includes('refundOrder'),
+      `the compensation RPC must be wired, got: ${JSON.stringify(invoked)}`
+    )
+  })
+
+  test('onError survives regeneration back to code', async () => {
+    const { code } = await inspectWorkflow(WORKFLOW_BODY)
+
+    assert.ok(
+      code.includes("onError: 'refundOrder'"),
+      `onError must round-trip as an rpc name, got:\n${code}`
+    )
+    assert.ok(
+      code.includes('retries: 3'),
+      'other options must still round-trip'
+    )
+  })
+})

package/src/add/add-workflow-return-switch.test.ts

@@ -0,0 +1,121 @@
+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 ship = pikkuSessionlessFunc({',
+  "  func: async () => ({ id: 's', ok: true }),",
+  '})',
+].join('\n')
+
+async function inspectWorkflow(body: string): Promise<{
+  nodes: Record<string, any>
+  diags: string[]
+}> {
+  const diags: string[] = []
+  const logger = {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    diagnostic: (d: any) => diags.push(d?.message ?? String(d)),
+    critical: (d: any) => diags.push(d?.message ?? String(d)),
+    hasCriticalErrors: () => false,
+  } as unknown as InspectorLogger
+
+  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-rs-'))
+  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 { nodes: graph?.nodes ?? {}, diags }
+  } finally {
+    await rm(rootDir, { recursive: true, force: true })
+  }
+}
+
+describe('switch extraction — a fall-through case is a real case', () => {
+  test("case 'a': case 'b': records both values", async () => {
+    const { nodes } = await inspectWorkflow(
+      [
+        '  switch (data.kind) {',
+        "    case 'a':",
+        "    case 'b':",
+        "      await workflow.do('Ship', 'ship', {})",
+        '      break',
+        '  }',
+        '  return { ok: true }',
+      ].join('\n')
+    )
+
+    const switchNode = Object.values(nodes).find(
+      (n: any) => n.flow === 'switch'
+    ) as any
+    assert.ok(switchNode, 'a switch node should exist')
+    const values = (switchNode.cases ?? []).map((c: any) => c.value)
+    assert.deepEqual(
+      values.sort(),
+      ['a', 'b'],
+      `a fall-through case must not be dropped, got: ${JSON.stringify(switchNode.cases)}`
+    )
+    const entries = new Set((switchNode.cases ?? []).map((c: any) => c.entry))
+    assert.equal(entries.size, 1, 'both cases should share the same entry')
+  })
+})
+
+describe('return extraction — a spread output is not silently dropped', () => {
+  test('return { ...r, extra } keeps the spread', async () => {
+    const { nodes } = await inspectWorkflow(
+      [
+        "  const r = await workflow.do('Ship', 'ship', {})",
+        '  return { ...r, extra: 1 }',
+      ].join('\n')
+    )
+
+    const returnNode = Object.values(nodes).find(
+      (n: any) => n.flow === 'return'
+    ) as any
+    assert.ok(returnNode, 'a return node should exist')
+    assert.deepEqual(
+      returnNode.spread,
+      ['r'],
+      `the spread source must be recorded, got: ${JSON.stringify(returnNode)}`
+    )
+  })
+
+  test('return r produces a return node', async () => {
+    const { nodes } = await inspectWorkflow(
+      ["  const r = await workflow.do('Ship', 'ship', {})", '  return r'].join(
+        '\n'
+      )
+    )
+
+    const returnNode = Object.values(nodes).find(
+      (n: any) => n.flow === 'return'
+    ) as any
+    assert.ok(
+      returnNode,
+      `returning a variable must still produce a return node, got: ${JSON.stringify(nodes)}`
+    )
+    assert.deepEqual(returnNode.spread, ['r'])
+  })
+})

package/src/add/add-workflow-silent-drops.test.ts

@@ -0,0 +1,163 @@
+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'
+
+function makeLogger(diags: string[]): InspectorLogger {
+  return {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    diagnostic: ({ code, message }: any) => {
+      diags.push(`${code}: ${message}`)
+    },
+    critical: (code: any, message: string) => {
+      diags.push(`${code}: ${message}`)
+    },
+    hasCriticalErrors: () => false,
+  }
+}
+
+const STEP_FILE = [
+  "import { pikkuSessionlessFunc } from '@pikku/core'",
+  'export const listUsers = pikkuSessionlessFunc({',
+  "  func: async () => ({ users: [{ id: '1', email: 'a@b.c' }] }),",
+  '})',
+  'export const rpcA = pikkuSessionlessFunc({',
+  "  func: async () => ({ id: 'a' }),",
+  '})',
+  'export const rpcB = pikkuSessionlessFunc({',
+  "  func: async () => ({ id: 'b' }),",
+  '})',
+  'export const rpcC = pikkuSessionlessFunc({',
+  '  func: async () => ({ ok: true }),',
+  '})',
+].join('\n')
+
+async function inspectWorkflow(body: string) {
+  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-drops-'))
+  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')
+  )
+  const diags: string[] = []
+  try {
+    const state: any = await inspect(makeLogger(diags), [stepFile, wfFile], {
+      rootDir,
+    })
+    const metaMap = state.workflows.meta
+    const meta = (
+      metaMap instanceof Map ? [...metaMap.values()] : Object.values(metaMap)
+    )[0] as any
+    return {
+      invoked: [...state.rpc.invokedFunctions] as string[],
+      steps: (meta?.steps ?? []) as any[],
+      diags,
+    }
+  } finally {
+    await rm(rootDir, { recursive: true, force: true })
+  }
+}
+
+describe('DSL extraction — constructs that must not be silently dropped', () => {
+  test('a property access on the loop item (u.id) survives as an item input', async () => {
+    const { steps } = await inspectWorkflow(
+      [
+        "  const audience = await workflow.do('collect', 'listUsers', {})",
+        '  await Promise.all(',
+        '    audience.users.map(async (u) => {',
+        "      await workflow.do('send', 'rpcC', { userId: u.id, tag: 'x' })",
+        '    })',
+        '  )',
+        '  return { ok: true }',
+      ].join('\n')
+    )
+
+    const fanout = steps.find((s) => s.type === 'fanout')
+    assert.ok(fanout, 'fanout step should be extracted')
+    const send = fanout.body?.[0]
+    assert.ok(send, 'the fanout body step should be extracted')
+    assert.deepEqual(
+      send.inputs?.userId,
+      { from: 'item', path: 'id' },
+      `u.id must map to the loop item, got: ${JSON.stringify(send.inputs)}`
+    )
+    assert.deepEqual(
+      send.inputs?.tag,
+      { from: 'literal', value: 'x' },
+      'sibling literal inputs must still survive'
+    )
+  })
+
+  test('array destructuring of a Promise.all group keeps both steps and binds each result', async () => {
+    const { invoked, steps } = await inspectWorkflow(
+      [
+        '  const [org, user] = await Promise.all([',
+        "    workflow.do('create org', 'rpcA', {}),",
+        "    workflow.do('create user', 'rpcB', {}),",
+        '  ])',
+        '  return { orgId: org.id, userId: user.id }',
+      ].join('\n')
+    )
+
+    assert.ok(invoked.includes('rpcA'), 'rpcA must not be dropped')
+    assert.ok(invoked.includes('rpcB'), 'rpcB must not be dropped')
+
+    const parallel = steps.find((s) => s.type === 'parallel')
+    assert.ok(parallel, 'a parallel step should be extracted')
+    assert.deepEqual(
+      parallel.children?.map((c: any) => c.outputVar),
+      ['org', 'user'],
+      'each destructured name should bind to its matching child step'
+    )
+
+    const ret = steps.find((s) => s.type === 'return')
+    assert.deepEqual(
+      ret?.outputs?.orgId,
+      { from: 'outputVar', name: 'org', path: 'id' },
+      'org.id must resolve to the bound step output, not degrade to a trigger input'
+    )
+  })
+
+  test('object destructuring of a step result reports a diagnostic instead of silently dropping', async () => {
+    const { invoked, diags } = await inspectWorkflow(
+      [
+        "  const { id } = await workflow.do('s', 'rpcA', {})",
+        '  return { id }',
+      ].join('\n')
+    )
+
+    const dropped = !invoked.includes('rpcA')
+    assert.ok(
+      !dropped || diags.length > 0,
+      'if the step is dropped the user must be told — silence is the bug'
+    )
+  })
+
+  test('a brace-less for-of body is still extracted as a sequential fanout', async () => {
+    const { invoked, steps } = await inspectWorkflow(
+      [
+        '  for (const email of data.emails)',
+        "    await workflow.do('invite', 'rpcA', { email })",
+        '  return { ok: true }',
+      ].join('\n')
+    )
+
+    assert.ok(invoked.includes('rpcA'), 'rpcA must not be dropped')
+    const fanout = steps.find((s) => s.type === 'fanout')
+    assert.ok(fanout, 'a brace-less for-of should still produce a fanout step')
+    assert.equal(fanout.mode, 'sequential')
+  })
+})