@pikku/inspector 0.9.5 → 0.10.0

package/src/inspector.ts

@@ -1,23 +1,15 @@
 import * as ts from 'typescript'
 import { visitSetup, visitRoutes } from './visit.js'
 import { TypesMap } from './types-map.js'
-import {
-  InspectorState,
-  InspectorHTTPState,
-  InspectorFilters,
-  InspectorLogger,
-} from './types.js'
-
-export const normalizeHTTPTypes = (
-  httpState: InspectorHTTPState
-): InspectorHTTPState => {
-  return httpState
-}
+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'
 
 export const inspect = (
   logger: InspectorLogger,
   routeFiles: string[],
-  filters: InspectorFilters
+  options: InspectorOptions = {}
 ): InspectorState => {
   const program = ts.createProgram(routeFiles, {
     target: ts.ScriptTarget.ESNext,
@@ -26,16 +18,26 @@ export const inspect = (
   const checker = program.getTypeChecker()
   const sourceFiles = program.getSourceFiles()
 
+  // Infer root directory from source files
+  const rootDir = findCommonAncestor(routeFiles)
+
   const state: InspectorState = {
+    rootDir,
     singletonServicesTypeImportMap: new Map(),
     sessionServicesTypeImportMap: new Map(),
     userSessionTypeImportMap: new Map(),
+    configTypeImportMap: new Map(),
     singletonServicesFactories: new Map(),
     sessionServicesFactories: new Map(),
+    sessionServicesMeta: new Map(),
     configFactories: new Map(),
+    filesAndMethods: {},
+    filesAndMethodsErrors: new Map(),
+    typesLookup: new Map(),
     functions: {
       typesMap: new TypesMap(),
       meta: {},
+      files: new Map(),
     },
     http: {
       metaInputTypes: new Map(),
@@ -49,6 +51,8 @@ export const inspect = (
         options: {},
       },
       files: new Set(),
+      routeMiddleware: new Map(),
+      routePermissions: new Map(),
     },
     channels: {
       files: new Set(),
@@ -75,30 +79,50 @@ export const inspect = (
       promptsMeta: {},
       files: new Set(),
     },
+    cli: {
+      meta: {
+        programs: {},
+        renderers: {},
+      },
+      files: new Set(),
+    },
     middleware: {
       meta: {},
+      tagMiddleware: new Map(),
     },
     permissions: {
       meta: {},
+      tagPermissions: new Map(),
+    },
+    serviceAggregation: {
+      requiredServices: new Set(),
+      usedFunctions: new Set(),
+      usedMiddleware: new Set(),
+      usedPermissions: new Set(),
     },
   }
 
   // First sweep: add all functions
   for (const sourceFile of sourceFiles) {
     ts.forEachChild(sourceFile, (child) =>
-      visitSetup(checker, child, state, filters, logger)
+      visitSetup(logger, checker, child, state, options)
     )
   }
 
   // Second sweep: add all transports
   for (const sourceFile of sourceFiles) {
     ts.forEachChild(sourceFile, (child) =>
-      visitRoutes(checker, child, state, filters, logger)
+      visitRoutes(logger, checker, child, state, options)
     )
   }
 
-  // Normalise the typesMap
-  state.http = normalizeHTTPTypes(state.http)
+  // Populate filesAndMethods
+  const { result, errors } = getFilesAndMethods(state, options.types)
+  state.filesAndMethods = result
+  state.filesAndMethodsErrors = errors
+
+  // Post-processing: Aggregate required services from wired functions/middleware/permissions
+  aggregateRequiredServices(state)
 
   return state
 }

package/src/types.ts

@@ -1,10 +1,13 @@
+import * as ts from 'typescript'
 import { ChannelsMeta } from '@pikku/core/channel'
 import { HTTPWiringsMeta } from '@pikku/core/http'
 import { ScheduledTasksMeta } from '@pikku/core/scheduler'
 import { queueWorkersMeta } from '@pikku/core/queue'
-import { MCPResourceMeta, MCPToolMeta, MCPPromptMeta } from '@pikku/core'
+import { MCPResourceMeta, MCPToolMeta, MCPPromptMeta } from '@pikku/core/mcp'
+import { CLIMeta } from '@pikku/core/cli'
 import { TypesMap } from './types-map.js'
 import { FunctionsMeta, FunctionServicesMeta } from '@pikku/core'
+import { ErrorCode } from './error-codes.js'
 
 export type PathToNameAndType = Map<
   string,
@@ -20,15 +23,42 @@ export type MetaInputTypes = Map<
   }
 >
 
+export interface MiddlewareGroupMeta {
+  exportName: string | null // null if not exported
+  sourceFile: string
+  position: number
+  services: FunctionServicesMeta
+  middlewareCount: number
+  isFactory: boolean // true if wrapped in () => add...()
+}
+
+export interface PermissionGroupMeta {
+  exportName: string | null // null if not exported
+  sourceFile: string
+  position: number
+  services: FunctionServicesMeta
+  permissionCount: number
+  isFactory: boolean // true if wrapped in () => add...()
+}
+
 export interface InspectorHTTPState {
   metaInputTypes: MetaInputTypes
   meta: HTTPWiringsMeta
   files: Set<string>
+  // HTTP middleware calls tracking - route pattern -> group metadata
+  // Pattern '*' matches all routes (from addHTTPMiddleware('*', [...]))
+  // Pattern '/api/*' matches specific routes (from addHTTPMiddleware('/api/*', [...]))
+  routeMiddleware: Map<string, MiddlewareGroupMeta>
+  // HTTP permission calls tracking - route pattern -> group metadata
+  // Pattern '*' matches all routes (from addHTTPPermission('*', [...]))
+  // Pattern '/api/*' matches specific routes (from addHTTPPermission('/api/*', [...]))
+  routePermissions: Map<string, PermissionGroupMeta>
 }
 
 export interface InspectorFunctionState {
   typesMap: TypesMap
   meta: FunctionsMeta
+  files: Map<string, { path: string; exportedName: string }>
 }
 
 export interface InspectorChannelState {
@@ -37,6 +67,7 @@ export interface InspectorChannelState {
 }
 
 export interface InspectorMiddlewareState {
+  // Individual middleware function metadata
   meta: Record<
     string,
     {
@@ -44,11 +75,18 @@ export interface InspectorMiddlewareState {
       sourceFile: string
       position: number
       exportedName: string | null
+      factory?: boolean // true if wrapped with pikkuMiddlewareFactory
+      name?: string // optional name from pikkuMiddleware({ name: '...' })
+      description?: string // optional description from pikkuMiddleware({ description: '...' })
     }
   >
+  // Tag-based middleware calls tracking - tag -> group metadata
+  // e.g., export const adminMiddleware = () => addMiddleware('admin', [...])
+  tagMiddleware: Map<string, MiddlewareGroupMeta>
 }
 
 export interface InspectorPermissionState {
+  // Individual permission function metadata
   meta: Record<
     string,
     {
@@ -56,29 +94,108 @@ export interface InspectorPermissionState {
       sourceFile: string
       position: number
       exportedName: string | null
+      factory?: boolean // true if wrapped with pikkuPermissionFactory
+      name?: string // optional name from pikkuPermission({ name: '...' })
+      description?: string // optional description from pikkuPermission({ description: '...' })
     }
   >
+  // Tag-based permission calls tracking - tag -> group metadata
+  // e.g., export const adminPermissions = () => addPermission('admin', [...])
+  tagPermissions: Map<string, PermissionGroupMeta>
 }
 
 export type InspectorFilters = {
+  names?: string[] // Wildcard support: "email-*" matches "email-worker", "email-sender"
   tags?: string[]
   types?: string[]
   directories?: string[]
+  httpRoutes?: string[] // HTTP route patterns: "/api/*", "/webhooks/*"
+  httpMethods?: string[] // HTTP methods: "GET", "POST", "DELETE", etc.
 }
 
+export type InspectorOptions = Partial<{
+  types: Partial<{
+    configFileType: string
+    userSessionType: string
+    singletonServicesFactoryType: string
+    sessionServicesFactoryType: string
+  }>
+}>
+
 export interface InspectorLogger {
   info: (message: string) => void
   error: (message: string) => void
   warn: (message: string) => void
   debug: (message: string) => void
+  critical: (code: ErrorCode, message: string) => void
+  hasCriticalErrors: () => boolean
+}
+
+export type AddWiring = (
+  logger: InspectorLogger,
+  node: ts.Node,
+  checker: ts.TypeChecker,
+  state: InspectorState,
+  options: InspectorOptions
+) => void
+export interface InspectorFilesAndMethods {
+  userSessionType?: {
+    file: string
+    variable: string
+    type: string
+    typePath: string
+  }
+  sessionServicesType?: {
+    file: string
+    variable: string
+    type: string
+    typePath: string
+  }
+  singletonServicesType?: {
+    file: string
+    variable: string
+    type: string
+    typePath: string
+  }
+  pikkuConfigType?: {
+    file: string
+    variable: string
+    type: string
+    typePath: string
+  }
+  pikkuConfigFactory?: {
+    file: string
+    variable: string
+    type: string
+    typePath: string
+  }
+  singletonServicesFactory?: {
+    file: string
+    variable: string
+    type: string
+    typePath: string
+  }
+  sessionServicesFactory?: {
+    file: string
+    variable: string
+    type: string
+    typePath: string
+  }
 }
+
 export interface InspectorState {
+  rootDir: string // Root directory inferred from source files
   singletonServicesTypeImportMap: PathToNameAndType
   sessionServicesTypeImportMap: PathToNameAndType
   userSessionTypeImportMap: PathToNameAndType
+  configTypeImportMap: PathToNameAndType
   singletonServicesFactories: PathToNameAndType
   sessionServicesFactories: PathToNameAndType
+  sessionServicesMeta: Map<string, string[]> // variable name -> singleton services consumed
   configFactories: PathToNameAndType
+  filesAndMethods: InspectorFilesAndMethods
+  filesAndMethodsErrors: Map<string, PathToNameAndType>
+  typesLookup: Map<string, ts.Type[]> // Lookup for types by name (e.g., function input types, Config type)
   http: InspectorHTTPState
   functions: InspectorFunctionState
   channels: InspectorChannelState
@@ -103,6 +220,16 @@ export interface InspectorState {
     promptsMeta: MCPPromptMeta
     files: Set<string>
   }
+  cli: {
+    meta: CLIMeta
+    files: Set<string>
+  }
   middleware: InspectorMiddlewareState
   permissions: InspectorPermissionState
+  serviceAggregation: {
+    requiredServices: Set<string> // All services needed across the app
+    usedFunctions: Set<string> // Function names actually wired/exposed
+    usedMiddleware: Set<string> // Middleware names used by wired functions
+    usedPermissions: Set<string> // Permission names used by wired functions
+  }
 }

package/src/utils/ensure-function-metadata.ts

@@ -0,0 +1,24 @@
+import { InspectorState } from '../types.js'
+
+/**
+ * Ensures that function metadata exists for a given pikkuFuncName.
+ * Creates stub metadata if it doesn't exist (useful for inline functions).
+ */
+export function ensureFunctionMetadata(
+  state: InspectorState,
+  pikkuFuncName: string,
+  fallbackName?: string
+): void {
+  if (!state.functions.meta[pikkuFuncName]) {
+    state.functions.meta[pikkuFuncName] = {
+      pikkuFuncName,
+      name: fallbackName || pikkuFuncName,
+      services: { optimized: false, services: [] },
+      inputSchemaName: null,
+      outputSchemaName: null,
+      inputs: [],
+      outputs: [],
+      middleware: undefined,
+    }
+  }
+}