synthra 0.1.0

data/lib/synthra/parser/ast.rb

@@ -0,0 +1,1287 @@
+# frozen_string_literal: true
+
+# =============================================================================
+
+# Synthra Abstract Syntax Tree (AST) Nodes
+# =============================================================================
+#
+# This file defines all AST node types used to represent the parsed
+# structure of DSL files. The parser converts a token stream into
+# a tree of these nodes.
+#
+# The AST serves as an intermediate representation between parsing
+# and schema creation, enabling validation, transformation, and
+# debugging of DSL definitions.
+#
+# Node Hierarchy:
+#   Node (base)
+#     ├── SchemaNode      - Top-level schema definition
+#     ├── FieldNode       - Field within a schema
+#     ├── TypeNode        - Type reference (base for special types)
+#     │   ├── ArrayTypeNode  - Array type with element and size
+#     │   └── CustomNode     - Custom function call
+#     ├── BehaviorNode    - Behavior annotation (@latency, etc.)
+#     ├── ConditionNode   - Conditional field condition (if ...)
+#     ├── ReferenceNode   - Cross-schema reference (Ref(User.id))
+#     ├── ModifierNode    - Field modifier (unique, range)
+#     └── EnumValueNode   - Enum value with optional probability
+#
+# =============================================================================
+
+
+module Synthra
+  module Parser
+
+    # Abstract Syntax Tree nodes for representing parsed DSL structure
+    #
+    # The AST module contains node classes that represent the hierarchical
+    # structure of a parsed DSL file. Each node type corresponds to a
+    # different DSL construct.
+    #
+    # @example Parse DSL to AST
+    #   parser = Synthra::Parser::Parser.new
+    #   ast_nodes = parser.parse(dsl_source)
+    #   # => [SchemaNode, SchemaNode, ...]
+    #
+    # @example Convert AST to Schema
+    #   schema = ast_nodes.first.to_schema
+    #   # => Synthra::Schema
+    #
+
+    module AST
+
+      # Base class for all AST nodes
+      #
+      # All AST nodes inherit from Node and share the `line` attribute
+      # for error reporting and debugging.
+      #
+      # @abstract Subclass and implement specific node behavior
+      #
+      # @!attribute [r] line
+      #   Source line number where this node was defined
+      #   @return [Integer, nil] the line number (1-based) or nil
+      #
+
+      class Node
+        attr_reader :line
+
+        # Create a new AST node
+        #
+        # @param line [Integer, nil] source line number (1-based)
+        #
+
+        def initialize(line: nil)
+          @line = line
+        end
+      end
+
+      # Schema definition node
+      #
+      # Represents a complete schema definition in the DSL. A SchemaNode
+      # contains the schema name, list of fields, and any schema-level
+      # behaviors.
+      #
+      # @example DSL
+      #   User:
+      #     @seed 12345
+      #     id: uuid
+      #     name: name
+      #
+      # @example AST
+      #   SchemaNode.new(
+      #     name: "User",
+      #     fields: [FieldNode.new(...), FieldNode.new(...)],
+      #     behaviors: [BehaviorNode.new(name: :seed, value: 12345)]
+      #   )
+      #
+
+      class SchemaNode < Node
+
+        # @!attribute [r] name
+        #   The schema name (e.g., "User", "Order")
+        #   @return [String] schema name
+
+        attr_reader :name
+
+        # @!attribute [r] fields
+        #   Field definitions within this schema
+        #   @return [Array<FieldNode>] list of field nodes
+
+        attr_reader :fields
+
+        # @!attribute [r] behaviors
+        #   Schema-level behaviors (@latency, @seed, etc.)
+        #   @return [Array<BehaviorNode>] list of behavior nodes
+
+        attr_reader :behaviors
+
+        # @!attribute [r] parent_name
+        #   Name of the schema this one inherits from (nil if none)
+        #   @return [String, nil] parent schema name
+
+        attr_reader :parent_name
+
+        # Create a new SchemaNode
+        #
+        # @param name [String] the schema name
+        # @param fields [Array<FieldNode>] field definitions
+        # @param behaviors [Array<BehaviorNode>] schema-level behaviors
+        # @param parent_name [String, nil] name of an inherited parent schema
+        # @param line [Integer, nil] source line number
+        #
+
+        def initialize(name:, fields: [], behaviors: [], parent_name: nil, line: nil)
+          super(line: line)
+          @name = name
+          @fields = fields
+          @behaviors = behaviors
+          @parent_name = parent_name
+        end
+
+        # Convert this AST node to a Schema object
+        #
+        # Creates a Synthra::Schema instance from this node,
+        # converting all child nodes (fields, behaviors) as well.
+        #
+        # @return [Synthra::Schema] the schema object
+        #
+        # @example
+        #   schema_node.to_schema
+        #   # => #<Schema User fields=2 behaviors=1>
+        #
+
+        def to_schema
+          all_behaviors = behaviors.map(&:to_behavior)
+          
+          # Extract version from behaviors
+          version_behavior = all_behaviors.find { |b| b[:name] == :version }
+          version = version_behavior&.dig(:value)
+          
+          # Extract deprecated from behaviors
+          deprecated_behavior = all_behaviors.find { |b| b[:name] == :deprecated }
+          deprecated = !deprecated_behavior.nil?
+          deprecation_message = deprecated_behavior&.dig(:value)
+          
+          # Filter out version/deprecated from runtime behaviors
+          runtime_behaviors = all_behaviors.reject { |b| [:version, :deprecated].include?(b[:name]) }
+          
+          Schema.new(
+            name: name,
+            fields: fields.map(&:to_field),
+            behaviors: runtime_behaviors,
+            metadata: {},
+            version: version,
+            deprecated: deprecated,
+            deprecation_message: deprecation_message
+          )
+        end
+      end
+
+      # Field definition node
+      #
+      # Represents a single field within a schema. Contains the field
+      # name, type information, optional flag, conditions, and behaviors.
+      #
+      # @example DSL
+      #   email?: email if has_contact  @partial_data 20%
+      #
+      # @example AST
+      #   FieldNode.new(
+      #     name: "email",
+      #     type_node: TypeNode.new(name: "email"),
+      #     optional: true,
+      #     condition: ConditionNode.new(field_name: "has_contact"),
+      #     behaviors: [BehaviorNode.new(name: :partial_data, value: 20)]
+      #   )
+      #
+
+      class FieldNode < Node
+
+        # @!attribute [r] name
+        #   The field name (without ? suffix)
+        #   @return [String] field name
+
+        attr_reader :name
+
+        # @!attribute [r] type_node
+        #   The type definition for this field
+        #   @return [TypeNode] type node
+
+        attr_reader :type_node
+
+        # @!attribute [r] optional
+        #   Whether the field is optional (? suffix)
+        #   @return [Boolean] true if optional
+
+        attr_reader :optional
+
+        # @!attribute [r] condition
+        #   Condition for including this field
+        #   @return [ConditionNode, nil] condition or nil
+
+        attr_reader :condition
+
+        # @!attribute [r] behaviors
+        #   Field-level behaviors
+        #   @return [Array<BehaviorNode>] list of behaviors
+
+        attr_reader :behaviors
+
+        # Create a new FieldNode
+        #
+        # @param name [String] field name (without ?)
+        # @param type_node [TypeNode] type definition
+        # @param optional [Boolean] is field optional?
+        # @param condition [ConditionNode, nil] inclusion condition
+        # @param behaviors [Array<BehaviorNode>] field behaviors
+        # @param line [Integer, nil] source line number
+        #
+
+        def initialize(name:, type_node:, optional: false, condition: nil, behaviors: [], line: nil)
+          super(line: line)
+          @name = name
+          @type_node = type_node
+          @optional = optional
+          @condition = condition
+          @behaviors = behaviors
+        end
+
+        # Check if this field is optional
+        #
+        # @return [Boolean] true if the field is optional
+        #
+
+        def optional?
+          @optional
+        end
+
+        # Convert this AST node to a Field object
+        #
+        # Creates a Synthra::Field instance from this node.
+        #
+        # @return [Synthra::Field] the field object
+        #
+        # @example
+        #   field_node.to_field
+        #   # => #<Field email?: email>
+        #
+
+        def to_field
+          Field.new(
+            name: optional? ? "#{name}?" : name,
+            type_name: type_node.name,
+            type_args: type_node.arguments,
+            nullable: type_node.nullable?,
+            condition: condition&.field_name,
+            behaviors: behaviors.map(&:to_field_behavior)
+          )
+        end
+      end
+
+      # Type reference node
+      #
+      # Represents a type declaration with optional arguments. This is the
+      # base class for type nodes; ArrayTypeNode and CustomNode extend it
+      # for special cases.
+      #
+      # @example DSL
+      #   age: number(18..80)
+      #   status: enum(active, inactive:30%)
+      #
+      # @example AST
+      #   TypeNode.new(
+      #     name: "number",
+      #     arguments: { range: 18..80 }
+      #   )
+      #
+
+      class TypeNode < Node
+
+        # @!attribute [r] name
+        #   The type name (uuid, text, number, etc.)
+        #   @return [String] type name
+
+        attr_reader :name
+
+        # @!attribute [r] arguments
+        #   Type arguments (min, max, values, etc.)
+        #   @return [Hash] argument name => value pairs
+
+        attr_reader :arguments
+
+        # @!attribute [r] nullable
+        #   Whether the type can be null (? suffix on type)
+        #   @return [Boolean] true if nullable
+
+        attr_reader :nullable
+
+        # Create a new TypeNode
+        #
+        # @param name [String] type name (may have ? suffix)
+        # @param arguments [Hash] type arguments
+        # @param nullable [Boolean] is type nullable?
+        # @param line [Integer, nil] source line number
+        #
+
+        def initialize(name:, arguments: {}, nullable: false, line: nil)
+          super(line: line)
+          @name = name.to_s.delete_suffix("?")
+          @nullable = nullable || name.to_s.end_with?("?")
+          @arguments = arguments
+        end
+
+        # Check if this type can be null
+        #
+        # @return [Boolean] true if nullable
+        #
+
+        def nullable?
+          @nullable
+        end
+      end
+
+      # Behavior annotation node
+      #
+      # Represents a behavior declaration at schema or field level.
+      # Behaviors modify generation (latency, failure) or set metadata (seed).
+      #
+      # @example DSL
+      #   @latency 100..500ms
+      #   @failure 10%
+      #   @seed 12345
+      #
+      # @example AST
+      #   BehaviorNode.new(name: :latency, value: 100..500)
+      #   BehaviorNode.new(name: :failure, value: 10)
+      #   BehaviorNode.new(name: :seed, value: 12345)
+      #
+
+      class BehaviorNode < Node
+
+        # @!attribute [r] name
+        #   Behavior name (latency, failure, seed, etc.)
+        #   @return [Symbol] behavior name
+
+        attr_reader :name
+
+        # @!attribute [r] value
+        #   Behavior configuration value
+        #   @return [Object] the value (Integer, Range, Hash, etc.)
+
+        attr_reader :value
+
+        # Create a new BehaviorNode
+        #
+        # @param name [String, Symbol] behavior name
+        # @param value [Object] behavior value
+        # @param line [Integer, nil] source line number
+        #
+
+        def initialize(name:, value:, line: nil)
+          super(line: line)
+          @name = name.to_sym
+          @value = value
+        end
+
+        # Convert to FieldBehavior for field-level behaviors
+        #
+        # @return [Synthra::FieldBehavior] field behavior object
+        #
+
+        def to_field_behavior
+          FieldBehavior.new(type: name, value: value)
+        end
+
+        # Convert to behavior configuration hash for schema-level
+        #
+        # @return [Hash] behavior configuration hash
+        #
+
+        def to_behavior
+          { name: name, value: value }
+        end
+      end
+
+      # Condition node for conditional fields
+      #
+      # Represents the condition part of a conditional field (if ...).
+      # The condition references another field that must be truthy.
+      #
+      # @example DSL
+      #   admin_note: text if is_admin
+      #
+      # @example AST
+      #   ConditionNode.new(field_name: "is_admin")
+      #
+
+      class ConditionNode < Node
+
+        # Dangerous method names that should never be allowed in conditions
+        # @api private
+        DANGEROUS_METHODS = %w[class instance_eval eval send __send__ method_missing].freeze
+
+        # @!attribute [r] field_name
+        #   Name of the field to check
+        #   @return [String] field name
+
+        attr_reader :field_name
+
+        # Create a new ConditionNode
+        #
+        # @param field_name [String] name of field to check for truthiness
+        # @param line [Integer, nil] source line number
+        #
+
+        def initialize(field_name:, line: nil)
+          super(line: line)
+          @field_name = field_name
+        end
+
+        # Evaluate the condition against a context
+        #
+        # Checks if the referenced field has a truthy value in the
+        # given context. Security: Only uses hash access, never method calls,
+        # and validates field names against a whitelist of dangerous methods.
+        #
+        # @param context [Hash, Generator::Context] generation context
+        # @return [Boolean] true if condition is met
+        #
+        # @example
+        #   condition = ConditionNode.new(field_name: "is_admin")
+        #   condition.evaluate({ "is_admin" => true })   # => true
+        #   condition.evaluate({ "is_admin" => false })  # => false
+        #   condition.evaluate({ "is_admin" => nil })    # => false
+        #
+
+        def evaluate(context)
+
+          # Security: Only use hash access, never public_send
+          # Reject dangerous field names that could be exploited
+          field_name_str = @field_name.to_s
+          return false if field_name_str.start_with?("__")
+
+          # Whitelist validation: reject dangerous method names
+          return false if self.class::DANGEROUS_METHODS.include?(field_name_str)
+          
+          return false unless context.respond_to?(:[])
+
+          value = context[@field_name] || context[@field_name.to_sym]
+          !!value
+        end
+      end
+
+      # Reference to another schema's field
+      #
+      # Represents a Ref() expression that references a field from
+      # another schema. Used for cross-schema relationships.
+      #
+      # @example DSL
+      #   user_id: Ref(User.id)
+      #   category: Ref(Category.name)
+      #
+      # @example AST
+      #   ReferenceNode.new(
+      #     schema_name: "User",
+      #     field_path: "id"
+      #   )
+      #
+
+      class ReferenceNode < Node
+
+        # @!attribute [r] schema_name
+        #   Name of the referenced schema
+        #   @return [String] schema name
+
+        attr_reader :schema_name
+
+        # @!attribute [r] field_path
+        #   Path to the field within the schema
+        #   @return [String] field path (may contain dots for nesting)
+
+        attr_reader :field_path
+
+        # Create a new ReferenceNode
+        #
+        # @param schema_name [String] name of referenced schema
+        # @param field_path [String] path to field in schema
+        # @param line [Integer, nil] source line number
+        #
+
+        def initialize(schema_name:, field_path:, line: nil)
+          super(line: line)
+          @schema_name = schema_name
+          @field_path = field_path
+        end
+
+        # Get full reference string
+        #
+        # @return [String] "SchemaName.field_path"
+        #
+        # @example
+        #   ref.to_s  # => "User.id"
+        #
+
+        def to_s
+          "#{schema_name}.#{field_path}"
+        end
+      end
+
+      # Modifier node for field modifiers
+      #
+      # Represents a modifier applied to a field (unique, range, etc.).
+      #
+      # @example DSL
+      #   id: uuid unique
+      #   age: number(18..80)  # range is often embedded in type args
+      #
+      # @example AST
+      #   ModifierNode.new(name: :unique, value: true)
+      #
+
+      class ModifierNode < Node
+
+        # @!attribute [r] name
+        #   Modifier name (unique, range, etc.)
+        #   @return [Symbol] modifier name
+
+        attr_reader :name
+
+        # @!attribute [r] value
+        #   Modifier value
+        #   @return [Object] the value
+
+        attr_reader :value
+
+        # Create a new ModifierNode
+        #
+        # @param name [String, Symbol] modifier name
+        # @param value [Object] modifier value
+        # @param line [Integer, nil] source line number
+        #
+
+        def initialize(name:, value:, line: nil)
+          super(line: line)
+          @name = name.to_sym
+          @value = value
+        end
+      end
+
+      # Enum value with optional probability
+      #
+      # Represents a single value within an enum type, optionally
+      # with a probability weight.
+      #
+      # @example DSL
+      #   status: enum(pending, active:60%, completed:30%)
+      #
+      # @example AST
+      #   EnumValueNode.new(value: "pending")
+      #   EnumValueNode.new(value: "active", probability: 60)
+      #
+
+      class EnumValueNode < Node
+
+        # @!attribute [r] value
+        #   The enum value
+        #   @return [String] enum value
+
+        attr_reader :value
+
+        # @!attribute [r] probability
+        #   Optional probability percentage
+        #   @return [Integer, nil] probability (0-100) or nil
+
+        attr_reader :probability
+
+        # Create a new EnumValueNode
+        #
+        # @param value [String] enum value
+        # @param probability [Integer, nil] probability percentage
+        # @param line [Integer, nil] source line number
+        #
+
+        def initialize(value:, probability: nil, line: nil)
+          super(line: line)
+          @value = value
+          @probability = probability
+        end
+      end
+
+      # Array type node
+      #
+      # Represents an array type with element type and size specification.
+      # Extends TypeNode with array-specific attributes.
+      #
+      # @example DSL
+      #   tags: array(text, 1..5)
+      #   items: array(Item, 3)
+      #
+      # @example AST
+      #   ArrayTypeNode.new(
+      #     element_type: TypeNode.new(name: "text"),
+      #     size_range: 1..5
+      #   )
+      #
+
+      class ArrayTypeNode < TypeNode
+
+        # @!attribute [r] element_type
+        #   Type of elements in the array
+        #   @return [TypeNode] element type node
+
+        attr_reader :element_type
+
+        # @!attribute [r] size_range
+        #   Size specification (Range or fixed Integer)
+        #   @return [Range, Integer, Hash] size specification
+
+        attr_reader :size_range
+
+        # Create a new ArrayTypeNode
+        #
+        # @param element_type [TypeNode] element type
+        # @param size_range [Range, Integer, Hash] size specification
+        # @param nullable [Boolean] whether the array can be null
+        # @param line [Integer, nil] source line number
+        #
+
+        def initialize(element_type:, size_range:, nullable: false, line: nil)
+          super(
+            name: "array",
+            arguments: { element: element_type, size: size_range },
+            nullable: nullable,
+            line: line
+          )
+          @element_type = element_type
+          @size_range = size_range
+        end
+      end
+
+      # Custom function call node
+      #
+      # Represents a custom() type that calls a registered function.
+      # The function is called during generation with the context.
+      #
+      # @example DSL
+      #   full_name: custom(:compute_full_name)
+      #
+      # @example AST
+      #   CustomNode.new(function_name: :compute_full_name)
+      #
+
+      class CustomNode < TypeNode
+
+        # @!attribute [r] function_name
+        #   Name of the function to call
+        #   @return [Symbol] function name
+
+        attr_reader :function_name
+
+        # Create a new CustomNode
+        #
+        # @param function_name [Symbol] name of registered function
+        # @param line [Integer, nil] source line number
+        #
+
+        def initialize(function_name:, line: nil)
+          super(
+            name: "custom",
+            arguments: { function: function_name },
+            line: line
+          )
+          @function_name = function_name
+        end
+      end
+
+      # =========================================================================
+      # Simulyra DSL - New AST Nodes for Layered Architecture
+      # =========================================================================
+
+      # Program node - root of the AST
+      #
+      # Contains all top-level definitions: schemas and APIs.
+      # This is the entry point for the parsed DSL.
+      #
+      # @example DSL
+      #   schema User:
+      #     id: uuid
+      #   
+      #   api GET /users:
+      #     scenario Success:
+      #       @status 200
+      #
+      # @example AST
+      #   ProgramNode.new(
+      #     schemas: [SchemaDefinitionNode.new(...)],
+      #     apis: [ApiDefinitionNode.new(...)]
+      #   )
+      #
+
+      class ProgramNode < Node
+
+        # @!attribute [r] schemas
+        #   Schema definitions in the program
+        #   @return [Array<SchemaDefinitionNode>] list of schema definitions
+
+        attr_reader :schemas
+
+        # @!attribute [r] apis
+        #   API definitions in the program
+        #   @return [Array<ApiDefinitionNode>] list of API definitions
+
+        attr_reader :apis
+
+        # @!attribute [r] legacy_schemas
+        #   Legacy schema definitions (without 'schema' keyword)
+        #   @return [Array<SchemaNode>] list of legacy schema nodes
+
+        attr_reader :legacy_schemas
+
+        # Create a new ProgramNode
+        #
+        # @param schemas [Array<SchemaDefinitionNode>] schema definitions
+        # @param apis [Array<ApiDefinitionNode>] API definitions
+        # @param legacy_schemas [Array<SchemaNode>] legacy schema definitions
+        # @param line [Integer, nil] source line number
+        #
+
+        def initialize(schemas: [], apis: [], legacy_schemas: [], line: nil)
+          super(line: line)
+          @schemas = schemas
+          @apis = apis
+          @legacy_schemas = legacy_schemas
+        end
+
+        # Get all schema nodes (both new and legacy)
+        #
+        # @return [Array<SchemaDefinitionNode, SchemaNode>] all schemas
+        #
+
+        def all_schemas
+          schemas + legacy_schemas
+        end
+      end
+
+      # Schema definition node (new syntax)
+      #
+      # Represents a schema definition using the new Simulyra syntax:
+      # `schema Name:`
+      #
+      # This differs from the legacy SchemaNode which just uses `Name:`
+      #
+      # @example DSL
+      #   schema User:
+      #     id: uuid
+      #     email: email
+      #
+      # @example AST
+      #   SchemaDefinitionNode.new(
+      #     name: "User",
+      #     fields: [FieldNode.new(...), FieldNode.new(...)]
+      #   )
+      #
+
+      class SchemaDefinitionNode < Node
+
+        # @!attribute [r] name
+        #   The schema name
+        #   @return [String] schema name
+
+        attr_reader :name
+
+        # @!attribute [r] fields
+        #   Field definitions within this schema
+        #   @return [Array<FieldNode>] list of field nodes
+
+        attr_reader :fields
+
+        # @!attribute [r] behaviors
+        #   Schema-level behaviors (for compatibility)
+        #   @return [Array<BehaviorNode>] list of behavior nodes
+
+        attr_reader :behaviors
+
+        # Create a new SchemaDefinitionNode
+        #
+        # @param name [String] the schema name
+        # @param fields [Array<FieldNode>] field definitions
+        # @param behaviors [Array<BehaviorNode>] schema-level behaviors
+        # @param line [Integer, nil] source line number
+        #
+
+        def initialize(name:, fields: [], behaviors: [], line: nil)
+          super(line: line)
+          @name = name
+          @fields = fields
+          @behaviors = behaviors
+        end
+
+        # Convert to Schema object
+        #
+        # @return [Synthra::Schema] the schema object
+        #
+
+        def to_schema
+          all_behaviors = behaviors.map(&:to_behavior)
+          
+          version_behavior = all_behaviors.find { |b| b[:name] == :version }
+          version = version_behavior&.dig(:value)
+          
+          deprecated_behavior = all_behaviors.find { |b| b[:name] == :deprecated }
+          deprecated = !deprecated_behavior.nil?
+          deprecation_message = deprecated_behavior&.dig(:value)
+          
+          runtime_behaviors = all_behaviors.reject { |b| [:version, :deprecated].include?(b[:name]) }
+          
+          Schema.new(
+            name: name,
+            fields: fields.map(&:to_field),
+            behaviors: runtime_behaviors,
+            metadata: {},
+            version: version,
+            deprecated: deprecated,
+            deprecation_message: deprecation_message
+          )
+        end
+      end
+
+      # API definition node
+      #
+      # Represents an API endpoint definition with HTTP method, path,
+      # and response scenarios.
+      #
+      # @example DSL
+      #   api GET /users:
+      #     scenario Success:
+      #       @status 200
+      #       users: schema(:User).array
+      #
+      # @example AST
+      #   ApiDefinitionNode.new(
+      #     method: :get,
+      #     path: "/users",
+      #     scenarios: [ScenarioNode.new(...)]
+      #   )
+      #
+
+      class ApiDefinitionNode < Node
+
+        # @!attribute [r] method
+        #   HTTP method (get, post, put, patch, delete, options, head)
+        #   @return [Symbol] HTTP method as lowercase symbol
+
+        attr_reader :method
+
+        # @!attribute [r] path
+        #   URL path (e.g., "/users", "/users/:id")
+        #   @return [String] URL path
+
+        attr_reader :path
+
+        # @!attribute [r] scenarios
+        #   Response scenarios for this API
+        #   @return [Array<ScenarioNode>] list of scenario nodes
+
+        attr_reader :scenarios
+
+        # Create a new ApiDefinitionNode
+        #
+        # @param method [Symbol] HTTP method (:get, :post, etc.)
+        # @param path [String] URL path
+        # @param scenarios [Array<ScenarioNode>] response scenarios
+        # @param line [Integer, nil] source line number
+        #
+
+        def initialize(method:, path:, scenarios: [], line: nil)
+          super(line: line)
+          @method = method
+          @path = path
+          @scenarios = scenarios
+        end
+      end
+
+      # Scenario node
+      #
+      # Represents a response scenario within an API definition.
+      # Scenarios define possible HTTP responses with status codes,
+      # probabilities, and response body shapes.
+      #
+      # @example DSL
+      #   scenario Success:
+      #     @status 200
+      #     @probability 80%
+      #     users: schema(:User).array
+      #
+      # @example AST
+      #   ScenarioNode.new(
+      #     name: "Success",
+      #     directives: [StatusDirective.new(status_code: 200), ...],
+      #     response_fields: [ResponseFieldNode.new(...)]
+      #   )
+      #
+
+      class ScenarioNode < Node
+
+        # @!attribute [r] name
+        #   Scenario name (e.g., "Success", "NotFound", "ValidationError")
+        #   @return [String] scenario name
+
+        attr_reader :name
+
+        # @!attribute [r] directives
+        #   HTTP directives (@status, @probability, @header, @latency)
+        #   @return [Array<DirectiveNode>] list of directive nodes
+
+        attr_reader :directives
+
+        # @!attribute [r] response_fields
+        #   Response body field definitions
+        #   @return [Array<ResponseFieldNode>] list of response field nodes
+
+        attr_reader :response_fields
+
+        # Create a new ScenarioNode
+        #
+        # @param name [String] scenario name
+        # @param directives [Array<DirectiveNode>] HTTP directives
+        # @param response_fields [Array<ResponseFieldNode>] response fields
+        # @param line [Integer, nil] source line number
+        #
+
+        def initialize(name:, directives: [], response_fields: [], line: nil)
+          super(line: line)
+          @name = name
+          @directives = directives
+          @response_fields = response_fields
+        end
+
+        # Get the status code from directives
+        #
+        # @return [Integer, nil] HTTP status code or nil
+        #
+
+        def status_code
+          status_directive = directives.find { |d| d.is_a?(StatusDirective) }
+          status_directive&.status_code
+        end
+
+        # Get the probability from directives
+        #
+        # @return [Integer, nil] probability percentage or nil
+        #
+
+        def probability
+          prob_directive = directives.find { |d| d.is_a?(ProbabilityDirective) }
+          prob_directive&.percentage
+        end
+      end
+
+      # Response field node
+      #
+      # Represents a field in a scenario's response body.
+      # Similar to FieldNode but specifically for response definitions.
+      #
+      # @example DSL
+      #   users: schema(:User).array
+      #   message: string
+      #
+      # @example AST
+      #   ResponseFieldNode.new(
+      #     name: "users",
+      #     type_node: SchemaReferenceNode.new(schema_name: "User", array: true)
+      #   )
+      #
+
+      class ResponseFieldNode < Node
+
+        # @!attribute [r] name
+        #   Field name
+        #   @return [String] field name
+
+        attr_reader :name
+
+        # @!attribute [r] type_node
+        #   Type definition
+        #   @return [TypeNode, SchemaReferenceNode] type node
+
+        attr_reader :type_node
+
+        # Create a new ResponseFieldNode
+        #
+        # @param name [String] field name
+        # @param type_node [TypeNode] type definition
+        # @param line [Integer, nil] source line number
+        #
+
+        def initialize(name:, type_node:, line: nil)
+          super(line: line)
+          @name = name
+          @type_node = type_node
+        end
+      end
+
+      # Schema reference node
+      #
+      # Represents an explicit schema reference using the syntax:
+      # `schema(:Name)` or `schema(:Name).array`
+      #
+      # This is the ONLY valid way to reference schemas in the new DSL.
+      # The system must NEVER infer schemas from capitalization.
+      #
+      # @example DSL
+      #   user: schema(:User)
+      #   users: schema(:User).array
+      #   users: schema(:User).array(1..10)
+      #
+      # @example AST
+      #   SchemaReferenceNode.new(schema_name: "User")
+      #   SchemaReferenceNode.new(schema_name: "User", array: true)
+      #   SchemaReferenceNode.new(schema_name: "User", array: true, array_range: 1..10)
+      #
+
+      class SchemaReferenceNode < TypeNode
+
+        # @!attribute [r] schema_name
+        #   Name of the referenced schema
+        #   @return [String] schema name
+
+        attr_reader :schema_name
+
+        # @!attribute [r] array
+        #   Whether this is an array of the schema type
+        #   @return [Boolean] true if array
+
+        attr_reader :array
+
+        # @!attribute [r] array_range
+        #   Optional range for array size
+        #   @return [Range, nil] size range or nil
+
+        attr_reader :array_range
+
+        # @!attribute [r] optional
+        #   Whether this reference is optional
+        #   @return [Boolean] true if optional
+
+        attr_reader :optional
+
+        # Create a new SchemaReferenceNode
+        #
+        # @param schema_name [String] name of the referenced schema
+        # @param array [Boolean] whether this is an array
+        # @param array_range [Range, nil] optional array size range
+        # @param optional [Boolean] whether the reference is optional
+        # @param line [Integer, nil] source line number
+        #
+
+        def initialize(schema_name:, array: false, array_range: nil, optional: false, line: nil)
+          super(
+            name: "schema_ref",
+            arguments: {
+              schema_name: schema_name,
+              array: array,
+              array_range: array_range
+            },
+            nullable: optional,
+            line: line
+          )
+          @schema_name = schema_name
+          @array = array
+          @array_range = array_range
+          @optional = optional
+        end
+
+        # Check if this is an array reference
+        #
+        # @return [Boolean] true if array
+        #
+
+        def array?
+          @array
+        end
+
+        # Check if this is an optional reference
+        #
+        # @return [Boolean] true if optional
+        #
+
+        def optional?
+          @optional
+        end
+      end
+
+      # =========================================================================
+      # Directive Nodes for Scenarios
+      # =========================================================================
+
+      # Base class for directive nodes
+      #
+      # Directives are scenario-level declarations that control HTTP behavior.
+      # All directives start with @ in the DSL.
+      #
+
+      class DirectiveNode < Node
+      end
+
+      # Status directive
+      #
+      # Sets the HTTP status code for a scenario.
+      #
+      # @example DSL
+      #   @status 200
+      #   @status 404
+      #
+
+      class StatusDirective < DirectiveNode
+
+        # @!attribute [r] status_code
+        #   HTTP status code
+        #   @return [Integer] status code (100-599)
+
+        attr_reader :status_code
+
+        # Create a new StatusDirective
+        #
+        # @param status_code [Integer] HTTP status code
+        # @param line [Integer, nil] source line number
+        #
+
+        def initialize(status_code:, line: nil)
+          super(line: line)
+          @status_code = status_code
+        end
+      end
+
+      # Probability directive
+      #
+      # Sets the probability of this scenario being selected.
+      #
+      # @example DSL
+      #   @probability 80%
+      #
+
+      class ProbabilityDirective < DirectiveNode
+
+        # @!attribute [r] percentage
+        #   Probability percentage (0-100)
+        #   @return [Integer] percentage
+
+        attr_reader :percentage
+
+        # Create a new ProbabilityDirective
+        #
+        # @param percentage [Integer] probability percentage
+        # @param line [Integer, nil] source line number
+        #
+
+        def initialize(percentage:, line: nil)
+          super(line: line)
+          @percentage = percentage
+        end
+      end
+
+      # Latency directive
+      #
+      # Sets simulated response latency for a scenario.
+      #
+      # @example DSL
+      #   @latency 100..500ms
+      #
+
+      class LatencyDirective < DirectiveNode
+
+        # @!attribute [r] min_ms
+        #   Minimum latency in milliseconds
+        #   @return [Integer] minimum latency
+
+        attr_reader :min_ms
+
+        # @!attribute [r] max_ms
+        #   Maximum latency in milliseconds
+        #   @return [Integer] maximum latency
+
+        attr_reader :max_ms
+
+        # Create a new LatencyDirective
+        #
+        # @param min_ms [Integer] minimum latency
+        # @param max_ms [Integer] maximum latency
+        # @param line [Integer, nil] source line number
+        #
+
+        def initialize(min_ms:, max_ms:, line: nil)
+          super(line: line)
+          @min_ms = min_ms
+          @max_ms = max_ms
+        end
+      end
+
+      # Header directive
+      #
+      # Sets a custom HTTP header for the response.
+      #
+      # @example DSL
+      #   @header Content-Type: application/json
+      #   @header X-Custom: value
+      #
+
+      class HeaderDirective < DirectiveNode
+
+        # @!attribute [r] key
+        #   Header name
+        #   @return [String] header key
+
+        attr_reader :key
+
+        # @!attribute [r] value
+        #   Header value
+        #   @return [String] header value
+
+        attr_reader :value
+
+        # Create a new HeaderDirective
+        #
+        # @param key [String] header name
+        # @param value [String] header value
+        # @param line [Integer, nil] source line number
+        #
+
+        def initialize(key:, value:, line: nil)
+          super(line: line)
+          @key = key
+          @value = value
+        end
+      end
+
+      # Method directive
+      #
+      # Associates a scenario with specific HTTP methods.
+      # Used in the legacy response scenarios format.
+      #
+      # @example DSL
+      #   @method GET
+      #   @method POST
+      #
+
+      class MethodDirective < DirectiveNode
+
+        # @!attribute [r] http_method
+        #   HTTP method
+        #   @return [Symbol] http method as lowercase symbol
+
+        attr_reader :http_method
+
+        # Create a new MethodDirective
+        #
+        # @param http_method [Symbol] HTTP method
+        # @param line [Integer, nil] source line number
+        #
+
+        def initialize(http_method:, line: nil)
+          super(line: line)
+          @http_method = http_method
+        end
+      end
+    end
+  end
+end