@pikku/inspector 0.12.21 → 0.12.23

package/src/add/add-http-routes.ts

@@ -1,45 +1,63 @@
 import * as ts from 'typescript'
 import { getPropertyValue } from '../utils/get-property-value.js'
-import type { AddWiring, InspectorState, InspectorLogger } from '../types.js'
-import { registerHTTPRoute } from './add-http-route.js'
+import type {
+  AddWiring,
+  ExportedHTTPRouteConfigMeta,
+  ExportedHTTPRouteMapMeta,
+  ExportedHTTPRoutesGroupMeta,
+  InspectorLogger,
+  InspectorState,
+} from '../types.js'
+import { registerHTTPRoute, registerHTTPRouteMeta } from './add-http-route.js'
 import { resolveIdentifier } from '../utils/resolve-identifier.js'
+import { extractFunctionName } from '../utils/extract-function-name.js'
+import { getPropertyAssignmentInitializer } from '../utils/type-utils.js'
+import { resolveAddonName } from '../utils/resolve-addon-package.js'
+import {
+  resolveRefContract,
+  type RefContractResolution,
+} from '../utils/resolve-ref-contract.js'
+import { getExportedVariableName } from '../utils/get-exported-variable-name.js'
 
-/**
- * Group configuration extracted from wireHTTPRoutes or defineHTTPRoutes
- */
 interface GroupConfig {
   basePath: string
   tags: string[]
   auth?: boolean
 }
 
-/**
- * Process wireHTTPRoutes calls
- */
 export const addHTTPRoutes: AddWiring = (
   logger,
   node,
   checker,
   state,
-  _options
+  options
 ) => {
   if (!ts.isCallExpression(node)) return
 
   const { expression, arguments: args } = node
-  if (!ts.isIdentifier(expression) || expression.text !== 'wireHTTPRoutes')
+  if (!ts.isIdentifier(expression)) return
+
+  if (expression.text === 'defineHTTPRoutes') {
+    const exportName = getExportedVariableName(node, options.sourceFile)
+    const firstArg = args[0]
+    if (exportName && firstArg && ts.isObjectLiteralExpression(firstArg)) {
+      const contract = serializeHTTPRoutesContract(firstArg, checker, state)
+      if (contract) {
+        state.exportedContracts.http[exportName] = contract
+      }
+    }
     return
+  }
+
+  if (expression.text !== 'wireHTTPRoutes') return
 
   const firstArg = args[0]
   if (!firstArg || !ts.isObjectLiteralExpression(firstArg)) return
 
-  // Extract group config
   const groupConfig = extractGroupConfig(firstArg)
-
-  // Get routes property
   const routesProp = getPropertyAssignment(firstArg, 'routes')
   if (!routesProp) return
 
-  // Process routes recursively
   processRoutes(
     routesProp.initializer,
     groupConfig,
@@ -50,9 +68,6 @@ export const addHTTPRoutes: AddWiring = (
   )
 }
 
-/**
- * Get a property assignment from an object literal
- */
 function getPropertyAssignment(
   obj: ts.ObjectLiteralExpression,
   propName: string
@@ -69,9 +84,6 @@ function getPropertyAssignment(
   return undefined
 }
 
-/**
- * Extract group configuration from an object literal
- */
 function extractGroupConfig(obj: ts.ObjectLiteralExpression): GroupConfig {
   const basePath = (getPropertyValue(obj, 'basePath') as string) || ''
   const tags = (getPropertyValue(obj, 'tags') as string[]) || []
@@ -84,9 +96,6 @@ function extractGroupConfig(obj: ts.ObjectLiteralExpression): GroupConfig {
   }
 }
 
-/**
- * Merge two group configs following cascading rules
- */
 function mergeConfigs(parent: GroupConfig, child: GroupConfig): GroupConfig {
   return {
     basePath: parent.basePath + child.basePath,
@@ -95,9 +104,6 @@ function mergeConfigs(parent: GroupConfig, child: GroupConfig): GroupConfig {
   }
 }
 
-/**
- * Check if a value is a route config (has method, func, and route)
- */
 function isRouteConfig(obj: ts.ObjectLiteralExpression): boolean {
   let hasMethod = false
   let hasFunc = false
@@ -114,9 +120,6 @@ function isRouteConfig(obj: ts.ObjectLiteralExpression): boolean {
   return hasMethod && hasFunc && hasRoute
 }
 
-/**
- * Check if a value is a route contract (has routes property but no method/func)
- */
 function isRouteContract(obj: ts.ObjectLiteralExpression): boolean {
   let hasRoutes = false
   let hasMethod = false
@@ -133,9 +136,6 @@ function isRouteContract(obj: ts.ObjectLiteralExpression): boolean {
   return hasRoutes && !hasMethod && !hasFunc
 }
 
-/**
- * Recursively process routes - handles nested maps, contracts, and identifiers
- */
 function processRoutes(
   node: ts.Node,
   parentConfig: GroupConfig,
@@ -144,7 +144,6 @@ function processRoutes(
   logger: InspectorLogger,
   sourceFile: ts.SourceFile
 ): void {
-  // Handle array of routes
   if (ts.isArrayLiteralExpression(node)) {
     for (const element of node.elements) {
       if (ts.isObjectLiteralExpression(element) && isRouteConfig(element)) {
@@ -154,15 +153,12 @@ function processRoutes(
     return
   }
 
-  // Handle object literal
   if (ts.isObjectLiteralExpression(node)) {
-    // Check if this is a route config
     if (isRouteConfig(node)) {
       processRoute(node, parentConfig, state, checker, logger, sourceFile)
       return
     }
 
-    // Check if this is a route contract
     if (isRouteContract(node)) {
       const contractConfig = extractGroupConfig(node)
       const mergedConfig = mergeConfigs(parentConfig, contractConfig)
@@ -180,9 +176,17 @@ function processRoutes(
       return
     }
 
-    // Otherwise it's a nested map - process each property
     for (const prop of node.properties) {
       if (ts.isPropertyAssignment(prop)) {
+        const ref = resolveRefContract(
+          prop.initializer,
+          'refHTTP',
+          state.exportedContracts.addonHttp
+        )
+        if (ref) {
+          processRefHTTPContract(ref, parentConfig, state, logger, sourceFile)
+          continue
+        }
         processRoutes(
           prop.initializer,
           parentConfig,
@@ -196,7 +200,18 @@ function processRoutes(
     return
   }
 
-  // Handle identifier - resolve to its definition
+  if (ts.isCallExpression(node)) {
+    const ref = resolveRefContract(
+      node,
+      'refHTTP',
+      state.exportedContracts.addonHttp
+    )
+    if (ref) {
+      processRefHTTPContract(ref, parentConfig, state, logger, sourceFile)
+    }
+    return
+  }
+
   if (ts.isIdentifier(node)) {
     const resolved = resolveIdentifier(node, checker, ['defineHTTPRoutes'])
     if (resolved) {
@@ -205,9 +220,236 @@ function processRoutes(
   }
 }
 
-/**
- * Register a single route using the shared registerHTTPRoute function
- */
+function processRefHTTPContract(
+  ref: RefContractResolution<ExportedHTTPRoutesGroupMeta>,
+  parentConfig: GroupConfig,
+  state: InspectorState,
+  logger: InspectorLogger,
+  sourceFile: ts.SourceFile
+): void {
+  const basePath =
+    ref.basePath !== undefined ? ref.basePath : ref.contract.basePath || ''
+  processExportedRouteMap(
+    ref.contract.routes,
+    mergeConfigs(parentConfig, {
+      basePath,
+      tags: ref.contract.tags || [],
+      auth: ref.contract.auth,
+    }),
+    state,
+    logger,
+    sourceFile
+  )
+}
+
+function processExportedRouteMap(
+  routes: ExportedHTTPRouteMapMeta,
+  parentConfig: GroupConfig,
+  state: InspectorState,
+  logger: InspectorLogger,
+  sourceFile: ts.SourceFile
+): void {
+  for (const value of Object.values(routes)) {
+    if (isExportedRouteConfig(value)) {
+      registerHTTPRouteMeta({
+        route: value,
+        state,
+        logger,
+        sourceFile,
+        basePath: parentConfig.basePath,
+        inheritedTags: parentConfig.tags,
+        inheritedAuth: parentConfig.auth,
+      })
+      continue
+    }
+
+    if (isExportedRouteContract(value)) {
+      processExportedRouteMap(
+        value.routes,
+        mergeConfigs(parentConfig, {
+          basePath: value.basePath || '',
+          tags: value.tags || [],
+          auth: value.auth,
+        }),
+        state,
+        logger,
+        sourceFile
+      )
+      continue
+    }
+
+    processExportedRouteMap(value, parentConfig, state, logger, sourceFile)
+  }
+}
+
+function isExportedRouteConfig(
+  value: ExportedHTTPRouteMapMeta[string]
+): value is ExportedHTTPRouteConfigMeta {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'method' in value &&
+    'route' in value &&
+    'func' in value
+  )
+}
+
+function isExportedRouteContract(
+  value: ExportedHTTPRouteMapMeta[string]
+): value is ExportedHTTPRoutesGroupMeta {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    'routes' in value &&
+    !('method' in value)
+  )
+}
+
+function serializeHTTPRoutesContract(
+  node: ts.ObjectLiteralExpression,
+  checker: ts.TypeChecker,
+  state: InspectorState
+): ExportedHTTPRoutesGroupMeta | null {
+  if (isRouteContract(node)) {
+    const routesProp = getPropertyAssignment(node, 'routes')
+    if (!routesProp || !ts.isObjectLiteralExpression(routesProp.initializer)) {
+      return null
+    }
+
+    return {
+      ...extractGroupConfig(node),
+      routes: serializeHTTPRouteMap(routesProp.initializer, checker, state),
+    }
+  }
+
+  return {
+    routes: serializeHTTPRouteMap(node, checker, state),
+  }
+}
+
+function serializeHTTPRouteMap(
+  node: ts.ObjectLiteralExpression,
+  checker: ts.TypeChecker,
+  state: InspectorState
+): ExportedHTTPRouteMapMeta {
+  const result: ExportedHTTPRouteMapMeta = {}
+
+  for (const prop of node.properties) {
+    if (!ts.isPropertyAssignment(prop)) continue
+
+    const key = prop.name.getText().replace(/^['"]|['"]$/g, '')
+    const value = prop.initializer
+
+    if (ts.isObjectLiteralExpression(value)) {
+      if (isRouteConfig(value)) {
+        const route = serializeHTTPRouteConfig(value, checker, state)
+        if (route) {
+          result[key] = route
+        }
+        continue
+      }
+
+      if (isRouteContract(value)) {
+        const routeContract = serializeHTTPRoutesContract(value, checker, state)
+        if (routeContract) {
+          result[key] = routeContract
+        }
+        continue
+      }
+
+      result[key] = serializeHTTPRouteMap(value, checker, state)
+      continue
+    }
+
+    if (ts.isIdentifier(value)) {
+      const resolved = resolveIdentifier(value, checker, ['defineHTTPRoutes'])
+      if (resolved && ts.isObjectLiteralExpression(resolved)) {
+        if (isRouteContract(resolved)) {
+          const routeContract = serializeHTTPRoutesContract(
+            resolved,
+            checker,
+            state
+          )
+          if (routeContract) {
+            result[key] = routeContract
+          }
+        } else {
+          result[key] = serializeHTTPRouteMap(resolved, checker, state)
+        }
+      }
+    }
+  }
+
+  return result
+}
+
+function serializeHTTPRouteConfig(
+  obj: ts.ObjectLiteralExpression,
+  checker: ts.TypeChecker,
+  state: InspectorState
+): ExportedHTTPRouteConfigMeta | null {
+  const method = getPropertyValue(obj, 'method') as string | null
+  const route = getPropertyValue(obj, 'route') as string | null
+  const funcInitializer = getPropertyAssignmentInitializer(
+    obj,
+    'func',
+    true,
+    checker
+  )
+
+  if (!method || !route || !funcInitializer) {
+    return null
+  }
+
+  let pikkuFuncId = extractFunctionName(
+    funcInitializer,
+    checker,
+    state.rootDir
+  ).pikkuFuncId
+  let packageName: string | undefined
+
+  if (
+    ts.isCallExpression(funcInitializer) &&
+    ts.isIdentifier(funcInitializer.expression) &&
+    funcInitializer.expression.text === 'ref'
+  ) {
+    const [firstArg] = funcInitializer.arguments
+    if (firstArg && ts.isStringLiteral(firstArg)) {
+      pikkuFuncId = firstArg.text
+      const addonNamespace = pikkuFuncId.includes(':')
+        ? pikkuFuncId.split(':')[0]
+        : null
+      packageName = addonNamespace
+        ? state.rpc.wireAddonDeclarations.get(addonNamespace)?.package
+        : undefined
+    }
+  } else if (ts.isIdentifier(funcInitializer)) {
+    packageName =
+      resolveAddonName(
+        funcInitializer,
+        checker,
+        state.rpc.wireAddonDeclarations
+      ) || undefined
+  }
+
+  return {
+    auth: getPropertyValue(obj, 'auth') as boolean | undefined,
+    contentType: getPropertyValue(obj, 'contentType') as string | undefined,
+    headers:
+      (getPropertyValue(obj, 'headers') as unknown as Record<string, string>) ||
+      undefined,
+    method,
+    route,
+    sse: getPropertyValue(obj, 'sse') as boolean | undefined,
+    tags: (getPropertyValue(obj, 'tags') as string[]) || undefined,
+    timeout: getPropertyValue(obj, 'timeout') as number | undefined,
+    func: {
+      pikkuFuncId,
+      ...(packageName && { packageName }),
+    },
+  }
+}
+
 function processRoute(
   obj: ts.ObjectLiteralExpression,
   groupConfig: GroupConfig,

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

@@ -0,0 +1,106 @@
+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,
+  }
+}
+
+const STEP_FILE = [
+  "import { pikkuSessionlessFunc } from '@pikku/core'",
+  'export const processEventLeadsStep = pikkuSessionlessFunc({',
+  '  func: async ({ logger }) => ({ persistedCount: 1 }),',
+  '})',
+].join('\n')
+
+describe('addWorkflow — Promise.all fanout RPC detection', () => {
+  test('registers fanout RPC when captured with `const x = await Promise.all(map(...))`', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-fanout-const-'))
+    const wfFile = join(rootDir, 'leads.workflow.ts')
+    const stepFile = join(rootDir, 'leads.steps.ts')
+
+    await writeFile(stepFile, STEP_FILE)
+    await writeFile(
+      wfFile,
+      [
+        "import { pikkuWorkflowFunc } from '@pikku/core/workflow'",
+        'export const extractLeadsWorkflow = pikkuWorkflowFunc(async (_, data, { workflow }) => {',
+        '  const events = [{ id: "a", name: "x" }]',
+        '  const processed = await Promise.all(',
+        '    events.map((event) =>',
+        "      workflow.do(`Enrich event ${event.id ?? event.name}`, 'processEventLeadsStep', { event })",
+        '    )',
+        '  )',
+        '  return { count: processed.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('processEventLeadsStep'),
+        'processEventLeadsStep should be registered when fanout is captured with const'
+      )
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+
+  test('registers fanout RPC with string-concatenation (`+`) step name, same as template literal', async () => {
+    const rootDir = await mkdtemp(join(tmpdir(), 'pikku-fanout-concat-'))
+    const wfFile = join(rootDir, 'leads.workflow.ts')
+    const stepFile = join(rootDir, 'leads.steps.ts')
+
+    await writeFile(stepFile, STEP_FILE)
+    await writeFile(
+      wfFile,
+      [
+        "import { pikkuWorkflowFunc } from '@pikku/core/workflow'",
+        'export const extractLeadsWorkflow = pikkuWorkflowFunc(async (_, data, { workflow }) => {',
+        '  const events = [{ id: "a", name: "x" }]',
+        '  await Promise.all(',
+        '    events.map((event) =>',
+        "      workflow.do('Enrich event ' + (event.id ?? event.name), 'processEventLeadsStep', { event })",
+        '    )',
+        '  )',
+        '  return { ok: true }',
+        '})',
+      ].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('processEventLeadsStep'),
+        'processEventLeadsStep should be registered even when the step name uses `+` concatenation with a non-static operand'
+      )
+    } finally {
+      await rm(rootDir, { recursive: true, force: true })
+    }
+  })
+})

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

@@ -14,6 +14,9 @@ function makeLogger(
     info: () => {},
     warn: () => {},
     error: () => {},
+    diagnostic: ({ code, message }) => {
+      criticals.push({ code, message })
+    },
     critical: (code: any, message: string) => {
       criticals.push({ code, message })
     },

package/src/add/add-workflow.ts

@@ -16,6 +16,20 @@ import {
   getPropertyValue,
 } from '../utils/get-property-value.js'
 import { extractDSLWorkflow } from '../utils/workflow/dsl/extract-dsl-workflow.js'
+import { getSourceText } 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)
+  }
+}
 
 /**
  * Recursively check if any step has inline type (non-serializable)
@@ -99,7 +113,7 @@ function getWorkflowInvocations(
           const optionsArg =
             args.length >= 4 ? args[args.length - 1] : undefined
 
-          const stepName = extractStringLiteral(stepNameArg, checker)
+          const stepName = extractStepName(stepNameArg, checker)
           const description =
             extractDescription(optionsArg, checker) ?? undefined
 
@@ -126,7 +140,7 @@ function getWorkflowInvocations(
           const stepNameArg = args[0]
           const durationArg = args[1]
 
-          const stepName = extractStringLiteral(stepNameArg, checker)
+          const stepName = extractStepName(stepNameArg, checker)
           const duration = extractDuration(durationArg, checker)
 
           steps.push({