@pikku/inspector 0.12.42 → 0.12.44

package/src/add/add-workflow-graph-notes.test.ts

@@ -0,0 +1,74 @@
+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(): InspectorLogger {
+  return {
+    debug: () => {},
+    info: () => {},
+    warn: () => {},
+    error: () => {},
+    diagnostic: () => {},
+    critical: () => {},
+    hasCriticalErrors: () => false,
+  }
+}
+
+describe('addWorkflowGraph — notes extraction', () => {
+  test('node-level and graph-level notes are carried into the serialized graph', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-graph-notes-'))
+    const stepFile = join(rootDir, 'my.steps.ts')
+    const graphFile = join(rootDir, 'my.graph.ts')
+
+    await writeFile(
+      stepFile,
+      [
+        "import { pikkuSessionlessFunc } from '@pikku/core'",
+        'export const assess = pikkuSessionlessFunc({ func: async () => ({ ok: true }) })',
+        'export const notify = pikkuSessionlessFunc({ func: async () => ({ sent: true }) })',
+      ].join('\n')
+    )
+
+    await writeFile(
+      graphFile,
+      [
+        "import { pikkuWorkflowGraph } from '@pikku/core/workflow'",
+        'export const myGraph = pikkuWorkflowGraph({',
+        "  name: 'my-graph',",
+        "  notes: ['imported sticky note'],",
+        '  nodes: {',
+        "    assess: 'assess',",
+        "    notify: 'notify',",
+        '  },',
+        '  config: {',
+        "    assess: { next: 'notify', notes: 'STUB — generated from node \"Assess\"' },",
+        '    notify: {},',
+        '  },',
+        '})',
+      ].join('\n')
+    )
+
+    try {
+      const state = await inspect(makeLogger(), [stepFile, graphFile], {
+        rootDir,
+      })
+      const graph = state.workflows.graphMeta['my-graph']
+      assert.ok(graph, 'graph meta should be registered')
+      assert.deepEqual(graph.notes, ['imported sticky note'])
+      assert.equal(
+        (graph.nodes['assess'] as { notes?: string }).notes,
+        'STUB — generated from node "Assess"'
+      )
+      assert.equal(
+        (graph.nodes['notify'] as { notes?: string }).notes,
+        undefined
+      )
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+})

package/src/add/add-workflow-graph.ts

@@ -12,6 +12,11 @@ function extractAstValue(
   refParamName: string,
   templateParamName: string | undefined
 ): unknown {
+  // `'GET' as const` / parenthesised values wrap the real initializer — see
+  // through them or the whole property is silently dropped from the meta.
+  while (ts.isAsExpression(expr) || ts.isParenthesizedExpression(expr)) {
+    expr = expr.expression
+  }
   if (ts.isStringLiteral(expr)) {
     return expr.text
   }
@@ -146,10 +151,14 @@ function extractInputMapping(
       ? node.parameters[0].name.text
       : 'ref'
 
+  // The canonical form imports `template` from '@pikku/core/workflow' and calls
+  // it inside a single-param `(ref) => (...)` arrow; the older form passes it as
+  // a second arrow parameter. Support both — default to the imported name so a
+  // `template(...)` value is never dropped just because it isn't a 2nd param.
   const templateParamName =
     node.parameters.length > 1 && ts.isIdentifier(node.parameters[1].name)
       ? node.parameters[1].name.text
-      : undefined
+      : 'template'
 
   const input: Record<string, unknown | DataRef> = {}
 
@@ -184,6 +193,13 @@ function extractNextConfig(
   node: ts.Node,
   _checker: ts.TypeChecker
 ): string | string[] | Record<string, string | string[]> | undefined {
+  // Key-based branch `next` (`{ key: [targets] }`) is authored with an `as any`
+  // cast because the graph's NextConfig can't narrow record targets to node-id
+  // literals; see through that (and parens) so the routing survives into the meta.
+  while (ts.isAsExpression(node) || ts.isParenthesizedExpression(node)) {
+    node = node.expression
+  }
+
   if (ts.isStringLiteral(node)) {
     return node.text
   }
@@ -254,6 +270,7 @@ interface PikkuWorkflowGraphExtract {
   name?: string
   description?: string
   tags?: string[]
+  notes?: string[]
   disabled?: true
   nodesNode?: ts.ObjectLiteralExpression
   configNode?: ts.ObjectLiteralExpression
@@ -270,6 +287,7 @@ function extractWorkflowGraphConfig(
   let name: string | undefined
   let description: string | undefined
   let tags: string[] | undefined
+  let notes: string[] | undefined
   let disabled: true | undefined
   let nodesNode: ts.ObjectLiteralExpression | undefined
   let configNode: ts.ObjectLiteralExpression | undefined
@@ -293,6 +311,13 @@ function extractWorkflowGraphConfig(
       tags = prop.initializer.elements
         .filter(ts.isStringLiteral)
         .map((el) => (el as ts.StringLiteral).text)
+    } else if (
+      propName === 'notes' &&
+      ts.isArrayLiteralExpression(prop.initializer)
+    ) {
+      notes = prop.initializer.elements
+        .filter(ts.isStringLiteral)
+        .map((el) => (el as ts.StringLiteral).text)
     } else if (
       propName === 'nodes' &&
       ts.isObjectLiteralExpression(prop.initializer)
@@ -306,7 +331,7 @@ function extractWorkflowGraphConfig(
     }
   }
 
-  return { name, description, tags, disabled, nodesNode, configNode }
+  return { name, description, tags, notes, disabled, nodesNode, configNode }
 }
 
 /**
@@ -359,6 +384,7 @@ function extractGraphFromNewFormat(
       onError: undefined,
       retries: undefined,
       retryDelay: undefined,
+      notes: undefined,
     }
   }
 
@@ -386,6 +412,7 @@ function extractGraphFromNewFormat(
           nodes[nodeId].input = nodeConfig.input
           nodes[nodeId].retries = nodeConfig.retries
           nodes[nodeId].retryDelay = nodeConfig.retryDelay
+          nodes[nodeId].notes = nodeConfig.notes
         }
       }
     }
@@ -406,12 +433,14 @@ function extractNodeConfigFromObject(
   input: Record<string, any>
   retries: number | undefined
   retryDelay: string | number | undefined
+  notes: string | undefined
 } {
   let next: any = undefined
   let onError: any = undefined
   let input: Record<string, any> = {}
   let retries: number | undefined = undefined
   let retryDelay: string | number | undefined = undefined
+  let notes: string | undefined = undefined
 
   for (const prop of obj.properties) {
     if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) continue
@@ -434,10 +463,12 @@ function extractNodeConfigFromObject(
       } else if (ts.isStringLiteral(prop.initializer)) {
         retryDelay = prop.initializer.text
       }
+    } else if (propName === 'notes') {
+      notes = extractStringLiteral(prop.initializer, checker)
     }
   }
 
-  return { next, onError, input, retries, retryDelay }
+  return { next, onError, input, retries, retryDelay, notes }
 }
 
 /**
@@ -526,6 +557,7 @@ export const addWorkflowGraph: AddWiring = (logger, node, checker, state) => {
     source: 'graph',
     description: graphConfig.description,
     tags: graphConfig.tags,
+    notes: graphConfig.notes,
     nodes: graphNodes,
     entryNodeIds,
   }

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')
+  })
+})