@pikku/inspector 0.10.2 → 0.11.0

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+## 0.11.0
+
+### Minor Changes
+
+- Add workflow inspection and analysis
+- Add enhanced type extraction utilities
+
+
 # @pikku/inspector
 
 ## 0.10.2

package/dist/add/add-functions.js

@@ -233,6 +233,7 @@ export const addFunctions = (logger, node, checker, state) => {
     const { pikkuFuncName, name, explicitName, exportedName } = extractFunctionName(node, checker, state.rootDir);
     let tags;
     let expose;
+    let internal;
     let docs;
     let objectNode;
     // determine the actual handler expression:
@@ -244,6 +245,7 @@ export const addFunctions = (logger, node, checker, state) => {
         objectNode = handlerNode;
         tags = getPropertyValue(handlerNode, 'tags') || undefined;
         expose = getPropertyValue(handlerNode, 'expose');
+        internal = getPropertyValue(handlerNode, 'internal');
         docs = getPropertyValue(handlerNode, 'docs');
         const fnProp = getPropertyAssignmentInitializer(handlerNode, 'func', true, checker);
         if (!fnProp ||
@@ -342,6 +344,7 @@ export const addFunctions = (logger, node, checker, state) => {
         inputs: inputNames.filter((n) => n !== 'void') ?? null,
         outputs: outputNames.filter((n) => n !== 'void') ?? null,
         expose: expose || undefined,
+        internal: internal || undefined,
         tags: tags || undefined,
         docs: docs || undefined,
         isDirectFunction,
@@ -363,6 +366,10 @@ export const addFunctions = (logger, node, checker, state) => {
             logger.error(`• Function with explicit name '${name}' is not exported, this is not allowed.`);
             return;
         }
+        // Mark internal functions as invoked to force bundling
+        if (internal) {
+            state.rpc.invokedFunctions.add(pikkuFuncName);
+        }
         if (expose) {
             state.rpc.exposedMeta[name] = pikkuFuncName;
             state.rpc.exposedFiles.set(name, {
@@ -376,8 +383,8 @@ export const addFunctions = (logger, node, checker, state) => {
         state.rpc.internalMeta[name] = pikkuFuncName;
         // But we only import the actual function if it's actually invoked to keep
         // bundle size down
-        if (state.rpc.invokedFunctions.has(pikkuFuncName) || expose) {
-            state.rpc.internalFiles.set(name, {
+        if (state.rpc.invokedFunctions.has(pikkuFuncName) || expose || internal) {
+            state.rpc.internalFiles.set(pikkuFuncName, {
                 path: node.getSourceFile().fileName,
                 exportedName,
             });

package/dist/add/add-workflow.d.ts

@@ -0,0 +1,6 @@
+import { AddWiring } from '../types.js';
+/**
+ * Inspector for wireWorkflow() calls
+ * Detects workflow registration and extracts metadata
+ */
+export declare const addWorkflow: AddWiring;

package/dist/add/add-workflow.js

@@ -0,0 +1,152 @@
+import * as ts from 'typescript';
+import { getPropertyValue, getPropertyTags, } from '../utils/get-property-value.js';
+import { extractFunctionName } from '../utils/extract-function-name.js';
+import { getPropertyAssignmentInitializer, resolveFunctionDeclaration, } from '../utils/type-utils.js';
+import { resolveMiddleware } from '../utils/middleware.js';
+import { extractWireNames } from '../utils/post-process.js';
+import { ErrorCode } from '../error-codes.js';
+import { extractStringLiteral, extractNumberLiteral, extractPropertyString, isStringLike, isFunctionLike, } from '../utils/extract-node-value.js';
+/**
+ * Scan for workflow.do() and workflow.sleep() calls to extract workflow steps
+ */
+function getWorkflowInvocations(node, checker, state, workflowName, steps) {
+    // Look for property access expressions: workflow.do or workflow.sleep
+    if (ts.isPropertyAccessExpression(node)) {
+        const { name } = node;
+        // Check if this is accessing 'do' or 'sleep' property
+        if (name.text === 'do' || name.text === 'sleep') {
+            // Check if the parent is a call expression
+            const parent = node.parent;
+            if (ts.isCallExpression(parent) && parent.expression === node) {
+                const args = parent.arguments;
+                if (name.text === 'do' && args.length >= 2) {
+                    // workflow.do(stepName, rpcName|fn, data?, options?)
+                    const stepNameArg = args[0];
+                    const secondArg = args[1];
+                    const optionsArg = args.length >= 3 ? args[args.length - 1] : undefined;
+                    const stepName = extractStringLiteral(stepNameArg, checker);
+                    const description = extractDescription(optionsArg, checker) ?? undefined;
+                    // Determine form by checking 2nd argument type
+                    if (isStringLike(secondArg, checker)) {
+                        // RPC form: workflow.do(stepName, rpcName, data, options?)
+                        const rpcName = extractStringLiteral(secondArg, checker);
+                        steps.push({
+                            type: 'rpc',
+                            stepName,
+                            rpcName,
+                            description,
+                        });
+                        state.rpc.invokedFunctions.add(rpcName);
+                    }
+                    else if (isFunctionLike(secondArg)) {
+                        // Inline form: workflow.do(stepName, fn, options?)
+                        steps.push({
+                            type: 'inline',
+                            stepName: stepName || '<dynamic>',
+                            description: description || '<dynamic>',
+                        });
+                    }
+                }
+                else if (name.text === 'sleep' && args.length >= 2) {
+                    // workflow.sleep(stepName, duration)
+                    const stepNameArg = args[0];
+                    const durationArg = args[1];
+                    const stepName = extractStringLiteral(stepNameArg, checker);
+                    const duration = extractDuration(durationArg, checker);
+                    steps.push({
+                        type: 'sleep',
+                        stepName: stepName || '<dynamic>',
+                        duration: duration || '<dynamic>',
+                    });
+                }
+            }
+        }
+    }
+    // Don't recurse into nested functions - only look at top-level workflow calls
+    ts.forEachChild(node, (child) => {
+        if (ts.isFunctionDeclaration(child) ||
+            ts.isFunctionExpression(child) ||
+            ts.isArrowFunction(child)) {
+            return;
+        }
+        getWorkflowInvocations(child, checker, state, workflowName, steps);
+    });
+}
+/**
+ * Extract description from options object
+ */
+function extractDescription(optionsNode, checker) {
+    if (!optionsNode || !ts.isObjectLiteralExpression(optionsNode)) {
+        return null;
+    }
+    return extractPropertyString(optionsNode, 'description', checker);
+}
+/**
+ * Extract duration value (number or string)
+ */
+function extractDuration(node, checker) {
+    const numValue = extractNumberLiteral(node);
+    if (numValue !== null) {
+        return numValue;
+    }
+    return extractStringLiteral(node, checker);
+}
+/**
+ * Inspector for wireWorkflow() calls
+ * Detects workflow registration and extracts metadata
+ */
+export const addWorkflow = (logger, node, checker, state, options) => {
+    if (!ts.isCallExpression(node)) {
+        return;
+    }
+    const args = node.arguments;
+    const firstArg = args[0];
+    const expression = node.expression;
+    // Check if the call is to wireWorkflow
+    if (!ts.isIdentifier(expression) || expression.text !== 'wireWorkflow') {
+        return;
+    }
+    if (!firstArg) {
+        return;
+    }
+    if (ts.isObjectLiteralExpression(firstArg)) {
+        const obj = firstArg;
+        const workflowName = getPropertyValue(obj, 'name');
+        const description = getPropertyValue(obj, 'description');
+        const docs = getPropertyValue(obj, 'docs') || undefined;
+        const tags = getPropertyTags(obj, 'Workflow', workflowName, logger);
+        // --- find the referenced function ---
+        const funcInitializer = getPropertyAssignmentInitializer(obj, 'func', true, checker);
+        if (!workflowName) {
+            logger.critical(ErrorCode.MISSING_NAME, `Wasn't able to determine 'name' property for workflow wiring.`);
+            return;
+        }
+        if (!funcInitializer) {
+            logger.critical(ErrorCode.MISSING_FUNC, `No valid 'func' property for workflow '${workflowName}'.`);
+            return;
+        }
+        const pikkuFuncName = extractFunctionName(funcInitializer, checker, state.rootDir).pikkuFuncName;
+        // --- 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.workflows.files.add(node.getSourceFile().fileName);
+        // Extract workflow steps from function body
+        // Resolve the identifier to the actual function declaration
+        const resolvedFunc = resolveFunctionDeclaration(funcInitializer, checker);
+        const steps = [];
+        if (resolvedFunc) {
+            getWorkflowInvocations(resolvedFunc, checker, state, workflowName, steps);
+        }
+        state.workflows.meta[workflowName] = {
+            pikkuFuncName,
+            workflowName,
+            description,
+            docs,
+            tags,
+            middleware,
+            steps,
+        };
+    }
+};

package/dist/error-codes.d.ts

@@ -17,6 +17,8 @@ export declare enum ErrorCode {
     MISSING_QUEUE_NAME = "PKU384",
     MISSING_CHANNEL_NAME = "PKU400",
     CLI_CLIENTSIDE_RENDERER_HAS_SERVICES = "PKU672",
+    DYNAMIC_STEP_NAME = "PKU529",
+    WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED = "PKU600",
     CONFIG_TYPE_NOT_FOUND = "PKU426",
     CONFIG_TYPE_UNDEFINED = "PKU427",
     SCHEMA_NO_ROOT = "PKU431",
@@ -31,5 +33,6 @@ export declare enum ErrorCode {
     PERMISSION_HANDLER_INVALID = "PKU835",
     PERMISSION_TAG_INVALID = "PKU836",
     PERMISSION_EMPTY_ARRAY = "PKU937",
-    PERMISSION_PATTERN_INVALID = "PKU975"
+    PERMISSION_PATTERN_INVALID = "PKU975",
+    WORKFLOW_MULTI_QUEUE_NOT_SUPPORTED = "PKU901"
 }

package/dist/error-codes.js

@@ -19,6 +19,8 @@ export var ErrorCode;
     ErrorCode["MISSING_QUEUE_NAME"] = "PKU384";
     ErrorCode["MISSING_CHANNEL_NAME"] = "PKU400";
     ErrorCode["CLI_CLIENTSIDE_RENDERER_HAS_SERVICES"] = "PKU672";
+    ErrorCode["DYNAMIC_STEP_NAME"] = "PKU529";
+    ErrorCode["WORKFLOW_ORCHESTRATOR_NOT_CONFIGURED"] = "PKU600";
     // Configuration errors
     ErrorCode["CONFIG_TYPE_NOT_FOUND"] = "PKU426";
     ErrorCode["CONFIG_TYPE_UNDEFINED"] = "PKU427";
@@ -37,4 +39,6 @@ export var ErrorCode;
     ErrorCode["PERMISSION_TAG_INVALID"] = "PKU836";
     ErrorCode["PERMISSION_EMPTY_ARRAY"] = "PKU937";
     ErrorCode["PERMISSION_PATTERN_INVALID"] = "PKU975";
+    // Feature Flag
+    ErrorCode["WORKFLOW_MULTI_QUEUE_NOT_SUPPORTED"] = "PKU901";
 })(ErrorCode || (ErrorCode = {}));

package/dist/inspector.js

@@ -56,6 +56,10 @@ export function getInitialInspectorState(rootDir) {
             meta: {},
             files: new Set(),
         },
+        workflows: {
+            meta: {},
+            files: new Set(),
+        },
         rpc: {
             internalMeta: {},
             internalFiles: new Map(),

package/dist/types.d.ts

@@ -2,7 +2,8 @@ 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 { QueueWorkersMeta } from '@pikku/core/queue';
+import { WorkflowsMeta } from '@pikku/core/workflow';
 import { MCPResourceMeta, MCPToolMeta, MCPPromptMeta } from '@pikku/core/mcp';
 import { CLIMeta } from '@pikku/core/cli';
 import { TypesMap } from './types-map.js';
@@ -168,7 +169,11 @@ export interface InspectorState {
         files: Set<string>;
     };
     queueWorkers: {
-        meta: queueWorkersMeta;
+        meta: QueueWorkersMeta;
+        files: Set<string>;
+    };
+    workflows: {
+        meta: WorkflowsMeta;
         files: Set<string>;
     };
     rpc: {

package/dist/utils/extract-node-value.d.ts

@@ -0,0 +1,24 @@
+import * as ts from 'typescript';
+/**
+ * Extract string literal value from a TypeScript node.
+ * Handles string literals, template literals (including placeholders),
+ * and constant variable references.
+ */
+export declare function extractStringLiteral(node: ts.Node, checker: ts.TypeChecker): string;
+/**
+ * Check if node is string-like (string literal or template expression)
+ */
+export declare function isStringLike(node: ts.Node, _checker: ts.TypeChecker): boolean;
+/**
+ * Check if node is function-like (arrow, function expression, or function declaration)
+ */
+export declare function isFunctionLike(node: ts.Node): boolean;
+/**
+ * Extract number literal value from a node
+ */
+export declare function extractNumberLiteral(node: ts.Node): number | null;
+/**
+ * Extract a property value from an object literal expression
+ * Returns the extracted value or null if not found/cannot extract
+ */
+export declare function extractPropertyString(objNode: ts.ObjectLiteralExpression, propertyName: string, checker: ts.TypeChecker): string | null;

package/dist/utils/extract-node-value.js

@@ -0,0 +1,79 @@
+import * as ts from 'typescript';
+/**
+ * Extract string literal value from a TypeScript node.
+ * Handles string literals, template literals (including placeholders),
+ * and constant variable references.
+ */
+export function extractStringLiteral(node, checker) {
+    if (ts.isStringLiteral(node)) {
+        return node.text;
+    }
+    if (ts.isNoSubstitutionTemplateLiteral(node)) {
+        return node.text;
+    }
+    if (ts.isTemplateExpression(node)) {
+        // reconstruct: `head + ${expr} + middle + ${expr} + tail`
+        let result = node.head.text;
+        for (const span of node.templateSpans) {
+            const exprText = span.expression.getText();
+            result += '${' + exprText + '}' + span.literal.text;
+        }
+        return result;
+    }
+    // Try to evaluate constant identifiers
+    if (ts.isIdentifier(node)) {
+        const symbol = checker.getSymbolAtLocation(node);
+        if (symbol?.valueDeclaration &&
+            ts.isVariableDeclaration(symbol.valueDeclaration)) {
+            const init = symbol.valueDeclaration.initializer;
+            if (init) {
+                return extractStringLiteral(init, checker);
+            }
+        }
+    }
+    throw new Error('Unable to extract string literal from node');
+}
+/**
+ * Check if node is string-like (string literal or template expression)
+ */
+export function isStringLike(node, _checker) {
+    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
+        return true;
+    }
+    // Check if it's a template string with substitutions
+    if (ts.isTemplateExpression(node)) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Check if node is function-like (arrow, function expression, or function declaration)
+ */
+export function isFunctionLike(node) {
+    return (ts.isArrowFunction(node) ||
+        ts.isFunctionExpression(node) ||
+        ts.isFunctionDeclaration(node));
+}
+/**
+ * Extract number literal value from a node
+ */
+export function extractNumberLiteral(node) {
+    if (ts.isNumericLiteral(node)) {
+        return Number(node.text);
+    }
+    return null;
+}
+/**
+ * Extract a property value from an object literal expression
+ * Returns the extracted value or null if not found/cannot extract
+ */
+export function extractPropertyString(objNode, propertyName, checker) {
+    for (const prop of objNode.properties) {
+        if (ts.isPropertyAssignment(prop) &&
+            ts.isIdentifier(prop.name) &&
+            prop.name.text === propertyName) {
+            return extractStringLiteral(prop.initializer, checker);
+        }
+    }
+    return null;
+}

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

@@ -123,6 +123,10 @@ export interface SerializableInspectorState {
         meta: InspectorState['queueWorkers']['meta'];
         files: string[];
     };
+    workflows: {
+        meta: InspectorState['workflows']['meta'];
+        files: string[];
+    };
     rpc: {
         internalMeta: InspectorState['rpc']['internalMeta'];
         internalFiles: Array<[string, {

package/dist/utils/serialize-inspector-state.js

@@ -50,6 +50,10 @@ export function serializeInspectorState(state) {
             meta: state.queueWorkers.meta,
             files: Array.from(state.queueWorkers.files),
         },
+        workflows: {
+            meta: state.workflows.meta,
+            files: Array.from(state.workflows.files),
+        },
         rpc: {
             internalMeta: state.rpc.internalMeta,
             internalFiles: Array.from(state.rpc.internalFiles.entries()),
@@ -137,6 +141,10 @@ export function deserializeInspectorState(data) {
             meta: data.queueWorkers.meta,
             files: new Set(data.queueWorkers.files),
         },
+        workflows: {
+            meta: data.workflows.meta,
+            files: new Set(data.workflows.files),
+        },
         rpc: {
             internalMeta: data.rpc.internalMeta,
             internalFiles: new Map(data.rpc.internalFiles),

package/dist/utils/type-utils.d.ts

@@ -1,3 +1,7 @@
 import * as ts from 'typescript';
 export declare const extractTypeKeys: (type: ts.Type) => string[];
+/**
+ * Resolve an identifier or call expression to the actual function declaration
+ */
+export declare function resolveFunctionDeclaration(node: ts.Node, checker: ts.TypeChecker): ts.Node | null;
 export declare function getPropertyAssignmentInitializer(obj: ts.ObjectLiteralExpression, propName: string, followShorthand?: boolean, checker?: ts.TypeChecker): ts.Expression | undefined;

package/dist/utils/type-utils.js

@@ -2,6 +2,61 @@ import * as ts from 'typescript';
 export const extractTypeKeys = (type) => {
     return type.getProperties().map((symbol) => symbol.getName());
 };
+/**
+ * Resolve an identifier or call expression to the actual function declaration
+ */
+export function resolveFunctionDeclaration(node, checker) {
+    // If it's already a function-like node, return it
+    if (ts.isFunctionDeclaration(node) ||
+        ts.isFunctionExpression(node) ||
+        ts.isArrowFunction(node)) {
+        return node;
+    }
+    // If it's a call expression (e.g., pikkuWorkflowFunc(...)), get its first argument
+    if (ts.isCallExpression(node) && node.arguments.length > 0) {
+        const firstArg = node.arguments[0];
+        if (ts.isFunctionExpression(firstArg) || ts.isArrowFunction(firstArg)) {
+            return firstArg;
+        }
+    }
+    // If it's an identifier, resolve to declaration
+    if (ts.isIdentifier(node)) {
+        const symbol = checker.getSymbolAtLocation(node);
+        if (!symbol)
+            return null;
+        // Try valueDeclaration first, then fallback to declarations[0]
+        const decl = symbol.valueDeclaration || symbol.declarations?.[0];
+        if (!decl)
+            return null;
+        // If it's an import specifier, resolve the aliased symbol
+        if (ts.isImportSpecifier(decl)) {
+            const aliasedSymbol = checker.getAliasedSymbol(symbol);
+            if (aliasedSymbol) {
+                const aliasedDecl = aliasedSymbol.valueDeclaration || aliasedSymbol.declarations?.[0];
+                if (aliasedDecl) {
+                    // For variable declarations, get the initializer
+                    if (ts.isVariableDeclaration(aliasedDecl) &&
+                        aliasedDecl.initializer) {
+                        return resolveFunctionDeclaration(aliasedDecl.initializer, checker);
+                    }
+                    // For function declarations, return directly
+                    if (ts.isFunctionDeclaration(aliasedDecl)) {
+                        return aliasedDecl;
+                    }
+                }
+            }
+        }
+        // If it's a variable declaration, get the initializer
+        if (ts.isVariableDeclaration(decl) && decl.initializer) {
+            return resolveFunctionDeclaration(decl.initializer, checker);
+        }
+        // If it's a function declaration
+        if (ts.isFunctionDeclaration(decl)) {
+            return decl;
+        }
+    }
+    return null;
+}
 export function getPropertyAssignmentInitializer(obj, propName, followShorthand = false, checker) {
     for (const prop of obj.properties) {
         // ①  foo: () => {}

package/dist/visit.js

@@ -4,6 +4,7 @@ import { addFileExtendsCoreType } from './add/add-file-extends-core-type.js';
 import { addHTTPRoute } from './add/add-http-route.js';
 import { addSchedule } from './add/add-schedule.js';
 import { addQueueWorker } from './add/add-queue-worker.js';
+import { addWorkflow } from './add/add-workflow.js';
 import { addMCPResource } from './add/add-mcp-resource.js';
 import { addMCPTool } from './add/add-mcp-tool.js';
 import { addMCPPrompt } from './add/add-mcp-prompt.js';
@@ -24,6 +25,7 @@ export const visitSetup = (logger, checker, node, state, options) => {
     addRPCInvocations(node, state, logger);
     addMiddleware(logger, node, checker, state, options);
     addPermission(logger, node, checker, state, options);
+    addWorkflow(logger, node, checker, state, options);
     ts.forEachChild(node, (child) => visitSetup(logger, checker, child, state, options));
 };
 export const visitRoutes = (logger, checker, node, state, options) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.10.2",
+  "version": "0.11.0",
   "author": "yasser.fadl@gmail.com",
   "license": "MIT",
   "type": "module",
@@ -16,7 +16,7 @@
     "test:coverage": "bash run-tests.sh --coverage"
   },
   "dependencies": {
-    "@pikku/core": "^0.10.2",
+    "@pikku/core": "^0.11.0",
     "path-to-regexp": "^8.3.0",
     "typescript": "^5.9"
   },

package/src/add/add-functions.ts

@@ -305,6 +305,7 @@ export const addFunctions: AddWiring = (logger, node, checker, state) => {
 
   let tags: string[] | undefined
   let expose: boolean | undefined
+  let internal: boolean | undefined
   let docs: PikkuDocs | undefined
   let objectNode: ts.ObjectLiteralExpression | undefined
 
@@ -318,6 +319,7 @@ export const addFunctions: AddWiring = (logger, node, checker, state) => {
     objectNode = handlerNode
     tags = (getPropertyValue(handlerNode, 'tags') as string[]) || undefined
     expose = getPropertyValue(handlerNode, 'expose') as boolean | undefined
+    internal = getPropertyValue(handlerNode, 'internal') as boolean | undefined
     docs = getPropertyValue(handlerNode, 'docs') as PikkuDocs | undefined
 
     const fnProp = getPropertyAssignmentInitializer(
@@ -454,6 +456,7 @@ export const addFunctions: AddWiring = (logger, node, checker, state) => {
     inputs: inputNames.filter((n) => n !== 'void') ?? null,
     outputs: outputNames.filter((n) => n !== 'void') ?? null,
     expose: expose || undefined,
+    internal: internal || undefined,
     tags: tags || undefined,
     docs: docs || undefined,
     isDirectFunction,
@@ -481,6 +484,11 @@ export const addFunctions: AddWiring = (logger, node, checker, state) => {
       return
     }
 
+    // Mark internal functions as invoked to force bundling
+    if (internal) {
+      state.rpc.invokedFunctions.add(pikkuFuncName)
+    }
+
     if (expose) {
       state.rpc.exposedMeta[name] = pikkuFuncName
       state.rpc.exposedFiles.set(name, {
@@ -496,8 +504,8 @@ export const addFunctions: AddWiring = (logger, node, checker, state) => {
 
     // But we only import the actual function if it's actually invoked to keep
     // bundle size down
-    if (state.rpc.invokedFunctions.has(pikkuFuncName) || expose) {
-      state.rpc.internalFiles.set(name, {
+    if (state.rpc.invokedFunctions.has(pikkuFuncName) || expose || internal) {
+      state.rpc.internalFiles.set(pikkuFuncName, {
         path: node.getSourceFile().fileName,
         exportedName,
       })