@orbytautomation/engine 0.1.0

package/dist/parser/SchemaValidator.js

@@ -0,0 +1,212 @@
+/**
+ * Schema Validator
+ *
+ * Validates workflow YAML/JSON against Zod schema from @dev-ecosystem/core.
+ * Provides enhanced error diagnostics with typo detection and helpful suggestions.
+ *
+ * @module parser
+ */
+import { z } from 'zod';
+import { OrbytWorkflowSchema } from '@dev-ecosystem/core';
+import { SchemaError, findMatches, isLikelyTypo, getValidFields, isValidField, OrbytError, ErrorSeverity, } from '../errors/index.js';
+/**
+ * Enhanced schema validator with diagnostic capabilities
+ */
+export class SchemaValidator {
+    /**
+     * Validate raw workflow data against Zod schema
+     *
+     * @param rawWorkflow - Raw workflow object from YAML/JSON
+     * @returns Validated and typed workflow definition
+     * @throws {OrbytError} If validation fails with detailed diagnostics
+     */
+    static validate(rawWorkflow) {
+        try {
+            // First, check for unknown fields at root level
+            this.validateUnknownFields(rawWorkflow, 'root');
+            // Use Zod schema from ecosystem-core for structural validation
+            const validated = OrbytWorkflowSchema.parse(rawWorkflow);
+            // Additional semantic validations
+            this.validateWorkflowBody(validated);
+            return validated;
+        }
+        catch (error) {
+            // If it's already an OrbytError, rethrow it
+            if (error instanceof OrbytError) {
+                throw error;
+            }
+            // Transform Zod errors into diagnostic-rich OrbytErrors
+            if (error instanceof z.ZodError) {
+                throw this.transformZodError(error);
+            }
+            throw error;
+        }
+    }
+    /**
+     * Check for unknown fields and suggest corrections
+     * Enhanced with multiple suggestions and better context
+     *
+     * @param obj - Object to check
+     * @param path - Current path context
+     */
+    static validateUnknownFields(obj, path) {
+        if (!obj || typeof obj !== 'object') {
+            return;
+        }
+        const validFields = getValidFields(path);
+        const actualFields = Object.keys(obj);
+        for (const field of actualFields) {
+            if (!isValidField(field, path)) {
+                // Find multiple suggestions (up to 3)
+                const suggestions = findMatches(field, Array.from(validFields), 3, 0.5);
+                const bestMatch = suggestions[0];
+                // Build hint with multiple suggestions or best match
+                let hint;
+                if (suggestions.length > 1) {
+                    hint = `Did you mean one of: ${suggestions.map(s => `"${s}"`).join(', ')}?`;
+                }
+                else if (bestMatch) {
+                    hint = `Did you mean "${bestMatch}"?`;
+                }
+                else {
+                    hint = `Valid fields at ${path}: ${Array.from(validFields).join(', ')}`;
+                }
+                // Check if this looks like a very close typo (>0.8 similarity)
+                if (bestMatch && isLikelyTypo(field, bestMatch)) {
+                    hint = `This looks like a typo of "${bestMatch}"!`;
+                }
+                // Throw error with enhanced suggestion
+                throw new SchemaError({
+                    code: 'ORB-S-001',
+                    message: `Unknown field "${field}"`,
+                    path: path === 'root' ? field : `${path}.${field}`,
+                    hint,
+                    severity: ErrorSeverity.ERROR,
+                });
+            }
+            // Recursively validate nested objects
+            const value = obj[field];
+            if (value && typeof value === 'object' && !Array.isArray(value)) {
+                const nestedPath = path === 'root' ? field : `${path}.${field}`;
+                this.validateUnknownFields(value, nestedPath);
+            }
+            // Validate array items (steps, triggers, etc.)
+            if (Array.isArray(value)) {
+                if (field === 'steps') {
+                    value.forEach((item, index) => {
+                        if (item && typeof item === 'object') {
+                            this.validateUnknownFields(item, `workflow.steps[${index}]`);
+                        }
+                    });
+                }
+                else if (field === 'triggers') {
+                    value.forEach((item, index) => {
+                        if (item && typeof item === 'object') {
+                            this.validateUnknownFields(item, `triggers[${index}]`);
+                        }
+                    });
+                }
+            }
+        }
+    }
+    /**
+     * Validate workflow body structure and semantics
+     *
+     * @param workflow - Validated workflow definition
+     */
+    static validateWorkflowBody(workflow) {
+        // Check if workflow body exists
+        if (!workflow.workflow || !workflow.workflow.steps) {
+            throw SchemaError.missingField('workflow.steps', 'workflow');
+        }
+        // Validate steps array is not empty
+        if (workflow.workflow.steps.length === 0) {
+            throw new SchemaError({
+                code: 'ORB-S-003',
+                message: 'Workflow must contain at least one step',
+                path: 'workflow.steps',
+                hint: 'Add at least one step to the workflow.',
+                severity: 'error',
+            });
+        }
+    }
+    /**
+     * Transform Zod validation error into OrbytError with better diagnostics
+     *
+     * @param error - Zod validation error
+     * @returns Enhanced OrbytError
+     */
+    static transformZodError(error) {
+        // Get the first error (we'll enhance to handle multiple later)
+        const firstIssue = error.issues[0];
+        const path = firstIssue.path.join('.');
+        // Determine error type and create appropriate error
+        switch (firstIssue.code) {
+            case 'invalid_type':
+                // Access properties without casting to specific type
+                const expectedType = firstIssue.expected || 'unknown';
+                const receivedType = firstIssue.received || 'unknown';
+                return SchemaError.invalidType(path.split('.').pop() || 'unknown', expectedType, String(receivedType), path);
+            case 'invalid_union':
+                // Handle union/enum-like errors
+                return new SchemaError({
+                    code: 'ORB-S-004',
+                    message: firstIssue.message,
+                    path,
+                    hint: 'Check the allowed values in the workflow schema documentation.',
+                    severity: ErrorSeverity.ERROR,
+                });
+            default:
+                // Generic schema error
+                return new SchemaError({
+                    code: 'ORB-S-002',
+                    message: firstIssue.message,
+                    path,
+                    hint: 'Check the workflow schema documentation.',
+                    severity: ErrorSeverity.ERROR,
+                });
+        }
+    }
+    /**
+     * Check if workflow data is valid without throwing
+     *
+     * @param rawWorkflow - Raw workflow object to validate
+     * @returns True if valid, false otherwise
+     */
+    static isValid(rawWorkflow) {
+        try {
+            this.validate(rawWorkflow);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Safely validate and return result with success/error
+     *
+     * @param rawWorkflow - Raw workflow object to validate
+     * @returns Object with success flag and either data or error
+     */
+    static safeParse(rawWorkflow) {
+        try {
+            const data = this.validate(rawWorkflow);
+            return { success: true, data };
+        }
+        catch (error) {
+            if (error instanceof OrbytError) {
+                return { success: false, error };
+            }
+            // Wrap unexpected errors
+            return {
+                success: false,
+                error: new SchemaError({
+                    code: 'ORB-S-005',
+                    message: error instanceof Error ? error.message : 'Unknown error',
+                    severity: 'error',
+                }),
+            };
+        }
+    }
+}
+//# sourceMappingURL=SchemaValidator.js.map

package/dist/parser/SchemaValidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"SchemaValidator.js","sourceRoot":"","sources":["../../src/parser/SchemaValidator.ts"],"names":[],"mappings":"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"}

package/dist/parser/StepParser.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Step Parser
+ *
+ * Parses individual workflow steps and resolves adapter types.
+ * Converts validated step definitions into internal Step objects with semantic validation.
+ *
+ * @module parser
+ */
+import type { StepDefinition as ZodStepDefinition } from '@dev-ecosystem/core';
+/**
+ * Parsed internal step representation
+ */
+export interface ParsedStep {
+    /** Unique step identifier */
+    id: string;
+    /** Adapter type (http, shell, cli, plugin, etc.) */
+    adapter: string;
+    /** Full action name (e.g., 'http.request.get') */
+    action: string;
+    /** Input parameters for the step */
+    input: Record<string, any>;
+    /** Step dependencies (other step IDs) */
+    needs: string[];
+    /** Optional name */
+    name?: string;
+    /** Conditional execution expression */
+    when?: string;
+    /** Continue workflow on failure */
+    continueOnError: boolean;
+    /** Retry policy */
+    retry?: {
+        max: number;
+        backoff?: 'linear' | 'exponential';
+        delay?: number;
+    };
+    /** Timeout string (e.g., '30s', '5m') */
+    timeout?: string;
+    /** Environment variables for this step */
+    env?: Record<string, string>;
+    /** Output mappings */
+    outputs?: Record<string, string>;
+}
+/**
+ * Parses individual workflow steps with enhanced validation
+ */
+export declare class StepParser {
+    /**
+     * Parse a step definition into internal representation
+     * Enhanced with better validation
+     *
+     * @param stepDef - Validated step definition from schema
+     * @param stepIndex - Index of the step in the workflow (for error messages)
+     * @returns Parsed step object ready for execution
+     */
+    static parse(stepDef: ZodStepDefinition, stepIndex?: number): ParsedStep;
+    /**
+     * Resolve adapter type from 'uses' field
+     * Enhanced with format validation
+     *
+     * Examples:
+     *   'http.request.get' -> 'http'
+     *   'shell.exec' -> 'shell'
+     *   'cli.run' -> 'cli'
+     *   'mediaproc.image.resize' -> 'plugin'
+     *
+     * @param uses - The 'uses' field from step definition
+     * @param stepPath - Path for error messages
+     * @returns Adapter type string
+     */
+    static resolveAdapter(uses: string, stepPath?: string): string;
+    /**
+     * Validate conditional expression syntax (basic check)
+     * Provides hints for common variable references
+     *
+     * @param condition - Conditional expression string
+     * @param path - Path for error messages
+     */
+    private static validateConditionalExpression;
+    /**
+     * Parse multiple steps
+     *
+     * @param stepDefs - Array of step definitions
+     * @returns Array of parsed steps
+     */
+    static parseAll(stepDefs: ZodStepDefinition[]): ParsedStep[];
+    /**
+     * Validate step IDs are unique
+     *
+     * @param steps - Array of parsed steps
+     * @throws {ValidationError} If duplicate step IDs found
+     */
+    static validateUniqueIds(steps: ParsedStep[]): void;
+    /**
+     * Validate step dependencies (needs) refer to valid steps
+     * Enhanced with better error messages and suggestions
+     *
+     * @param steps - Array of parsed steps
+     * @throws {ValidationError} If step references non-existent dependency
+     */
+    static validateDependencies(steps: ParsedStep[]): void;
+    /**
+     * Detect circular dependencies in step graph
+     *
+     * @param steps - Array of parsed steps
+     * @throws {ValidationError} If circular dependency detected
+     */
+    static detectCircularDependencies(steps: ParsedStep[]): void;
+    /**
+     * Run all validation checks on parsed steps
+     * Enhanced with comprehensive validation
+     *
+     * @param steps - Array of parsed steps
+     * @throws {ValidationError} If any validation fails
+     */
+    static validateAll(steps: ParsedStep[]): void;
+    /**
+     * Validate output references in step output mappings
+     * Ensures steps don't reference outputs from steps that haven't executed yet
+     *
+     * @param steps - Array of parsed steps
+     */
+    private static validateOutputReferences;
+}
+//# sourceMappingURL=StepParser.d.ts.map

package/dist/parser/StepParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StepParser.d.ts","sourceRoot":"","sources":["../../src/parser/StepParser.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,cAAc,IAAI,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAG/E;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,6BAA6B;IAC7B,EAAE,EAAE,MAAM,CAAC;IAEX,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAEhB,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;IAEf,oCAAoC;IACpC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAE3B,yCAAyC;IACzC,KAAK,EAAE,MAAM,EAAE,CAAC;IAEhB,oBAAoB;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,uCAAuC;IACvC,IAAI,CAAC,EAAE,MAAM,CAAC;IAEd,mCAAmC;IACnC,eAAe,EAAE,OAAO,CAAC;IAEzB,mBAAmB;IACnB,KAAK,CAAC,EAAE;QACN,GAAG,EAAE,MAAM,CAAC;QACZ,OAAO,CAAC,EAAE,QAAQ,GAAG,aAAa,CAAC;QACnC,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;IAEF,yCAAyC;IACzC,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB,0CAA0C;IAC1C,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAE7B,sBAAsB;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED;;GAEG;AACH,qBAAa,UAAU;IACrB;;;;;;;OAOG;IACH,MAAM,CAAC,KAAK,CAAC,OAAO,EAAE,iBAAiB,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,UAAU;IA0DxE;;;;;;;;;;;;;OAaG;IACH,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM;IAsC9D;;;;;;OAMG;IACH,OAAO,CAAC,MAAM,CAAC,6BAA6B;IAqC5C;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,EAAE,GAAG,UAAU,EAAE;IAI5D;;;;;OAKG;IACH,MAAM,CAAC,iBAAiB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,IAAI;IAkBnD;;;;;;OAMG;IACH,MAAM,CAAC,oBAAoB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,IAAI;IAyBtD;;;;;OAKG;IACH,MAAM,CAAC,0BAA0B,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,IAAI;IA0C5D;;;;;;OAMG;IACH,MAAM,CAAC,WAAW,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,IAAI;IAU7C;;;;;OAKG;IACH,OAAO,CAAC,MAAM,CAAC,wBAAwB;CA6DxC"}

package/dist/parser/StepParser.js

@@ -0,0 +1,330 @@
+/**
+ * Step Parser
+ *
+ * Parses individual workflow steps and resolves adapter types.
+ * Converts validated step definitions into internal Step objects with semantic validation.
+ *
+ * @module parser
+ */
+import { ValidationError, SchemaError, findClosestMatch, isLikelyTypo } from '../errors/index.js';
+/**
+ * Parses individual workflow steps with enhanced validation
+ */
+export class StepParser {
+    /**
+     * Parse a step definition into internal representation
+     * Enhanced with better validation
+     *
+     * @param stepDef - Validated step definition from schema
+     * @param stepIndex - Index of the step in the workflow (for error messages)
+     * @returns Parsed step object ready for execution
+     */
+    static parse(stepDef, stepIndex) {
+        const stepPath = stepIndex !== undefined ? `workflow.steps[${stepIndex}]` : 'workflow.steps';
+        // Validate required fields
+        if (!stepDef.id) {
+            throw SchemaError.missingField('id', stepPath);
+        }
+        // Validate ID format (alphanumeric, hyphens, underscores)
+        if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(stepDef.id)) {
+            throw new SchemaError({
+                code: 'ORB-S-006',
+                message: `Invalid step ID format: "${stepDef.id}"`,
+                path: `${stepPath}.id`,
+                hint: 'Step IDs must start with a letter and contain only letters, numbers, hyphens, and underscores.',
+                severity: 'error',
+            });
+        }
+        if (!stepDef.uses) {
+            throw SchemaError.missingField('uses', `${stepPath}.${stepDef.id}`);
+        }
+        // Resolve adapter type from the 'uses' field (with validation)
+        const adapter = this.resolveAdapter(stepDef.uses, `${stepPath}.${stepDef.id}`);
+        // Validate conditional expression if present
+        if (stepDef.when) {
+            this.validateConditionalExpression(stepDef.when, `${stepPath}.${stepDef.id}.when`);
+        }
+        // Build parsed step
+        const parsedStep = {
+            id: stepDef.id,
+            adapter,
+            action: stepDef.uses,
+            input: stepDef.with || {},
+            needs: stepDef.needs || [],
+            name: stepDef.name,
+            when: stepDef.when,
+            continueOnError: stepDef.continueOnError || false,
+            timeout: stepDef.timeout,
+            env: stepDef.env,
+            outputs: stepDef.outputs,
+        };
+        // Copy retry policy if present
+        if (stepDef.retry) {
+            parsedStep.retry = {
+                max: stepDef.retry.max,
+                backoff: stepDef.retry.backoff,
+                delay: stepDef.retry.delay,
+            };
+        }
+        return parsedStep;
+    }
+    /**
+     * Resolve adapter type from 'uses' field
+     * Enhanced with format validation
+     *
+     * Examples:
+     *   'http.request.get' -> 'http'
+     *   'shell.exec' -> 'shell'
+     *   'cli.run' -> 'cli'
+     *   'mediaproc.image.resize' -> 'plugin'
+     *
+     * @param uses - The 'uses' field from step definition
+     * @param stepPath - Path for error messages
+     * @returns Adapter type string
+     */
+    static resolveAdapter(uses, stepPath) {
+        // Validate format: must contain at least one dot
+        if (!uses.includes('.')) {
+            throw new SchemaError({
+                code: 'ORB-S-006',
+                message: `Invalid action format: "${uses}"`,
+                path: stepPath ? `${stepPath}.uses` : 'step.uses',
+                hint: 'Action format must be: namespace.action (e.g., "http.request" or "shell.exec")',
+                severity: 'error',
+            });
+        }
+        // Extract prefix before first dot
+        const prefix = uses.split('.')[0];
+        // Built-in adapter types
+        const builtInAdapters = ['http', 'shell', 'cli', 'fs', 'webhook'];
+        if (builtInAdapters.includes(prefix)) {
+            return prefix;
+        }
+        // Check for common typos in built-in adapters
+        const closestAdapter = findClosestMatch(prefix, builtInAdapters, 0.7);
+        if (closestAdapter && isLikelyTypo(prefix, closestAdapter)) {
+            throw new SchemaError({
+                code: 'ORB-V-008',
+                message: `Unknown adapter: "${prefix}"`,
+                path: stepPath ? `${stepPath}.uses` : 'step.uses',
+                hint: `Did you mean "${closestAdapter}"? (Built-in adapters: ${builtInAdapters.join(', ')})`,
+                severity: 'error',
+            });
+        }
+        // Everything else is a plugin adapter
+        return 'plugin';
+    }
+    /**
+     * Validate conditional expression syntax (basic check)
+     * Provides hints for common variable references
+     *
+     * @param condition - Conditional expression string
+     * @param path - Path for error messages
+     */
+    static validateConditionalExpression(condition, path) {
+        // Check for empty condition
+        if (!condition || condition.trim().length === 0) {
+            throw new SchemaError({
+                code: 'ORB-S-006',
+                message: 'Conditional expression cannot be empty',
+                path,
+                hint: 'Provide a valid expression or remove the "when" field.',
+                severity: 'error',
+            });
+        }
+        // Check for common variable reference patterns and provide hints
+        const validPrefixes = ['inputs.', 'secrets.', 'steps.', 'context.'];
+        const hasVariable = /\$\{([^}]+)\}/.test(condition);
+        if (hasVariable) {
+            // Extract variables
+            const variables = condition.match(/\$\{([^}]+)\}/g) || [];
+            for (const variable of variables) {
+                const varName = variable.slice(2, -1); // Remove ${ and }
+                const hasValidPrefix = validPrefixes.some(prefix => varName.startsWith(prefix));
+                if (!hasValidPrefix && !varName.startsWith('env.')) {
+                    throw new SchemaError({
+                        code: 'ORB-V-006',
+                        message: `Invalid variable reference: "${variable}"`,
+                        path,
+                        hint: `Variables must start with one of: ${validPrefixes.join(', ')}`,
+                        severity: 'error',
+                    });
+                }
+            }
+        }
+    }
+    /**
+     * Parse multiple steps
+     *
+     * @param stepDefs - Array of step definitions
+     * @returns Array of parsed steps
+     */
+    static parseAll(stepDefs) {
+        return stepDefs.map((step, index) => this.parse(step, index));
+    }
+    /**
+     * Validate step IDs are unique
+     *
+     * @param steps - Array of parsed steps
+     * @throws {ValidationError} If duplicate step IDs found
+     */
+    static validateUniqueIds(steps) {
+        const idMap = new Map();
+        steps.forEach((step, index) => {
+            if (idMap.has(step.id)) {
+                const firstIndex = idMap.get(step.id);
+                throw new ValidationError({
+                    code: 'ORB-V-001',
+                    message: `Duplicate step ID "${step.id}"`,
+                    path: `workflow.steps[${index}]`,
+                    hint: `Step ID "${step.id}" was already defined at workflow.steps[${firstIndex}]. Step IDs must be unique.`,
+                    severity: 'error',
+                });
+            }
+            idMap.set(step.id, index);
+        });
+    }
+    /**
+     * Validate step dependencies (needs) refer to valid steps
+     * Enhanced with better error messages and suggestions
+     *
+     * @param steps - Array of parsed steps
+     * @throws {ValidationError} If step references non-existent dependency
+     */
+    static validateDependencies(steps) {
+        const stepIds = new Set(steps.map(s => s.id));
+        const allStepIds = Array.from(stepIds);
+        steps.forEach((step, index) => {
+            for (const dependency of step.needs) {
+                if (!stepIds.has(dependency)) {
+                    // Try to find similar step IDs
+                    const suggestion = findClosestMatch(dependency, allStepIds, 0.6);
+                    const hint = suggestion
+                        ? `Did you mean "${suggestion}"? Available steps: ${allStepIds.join(', ')}`
+                        : `Available steps: ${allStepIds.join(', ')}`;
+                    throw new ValidationError({
+                        code: 'ORB-V-002',
+                        message: `Unknown step "${dependency}"`,
+                        path: `workflow.steps[${index}].needs`,
+                        hint,
+                        severity: 'error',
+                    });
+                }
+            }
+        });
+    }
+    /**
+     * Detect circular dependencies in step graph
+     *
+     * @param steps - Array of parsed steps
+     * @throws {ValidationError} If circular dependency detected
+     */
+    static detectCircularDependencies(steps) {
+        const stepMap = new Map(steps.map((s, i) => [s.id, { step: s, index: i }]));
+        const visited = new Set();
+        const recursionStack = new Set();
+        function visit(stepId, path) {
+            if (recursionStack.has(stepId)) {
+                // Found cycle
+                const cycleStart = path.indexOf(stepId);
+                const cycle = path.slice(cycleStart).concat(stepId);
+                throw ValidationError.circularDependency(cycle, 'workflow.steps');
+            }
+            if (visited.has(stepId)) {
+                return; // Already processed
+            }
+            visited.add(stepId);
+            recursionStack.add(stepId);
+            // Visit dependencies
+            const stepData = stepMap.get(stepId);
+            if (stepData) {
+                for (const dep of stepData.step.needs) {
+                    visit(dep, [...path, stepId]);
+                }
+            }
+            recursionStack.delete(stepId);
+        }
+        // Visit all steps
+        for (const step of steps) {
+            if (!visited.has(step.id)) {
+                visit(step.id, []);
+            }
+        }
+    }
+    /**
+     * Run all validation checks on parsed steps
+     * Enhanced with comprehensive validation
+     *
+     * @param steps - Array of parsed steps
+     * @throws {ValidationError} If any validation fails
+     */
+    static validateAll(steps) {
+        // Order matters: check basic constraints first
+        this.validateUniqueIds(steps);
+        this.validateDependencies(steps);
+        this.detectCircularDependencies(steps);
+        // Additional semantic validations
+        this.validateOutputReferences(steps);
+    }
+    /**
+     * Validate output references in step output mappings
+     * Ensures steps don't reference outputs from steps that haven't executed yet
+     *
+     * @param steps - Array of parsed steps
+     */
+    static validateOutputReferences(steps) {
+        // Build execution order considering dependencies
+        const stepMap = new Map(steps.map(s => [s.id, s]));
+        const executed = new Set();
+        // Simple topological order (dependencies-first)
+        const getExecutionOrder = () => {
+            const order = [];
+            const visited = new Set();
+            function visit(stepId) {
+                if (visited.has(stepId))
+                    return;
+                visited.add(stepId);
+                const step = stepMap.get(stepId);
+                if (step) {
+                    // Visit dependencies first
+                    for (const dep of step.needs) {
+                        visit(dep);
+                    }
+                    order.push(stepId);
+                }
+            }
+            for (const step of steps) {
+                visit(step.id);
+            }
+            return order;
+        };
+        const executionOrder = getExecutionOrder();
+        // Validate each step's outputs don't reference future steps
+        executionOrder.forEach((stepId) => {
+            const step = stepMap.get(stepId);
+            if (!step || !step.outputs)
+                return;
+            // Check if output values reference other steps
+            for (const [outputKey, outputValue] of Object.entries(step.outputs)) {
+                // Look for ${steps.X.outputs.Y} patterns
+                const stepRefs = outputValue.match(/\$\{steps\.([^.]+)\./g);
+                if (stepRefs) {
+                    for (const ref of stepRefs) {
+                        const referencedStepId = ref.match(/steps\.([^.]+)/)?.[1];
+                        if (referencedStepId && !executed.has(referencedStepId)) {
+                            throw new ValidationError({
+                                code: 'ORB-V-005',
+                                message: `Step "${stepId}" references output from "${referencedStepId}" which hasn't executed yet`,
+                                path: `workflow.steps[${steps.findIndex(s => s.id === stepId)}].outputs.${outputKey}`,
+                                hint: `Add "${referencedStepId}" to the "needs" array of step "${stepId}".`,
+                                severity: 'error',
+                            });
+                        }
+                    }
+                }
+            }
+            executed.add(stepId);
+        });
+    }
+}
+//# sourceMappingURL=StepParser.js.map