@output.ai/core 0.2.2 → 0.3.0-dev.pr263-a59dd0e

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

@@ -1,7 +1,7 @@
 import traverseModule from '@babel/traverse';
 import { dirname } from 'node:path';
-import { parse, toAbsolutePath, getFileKind } from '../tools.js';
-import { ComponentFile, CoreModule, EXTRANEOUS_FILE, ExtraneousFileList } from '../consts.js';
+import { parse, toAbsolutePath, getFileKind, isAnyStepsPath, isEvaluatorsPath, isWorkflowPath } from '../tools.js';
+import { ComponentFile, CoreModule } from '../consts.js';
 import {
   isCallExpression,
   isFunctionExpression,
@@ -18,36 +18,92 @@ import {
 const traverse = traverseModule.default ?? traverseModule;
 
 /**
- * Check if workflow dependencies
+ * 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 ( isEvaluatorsPath( filename ) ) {
+    return 'evaluators.js';
+  }
+  if ( /workflow\.js$/.test( filename ) ) {
+    return 'workflow.js';
+  }
+  return filename;
+};
+
+/**
+ * Check if workflow dependencies are valid.
+ * Workflows can import:
+ * - Components (steps, evaluators, workflow)
+ * - Core modules (@output.ai/core, local_core)
+ * - ANY file that is NOT a component file (flexible utility imports)
  */
 const validateWorkflowImports = ( { specifier, filename } ) => {
   const isCore = Object.values( CoreModule ).includes( specifier );
-  const isComponent = Object.values( ComponentFile ).includes( getFileKind( specifier ) );
-  const isAllowedExtraneous = getFileKind( specifier ) === EXTRANEOUS_FILE;
-  if ( !isCore && !isComponent && !isAllowedExtraneous ) {
+  const fileKind = getFileKind( specifier );
+  const isComponent = Object.values( ComponentFile ).includes( fileKind );
+  const isNonComponentFile = fileKind === null;
+
+  if ( !isCore && !isComponent && !isNonComponentFile ) {
     throw new Error( `Invalid dependency in workflow.js: '${specifier}'. \
-Only components (${Object.values( ComponentFile ) } ), @output.ai/core, or whitelisted (${ExtraneousFileList}) imports are allowed in ${filename}` );
+Only components (${Object.values( ComponentFile ) } ), @output.ai/core, or non-component files are allowed in ${filename}` );
   }
 };
 
 /**
- * Check if evaluators, steps or shared_steps import invalid dependencies
+ * Check if evaluators or steps import invalid dependencies.
+ * Steps and evaluators CANNOT import:
+ * - Other steps (local or shared) - activity isolation
+ * - Other evaluators (local or shared) - activity isolation
+ * - Workflows
+ *
+ * Steps and evaluators CAN import:
+ * - ANY file that is NOT a component file (flexible utility imports)
  */
-const validateStepEvaluatorImports = ( { fileKind, specifier, filename } ) => {
-  if ( Object.values( ComponentFile ).includes( getFileKind( specifier ) ) ) {
-    throw new Error( `Invalid dependency in ${fileKind}.js: '${specifier}'. \
-Steps, shared_steps, evaluators or workflows are not allowed dependencies in ${filename}` );
+const validateStepEvaluatorImports = ( { specifier, filename } ) => {
+  const importedFileKind = getFileKind( specifier );
+
+  // Activity isolation: steps/evaluators cannot import other steps, evaluators, or workflows
+  if ( Object.values( ComponentFile ).includes( importedFileKind ) ) {
+    const fileLabel = getFileKindLabel( filename );
+    throw new Error( `Invalid dependency in ${fileLabel}: '${specifier}'. \
+Steps, evaluators or workflows are not allowed dependencies in ${filename}` );
   }
 };
 
 /**
- * Validate import for evaluators, steps, shared_steps, workflow
+ * Validate import for evaluators, steps, workflow
  */
 const executeImportValidations = ( { fileKind, specifier, filename } ) => {
   if ( fileKind === ComponentFile.WORKFLOW ) {
-    validateWorkflowImports( { fileKind, specifier, filename } );
+    validateWorkflowImports( { specifier, filename } );
   } else if ( Object.values( ComponentFile ).includes( fileKind ) ) {
-    validateStepEvaluatorImports( { fileKind, specifier, filename } );
+    validateStepEvaluatorImports( { specifier, 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' && !isEvaluatorsPath( 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}` );
   }
 };
 
@@ -56,13 +112,13 @@ const executeImportValidations = ( { fileKind, specifier, filename } ) => {
  * Returns the source unchanged unless a validation error is found.
  *
  * Rules enforced:
- *  - evaluators.js `fn`: at each evaluator().fn body: calling any evaluator, step, shared_step or workflow is forbidden
- *  - evaluators.js: may not import evaluators.js, steps.js/shared_steps.js, workflow.js
- *  - shared_steps.js `fn`: at each step().fn body: calling any evaluator, step, shared_step or workflow is forbidden
- *  - shared_steps.js: may not import evaluators.js, steps.js, shared_steps.js, workflow.js
- *  - steps.js: at each step().fn body: calling any evaluator, step, shared_step or workflow is forbidden
- *  - steps.js: may not import evaluators.js, steps.js, shared_steps.js, workflow.js
- *  - workflow.js: may only import components: evaluators.js, steps.js, shared_steps.js, workflow.js; and files: types.js or `@output.ai/core`
+ *  - Instantiation location: step() must be in steps path, evaluator() in evaluators path, workflow() in workflow path
+ *  - evaluators.js `fn`: at each evaluator().fn body: calling any evaluator, step, or workflow is forbidden
+ *  - evaluators.js: may not import evaluators.js, steps.js, workflow.js, or any shared steps/evaluators
+ *  - steps.js: at each step().fn body: calling any evaluator, step, or workflow is forbidden
+ *  - steps.js: may not import evaluators.js, steps.js, workflow.js, or any shared steps/evaluators
+ *  - workflow.js: may import components (evaluators.js, steps.js, workflow.js including shared);
+ *                 and any non-component file, or `@output.ai/core`
  *
  * @param {string|Buffer} source
  * @param {any} inputMap
@@ -82,7 +138,7 @@ export default function workflowValidatorLoader( source, inputMap ) {
     // Collect local declarations and imported identifiers by type
     const localStepIds = new Set();
     const localEvaluatorIds = new Set();
-    const importedStepIds = new Set(); // includes shared_steps
+    const importedStepIds = new Set();
     const importedEvaluatorIds = new Set();
     const importedWorkflowIds = new Set();
 
@@ -94,12 +150,12 @@ export default function workflowValidatorLoader( source, inputMap ) {
         executeImportValidations( { fileKind, specifier, filename } );
 
         // Collect imported identifiers for later call checks
+        const importedKind = getFileKind( specifier );
         const accumulator = ( {
           [ComponentFile.STEPS]: importedStepIds,
-          [ComponentFile.SHARED_STEPS]: importedStepIds,
           [ComponentFile.EVALUATORS]: importedEvaluatorIds,
           [ComponentFile.WORKFLOW]: importedWorkflowIds
-        } )[fileKind];
+        } )[importedKind];
         if ( accumulator ) {
           for ( const s of path.node.specifiers ) {
             if ( isImportSpecifier( s ) || isImportDefaultSpecifier( s ) ) {
@@ -114,12 +170,21 @@ export default function workflowValidatorLoader( source, inputMap ) {
           return;
         }
 
-        // Collect local step/evaluator declarations: const X = step({...}) / evaluator({...})
-        if ( isIdentifier( init.callee, { name: 'step' } ) && isIdentifier( path.node.id ) ) {
-          localStepIds.add( path.node.id.name );
+        // 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: 'evaluator' } ) && isIdentifier( path.node.id ) ) {
-          localEvaluatorIds.add( path.node.id.name );
+        if ( isIdentifier( init.callee, { name: 'workflow' } ) ) {
+          validateInstantiationLocation( 'workflow', filename );
         }
 
         // CommonJS requires: validate source and collect identifiers
@@ -134,7 +199,7 @@ export default function workflowValidatorLoader( source, inputMap ) {
           // Collect imported identifiers from require patterns
           if ( isStringLiteral( firstArg ) ) {
             const reqType = getFileKind( toAbsolutePath( fileDir, req ) );
-            if ( [ ComponentFile.STEPS, ComponentFile.SHARED_STEPS ].includes( reqType ) && isObjectPattern( path.node.id ) ) {
+            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 );
@@ -157,7 +222,7 @@ export default function workflowValidatorLoader( source, inputMap ) {
     } );
 
     // Function-body call validations for steps/evaluators files
-    if ( [ ComponentFile.STEPS, ComponentFile.SHARED_STEPS, ComponentFile.EVALUATORS ].includes( fileKind ) ) {
+    if ( [ ComponentFile.STEPS, ComponentFile.EVALUATORS ].includes( fileKind ) ) {
       traverse( ast, {
         ObjectProperty: path => {
           if ( !isIdentifier( path.node.key, { name: 'fn' } ) ) {
@@ -173,6 +238,7 @@ export default function workflowValidatorLoader( source, inputMap ) {
               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 ) ],
@@ -180,7 +246,7 @@ export default function workflowValidatorLoader( source, inputMap ) {
                 ].find( v => v[1] )?.[0];
 
                 if ( violation ) {
-                  throw new Error( `Invalid call in ${fileKind}.js fn: calling a ${violation} ('${name}') is not allowed in ${filename}` );
+                  throw new Error( `Invalid call in ${fileLabel} fn: calling a ${violation} ('${name}') is not allowed in ${filename}` );
                 }
               }
             }