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

package/src/worker/webpack_loaders/tools.js

@@ -24,7 +24,15 @@ import {
   isExportDefaultDeclaration,
   isFunctionDeclaration
 } from '@babel/types';
-import { ComponentFile, EXTRANEOUS_FILE, ExtraneousFileList, NodeType } from './consts.js';
+import { ComponentFile, NodeType } from './consts.js';
+
+// Path pattern regexes - shared across multiple helper functions
+const STEPS_FILE_REGEX = /(^|\/)steps\.js$/;
+const STEPS_FOLDER_REGEX = /\/steps\/[^/]+\.js$/;
+const EVALUATORS_FILE_REGEX = /(^|\/)evaluators\.js$/;
+const EVALUATORS_FOLDER_REGEX = /\/evaluators\/[^/]+\.js$/;
+const PATH_TRAVERSAL_REGEX = /\.\.\//;
+const SHARED_PATH_REGEX = /\/shared\//;
 
 /**
  * Resolve a relative module specifier against a base directory.
@@ -104,25 +112,67 @@ export const toFunctionExpression = arrow => {
 };
 
 /**
- * Check if a module specifier or request string points to steps.js.
+ * Check if a module specifier or request string points to steps.js or is in a steps folder.
+ * Matches: steps.js, /steps.js, /steps/*.js
+ * This matches LOCAL steps only (no path traversal).
+ * @param {string} value - Module path or request string.
+ * @returns {boolean} True if it matches a local steps path.
+ */
+export const isStepsPath = value => {
+  // Exclude shared steps (paths with ../ or containing /shared/)
+  if ( PATH_TRAVERSAL_REGEX.test( value ) || SHARED_PATH_REGEX.test( value ) ) {
+    return false;
+  }
+  return STEPS_FILE_REGEX.test( value ) || STEPS_FOLDER_REGEX.test( value );
+};
+
+/**
+ * Check if a module specifier or request string points to shared steps.
+ * Shared steps are steps imported from outside the current workflow directory.
+ * Matches paths with ../ traversal or /shared/ and containing steps pattern.
+ * @param {string} value - Module path or request string.
+ * @returns {boolean} True if it matches a shared steps path.
+ */
+export const isSharedStepsPath = value => {
+  const hasStepsPattern = STEPS_FILE_REGEX.test( value ) || STEPS_FOLDER_REGEX.test( value );
+  if ( !hasStepsPattern ) {
+    return false;
+  }
+  return PATH_TRAVERSAL_REGEX.test( value ) || SHARED_PATH_REGEX.test( value );
+};
+
+/**
+ * Check if a path matches any steps pattern (local or shared).
+ * Used for validation purposes.
  * @param {string} value - Module path or request string.
- * @returns {boolean} True if it matches steps.js.
+ * @returns {boolean} True if it matches any steps path pattern.
  */
-export const isStepsPath = value => /(^|\/)steps\.js$/.test( value );
+export const isAnyStepsPath = value =>
+  STEPS_FILE_REGEX.test( value ) || STEPS_FOLDER_REGEX.test( value );
 
 /**
- * Check if a module specifier or request string points to shared_steps.js.
+ * Check if a module specifier or request string points to evaluators.js or is in an evaluators folder.
+ * Matches: evaluators.js, /evaluators.js, /evaluators/*.js
  * @param {string} value - Module path or request string.
- * @returns {boolean} True if it matches shared_steps.js.
+ * @returns {boolean} True if it matches an evaluators path.
  */
-export const isSharedStepsPath = value => /(^|\/)shared_steps\.js$/.test( value );
+export const isEvaluatorsPath = value =>
+  EVALUATORS_FILE_REGEX.test( value ) || EVALUATORS_FOLDER_REGEX.test( value );
 
 /**
- * Check if a module specifier or request string points to evaluators.js.
+ * Check if a module specifier or request string points to shared evaluators.
+ * Shared evaluators are evaluators imported from outside the current workflow directory.
+ * Matches paths with ../ traversal or /shared/ and containing evaluators pattern.
  * @param {string} value - Module path or request string.
- * @returns {boolean} True if it matches evaluators.js.
+ * @returns {boolean} True if it matches a shared evaluators path.
  */
-export const isEvaluatorsPath = value => /(^|\/)evaluators\.js$/.test( value );
+export const isSharedEvaluatorsPath = value => {
+  const hasEvaluatorsPattern = EVALUATORS_FILE_REGEX.test( value ) || EVALUATORS_FOLDER_REGEX.test( value );
+  if ( !hasEvaluatorsPattern ) {
+    return false;
+  }
+  return PATH_TRAVERSAL_REGEX.test( value ) || SHARED_PATH_REGEX.test( value );
+};
 
 /**
  * Check if a module specifier or request string points to workflow.js.
@@ -132,35 +182,29 @@ export const isEvaluatorsPath = value => /(^|\/)evaluators\.js$/.test( value );
 export const isWorkflowPath = value => /(^|\/)workflow\.js$/.test( value );
 
 /**
- * Check if a module specifier or request string points to types.js.
+ * Check if a path is a component file (steps, evaluators, or workflow).
  * @param {string} value - Module path or request string.
- * @returns {boolean} True if it matches types.js.
+ * @returns {boolean} True if it matches any component file path.
  */
-export const isTypesPath = value => /(^|\/)types\.js$/.test( value );
-
-export const isExtraneousFile = value => ExtraneousFileList.map( t => new RegExp( `(^|\/)${t}\\.js$` ) ).find( rx => rx.test( value ) );
+export const isComponentFile = value =>
+  isAnyStepsPath( value ) || isEvaluatorsPath( value ) || isWorkflowPath( value );
 
 /**
  * Determine file kind based on its path.
- * @param {string} filename
- * @returns {'workflow'|'steps'|'shared_steps'|'evaluators'|null}
+ * Returns the component type if it's a component file, null otherwise.
+ * @param {string} path
+ * @returns {'workflow'|'steps'|'evaluators'|null}
  */
 export const getFileKind = path => {
-  if ( isStepsPath( path ) ) {
+  if ( isAnyStepsPath( path ) ) {
     return ComponentFile.STEPS;
   }
-  if ( isSharedStepsPath( path ) ) {
-    return ComponentFile.SHARED_STEPS;
-  }
   if ( isEvaluatorsPath( path ) ) {
     return ComponentFile.EVALUATORS;
   }
   if ( isWorkflowPath( path ) ) {
     return ComponentFile.WORKFLOW;
   }
-  if ( isExtraneousFile( path ) ) {
-    return EXTRANEOUS_FILE;
-  }
   return null;
 };
 
@@ -283,12 +327,12 @@ export const buildStepsNameMap = ( path, cache ) => buildComponentNameMap( {
 
 /**
  * Build a map from exported shared step identifier to declared step name.
- * Parses `shared_steps.js` for `export const X = step({ name: '...' })`.
- * Uses the same factory as regular steps.
+ * Same as buildStepsNameMap but for shared steps.
  *
  * @param {string} path - Absolute path to the shared steps module file.
- * @param {Map<string, Map<string,string>>} cache - Cache of computed name maps.
+ * @param {Map<string, Map<string,string>>} cache - Cache of computed step name maps.
  * @returns {Map<string,string>} Exported identifier -> step name.
+ * @throws {Error} When a step name is invalid (non-static or missing).
  */
 export const buildSharedStepsNameMap = ( path, cache ) => buildComponentNameMap( {
   path,

package/src/worker/webpack_loaders/tools.spec.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { mkdtempSync, writeFileSync, rmSync, mkdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join, resolve as resolvePath } from 'node:path';
 import * as t from '@babel/types';
@@ -12,7 +12,9 @@ import {
   toFunctionExpression,
   isStepsPath,
   isSharedStepsPath,
+  isAnyStepsPath,
   isEvaluatorsPath,
+  isSharedEvaluatorsPath,
   isWorkflowPath,
   createThisMethodCall,
   resolveNameFromOptions,
@@ -20,7 +22,6 @@ import {
   buildSharedStepsNameMap,
   buildWorkflowNameMap,
   buildEvaluatorsNameMap,
-  isExtraneousFile,
   getFileKind
 } from './tools.js';
 
@@ -138,14 +139,49 @@ describe( 'workflow_rewriter tools', () => {
     expect( t.isFunctionExpression( fn2 ) ).toBe( true );
   } );
 
-  it( 'isStepsPath: matches steps.js at root or subpath', () => {
+  it( 'isStepsPath: matches LOCAL steps.js (no path traversal)', () => {
+    // Local steps (without ../ or /shared/)
     expect( isStepsPath( 'steps.js' ) ).toBe( true );
     expect( isStepsPath( './steps.js' ) ).toBe( true );
     expect( isStepsPath( '/a/b/steps.js' ) ).toBe( true );
+    expect( isStepsPath( './steps/fetch.js' ) ).toBe( true );
+    // Shared steps (with ../ or /shared/) should NOT match isStepsPath
+    expect( isStepsPath( '../steps.js' ) ).toBe( false );
+    expect( isStepsPath( '../../shared/steps/common.js' ) ).toBe( false );
+    // Non-steps
     expect( isStepsPath( 'steps.ts' ) ).toBe( false );
     expect( isStepsPath( 'workflow.js' ) ).toBe( false );
   } );
 
+  it( 'isSharedStepsPath: matches steps imported from outside workflow directory', () => {
+    // Shared steps: must have steps pattern AND have path traversal or /shared/
+    expect( isSharedStepsPath( '../steps.js' ) ).toBe( true );
+    expect( isSharedStepsPath( '../../steps.js' ) ).toBe( true );
+    expect( isSharedStepsPath( '../../shared/steps/common.js' ) ).toBe( true );
+    expect( isSharedStepsPath( '../other_workflow/steps.js' ) ).toBe( true );
+    expect( isSharedStepsPath( '/src/shared/steps/common.js' ) ).toBe( true );
+    // Local steps (no traversal, no /shared/) should NOT match
+    expect( isSharedStepsPath( './steps.js' ) ).toBe( false );
+    expect( isSharedStepsPath( 'steps.js' ) ).toBe( false );
+    expect( isSharedStepsPath( './steps/fetch.js' ) ).toBe( false );
+    // Non-steps should NOT match
+    expect( isSharedStepsPath( '../utils.js' ) ).toBe( false );
+    expect( isSharedStepsPath( 'evaluators.js' ) ).toBe( false );
+  } );
+
+  it( 'isAnyStepsPath: matches any steps pattern (local or shared)', () => {
+    // Local steps
+    expect( isAnyStepsPath( 'steps.js' ) ).toBe( true );
+    expect( isAnyStepsPath( './steps.js' ) ).toBe( true );
+    expect( isAnyStepsPath( './steps/fetch.js' ) ).toBe( true );
+    // Shared steps
+    expect( isAnyStepsPath( '../steps.js' ) ).toBe( true );
+    expect( isAnyStepsPath( '../../shared/steps/common.js' ) ).toBe( true );
+    // Non-steps
+    expect( isAnyStepsPath( 'workflow.js' ) ).toBe( false );
+    expect( isAnyStepsPath( 'utils.js' ) ).toBe( false );
+  } );
+
   it( 'isWorkflowPath: matches workflow.js at root or subpath', () => {
     expect( isWorkflowPath( 'workflow.js' ) ).toBe( true );
     expect( isWorkflowPath( './workflow.js' ) ).toBe( true );
@@ -154,63 +190,29 @@ describe( 'workflow_rewriter tools', () => {
     expect( isWorkflowPath( 'steps.js' ) ).toBe( false );
   } );
 
-  it( 'isSharedStepsPath: matches shared_steps.js at root or subpath', () => {
-    expect( isSharedStepsPath( 'shared_steps.js' ) ).toBe( true );
-    expect( isSharedStepsPath( './shared_steps.js' ) ).toBe( true );
-    expect( isSharedStepsPath( '/a/b/shared_steps.js' ) ).toBe( true );
-    expect( isSharedStepsPath( 'shared_steps.ts' ) ).toBe( false );
-    expect( isSharedStepsPath( 'evaluators.js' ) ).toBe( false );
-  } );
-
   it( 'isEvaluatorsPath: matches evaluators.js at root or subpath', () => {
     expect( isEvaluatorsPath( 'evaluators.js' ) ).toBe( true );
     expect( isEvaluatorsPath( './evaluators.js' ) ).toBe( true );
     expect( isEvaluatorsPath( '/a/b/evaluators.js' ) ).toBe( true );
+    expect( isEvaluatorsPath( './evaluators/quality.js' ) ).toBe( true );
     expect( isEvaluatorsPath( 'evaluators.ts' ) ).toBe( false );
     expect( isEvaluatorsPath( 'steps.js' ) ).toBe( false );
   } );
 
-  it( 'isExtraneousFile: returns truthy for extraneous files (types/consts/constants/vars/variables)', () => {
-    const ok = [
-      'types.js',
-      './types.js',
-      '/a/b/types.js',
-      'consts.js',
-      './consts.js',
-      '/a/b/consts.js',
-      'constants.js',
-      './constants.js',
-      '/a/b/constants.js',
-      'vars.js',
-      './vars.js',
-      '/a/b/vars.js',
-      'variables.js',
-      './variables.js',
-      '/a/b/variables.js'
-    ];
-    for ( const p of ok ) {
-      expect( Boolean( isExtraneousFile( p ) ) ).toBe( true );
-    }
-  } );
-
-  it( 'isExtraneousFile: returns falsy for non-extraneous or non-.js files', () => {
-    const bad = [
-      'types.ts',
-      '/a/b/types.ts',
-      'types.mjs',
-      'variables.jsx',
-      'variables.mjs',
-      'myconstants.js',
-      'steps.js',
-      'evaluators.js',
-      'shared_steps.js',
-      'workflow.js',
-      'typess.js',
-      '/a/b/c/variables.json'
-    ];
-    for ( const p of bad ) {
-      expect( isExtraneousFile( p ) ).toBeFalsy();
-    }
+  it( 'isSharedEvaluatorsPath: matches evaluators imported from outside workflow directory', () => {
+    // Shared evaluators: must have evaluators pattern AND have path traversal or /shared/
+    expect( isSharedEvaluatorsPath( '../evaluators.js' ) ).toBe( true );
+    expect( isSharedEvaluatorsPath( '../../evaluators.js' ) ).toBe( true );
+    expect( isSharedEvaluatorsPath( '../../shared/evaluators/quality.js' ) ).toBe( true );
+    expect( isSharedEvaluatorsPath( '../other_workflow/evaluators.js' ) ).toBe( true );
+    expect( isSharedEvaluatorsPath( '/src/shared/evaluators/quality.js' ) ).toBe( true );
+    // Local evaluators (no traversal, no /shared/) should NOT match
+    expect( isSharedEvaluatorsPath( './evaluators.js' ) ).toBe( false );
+    expect( isSharedEvaluatorsPath( 'evaluators.js' ) ).toBe( false );
+    expect( isSharedEvaluatorsPath( './evaluators/quality.js' ) ).toBe( false );
+    // Non-evaluators should NOT match
+    expect( isSharedEvaluatorsPath( '../utils.js' ) ).toBe( false );
+    expect( isSharedEvaluatorsPath( 'steps.js' ) ).toBe( false );
   } );
 
   it( 'createThisMethodCall: builds this.method(\'name\', ...args) call', () => {
@@ -223,9 +225,10 @@ describe( 'workflow_rewriter tools', () => {
     expect( call.arguments.length ).toBe( 3 );
   } );
 
-  it( 'buildSharedStepsNameMap: reads names from shared_steps module and caches result', () => {
+  it( 'buildSharedStepsNameMap: reads names from shared steps module and caches result', () => {
     const dir = mkdtempSync( join( tmpdir(), 'tools-shared-steps-' ) );
-    const stepsPath = join( dir, 'shared_steps.js' );
+    mkdirSync( join( dir, 'shared', 'steps' ), { recursive: true } );
+    const stepsPath = join( dir, 'shared', 'steps', 'common.js' );
     writeFileSync( stepsPath, [
       'export const StepA = step({ name: "shared.step.a" })',
       'export const StepB = step({ name: "shared.step.b" })'
@@ -243,9 +246,13 @@ describe( 'workflow_rewriter tools', () => {
   it( 'getFileKind: classifies file by its path', () => {
     expect( getFileKind( '/p/workflow.js' ) ).toBe( 'workflow' );
     expect( getFileKind( '/p/steps.js' ) ).toBe( 'steps' );
-    expect( getFileKind( '/p/shared_steps.js' ) ).toBe( 'shared_steps' );
+    // Files in steps folder are steps
+    expect( getFileKind( '/p/steps/fetch.js' ) ).toBe( 'steps' );
+    expect( getFileKind( '/p/shared/steps/common.js' ) ).toBe( 'steps' );
     expect( getFileKind( '/p/evaluators.js' ) ).toBe( 'evaluators' );
+    expect( getFileKind( '/p/evaluators/quality.js' ) ).toBe( 'evaluators' );
     expect( getFileKind( '/p/other.js' ) ).toBe( null );
+    expect( getFileKind( '/p/utils.js' ) ).toBe( null );
+    expect( getFileKind( '/p/clients/api.js' ) ).toBe( null );
   } );
 } );
-

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

@@ -1,5 +1,5 @@
 import { describe, it, expect } from 'vitest';
-import { mkdtempSync, writeFileSync, rmSync } from 'node:fs';
+import { mkdtempSync, writeFileSync, rmSync, mkdirSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import loader from './index.mjs';
@@ -48,12 +48,15 @@ const obj = {
     rmSync( dir, { recursive: true, force: true } );
   } );
 
-  it( 'rewrites ESM shared_steps imports to invokeSharedStep', async () => {
+  it( 'rewrites ESM shared steps imports to invokeSharedStep', async () => {
+    // Create directory structure: shared/steps/common.js
     const dir = mkdtempSync( join( tmpdir(), 'ast-loader-esm-shared-' ) );
-    writeFileSync( join( dir, 'shared_steps.js' ), 'export const SharedA = step({ name: \'shared.a\' });' );
+    mkdirSync( join( dir, 'shared', 'steps' ), { recursive: true } );
+    mkdirSync( join( dir, 'workflows', 'my_workflow' ), { recursive: true } );
+    writeFileSync( join( dir, 'shared', 'steps', 'common.js' ), 'export const SharedA = step({ name: \'shared.a\' });' );
 
     const source = `
-import { SharedA } from './shared_steps.js';
+import { SharedA } from '../../shared/steps/common.js';
 
 const obj = {
   fn: async (x) => {
@@ -61,21 +64,24 @@ const obj = {
   }
 }`;
 
-    const { code } = await runLoader( source, join( dir, 'file.js' ) );
+    const { code } = await runLoader( source, join( dir, 'workflows', 'my_workflow', 'workflow.js' ) );
 
-    expect( code ).not.toMatch( /from '\.\/shared_steps\.js'/ );
+    expect( code ).not.toMatch( /from '\.\.\/\.\.\/shared\/steps\/common\.js'/ );
     expect( code ).toMatch( /fn:\s*async function \(x\)/ );
     expect( code ).toMatch( /this\.invokeSharedStep\('shared\.a',\s*1\)/ );
 
     rmSync( dir, { recursive: true, force: true } );
   } );
 
-  it( 'rewrites CJS shared_steps requires to invokeSharedStep', async () => {
+  it( 'rewrites CJS shared steps requires to invokeSharedStep', async () => {
+    // Create directory structure: shared/steps/common.js
     const dir = mkdtempSync( join( tmpdir(), 'ast-loader-cjs-shared-' ) );
-    writeFileSync( join( dir, 'shared_steps.js' ), 'export const SharedB = step({ name: \'shared.b\' });' );
+    mkdirSync( join( dir, 'shared', 'steps' ), { recursive: true } );
+    mkdirSync( join( dir, 'workflows', 'my_workflow' ), { recursive: true } );
+    writeFileSync( join( dir, 'shared', 'steps', 'common.js' ), 'export const SharedB = step({ name: \'shared.b\' });' );
 
     const source = `
-const { SharedB } = require( './shared_steps.js' );
+const { SharedB } = require( '../../shared/steps/common.js' );
 
 const obj = {
   fn: async (y) => {
@@ -83,9 +89,9 @@ const obj = {
   }
 }`;
 
-    const { code } = await runLoader( source, join( dir, 'file.js' ) );
+    const { code } = await runLoader( source, join( dir, 'workflows', 'my_workflow', 'workflow.js' ) );
 
-    expect( code ).not.toMatch( /require\('\.\/shared_steps\.js'\)/ );
+    expect( code ).not.toMatch( /require\('\.\.\/\.\.\/shared\/steps\/common\.js'\)/ );
     expect( code ).toMatch( /fn:\s*async function \(y\)/ );
     expect( code ).toMatch( /this\.invokeSharedStep\('shared\.b'\)/ );
 

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}` );
                 }
               }
             }