@pikku/inspector 0.12.22 → 0.12.23

package/src/add/add-channel.ts

@@ -21,6 +21,8 @@ import { resolveIdentifier } from '../utils/resolve-identifier.js'
 import { resolveFunctionMeta } from '../utils/resolve-function-meta.js'
 import { resolveAddonName } from '../utils/resolve-addon-package.js'
 import { validateAuthSessionless } from '../utils/validate-auth-sessionless.js'
+import { getExportedVariableName } from '../utils/get-exported-variable-name.js'
+import { resolveRefContract } from '../utils/resolve-ref-contract.js'
 
 /**
  * Safely get the "initializer" expression of a property-like AST node:
@@ -40,6 +42,16 @@ function getInitializerOf(
   return undefined
 }
 
+function getObjectPropertyName(
+  name: ts.PropertyName | undefined
+): string | null {
+  if (!name) return null
+  if (ts.isIdentifier(name)) return name.text
+  if (ts.isStringLiteral(name) || ts.isNumericLiteral(name)) return name.text
+  if (ts.isComputedPropertyName(name)) return null
+  return name.getText()
+}
+
 /**
  * Resolve a handler expression (Identifier, CallExpression, or { func })
  * into its underlying function name.
@@ -116,6 +128,27 @@ function getHandlerNameFromExpression(
   return null
 }
 
+function extractExportedChannelRoutes(
+  logger: {
+    error: (msg: string) => void
+    critical: (code: ErrorCode, msg: string) => void
+  },
+  routes: ts.ObjectLiteralExpression,
+  state: InspectorState,
+  checker: ts.TypeChecker
+): Record<string, ChannelMessageMeta> {
+  const wrapper = ts.factory.createObjectLiteralExpression([
+    ts.factory.createPropertyAssignment(
+      'onMessageWiring',
+      ts.factory.createObjectLiteralExpression([
+        ts.factory.createPropertyAssignment('contract', routes),
+      ])
+    ),
+  ])
+
+  return addMessagesRoutes(logger, wrapper, state, checker).contract ?? {}
+}
+
 /**
  * Build out the nested message-routes by looking up each handler
  * in state.functions.meta instead of re-inferring it here.
@@ -155,9 +188,24 @@ export function addMessagesRoutes(
       }
     }
 
+    const refContract = resolveRefContract(
+      chanInit,
+      'refChannel',
+      state.exportedContracts.addonChannel
+    )
+    if (refContract) {
+      const refChannelKey = getObjectPropertyName(chanElem.name)
+      if (!refChannelKey) continue
+      result[refChannelKey] = {
+        ...refContract.contract,
+      }
+      continue
+    }
+
     if (!ts.isObjectLiteralExpression(chanInit)) continue
 
-    const channelKey = chanElem.name!.getText()
+    const channelKey = getObjectPropertyName(chanElem.name)
+    if (!channelKey) continue
     result[channelKey] = {}
 
     for (const routeElem of chanInit.properties) {
@@ -168,11 +216,8 @@ export function addMessagesRoutes(
       const routeName = routeElem.name
       if (!routeName) continue
 
-      let routeKey = routeName.getText()
-      // For string literals like 'greet' or "greet", strip the quotes
-      if (ts.isStringLiteral(routeName)) {
-        routeKey = routeName.text
-      }
+      const routeKey = getObjectPropertyName(routeName)
+      if (!routeKey) continue
 
       // For shorthand properties, we need to resolve the identifier to its declaration
       if (ts.isShorthandPropertyAssignment(routeElem)) {
@@ -529,6 +574,18 @@ export const addChannel: AddWiring = (
   options
 ) => {
   if (!ts.isCallExpression(node)) return
+  if (
+    ts.isIdentifier(node.expression) &&
+    node.expression.text === 'defineChannelRoutes'
+  ) {
+    const exportName = getExportedVariableName(node, options.sourceFile)
+    const [firstArg] = node.arguments
+    if (exportName && firstArg && ts.isObjectLiteralExpression(firstArg)) {
+      state.exportedContracts.channel[exportName] =
+        extractExportedChannelRoutes(logger, firstArg, state, checker)
+    }
+    return
+  }
   const { expression, arguments: args } = node
   if (!ts.isIdentifier(expression) || expression.text !== 'wireChannel') return
   const first = args[0]
@@ -664,7 +721,9 @@ export const addChannel: AddWiring = (
     state.serviceAggregation.usedFunctions.add(message.pikkuFuncId)
   }
 
-  for (const channelHandlers of Object.values(messageWirings)) {
+  for (const channelHandlers of Object.values(
+    messageWirings as Record<string, Record<string, ChannelMessageMeta>>
+  )) {
     for (const handler of Object.values(channelHandlers)) {
       state.serviceAggregation.usedFunctions.add(handler.pikkuFuncId)
     }

package/src/add/add-cli.ts

@@ -19,6 +19,8 @@ import { resolveIdentifier } from '../utils/resolve-identifier.js'
 import { resolveAddonName } from '../utils/resolve-addon-package.js'
 import { validateAuthSessionless } from '../utils/validate-auth-sessionless.js'
 import { extractServicesFromFunction } from '../utils/extract-services.js'
+import { getExportedVariableName } from '../utils/get-exported-variable-name.js'
+import { resolveRefContract } from '../utils/resolve-ref-contract.js'
 
 // Track if we've warned about missing Config type to avoid duplicate warnings
 const configTypeWarningShown = new Set<string>()
@@ -34,6 +36,25 @@ export const addCLI: AddWiring = (
   options
 ) => {
   if (!ts.isCallExpression(node)) return
+  if (
+    ts.isIdentifier(node.expression) &&
+    node.expression.text === 'defineCLICommands'
+  ) {
+    const exportName = getExportedVariableName(node, options.sourceFile)
+    const [firstArg] = node.arguments
+    if (exportName && firstArg && ts.isObjectLiteralExpression(firstArg)) {
+      inspectorState.exportedContracts.cli[exportName] = processCommands(
+        logger,
+        firstArg,
+        node.getSourceFile(),
+        typeChecker,
+        exportName,
+        inspectorState,
+        options
+      )
+    }
+    return
+  }
   // Check if this is a wireCLI call
   if (!node || !node.expression) {
     return
@@ -214,6 +235,15 @@ function processCommands(
           programTags
         )
         Object.assign(commands, spreadCommands)
+      } else {
+        const refCommands = resolveRefContract(
+          prop.expression,
+          'refCLI',
+          inspectorState.exportedContracts.addonCli
+        )
+        if (refCommands) {
+          Object.assign(commands, refCommands.contract)
+        }
       }
       continue
     }

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

@@ -13,7 +13,11 @@ import {
   getPropertyAssignmentInitializer,
   extractTypeKeys,
 } from '../utils/type-utils.js'
-import type { AddWiring, InspectorState } from '../types.js'
+import type {
+  AddWiring,
+  ExportedHTTPRouteConfigMeta,
+  InspectorState,
+} from '../types.js'
 import { resolveHTTPMiddlewareFromObject } from '../utils/middleware.js'
 import { resolveHTTPPermissionsFromObject } from '../utils/permissions.js'
 import { extractWireNames } from '../utils/post-process.js'
@@ -40,6 +44,16 @@ export interface RegisterHTTPRouteParams {
   inheritedAuth?: boolean
 }
 
+export interface RegisterHTTPRouteMetaParams {
+  route: ExportedHTTPRouteConfigMeta
+  state: InspectorState
+  logger: InspectorLogger
+  sourceFile: ts.SourceFile
+  basePath?: string
+  inheritedTags?: string[]
+  inheritedAuth?: boolean
+}
+
 /**
  * Extract header schema reference from headers property
  */
@@ -421,6 +435,66 @@ export function registerHTTPRoute({
   }
 }
 
+export function registerHTTPRouteMeta({
+  route,
+  state,
+  logger,
+  sourceFile,
+  basePath = '',
+  inheritedTags = [],
+  inheritedAuth,
+}: RegisterHTTPRouteMetaParams): void {
+  const method = route.method.toLowerCase()
+  const fullRoute = basePath + route.route
+  const tags = [...inheritedTags, ...(route.tags || [])]
+  const funcName = route.func.pikkuFuncId
+  const fnMeta = resolveFunctionMeta(state, funcName)
+
+  if (!fnMeta) {
+    logger.critical(
+      ErrorCode.FUNCTION_METADATA_NOT_FOUND,
+      `No function metadata found for '${funcName}'.`
+    )
+    return
+  }
+
+  let params: string[] = []
+  try {
+    const keys = pathToRegexp(fullRoute).keys
+    params = keys.filter((k) => k.type === 'param').map((k) => k.name)
+  } catch (error) {
+    logger.error(
+      `Failed to parse route '${fullRoute}': ${error instanceof Error ? error.message : error}`
+    )
+    return
+  }
+
+  if (!route.func.packageName) {
+    computeInputTypes(
+      state.http.metaInputTypes,
+      method,
+      fnMeta.inputs?.[0] || null,
+      [],
+      params
+    )
+  }
+
+  state.serviceAggregation.usedFunctions.add(funcName)
+  state.http.files.add(sourceFile.fileName)
+  state.http.meta[method][fullRoute] = {
+    pikkuFuncId: funcName,
+    ...(route.func.packageName && { packageName: route.func.packageName }),
+    route: fullRoute,
+    sourceFile: sourceFile.fileName,
+    method: method as HTTPMethod,
+    params: params.length > 0 ? params : undefined,
+    inputTypes: undefined,
+    tags: tags.length > 0 ? tags : undefined,
+    sse: route.sse ? true : undefined,
+    groupBasePath: basePath || undefined,
+  }
+}
+
 /**
  * Process wireHTTP calls
  */

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,