@outputai/core 0.1.0

package/src/worker/webpack_loaders/workflow_rewriter/rewrite_fn_bodies.js

@@ -0,0 +1,196 @@
+import traverseModule from '@babel/traverse';
+import { isArrowFunctionExpression, isIdentifier } from '@babel/types';
+import {
+  toFunctionExpression,
+  createThisMethodCall,
+  isFunction,
+  bindThisAtCallSite,
+  isFunctionLikeBinding
+} from '../tools.js';
+
+// Handle CJS/ESM interop for Babel packages when executed as a webpack loader
+const traverse = traverseModule.default ?? traverseModule;
+
+/**
+ * Check whether a CallExpression callee is a simple Identifier.
+ * Only direct identifier calls are rewritten; member/dynamic calls are skipped.
+ *
+ * We only support rewriting `Foo()` calls that refer to imported steps/flows/evaluators
+ * or local call-chain functions. Calls like `obj.Foo()` or `(getFn())()` are out of scope.
+ *
+ * Examples:
+ * - Supported: `Foo()`
+ * - Skipped:   `obj.Foo()`, `(getFn())()`
+ *
+ * @param {import('@babel/traverse').NodePath} cPath - Path to a CallExpression node.
+ * @returns {boolean} True when callee is an Identifier.
+ */
+const isIdentifierCallee = cPath => isIdentifier( cPath.node.callee );
+
+/**
+ * Convert an ArrowFunctionExpression at the given path into a FunctionExpression
+ * to ensure dynamic `this` semantics inside the function body.
+ *
+ * Workflow code relies on `this` to invoke steps/flows (e.g., `this.invokeStep(...)`).
+ * Arrow functions capture `this` lexically, which would break that contract.
+ *
+ * If the node is an arrow, it is replaced by an equivalent FunctionExpression and
+ * the `state.rewrote` flag is set. If not an arrow, this is a no-op.
+ *
+ * @param {import('@babel/traverse').NodePath} nodePath - Path to a function node.
+ * @param {{ rewrote: boolean }} state - Mutation target to indicate a rewrite occurred.
+ * @returns {void}
+ */
+const normalizeArrowToFunctionPath = ( nodePath, state ) => {
+  if ( isArrowFunctionExpression( nodePath.node ) ) {
+    nodePath.replaceWith( toFunctionExpression( nodePath.node ) );
+    state.rewrote = true;
+  }
+};
+/**
+ * Rewrite calls inside a function body and collect call-chain functions discovered within.
+ * - Imported calls (steps/shared/evaluators/flows) are rewritten to `this.invokeX` or `this.startWorkflow`.
+ * - Local call-chain function calls are rewritten to `fn.call(this, ...)` to bind `this` correctly.
+ * - Returns a map of call-chain function name -> binding path for further recursive processing.
+ *
+ * @param {import('@babel/traverse').NodePath} bodyPath - Path to a function's body node.
+ * @param {Array<{ list: Array<any>, method: string, key: string }>} descriptors - Import rewrite descriptors.
+ * @param {{ rewrote: boolean }} state - Mutable state used to flag that edits were performed.
+ * @returns {Map<string, import('@babel/traverse').NodePath>} Discovered call-chain function bindings.
+ */
+const rewriteCallsInBody = ( bodyPath, descriptors, state ) => {
+  const callChainFunctions = new Map();
+  bodyPath.traverse( {
+    CallExpression: cPath => {
+      if ( !isIdentifierCallee( cPath ) ) {
+        return; // Only identifier callees are supported (skip member/dynamic)
+      }
+      const callee = cPath.node.callee;
+
+      // Rewrite imported calls (steps/shared/evaluators/flows)
+      for ( const { list, method, key } of descriptors ) {
+        const found = list.find( x => x.localName === callee.name );
+        if ( found ) {
+          const args = cPath.node.arguments;
+          cPath.replaceWith( createThisMethodCall( method, found[key], args ) );
+          state.rewrote = true;
+          return;
+        }
+      }
+
+      // Rewrite local call-chain function calls and track for recursive processing
+      const binding = cPath.scope.getBinding( callee.name );
+      if ( !binding ) {
+        return;
+      }
+      if ( !isFunctionLikeBinding( binding.path.node ) ) {
+        return; // Not a function-like binding
+      }
+
+      // Queue call-chain function for recursive processing
+      if ( !callChainFunctions.has( callee.name ) ) {
+        callChainFunctions.set( callee.name, binding.path );
+      }
+
+      // Bind `this` at callsite: fn(...) -> fn.call(this, ...)
+      cPath.replaceWith( bindThisAtCallSite( callee.name, cPath.node.arguments ) );
+      state.rewrote = true;
+    }
+  } );
+  return callChainFunctions;
+};
+
+/**
+ * Recursively process a call-chain function:
+ * - Ensures the function is a FunctionExpression (converts arrow when needed).
+ * - Rewrites calls inside the function using `rewriteCallsInBody`.
+ * - Follows nested call-chain functions depth-first while avoiding cycles via `processedFns`.
+ *
+ * @param {object} params - Params for processing a call-chain function.
+ * @param {string} params.name - Local identifier name in the current scope.
+ * @param {import('@babel/traverse').NodePath} params.bindingPath - Binding path of the function declaration.
+ * @param {{ rewrote: boolean }} params.state - Mutable state used to flag that edits were performed.
+ * @param {Array<{ list: Array<any>, method: string, key: string }>} params.descriptors - Import rewrite descriptors.
+ * @param {Set<string>} [params.processedFns] - Already processed names to avoid cycles.
+ */
+const processFunction = ( { name, bindingPath, state, descriptors, processedFns = new Set() } ) => {
+  // Avoid infinite loops for recursive/repeated references
+  if ( processedFns.has( name ) || bindingPath.removed ) {
+    return;
+  }
+  processedFns.add( name );
+
+  if ( bindingPath.isVariableDeclarator() ) {
+    // Case 1: const foo = <function or arrow>
+    const initPath = bindingPath.get( 'init' );
+    // Arrow functions capture `this` lexically; normalize for dynamic `this`
+    normalizeArrowToFunctionPath( initPath, state );
+    // Rewrite calls in body; collect nested call-chain functions from this scope
+    const callChainFunctions = rewriteCallsInBody( initPath.get( 'body' ), descriptors, state );
+    // DFS: process nested call-chain functions (processedFns prevents cycles)
+    callChainFunctions.forEach( ( childBindingPath, childName ) => {
+      processFunction( { name: childName, bindingPath: childBindingPath, state, descriptors, processedFns } );
+    } );
+  } else if ( bindingPath.isFunctionDeclaration() ) {
+    // Case 2: function foo(...) { ... }
+    // Function declarations already have dynamic `this`; no normalization needed
+    const callChainFunctions = rewriteCallsInBody( bindingPath.get( 'body' ), descriptors, state );
+    // Continue DFS into any functions called from this declaration
+    callChainFunctions.forEach( ( childBindingPath, childName ) => {
+      processFunction( { name: childName, bindingPath: childBindingPath, state, descriptors, processedFns } );
+    } );
+  }
+};
+
+/**
+ * Rewrite calls to imported steps/workflows within `fn` object properties.
+ * Converts arrow fns to functions and replaces `StepX(...)` with
+ * `this.invokeStep('name', ...)` and `FlowY(...)` with
+ * `this.startWorkflow('name', ...)`.
+ *
+ * @param {object} params
+ * @param {import('@babel/types').File} params.ast - Parsed file AST.
+ * @param {Array<{localName:string,stepName:string}>} params.stepImports - Step imports.
+ * @param {Array<{localName:string,stepName:string}>} params.sharedStepImports - Shared step imports.
+ * @param {Array<{localName:string,evaluatorName:string}>} params.evaluatorImports - Evaluator imports.
+ * @param {Array<{localName:string,workflowName:string}>} params.flowImports - Workflow imports.
+ * @returns {boolean} True if the AST was modified; false otherwise.
+ */
+export default function rewriteFnBodies( { ast, stepImports, sharedStepImports = [], evaluatorImports, sharedEvaluatorImports = [], flowImports } ) {
+  const state = { rewrote: false };
+  // Build rewrite descriptors once per traversal
+  const descriptors = [
+    { list: stepImports, method: 'invokeStep', key: 'stepName' },
+    { list: sharedStepImports, method: 'invokeSharedStep', key: 'stepName' },
+    { list: evaluatorImports, method: 'invokeEvaluator', key: 'evaluatorName' },
+    { list: sharedEvaluatorImports, method: 'invokeSharedEvaluator', key: 'evaluatorName' },
+    { list: flowImports, method: 'startWorkflow', key: 'workflowName' }
+  ];
+  traverse( ast, {
+    ObjectProperty: path => {
+      // Only transform object properties named 'fn'
+      if ( !isIdentifier( path.node.key, { name: 'fn' } ) ) {
+        return;
+      }
+
+      const val = path.node.value;
+
+      // Only functions (including arrows) are eligible
+      if ( !isFunction( val ) && !isArrowFunctionExpression( val ) ) {
+        return;
+      }
+
+      // Normalize arrow to function for correct dynamic `this`
+      normalizeArrowToFunctionPath( path.get( 'value' ), state );
+
+      // Rewrite the main workflow fn body and collect call-chain functions discovered within it
+      const callChainFunctions = rewriteCallsInBody( path.get( 'value.body' ), descriptors, state );
+
+      // Recursively rewrite call-chain functions and any functions they call
+      callChainFunctions.forEach( ( bindingPath, name ) => {
+        processFunction( { name, bindingPath, state, descriptors } );
+      } );
+    }
+  } );
+  return state.rewrote;
+};

package/src/worker/webpack_loaders/workflow_rewriter/rewrite_fn_bodies.spec.js

@@ -0,0 +1,123 @@
+import { describe, it, expect } from 'vitest';
+import generatorModule from '@babel/generator';
+import { parse } from '../tools.js';
+import rewriteFnBodies from './rewrite_fn_bodies.js';
+
+const generate = generatorModule.default ?? generatorModule;
+
+describe( 'rewrite_fn_bodies', () => {
+  it( 'converts arrow to function and rewrites step/workflow calls', () => {
+    const src = `
+const obj = {
+  fn: async x => {
+    StepA( 1 );
+    FlowB( 2 );
+  }
+}`;
+    const ast = parse( src, 'file.js' );
+    const stepImports = [ { localName: 'StepA', stepName: 'step.a' } ];
+    const flowImports = [ { localName: 'FlowB', workflowName: 'flow.b' } ];
+
+    const rewrote = rewriteFnBodies( { ast, stepImports, evaluatorImports: [], flowImports } );
+    expect( rewrote ).toBe( true );
+
+    const code = ast.program.body.map( n => n.type ).length; // smoke: ast mutated
+    expect( code ).toBeGreaterThan( 0 );
+  } );
+
+  it( 'rewrites evaluator calls to this.invokeEvaluator', () => {
+    const src = `
+const obj = {
+  fn: async x => {
+    EvalA(3);
+  }
+};`;
+    const ast = parse( src, 'file.js' );
+    const evaluatorImports = [ { localName: 'EvalA', evaluatorName: 'eval.a' } ];
+    const rewrote = rewriteFnBodies( { ast, stepImports: [], evaluatorImports, flowImports: [] } );
+    expect( rewrote ).toBe( true );
+  } );
+
+  it( 'does nothing when no matching calls are present', () => {
+    const src = [ 'const obj = { fn: function() { other(); } }' ].join( '\n' );
+    const ast = parse( src, 'file.js' );
+    const rewrote = rewriteFnBodies( { ast, stepImports: [], evaluatorImports: [], flowImports: [] } );
+    expect( rewrote ).toBe( false );
+  } );
+
+  it( 'rewrites helper calls and helper bodies (steps and evaluators)', () => {
+    const src = `
+const foo = async () => {
+  StepA( 1 );
+};
+
+function bar( x ) {
+  EvalA( x );
+}
+
+const obj = {
+  fn: async x => {
+    foo();
+    bar( 2 );
+  }
+}`;
+
+    const ast = parse( src, 'file.js' );
+    const stepImports = [ { localName: 'StepA', stepName: 'step.a' } ];
+    const evaluatorImports = [ { localName: 'EvalA', evaluatorName: 'eval.a' } ];
+
+    const rewrote = rewriteFnBodies( { ast, stepImports, sharedStepImports: [], evaluatorImports, flowImports: [] } );
+    expect( rewrote ).toBe( true );
+
+    const { code } = generate( ast, { quotes: 'single' } );
+
+    // Helper calls in fn are rewritten to call(this, ...)
+    expect( code ).toMatch( /foo\.call\(this\)/ );
+    expect( code ).toMatch( /bar\.call\(this,\s*2\)/ );
+
+    // Inside helpers, calls are rewritten
+    expect( code ).toMatch( /this\.invokeStep\(([\"'])step\.a\1,\s*1\)/ );
+    expect( code ).toMatch( /this\.invokeEvaluator\(([\"'])eval\.a\1,\s*x\)/ );
+
+    // Arrow helper converted to function expression to allow dynamic this
+    expect( code ).toMatch( /const foo = async function/ );
+  } );
+
+  it( 'rewrites nested helper chains until the step invocation', () => {
+    const src = `
+const foo = () => {
+  bar();
+};
+
+function bar() {
+  baz( 42 );
+}
+
+const baz = n => {
+  StepA( n );
+};
+
+const obj = {
+  fn: async () => {
+    foo();
+  }
+}`;
+
+    const ast = parse( src, 'file.js' );
+    const stepImports = [ { localName: 'StepA', stepName: 'step.a' } ];
+    const rewrote = rewriteFnBodies( { ast, stepImports, evaluatorImports: [], flowImports: [] } );
+    expect( rewrote ).toBe( true );
+
+    const { code } = generate( ast, { quotes: 'single' } );
+    // Calls along the chain are bound with this
+    expect( code ).toMatch( /foo\.call\(this\)/ );
+    expect( code ).toMatch( /bar\.call\(this\)/ );
+    expect( code ).toMatch( /baz\.call\(this,\s*42\)/ );
+    // Deep step rewrite in the last helper
+    expect( code ).toMatch( /this\.invokeStep\(([\"'])step\.a\1,\s*n\)/ );
+    // Arrow helpers converted to functions
+    expect( code ).toMatch( /const foo = function/ );
+    expect( code ).toMatch( /const baz = function/ );
+  } );
+} );
+

package/src/worker/webpack_loaders/workflow_validator/index.mjs

@@ -0,0 +1,205 @@
+import traverseModule from '@babel/traverse';
+import { dirname } from 'node:path';
+import { parse, toAbsolutePath, getFileKind, isAnyStepsPath, isAnyEvaluatorsPath, isWorkflowPath } from '../tools.js';
+import { ComponentFile } from '../consts.js';
+import {
+  isCallExpression,
+  isFunctionExpression,
+  isArrowFunctionExpression,
+  isIdentifier,
+  isImportDefaultSpecifier,
+  isImportSpecifier,
+  isObjectPattern,
+  isObjectProperty,
+  isStringLiteral
+} from '@babel/types';
+
+// Handle CJS/ESM interop for Babel packages when executed as a webpack loader
+const traverse = traverseModule.default ?? traverseModule;
+
+/**
+ * Determine the file kind label for error messages.
+ * Handles both flat files (steps.js) and folder-based files (steps/fetch_data.js).
+ * @param {string} filename - The file path
+ * @returns {string} Human-readable file kind for error messages
+ */
+const getFileKindLabel = filename => {
+  if ( isAnyStepsPath( filename ) ) {
+    return 'steps.js';
+  }
+  if ( isAnyEvaluatorsPath( filename ) ) {
+    return 'evaluators.js';
+  }
+  if ( /workflow\.js$/.test( filename ) ) {
+    return 'workflow.js';
+  }
+  return filename;
+};
+
+/**
+ * Validate that component instantiation calls occur in the correct file locations.
+ * - step() must be called in a file whose path contains 'steps'
+ * - evaluator() must be called in a file whose path contains 'evaluators'
+ * - workflow() must be called in a file whose path contains 'workflow'
+ * @param {string} calleeName - The factory function name (step, evaluator, workflow)
+ * @param {string} filename - The file path where the call occurs
+ */
+const validateInstantiationLocation = ( calleeName, filename ) => {
+  if ( calleeName === 'step' && !isAnyStepsPath( filename ) ) {
+    throw new Error( `Invalid instantiation location: step() can only be called in files with 'steps' in the path. Found in: ${filename}` );
+  }
+  if ( calleeName === 'evaluator' && !isAnyEvaluatorsPath( filename ) ) {
+    throw new Error( `Invalid instantiation location: evaluator() can only be called in files with 'evaluators' in the path. Found in: ${filename}` );
+  }
+  if ( calleeName === 'workflow' && !isWorkflowPath( filename ) ) {
+    throw new Error( `Invalid instantiation location: workflow() can only be called in files with 'workflow' in the path. Found in: ${filename}` );
+  }
+};
+
+/**
+ * Webpack loader that validates component instantiation and fn body calls.
+ * Returns the source unchanged unless a validation error is found.
+ *
+ * Rules enforced:
+ *  - Instantiation location: step() must be in steps path, evaluator() in evaluators path, workflow() in workflow path
+ *  - steps.js `fn`: calling any step, evaluator, or workflow inside fn body emits warning
+ *  - evaluators.js `fn`: calling any step, evaluator, or workflow inside fn body emits warning
+ *
+ * NOTE: Import restrictions have been removed - any file can import any other file.
+ *
+ * @param {string|Buffer} source
+ * @param {any} inputMap
+ * @this {import('webpack').LoaderContext<{}>}
+ */
+export default function workflowValidatorLoader( source, inputMap ) {
+  this.cacheable?.( true );
+  const callback = this.async?.() ?? this.callback;
+  const emitWarning = this.emitWarning?.bind( this ) ?? ( () => {} );
+
+  try {
+    const filename = this.resourcePath;
+    const fileDir = dirname( filename );
+    const ast = parse( String( source ), filename );
+
+    const fileKind = getFileKind( filename );
+
+    // Collect local declarations and imported identifiers by type
+    const localStepIds = new Set();
+    const localEvaluatorIds = new Set();
+    const importedStepIds = new Set();
+    const importedEvaluatorIds = new Set();
+    const importedWorkflowIds = new Set();
+
+    // First pass: collect imported identifiers for fn body call checks
+    traverse( ast, {
+      ImportDeclaration: path => {
+        const specifier = path.node.source.value;
+
+        // Collect imported identifiers for later call checks
+        const importedKind = getFileKind( specifier );
+        const accumulator = ( {
+          [ComponentFile.STEPS]: importedStepIds,
+          [ComponentFile.EVALUATORS]: importedEvaluatorIds,
+          [ComponentFile.WORKFLOW]: importedWorkflowIds
+        } )[importedKind];
+        if ( accumulator ) {
+          for ( const s of path.node.specifiers ) {
+            if ( isImportSpecifier( s ) || isImportDefaultSpecifier( s ) ) {
+              accumulator.add( s.local.name );
+            }
+          }
+        }
+      },
+      VariableDeclarator: path => {
+        const init = path.node.init;
+        if ( !isCallExpression( init ) ) {
+          return;
+        }
+
+        // Validate instantiation location for step/evaluator/workflow calls
+        if ( isIdentifier( init.callee, { name: 'step' } ) ) {
+          validateInstantiationLocation( 'step', filename );
+          if ( isIdentifier( path.node.id ) ) {
+            localStepIds.add( path.node.id.name );
+          }
+        }
+        if ( isIdentifier( init.callee, { name: 'evaluator' } ) ) {
+          validateInstantiationLocation( 'evaluator', filename );
+          if ( isIdentifier( path.node.id ) ) {
+            localEvaluatorIds.add( path.node.id.name );
+          }
+        }
+        if ( isIdentifier( init.callee, { name: 'workflow' } ) ) {
+          validateInstantiationLocation( 'workflow', filename );
+        }
+
+        // CommonJS requires: collect identifiers for fn body call checks
+        if ( isIdentifier( init.callee, { name: 'require' } ) ) {
+          const firstArg = init.arguments[0];
+          if ( !isStringLiteral( firstArg ) ) {
+            return;
+          }
+          const req = firstArg.value;
+
+          // Collect imported identifiers from require patterns
+          const reqType = getFileKind( toAbsolutePath( fileDir, req ) );
+          if ( reqType === ComponentFile.STEPS && isObjectPattern( path.node.id ) ) {
+            for ( const prop of path.node.id.properties ) {
+              if ( isObjectProperty( prop ) && isIdentifier( prop.value ) ) {
+                importedStepIds.add( prop.value.name );
+              }
+            }
+          }
+          if ( reqType === ComponentFile.EVALUATORS && isObjectPattern( path.node.id ) ) {
+            for ( const prop of path.node.id.properties ) {
+              if ( isObjectProperty( prop ) && isIdentifier( prop.value ) ) {
+                importedEvaluatorIds.add( prop.value.name );
+              }
+            }
+          }
+          if ( reqType === ComponentFile.WORKFLOW && isIdentifier( path.node.id ) ) {
+            importedWorkflowIds.add( path.node.id.name );
+          }
+        }
+      }
+    } );
+
+    // Function-body call validations for steps/evaluators files
+    if ( [ ComponentFile.STEPS, ComponentFile.EVALUATORS ].includes( fileKind ) ) {
+      traverse( ast, {
+        ObjectProperty: path => {
+          if ( !isIdentifier( path.node.key, { name: 'fn' } ) ) {
+            return;
+          }
+          const val = path.node.value;
+          if ( !isFunctionExpression( val ) && !isArrowFunctionExpression( val ) ) {
+            return;
+          }
+
+          path.get( 'value' ).traverse( {
+            CallExpression: cPath => {
+              const callee = cPath.node.callee;
+              if ( isIdentifier( callee ) ) {
+                const { name } = callee;
+                const fileLabel = getFileKindLabel( filename );
+                const violation = [
+                  [ 'step', localStepIds.has( name ) || importedStepIds.has( name ) ],
+                  [ 'evaluator', localEvaluatorIds.has( name ) || importedEvaluatorIds.has( name ) ],
+                  [ 'workflow', importedWorkflowIds.has( name ) ]
+                ].find( v => v[1] )?.[0];
+
+                if ( violation ) {
+                  emitWarning( new Error( `Invalid call in ${fileLabel} fn: calling a ${violation} ('${name}') is not allowed in ${filename}` ) );
+                }
+              }
+            }
+          } );
+        }
+      } );
+    }
+
+    return callback( null, source, inputMap );
+  } catch ( err ) {
+    return callback( err );
+  }
+}