@pikku/inspector 0.11.1 → 0.12.0

package/src/add/add-permission.ts

@@ -1,14 +1,58 @@
 import * as ts from 'typescript'
-import { AddWiring } from '../types.js'
+import type { AddWiring, InspectorState } from '../types.js'
 import {
   extractFunctionName,
   isNamedExport,
+  makeContextBasedId,
 } from '../utils/extract-function-name.js'
-import { extractServicesFromFunction } from '../utils/extract-services.js'
+import {
+  extractServicesFromFunction,
+  extractUsedWires,
+} from '../utils/extract-services.js'
 import { extractPermissionPikkuNames } from '../utils/permissions.js'
 import { getPropertyValue } from '../utils/get-property-value.js'
 import { getPropertyAssignmentInitializer } from '../utils/type-utils.js'
 
+function renameTempDefinitions(
+  state: InspectorState,
+  definitionIds: string[],
+  groupType: string,
+  groupKey: string
+): void {
+  const tempIndices = definitionIds
+    .map((name, i) => (name.startsWith('__temp_') ? i : -1))
+    .filter((i) => i >= 0)
+
+  for (const idx of tempIndices) {
+    const oldId = definitionIds[idx]
+    const newId =
+      tempIndices.length === 1
+        ? makeContextBasedId(groupType, groupKey)
+        : makeContextBasedId(groupType, groupKey, String(idx))
+    const existing = state.permissions.definitions[oldId]
+    if (existing) {
+      delete state.permissions.definitions[oldId]
+      state.permissions.definitions[newId] = existing
+    }
+    definitionIds[idx] = newId
+  }
+}
+
+function isInsidePermissionFactory(node: ts.Node): boolean {
+  let current = node.parent
+  while (current) {
+    if (
+      ts.isCallExpression(current) &&
+      ts.isIdentifier(current.expression) &&
+      current.expression.text === 'pikkuPermissionFactory'
+    ) {
+      return true
+    }
+    current = current.parent
+  }
+  return false
+}
+
 /**
  * Inspect pikkuPermission calls, addPermission calls, and addHTTPPermission calls
  */
@@ -24,6 +68,9 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
 
   // Handle pikkuPermission(...) - individual permission function definition
   if (expression.text === 'pikkuPermission') {
+    // Skip if nested inside pikkuPermissionFactory — the factory handler extracts services itself
+    if (isInsidePermissionFactory(node)) return
+
     const arg = args[0]
     if (!arg) return
 
@@ -31,15 +78,12 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
     let name: string | undefined
     let description: string | undefined
 
-    // Check if using object syntax: pikkuPermission({ func: ..., name: '...', description: '...' })
     if (ts.isObjectLiteralExpression(arg)) {
-      // Extract name and description metadata
       const nameValue = getPropertyValue(arg, 'name')
       const descValue = getPropertyValue(arg, 'description')
       name = typeof nameValue === 'string' ? nameValue : undefined
       description = typeof descValue === 'string' ? descValue : undefined
 
-      // Extract the func property
       const fnProp = getPropertyAssignmentInitializer(
         arg,
         'func',
@@ -64,22 +108,129 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
     }
 
     const services = extractServicesFromFunction(actualHandler)
-    const { pikkuFuncName, exportedName } = extractFunctionName(
+    const wires = extractUsedWires(actualHandler, 2)
+    let { pikkuFuncId, exportedName } = extractFunctionName(
       node,
       checker,
       state.rootDir
     )
-    state.permissions.meta[pikkuFuncName] = {
+    if (pikkuFuncId.startsWith('__temp_')) {
+      if (
+        ts.isVariableDeclaration(node.parent) &&
+        ts.isIdentifier(node.parent.name)
+      ) {
+        pikkuFuncId = node.parent.name.text
+      } else if (
+        ts.isPropertyAssignment(node.parent) &&
+        ts.isIdentifier(node.parent.name)
+      ) {
+        pikkuFuncId = node.parent.name.text
+      } else {
+        logger.error(
+          `• pikkuPermission() must be assigned to a variable or object property. ` +
+            `Extract it to a const: const myPermission = pikkuPermission(...)`
+        )
+        return
+      }
+    }
+    const dataParam = actualHandler.parameters[1]
+    const dataParamName =
+      dataParam && ts.isIdentifier(dataParam.name) ? dataParam.name.text : null
+    const requiresData = !(dataParamName && dataParamName.startsWith('_'))
+
+    state.permissions.definitions[pikkuFuncId] = {
       services,
+      wires: wires.wires.length > 0 || !wires.optimized ? wires : undefined,
       sourceFile: node.getSourceFile().fileName,
       position: node.getStart(),
       exportedName,
       name,
       description,
+      ...(requiresData ? {} : { requiresData: false }),
     }
 
     logger.debug(
-      `• Found permission with services: ${services.services.join(', ')}${name ? ` (name: ${name})` : ''}${description ? ` (description: ${description})` : ''}`
+      `• Found permission with services: ${services.services.join(', ')}${name ? ` (name: ${name})` : ''}${description ? ` (description: ${description})` : ''}${!requiresData ? ' (auth-only)' : ''}`
+    )
+    return
+  }
+
+  if (expression.text === 'pikkuAuth') {
+    if (isInsidePermissionFactory(node)) return
+
+    const arg = args[0]
+    if (!arg) return
+
+    let actualHandler: ts.ArrowFunction | ts.FunctionExpression
+    let name: string | undefined
+    let description: string | undefined
+
+    if (ts.isObjectLiteralExpression(arg)) {
+      const nameValue = getPropertyValue(arg, 'name')
+      const descValue = getPropertyValue(arg, 'description')
+      name = typeof nameValue === 'string' ? nameValue : undefined
+      description = typeof descValue === 'string' ? descValue : undefined
+
+      const fnProp = getPropertyAssignmentInitializer(
+        arg,
+        'func',
+        true,
+        checker
+      )
+      if (
+        !fnProp ||
+        (!ts.isArrowFunction(fnProp) && !ts.isFunctionExpression(fnProp))
+      ) {
+        logger.error(`• pikkuAuth object missing required 'func' property.`)
+        return
+      }
+      actualHandler = fnProp
+    } else if (ts.isArrowFunction(arg) || ts.isFunctionExpression(arg)) {
+      actualHandler = arg
+    } else {
+      logger.error(`• Handler for pikkuAuth is not a function.`)
+      return
+    }
+
+    const services = extractServicesFromFunction(actualHandler)
+    const wires = extractUsedWires(actualHandler, 1)
+    let { pikkuFuncId, exportedName } = extractFunctionName(
+      node,
+      checker,
+      state.rootDir
+    )
+    if (pikkuFuncId.startsWith('__temp_')) {
+      if (
+        ts.isVariableDeclaration(node.parent) &&
+        ts.isIdentifier(node.parent.name)
+      ) {
+        pikkuFuncId = node.parent.name.text
+      } else if (
+        ts.isPropertyAssignment(node.parent) &&
+        ts.isIdentifier(node.parent.name)
+      ) {
+        pikkuFuncId = node.parent.name.text
+      } else {
+        logger.error(
+          `• pikkuAuth() must be assigned to a variable or object property. ` +
+            `Extract it to a const: const myAuth = pikkuAuth(...)`
+        )
+        return
+      }
+    }
+    state.permissions.definitions[pikkuFuncId] = {
+      services,
+      wires: wires.wires.length > 0 || !wires.optimized ? wires : undefined,
+      sourceFile: node.getSourceFile().fileName,
+      position: node.getStart(),
+      exportedName,
+      name,
+      description,
+      requiresData: false,
+    }
+
+    logger.debug(
+      `• Found auth permission with services: ${services.services.join(', ')}${name ? ` (name: ${name})` : ''}${description ? ` (description: ${description})` : ''}`
     )
     return
   }
@@ -101,6 +252,10 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
     // The factory should return pikkuPermission(...), so we need to find that call
     // If no wrapper is found, extract from the factory's returned function directly
     let services = { optimized: false, services: [] as string[] }
+    let wires: ReturnType<typeof extractUsedWires> = {
+      optimized: true,
+      wires: [],
+    }
 
     const findPikkuPermissionCall = (
       node: ts.Node
@@ -122,32 +277,51 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
         ts.isFunctionExpression(permissionHandler)
       ) {
         services = extractServicesFromFunction(permissionHandler)
+        wires = extractUsedWires(permissionHandler, 2)
       }
     } else {
-      // No pikkuPermission wrapper found - extract from factory's return value directly
-      // Factory pattern: (config) => (services, data, wire) => { ... }
       if (
         ts.isArrowFunction(factoryNode) ||
         ts.isFunctionExpression(factoryNode)
       ) {
         const factoryBody = factoryNode.body
-        // Check if the body is an arrow function (direct return)
         if (
           ts.isArrowFunction(factoryBody) ||
           ts.isFunctionExpression(factoryBody)
         ) {
           services = extractServicesFromFunction(factoryBody)
+          wires = extractUsedWires(factoryBody, 2)
         }
       }
     }
 
-    const { pikkuFuncName, exportedName } = extractFunctionName(
+    let { pikkuFuncId, exportedName } = extractFunctionName(
       node,
       checker,
       state.rootDir
     )
-    state.permissions.meta[pikkuFuncName] = {
+    if (pikkuFuncId.startsWith('__temp_')) {
+      if (
+        ts.isVariableDeclaration(node.parent) &&
+        ts.isIdentifier(node.parent.name)
+      ) {
+        pikkuFuncId = node.parent.name.text
+      } else if (
+        ts.isPropertyAssignment(node.parent) &&
+        ts.isIdentifier(node.parent.name)
+      ) {
+        pikkuFuncId = node.parent.name.text
+      } else {
+        logger.error(
+          `• pikkuPermissionFactory() must be assigned to a variable or object property. ` +
+            `Extract it to a const: const myPermission = pikkuPermissionFactory(...)`
+        )
+        return
+      }
+    }
+    state.permissions.definitions[pikkuFuncId] = {
       services,
+      wires: wires.wires.length > 0 || !wires.optimized ? wires : undefined,
       sourceFile: node.getSourceFile().fileName,
       position: node.getStart(),
       exportedName,
@@ -192,7 +366,7 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
       return
     }
 
-    // Extract permission pikkuFuncNames from array
+    // Extract permission pikkuFuncIds from array
     const permissionNames = extractPermissionPikkuNames(
       permissionsArrayArg,
       checker,
@@ -204,10 +378,11 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
       return
     }
 
-    // Collect services from all permissions in the group
+    renameTempDefinitions(state, permissionNames, 'tag', tag)
+
     const allServices = new Set<string>()
     for (const permissionName of permissionNames) {
-      const permissionMeta = state.permissions.meta[permissionName]
+      const permissionMeta = state.permissions.definitions[permissionName]
       if (permissionMeta && permissionMeta.services) {
         for (const service of permissionMeta.services.services) {
           allServices.add(service)
@@ -215,24 +390,17 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
       }
     }
 
-    // Check if this call is wrapped in a factory function
-    // We need to walk up the tree to see if the parent is: const x = () => addPermission(...)
     let isFactory = false
     let exportedName: string | null = null
     let parent = node.parent
 
-    // Check if parent is arrow function: () => addPermission(...)
     if (parent && ts.isArrowFunction(parent)) {
-      // Check if arrow function has no parameters
       if (parent.parameters.length === 0) {
         isFactory = true
 
-        // For factories, we need to check the arrow function's parent for the export name
-        // const apiTagPermissions = () => addPermission(...)
         const arrowParent = parent.parent
         if (arrowParent && ts.isVariableDeclaration(arrowParent)) {
           if (ts.isIdentifier(arrowParent.name)) {
-            // Check if it's exported
             if (isNamedExport(arrowParent)) {
               exportedName = arrowParent.name.text
             }
@@ -241,13 +409,11 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
       }
     }
 
-    // If not a factory, get export name from the call expression itself
     if (!isFactory) {
       const extracted = extractFunctionName(node, checker, state.rootDir)
       exportedName = extracted.exportedName
     }
 
-    // Log warning if not using factory pattern
     if (!isFactory && exportedName) {
       logger.warn(
         `• Permission group '${exportedName}' for tag '${tag}' is not wrapped in a factory function. ` +
@@ -255,7 +421,6 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
       )
     }
 
-    // Store group metadata
     state.permissions.tagPermissions.set(tag, {
       exportName: exportedName,
       sourceFile: node.getSourceFile().fileName,
@@ -264,7 +429,8 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
         optimized: false,
         services: Array.from(allServices),
       },
-      permissionCount: permissionNames.length,
+      count: permissionNames.length,
+      instanceIds: permissionNames,
       isFactory,
     })
 
@@ -306,7 +472,7 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
       return
     }
 
-    // Extract permission pikkuFuncNames from array
+    // Extract permission pikkuFuncIds from array
     const permissionNames = extractPermissionPikkuNames(
       permissionsArrayArg,
       checker,
@@ -320,10 +486,11 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
       return
     }
 
-    // Collect services from all permissions in the group
+    renameTempDefinitions(state, permissionNames, 'http', pattern)
+
     const allServices = new Set<string>()
     for (const permissionName of permissionNames) {
-      const permissionMeta = state.permissions.meta[permissionName]
+      const permissionMeta = state.permissions.definitions[permissionName]
       if (permissionMeta && permissionMeta.services) {
         for (const service of permissionMeta.services.services) {
           allServices.add(service)
@@ -331,23 +498,17 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
       }
     }
 
-    // Check if this call is wrapped in a factory function
     let isFactory = false
     let exportedName: string | null = null
     let parent = node.parent
 
-    // Check if parent is arrow function: () => addHTTPPermission(...)
     if (parent && ts.isArrowFunction(parent)) {
-      // Check if arrow function has no parameters
       if (parent.parameters.length === 0) {
         isFactory = true
 
-        // For factories, we need to check the arrow function's parent for the export name
-        // const apiRoutePermissions = () => addHTTPPermission(...)
         const arrowParent = parent.parent
         if (arrowParent && ts.isVariableDeclaration(arrowParent)) {
           if (ts.isIdentifier(arrowParent.name)) {
-            // Check if it's exported
             if (isNamedExport(arrowParent)) {
               exportedName = arrowParent.name.text
             }
@@ -356,13 +517,11 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
       }
     }
 
-    // If not a factory, get export name from the call expression itself
     if (!isFactory) {
       const extracted = extractFunctionName(node, checker, state.rootDir)
       exportedName = extracted.exportedName
     }
 
-    // Log warning if not using factory pattern
     if (!isFactory && exportedName) {
       logger.warn(
         `• HTTP permission group '${exportedName}' for pattern '${pattern}' is not wrapped in a factory function. ` +
@@ -370,7 +529,6 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
       )
     }
 
-    // Store group metadata
     state.http.routePermissions.set(pattern, {
       exportName: exportedName,
       sourceFile: node.getSourceFile().fileName,
@@ -379,7 +537,8 @@ export const addPermission: AddWiring = (logger, node, checker, state) => {
         optimized: false,
         services: Array.from(allServices),
       },
-      permissionCount: permissionNames.length,
+      count: permissionNames.length,
+      instanceIds: permissionNames,
       isFactory,
     })
 

package/src/add/add-queue-worker.ts

@@ -4,7 +4,10 @@ import {
   getCommonWireMetaData,
 } from '../utils/get-property-value.js'
 import { AddWiring } from '../types.js'
-import { extractFunctionName } from '../utils/extract-function-name.js'
+import {
+  extractFunctionName,
+  makeContextBasedId,
+} from '../utils/extract-function-name.js'
 import { getPropertyAssignmentInitializer } from '../utils/type-utils.js'
 import { resolveMiddleware } from '../utils/middleware.js'
 import { extractWireNames } from '../utils/post-process.js'
@@ -31,13 +34,11 @@ export const addQueueWorker: AddWiring = (logger, node, checker, state) => {
   if (ts.isObjectLiteralExpression(firstArg)) {
     const obj = firstArg
 
-    const queueName = getPropertyValue(obj, 'queueName') as string | null
-    const { tags, summary, description, errors } = getCommonWireMetaData(
-      obj,
-      'Queue worker',
-      queueName,
-      logger
-    )
+    const name = getPropertyValue(obj, 'name') as string | null
+    const { disabled, tags, summary, description, errors } =
+      getCommonWireMetaData(obj, 'Queue worker', name, logger)
+
+    if (disabled) return
 
     // --- find the referenced function ---
     const funcInitializer = getPropertyAssignmentInitializer(
@@ -49,21 +50,25 @@ export const addQueueWorker: AddWiring = (logger, node, checker, state) => {
     if (!funcInitializer) {
       logger.critical(
         ErrorCode.MISSING_FUNC,
-        `No valid 'func' property for queue processor '${queueName}'.`
+        `No valid 'func' property for queue processor '${name}'.`
       )
       return
     }
 
-    const pikkuFuncName = extractFunctionName(
+    const extracted = extractFunctionName(
       funcInitializer,
       checker,
       state.rootDir
-    ).pikkuFuncName
+    )
+    let pikkuFuncId = extracted.pikkuFuncId
+    if (pikkuFuncId.startsWith('__temp_') && name) {
+      pikkuFuncId = makeContextBasedId('queue', name)
+    }
 
-    if (!queueName) {
+    if (!name) {
       logger.critical(
         ErrorCode.MISSING_QUEUE_NAME,
-        `No 'queueName' provided for queue processor function '${pikkuFuncName}'.`
+        `No 'name' provided for queue processor function '${pikkuFuncId}'.`
       )
       return
     }
@@ -72,15 +77,15 @@ export const addQueueWorker: AddWiring = (logger, node, checker, state) => {
     const middleware = resolveMiddleware(state, obj, tags, checker)
 
     // --- track used functions/middleware for service aggregation ---
-    state.serviceAggregation.usedFunctions.add(pikkuFuncName)
-    extractWireNames(middleware).forEach((name) =>
-      state.serviceAggregation.usedMiddleware.add(name)
+    state.serviceAggregation.usedFunctions.add(pikkuFuncId)
+    extractWireNames(middleware).forEach((n) =>
+      state.serviceAggregation.usedMiddleware.add(n)
     )
 
     state.queueWorkers.files.add(node.getSourceFile().fileName)
-    state.queueWorkers.meta[queueName] = {
-      pikkuFuncName,
-      queueName,
+    state.queueWorkers.meta[name] = {
+      pikkuFuncId,
+      name,
       summary,
       description,
       errors,

package/src/add/add-rpc-invocations.ts

@@ -1,48 +1,95 @@
 import * as ts from 'typescript'
 import { InspectorState, InspectorLogger } from '../types.js'
 
+/**
+ * Helper to extract namespace from a namespaced function reference like 'ext:hello'
+ */
+function extractNamespace(functionRef: string): string | null {
+  const colonIndex = functionRef.indexOf(':')
+  if (colonIndex !== -1) {
+    return functionRef.substring(0, colonIndex)
+  }
+  return null
+}
+
 /**
  * Scan for rpc.invoke() calls to track which functions are actually being invoked
+ * Also detects external package usage via:
+ * - Namespaced calls: rpc.invoke('namespace:function')
+ * - External helper: external('namespace:function')
  */
 export function addRPCInvocations(
   node: ts.Node,
   state: InspectorState,
   logger: InspectorLogger
 ) {
-  // Look for property access expressions: rpc.invoke
-  if (ts.isPropertyAccessExpression(node)) {
-    const { expression, name } = node
+  // Look for call expressions: external('ext:hello') or rpc.invoke('...')
+  if (ts.isCallExpression(node)) {
+    const { expression, arguments: args } = node
+
+    // Check for external('namespace:function') calls
+    if (ts.isIdentifier(expression) && expression.text === 'external') {
+      const [firstArg] = args
+      if (firstArg && ts.isStringLiteral(firstArg)) {
+        const functionRef = firstArg.text
+        logger.debug(`• Found external() call: ${functionRef}`)
+        state.rpc.invokedFunctions.add(functionRef)
 
-    // Check if this is accessing 'invoke' property
-    if (name.text === 'invoke') {
-      // Check if the object is 'rpc' (or a variable containing rpc)
-      if (ts.isIdentifier(expression) && expression.text === 'rpc') {
-        // This is rpc.invoke - now we need to find the parent call expression
-        const parent = node.parent
-        if (ts.isCallExpression(parent) && parent.expression === node) {
-          // This is rpc.invoke('function-name')
-          const [firstArg] = parent.arguments
-          if (firstArg) {
-            // Extract the function name from string literal
-            if (ts.isStringLiteral(firstArg)) {
-              const functionName = firstArg.text
-              logger.debug(`• Found RPC invocation: ${functionName}`)
-              state.rpc.invokedFunctions.add(functionName)
-            }
-            // Handle template literals like `function-${name}`
-            else if (
-              ts.isTemplateExpression(firstArg) ||
-              ts.isNoSubstitutionTemplateLiteral(firstArg)
-            ) {
-              logger.warn(
-                `• Found dynamic RPC invocation: ${firstArg.getText()}`
-              )
-              logger.warn(
-                `\tYou can only use string literals for RPC function names, with ' or " and not \``
-              )
-            }
+        const namespace = extractNamespace(functionRef)
+        if (namespace) {
+          logger.debug(`  → External package detected: ${namespace}`)
+          state.rpc.usedExternalPackages.add(namespace)
+        }
+      }
+    }
+
+    // Check for workflow('...'), workflowStart('...'), workflowRun('...'), workflowStatus('...'), graphStart('...') calls
+    if (
+      ts.isIdentifier(expression) &&
+      (expression.text === 'workflow' ||
+        expression.text === 'workflowStart' ||
+        expression.text === 'workflowRun' ||
+        expression.text === 'workflowStatus' ||
+        expression.text === 'graphStart')
+    ) {
+      const [firstArg] = args
+      if (firstArg && ts.isStringLiteral(firstArg)) {
+        const workflowName = firstArg.text
+        logger.debug(`• Found ${expression.text}() call: ${workflowName}`)
+        state.workflows.invokedWorkflows.add(workflowName)
+      }
+    }
+
+    // Check for rpc.invoke('...') calls
+    if (
+      ts.isPropertyAccessExpression(expression) &&
+      expression.name.text === 'invoke' &&
+      ts.isIdentifier(expression.expression) &&
+      expression.expression.text === 'rpc'
+    ) {
+      const [firstArg] = args
+      if (firstArg) {
+        if (ts.isStringLiteral(firstArg)) {
+          const functionRef = firstArg.text
+          logger.debug(`• Found RPC invocation: ${functionRef}`)
+          state.rpc.invokedFunctions.add(functionRef)
+
+          const namespace = extractNamespace(functionRef)
+          if (namespace) {
+            logger.debug(`  → External package detected: ${namespace}`)
+            state.rpc.usedExternalPackages.add(namespace)
           }
         }
+        // Handle template literals like `function-${name}`
+        else if (
+          ts.isTemplateExpression(firstArg) ||
+          ts.isNoSubstitutionTemplateLiteral(firstArg)
+        ) {
+          logger.warn(`• Found dynamic RPC invocation: ${firstArg.getText()}`)
+          logger.warn(
+            `\tYou can only use string literals for RPC function names, with ' or " and not \``
+          )
+        }
       }
     }
   }