@pikku/inspector 0.12.42 → 0.12.44

package/src/utils/workflow/dsl/deserialize-fanout-body.test.ts

@@ -0,0 +1,71 @@
+import { strict as assert } from 'assert'
+import { describe, test } from 'node:test'
+import { deserializeDslWorkflow } from './deserialize-dsl-workflow.js'
+
+/**
+ * A fanout whose per-iteration body is two chained steps: the first captures
+ * its result into `digestData`, the second consumes it.
+ */
+const MULTI_STEP_FANOUT_GRAPH: any = {
+  name: 'dailyDigestWorkflow',
+  pikkuFuncId: 'dailyDigestWorkflow',
+  source: 'dsl',
+  entryNodeIds: ['start'],
+  nodes: {
+    start: {
+      nodeId: 'start',
+      flow: 'fanout',
+      sourceVar: 'users',
+      itemVar: 'u',
+      mode: 'parallel',
+      childEntry: 'start_item_0',
+    },
+    start_item_0: {
+      nodeId: 'start_item_0',
+      rpcName: 'getDigestData',
+      stepName: 'Get pipeline',
+      outputVar: 'digestData',
+      input: { userId: { $ref: 'u.id' } },
+      next: 'start_item_1',
+    },
+    start_item_1: {
+      nodeId: 'start_item_1',
+      rpcName: 'sendDigestEmail',
+      stepName: 'Send digest',
+      input: { dealsByStage: { $ref: 'digestData.dealsByStage' } },
+    },
+  },
+}
+
+describe('deserializeDslWorkflow — multi-step fanout body', () => {
+  test('emits every step in the map body, not just the entry step', () => {
+    const code = deserializeDslWorkflow(MULTI_STEP_FANOUT_GRAPH)
+
+    assert.ok(
+      code.includes("'getDigestData'"),
+      'the entry step of the body should be emitted'
+    )
+    assert.ok(
+      code.includes("'sendDigestEmail'"),
+      'steps chained after the entry step must not be dropped'
+    )
+  })
+
+  test('re-emits a captured step result as a `const` binding', () => {
+    const code = deserializeDslWorkflow(MULTI_STEP_FANOUT_GRAPH)
+
+    assert.ok(
+      code.includes('const digestData = await workflow.do('),
+      `a step with an outputVar should round-trip as a const binding, got:\n${code}`
+    )
+  })
+
+  test('uses a block-bodied map callback so multiple statements are valid', () => {
+    const code = deserializeDslWorkflow(MULTI_STEP_FANOUT_GRAPH)
+
+    assert.ok(
+      code.includes('users.map(async (u) => {'),
+      `map callback must be block-bodied, got:\n${code}`
+    )
+  })
+})

package/src/utils/workflow/dsl/deserialize-fanout-fidelity.test.ts

@@ -0,0 +1,99 @@
+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 notify = pikkuSessionlessFunc({',
+  "  func: async () => ({ id: 'n' }),",
+  '})',
+].join('\n')
+
+async function roundTrip(body: string): Promise<string> {
+  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-rtf-'))
+  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 — a fanout body keeps everything in it', () => {
+  test('a step option inside a fanout body survives', async () => {
+    const code = await roundTrip(
+      [
+        '  await Promise.all(',
+        '    data.users.map(async (u: any) => {',
+        "      await workflow.do('Notify', 'notify', { id: u.id }, { retries: 3 })",
+        '    })',
+        '  )',
+        '  return { ok: true }',
+      ].join('\n')
+    )
+
+    assert.ok(
+      code.includes('retries: 3'),
+      `retries must not be dropped from a fanout body step, got:\n${code}`
+    )
+  })
+
+  test('a non-RPC step inside a fanout body survives', async () => {
+    const code = await roundTrip(
+      [
+        '  await Promise.all(',
+        '    data.users.map(async (u: any) => {',
+        "        await workflow.sleep('Stagger', '1s')",
+        "        await workflow.do('Notify', 'notify', { id: u.id })",
+        '    })',
+        '  )',
+        '  return { ok: true }',
+      ].join('\n')
+    )
+
+    assert.ok(
+      code.includes("workflow.sleep('Stagger', '1s')"),
+      `a sleep inside a fanout body must not be deleted, got:\n${code}`
+    )
+    assert.ok(
+      code.includes("'notify'"),
+      `the rpc step must still be there, got:\n${code}`
+    )
+  })
+})

package/src/utils/workflow/dsl/deserialize-graph-next.test.ts

@@ -0,0 +1,161 @@
+import { strict as assert } from 'assert'
+import { describe, test } from 'node:test'
+import {
+  deserializeDslWorkflow,
+  deserializeGraphWorkflow,
+} from './deserialize-dsl-workflow.js'
+import type { SerializedWorkflowGraph } from '../graph/workflow-graph.types.js'
+
+function graph(
+  nodes: SerializedWorkflowGraph['nodes']
+): SerializedWorkflowGraph {
+  return {
+    name: 'wf',
+    pikkuFuncId: 'wf',
+    source: 'graph',
+    nodes,
+    entryNodeIds: ['start'],
+  }
+}
+
+describe('graph round-trip — a non-string next must not be stringified', () => {
+  test('a parallel fan-out keeps every target', () => {
+    const code = deserializeGraphWorkflow(
+      graph({
+        start: { nodeId: 'start', rpcName: 'begin', next: ['left', 'right'] },
+        left: { nodeId: 'left', rpcName: 'goLeft' },
+        right: { nodeId: 'right', rpcName: 'goRight' },
+      })
+    )
+
+    assert.ok(
+      !code.includes("next: 'left,right'"),
+      `an array next must not be joined into a single bogus node id, got:\n${code}`
+    )
+    assert.ok(
+      /next: \['left', 'right'\]/.test(code),
+      `both parallel targets must survive, got:\n${code}`
+    )
+  })
+
+  test('key-based branching keeps its routing table', () => {
+    const code = deserializeGraphWorkflow(
+      graph({
+        start: {
+          nodeId: 'start',
+          rpcName: 'classify',
+          next: { approved: 'ship', rejected: 'refund' },
+        },
+        ship: { nodeId: 'ship', rpcName: 'ship' },
+        refund: { nodeId: 'refund', rpcName: 'refund' },
+      })
+    )
+
+    assert.ok(
+      !code.includes('[object Object]'),
+      `a record next must not be stringified, got:\n${code}`
+    )
+    assert.ok(
+      code.includes("approved: 'ship'") && code.includes("rejected: 'refund'"),
+      `every branch key must survive, got:\n${code}`
+    )
+  })
+})
+
+describe('DSL round-trip — an unbound array step must not emit a broken binding', () => {
+  test('a filter with no outputVar does not declare `const undefined`', () => {
+    const code = deserializeDslWorkflow({
+      ...graph({
+        start: {
+          nodeId: 'start',
+          flow: 'filter',
+          sourceVar: 'data.users',
+          itemVar: 'u',
+          condition: { type: 'simple', expression: 'u.active' },
+        },
+      }),
+      source: 'dsl',
+    })
+
+    assert.ok(
+      !code.includes('const undefined'),
+      `an unbound filter must not emit a syntactically invalid binding, got:\n${code}`
+    )
+  })
+
+  test('an unbound some/every does not declare `const undefined`', () => {
+    const code = deserializeDslWorkflow({
+      ...graph({
+        start: {
+          nodeId: 'start',
+          flow: 'arrayPredicate',
+          mode: 'some',
+          sourceVar: 'data.users',
+          itemVar: 'u',
+          condition: { type: 'simple', expression: 'u.active' },
+        },
+      }),
+      source: 'dsl',
+    })
+
+    assert.ok(
+      !code.includes('const undefined'),
+      `an unbound predicate must not emit a syntactically invalid binding, got:\n${code}`
+    )
+  })
+})
+
+describe('graph round-trip — runtime-honoured node config must survive', () => {
+  test('onError routing is preserved', () => {
+    const code = deserializeGraphWorkflow(
+      graph({
+        start: {
+          nodeId: 'start',
+          rpcName: 'charge',
+          next: 'ship',
+          onError: 'refund',
+        },
+        ship: { nodeId: 'ship', rpcName: 'ship' },
+        refund: { nodeId: 'refund', rpcName: 'refund' },
+      })
+    )
+
+    assert.ok(
+      code.includes("onError: 'refund'"),
+      `error routing is honoured at runtime and must not be dropped, got:\n${code}`
+    )
+  })
+
+  test('retries and retryDelay are preserved', () => {
+    const code = deserializeGraphWorkflow(
+      graph({
+        start: {
+          nodeId: 'start',
+          rpcName: 'charge',
+          options: { retries: 3, retryDelay: '5s' },
+        },
+      })
+    )
+
+    assert.ok(
+      code.includes('retries: 3'),
+      `retries must not be dropped, got:\n${code}`
+    )
+    assert.ok(
+      code.includes("retryDelay: '5s'"),
+      `retryDelay must not be dropped, got:\n${code}`
+    )
+  })
+
+  test('graph-level notes are preserved', () => {
+    const code = deserializeGraphWorkflow({
+      ...graph({ start: { nodeId: 'start', rpcName: 'charge' } }),
+      notes: ['imported from n8n'],
+    })
+
+    assert.ok(
+      code.includes('imported from n8n'),
+      `graph notes must not be dropped, got:\n${code}`
+    )
+  })
+})

package/src/utils/workflow/dsl/deserialize-roundtrip-bindings.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'
+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 createOrg = pikkuSessionlessFunc({',
+  "  func: async () => ({ id: 'o' }),",
+  '})',
+  'export const createUser = pikkuSessionlessFunc({',
+  "  func: async () => ({ id: 'u' }),",
+  '})',
+  'export const ship = pikkuSessionlessFunc({',
+  "  func: async () => ({ id: 's' }),",
+  '})',
+].join('\n')
+
+async function roundTrip(body: string): Promise<string> {
+  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-rtb-'))
+  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 — regenerated code must still bind its variables', () => {
+  test('a Promise.all group keeps the destructured result bindings', async () => {
+    const code = await roundTrip(
+      [
+        '  const [org, user] = await Promise.all([',
+        "    workflow.do('create org', 'createOrg', {}),",
+        "    workflow.do('create user', 'createUser', {}),",
+        '  ])',
+        '  return { orgId: org.id, userId: user.id }',
+      ].join('\n')
+    )
+
+    assert.ok(
+      /const \[org, user\] = await Promise\.all\(\[/.test(code),
+      `parallel results must stay bound or the regenerated code cannot compile, got:\n${code}`
+    )
+  })
+
+  test('a step result bound inside a branch is hoisted so later references compile', async () => {
+    const code = await roundTrip(
+      [
+        '  let shipment: { id: string } | undefined',
+        '  if (data.needsShipping) {',
+        "    shipment = await workflow.do('Ship', 'ship', {})",
+        '  }',
+        '  return { shipmentId: shipment }',
+      ].join('\n')
+    )
+
+    const declaredOutside = /let shipment/.test(code)
+    const constInsideBranch = /\{\s*\n\s*const shipment =/.test(code)
+    assert.ok(
+      declaredOutside && !constInsideBranch,
+      `a variable referenced after the branch must be hoisted, not const-scoped inside it, got:\n${code}`
+    )
+  })
+})
+
+describe('DSL round-trip — step names are data, not structure', () => {
+  test('a step whose name contains a structural substring is not deleted', async () => {
+    const code = await roundTrip(
+      [
+        "  await workflow.do('sync_case_files', 'createOrg', {})",
+        "  await workflow.do('map_item_batch', 'createUser', {})",
+        '  return { ok: true }',
+      ].join('\n')
+    )
+
+    assert.ok(
+      code.includes("'sync_case_files'"),
+      `a top-level step named like a structural node id must survive, got:\n${code}`
+    )
+    assert.ok(
+      code.includes("'map_item_batch'"),
+      `a top-level step named like a structural node id must survive, got:\n${code}`
+    )
+  })
+})

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

@@ -0,0 +1,116 @@
+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 ship = pikkuSessionlessFunc({',
+  "  func: async () => ({ id: 's' }),",
+  '})',
+].join('\n')
+
+async function roundTrip(body: string): Promise<string> {
+  const rootDir = await mkdtemp(join(tmpdir(), 'pikku-rtv-'))
+  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 — values keep their type', () => {
+  test('a numeric sleep duration is not turned into a string', async () => {
+    const code = await roundTrip(
+      ["  await workflow.sleep('Wait', 5000)", '  return { ok: true }'].join(
+        '\n'
+      )
+    )
+
+    assert.ok(
+      code.includes("workflow.sleep('Wait', 5000)"),
+      `a numeric duration must stay numeric, got:\n${code}`
+    )
+  })
+
+  test('a string sleep duration keeps its quotes', async () => {
+    const code = await roundTrip(
+      ["  await workflow.sleep('Wait', '5s')", '  return { ok: true }'].join(
+        '\n'
+      )
+    )
+
+    assert.ok(
+      code.includes("workflow.sleep('Wait', '5s')"),
+      `a string duration must stay quoted, got:\n${code}`
+    )
+  })
+
+  test('an assignment expression is not turned into a string literal', async () => {
+    const code = await roundTrip(
+      ['  let count = 0', '  count = count + 1', '  return { count }'].join(
+        '\n'
+      )
+    )
+
+    assert.ok(
+      code.includes('count = count + 1'),
+      `an assigned expression must be regenerated as an expression, got:\n${code}`
+    )
+    assert.ok(
+      !code.includes("count = 'count + 1'"),
+      'an expression must not be quoted into a string literal'
+    )
+  })
+
+  test('an assigned string literal keeps its quotes', async () => {
+    const code = await roundTrip(
+      [
+        "  let status = 'pending'",
+        "  status = 'done'",
+        '  return { status }',
+      ].join('\n')
+    )
+
+    assert.ok(
+      code.includes("status = 'done'"),
+      `a string literal must stay a string literal, got:\n${code}`
+    )
+  })
+})