@pikku/inspector 0.9.6-next.0 → 0.10.0

package/src/inspector.ts

@@ -3,6 +3,8 @@ import { visitSetup, visitRoutes } from './visit.js'
 import { TypesMap } from './types-map.js'
 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,
@@ -16,13 +18,18 @@ 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(),
@@ -45,6 +52,7 @@ export const inspect = (
       },
       files: new Set(),
       routeMiddleware: new Map(),
+      routePermissions: new Map(),
     },
     channels: {
       files: new Set(),
@@ -72,7 +80,10 @@ export const inspect = (
       files: new Set(),
     },
     cli: {
-      meta: {},
+      meta: {
+        programs: {},
+        renderers: {},
+      },
       files: new Set(),
     },
     middleware: {
@@ -81,6 +92,13 @@ export const inspect = (
     },
     permissions: {
       meta: {},
+      tagPermissions: new Map(),
+    },
+    serviceAggregation: {
+      requiredServices: new Set(),
+      usedFunctions: new Set(),
+      usedMiddleware: new Set(),
+      usedPermissions: new Set(),
     },
   }
 
@@ -103,5 +121,8 @@ export const inspect = (
   state.filesAndMethods = result
   state.filesAndMethodsErrors = errors
 
+  // Post-processing: Aggregate required services from wired functions/middleware/permissions
+  aggregateRequiredServices(state)
+
   return state
 }

package/src/types.ts

@@ -3,10 +3,11 @@ 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 { CLIMeta } 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,
@@ -31,6 +32,15 @@ export interface MiddlewareGroupMeta {
   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
@@ -39,6 +49,10 @@ export interface InspectorHTTPState {
   // 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 {
@@ -62,6 +76,8 @@ export interface InspectorMiddlewareState {
       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
@@ -70,6 +86,7 @@ export interface InspectorMiddlewareState {
 }
 
 export interface InspectorPermissionState {
+  // Individual permission function metadata
   meta: Record<
     string,
     {
@@ -77,14 +94,23 @@ 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<{
@@ -94,7 +120,6 @@ export type InspectorOptions = Partial<{
     singletonServicesFactoryType: string
     sessionServicesFactoryType: string
   }>
-  filters: InspectorFilters
 }>
 
 export interface InspectorLogger {
@@ -102,6 +127,8 @@ export interface InspectorLogger {
   error: (message: string) => void
   warn: (message: string) => void
   debug: (message: string) => void
+  critical: (code: ErrorCode, message: string) => void
+  hasCriticalErrors: () => boolean
 }
 
 export type AddWiring = (
@@ -157,12 +184,14 @@ export interface InspectorFilesAndMethods {
 }
 
 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>
@@ -197,4 +226,10 @@ export interface InspectorState {
   }
   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,
+    }
+  }
+}

package/src/utils/extract-function-name.ts

@@ -1,4 +1,5 @@
 import * as ts from 'typescript'
+import { toRelativePath } from './find-root-dir.js'
 
 export type ExtractedFunctionName = {
   pikkuFuncName: string
@@ -16,7 +17,8 @@ export type ExtractedFunctionName = {
  */
 export function makeDeterministicAnonName(
   start: ts.Node,
-  checker: ts.TypeChecker
+  checker: ts.TypeChecker,
+  rootDir: string
 ): string {
   let node: ts.Node = start
   let target: ts.Node = start
@@ -45,7 +47,8 @@ export function makeDeterministicAnonName(
           target = decl.initializer
           // Return early - we found the function directly
           const sf = target.getSourceFile()
-          const file = sf.fileName.replace(/[^A-Za-z0-9_]/g, '_')
+          const relativePath = toRelativePath(sf.fileName, rootDir)
+          const file = relativePath.replace(/[^A-Za-z0-9_]/g, '_')
           const { line, character } = ts.getLineAndCharacterOfPosition(
             sf,
             target.getStart()
@@ -91,7 +94,8 @@ export function makeDeterministicAnonName(
             target = decl.initializer
             // Return early - we found the function directly
             const sf = target.getSourceFile()
-            const file = sf.fileName.replace(/[^A-Za-z0-9_]/g, '_')
+            const relativePath = toRelativePath(sf.fileName, rootDir)
+            const file = relativePath.replace(/[^A-Za-z0-9_]/g, '_')
             const { line, character } = ts.getLineAndCharacterOfPosition(
               sf,
               target.getStart()
@@ -103,7 +107,8 @@ export function makeDeterministicAnonName(
           target = decl
           // Return early
           const sf = target.getSourceFile()
-          const file = sf.fileName.replace(/[^A-Za-z0-9_]/g, '_')
+          const relativePath = toRelativePath(sf.fileName, rootDir)
+          const file = relativePath.replace(/[^A-Za-z0-9_]/g, '_')
           const { line, character } = ts.getLineAndCharacterOfPosition(
             sf,
             target.getStart()
@@ -238,7 +243,8 @@ export function makeDeterministicAnonName(
   }
 
   const sf = target.getSourceFile()
-  const file = sf.fileName.replace(/[^A-Za-z0-9_]/g, '_')
+  const relativePath = toRelativePath(sf.fileName, rootDir)
+  const file = relativePath.replace(/[^A-Za-z0-9_]/g, '_')
   const { line, character } = ts.getLineAndCharacterOfPosition(
     sf,
     target.getStart()
@@ -255,7 +261,8 @@ export function makeDeterministicAnonName(
  */
 export function extractFunctionName(
   callExpr: ts.Node,
-  checker: ts.TypeChecker
+  checker: ts.TypeChecker,
+  rootDir: string
 ): ExtractedFunctionName {
   const parent: any = callExpr.parent
 
@@ -304,7 +311,8 @@ export function extractFunctionName(
               // Use the function directly for position calculation
               result.pikkuFuncName = makeDeterministicAnonName(
                 firstArg,
-                checker
+                checker,
+                rootDir
               )
 
               // Continue with name extraction
@@ -678,7 +686,11 @@ export function extractFunctionName(
   // Generate the deterministic function name based on the original call expression
   // (the config), not the resolved inner function. This ensures the metadata key
   // matches what will be looked up at runtime when referencing the config object.
-  result.pikkuFuncName = makeDeterministicAnonName(originalCallExpr, checker)
+  result.pikkuFuncName = makeDeterministicAnonName(
+    originalCallExpr,
+    checker,
+    rootDir
+  )
 
   // Continue with regular name extraction for remaining cases
   // 1) const foo = pikkuFunc(...)