@pikku/inspector 0.9.5 → 0.10.0

package/dist/{add-schedule.js → add/add-schedule.js}

@@ -1,8 +1,11 @@
 import * as ts from 'typescript';
-import { getPropertyValue } from './get-property-value.js';
-import { PikkuWiringTypes } from '@pikku/core';
-import { extractFunctionName, getPropertyAssignmentInitializer, matchesFilters, } from './utils.js';
-export const addSchedule = (node, checker, state, filters, logger) => {
+import { getPropertyValue, getPropertyTags, } from '../utils/get-property-value.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 addSchedule = (logger, node, checker, state, options) => {
     if (!ts.isCallExpression(node)) {
         return;
     }
@@ -21,20 +24,21 @@ export const addSchedule = (node, checker, state, filters, logger) => {
         const nameValue = getPropertyValue(obj, 'name');
         const scheduleValue = getPropertyValue(obj, 'schedule');
         const docs = getPropertyValue(obj, 'docs') || undefined;
-        const tags = getPropertyValue(obj, 'tags') || undefined;
+        const tags = getPropertyTags(obj, 'Scheduler', nameValue, logger);
         const funcInitializer = getPropertyAssignmentInitializer(obj, 'func', true, 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).pikkuFuncName;
+        const pikkuFuncName = extractFunctionName(funcInitializer, checker, state.rootDir).pikkuFuncName;
         if (!nameValue || !scheduleValue) {
             return;
         }
-        const filePath = node.getSourceFile().fileName;
-        if (!matchesFilters(filters, { tags }, { type: PikkuWiringTypes.scheduler, name: nameValue, filePath }, logger)) {
-            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.scheduledTasks.files.add(node.getSourceFile().fileName);
         state.scheduledTasks.meta[nameValue] = {
             pikkuFuncName,
@@ -42,6 +46,7 @@ export const addSchedule = (node, checker, state, filters, logger) => {
             schedule: scheduleValue,
             docs,
             tags,
+            middleware,
         };
     }
 };

package/dist/error-codes.d.ts

@@ -0,0 +1,35 @@
+/**
+ * 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 declare enum ErrorCode {
+    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",
+    CONFIG_TYPE_NOT_FOUND = "PKU426",
+    CONFIG_TYPE_UNDEFINED = "PKU427",
+    SCHEMA_NO_ROOT = "PKU431",
+    SCHEMA_GENERATION_ERROR = "PKU456",
+    SCHEMA_LOAD_ERROR = "PKU488",
+    FUNCTION_METADATA_NOT_FOUND = "PKU559",
+    HANDLER_NOT_RESOLVED = "PKU568",
+    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/dist/error-codes.js

@@ -0,0 +1,40 @@
+/**
+ * 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 var ErrorCode;
+(function (ErrorCode) {
+    // Validation errors
+    ErrorCode["MISSING_NAME"] = "PKU111";
+    ErrorCode["MISSING_DESCRIPTION"] = "PKU123";
+    ErrorCode["MISSING_URI"] = "PKU220";
+    ErrorCode["MISSING_FUNC"] = "PKU236";
+    ErrorCode["INVALID_TAGS_TYPE"] = "PKU247";
+    ErrorCode["INVALID_HANDLER"] = "PKU300";
+    ErrorCode["MISSING_TITLE"] = "PKU370";
+    ErrorCode["MISSING_QUEUE_NAME"] = "PKU384";
+    ErrorCode["MISSING_CHANNEL_NAME"] = "PKU400";
+    ErrorCode["CLI_CLIENTSIDE_RENDERER_HAS_SERVICES"] = "PKU672";
+    // Configuration errors
+    ErrorCode["CONFIG_TYPE_NOT_FOUND"] = "PKU426";
+    ErrorCode["CONFIG_TYPE_UNDEFINED"] = "PKU427";
+    ErrorCode["SCHEMA_NO_ROOT"] = "PKU431";
+    ErrorCode["SCHEMA_GENERATION_ERROR"] = "PKU456";
+    ErrorCode["SCHEMA_LOAD_ERROR"] = "PKU488";
+    // Function errors
+    ErrorCode["FUNCTION_METADATA_NOT_FOUND"] = "PKU559";
+    ErrorCode["HANDLER_NOT_RESOLVED"] = "PKU568";
+    // Middleware/Permission errors
+    ErrorCode["MIDDLEWARE_HANDLER_INVALID"] = "PKU685";
+    ErrorCode["MIDDLEWARE_TAG_INVALID"] = "PKU715";
+    ErrorCode["MIDDLEWARE_EMPTY_ARRAY"] = "PKU736";
+    ErrorCode["MIDDLEWARE_PATTERN_INVALID"] = "PKU787";
+    ErrorCode["PERMISSION_HANDLER_INVALID"] = "PKU835";
+    ErrorCode["PERMISSION_TAG_INVALID"] = "PKU836";
+    ErrorCode["PERMISSION_EMPTY_ARRAY"] = "PKU937";
+    ErrorCode["PERMISSION_PATTERN_INVALID"] = "PKU975";
+})(ErrorCode || (ErrorCode = {}));

package/dist/index.d.ts

@@ -1,4 +1,10 @@
 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';

package/dist/index.js

@@ -1 +1,5 @@
 export { inspect } from './inspector.js';
+export { getFilesAndMethods } from './utils/get-files-and-methods.js';
+export { ErrorCode } from './error-codes.js';
+export { serializeInspectorState, deserializeInspectorState, } from './utils/serialize-inspector-state.js';
+export { filterInspectorState } from './utils/filter-inspector-state.js';

package/dist/inspector.d.ts

@@ -1,3 +1,2 @@
-import { InspectorState, InspectorHTTPState, InspectorFilters, InspectorLogger } from './types.js';
-export declare const normalizeHTTPTypes: (httpState: InspectorHTTPState) => InspectorHTTPState;
-export declare const inspect: (logger: InspectorLogger, routeFiles: string[], filters: InspectorFilters) => InspectorState;
+import { InspectorState, InspectorLogger, InspectorOptions } from './types.js';
+export declare const inspect: (logger: InspectorLogger, routeFiles: string[], options?: InspectorOptions) => InspectorState;

package/dist/inspector.js

@@ -1,26 +1,35 @@
 import * as ts from 'typescript';
 import { visitSetup, visitRoutes } from './visit.js';
 import { TypesMap } from './types-map.js';
-export const normalizeHTTPTypes = (httpState) => {
-    return httpState;
-};
-export const inspect = (logger, routeFiles, filters) => {
+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, routeFiles, options = {}) => {
     const program = ts.createProgram(routeFiles, {
         target: ts.ScriptTarget.ESNext,
         module: ts.ModuleKind.CommonJS,
     });
     const checker = program.getTypeChecker();
     const sourceFiles = program.getSourceFiles();
+    // Infer root directory from source files
+    const rootDir = findCommonAncestor(routeFiles);
     const state = {
+        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(),
@@ -34,6 +43,8 @@ export const inspect = (logger, routeFiles, filters) => {
                 options: {},
             },
             files: new Set(),
+            routeMiddleware: new Map(),
+            routePermissions: new Map(),
         },
         channels: {
             files: new Set(),
@@ -60,22 +71,41 @@ export const inspect = (logger, routeFiles, filters) => {
             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));
+        ts.forEachChild(sourceFile, (child) => 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));
+        ts.forEachChild(sourceFile, (child) => 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/dist/types.d.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, {
     variable: string;
     type: string | null;
@@ -15,14 +18,36 @@ export type MetaInputTypes = Map<string, {
     params: string[] | undefined;
     body: string[] | undefined;
 }>;
+export interface MiddlewareGroupMeta {
+    exportName: string | null;
+    sourceFile: string;
+    position: number;
+    services: FunctionServicesMeta;
+    middlewareCount: number;
+    isFactory: boolean;
+}
+export interface PermissionGroupMeta {
+    exportName: string | null;
+    sourceFile: string;
+    position: number;
+    services: FunctionServicesMeta;
+    permissionCount: number;
+    isFactory: boolean;
+}
 export interface InspectorHTTPState {
     metaInputTypes: MetaInputTypes;
     meta: HTTPWiringsMeta;
     files: Set<string>;
+    routeMiddleware: Map<string, MiddlewareGroupMeta>;
+    routePermissions: Map<string, PermissionGroupMeta>;
 }
 export interface InspectorFunctionState {
     typesMap: TypesMap;
     meta: FunctionsMeta;
+    files: Map<string, {
+        path: string;
+        exportedName: string;
+    }>;
 }
 export interface InspectorChannelState {
     meta: ChannelsMeta;
@@ -34,7 +59,11 @@ export interface InspectorMiddlewareState {
         sourceFile: string;
         position: number;
         exportedName: string | null;
+        factory?: boolean;
+        name?: string;
+        description?: string;
     }>;
+    tagMiddleware: Map<string, MiddlewareGroupMeta>;
 }
 export interface InspectorPermissionState {
     meta: Record<string, {
@@ -42,26 +71,94 @@ export interface InspectorPermissionState {
         sourceFile: string;
         position: number;
         exportedName: string | null;
+        factory?: boolean;
+        name?: string;
+        description?: string;
     }>;
+    tagPermissions: Map<string, PermissionGroupMeta>;
 }
 export type InspectorFilters = {
+    names?: string[];
     tags?: string[];
     types?: string[];
     directories?: string[];
+    httpRoutes?: string[];
+    httpMethods?: string[];
 };
+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;
     singletonServicesTypeImportMap: PathToNameAndType;
     sessionServicesTypeImportMap: PathToNameAndType;
     userSessionTypeImportMap: PathToNameAndType;
+    configTypeImportMap: PathToNameAndType;
     singletonServicesFactories: PathToNameAndType;
     sessionServicesFactories: PathToNameAndType;
+    sessionServicesMeta: Map<string, string[]>;
     configFactories: PathToNameAndType;
+    filesAndMethods: InspectorFilesAndMethods;
+    filesAndMethodsErrors: Map<string, PathToNameAndType>;
+    typesLookup: Map<string, ts.Type[]>;
     http: InspectorHTTPState;
     functions: InspectorFunctionState;
     channels: InspectorChannelState;
@@ -92,6 +189,16 @@ export interface InspectorState {
         promptsMeta: MCPPromptMeta;
         files: Set<string>;
     };
+    cli: {
+        meta: CLIMeta;
+        files: Set<string>;
+    };
     middleware: InspectorMiddlewareState;
     permissions: InspectorPermissionState;
+    serviceAggregation: {
+        requiredServices: Set<string>;
+        usedFunctions: Set<string>;
+        usedMiddleware: Set<string>;
+        usedPermissions: Set<string>;
+    };
 }

package/dist/utils/ensure-function-metadata.d.ts

@@ -0,0 +1,6 @@
+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 declare function ensureFunctionMetadata(state: InspectorState, pikkuFuncName: string, fallbackName?: string): void;

package/dist/utils/ensure-function-metadata.js

@@ -0,0 +1,18 @@
+/**
+ * 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, pikkuFuncName, fallbackName) {
+    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/dist/utils/extract-function-name.d.ts

@@ -0,0 +1,31 @@
+import * as ts from 'typescript';
+export type ExtractedFunctionName = {
+    pikkuFuncName: string;
+    name: string;
+    explicitName: string | null;
+    exportedName: string | null;
+    localName: string | null;
+    propertyName: string | null;
+};
+/**
+ * Generate a deterministic "anonymous" name for any expression node,
+ * but if it's an Identifier pointing to a function, resolve it back
+ * to the function's declaration (so you get the true source location).
+ */
+export declare function makeDeterministicAnonName(start: ts.Node, checker: ts.TypeChecker, rootDir: string): string;
+/**
+ * Updated function to extract and prioritize function names correctly
+ * This function follows the priority:
+ * 1. Object with a name property
+ * 2. Exported name
+ * 3. Fallback to deterministic name
+ */
+export declare function extractFunctionName(callExpr: ts.Node, checker: ts.TypeChecker, rootDir: string): ExtractedFunctionName;
+/**
+ * Helper function to populate the 'name' field based on priority
+ */
+export declare function populateNameByPriority(result: ExtractedFunctionName): void;
+/**
+ * Helper function to check if a variable declaration is a named export
+ */
+export declare function isNamedExport(declaration: ts.VariableDeclaration): boolean;