@pikku/inspector 0.9.5 → 0.10.0

package/src/add/add-permission.ts

@@ -0,0 +1,391 @@
+import * as ts from 'typescript'
+import { AddWiring } from '../types.js'
+import {
+  extractFunctionName,
+  isNamedExport,
+} from '../utils/extract-function-name.js'
+import { extractServicesFromFunction } 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'
+
+/**
+ * Inspect pikkuPermission calls, addPermission calls, and addHTTPPermission calls
+ */
+export const addPermission: AddWiring = (logger, node, checker, state) => {
+  if (!ts.isCallExpression(node)) return
+
+  const { expression, arguments: args } = node
+
+  // only handle specific function calls
+  if (!ts.isIdentifier(expression)) {
+    return
+  }
+
+  // Handle pikkuPermission(...) - individual permission function definition
+  if (expression.text === 'pikkuPermission') {
+    const arg = args[0]
+    if (!arg) return
+
+    let actualHandler: ts.ArrowFunction | ts.FunctionExpression
+    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',
+        true,
+        checker
+      )
+      if (
+        !fnProp ||
+        (!ts.isArrowFunction(fnProp) && !ts.isFunctionExpression(fnProp))
+      ) {
+        logger.error(
+          `• pikkuPermission object missing required 'func' property.`
+        )
+        return
+      }
+      actualHandler = fnProp
+    } else if (ts.isArrowFunction(arg) || ts.isFunctionExpression(arg)) {
+      actualHandler = arg
+    } else {
+      logger.error(`• Handler for pikkuPermission is not a function.`)
+      return
+    }
+
+    const services = extractServicesFromFunction(actualHandler)
+    const { pikkuFuncName, exportedName } = extractFunctionName(
+      node,
+      checker,
+      state.rootDir
+    )
+    state.permissions.meta[pikkuFuncName] = {
+      services,
+      sourceFile: node.getSourceFile().fileName,
+      position: node.getStart(),
+      exportedName,
+      name,
+      description,
+    }
+
+    logger.debug(
+      `• Found permission with services: ${services.services.join(', ')}${name ? ` (name: ${name})` : ''}${description ? ` (description: ${description})` : ''}`
+    )
+    return
+  }
+
+  // Handle pikkuPermissionFactory(...) - permission factory function
+  if (expression.text === 'pikkuPermissionFactory') {
+    const factoryNode = args[0]
+    if (!factoryNode) return
+
+    if (
+      !ts.isArrowFunction(factoryNode) &&
+      !ts.isFunctionExpression(factoryNode)
+    ) {
+      logger.error(`• Handler for pikkuPermissionFactory is not a function.`)
+      return
+    }
+
+    // Extract services by looking inside the factory function body
+    // 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[] }
+
+    const findPikkuPermissionCall = (
+      node: ts.Node
+    ): ts.CallExpression | undefined => {
+      if (ts.isCallExpression(node)) {
+        const expr = node.expression
+        if (ts.isIdentifier(expr) && expr.text === 'pikkuPermission') {
+          return node
+        }
+      }
+      return ts.forEachChild(node, findPikkuPermissionCall)
+    }
+
+    const pikkuPermissionCall = findPikkuPermissionCall(factoryNode)
+    if (pikkuPermissionCall && pikkuPermissionCall.arguments[0]) {
+      const permissionHandler = pikkuPermissionCall.arguments[0]
+      if (
+        ts.isArrowFunction(permissionHandler) ||
+        ts.isFunctionExpression(permissionHandler)
+      ) {
+        services = extractServicesFromFunction(permissionHandler)
+      }
+    } else {
+      // No pikkuPermission wrapper found - extract from factory's return value directly
+      // Factory pattern: (config) => (services, data, session) => { ... }
+      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)
+        }
+      }
+    }
+
+    const { pikkuFuncName, exportedName } = extractFunctionName(
+      node,
+      checker,
+      state.rootDir
+    )
+    state.permissions.meta[pikkuFuncName] = {
+      services,
+      sourceFile: node.getSourceFile().fileName,
+      position: node.getStart(),
+      exportedName,
+      factory: true,
+    }
+
+    logger.debug(
+      `• Found permission factory with services: ${services.services.join(', ')}`
+    )
+    return
+  }
+
+  // Handle addPermission('tag', [permission1, permission2])
+  // Supports two patterns:
+  // 1. export const x = () => addPermission('tag', [...])  (factory - tree-shakeable)
+  // 2. export const x = addPermission('tag', [...])  (direct - no tree-shaking)
+  if (expression.text === 'addPermission') {
+    const tagArg = args[0]
+    const permissionsArrayArg = args[1]
+
+    if (!tagArg || !permissionsArrayArg) return
+
+    // Extract tag name
+    let tag: string | undefined
+    if (ts.isStringLiteral(tagArg)) {
+      tag = tagArg.text
+    }
+
+    if (!tag) {
+      logger.warn(`• addPermission call without valid tag string`)
+      return
+    }
+
+    // Check if permissions is a literal array or object
+    if (
+      !ts.isArrayLiteralExpression(permissionsArrayArg) &&
+      !ts.isObjectLiteralExpression(permissionsArrayArg)
+    ) {
+      logger.error(
+        `• addPermission('${tag}', ...) must have a literal array or object as second argument`
+      )
+      return
+    }
+
+    // Extract permission pikkuFuncNames from array
+    const permissionNames = extractPermissionPikkuNames(
+      permissionsArrayArg,
+      checker,
+      state.rootDir
+    )
+
+    if (permissionNames.length === 0) {
+      logger.warn(`• addPermission('${tag}', ...) has empty permissions array`)
+      return
+    }
+
+    // Collect services from all permissions in the group
+    const allServices = new Set<string>()
+    for (const permissionName of permissionNames) {
+      const permissionMeta = state.permissions.meta[permissionName]
+      if (permissionMeta && permissionMeta.services) {
+        for (const service of permissionMeta.services.services) {
+          allServices.add(service)
+        }
+      }
+    }
+
+    // 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
+            }
+          }
+        }
+      }
+    }
+
+    // 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. ` +
+          `For tree-shaking, use: export const ${exportedName} = () => addPermission('${tag}', [...])`
+      )
+    }
+
+    // Store group metadata
+    state.permissions.tagPermissions.set(tag, {
+      exportName: exportedName,
+      sourceFile: node.getSourceFile().fileName,
+      position: node.getStart(),
+      services: {
+        optimized: false,
+        services: Array.from(allServices),
+      },
+      permissionCount: permissionNames.length,
+      isFactory,
+    })
+
+    logger.debug(
+      `• Found tag permission group: ${tag} -> [${permissionNames.join(', ')}] (${isFactory ? 'factory' : 'direct'})`
+    )
+    return
+  }
+
+  // Handle addHTTPPermission(pattern, [permission1, permission2])
+  // Supports two patterns:
+  // 1. export const x = () => addHTTPPermission('*', [...])  (factory - tree-shakeable)
+  // 2. export const x = addHTTPPermission('*', [...])  (direct - no tree-shaking)
+  if (expression.text === 'addHTTPPermission') {
+    const patternArg = args[0]
+    const permissionsArrayArg = args[1]
+
+    if (!patternArg || !permissionsArrayArg) return
+
+    // Extract route pattern
+    let pattern: string | undefined
+    if (ts.isStringLiteral(patternArg)) {
+      pattern = patternArg.text
+    }
+
+    if (!pattern) {
+      logger.warn(`• addHTTPPermission call without valid pattern string`)
+      return
+    }
+
+    // Check if permissions is a literal array or object
+    if (
+      !ts.isArrayLiteralExpression(permissionsArrayArg) &&
+      !ts.isObjectLiteralExpression(permissionsArrayArg)
+    ) {
+      logger.error(
+        `• addHTTPPermission('${pattern}', ...) must have a literal array or object as second argument`
+      )
+      return
+    }
+
+    // Extract permission pikkuFuncNames from array
+    const permissionNames = extractPermissionPikkuNames(
+      permissionsArrayArg,
+      checker,
+      state.rootDir
+    )
+
+    if (permissionNames.length === 0) {
+      logger.warn(
+        `• addHTTPPermission('${pattern}', ...) has empty permissions array`
+      )
+      return
+    }
+
+    // Collect services from all permissions in the group
+    const allServices = new Set<string>()
+    for (const permissionName of permissionNames) {
+      const permissionMeta = state.permissions.meta[permissionName]
+      if (permissionMeta && permissionMeta.services) {
+        for (const service of permissionMeta.services.services) {
+          allServices.add(service)
+        }
+      }
+    }
+
+    // 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
+            }
+          }
+        }
+      }
+    }
+
+    // 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. ` +
+          `For tree-shaking, use: export const ${exportedName} = () => addHTTPPermission('${pattern}', [...])`
+      )
+    }
+
+    // Store group metadata
+    state.http.routePermissions.set(pattern, {
+      exportName: exportedName,
+      sourceFile: node.getSourceFile().fileName,
+      position: node.getStart(),
+      services: {
+        optimized: false,
+        services: Array.from(allServices),
+      },
+      permissionCount: permissionNames.length,
+      isFactory,
+    })
+
+    logger.debug(
+      `• Found HTTP route permission group: ${pattern} -> [${permissionNames.join(', ')}] (${isFactory ? 'factory' : 'direct'})`
+    )
+    return
+  }
+}

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

@@ -0,0 +1,92 @@
+import * as ts from 'typescript'
+import {
+  getPropertyValue,
+  getPropertyTags,
+} from '../utils/get-property-value.js'
+import { PikkuDocs } from '@pikku/core'
+import { AddWiring } from '../types.js'
+import { extractFunctionName } 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'
+import { ErrorCode } from '../error-codes.js'
+
+export const addQueueWorker: AddWiring = (
+  logger,
+  node,
+  checker,
+  state,
+  options
+) => {
+  if (!ts.isCallExpression(node)) {
+    return
+  }
+
+  const args = node.arguments
+  const firstArg = args[0]
+  const expression = node.expression
+
+  // Check if the call is to addQueueWorker
+  if (!ts.isIdentifier(expression) || expression.text !== 'wireQueueWorker') {
+    return
+  }
+
+  if (!firstArg) {
+    return
+  }
+
+  if (ts.isObjectLiteralExpression(firstArg)) {
+    const obj = firstArg
+
+    const queueName = getPropertyValue(obj, 'queueName') as string | null
+    const docs = (getPropertyValue(obj, 'docs') as PikkuDocs) || undefined
+    const tags = getPropertyTags(obj, 'Queue worker', queueName, logger)
+
+    // --- find the referenced function ---
+    const funcInitializer = getPropertyAssignmentInitializer(
+      obj,
+      'func',
+      true,
+      checker
+    )
+    if (!funcInitializer) {
+      logger.critical(
+        ErrorCode.MISSING_FUNC,
+        `No valid 'func' property for queue processor '${queueName}'.`
+      )
+      return
+    }
+
+    const pikkuFuncName = extractFunctionName(
+      funcInitializer,
+      checker,
+      state.rootDir
+    ).pikkuFuncName
+
+    if (!queueName) {
+      logger.critical(
+        ErrorCode.MISSING_QUEUE_NAME,
+        `No 'queueName' provided for queue processor function '${pikkuFuncName}'.`
+      )
+      return
+    }
+
+    // --- resolve middleware ---
+    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.queueWorkers.files.add(node.getSourceFile().fileName)
+    state.queueWorkers.meta[queueName] = {
+      pikkuFuncName,
+      queueName,
+      docs,
+      tags,
+      middleware,
+    }
+  }
+}

package/src/{add-rpc-invocations.ts → add/add-rpc-invocations.ts}

@@ -1,5 +1,5 @@
 import * as ts from 'typescript'
-import { InspectorState, InspectorLogger } from './types.js'
+import { InspectorState, InspectorLogger } from '../types.js'
 
 /**
  * Scan for rpc.invoke() calls to track which functions are actually being invoked

package/src/{add-schedule.ts → add/add-schedule.ts}

@@ -1,19 +1,22 @@
 import * as ts from 'typescript'
-import { getPropertyValue } from './get-property-value.js'
-import { PikkuDocs, PikkuWiringTypes } from '@pikku/core'
-import { InspectorFilters, InspectorState, InspectorLogger } from './types.js'
 import {
-  extractFunctionName,
-  getPropertyAssignmentInitializer,
-  matchesFilters,
-} from './utils.js'
+  getPropertyValue,
+  getPropertyTags,
+} from '../utils/get-property-value.js'
+import { PikkuDocs } from '@pikku/core'
+import { AddWiring } from '../types.js'
+import { extractFunctionName } 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'
 
-export const addSchedule = (
-  node: ts.Node,
-  checker: ts.TypeChecker,
-  state: InspectorState,
-  filters: InspectorFilters,
-  logger: InspectorLogger
+import { ErrorCode } from '../error-codes.js'
+export const addSchedule: AddWiring = (
+  logger,
+  node,
+  checker,
+  state,
+  options
 ) => {
   if (!ts.isCallExpression(node)) {
     return
@@ -38,7 +41,7 @@ export const addSchedule = (
     const nameValue = getPropertyValue(obj, 'name') as string | null
     const scheduleValue = getPropertyValue(obj, 'schedule') as string | null
     const docs = (getPropertyValue(obj, 'docs') as PikkuDocs) || undefined
-    const tags = (getPropertyValue(obj, 'tags') as string[]) || undefined
+    const tags = getPropertyTags(obj, 'Scheduler', nameValue, logger)
 
     const funcInitializer = getPropertyAssignmentInitializer(
       obj,
@@ -47,33 +50,31 @@ export const addSchedule = (
       checker
     )
     if (!funcInitializer) {
-      console.error(
-        `• No valid 'func' property for scheduled task '${nameValue}'.`
+      logger.critical(
+        ErrorCode.MISSING_FUNC,
+        `No valid 'func' property for scheduled task '${nameValue}'.`
       )
       return
     }
 
     const pikkuFuncName = extractFunctionName(
       funcInitializer,
-      checker
+      checker,
+      state.rootDir
     ).pikkuFuncName
 
     if (!nameValue || !scheduleValue) {
       return
     }
 
-    const filePath = node.getSourceFile().fileName
+    // --- resolve middleware ---
+    const middleware = resolveMiddleware(state, obj, tags, checker)
 
-    if (
-      !matchesFilters(
-        filters,
-        { tags },
-        { type: PikkuWiringTypes.scheduler, name: nameValue, filePath },
-        logger
-      )
-    ) {
-      return
-    }
+    // --- track used functions/middleware for service aggregation ---
+    state.serviceAggregation.usedFunctions.add(pikkuFuncName)
+    extractWireNames(middleware).forEach((name) =>
+      state.serviceAggregation.usedMiddleware.add(name)
+    )
 
     state.scheduledTasks.files.add(node.getSourceFile().fileName)
     state.scheduledTasks.meta[nameValue] = {
@@ -82,6 +83,7 @@ export const addSchedule = (
       schedule: scheduleValue,
       docs,
       tags,
+      middleware,
     }
   }
 }

package/src/error-codes.ts

@@ -0,0 +1,43 @@
+/**
+ * Error code system for Pikku CLI and Inspector
+ *
+ * Each error has a unique code and links to documentation at pikku.dev
+ *
+ * Error codes use random 3-digit numbers to avoid implying a sequential order.
+ * Each code links to detailed documentation and troubleshooting steps.
+ */
+
+export enum ErrorCode {
+  // Validation errors
+  MISSING_NAME = 'PKU111',
+  MISSING_DESCRIPTION = 'PKU123',
+  MISSING_URI = 'PKU220',
+  MISSING_FUNC = 'PKU236',
+  INVALID_TAGS_TYPE = 'PKU247',
+  INVALID_HANDLER = 'PKU300',
+  MISSING_TITLE = 'PKU370',
+  MISSING_QUEUE_NAME = 'PKU384',
+  MISSING_CHANNEL_NAME = 'PKU400',
+  CLI_CLIENTSIDE_RENDERER_HAS_SERVICES = 'PKU672',
+
+  // Configuration errors
+  CONFIG_TYPE_NOT_FOUND = 'PKU426',
+  CONFIG_TYPE_UNDEFINED = 'PKU427',
+  SCHEMA_NO_ROOT = 'PKU431',
+  SCHEMA_GENERATION_ERROR = 'PKU456',
+  SCHEMA_LOAD_ERROR = 'PKU488',
+
+  // Function errors
+  FUNCTION_METADATA_NOT_FOUND = 'PKU559',
+  HANDLER_NOT_RESOLVED = 'PKU568',
+
+  // Middleware/Permission errors
+  MIDDLEWARE_HANDLER_INVALID = 'PKU685',
+  MIDDLEWARE_TAG_INVALID = 'PKU715',
+  MIDDLEWARE_EMPTY_ARRAY = 'PKU736',
+  MIDDLEWARE_PATTERN_INVALID = 'PKU787',
+  PERMISSION_HANDLER_INVALID = 'PKU835',
+  PERMISSION_TAG_INVALID = 'PKU836',
+  PERMISSION_EMPTY_ARRAY = 'PKU937',
+  PERMISSION_PATTERN_INVALID = 'PKU975',
+}

package/src/index.ts

@@ -1,4 +1,16 @@
 export { inspect } from './inspector.js'
+export { getFilesAndMethods } from './utils/get-files-and-methods.js'
 export type { TypesMap } from './types-map.js'
 export type * from './types.js'
 export type { InspectorState } from './types.js'
+export type {
+  FilesAndMethods,
+  FilesAndMethodsErrors,
+} from './utils/get-files-and-methods.js'
+export { ErrorCode } from './error-codes.js'
+export {
+  serializeInspectorState,
+  deserializeInspectorState,
+} from './utils/serialize-inspector-state.js'
+export type { SerializableInspectorState } from './utils/serialize-inspector-state.js'
+export { filterInspectorState } from './utils/filter-inspector-state.js'