@pikku/inspector 0.11.1 → 0.12.0

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

@@ -5,20 +5,110 @@ import {
 } from '../utils/get-property-value.js'
 import { pathToRegexp } from 'path-to-regexp'
 import { HTTPMethod } from '@pikku/core/http'
-import { extractFunctionName } from '../utils/extract-function-name.js'
-import { getPropertyAssignmentInitializer } from '../utils/type-utils.js'
-import { AddWiring } from '../types.js'
+import {
+  extractFunctionName,
+  makeContextBasedId,
+} from '../utils/extract-function-name.js'
+import {
+  getPropertyAssignmentInitializer,
+  extractTypeKeys,
+} from '../utils/type-utils.js'
+import { AddWiring, InspectorState } from '../types.js'
 import { resolveHTTPMiddlewareFromObject } from '../utils/middleware.js'
 import { resolveHTTPPermissionsFromObject } from '../utils/permissions.js'
 import { extractWireNames } from '../utils/post-process.js'
 import { ensureFunctionMetadata } from '../utils/ensure-function-metadata.js'
 import { ErrorCode } from '../error-codes.js'
+import { detectSchemaVendorOrError } from '../utils/detect-schema-vendor.js'
+
+import type { InspectorLogger } from '../types.js'
+
+/**
+ * Parameters for registering an HTTP route
+ */
+export interface RegisterHTTPRouteParams {
+  obj: ts.ObjectLiteralExpression
+  state: InspectorState
+  checker: ts.TypeChecker
+  logger: InspectorLogger
+  sourceFile: ts.SourceFile
+  basePath?: string
+  inheritedTags?: string[]
+}
+
+/**
+ * Extract header schema reference from headers property
+ */
+const extractHeadersSchema = (
+  obj: ts.ObjectLiteralExpression,
+  routeName: string,
+  method: string,
+  state: InspectorState,
+  checker: ts.TypeChecker,
+  logger: InspectorLogger
+): string | undefined => {
+  const headersNode = getPropertyAssignmentInitializer(
+    obj,
+    'headers',
+    true,
+    checker
+  )
+  if (!headersNode || !ts.isIdentifier(headersNode)) return undefined
+
+  // Resolve the schema reference
+  const symbol = checker.getSymbolAtLocation(headersNode)
+  if (!symbol) return undefined
+
+  const decl = symbol.valueDeclaration || symbol.declarations?.[0]
+  if (!decl) return undefined
+
+  let sourceFile: string
+  if (ts.isImportSpecifier(decl)) {
+    const aliasedSymbol = checker.getAliasedSymbol(symbol)
+    if (aliasedSymbol) {
+      const aliasedDecl =
+        aliasedSymbol.valueDeclaration || aliasedSymbol.declarations?.[0]
+      if (aliasedDecl) {
+        sourceFile = aliasedDecl.getSourceFile().fileName
+      } else {
+        return undefined
+      }
+    } else {
+      return undefined
+    }
+  } else {
+    sourceFile = decl.getSourceFile().fileName
+  }
+
+  const vendor = detectSchemaVendorOrError(
+    headersNode,
+    checker,
+    logger,
+    `Route '${routeName}' header`,
+    sourceFile
+  )
+  if (!vendor) return undefined
+
+  // Create a sanitized schema name from route and method to avoid collisions
+  const sanitizedRoute = routeName
+    .replace(/[^a-zA-Z0-9]/g, '_')
+    .replace(/^_+|_+$/g, '')
+  const schemaName = `${method.toUpperCase()}_${sanitizedRoute}_Headers`
+
+  state.schemaLookup.set(schemaName, {
+    variableName: headersNode.text,
+    sourceFile,
+    vendor,
+  })
+
+  return schemaName
+}
 
 /**
  * Populate metaInputTypes for a given route based on method, input type,
- * query and params. Returns undefined (we only mutate metaTypes).
+ * query and params.
  */
-export const getInputTypes = (
+const computeInputTypes = (
   metaTypes: Map<
     string,
     { query?: string[]; params?: string[]; body?: string[] }
@@ -27,7 +117,7 @@ export const getInputTypes = (
   inputType: string | null,
   queryValues: string[],
   paramsValues: string[]
-): undefined => {
+): void => {
   if (!inputType) return
   metaTypes.set(inputType, {
     query: queryValues,
@@ -36,49 +126,60 @@ export const getInputTypes = (
       ? [...new Set([...queryValues, ...paramsValues])]
       : [],
   })
-  return
 }
 
 /**
- * Simplified wireHTTP: re-uses function metadata from state.functions.meta
- * instead of re-inferring types here.
+ * Shared function to register an HTTP route in the inspector state.
+ * Used by both wireHTTP and wireHTTPRoutes.
  */
-export const addHTTPRoute: AddWiring = (
-  logger,
-  node,
-  checker,
+export function registerHTTPRoute({
+  obj,
   state,
-  options
-) => {
-  // only look at calls
-  if (!ts.isCallExpression(node)) return
+  checker,
+  logger,
+  sourceFile,
+  basePath = '',
+  inheritedTags = [],
+}: RegisterHTTPRouteParams): void {
+  // Extract route path
+  const routePath = getPropertyValue(obj, 'route') as string | null
+  if (!routePath) return
 
-  const { expression, arguments: args } = node
-  if (!ts.isIdentifier(expression) || expression.text !== 'wireHTTP') return
+  const method = (
+    (getPropertyValue(obj, 'method') as string) || 'get'
+  ).toLowerCase()
+  const fullRoute = basePath + routePath
 
-  // must pass an object literal
-  const firstArg = args[0]
-  if (!firstArg || !ts.isObjectLiteralExpression(firstArg)) return
-  const obj = firstArg
+  // Extract params from route path
+  let params: string[] = []
+  try {
+    const keys = pathToRegexp(fullRoute).keys
+    params = keys.filter((k) => k.type === 'param').map((k) => k.name)
+  } catch (e) {
+    logger.error(
+      `Failed to parse route '${fullRoute}': ${e instanceof Error ? e.message : e}`
+    )
+    return
+  }
 
-  // --- extract HTTP metadata ---
-  const route = getPropertyValue(obj, 'route') as string | null
-  if (!route) return
+  // Get common metadata
+  const {
+    disabled,
+    title,
+    tags: routeTags,
+    summary,
+    description,
+    errors,
+  } = getCommonWireMetaData(obj, 'HTTP route', fullRoute, logger)
 
-  const keys = pathToRegexp(route).keys
-  const params = keys.filter((k) => k.type === 'param').map((k) => k.name)
+  if (disabled) return
+
+  // Merge inherited tags with route tags
+  const tags = [...inheritedTags, ...(routeTags || [])]
 
-  const method =
-    (getPropertyValue(obj, 'method') as string)?.toLowerCase() || 'get'
-  const { tags, summary, description, errors } = getCommonWireMetaData(
-    obj,
-    'HTTP route',
-    route,
-    logger
-  )
   const query = (getPropertyValue(obj, 'query') as string[]) || []
 
-  // --- find the referenced function name first for filtering ---
+  // Get function reference
   const funcInitializer = getPropertyAssignmentInitializer(
     obj,
     'func',
@@ -88,21 +189,27 @@ export const addHTTPRoute: AddWiring = (
   if (!funcInitializer) {
     logger.critical(
       ErrorCode.MISSING_FUNC,
-      `No valid 'func' property for route '${route}'.`
+      `No valid 'func' property for route '${fullRoute}'.`
     )
     return
   }
 
-  const funcName = extractFunctionName(
+  const extracted = extractFunctionName(funcInitializer, checker, state.rootDir)
+  let funcName = extracted.pikkuFuncId
+  if (funcName.startsWith('__temp_')) {
+    funcName = makeContextBasedId('http', method, fullRoute)
+  }
+
+  ensureFunctionMetadata(
+    state,
+    funcName,
+    fullRoute,
     funcInitializer,
     checker,
-    state.rootDir
-  ).pikkuFuncName
-
-  // Ensure function metadata exists (creates stub for inline functions)
-  ensureFunctionMetadata(state, funcName, route)
+    extracted.isHelper
+  )
 
-  // lookup existing function metadata
+  // Lookup existing function metadata
   const fnMeta = state.functions.meta[funcName]
   if (!fnMeta) {
     logger.critical(
@@ -113,34 +220,64 @@ export const addHTTPRoute: AddWiring = (
   }
   const input = fnMeta.inputs?.[0] || null
 
-  // --- compute inputTypes (body/query/params) ---
-  const inputTypes = getInputTypes(
-    state.http.metaInputTypes,
-    method,
-    input,
-    query,
-    params
-  )
+  // Validate that route params and query params exist in function input type
+  if (params.length > 0 || query.length > 0) {
+    const inputTypes = state.typesLookup.get(funcName)
+    if (inputTypes && inputTypes.length > 0) {
+      const inputKeys = extractTypeKeys(inputTypes[0])
+
+      // Check path params
+      if (params.length > 0) {
+        const missingParams = params.filter((p) => !inputKeys.includes(p))
+        if (missingParams.length > 0) {
+          logger.critical(
+            ErrorCode.ROUTE_PARAM_MISMATCH,
+            `Route '${fullRoute}' has path parameter(s) [${missingParams.join(', ')}] ` +
+              `not found in function '${funcName}' input type. ` +
+              `Input type has: [${inputKeys.join(', ')}]`
+          )
+          return
+        }
+      }
 
-  // --- resolve middleware ---
+      // Check query params
+      if (query.length > 0) {
+        const missingQuery = query.filter((q) => !inputKeys.includes(q))
+        if (missingQuery.length > 0) {
+          logger.critical(
+            ErrorCode.ROUTE_QUERY_MISMATCH,
+            `Route '${fullRoute}' has query parameter(s) [${missingQuery.join(', ')}] ` +
+              `not found in function '${funcName}' input type. ` +
+              `Input type has: [${inputKeys.join(', ')}]`
+          )
+          return
+        }
+      }
+    }
+  }
+
+  // Compute inputTypes (body/query/params)
+  computeInputTypes(state.http.metaInputTypes, method, input, query, params)
+
+  // Resolve middleware
   const middleware = resolveHTTPMiddlewareFromObject(
     state,
-    route,
+    fullRoute,
     obj,
     tags,
     checker
   )
 
-  // --- resolve permissions ---
+  // Resolve permissions
   const permissions = resolveHTTPPermissionsFromObject(
     state,
-    route,
+    fullRoute,
     obj,
     tags,
     checker
   )
 
-  // --- track used functions/middleware/permissions for service aggregation ---
+  // Track used functions/middleware/permissions for service aggregation
   state.serviceAggregation.usedFunctions.add(funcName)
   extractWireNames(middleware).forEach((name) =>
     state.serviceAggregation.usedMiddleware.add(name)
@@ -149,20 +286,64 @@ export const addHTTPRoute: AddWiring = (
     state.serviceAggregation.usedPermissions.add(name)
   )
 
-  // --- record route ---
-  state.http.files.add(node.getSourceFile().fileName)
-  state.http.meta[method][route] = {
-    pikkuFuncName: funcName,
-    route,
+  // Check for SSE
+  const sse = getPropertyValue(obj, 'sse') === true
+
+  // Extract header schema
+  const headersSchemaName = extractHeadersSchema(
+    obj,
+    fullRoute,
+    method,
+    state,
+    checker,
+    logger
+  )
+
+  // Record route
+  state.http.files.add(sourceFile.fileName)
+  state.http.meta[method][fullRoute] = {
+    pikkuFuncId: funcName,
+    route: fullRoute,
     method: method as HTTPMethod,
     params: params.length > 0 ? params : undefined,
     query: query.length > 0 ? query : undefined,
-    inputTypes,
+    inputTypes: undefined,
+    title,
     summary,
     description,
     errors,
-    tags,
+    tags: tags.length > 0 ? tags : undefined,
     middleware,
     permissions,
+    sse: sse ? true : undefined,
+    headersSchemaName,
+    groupBasePath: basePath || undefined,
   }
 }
+
+/**
+ * Process wireHTTP calls
+ */
+export const addHTTPRoute: AddWiring = (
+  logger,
+  node,
+  checker,
+  state,
+  _options
+) => {
+  if (!ts.isCallExpression(node)) return
+
+  const { expression, arguments: args } = node
+  if (!ts.isIdentifier(expression) || expression.text !== 'wireHTTP') return
+
+  const firstArg = args[0]
+  if (!firstArg || !ts.isObjectLiteralExpression(firstArg)) return
+
+  registerHTTPRoute({
+    obj: firstArg,
+    state,
+    checker,
+    logger,
+    sourceFile: node.getSourceFile(),
+  })
+}

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

@@ -0,0 +1,228 @@
+import * as ts from 'typescript'
+import { getPropertyValue } from '../utils/get-property-value.js'
+import { AddWiring, InspectorState, InspectorLogger } from '../types.js'
+import { registerHTTPRoute } from './add-http-route.js'
+import { resolveIdentifier } from '../utils/resolve-identifier.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
+) => {
+  if (!ts.isCallExpression(node)) return
+
+  const { expression, arguments: args } = node
+  if (!ts.isIdentifier(expression) || 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,
+    state,
+    checker,
+    logger,
+    node.getSourceFile()
+  )
+}
+
+/**
+ * Get a property assignment from an object literal
+ */
+function getPropertyAssignment(
+  obj: ts.ObjectLiteralExpression,
+  propName: string
+): ts.PropertyAssignment | undefined {
+  for (const prop of obj.properties) {
+    if (
+      ts.isPropertyAssignment(prop) &&
+      ts.isIdentifier(prop.name) &&
+      prop.name.text === propName
+    ) {
+      return prop
+    }
+  }
+  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[]) || []
+  const auth = getPropertyValue(obj, 'auth')
+
+  return {
+    basePath,
+    tags,
+    auth: auth === true ? true : auth === false ? false : undefined,
+  }
+}
+
+/**
+ * Merge two group configs following cascading rules
+ */
+function mergeConfigs(parent: GroupConfig, child: GroupConfig): GroupConfig {
+  return {
+    basePath: parent.basePath + child.basePath,
+    tags: [...parent.tags, ...child.tags],
+    auth: child.auth ?? parent.auth,
+  }
+}
+
+/**
+ * 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
+  let hasRoute = false
+
+  for (const prop of obj.properties) {
+    if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+      if (prop.name.text === 'method') hasMethod = true
+      if (prop.name.text === 'func') hasFunc = true
+      if (prop.name.text === 'route') hasRoute = true
+    }
+  }
+
+  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
+  let hasFunc = false
+
+  for (const prop of obj.properties) {
+    if (ts.isPropertyAssignment(prop) && ts.isIdentifier(prop.name)) {
+      if (prop.name.text === 'routes') hasRoutes = true
+      if (prop.name.text === 'method') hasMethod = true
+      if (prop.name.text === 'func') hasFunc = true
+    }
+  }
+
+  return hasRoutes && !hasMethod && !hasFunc
+}
+
+/**
+ * Recursively process routes - handles nested maps, contracts, and identifiers
+ */
+function processRoutes(
+  node: ts.Node,
+  parentConfig: GroupConfig,
+  state: InspectorState,
+  checker: ts.TypeChecker,
+  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)) {
+        processRoute(element, parentConfig, state, checker, logger, sourceFile)
+      }
+    }
+    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)
+      const routesProp = getPropertyAssignment(node, 'routes')
+      if (routesProp) {
+        processRoutes(
+          routesProp.initializer,
+          mergedConfig,
+          state,
+          checker,
+          logger,
+          sourceFile
+        )
+      }
+      return
+    }
+
+    // Otherwise it's a nested map - process each property
+    for (const prop of node.properties) {
+      if (ts.isPropertyAssignment(prop)) {
+        processRoutes(
+          prop.initializer,
+          parentConfig,
+          state,
+          checker,
+          logger,
+          sourceFile
+        )
+      }
+    }
+    return
+  }
+
+  // Handle identifier - resolve to its definition
+  if (ts.isIdentifier(node)) {
+    const resolved = resolveIdentifier(node, checker, ['defineHTTPRoutes'])
+    if (resolved) {
+      processRoutes(resolved, parentConfig, state, checker, logger, sourceFile)
+    }
+  }
+}
+
+/**
+ * Register a single route using the shared registerHTTPRoute function
+ */
+function processRoute(
+  obj: ts.ObjectLiteralExpression,
+  groupConfig: GroupConfig,
+  state: InspectorState,
+  checker: ts.TypeChecker,
+  logger: InspectorLogger,
+  sourceFile: ts.SourceFile
+): void {
+  registerHTTPRoute({
+    obj,
+    state,
+    checker,
+    logger,
+    sourceFile,
+    basePath: groupConfig.basePath,
+    inheritedTags: groupConfig.tags,
+  })
+}