@pikku/inspector 0.12.75 → 0.12.82

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

@@ -1,155 +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'
-
-function makeLogger(
-  criticals: Array<{ code: string; message: string }>
-): InspectorLogger {
-  return {
-    debug: () => {},
-    info: () => {},
-    warn: () => {},
-    error: () => {},
-    diagnostic: ({ code, message }) => {
-      criticals.push({ code, message })
-    },
-    critical: (code: any, message: string) => {
-      criticals.push({ code, message })
-    },
-    hasCriticalErrors: () => criticals.length > 0,
-  }
-}
-
-describe('addWorkflow — workflow.do RPC detection', () => {
-  test('detects RPC step when result is assigned to a const', async () => {
-    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-workflow-'))
-    const wfFile = join(rootDir, 'my.workflow.ts')
-    const stepFile = join(rootDir, 'my.steps.ts')
-
-    await writeFile(
-      stepFile,
-      [
-        "import { pikkuSessionlessFunc } from '@pikku/core'",
-        'export const doThing = pikkuSessionlessFunc({',
-        '  func: async ({ logger }) => ({ ok: true }),',
-        '})',
-      ].join('\n')
-    )
-
-    await writeFile(
-      wfFile,
-      [
-        "import { pikkuWorkflowFunc } from '@pikku/core/workflow'",
-        'export const myWorkflow = pikkuWorkflowFunc(async (_, _input, { workflow }) => {',
-        "  const result = await workflow.do('Do thing', 'doThing', {})",
-        '  return { id: result.ok }',
-        '})',
-      ].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('doThing'),
-        'doThing should be in invokedFunctions'
-      )
-      assert.ok(
-        state.rpc.internalFiles.has('doThing'),
-        'doThing should be in internalFiles'
-      )
-    } finally {
-      await rm(rootDir, { recursive: true, force: true })
-    }
-  })
-
-  test('detects RPC step when result is reassigned to a pre-declared null variable', async () => {
-    // Regression: `let x = null; x = await workflow.do(...)` was treated as a
-    // set-step instead of an RPC step, so the referenced function was never registered.
-    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-workflow-reassign-'))
-    const wfFile = join(rootDir, 'project.workflow.ts')
-    const stepFile = join(rootDir, 'project.steps.ts')
-
-    await writeFile(
-      stepFile,
-      [
-        "import { pikkuSessionlessFunc } from '@pikku/core'",
-        'export const launchSandbox = pikkuSessionlessFunc({',
-        '  func: async ({ logger }) => ({ sandboxId: "abc" }),',
-        '})',
-      ].join('\n')
-    )
-
-    await writeFile(
-      wfFile,
-      [
-        "import { pikkuWorkflowFunc } from '@pikku/core/workflow'",
-        'export const createProjectWorkflow = pikkuWorkflowFunc(async (_, input, { workflow }) => {',
-        '  let launched: { sandboxId: string } | null = null',
-        '  if (input.createSandbox) {',
-        "    launched = await workflow.do('Launch sandbox', 'launchSandbox', { projectId: input.projectId })",
-        '  }',
-        '  return { sandboxId: launched?.sandboxId ?? null }',
-        '})',
-      ].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('launchSandbox'),
-        'launchSandbox should be in invokedFunctions even when assigned to a pre-declared null variable'
-      )
-      assert.ok(
-        state.rpc.internalFiles.has('launchSandbox'),
-        'launchSandbox should be in internalFiles so it gets registered in pikku-functions.gen.ts'
-      )
-    } finally {
-      await rm(rootDir, { recursive: true, force: true })
-    }
-  })
-
-  test('still treats plain reassignment to context var as a set step', async () => {
-    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-workflow-set-'))
-    const wfFile = join(rootDir, 'set.workflow.ts')
-
-    await writeFile(
-      wfFile,
-      [
-        "import { pikkuWorkflowFunc } from '@pikku/core/workflow'",
-        'export const setWorkflow = pikkuWorkflowFunc(async (_, input, { workflow }) => {',
-        '  let status = "pending"',
-        '  status = "done"',
-        "  await workflow.do('No-op', 'noopStep', {})",
-        '  return { status }',
-        '})',
-      ].join('\n')
-    )
-
-    const criticals: Array<{ code: string; message: string }> = []
-    try {
-      const state = await inspect(makeLogger(criticals), [wfFile], { rootDir })
-      const meta = state.workflows.meta['setWorkflow']
-      assert.ok(meta, 'workflow should be registered')
-      const steps = meta.steps ?? []
-      const setStep = steps.find(
-        (s: any) => s.type === 'set' && s.variable === 'status'
-      )
-      assert.ok(
-        setStep,
-        'plain string reassignment should still produce a set step'
-      )
-    } finally {
-      await rm(rootDir, { recursive: true, force: true })
-    }
-  })
-})

package/src/add/add-workflow.ts

@@ -1,482 +0,0 @@
-import * as ts from 'typescript'
-import type { AddWiring, InspectorState } from '../types.js'
-import { extractFunctionName } from '../utils/extract-function-name.js'
-import { extractFunctionNode } from '../utils/extract-function-node.js'
-import { ErrorCode } from '../error-codes.js'
-import type { WorkflowStepMeta, WorkflowContext } from '@pikku/core/workflow'
-import {
-  extractStringLiteral,
-  isStringLike,
-  isFunctionLike,
-  extractDescription,
-  extractDuration,
-} from '../utils/extract-node-value.js'
-import {
-  getCommonWireMetaData,
-  getPropertyValue,
-} from '../utils/get-property-value.js'
-import { extractDSLWorkflow } from '../utils/workflow/dsl/extract-dsl-workflow.js'
-import {
-  getSourceText,
-  extractActorFromOptions,
-} from '../utils/workflow/dsl/patterns.js'
-
-/**
- * Extract a workflow step's display name without letting a non-static name
- * (e.g. a function call) abort the scan. The step name is cosmetic, so a
- * resolution failure must never prevent the RPC from being registered.
- */
-function extractStepName(node: ts.Node, checker: ts.TypeChecker): string {
-  try {
-    return extractStringLiteral(node, checker)
-  } catch {
-    return getSourceText(node)
-  }
-}
-
-/**
- * Walk a function body for any `X.expectEventually(...)` call. Used to enforce
- * that the durable-polling assertion is a scenario-only primitive — regular
- * workflows must not carry test/assertion semantics.
- */
-function containsExpectEventuallyCall(node: ts.Node): boolean {
-  if (
-    ts.isCallExpression(node) &&
-    ts.isPropertyAccessExpression(node.expression) &&
-    node.expression.name.text === 'expectEventually'
-  ) {
-    return true
-  }
-  let found = false
-  ts.forEachChild(node, (child) => {
-    if (!found && !ts.isFunctionDeclaration(child)) {
-      found = containsExpectEventuallyCall(child)
-    }
-  })
-  return found
-}
-
-/**
- * Recursively check if any step has inline type (non-serializable)
- */
-function hasInlineSteps(steps: WorkflowStepMeta[]): boolean {
-  for (const step of steps) {
-    if (step.type === 'inline') {
-      return true
-    } else if (step.type === 'branch') {
-      for (const branch of step.branches) {
-        if (hasInlineSteps(branch.steps)) return true
-      }
-      if (step.elseSteps && hasInlineSteps(step.elseSteps)) return true
-    } else if (step.type === 'switch' && step.cases) {
-      for (const c of step.cases) {
-        if (c.steps && hasInlineSteps(c.steps)) return true
-      }
-      if (step.defaultSteps && hasInlineSteps(step.defaultSteps)) return true
-    } else if (step.type === 'fanout' && step.body) {
-      if (hasInlineSteps(step.body)) return true
-    } else if (step.type === 'parallel' && step.children) {
-      if (hasInlineSteps(step.children)) return true
-    }
-  }
-  return false
-}
-
-/**
- * Recursively collect all RPC names from workflow steps
- */
-export function collectInvokedRPCs(
-  steps: WorkflowStepMeta[],
-  rpcs: Set<string>
-): void {
-  for (const step of steps) {
-    if (step.type === 'rpc' && step.rpcName) {
-      rpcs.add(step.rpcName)
-      // The compensation handler is invoked at runtime too, so it has to be
-      // wired like any other step.
-      if (step.options?.onError) {
-        rpcs.add(step.options.onError)
-      }
-    } else if (step.type === 'scenarioStep' && step.stepFunc) {
-      // Steps are bundled like RPCs — the runner calls them through
-      // runPikkuFunc — but they are deliberately never RPC-registered.
-      rpcs.add(step.stepFunc)
-    } else if (step.type === 'branch') {
-      for (const branch of step.branches) {
-        collectInvokedRPCs(branch.steps, rpcs)
-      }
-      if (step.elseSteps) collectInvokedRPCs(step.elseSteps, rpcs)
-    } else if (step.type === 'switch' && step.cases) {
-      for (const c of step.cases) {
-        if (c.steps) collectInvokedRPCs(c.steps, rpcs)
-      }
-      if (step.defaultSteps) collectInvokedRPCs(step.defaultSteps, rpcs)
-    } else if (step.type === 'fanout' && step.body) {
-      collectInvokedRPCs(step.body as WorkflowStepMeta[], rpcs)
-    } else if (step.type === 'parallel' && step.children) {
-      collectInvokedRPCs(step.children as WorkflowStepMeta[], rpcs)
-    }
-  }
-}
-
-/**
- * Scan for workflow.do(), workflow.expectEventually(), workflow.sleep(), and
- * workflow.cancel() calls to extract workflow steps
- */
-function getWorkflowInvocations(
-  node: ts.Node,
-  checker: ts.TypeChecker,
-  state: InspectorState,
-  workflowName: string,
-  steps: WorkflowStepMeta[]
-) {
-  // Look for property access expressions: workflow.do or workflow.sleep
-  if (ts.isPropertyAccessExpression(node)) {
-    const { name } = node
-
-    // Check if this is accessing 'do' or 'sleep' property
-    if (
-      name.text === 'do' ||
-      name.text === 'sleep' ||
-      name.text === 'cancel' ||
-      name.text === 'expectEventually'
-    ) {
-      // Check if the parent is a call expression
-      const parent = node.parent
-      if (ts.isCallExpression(parent) && parent.expression === node) {
-        const args = parent.arguments
-
-        if (name.text === 'do' && args.length >= 2) {
-          // workflow.do(stepName, rpcName|fn, data?, options?)
-          const stepNameArg = args[0]
-          const secondArg = args[1]
-          const optionsArg =
-            args.length >= 4 ? args[args.length - 1] : undefined
-
-          const stepName = extractStepName(stepNameArg, checker)
-          const description =
-            extractDescription(optionsArg, checker) ?? undefined
-
-          // Determine form by checking 2nd argument type
-          if (isStringLike(secondArg, checker)) {
-            // RPC form: workflow.do(stepName, rpcName, data, options?)
-            const rpcName = extractStringLiteral(secondArg, checker)
-            steps.push({
-              type: 'rpc',
-              stepName,
-              rpcName,
-              actor: extractActorFromOptions(optionsArg),
-            })
-            state.rpc.invokedFunctions.add(rpcName)
-          } else if (isFunctionLike(secondArg)) {
-            // Inline form: workflow.do(stepName, fn, options?)
-            steps.push({
-              type: 'inline',
-              stepName: stepName || '<dynamic>',
-              description: description || '<dynamic>',
-            })
-          }
-        } else if (name.text === 'expectEventually' && args.length >= 4) {
-          // workflow.expectEventually(stepName, rpcName, data, predicate, options?)
-          const stepName = extractStepName(args[0], checker)
-          if (isStringLike(args[1], checker)) {
-            const rpcName = extractStringLiteral(args[1], checker)
-            steps.push({
-              type: 'rpc',
-              stepName,
-              rpcName,
-              expectEventually: true,
-              actor: extractActorFromOptions(
-                args.length >= 5 ? args[4] : undefined
-              ),
-            })
-            state.rpc.invokedFunctions.add(rpcName)
-          }
-        } else if (name.text === 'sleep' && args.length >= 2) {
-          // workflow.sleep(stepName, duration)
-          const stepNameArg = args[0]
-          const durationArg = args[1]
-
-          const stepName = extractStepName(stepNameArg, checker)
-          const duration = extractDuration(durationArg, checker)
-
-          steps.push({
-            type: 'sleep',
-            stepName: stepName || '<dynamic>',
-            duration: duration || '<dynamic>',
-          })
-        } else if (name.text === 'cancel') {
-          // workflow.cancel(reason?)
-          steps.push({
-            type: 'cancel',
-          })
-        }
-      }
-    }
-  }
-
-  // Recurse into children, including arrow functions (for Promise.all callbacks)
-  // but skip function declarations (which would be separate functions)
-  ts.forEachChild(node, (child) => {
-    if (ts.isFunctionDeclaration(child)) {
-      return
-    }
-    getWorkflowInvocations(child, checker, state, workflowName, steps)
-  })
-}
-
-/**
- * Inspector for pikkuWorkflowFunc(), pikkuWorkflowComplexFunc() and
- * pikkuScenario() calls. Detects workflow registration and extracts metadata.
- */
-export const addWorkflow: AddWiring = (
-  logger,
-  node,
-  checker,
-  state,
-  options
-) => {
-  if (!ts.isCallExpression(node)) {
-    return
-  }
-
-  const args = node.arguments
-  const firstArg = args[0]
-  const expression = node.expression
-
-  if (!ts.isIdentifier(expression)) {
-    return
-  }
-
-  let wrapperType: 'dsl' | 'complex' | 'scenario' | null = null
-  if (expression.text === 'pikkuWorkflowFunc') {
-    wrapperType = 'dsl'
-  } else if (expression.text === 'pikkuWorkflowComplexFunc') {
-    if (!options.allow?.complexWorkflows) {
-      logger.critical(
-        ErrorCode.COMPLEX_WORKFLOW_NOT_ALLOWED,
-        `'${expression.text}' is used here, but this project has not enabled complex workflows. ` +
-          `Their inline steps cannot be serialized, so they are absent from the workflow graph and ` +
-          `cannot be replayed or migrated across a definition change. Express the workflow with ` +
-          `pikkuWorkflowFunc and the step DSL, or set \`allow: { complexWorkflows: true }\` in ` +
-          `pikku.config.json if the project accepts that trade.`
-      )
-      return
-    }
-    wrapperType = 'complex'
-  } else if (expression.text === 'pikkuScenario') {
-    // A scenario is a complex workflow whose steps run as actors over the
-    // real transport — same extraction rules as complex, distinct meta.
-    wrapperType = 'scenario'
-  } else {
-    return
-  }
-
-  if (!firstArg) {
-    return
-  }
-
-  // Extract workflow name and metadata using same logic as add-functions
-  const { pikkuFuncId, name, exportedName } = extractFunctionName(
-    node,
-    checker,
-    state.rootDir
-  )
-
-  const workflowName = exportedName || name
-
-  if (!workflowName) {
-    logger.critical(
-      ErrorCode.MISSING_NAME,
-      `Could not determine workflow name from export.`
-    )
-    return
-  }
-
-  // Extract the function node (either direct function or from config.func)
-  const { funcNode, resolvedFunc } = extractFunctionNode(firstArg, checker)
-
-  // Extract metadata if using object form
-  let tags: string[] | undefined
-  let title: string | undefined
-  let summary: string | undefined
-  let description: string | undefined
-  let errors: string[] | undefined
-  let expose: boolean | undefined
-  let skip: string | undefined
-
-  if (ts.isObjectLiteralExpression(firstArg)) {
-    const metadata = getCommonWireMetaData(
-      firstArg,
-      'Workflow',
-      workflowName,
-      logger,
-      checker
-    )
-    if (metadata.disabled) return
-    tags = metadata.tags
-    title = metadata.title
-    summary = metadata.summary
-    description = metadata.description
-    errors = metadata.errors
-
-    expose = getPropertyValue(firstArg, 'expose') as boolean | undefined
-    skip = (getPropertyValue(firstArg, 'skip') as string | null) ?? undefined
-  }
-
-  // Validate that we got a valid function
-  if (
-    ts.isObjectLiteralExpression(firstArg) &&
-    (!funcNode || funcNode === firstArg)
-  ) {
-    logger.critical(
-      ErrorCode.MISSING_FUNC,
-      `No valid 'func' property for workflow '${workflowName}'.`
-    )
-    return
-  }
-
-  if (!resolvedFunc) {
-    logger.critical(
-      ErrorCode.MISSING_FUNC,
-      `Could not resolve workflow function for '${workflowName}'.`
-    )
-    return
-  }
-
-  if (
-    wrapperType !== 'scenario' &&
-    containsExpectEventuallyCall(resolvedFunc)
-  ) {
-    logger.critical(
-      ErrorCode.EXPECT_EVENTUALLY_SCENARIO_ONLY,
-      `Workflow '${workflowName}' calls workflow.expectEventually(), which is only ` +
-        `available in scenarios (pikkuScenario). Move it into a scenario, or drive ` +
-        `the assertion outside the workflow.`
-    )
-    return
-  }
-
-  // Track workflow file for wiring generation
-  if (exportedName) {
-    state.workflows.files.set(pikkuFuncId, {
-      path: node.getSourceFile().fileName,
-      exportedName,
-    })
-  }
-
-  let steps: WorkflowStepMeta[] = []
-  let context: WorkflowContext | undefined = undefined
-  let dsl: boolean | undefined = undefined
-  let asserts: boolean | undefined = undefined
-
-  // Try DSL workflow extraction first
-  // Pass the whole CallExpression node so findWorkflowFunction can find the arrow function
-  const result = extractDSLWorkflow(node, checker, {
-    allowInline: wrapperType !== 'dsl',
-  })
-
-  if (result.status === 'ok' && result.steps) {
-    // Extraction succeeded
-    steps = result.steps
-    context = result.context
-    asserts = result.asserts
-
-    // Check if workflow contains inline steps (non-serializable)
-    if (hasInlineSteps(steps)) {
-      if (wrapperType === 'dsl') {
-        // pikkuWorkflowFunc should not have inline steps
-        logger.critical(
-          ErrorCode.INVALID_DSL_WORKFLOW,
-          `Workflow '${workflowName}' uses pikkuWorkflowFunc but contains inline steps which are not allowed in DSL workflows. Use pikkuWorkflowComplexFunc instead.`
-        )
-        return
-      }
-      // pikkuWorkflowComplexFunc with inline steps is marked as non-dsl
-      dsl = false
-    } else {
-      // pikkuWorkflowComplexFunc is always non-dsl, pikkuWorkflowFunc is dsl
-      dsl = wrapperType === 'dsl'
-    }
-
-    // Collect all invoked RPCs from workflow steps
-    const rpcs = new Set<string>()
-    collectInvokedRPCs(steps, rpcs)
-    for (const rpc of rpcs) {
-      state.rpc.invokedFunctions.add(rpc)
-    }
-  } else {
-    // DSL extraction failed
-    if (wrapperType === 'dsl') {
-      // For pikkuWorkflowFunc, this is a critical error
-      // But still track RPC invocations for function registration
-      getWorkflowInvocations(resolvedFunc, checker, state, workflowName, steps)
-      logger.critical(
-        ErrorCode.INVALID_DSL_WORKFLOW,
-        `Workflow '${workflowName}' does not conform to DSL workflow rules:\n${result.reason || 'Unknown error'}`
-      )
-      return
-    } else if (wrapperType === 'scenario') {
-      // The fallback below understands do/sleep but not step/given/when/then,
-      // so a scenario that lands here registers with zero steps. Silence would
-      // leave the whole scenario passing vacuously.
-      logger.critical(
-        ErrorCode.SCENARIO_NOT_EXTRACTABLE,
-        `Scenario '${workflowName}' could not be extracted, so none of its steps were recorded and it would run as an empty scenario:\n${result.reason || 'Unknown error'}`
-      )
-      return
-    } else {
-      // For pikkuWorkflowComplexFunc, fall back to basic extraction
-      logger.debug(
-        `Workflow '${workflowName}' could not be extracted as DSL workflow: ${result.reason || 'Unknown error'}. Falling back to basic extraction.`
-      )
-      dsl = false
-    }
-  }
-
-  // For pikkuWorkflowComplexFunc, also run basic extraction so RPCs in
-  // patterns the DSL extractor doesn't handle (array+push, nested Promise.all
-  // with identifier args, etc.) are still registered as invoked functions.
-  // When DSL extraction already produced steps this pass is registration-only:
-  // appending to `steps` would duplicate nodes and clobber the graph.
-  if (wrapperType !== 'dsl') {
-    const sink: WorkflowStepMeta[] = steps.length > 0 ? [] : steps
-    getWorkflowInvocations(resolvedFunc, checker, state, workflowName, sink)
-  }
-
-  // Actor names the flow's steps run as (scenarios) — powers the console
-  // personas view and the Scenario graph badges.
-  const actorNames = [
-    ...new Set(
-      steps
-        .map((s) => ('actor' in s ? s.actor : undefined))
-        .filter((a): a is string => typeof a === 'string')
-    ),
-  ]
-
-  state.workflows.meta[workflowName] = {
-    pikkuFuncId,
-    name: workflowName,
-    steps,
-    context,
-    dsl,
-    title,
-    summary,
-    description,
-    errors,
-    tags,
-    expose,
-    skip,
-    scenario: wrapperType === 'scenario' ? true : undefined,
-    asserts,
-    actors: actorNames.length > 0 ? actorNames : undefined,
-  }
-
-  // The scenario "logger/config only" rule (PKU673) and the implicit
-  // workflow platform-service injection both used to live here, reading
-  // state.functions.meta[pikkuFuncId]. addWorkflow runs in the visitSetup
-  // pass, which completes before addFunctions populates that meta, so both
-  // were dead. The rule now lives in validateScenarioServices (post-process),
-  // and aggregateRequiredServices already adds the platform services globally
-  // whenever any workflow exists.
-}