@pikku/inspector 0.9.6-next.0 → 0.10.1

package/dist/utils/middleware.js

@@ -5,7 +5,7 @@ import { extractFunctionName } from './extract-function-name.js';
  * Resolves each identifier to its pikkuFuncName using extractFunctionName
  * Also handles call expressions (like logCommandInfoAndTime({...}))
  */
-export function extractMiddlewarePikkuNames(arrayNode, checker) {
+export function extractMiddlewarePikkuNames(arrayNode, checker, rootDir) {
     if (!ts.isArrayLiteralExpression(arrayNode)) {
         return [];
     }
@@ -13,13 +13,13 @@ export function extractMiddlewarePikkuNames(arrayNode, checker) {
     for (const element of arrayNode.elements) {
         if (ts.isIdentifier(element)) {
             // Resolve the identifier to its pikkuFuncName
-            const { pikkuFuncName } = extractFunctionName(element, checker);
+            const { pikkuFuncName } = extractFunctionName(element, checker, rootDir);
             names.push(pikkuFuncName);
         }
         else if (ts.isCallExpression(element)) {
-            // Handle call expressions like logCommandInfoAndTime({...})
-            // These create inline middleware, so we use the call expression itself as the name
-            const { pikkuFuncName } = extractFunctionName(element, checker);
+            // Handle call expressions like rateLimiter(10) or logCommandInfoAndTime({...})
+            // Extract the function being called (e.g., 'rateLimiter' from 'rateLimiter(10)')
+            const { pikkuFuncName } = extractFunctionName(element.expression, checker, rootDir);
             names.push(pikkuFuncName);
         }
     }
@@ -84,7 +84,7 @@ export function resolveHTTPMiddleware(state, route, tags, explicitMiddlewareNode
     }
     // 3. Explicit wire middleware (inline is OK here)
     if (explicitMiddlewareNode) {
-        const middlewareNames = extractMiddlewarePikkuNames(explicitMiddlewareNode, checker);
+        const middlewareNames = extractMiddlewarePikkuNames(explicitMiddlewareNode, checker, state.rootDir);
         for (const name of middlewareNames) {
             const meta = state.middleware.meta[name];
             resolved.push({
@@ -117,7 +117,7 @@ function resolveTagAndExplicitMiddleware(state, tags, explicitMiddlewareNode, ch
     }
     // 2. Explicit middleware (inline is OK here - used directly in wire/function)
     if (explicitMiddlewareNode) {
-        const middlewareNames = extractMiddlewarePikkuNames(explicitMiddlewareNode, checker);
+        const middlewareNames = extractMiddlewarePikkuNames(explicitMiddlewareNode, checker, state.rootDir);
         for (const name of middlewareNames) {
             const meta = state.middleware.meta[name];
             resolved.push({

package/dist/utils/permissions.d.ts

@@ -0,0 +1,43 @@
+import * as ts from 'typescript';
+import { PermissionMetadata } from '@pikku/core';
+import { InspectorState } from '../types.js';
+/**
+ * Extract permission pikkuFuncNames from an expression (array or object literal)
+ * Resolves each identifier to its pikkuFuncName using extractFunctionName
+ * Also handles call expressions (like rolePermission({...}))
+ *
+ * Supports both formats:
+ * - Array: [permission1, permission2]
+ * - Record: { groupName: permission1, anotherGroup: [permission2, permission3] }
+ */
+export declare function extractPermissionPikkuNames(node: ts.Expression, checker: ts.TypeChecker, rootDir: string): string[];
+/**
+ * Get permissions array from an object literal expression property
+ * Returns the initializer node for the 'permissions' property if it exists
+ */
+export declare function getPermissionsNode(obj: ts.ObjectLiteralExpression): ts.Expression | undefined;
+/**
+ * Check if a route matches a pattern with wildcards
+ * Pattern can be exact match or use * as wildcard
+ * e.g., '/api/*' matches '/api/users', '/api/posts/123', etc.
+ */
+export declare function routeMatchesPattern(route: string, pattern: string): boolean;
+/**
+ * Resolve permissions for an HTTP wiring based on:
+ * 1. Global HTTP permissions (addHTTPPermission('*', [...]))
+ * 2. Route-specific HTTP permissions (addHTTPPermission('/pattern', [...]))
+ * 3. Tag-based permissions (addPermission('tag', [...]))
+ * 4. Explicit wiring permissions (wireHTTP({ permissions: [...] }))
+ * Returns undefined if no permissions are found, otherwise returns array with at least one item
+ */
+export declare function resolveHTTPPermissions(state: InspectorState, route: string, tags: string[] | undefined, explicitPermissionsNode: ts.Expression | undefined, checker: ts.TypeChecker): PermissionMetadata[] | undefined;
+/**
+ * Convenience wrapper: Extract permissions node from object and resolve
+ * Use this in add-* files for cleaner code
+ */
+export declare function resolvePermissions(state: InspectorState, obj: ts.ObjectLiteralExpression, tags: string[] | undefined, checker: ts.TypeChecker): PermissionMetadata[] | undefined;
+/**
+ * Convenience wrapper for HTTP: Extract permissions and resolve with HTTP-specific logic
+ * Use this in add-http-route.ts for cleaner code
+ */
+export declare function resolveHTTPPermissionsFromObject(state: InspectorState, route: string, obj: ts.ObjectLiteralExpression, tags: string[] | undefined, checker: ts.TypeChecker): PermissionMetadata[] | undefined;

package/dist/utils/permissions.js

@@ -0,0 +1,178 @@
+import * as ts from 'typescript';
+import { extractFunctionName } from './extract-function-name.js';
+/**
+ * Extract permission pikkuFuncNames from an expression (array or object literal)
+ * Resolves each identifier to its pikkuFuncName using extractFunctionName
+ * Also handles call expressions (like rolePermission({...}))
+ *
+ * Supports both formats:
+ * - Array: [permission1, permission2]
+ * - Record: { groupName: permission1, anotherGroup: [permission2, permission3] }
+ */
+export function extractPermissionPikkuNames(node, checker, rootDir) {
+    const names = [];
+    // Helper to extract from a single element
+    const extractFromElement = (element) => {
+        if (ts.isIdentifier(element)) {
+            const { pikkuFuncName } = extractFunctionName(element, checker, rootDir);
+            names.push(pikkuFuncName);
+        }
+        else if (ts.isCallExpression(element)) {
+            // Handle call expressions like hasEmailQuota(100) or rolePermission({...})
+            // Extract the function being called (e.g., 'hasEmailQuota' from 'hasEmailQuota(100)')
+            const { pikkuFuncName } = extractFunctionName(element.expression, checker, rootDir);
+            names.push(pikkuFuncName);
+        }
+        else if (ts.isArrayLiteralExpression(element)) {
+            // Nested array (for Record values that are arrays)
+            for (const nestedElement of element.elements) {
+                extractFromElement(nestedElement);
+            }
+        }
+    };
+    if (ts.isArrayLiteralExpression(node)) {
+        // Array format: [permission1, permission2]
+        for (const element of node.elements) {
+            extractFromElement(element);
+        }
+    }
+    else if (ts.isObjectLiteralExpression(node)) {
+        // Record format: { groupName: permission1, anotherGroup: [permission2] }
+        for (const prop of node.properties) {
+            if (ts.isPropertyAssignment(prop)) {
+                extractFromElement(prop.initializer);
+            }
+        }
+    }
+    return names;
+}
+/**
+ * Get permissions array from an object literal expression property
+ * Returns the initializer node for the 'permissions' property if it exists
+ */
+export function getPermissionsNode(obj) {
+    const permissionsProp = obj.properties.find((p) => ts.isPropertyAssignment(p) &&
+        ts.isIdentifier(p.name) &&
+        p.name.text === 'permissions');
+    return permissionsProp?.initializer;
+}
+/**
+ * Check if a route matches a pattern with wildcards
+ * Pattern can be exact match or use * as wildcard
+ * e.g., '/api/*' matches '/api/users', '/api/posts/123', etc.
+ */
+export function routeMatchesPattern(route, pattern) {
+    if (route === pattern)
+        return true;
+    // Convert pattern to regex: replace * with .*
+    const regexPattern = pattern
+        .replace(/[.+?^${}()|[\]\\]/g, '\\$&') // Escape regex special chars except *
+        .replace(/\*/g, '.*'); // Replace * with .*
+    const regex = new RegExp(`^${regexPattern}$`);
+    return regex.test(route);
+}
+/**
+ * Resolve permissions for an HTTP wiring based on:
+ * 1. Global HTTP permissions (addHTTPPermission('*', [...]))
+ * 2. Route-specific HTTP permissions (addHTTPPermission('/pattern', [...]))
+ * 3. Tag-based permissions (addPermission('tag', [...]))
+ * 4. Explicit wiring permissions (wireHTTP({ permissions: [...] }))
+ * Returns undefined if no permissions are found, otherwise returns array with at least one item
+ */
+export function resolveHTTPPermissions(state, route, tags, explicitPermissionsNode, checker) {
+    const resolved = [];
+    // 1. HTTP route permission groups (includes '*' for global)
+    for (const [pattern, _groupMeta] of state.http.routePermissions.entries()) {
+        if (routeMatchesPattern(route, pattern)) {
+            // Just reference the group by route pattern
+            resolved.push({
+                type: 'http',
+                route: pattern,
+            });
+        }
+    }
+    // 2. Tag-based permission groups
+    if (tags && tags.length > 0) {
+        for (const tag of tags) {
+            if (state.permissions.tagPermissions.has(tag)) {
+                // Just reference the group by tag
+                resolved.push({
+                    type: 'tag',
+                    tag,
+                });
+            }
+        }
+    }
+    // 3. Explicit wire permissions (inline is OK here)
+    if (explicitPermissionsNode) {
+        const permissionNames = extractPermissionPikkuNames(explicitPermissionsNode, checker, state.rootDir);
+        for (const name of permissionNames) {
+            const meta = state.permissions.meta[name];
+            resolved.push({
+                type: 'wire',
+                name,
+                inline: meta?.exportedName === null,
+            });
+        }
+    }
+    return resolved.length > 0 ? resolved : undefined;
+}
+/**
+ * Resolve tag-based and explicit permissions (common logic for wires and functions)
+ * 1. Tag-based permissions (addPermission('tag', [...]))
+ * 2. Explicit permissions (wireHTTP/pikkuFunc({ permissions: [...] }))
+ */
+function resolveTagAndExplicitPermissions(state, tags, explicitPermissionsNode, checker) {
+    const resolved = [];
+    // 1. Tag-based permission groups
+    if (tags && tags.length > 0) {
+        for (const tag of tags) {
+            if (state.permissions.tagPermissions.has(tag)) {
+                // Just reference the group by tag
+                resolved.push({
+                    type: 'tag',
+                    tag,
+                });
+            }
+        }
+    }
+    // 2. Explicit permissions (inline is OK here - used directly in wire/function)
+    if (explicitPermissionsNode) {
+        const permissionNames = extractPermissionPikkuNames(explicitPermissionsNode, checker, state.rootDir);
+        for (const name of permissionNames) {
+            const meta = state.permissions.meta[name];
+            resolved.push({
+                type: 'wire',
+                name,
+                inline: meta?.exportedName === null,
+            });
+        }
+    }
+    return resolved;
+}
+/**
+ * Resolve permissions for a function based on:
+ * 1. Tag-based permissions (addPermission('tag', [...]))
+ * 2. Explicit function permissions (pikkuFunc({ permissions: [...] }))
+ * Returns undefined if no permissions are found, otherwise returns array with at least one item
+ */
+function resolveFunctionPermissionsInternal(state, tags, explicitPermissionsNode, checker) {
+    const resolved = resolveTagAndExplicitPermissions(state, tags, explicitPermissionsNode, checker);
+    return resolved.length > 0 ? resolved : undefined;
+}
+/**
+ * Convenience wrapper: Extract permissions node from object and resolve
+ * Use this in add-* files for cleaner code
+ */
+export function resolvePermissions(state, obj, tags, checker) {
+    const explicitPermissionsNode = getPermissionsNode(obj);
+    return resolveFunctionPermissionsInternal(state, tags, explicitPermissionsNode, checker);
+}
+/**
+ * Convenience wrapper for HTTP: Extract permissions and resolve with HTTP-specific logic
+ * Use this in add-http-route.ts for cleaner code
+ */
+export function resolveHTTPPermissionsFromObject(state, route, obj, tags, checker) {
+    const explicitPermissionsNode = getPermissionsNode(obj);
+    return resolveHTTPPermissions(state, route, tags, explicitPermissionsNode, checker);
+}

package/dist/utils/post-process.d.ts

@@ -0,0 +1,16 @@
+import { InspectorState } from '../types.js';
+import { MiddlewareMetadata, PermissionMetadata } from '@pikku/core';
+/**
+ * Helper to extract wire-level middleware/permission names from metadata.
+ * Only extracts type:'wire' variants (individual middleware/permissions).
+ * Skips type:'http' and type:'tag' (reference groups, not individuals).
+ */
+export declare function extractWireNames(list?: MiddlewareMetadata[] | PermissionMetadata[]): string[];
+/**
+ * Aggregates all required services from wired functions, middleware, and permissions.
+ * Must be called after AST traversal completes.
+ *
+ * Note: usedFunctions, usedMiddleware, and usedPermissions are tracked directly
+ * in the add-* methods during AST traversal for efficiency.
+ */
+export declare function aggregateRequiredServices(state: InspectorState): void;

package/dist/utils/post-process.js

@@ -0,0 +1,132 @@
+/**
+ * Helper to extract wire-level middleware/permission names from metadata.
+ * Only extracts type:'wire' variants (individual middleware/permissions).
+ * Skips type:'http' and type:'tag' (reference groups, not individuals).
+ */
+export function extractWireNames(list) {
+    if (!list)
+        return [];
+    return list
+        .filter((item) => item.type === 'wire')
+        .map((item) => item.name);
+}
+/**
+ * Helper to expand middleware/permission groups into individual names
+ * and add their services to the aggregation.
+ * This handles tag-based and HTTP-pattern-based middleware/permission groups.
+ */
+function expandAndAddGroupServices(list, state, addServices, isMiddleware) {
+    if (!list)
+        return;
+    for (const item of list) {
+        if (item.type === 'tag') {
+            // Expand tag-based group
+            const groupMeta = isMiddleware
+                ? state.middleware.tagMiddleware.get(item.tag)
+                : state.permissions.tagPermissions.get(item.tag);
+            if (groupMeta?.services) {
+                addServices(groupMeta.services);
+            }
+        }
+        else if (item.type === 'http' && 'route' in item) {
+            // Expand HTTP-pattern-based group
+            const groupMeta = isMiddleware
+                ? state.http.routeMiddleware.get(item.route)
+                : state.http.routePermissions.get(item.route);
+            if (groupMeta?.services) {
+                addServices(groupMeta.services);
+            }
+        }
+    }
+}
+/**
+ * Aggregates all required services from wired functions, middleware, and permissions.
+ * Must be called after AST traversal completes.
+ *
+ * Note: usedFunctions, usedMiddleware, and usedPermissions are tracked directly
+ * in the add-* methods during AST traversal for efficiency.
+ */
+export function aggregateRequiredServices(state) {
+    const { requiredServices, usedFunctions, usedMiddleware, usedPermissions } = state.serviceAggregation;
+    // Internal services (always excluded from tree-shaking)
+    const internalServices = new Set(['rpc', 'mcp', 'channel', 'userSession']);
+    const addServices = (services) => {
+        if (!services || !services.services)
+            return;
+        services.services.forEach((service) => {
+            if (!internalServices.has(service)) {
+                requiredServices.add(service);
+            }
+        });
+    };
+    // 1. Services from used functions
+    usedFunctions.forEach((funcName) => {
+        const funcMeta = state.functions.meta[funcName];
+        if (funcMeta?.services) {
+            addServices(funcMeta.services);
+        }
+    });
+    // 2. Services from used middleware (individual + groups)
+    usedMiddleware.forEach((middlewareName) => {
+        const middlewareMeta = state.middleware.meta[middlewareName];
+        if (middlewareMeta?.services) {
+            addServices(middlewareMeta.services);
+        }
+    });
+    // 3. Services from used permissions (individual + groups)
+    usedPermissions.forEach((permissionName) => {
+        const permissionMeta = state.permissions.meta[permissionName];
+        if (permissionMeta?.services) {
+            addServices(permissionMeta.services);
+        }
+    });
+    // 4. Services from middleware/permission groups used in wirings
+    // We need to check all wirings and expand any tag/HTTP-pattern groups they use
+    for (const method of [
+        'get',
+        'post',
+        'put',
+        'patch',
+        'delete',
+        'head',
+        'options',
+    ]) {
+        for (const routeMeta of Object.values(state.http.meta[method])) {
+            expandAndAddGroupServices(routeMeta.middleware, state, addServices, true);
+            expandAndAddGroupServices(routeMeta.permissions, state, addServices, false);
+        }
+    }
+    // Also check other wiring types (channels, queues, schedulers, MCP)
+    for (const channelMeta of Object.values(state.channels.meta)) {
+        expandAndAddGroupServices(channelMeta.middleware, state, addServices, true);
+        expandAndAddGroupServices(channelMeta.permissions, state, addServices, false);
+    }
+    for (const queueMeta of Object.values(state.queueWorkers.meta)) {
+        expandAndAddGroupServices(queueMeta.middleware, state, addServices, true);
+        // expandAndAddGroupServices(queueMeta.permissions, state, addServices, false)
+    }
+    for (const scheduleMeta of Object.values(state.scheduledTasks.meta)) {
+        expandAndAddGroupServices(scheduleMeta.middleware, state, addServices, true);
+        // expandAndAddGroupServices(scheduleMeta.permissions, state, addServices, false)
+    }
+    for (const toolMeta of Object.values(state.mcpEndpoints.toolsMeta)) {
+        expandAndAddGroupServices(toolMeta.middleware, state, addServices, true);
+        expandAndAddGroupServices(toolMeta.permissions, state, addServices, false);
+    }
+    for (const promptMeta of Object.values(state.mcpEndpoints.promptsMeta)) {
+        expandAndAddGroupServices(promptMeta.middleware, state, addServices, true);
+        expandAndAddGroupServices(promptMeta.permissions, state, addServices, false);
+    }
+    for (const resourceMeta of Object.values(state.mcpEndpoints.resourcesMeta)) {
+        expandAndAddGroupServices(resourceMeta.middleware, state, addServices, true);
+        expandAndAddGroupServices(resourceMeta.permissions, state, addServices, false);
+    }
+    // 5. Services from session service factories
+    for (const singletonServices of state.sessionServicesMeta.values()) {
+        singletonServices.forEach((service) => {
+            if (!internalServices.has(service)) {
+                requiredServices.add(service);
+            }
+        });
+    }
+}

package/dist/utils/serialize-inspector-state.d.ts

@@ -0,0 +1,179 @@
+import { InspectorState } from '../types.js';
+/**
+ * Serializable version of InspectorState that can be saved to JSON
+ * Omits typesLookup (contains non-serializable ts.Type objects) and converts Maps/Sets to arrays
+ */
+export interface SerializableInspectorState {
+    rootDir: string;
+    singletonServicesTypeImportMap: Array<[
+        string,
+        {
+            variable: string;
+            type: string | null;
+            typePath: string | null;
+        }[]
+    ]>;
+    sessionServicesTypeImportMap: Array<[
+        string,
+        {
+            variable: string;
+            type: string | null;
+            typePath: string | null;
+        }[]
+    ]>;
+    userSessionTypeImportMap: Array<[
+        string,
+        {
+            variable: string;
+            type: string | null;
+            typePath: string | null;
+        }[]
+    ]>;
+    configTypeImportMap: Array<[
+        string,
+        {
+            variable: string;
+            type: string | null;
+            typePath: string | null;
+        }[]
+    ]>;
+    singletonServicesFactories: Array<[
+        string,
+        {
+            variable: string;
+            type: string | null;
+            typePath: string | null;
+        }[]
+    ]>;
+    sessionServicesFactories: Array<[
+        string,
+        {
+            variable: string;
+            type: string | null;
+            typePath: string | null;
+        }[]
+    ]>;
+    sessionServicesMeta: Array<[string, string[]]>;
+    configFactories: Array<[
+        string,
+        {
+            variable: string;
+            type: string | null;
+            typePath: string | null;
+        }[]
+    ]>;
+    filesAndMethods: InspectorState['filesAndMethods'];
+    filesAndMethodsErrors: Array<[
+        string,
+        Array<[
+            string,
+            {
+                variable: string;
+                type: string | null;
+                typePath: string | null;
+            }[]
+        ]>
+    ]>;
+    functions: {
+        typesMap: {
+            map: Array<[string, {
+                originalName: string;
+                path: string | null;
+            }]>;
+            customTypes: Array<[string, {
+                type: string;
+                references: string[];
+            }]>;
+        };
+        meta: InspectorState['functions']['meta'];
+        files: Array<[string, {
+            path: string;
+            exportedName: string;
+        }]>;
+    };
+    http: {
+        metaInputTypes: Array<[
+            string,
+            {
+                query: string[] | undefined;
+                params: string[] | undefined;
+                body: string[] | undefined;
+            }
+        ]>;
+        meta: InspectorState['http']['meta'];
+        files: string[];
+        routeMiddleware: Array<[
+            string,
+            InspectorState['http']['routeMiddleware'] extends Map<string, infer V> ? V : never
+        ]>;
+        routePermissions: Array<[
+            string,
+            InspectorState['http']['routePermissions'] extends Map<string, infer V> ? V : never
+        ]>;
+    };
+    channels: {
+        files: string[];
+        meta: InspectorState['channels']['meta'];
+    };
+    scheduledTasks: {
+        meta: InspectorState['scheduledTasks']['meta'];
+        files: string[];
+    };
+    queueWorkers: {
+        meta: InspectorState['queueWorkers']['meta'];
+        files: string[];
+    };
+    rpc: {
+        internalMeta: InspectorState['rpc']['internalMeta'];
+        internalFiles: Array<[string, {
+            path: string;
+            exportedName: string;
+        }]>;
+        exposedMeta: InspectorState['rpc']['exposedMeta'];
+        exposedFiles: Array<[string, {
+            path: string;
+            exportedName: string;
+        }]>;
+        invokedFunctions: string[];
+    };
+    mcpEndpoints: {
+        resourcesMeta: InspectorState['mcpEndpoints']['resourcesMeta'];
+        toolsMeta: InspectorState['mcpEndpoints']['toolsMeta'];
+        promptsMeta: InspectorState['mcpEndpoints']['promptsMeta'];
+        files: string[];
+    };
+    cli: {
+        meta: InspectorState['cli']['meta'];
+        files: string[];
+    };
+    middleware: {
+        meta: InspectorState['middleware']['meta'];
+        tagMiddleware: Array<[
+            string,
+            InspectorState['middleware']['tagMiddleware'] extends Map<string, infer V> ? V : never
+        ]>;
+    };
+    permissions: {
+        meta: InspectorState['permissions']['meta'];
+        tagPermissions: Array<[
+            string,
+            InspectorState['permissions']['tagPermissions'] extends Map<string, infer V> ? V : never
+        ]>;
+    };
+    serviceAggregation: {
+        requiredServices: string[];
+        usedFunctions: string[];
+        usedMiddleware: string[];
+        usedPermissions: string[];
+    };
+}
+/**
+ * Serializes InspectorState to a JSON-compatible format
+ * Omits typesLookup (not needed for filtering/generation) and converts Maps/Sets to arrays
+ */
+export declare function serializeInspectorState(state: InspectorState): SerializableInspectorState;
+/**
+ * Deserializes JSON data back to InspectorState
+ * Creates a partial state suitable for filtering/generation (without typesLookup)
+ */
+export declare function deserializeInspectorState(data: SerializableInspectorState): Omit<InspectorState, 'typesLookup'>;