@pikku/inspector 0.11.0 → 0.11.1

package/src/add/add-workflow.ts

@@ -1,29 +1,21 @@
 import * as ts from 'typescript'
-import {
-  getPropertyValue,
-  getPropertyTags,
-} from '../utils/get-property-value.js'
-import { PikkuDocs } from '@pikku/core'
 import { AddWiring, InspectorState } from '../types.js'
 import { extractFunctionName } from '../utils/extract-function-name.js'
-import {
-  getPropertyAssignmentInitializer,
-  resolveFunctionDeclaration,
-} from '../utils/type-utils.js'
-import { resolveMiddleware } from '../utils/middleware.js'
-import { extractWireNames } from '../utils/post-process.js'
+import { extractFunctionNode } from '../utils/extract-function-node.js'
 import { ErrorCode } from '../error-codes.js'
 import { WorkflowStepMeta } from '@pikku/core/workflow'
 import {
   extractStringLiteral,
-  extractNumberLiteral,
-  extractPropertyString,
   isStringLike,
   isFunctionLike,
+  extractDescription,
+  extractDuration,
 } from '../utils/extract-node-value.js'
+import { extractSimpleWorkflow } from '../workflow/extract-simple-workflow.js'
+import { getCommonWireMetaData } from '../utils/get-property-value.js'
 
 /**
- * Scan for workflow.do() and workflow.sleep() calls to extract workflow steps
+ * Scan for workflow.do(), workflow.sleep(), and workflow.cancel() calls to extract workflow steps
  */
 function getWorkflowInvocations(
   node: ts.Node,
@@ -37,7 +29,7 @@ function getWorkflowInvocations(
     const { name } = node
 
     // Check if this is accessing 'do' or 'sleep' property
-    if (name.text === 'do' || name.text === 'sleep') {
+    if (name.text === 'do' || name.text === 'sleep' || name.text === 'cancel') {
       // Check if the parent is a call expression
       const parent = node.parent
       if (ts.isCallExpression(parent) && parent.expression === node) {
@@ -62,7 +54,6 @@ function getWorkflowInvocations(
               type: 'rpc',
               stepName,
               rpcName,
-              description,
             })
             state.rpc.invokedFunctions.add(rpcName)
           } else if (isFunctionLike(secondArg)) {
@@ -86,6 +77,11 @@ function getWorkflowInvocations(
             stepName: stepName || '<dynamic>',
             duration: duration || '<dynamic>',
           })
+        } else if (name.text === 'cancel') {
+          // workflow.cancel(reason?)
+          steps.push({
+            type: 'cancel',
+          })
         }
       }
     }
@@ -105,43 +101,10 @@ function getWorkflowInvocations(
 }
 
 /**
- * Extract description from options object
- */
-function extractDescription(
-  optionsNode: ts.Node | undefined,
-  checker: ts.TypeChecker
-): string | null {
-  if (!optionsNode || !ts.isObjectLiteralExpression(optionsNode)) {
-    return null
-  }
-  return extractPropertyString(optionsNode, 'description', checker)
-}
-
-/**
- * Extract duration value (number or string)
- */
-function extractDuration(
-  node: ts.Node,
-  checker: ts.TypeChecker
-): string | number | null {
-  const numValue = extractNumberLiteral(node)
-  if (numValue !== null) {
-    return numValue
-  }
-  return extractStringLiteral(node, checker)
-}
-
-/**
- * Inspector for wireWorkflow() calls
+ * Inspector for pikkuWorkflow() and pikkuSimpleWorkflow() calls
  * Detects workflow registration and extracts metadata
  */
-export const addWorkflow: AddWiring = (
-  logger,
-  node,
-  checker,
-  state,
-  options
-) => {
+export const addWorkflow: AddWiring = (logger, node, checker, state) => {
   if (!ts.isCallExpression(node)) {
     return
   }
@@ -150,8 +113,16 @@ export const addWorkflow: AddWiring = (
   const firstArg = args[0]
   const expression = node.expression
 
-  // Check if the call is to wireWorkflow
-  if (!ts.isIdentifier(expression) || expression.text !== 'wireWorkflow') {
+  if (!ts.isIdentifier(expression)) {
+    return
+  }
+
+  let wrapperType: 'simple' | 'regular' | null = null
+  if (expression.text === 'pikkuWorkflowFunc') {
+    wrapperType = 'regular'
+  } else if (expression.text === 'pikkuSimpleWorkflowFunc') {
+    wrapperType = 'simple'
+  } else {
     return
   }
 
@@ -159,73 +130,112 @@ export const addWorkflow: AddWiring = (
     return
   }
 
-  if (ts.isObjectLiteralExpression(firstArg)) {
-    const obj = firstArg
-
-    const workflowName = getPropertyValue(obj, 'name') as string | null
-    const description = getPropertyValue(obj, 'description') as
-      | string
-      | undefined
-    const docs = (getPropertyValue(obj, 'docs') as PikkuDocs) || undefined
-    const tags = getPropertyTags(obj, 'Workflow', workflowName, logger)
-
-    // --- find the referenced function ---
-    const funcInitializer = getPropertyAssignmentInitializer(
-      obj,
-      'func',
-      true,
-      checker
+  // Extract workflow name and metadata using same logic as add-functions
+  const { pikkuFuncName, 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
+  }
 
-    if (!workflowName) {
-      logger.critical(
-        ErrorCode.MISSING_NAME,
-        `Wasn't able to determine 'name' property for workflow wiring.`
-      )
-      return
-    }
+  // Extract the function node (either direct function or from config.func)
+  const { funcNode, resolvedFunc } = extractFunctionNode(firstArg, checker)
 
-    if (!funcInitializer) {
-      logger.critical(
-        ErrorCode.MISSING_FUNC,
-        `No valid 'func' property for workflow '${workflowName}'.`
-      )
-      return
-    }
+  // Extract metadata if using object form
+  let tags: string[] | undefined
+  let summary: string | undefined
+  let description: string | undefined
+  let errors: string[] | undefined
 
-    const pikkuFuncName = extractFunctionName(
-      funcInitializer,
-      checker,
-      state.rootDir
-    ).pikkuFuncName
+  if (ts.isObjectLiteralExpression(firstArg)) {
+    const metadata = getCommonWireMetaData(
+      firstArg,
+      'Workflow',
+      workflowName,
+      logger
+    )
+    tags = metadata.tags
+    summary = metadata.summary
+    description = metadata.description
+    errors = metadata.errors
+  }
 
-    // --- resolve middleware ---
-    const middleware = resolveMiddleware(state, obj, tags, checker)
+  // 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
+  }
 
-    // --- track used functions/middleware for service aggregation ---
-    state.serviceAggregation.usedFunctions.add(pikkuFuncName)
-    extractWireNames(middleware).forEach((name) =>
-      state.serviceAggregation.usedMiddleware.add(name)
+  if (!resolvedFunc) {
+    logger.critical(
+      ErrorCode.MISSING_FUNC,
+      `Could not resolve workflow function for '${workflowName}'.`
     )
+    return
+  }
 
-    state.workflows.files.add(node.getSourceFile().fileName)
+  // Track workflow file for wiring generation
+  if (exportedName) {
+    state.workflows.files.set(pikkuFuncName, {
+      path: node.getSourceFile().fileName,
+      exportedName,
+    })
+  }
 
-    // Extract workflow steps from function body
-    // Resolve the identifier to the actual function declaration
-    const resolvedFunc = resolveFunctionDeclaration(funcInitializer, checker)
-    const steps: WorkflowStepMeta[] = []
-    if (resolvedFunc) {
-      getWorkflowInvocations(resolvedFunc, checker, state, workflowName, steps)
+  let steps: WorkflowStepMeta[] = []
+  let simple: boolean | undefined = undefined
+
+  // Try simple workflow extraction first
+  // Pass the whole CallExpression node so findWorkflowFunction can find the arrow function
+  const result = extractSimpleWorkflow(node, checker)
+
+  if (result.status === 'ok' && result.steps) {
+    // Simple extraction succeeded
+    steps = result.steps
+    simple = true
+  } else {
+    // Simple extraction failed
+    if (wrapperType === 'simple') {
+      // For pikkuSimpleWorkflowFunc, this is a critical error
+      logger.critical(
+        ErrorCode.INVALID_SIMPLE_WORKFLOW,
+        `Workflow '${workflowName}' uses pikkuSimpleWorkflowFunc but does not conform to simple workflow DSL:\n${result.reason || 'Unknown error'}`
+      )
+      return
+    } else {
+      // For pikkuWorkflowFunc, fall back to basic extraction
+      logger.debug(
+        `Workflow '${workflowName}' could not be extracted as simple workflow: ${result.reason || 'Unknown error'}. Falling back to basic extraction.`
+      )
+      simple = false
     }
+  }
 
-    state.workflows.meta[workflowName] = {
-      pikkuFuncName,
-      workflowName,
-      description,
-      docs,
-      tags,
-      middleware,
-      steps,
-    }
+  getWorkflowInvocations(resolvedFunc, checker, state, workflowName, steps)
+
+  state.workflows.meta[workflowName] = {
+    pikkuFuncName,
+    workflowName,
+    steps,
+    simple,
+    summary,
+    description,
+    errors,
+    tags,
   }
 }

package/src/error-codes.ts

@@ -21,6 +21,7 @@ export enum ErrorCode {
   CLI_CLIENTSIDE_RENDERER_HAS_SERVICES = 'PKU672',
   DYNAMIC_STEP_NAME = 'PKU529',
   WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED = 'PKU600',
+  INVALID_SIMPLE_WORKFLOW = 'PKU641',
 
   // Configuration errors
   CONFIG_TYPE_NOT_FOUND = 'PKU426',

package/src/index.ts

@@ -14,3 +14,5 @@ export {
 } from './utils/serialize-inspector-state.js'
 export type { SerializableInspectorState } from './utils/serialize-inspector-state.js'
 export { filterInspectorState } from './utils/filter-inspector-state.js'
+export { writeAllServiceMetadata } from './utils/write-service-metadata.js'
+export type { ServiceMetadata } from './utils/extract-service-metadata.js'

package/src/inspector.ts

@@ -5,7 +5,10 @@ import { TypesMap } from './types-map.js'
 import { InspectorState, InspectorLogger, InspectorOptions } from './types.js'
 import { getFilesAndMethods } from './utils/get-files-and-methods.js'
 import { findCommonAncestor } from './utils/find-root-dir.js'
-import { aggregateRequiredServices } from './utils/post-process.js'
+import {
+  aggregateRequiredServices,
+  extractServiceInterfaceMetadata,
+} from './utils/post-process.js'
 
 /**
  * Creates an initial/empty inspector state with all required properties initialized
@@ -16,12 +19,12 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
   return {
     rootDir,
     singletonServicesTypeImportMap: new Map(),
-    sessionServicesTypeImportMap: new Map(),
+    wireServicesTypeImportMap: new Map(),
     userSessionTypeImportMap: new Map(),
     configTypeImportMap: new Map(),
     singletonServicesFactories: new Map(),
-    sessionServicesFactories: new Map(),
-    sessionServicesMeta: new Map(),
+    wireServicesFactories: new Map(),
+    wireServicesMeta: new Map(),
     configFactories: new Map(),
     filesAndMethods: {},
     filesAndMethodsErrors: new Map(),
@@ -60,7 +63,7 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
     },
     workflows: {
       meta: {},
-      files: new Set(),
+      files: new Map(),
     },
     rpc: {
       internalMeta: {},
@@ -96,8 +99,9 @@ export function getInitialInspectorState(rootDir: string): InspectorState {
       usedMiddleware: new Set(),
       usedPermissions: new Set(),
       allSingletonServices: [],
-      allSessionServices: [],
+      allWireServices: [],
     },
+    serviceMetadata: [],
   }
 }
 
@@ -177,6 +181,12 @@ export const inspect = (
     logger.debug(
       `Aggregate required services completed in ${(performance.now() - startAggregate).toFixed(2)}ms`
     )
+
+    const startServiceMeta = performance.now()
+    extractServiceInterfaceMetadata(state, checker)
+    logger.debug(
+      `Extract service metadata completed in ${(performance.now() - startServiceMeta).toFixed(2)}ms`
+    )
   }
 
   return state

package/src/types.ts

@@ -120,7 +120,7 @@ export type InspectorOptions = Partial<{
     configFileType: string
     userSessionType: string
     singletonServicesFactoryType: string
-    sessionServicesFactoryType: string
+    wireServicesFactoryType: string
   }>
 }>
 
@@ -147,7 +147,7 @@ export interface InspectorFilesAndMethods {
     type: string
     typePath: string
   }
-  sessionServicesType?: {
+  wireServicesType?: {
     file: string
     variable: string
     type: string
@@ -177,7 +177,7 @@ export interface InspectorFilesAndMethods {
     type: string
     typePath: string
   }
-  sessionServicesFactory?: {
+  wireServicesFactory?: {
     file: string
     variable: string
     type: string
@@ -188,12 +188,12 @@ export interface InspectorFilesAndMethods {
 export interface InspectorState {
   rootDir: string // Root directory inferred from source files
   singletonServicesTypeImportMap: PathToNameAndType
-  sessionServicesTypeImportMap: PathToNameAndType
+  wireServicesTypeImportMap: PathToNameAndType
   userSessionTypeImportMap: PathToNameAndType
   configTypeImportMap: PathToNameAndType
   singletonServicesFactories: PathToNameAndType
-  sessionServicesFactories: PathToNameAndType
-  sessionServicesMeta: Map<string, string[]> // variable name -> singleton services consumed
+  wireServicesFactories: PathToNameAndType
+  wireServicesMeta: Map<string, string[]> // variable name -> singleton services consumed
   configFactories: PathToNameAndType
   filesAndMethods: InspectorFilesAndMethods
   filesAndMethodsErrors: Map<string, PathToNameAndType>
@@ -211,7 +211,7 @@ export interface InspectorState {
   }
   workflows: {
     meta: WorkflowsMeta
-    files: Set<string>
+    files: Map<string, { path: string; exportedName: string }>
   }
   rpc: {
     internalMeta: Record<string, string>
@@ -238,6 +238,16 @@ export interface InspectorState {
     usedMiddleware: Set<string> // Middleware names used by wired functions
     usedPermissions: Set<string> // Permission names used by wired functions
     allSingletonServices: string[] // All services available in SingletonServices type
-    allSessionServices: string[] // All services available in Services type (excluding SingletonServices)
+    allWireServices: string[] // All services available in Services type (excluding SingletonServices)
   }
+  serviceMetadata: Array<{
+    name: string
+    summary: string
+    description: string
+    package: string
+    path: string
+    version: string
+    interface: string
+    expandedProperties: Record<string, string>
+  }>
 }

package/src/utils/extract-function-node.ts

@@ -0,0 +1,58 @@
+import * as ts from 'typescript'
+import {
+  getPropertyAssignmentInitializer,
+  resolveFunctionDeclaration,
+} from './type-utils.js'
+
+/**
+ * Extracts the actual function node from a pikkuFunc/pikkuWorkflowFunc call
+ * Handles both direct function form and config object form { func: ... }
+ */
+export function extractFunctionNode(
+  firstArg: ts.Expression,
+  checker: ts.TypeChecker
+): {
+  funcNode: ts.Node
+  resolvedFunc: ts.Node | null
+  isDirectFunction: boolean
+} {
+  let funcNode: ts.Node = firstArg
+  let isDirectFunction = true
+
+  // Check if first argument is a config object with 'func' property
+  if (ts.isObjectLiteralExpression(firstArg)) {
+    isDirectFunction = false
+    const funcInitializer = getPropertyAssignmentInitializer(
+      firstArg,
+      'func',
+      true,
+      checker
+    )
+
+    if (funcInitializer) {
+      funcNode = funcInitializer
+    } else {
+      // Return the original node if no func property found
+      // Caller should handle validation
+      funcNode = firstArg
+    }
+  }
+
+  // Resolve identifier to get the actual function node
+  if (ts.isIdentifier(funcNode)) {
+    const symbol = checker.getSymbolAtLocation(funcNode)
+    const decl = symbol?.valueDeclaration || symbol?.declarations?.[0]
+    if (decl && ts.isVariableDeclaration(decl) && decl.initializer) {
+      funcNode = decl.initializer
+    }
+  }
+
+  // Resolve function declaration for deeper analysis
+  const resolvedFunc = resolveFunctionDeclaration(funcNode, checker)
+
+  return {
+    funcNode,
+    resolvedFunc,
+    isDirectFunction,
+  }
+}

package/src/utils/extract-node-value.ts

@@ -99,3 +99,34 @@ export function extractPropertyString(
   }
   return null
 }
+
+/**
+ * Extract description from options object
+ */
+export function extractDescription(
+  optionsNode: ts.Node | undefined,
+  checker: ts.TypeChecker
+): string | null {
+  if (!optionsNode || !ts.isObjectLiteralExpression(optionsNode)) {
+    return null
+  }
+  return extractPropertyString(optionsNode, 'description', checker)
+}
+
+/**
+ * Extract duration value (number or string)
+ */
+export function extractDuration(
+  node: ts.Node,
+  checker: ts.TypeChecker
+): string | number | null {
+  const numValue = extractNumberLiteral(node)
+  if (numValue !== null) {
+    return numValue
+  }
+  try {
+    return extractStringLiteral(node, checker)
+  } catch {
+    return null
+  }
+}