@pikku/inspector 0.10.2 → 0.11.1

package/dist/workflow/patterns.d.ts

@@ -0,0 +1,39 @@
+import * as ts from 'typescript';
+/**
+ * Pattern detection helpers for simple workflow extraction
+ */
+/**
+ * Check if a call expression is workflow.do()
+ */
+export declare function isWorkflowDoCall(node: ts.CallExpression, checker: ts.TypeChecker): boolean;
+/**
+ * Check if a call expression is workflow.sleep()
+ */
+export declare function isWorkflowSleepCall(node: ts.CallExpression, checker: ts.TypeChecker): boolean;
+/**
+ * Check if an expression is Promise.all(array.map(...))
+ */
+export declare function isParallelFanout(node: ts.CallExpression): boolean;
+/**
+ * Check if an expression is Promise.all([...])
+ */
+export declare function isParallelGroup(node: ts.CallExpression): boolean;
+/**
+ * Check if a for statement is a valid sequential fanout (for..of)
+ */
+export declare function isSequentialFanout(node: ts.ForOfStatement): boolean;
+/**
+ * Extract the variable name from a for..of statement
+ */
+export declare function extractForOfVariable(node: ts.ForOfStatement): {
+    itemVar: string;
+    sourceVar: string;
+} | null;
+/**
+ * Check if a type is an array type
+ */
+export declare function isArrayType(type: ts.Type, checker: ts.TypeChecker): boolean;
+/**
+ * Get the source text of a node (for condition expressions)
+ */
+export declare function getSourceText(node: ts.Node): string;

package/dist/workflow/patterns.js

@@ -0,0 +1,138 @@
+import * as ts from 'typescript';
+/**
+ * Pattern detection helpers for simple workflow extraction
+ */
+/**
+ * Check if a call expression is workflow.do()
+ */
+export function isWorkflowDoCall(node, checker) {
+    if (!ts.isPropertyAccessExpression(node.expression)) {
+        return false;
+    }
+    const propAccess = node.expression;
+    return (propAccess.name.text === 'do' &&
+        ts.isIdentifier(propAccess.expression) &&
+        propAccess.expression.text === 'workflow');
+}
+/**
+ * Check if a call expression is workflow.sleep()
+ */
+export function isWorkflowSleepCall(node, checker) {
+    if (!ts.isPropertyAccessExpression(node.expression)) {
+        return false;
+    }
+    const propAccess = node.expression;
+    return (propAccess.name.text === 'sleep' &&
+        ts.isIdentifier(propAccess.expression) &&
+        propAccess.expression.text === 'workflow');
+}
+/**
+ * Check if an expression is Promise.all(array.map(...))
+ */
+export function isParallelFanout(node) {
+    // Promise.all(...)
+    if (!ts.isPropertyAccessExpression(node.expression)) {
+        return false;
+    }
+    const propAccess = node.expression;
+    if (!ts.isIdentifier(propAccess.expression) ||
+        propAccess.expression.text !== 'Promise' ||
+        propAccess.name.text !== 'all') {
+        return false;
+    }
+    // Check if argument is array.map(...)
+    const arg = node.arguments[0];
+    if (!arg || !ts.isCallExpression(arg)) {
+        return false;
+    }
+    if (!ts.isPropertyAccessExpression(arg.expression)) {
+        return false;
+    }
+    return arg.expression.name.text === 'map';
+}
+/**
+ * Check if an expression is Promise.all([...])
+ */
+export function isParallelGroup(node) {
+    // Promise.all(...)
+    if (!ts.isPropertyAccessExpression(node.expression)) {
+        return false;
+    }
+    const propAccess = node.expression;
+    if (!ts.isIdentifier(propAccess.expression) ||
+        propAccess.expression.text !== 'Promise' ||
+        propAccess.name.text !== 'all') {
+        return false;
+    }
+    // Check if argument is an array literal
+    const arg = node.arguments[0];
+    return !!arg && ts.isArrayLiteralExpression(arg);
+}
+/**
+ * Check if a for statement is a valid sequential fanout (for..of)
+ */
+export function isSequentialFanout(node) {
+    // Must have const declaration
+    if (!ts.isVariableDeclarationList(node.initializer)) {
+        return false;
+    }
+    const declList = node.initializer;
+    if (!(declList.flags & ts.NodeFlags.Const)) {
+        return false;
+    }
+    // Must have exactly one declaration
+    if (declList.declarations.length !== 1) {
+        return false;
+    }
+    return true;
+}
+/**
+ * Extract the variable name from a for..of statement
+ */
+export function extractForOfVariable(node) {
+    if (!ts.isVariableDeclarationList(node.initializer)) {
+        return null;
+    }
+    const decl = node.initializer.declarations[0];
+    if (!ts.isIdentifier(decl.name)) {
+        return null;
+    }
+    const itemVar = decl.name.text;
+    // Extract source variable
+    let sourceVar = null;
+    if (ts.isIdentifier(node.expression)) {
+        sourceVar = node.expression.text;
+    }
+    else if (ts.isPropertyAccessExpression(node.expression) &&
+        ts.isIdentifier(node.expression.expression)) {
+        // Handle data.memberEmails
+        sourceVar = node.expression.expression.text;
+    }
+    if (!sourceVar) {
+        return null;
+    }
+    return { itemVar, sourceVar };
+}
+/**
+ * Check if a type is an array type
+ */
+export function isArrayType(type, checker) {
+    // Check if it's an array type
+    if (checker.isArrayType(type)) {
+        return true;
+    }
+    // Check if it's a tuple type
+    if (type.flags & ts.TypeFlags.Object) {
+        const objectType = type;
+        if (objectType.objectFlags & ts.ObjectFlags.Tuple) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Get the source text of a node (for condition expressions)
+ */
+export function getSourceText(node) {
+    return node.getText().trim();
+}

package/dist/workflow/validation.d.ts

@@ -0,0 +1,28 @@
+import * as ts from 'typescript';
+/**
+ * Validation rules for simple workflows
+ */
+export interface ValidationError {
+    message: string;
+    node: ts.Node;
+}
+/**
+ * Check if a node contains only allowed patterns
+ *
+ * Allowed patterns:
+ * - VariableStatement (const/let declarations)
+ * - ExpressionStatement (await workflow.do, await workflow.sleep, await Promise.all)
+ * - IfStatement (branches)
+ * - ForOfStatement (sequential fanout)
+ * - ReturnStatement
+ * - Block (containers)
+ */
+export declare function validateNoDisallowedPatterns(node: ts.Node): ValidationError[];
+/**
+ * Validate that all workflow.do calls are awaited
+ */
+export declare function validateAwaitedCalls(node: ts.Node): ValidationError[];
+/**
+ * Combine all validation errors into a single error message
+ */
+export declare function formatValidationErrors(errors: ValidationError[]): string;

package/dist/workflow/validation.js

@@ -0,0 +1,124 @@
+import * as ts from 'typescript';
+/**
+ * Check if a node contains only allowed patterns
+ *
+ * Allowed patterns:
+ * - VariableStatement (const/let declarations)
+ * - ExpressionStatement (await workflow.do, await workflow.sleep, await Promise.all)
+ * - IfStatement (branches)
+ * - ForOfStatement (sequential fanout)
+ * - ReturnStatement
+ * - Block (containers)
+ */
+export function validateNoDisallowedPatterns(node) {
+    const errors = [];
+    function visitBlock(block) {
+        for (const statement of block.statements) {
+            if (ts.isVariableStatement(statement) ||
+                ts.isExpressionStatement(statement) ||
+                ts.isIfStatement(statement) ||
+                ts.isForOfStatement(statement) ||
+                ts.isReturnStatement(statement)) {
+                // Allowed statement type - recurse into it
+                visitNode(statement);
+            }
+            else {
+                // Unknown/disallowed statement type
+                const nodeType = ts.SyntaxKind[statement.kind];
+                errors.push({
+                    message: `Statement type '${nodeType}' is not allowed in simple workflows. Allowed: const/let, if/else, for..of, return, and workflow calls. If this should be supported, please report the node type: ${nodeType}`,
+                    node: statement,
+                });
+            }
+        }
+    }
+    function visitNode(node) {
+        // Disallow while and do-while
+        if (ts.isWhileStatement(node) || ts.isDoStatement(node)) {
+            errors.push({
+                message: 'while and do-while loops are not allowed in simple workflows',
+                node,
+            });
+            return;
+        }
+        // Disallow for and for-in loops
+        if (ts.isForInStatement(node) || ts.isForStatement(node)) {
+            errors.push({
+                message: 'for and for-in loops are not allowed in simple workflows. Use for-of instead.',
+                node,
+            });
+            return;
+        }
+        // Check for inline workflow.do
+        if (ts.isCallExpression(node)) {
+            if (ts.isPropertyAccessExpression(node.expression)) {
+                const propAccess = node.expression;
+                if (propAccess.name.text === 'do' &&
+                    ts.isIdentifier(propAccess.expression) &&
+                    propAccess.expression.text === 'workflow') {
+                    const secondArg = node.arguments[1];
+                    if (secondArg &&
+                        (ts.isArrowFunction(secondArg) ||
+                            ts.isFunctionExpression(secondArg))) {
+                        errors.push({
+                            message: 'Inline workflow.do with function argument is not allowed in simple workflows. Use RPC form instead.',
+                            node,
+                        });
+                        return;
+                    }
+                }
+            }
+        }
+        // Recurse into blocks
+        if (ts.isBlock(node)) {
+            visitBlock(node);
+        }
+        else {
+            ts.forEachChild(node, visitNode);
+        }
+    }
+    visitNode(node);
+    return errors;
+}
+/**
+ * Validate that all workflow.do calls are awaited
+ */
+export function validateAwaitedCalls(node) {
+    const errors = [];
+    function visit(node, parentIsAwait = false) {
+        if (ts.isCallExpression(node)) {
+            if (ts.isPropertyAccessExpression(node.expression)) {
+                const propAccess = node.expression;
+                if ((propAccess.name.text === 'do' || propAccess.name.text === 'sleep') &&
+                    ts.isIdentifier(propAccess.expression) &&
+                    propAccess.expression.text === 'workflow') {
+                    if (!parentIsAwait) {
+                        errors.push({
+                            message: `workflow.${propAccess.name.text}() must be awaited`,
+                            node,
+                        });
+                    }
+                    return;
+                }
+            }
+        }
+        if (ts.isAwaitExpression(node)) {
+            // Mark child as awaited
+            ts.forEachChild(node.expression, (child) => visit(child, true));
+        }
+        else {
+            ts.forEachChild(node, (child) => visit(child, false));
+        }
+    }
+    visit(node);
+    return errors;
+}
+/**
+ * Combine all validation errors into a single error message
+ */
+export function formatValidationErrors(errors) {
+    if (errors.length === 0) {
+        return '';
+    }
+    return errors.map((err) => `- ${err.message}`).join('\n');
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@pikku/inspector",
-  "version": "0.10.2",
+  "version": "0.11.1",
   "author": "yasser.fadl@gmail.com",
-  "license": "MIT",
+  "license": "BUSL-1.1",
   "type": "module",
   "module": "dist/index.js",
   "main": "dist/index.js",
@@ -16,12 +16,12 @@
     "test:coverage": "bash run-tests.sh --coverage"
   },
   "dependencies": {
-    "@pikku/core": "^0.10.2",
+    "@pikku/core": "^0.11.1",
     "path-to-regexp": "^8.3.0",
     "typescript": "^5.9"
   },
   "devDependencies": {
-    "@types/node": "^24.9.1"
+    "@types/node": "^24.10.1"
   },
   "engines": {
     "node": ">=18"

package/src/add/add-channel.ts

@@ -2,10 +2,9 @@ import * as ts from 'typescript'
 import { ErrorCode } from '../error-codes.js'
 import {
   getPropertyValue,
-  getPropertyTags,
+  getCommonWireMetaData,
 } from '../utils/get-property-value.js'
 import { pathToRegexp } from 'path-to-regexp'
-import { PikkuDocs } from '@pikku/core'
 import { extractFunctionName } from '../utils/extract-function-name.js'
 import { getPropertyAssignmentInitializer } from '../utils/type-utils.js'
 import type { ChannelMessageMeta, ChannelMeta } from '@pikku/core/channel'
@@ -206,7 +205,12 @@ export function addMessagesRoutes(
                     if (fnMeta) {
                       // Resolve middleware for this route
                       const routeTags = ts.isObjectLiteralExpression(init)
-                        ? getPropertyTags(init, 'channel', channelKey, logger)
+                        ? getCommonWireMetaData(
+                            init,
+                            'Channel message',
+                            routeKey,
+                            logger
+                          ).tags
                         : undefined
                       const routeMiddleware = ts.isObjectLiteralExpression(init)
                         ? resolveMiddleware(state, init, routeTags, checker)
@@ -233,7 +237,12 @@ export function addMessagesRoutes(
                   if (fnMeta) {
                     // Resolve middleware for this route
                     const routeTags = ts.isObjectLiteralExpression(init)
-                      ? getPropertyTags(init, 'channel', channelKey, logger)
+                      ? getCommonWireMetaData(
+                          init,
+                          'Channel message',
+                          routeKey,
+                          logger
+                        ).tags
                       : undefined
                     const routeMiddleware = ts.isObjectLiteralExpression(init)
                       ? resolveMiddleware(state, init, routeTags, checker)
@@ -277,12 +286,12 @@ export function addMessagesRoutes(
                         if (fnMeta) {
                           // Resolve middleware for this route
                           const routeTags = ts.isObjectLiteralExpression(init)
-                            ? getPropertyTags(
+                            ? getCommonWireMetaData(
                                 init,
-                                'channel',
-                                channelKey,
+                                'Channel message',
+                                routeKey,
                                 logger
-                              )
+                              ).tags
                             : undefined
                           const routeMiddleware = ts.isObjectLiteralExpression(
                             init
@@ -308,12 +317,12 @@ export function addMessagesRoutes(
                         if (fnMeta) {
                           // Resolve middleware for this route
                           const routeTags = ts.isObjectLiteralExpression(init)
-                            ? getPropertyTags(
+                            ? getCommonWireMetaData(
                                 init,
-                                'channel',
-                                channelKey,
+                                'Channel message',
+                                routeKey,
                                 logger
-                              )
+                              ).tags
                             : undefined
                           const routeMiddleware = ts.isObjectLiteralExpression(
                             init
@@ -396,7 +405,12 @@ export function addMessagesRoutes(
               if (fnMeta) {
                 // Resolve middleware for this route
                 const routeTags = ts.isObjectLiteralExpression(init)
-                  ? getPropertyTags(init, 'channel', channelKey, logger)
+                  ? getCommonWireMetaData(
+                      init,
+                      'Channel message',
+                      routeKey,
+                      logger
+                    ).tags
                   : undefined
                 const routeMiddleware = ts.isObjectLiteralExpression(init)
                   ? resolveMiddleware(state, init, routeTags, checker)
@@ -438,7 +452,7 @@ export function addMessagesRoutes(
       // Resolve middleware and permissions for this route
       // Check if the route config is an object literal with middleware/permissions
       const routeTags = ts.isObjectLiteralExpression(init)
-        ? getPropertyTags(init, 'channel', channelKey, logger)
+        ? getCommonWireMetaData(init, 'Channel message', routeKey, logger).tags
         : undefined
       const routeMiddleware = ts.isObjectLiteralExpression(init)
         ? resolveMiddleware(state, init, routeTags, checker)
@@ -487,8 +501,12 @@ export const addChannel: AddWiring = (
         .map((k) => k.name)
     : []
 
-  const docs = getPropertyValue(obj, 'docs') as PikkuDocs | undefined
-  const tags = getPropertyTags(obj, 'Channel', route, logger)
+  const { tags, summary, description, errors } = getCommonWireMetaData(
+    obj,
+    'Channel',
+    name,
+    logger
+  )
   const query = getPropertyValue(obj, 'query') as string[] | []
 
   const connect = getPropertyAssignmentInitializer(
@@ -602,7 +620,9 @@ export const addChannel: AddWiring = (
       : null,
     message,
     messageWirings,
-    docs: docs ?? undefined,
+    summary,
+    description,
+    errors,
     tags: tags ?? undefined,
     middleware,
   }

package/src/add/add-file-with-factory.ts

@@ -6,7 +6,7 @@ import { extractServicesFromFunction } from '../utils/extract-services.js'
 const wrapperFunctionMap: Record<string, string> = {
   pikkuConfig: 'CreateConfig',
   pikkuServices: 'CreateSingletonServices',
-  pikkuSessionServices: 'CreateSessionServices',
+  pikkuWireServices: 'CreateWireServices',
 }
 
 export const addFileWithFactory = (
@@ -54,9 +54,9 @@ export const addFileWithFactory = (
           })
           methods.set(fileName, variables)
 
-          // Extract singleton services for CreateSessionServices factories
+          // Extract singleton services for CreateWireServices factories
           if (
-            expectedTypeName === 'CreateSessionServices' &&
+            expectedTypeName === 'CreateWireServices' &&
             state &&
             callExpression.arguments.length > 0
           ) {
@@ -74,7 +74,7 @@ export const addFileWithFactory = (
 
             if (functionNode) {
               const servicesMeta = extractServicesFromFunction(functionNode)
-              state.sessionServicesMeta.set(variableName, servicesMeta.services)
+              state.wireServicesMeta.set(variableName, servicesMeta.services)
             }
           }
 
@@ -109,9 +109,9 @@ export const addFileWithFactory = (
         })
         methods.set(fileName, variables)
 
-        // Extract singleton services for CreateSessionServices factories
+        // Extract singleton services for CreateWireServices factories
         if (
-          expectedTypeName === 'CreateSessionServices' &&
+          expectedTypeName === 'CreateWireServices' &&
           state &&
           node.initializer
         ) {
@@ -124,7 +124,7 @@ export const addFileWithFactory = (
 
           if (functionNode) {
             const servicesMeta = extractServicesFromFunction(functionNode)
-            state.sessionServicesMeta.set(variableName, servicesMeta.services)
+            state.wireServicesMeta.set(variableName, servicesMeta.services)
           }
         }
       }
@@ -149,9 +149,9 @@ export const addFileWithFactory = (
           })
           methods.set(fileName, variables)
 
-          // Extract singleton services for CreateSessionServices factories
+          // Extract singleton services for CreateWireServices factories
           if (
-            expectedTypeName === 'CreateSessionServices' &&
+            expectedTypeName === 'CreateWireServices' &&
             state &&
             node.initializer
           ) {
@@ -167,7 +167,7 @@ export const addFileWithFactory = (
 
             if (functionNode) {
               const servicesMeta = extractServicesFromFunction(functionNode)
-              state.sessionServicesMeta.set(variableName, servicesMeta.services)
+              state.wireServicesMeta.set(variableName, servicesMeta.services)
             }
           }
         }