@pikku/inspector 0.12.74 → 0.12.81

package/src/utils/workflow/dsl/index.ts

@@ -1,11 +0,0 @@
-/**
- * DSL (Domain Specific Language) workflow extraction exports
- */
-export { extractDSLWorkflow } from './extract-dsl-workflow.js'
-export {
-  deserializeDslWorkflow,
-  deserializeGraphWorkflow,
-  deserializeAllDslWorkflows,
-} from './deserialize-dsl-workflow.js'
-export * from './patterns.js'
-export * from './validation.js'

package/src/utils/workflow/dsl/patterns.ts

@@ -1,440 +0,0 @@
-import * as ts from 'typescript'
-
-/**
- * Pattern detection helpers for DSL workflow extraction
- */
-
-/**
- * The wire object handed to a DSL func is named `workflow` in a workflow and
- * `scenario` in a scenario — both carry the same `do`/`sleep`/`suspend` DSL, so
- * step extraction accepts either identifier.
- */
-export function isWorkflowWireIdentifier(expr: ts.Expression): boolean {
-  return (
-    ts.isIdentifier(expr) &&
-    (expr.text === 'workflow' || expr.text === 'scenario')
-  )
-}
-
-/**
- * Check if a call expression is workflow.do() or workflow.expectEventually()
- * (both are RPC steps; expectEventually is the polling variant used by scenarios)
- */
-export function isWorkflowDoCall(
-  node: ts.CallExpression,
-  checker: ts.TypeChecker
-): boolean {
-  if (!ts.isPropertyAccessExpression(node.expression)) {
-    return false
-  }
-
-  const propAccess = node.expression
-  return (
-    (propAccess.name.text === 'do' ||
-      propAccess.name.text === 'expectEventually') &&
-    isWorkflowWireIdentifier(propAccess.expression)
-  )
-}
-
-/**
- * Placeholder recorded when a scenario step's target isn't a static string
- * literal. The step is kept rather than dropped so post-processing can raise
- * PKU678 against it — a dropped step is the silent-failure mode this repo has
- * hit repeatedly on workflow graph round-trips.
- */
-export const DYNAMIC_SCENARIO_STEP_TARGET = '<dynamic>'
-
-const SCENARIO_STEP_PHASES = ['given', 'when', 'then'] as const
-
-export type ScenarioStepPhaseName = (typeof SCENARIO_STEP_PHASES)[number]
-
-/**
- * Check if a call expression is scenario.given()/when()/then() — a declared
- * `pikkuScenarioStep` invoked by name. `given`/`when` are pure sugar for each
- * other; `then` additionally makes the step's bindings witnesses.
- */
-export function isScenarioStepCall(node: ts.CallExpression): boolean {
-  return getScenarioStepPhase(node) !== undefined
-}
-
-/**
- * The Gherkin-style phase of a scenario step call, or undefined when the call
- * isn't one.
- */
-export function getScenarioStepPhase(
-  node: ts.CallExpression
-): ScenarioStepPhaseName | undefined {
-  if (!ts.isPropertyAccessExpression(node.expression)) {
-    return
-  }
-  const propAccess = node.expression
-  if (!isWorkflowWireIdentifier(propAccess.expression)) {
-    return
-  }
-  return SCENARIO_STEP_PHASES.find((phase) => phase === propAccess.name.text)
-}
-
-/**
- * The expectation helpers that assert without being a `then`.
- *
- * `expectService`, `expectError` and `expectScore` are inline steps rather than
- * scenario steps, so they carry no phase and never reach the step meta — but
- * each one is a witness: a recorded service call, a refusal, or a graded run.
- * PKU680 has to see them, or a scenario whose only assertion is one of these
- * reads as asserting nothing.
- */
-const SCENARIO_EXPECTATION_CALLS = [
-  'expectService',
-  'expectError',
-  'expectEventually',
-  'expectScore',
-] as const
-
-/**
- * Check if a call expression is one of the scenario expectation helpers —
- * `scenario.expectService()`, `.expectError()`, `.expectEventually()` or
- * `.expectScore()`.
- */
-export function isScenarioExpectationCall(node: ts.CallExpression): boolean {
-  return (
-    ts.isPropertyAccessExpression(node.expression) &&
-    SCENARIO_EXPECTATION_CALLS.some(
-      (name) =>
-        name === (node.expression as ts.PropertyAccessExpression).name.text
-    ) &&
-    isWorkflowWireIdentifier(node.expression.expression)
-  )
-}
-
-/**
- * Check if a call expression is workflow.expectEventually()
- */
-export function isWorkflowExpectEventuallyCall(
-  node: ts.CallExpression
-): boolean {
-  return (
-    ts.isPropertyAccessExpression(node.expression) &&
-    node.expression.name.text === 'expectEventually' &&
-    isWorkflowWireIdentifier(node.expression.expression)
-  )
-}
-
-/**
- * Extract the actor NAME from a step options object literal:
- * `{ actor: actors.x }` → 'x' (also `actors['x']`). Undefined when absent
- * or not statically resolvable.
- */
-export function extractActorFromOptions(
-  optionsArg: ts.Expression | undefined
-): string | undefined {
-  if (!optionsArg || !ts.isObjectLiteralExpression(optionsArg)) return
-  for (const prop of optionsArg.properties) {
-    if (
-      ts.isPropertyAssignment(prop) &&
-      ts.isIdentifier(prop.name) &&
-      prop.name.text === 'actor'
-    ) {
-      const init = prop.initializer
-      if (ts.isPropertyAccessExpression(init)) {
-        return init.name.text
-      }
-      if (
-        ts.isElementAccessExpression(init) &&
-        ts.isStringLiteral(init.argumentExpression)
-      ) {
-        return init.argumentExpression.text
-      }
-    }
-  }
-  return
-}
-
-/**
- * Check if a call expression is workflow.sleep()
- */
-export function isWorkflowSleepCall(
-  node: ts.CallExpression,
-  checker: ts.TypeChecker
-): boolean {
-  if (!ts.isPropertyAccessExpression(node.expression)) {
-    return false
-  }
-
-  const propAccess = node.expression
-  return (
-    propAccess.name.text === 'sleep' &&
-    isWorkflowWireIdentifier(propAccess.expression)
-  )
-}
-
-/**
- * Check if a call expression is workflow.suspend()
- */
-export function isWorkflowSuspendCall(
-  node: ts.CallExpression,
-  _checker: ts.TypeChecker
-): boolean {
-  if (!ts.isPropertyAccessExpression(node.expression)) {
-    return false
-  }
-
-  const propAccess = node.expression
-  return (
-    propAccess.name.text === 'suspend' &&
-    isWorkflowWireIdentifier(propAccess.expression)
-  )
-}
-
-/**
- * Check if a call expression is workflow.approval()
- */
-export function isWorkflowApprovalCall(
-  node: ts.CallExpression,
-  _checker: ts.TypeChecker
-): boolean {
-  if (!ts.isPropertyAccessExpression(node.expression)) {
-    return false
-  }
-
-  const propAccess = node.expression
-  return (
-    propAccess.name.text === 'approval' &&
-    isWorkflowWireIdentifier(propAccess.expression)
-  )
-}
-
-/**
- * Check if a throw statement throws WorkflowCancelledException
- * Matches: throw new WorkflowCancelledException(...) or throw WorkflowCancelledException(...)
- */
-export function isThrowCancelException(node: ts.ThrowStatement): boolean {
-  const expr = node.expression
-  if (!expr) return false
-
-  // Check for: throw new WorkflowCancelledException(...)
-  if (ts.isNewExpression(expr)) {
-    if (ts.isIdentifier(expr.expression)) {
-      return expr.expression.text === 'WorkflowCancelledException'
-    }
-  }
-
-  // Check for: throw WorkflowCancelledException(...) - function call style
-  if (ts.isCallExpression(expr)) {
-    if (ts.isIdentifier(expr.expression)) {
-      return expr.expression.text === 'WorkflowCancelledException'
-    }
-  }
-
-  return false
-}
-
-/**
- * Extract the reason string from a throw WorkflowCancelledException statement
- */
-export function extractCancelReason(
-  node: ts.ThrowStatement,
-  checker: ts.TypeChecker
-): string | undefined {
-  const expr = node.expression
-  if (!expr) return undefined
-
-  let args: ts.NodeArray<ts.Expression> | undefined
-
-  if (ts.isNewExpression(expr) && expr.arguments) {
-    args = expr.arguments
-  } else if (ts.isCallExpression(expr)) {
-    args = expr.arguments
-  }
-
-  if (args && args.length > 0) {
-    const firstArg = args[0]
-    if (ts.isStringLiteral(firstArg)) {
-      return firstArg.text
-    }
-    // For template literals or other expressions, return the source text
-    return firstArg.getText()
-  }
-
-  return undefined
-}
-
-/**
- * Check if a call expression is array.filter()
- */
-export function isArrayFilter(node: ts.CallExpression): boolean {
-  if (!ts.isPropertyAccessExpression(node.expression)) {
-    return false
-  }
-
-  return node.expression.name.text === 'filter'
-}
-
-/**
- * Check if a call expression is array.some()
- */
-export function isArraySome(node: ts.CallExpression): boolean {
-  if (!ts.isPropertyAccessExpression(node.expression)) {
-    return false
-  }
-
-  return node.expression.name.text === 'some'
-}
-
-/**
- * Check if a call expression is array.every()
- */
-export function isArrayEvery(node: ts.CallExpression): boolean {
-  if (!ts.isPropertyAccessExpression(node.expression)) {
-    return false
-  }
-
-  return node.expression.name.text === 'every'
-}
-
-/**
- * Check if an expression is Promise.all(array.map(...))
- */
-export function isParallelFanout(node: ts.CallExpression): boolean {
-  // Promise.all(...)
-  if (!ts.isPropertyAccessExpression(node.expression)) {
-    return false
-  }
-
-  const propAccess = node.expression
-  if (
-    !ts.isIdentifier(propAccess.expression) ||
-    propAccess.expression.text !== 'Promise' ||
-    propAccess.name.text !== 'all'
-  ) {
-    return false
-  }
-
-  // Check if argument is array.map(...)
-  const arg = node.arguments[0]
-  if (!arg || !ts.isCallExpression(arg)) {
-    return false
-  }
-
-  if (!ts.isPropertyAccessExpression(arg.expression)) {
-    return false
-  }
-
-  return arg.expression.name.text === 'map'
-}
-
-/**
- * Check if an expression is Promise.all([...])
- */
-export function isParallelGroup(node: ts.CallExpression): boolean {
-  // Promise.all(...)
-  if (!ts.isPropertyAccessExpression(node.expression)) {
-    return false
-  }
-
-  const propAccess = node.expression
-  if (
-    !ts.isIdentifier(propAccess.expression) ||
-    propAccess.expression.text !== 'Promise' ||
-    propAccess.name.text !== 'all'
-  ) {
-    return false
-  }
-
-  // Check if argument is an array literal
-  const arg = node.arguments[0]
-  return !!arg && ts.isArrayLiteralExpression(arg)
-}
-
-/**
- * Check if a for statement is a valid sequential fanout (for..of)
- */
-export function isSequentialFanout(node: ts.ForOfStatement): boolean {
-  // Must have const declaration
-  if (!ts.isVariableDeclarationList(node.initializer)) {
-    return false
-  }
-
-  const declList = node.initializer
-  if (!(declList.flags & ts.NodeFlags.Const)) {
-    return false
-  }
-
-  // Must have exactly one declaration
-  if (declList.declarations.length !== 1) {
-    return false
-  }
-
-  return true
-}
-
-/**
- * Extract full source path from an expression (e.g., data.memberEmails)
- */
-export function extractSourcePath(expr: ts.Expression): string | null {
-  if (ts.isIdentifier(expr)) {
-    return expr.text
-  }
-
-  if (ts.isPropertyAccessExpression(expr)) {
-    const base = extractSourcePath(expr.expression)
-    if (base) {
-      return `${base}.${expr.name.text}`
-    }
-  }
-
-  return null
-}
-
-/**
- * Extract the variable name from a for..of statement
- */
-export function extractForOfVariable(
-  node: ts.ForOfStatement
-): { itemVar: string; sourceVar: string } | null {
-  if (!ts.isVariableDeclarationList(node.initializer)) {
-    return null
-  }
-
-  const decl = node.initializer.declarations[0]
-  if (!ts.isIdentifier(decl.name)) {
-    return null
-  }
-
-  const itemVar = decl.name.text
-
-  // Extract source variable with full path (e.g., data.memberEmails)
-  const sourceVar = extractSourcePath(node.expression)
-
-  if (!sourceVar) {
-    return null
-  }
-
-  return { itemVar, sourceVar }
-}
-
-/**
- * Check if a type is an array type
- */
-export function isArrayType(type: ts.Type, checker: ts.TypeChecker): boolean {
-  // Check if it's an array type
-  if (checker.isArrayType(type)) {
-    return true
-  }
-
-  // Check if it's a tuple type
-  if (type.flags & ts.TypeFlags.Object) {
-    const objectType = type as ts.ObjectType
-    if (objectType.objectFlags & ts.ObjectFlags.Tuple) {
-      return true
-    }
-  }
-
-  return false
-}
-
-/**
- * Get the source text of a node (for condition expressions)
- */
-export function getSourceText(node: ts.Node): string {
-  return node.getText().trim()
-}

package/src/utils/workflow/dsl/validation.ts

@@ -1,203 +0,0 @@
-import * as ts from 'typescript'
-import { isWorkflowWireIdentifier } from './patterns.js'
-
-/**
- * Validation rules for DSL workflows
- */
-
-export interface ValidationError {
-  message: string
-  node: ts.Node
-}
-
-/**
- * Check if a node contains only allowed patterns
- *
- * Allowed patterns:
- * - VariableStatement (const/let declarations)
- * - ExpressionStatement (await workflow.do, await workflow.sleep, await Promise.all)
- * - IfStatement (branches)
- * - SwitchStatement (switch/case)
- * - ForOfStatement (sequential fanout)
- * - ReturnStatement
- * - ThrowStatement (for WorkflowCancelledException)
- * - Block (containers)
- *
- * When `allowInline` is set (complex workflows and scenarios), the bodies of
- * closures are skipped: a callback is ordinary TypeScript, not DSL, so holding
- * it to the statement whitelist would reject valid code. Plain DSL workflows
- * still descend into callbacks, which is what validates fanout bodies.
- */
-export function validateNoDisallowedPatterns(
-  node: ts.Node,
-  options?: { allowInline?: boolean }
-): ValidationError[] {
-  const errors: ValidationError[] = []
-
-  function visitBlock(block: ts.Block) {
-    for (const statement of block.statements) {
-      if (
-        ts.isVariableStatement(statement) ||
-        ts.isExpressionStatement(statement) ||
-        ts.isIfStatement(statement) ||
-        ts.isSwitchStatement(statement) ||
-        ts.isForOfStatement(statement) ||
-        ts.isReturnStatement(statement) ||
-        ts.isThrowStatement(statement)
-      ) {
-        // Allowed statement type - recurse into it
-        visitNode(statement)
-      } else {
-        // Unknown/disallowed statement type
-        const nodeType = ts.SyntaxKind[statement.kind]
-        errors.push({
-          message: `Statement type '${nodeType}' is not allowed in DSL workflows. Allowed: const/let, if/else, switch/case, for..of, return, throw, and workflow calls. If this should be supported, please report the node type: ${nodeType}`,
-          node: statement,
-        })
-      }
-    }
-  }
-
-  function visitNode(node: ts.Node) {
-    if (
-      options?.allowInline &&
-      (ts.isArrowFunction(node) || ts.isFunctionExpression(node))
-    ) {
-      return
-    }
-
-    // Disallow while and do-while
-    if (ts.isWhileStatement(node) || ts.isDoStatement(node)) {
-      errors.push({
-        message: 'while and do-while loops are not allowed in DSL workflows',
-        node,
-      })
-      return
-    }
-
-    // Disallow for and for-in loops
-    if (ts.isForInStatement(node) || ts.isForStatement(node)) {
-      errors.push({
-        message:
-          'for and for-in loops are not allowed in DSL workflows. Use for-of instead.',
-        node,
-      })
-      return
-    }
-
-    // Check for inline workflow.do
-    if (!options?.allowInline && ts.isCallExpression(node)) {
-      if (ts.isPropertyAccessExpression(node.expression)) {
-        const propAccess = node.expression
-        if (
-          propAccess.name.text === 'do' &&
-          isWorkflowWireIdentifier(propAccess.expression)
-        ) {
-          const secondArg = node.arguments[1]
-          if (
-            secondArg &&
-            (ts.isArrowFunction(secondArg) ||
-              ts.isFunctionExpression(secondArg))
-          ) {
-            errors.push({
-              message:
-                'Inline workflow.do with function argument is not allowed in DSL workflows. Use pikkuWorkflowComplexFunc instead.',
-              node,
-            })
-            return
-          }
-        }
-      }
-    }
-
-    // Recurse into blocks
-    if (ts.isBlock(node)) {
-      visitBlock(node)
-    } else {
-      ts.forEachChild(node, visitNode)
-    }
-  }
-
-  visitNode(node)
-  return errors
-}
-
-/**
- * Validate that all workflow.do calls are awaited
- */
-export function validateAwaitedCalls(node: ts.Node): ValidationError[] {
-  const errors: ValidationError[] = []
-
-  function visit(
-    node: ts.Node,
-    parentIsAwait: boolean = false,
-    insidePromiseAll: boolean = false
-  ) {
-    // Check if this is Promise.all(...) first, before checking for workflow calls
-    if (
-      ts.isCallExpression(node) &&
-      ts.isPropertyAccessExpression(node.expression)
-    ) {
-      const propAccess = node.expression
-      if (
-        propAccess.name.text === 'all' &&
-        ts.isIdentifier(propAccess.expression) &&
-        propAccess.expression.text === 'Promise'
-      ) {
-        ts.forEachChild(node, (child) => visit(child, parentIsAwait, true))
-        return
-      }
-      // .push() on an array — workflow.do() inside is collecting promises
-      if (propAccess.name.text === 'push') {
-        ts.forEachChild(node, (child) => visit(child, parentIsAwait, true))
-        return
-      }
-    }
-
-    // Array literal — workflow.do() inside is collecting promises
-    if (ts.isArrayLiteralExpression(node)) {
-      ts.forEachChild(node, (child) => visit(child, parentIsAwait, true))
-      return
-    }
-
-    // Now check for workflow calls
-    if (ts.isCallExpression(node)) {
-      if (ts.isPropertyAccessExpression(node.expression)) {
-        const propAccess = node.expression
-        if (
-          (propAccess.name.text === 'do' || propAccess.name.text === 'sleep') &&
-          isWorkflowWireIdentifier(propAccess.expression)
-        ) {
-          if (!parentIsAwait && !insidePromiseAll) {
-            errors.push({
-              message: `workflow.${propAccess.name.text}() must be awaited`,
-              node,
-            })
-          }
-          return
-        }
-      }
-    }
-
-    if (ts.isAwaitExpression(node)) {
-      // Visit the expression itself with parentIsAwait=true
-      visit(node.expression, true, insidePromiseAll)
-    } else {
-      ts.forEachChild(node, (child) => visit(child, false, insidePromiseAll))
-    }
-  }
-
-  visit(node)
-  return errors
-}
-
-/**
- * Combine all validation errors into a single error message
- */
-export function formatValidationErrors(errors: ValidationError[]): string {
-  if (errors.length === 0) {
-    return ''
-  }
-
-  return errors.map((err) => `- ${err.message}`).join('\n')
-}

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

@@ -1,35 +0,0 @@
-import { test } from 'node:test'
-import assert from 'node:assert'
-import { convertDslToGraph } from './convert-dsl-to-graph.js'
-import type { WorkflowsMeta } from '@pikku/core/workflow'
-
-const scenarioMeta = (
-  overrides: Partial<WorkflowsMeta[string]> = {}
-): WorkflowsMeta[string] => ({
-  pikkuFuncId: 'installAddonFreshNameScenario',
-  name: 'installAddonFreshNameScenario',
-  scenario: true,
-  steps: [],
-  ...overrides,
-})
-
-test('convertDslToGraph: a scenario carries its skip reason into the graph', () => {
-  const graph = convertDslToGraph(
-    'installAddonFreshNameScenario',
-    scenarioMeta({ skip: 'npm cannot install inside this yarn workspace' })
-  )
-
-  assert.strictEqual(
-    graph.skip,
-    'npm cannot install inside this yarn workspace'
-  )
-})
-
-test('convertDslToGraph: a scenario with no skip leaves it unset', () => {
-  const graph = convertDslToGraph(
-    'installAddonFreshNameScenario',
-    scenarioMeta()
-  )
-
-  assert.strictEqual(graph.skip, undefined)
-})