@pikku/inspector 0.12.42 → 0.12.44

package/src/add/add-scope.ts

@@ -0,0 +1,225 @@
+import * as ts from 'typescript'
+import { getPropertyValue } from '../utils/get-property-value.js'
+import type { AddWiring, InspectorLogger } from '../types.js'
+import { ErrorCode } from '../error-codes.js'
+import type { ScopeNodeMeta } from '@pikku/core/scope'
+
+const SEPARATOR = ':'
+const WILDCARD = '*'
+
+/**
+ * Validates a single scope segment, reporting rather than throwing so the
+ * inspector can surface every problem in one pass.
+ *
+ * @returns true when the segment is usable.
+ */
+const isValidSegment = (
+  segment: string,
+  scopeName: string,
+  logger: InspectorLogger
+): boolean => {
+  if (segment.length === 0) {
+    logger.critical(
+      ErrorCode.INVALID_VALUE,
+      `Scope '${scopeName}' contains an empty segment.`
+    )
+    return false
+  }
+  if (segment.includes(SEPARATOR)) {
+    logger.critical(
+      ErrorCode.INVALID_VALUE,
+      `Scope segment '${segment}' in '${scopeName}' contains the '${SEPARATOR}' separator. ` +
+        `Nest scopes with the 'scopes' property instead of embedding '${SEPARATOR}' in a name.`
+    )
+    return false
+  }
+  if (segment === WILDCARD) {
+    logger.critical(
+      ErrorCode.INVALID_VALUE,
+      `Scope segment '${segment}' in '${scopeName}' is the wildcard. ` +
+        `'${WILDCARD}' is reserved for granting a scope and its descendants, and cannot be declared.`
+    )
+    return false
+  }
+  return true
+}
+
+/**
+ * Recursively extracts a `scopes: { ... }` object literal into nested metadata.
+ */
+const extractScopeNodes = (
+  obj: ts.ObjectLiteralExpression,
+  scopeName: string,
+  logger: InspectorLogger
+): Record<string, ScopeNodeMeta> | undefined => {
+  const nodes: Record<string, ScopeNodeMeta> = {}
+
+  for (const prop of obj.properties) {
+    if (!ts.isPropertyAssignment(prop)) {
+      continue
+    }
+
+    let segment: string | undefined
+    if (ts.isIdentifier(prop.name)) {
+      segment = prop.name.text
+    } else if (ts.isStringLiteral(prop.name)) {
+      segment = prop.name.text
+    }
+
+    if (segment === undefined) {
+      logger.critical(
+        ErrorCode.NON_LITERAL_WIRE_NAME,
+        `Scope '${scopeName}' has a nested scope whose key is not a literal.`
+      )
+      continue
+    }
+
+    if (!isValidSegment(segment, scopeName, logger)) {
+      continue
+    }
+
+    if (!ts.isObjectLiteralExpression(prop.initializer)) {
+      logger.critical(
+        ErrorCode.INVALID_VALUE,
+        `Nested scope '${segment}' in '${scopeName}' must be an object literal.`
+      )
+      continue
+    }
+
+    const node: ScopeNodeMeta = {}
+    const displayName = getPropertyValue(prop.initializer, 'displayName') as
+      | string
+      | null
+    if (displayName) {
+      node.displayName = displayName
+    }
+    const description = getPropertyValue(prop.initializer, 'description') as
+      | string
+      | null
+    if (description) {
+      node.description = description
+    }
+
+    const nestedProp = prop.initializer.properties.find(
+      (p) =>
+        ts.isPropertyAssignment(p) &&
+        ts.isIdentifier(p.name) &&
+        p.name.text === 'scopes'
+    )
+    if (
+      nestedProp &&
+      ts.isPropertyAssignment(nestedProp) &&
+      ts.isObjectLiteralExpression(nestedProp.initializer)
+    ) {
+      const nested = extractScopeNodes(
+        nestedProp.initializer,
+        scopeName,
+        logger
+      )
+      if (nested) {
+        node.scopes = nested
+      }
+    }
+
+    nodes[segment] = node
+  }
+
+  return Object.keys(nodes).length > 0 ? nodes : undefined
+}
+
+/**
+ * Unwraps `x as const` / `x as any` so a cast declaration is still extracted
+ * rather than silently skipped.
+ */
+const unwrapAs = (node: ts.Expression): ts.Expression =>
+  ts.isAsExpression(node) || ts.isSatisfiesExpression(node)
+    ? unwrapAs(node.expression)
+    : node
+
+export const addScope: AddWiring = (logger, node, checker, state, _options) => {
+  if (!ts.isCallExpression(node)) {
+    return
+  }
+
+  const expression = node.expression
+  if (!ts.isIdentifier(expression) || expression.text !== 'wireScope') {
+    return
+  }
+
+  const firstArg = node.arguments[0]
+  if (!firstArg) {
+    return
+  }
+
+  const unwrapped = unwrapAs(firstArg)
+  if (!ts.isObjectLiteralExpression(unwrapped)) {
+    return
+  }
+
+  const sourceFile = node.getSourceFile().fileName
+
+  // Roots are keyed exactly like the nodes beneath them, so each property of
+  // the call's single argument is one tree.
+  for (const prop of unwrapped.properties) {
+    if (!ts.isPropertyAssignment(prop)) {
+      continue
+    }
+
+    let name: string | undefined
+    if (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)) {
+      name = prop.name.text
+    }
+
+    if (name === undefined) {
+      logger.critical(
+        ErrorCode.NON_LITERAL_WIRE_NAME,
+        'A scope is declared with a key that is not a literal.'
+      )
+      continue
+    }
+
+    if (!isValidSegment(name, name, logger)) {
+      continue
+    }
+
+    if (!ts.isObjectLiteralExpression(prop.initializer)) {
+      logger.critical(
+        ErrorCode.INVALID_VALUE,
+        `Scope '${name}' must be an object literal.`
+      )
+      continue
+    }
+
+    const root = prop.initializer
+    const displayNameValue = getPropertyValue(root, 'displayName') as
+      | string
+      | null
+    const descriptionValue = getPropertyValue(root, 'description') as
+      | string
+      | null
+
+    let scopes: Record<string, ScopeNodeMeta> | undefined
+    const scopesProp = root.properties.find(
+      (p) =>
+        ts.isPropertyAssignment(p) &&
+        ts.isIdentifier(p.name) &&
+        p.name.text === 'scopes'
+    )
+    if (
+      scopesProp &&
+      ts.isPropertyAssignment(scopesProp) &&
+      ts.isObjectLiteralExpression(scopesProp.initializer)
+    ) {
+      scopes = extractScopeNodes(scopesProp.initializer, name, logger)
+    }
+
+    state.scopes.files.add(sourceFile)
+    state.scopes.definitions.push({
+      name,
+      displayName: displayNameValue || undefined,
+      description: descriptionValue || undefined,
+      scopes,
+      sourceFile,
+    })
+  }
+}

package/src/add/add-trigger.ts

@@ -9,6 +9,7 @@ import {
   makeContextBasedId,
 } from '../utils/extract-function-name.js'
 import { getPropertyAssignmentInitializer } from '../utils/type-utils.js'
+import { ensureInlineWiringFunction } from '../utils/ensure-function-metadata.js'
 import { resolveMiddleware } from '../utils/middleware.js'
 import { extractWireNames } from '../utils/post-process.js'
 import { resolveAddonName } from '../utils/resolve-addon-package.js'
@@ -83,6 +84,16 @@ const addWireTrigger: (
     return
   }
 
+  // Register metadata for a func inlined into the wiring (see helper).
+  ensureInlineWiringFunction(
+    state,
+    pikkuFuncId,
+    nameValue,
+    funcInitializer,
+    checker,
+    extracted.isHelper
+  )
+
   // --- resolve middleware ---
   const middleware = resolveMiddleware(state, obj, tags, checker)
 

package/src/add/add-wire-remote-addon.ts

@@ -0,0 +1,77 @@
+import * as ts from 'typescript'
+import type { InspectorState, InspectorLogger } from '../types.js'
+
+/**
+ * Detect wireRemoteAddon({ name: '...', package: '...' }) call expressions and
+ * record the namespace as a **remote** addon declaration. Only name + package
+ * are needed for codegen (serverUrl/auth are runtime closures resolved by the
+ * RPC runner); the `remote` marker tells the consumer's RPC-map generator to
+ * import the addon's `.remote.gen` map instead of `.internal.gen`.
+ */
+export function addWireRemoteAddon(
+  node: ts.Node,
+  state: InspectorState,
+  logger: InspectorLogger
+) {
+  if (!ts.isCallExpression(node)) return
+
+  const { expression, arguments: args } = node
+  if (!ts.isIdentifier(expression) || expression.text !== 'wireRemoteAddon')
+    return
+
+  const [firstArg] = args
+  if (!firstArg || !ts.isObjectLiteralExpression(firstArg)) return
+
+  let name: string | undefined
+  let pkg: string | undefined
+  // The auth binding is a runtime closure; we only extract the statically
+  // knowable slot names so `pikku verify` can check they exist in the
+  // consumer's own wirings. `hasAuth` distinguishes "public" (omitted) from
+  // "bound via a custom resolve()" (present but no static id).
+  let hasAuth = false
+  let authCredentialId: string | undefined
+  let authSecretId: string | undefined
+
+  for (const prop of firstArg.properties) {
+    if (!ts.isPropertyAssignment(prop) || !ts.isIdentifier(prop.name)) continue
+    const key = prop.name.text
+    if (key === 'name' && ts.isStringLiteral(prop.initializer)) {
+      name = prop.initializer.text
+    } else if (key === 'package' && ts.isStringLiteral(prop.initializer)) {
+      pkg = prop.initializer.text
+    } else if (
+      key === 'auth' &&
+      ts.isObjectLiteralExpression(prop.initializer)
+    ) {
+      hasAuth = true
+      for (const authProp of prop.initializer.properties) {
+        if (!ts.isPropertyAssignment(authProp) || !ts.isIdentifier(authProp.name))
+          continue
+        if (
+          authProp.name.text === 'credentialId' &&
+          ts.isStringLiteral(authProp.initializer)
+        ) {
+          authCredentialId = authProp.initializer.text
+        } else if (
+          authProp.name.text === 'secretId' &&
+          ts.isStringLiteral(authProp.initializer)
+        ) {
+          authSecretId = authProp.initializer.text
+        }
+      }
+    }
+  }
+
+  if (!name || !pkg) return
+
+  logger.debug(`• Found wireRemoteAddon: ${name} → ${pkg} (remote)`)
+  state.rpc.wireAddonDeclarations.set(name, {
+    package: pkg,
+    remote: true,
+    hasAuth,
+    authCredentialId,
+    authSecretId,
+  })
+  state.rpc.usedAddons.add(name)
+  state.rpc.wireAddonFiles.add(node.getSourceFile().fileName)
+}

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-graph-input.test.ts

@@ -0,0 +1,94 @@
+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 — node input extraction', () => {
+  test('`as const` and imported template() values survive into the serialized input', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-graph-input-'))
+    const stepFile = join(rootDir, 'my.steps.ts')
+    const graphFile = join(rootDir, 'my.graph.ts')
+
+    await writeFile(
+      stepFile,
+      [
+        "import { pikkuSessionlessFunc } from '@pikku/core'",
+        'export const edit = pikkuSessionlessFunc({ func: async () => ({ ok: true }) })',
+      ].join('\n')
+    )
+
+    await writeFile(
+      graphFile,
+      [
+        "import { pikkuWorkflowGraph } from '@pikku/core/workflow'",
+        "import { template } from '@pikku/core/workflow'",
+        'export const myGraph = pikkuWorkflowGraph({',
+        "  name: 'input-graph',",
+        "  nodes: { edit: 'edit' },",
+        '  config: {',
+        '    edit: {',
+        '      input: (ref) => ({',
+        "        method: 'GET' as const,",
+        '        operations: [',
+        "          { field: 'product', operation: 'set' as const, value: 'widget' },",
+        "          { field: 'email', operation: 'set' as const, value: ref('trigger', 'body.email') },",
+        "          { field: 'greeting', operation: 'set' as const, value: template('Hi $0', [ref('trigger', 'body.name')]) },",
+        '        ],',
+        '      }),',
+        '    },',
+        '  },',
+        '})',
+      ].join('\n')
+    )
+
+    try {
+      const state = await inspect(makeLogger(), [stepFile, graphFile], {
+        rootDir,
+      })
+      const graph = state.workflows.graphMeta['input-graph']
+      assert.ok(graph, 'graph meta should be registered')
+      const input = (graph.nodes['edit'] as { input?: any }).input
+      assert.ok(input, 'node input should be extracted')
+
+      // Bug 1 — top-level `X as const` must not be dropped.
+      assert.equal(input.method, 'GET', 'top-level `as const` value preserved')
+
+      // Bug 1 — nested `as const` inside an array element must not be dropped.
+      assert.equal(input.operations[0].operation, 'set')
+      assert.equal(input.operations[0].value, 'widget')
+      assert.equal(input.operations[1].operation, 'set')
+
+      // ref() still works alongside the fix.
+      assert.deepEqual(input.operations[1].value, {
+        $ref: 'trigger',
+        path: 'body.email',
+      })
+
+      // Bug 2 — imported template() (arrow has only `ref`, no 2nd param) preserved.
+      assert.equal(input.operations[2].operation, 'set')
+      assert.deepEqual(input.operations[2].value, {
+        $template: {
+          parts: ['Hi ', ''],
+          expressions: [{ $ref: 'trigger', path: 'body.name' }],
+        },
+      })
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+})