synthra 0.1.0

data/lib/synthra/parser/parser.rb

@@ -0,0 +1,1664 @@
+# frozen_string_literal: true
+
+# =============================================================================
+
+# Synthra Parser
+# =============================================================================
+#
+# The Parser is a recursive descent parser that converts a stream of tokens
+# into an Abstract Syntax Tree (AST). It's the second stage of DSL processing
+# after lexing.
+#
+# The parser handles:
+# - Schema definitions
+# - Field declarations with types and modifiers
+# - Type arguments (ranges, enums, custom functions)
+# - Behaviors at schema and field levels
+# - Conditional fields
+# - Cross-schema references
+#
+# Grammar (simplified):
+#   dsl        := schema*
+#   schema     := SCHEMA_NAME COLON NEWLINE INDENT (behavior | field)* DEDENT
+#   field      := FIELD_NAME COLON type behavior* condition? NEWLINE
+#   type       := TYPE arguments?
+#   arguments  := LPAREN arg_list RPAREN
+#   behavior   := AT_BEHAVIOR value?
+#   condition  := IF IDENTIFIER
+#
+# @example Parse a DSL file
+#   parser = Synthra::Parser::Parser.new
+#   ast = parser.parse(File.read("user.dsl"))
+#   # => [SchemaNode(User, fields: [...])]
+#
+# =============================================================================
+
+
+module Synthra
+  module Parser
+
+    # Recursive descent parser for the Synthra language
+    #
+    # Converts a token stream from the Lexer into an AST that represents
+    # the structure of the DSL. The AST can then be converted to Schema
+    # objects for data generation.
+    #
+    # @example Basic usage
+    #   parser = Parser.new
+    #   schemas = parser.parse(dsl_source)
+    #   schemas.first.to_schema  # => Synthra::Schema
+    #
+    # @example Handle parse errors
+    #   begin
+    #     schemas = parser.parse(source)
+    #   rescue Synthra::SyntaxError => e
+    #     puts "Syntax error at line #{e.line}: #{e.message}"
+    #   end
+    #
+
+    class Parser
+
+      # Include token type constants
+      include Tokens
+
+      # Create a new Parser instance
+      #
+      # @return [Parser] a new parser
+      #
+
+      def initialize
+        @tokens = []    # Token array from lexer
+        @pos = 0        # Current position in token array
+      end
+
+      # Parse DSL source code into AST
+      #
+      # This is the main entry point for parsing. It tokenizes the source
+      # using the Lexer, then parses the tokens into schema nodes.
+      #
+      # Supports both legacy syntax (SchemaName:) and new Simulyra syntax
+      # (schema Name:, api METHOD /path:, scenario Name:).
+      #
+      # @param source [String] DSL source code
+      # @return [Array<AST::SchemaNode>, AST::ProgramNode] array of schema AST nodes (legacy)
+      #   or a ProgramNode (new syntax)
+      # @raise [SyntaxError] if the source has syntax errors
+      #
+      # @example Legacy syntax
+      #   parser = Parser.new
+      #   schemas = parser.parse("User:\n  name: text")
+      #   schemas.first.name  # => "User"
+      #
+      # @example New Simulyra syntax
+      #   parser = Parser.new
+      #   program = parser.parse("schema User:\n  id: uuid\n\napi GET /users:\n  scenario Success:\n    @status 200")
+      #   program.schemas.first.name  # => "User"
+      #
+
+      def parse(source)
+        @tokens = Lexer.new(source).tokenize
+        @pos = 0
+
+        # Detect if this is new Simulyra syntax or legacy syntax
+        if uses_simulyra_syntax?
+          parse_program
+        else
+          parse_legacy
+        end
+      end
+
+      # Check if the source uses new Simulyra syntax
+      #
+      # @return [Boolean] true if uses schema/api/scenario keywords
+      #
+
+      def uses_simulyra_syntax?
+        @tokens.any? { |t| t.type?(SCHEMA_KEYWORD) || t.type?(API_KEYWORD) || t.type?(SCENARIO_KEYWORD) }
+      end
+
+      # Parse legacy DSL format (SchemaName: ...)
+      #
+      # @return [Array<AST::SchemaNode>] array of schema nodes
+      #
+
+      def parse_legacy
+        schemas = []
+        while !eof? && !current_token.type?(EOF)
+          skip_newlines
+          # :nocov: defensive guard — the enclosing `while` already exits on EOF, so this
+          # break's then-arm is unreachable.
+          break if eof? || current_token.type?(EOF)
+          # :nocov:
+
+          schemas << parse_schema
+          skip_newlines
+        end
+        schemas
+      end
+
+      # Parse new Simulyra DSL format into ProgramNode
+      #
+      # @return [AST::ProgramNode] program node containing schemas and APIs
+      #
+
+      def parse_program
+        schemas = []
+        apis = []
+        legacy_schemas = []
+
+        while !eof? && !current_token.type?(EOF)
+          skip_newlines
+          # :nocov: defensive guard — the enclosing `while` already exits on EOF, so this
+          # break's then-arm is unreachable.
+          break if eof? || current_token.type?(EOF)
+          # :nocov:
+
+          case current_token.type
+          when SCHEMA_KEYWORD
+            schemas << parse_schema_definition
+          when API_KEYWORD
+            apis << parse_api_definition
+          when SCHEMA_NAME
+            # Legacy schema definition in mixed content
+            legacy_schemas << parse_schema
+          else
+            error("Expected 'schema', 'api', or schema name", current_token)
+          end
+          skip_newlines
+        end
+
+        AST::ProgramNode.new(
+          schemas: schemas,
+          apis: apis,
+          legacy_schemas: legacy_schemas,
+          line: 1
+        )
+      end
+
+      private
+
+      # ==========================================================================
+
+      # Token Access Helpers
+      # ==========================================================================
+
+      # Get the current token
+      #
+      # @return [Token] current token or EOF token if at end
+      #
+
+      def current_token
+        @tokens[@pos] || Token.new(EOF, nil, line: 0, column: 0)
+      end
+
+      # Peek at a token ahead of current position
+      #
+      # @param offset [Integer] how many tokens ahead (default: 1)
+      # @return [Token] token at offset or EOF token
+      #
+
+      def peek_token(offset = 1)
+        @tokens[@pos + offset] || Token.new(EOF, nil, line: 0, column: 0)
+      end
+
+      # Advance to the next token
+      #
+      # @return [Token] the token that was consumed
+      #
+
+      def advance
+        token = current_token
+        @pos += 1
+        token
+      end
+
+      # Check if we've reached the end of tokens
+      #
+      # @return [Boolean] true if at or past end of token array
+      #
+
+      def eof?
+        @pos >= @tokens.length
+      end
+
+      # Expect and consume a specific token type
+      #
+      # @param type [Symbol] expected token type
+      # @return [Token] the consumed token
+      # @raise [SyntaxError] if current token doesn't match
+      #
+
+      def expect(type)
+        token = current_token
+        unless token.type?(type)
+          error("Expected #{type}, got #{token.type}", token)
+        end
+        advance
+      end
+
+      # Raise a syntax error
+      #
+      # @param message [String] error message
+      # @param token [Token] token where error occurred
+      # @raise [SyntaxError] always raises
+      #
+
+      def error(message, token = current_token)
+        raise SyntaxError.new(
+          message,
+          line: token.line,
+          column: token.column
+        )
+      end
+
+      # Skip any newline tokens
+      #
+      # @return [void]
+      #
+
+      def skip_newlines
+        advance while current_token.type?(NEWLINE)
+      end
+
+      # ==========================================================================
+
+      # Schema Parsing
+      # ==========================================================================
+
+      # Parse a schema definition
+      #
+      # Grammar: SCHEMA_NAME COLON NEWLINE INDENT (behavior | field)* DEDENT
+      #
+      # @return [AST::SchemaNode] the schema AST node
+      #
+
+      def parse_schema
+        token = expect(SCHEMA_NAME)
+        name = token.value
+        expect(COLON)
+        skip_newlines
+
+        fields = []
+        behaviors = []
+
+        # Parse indented block of fields and behaviors
+        if current_token.type?(INDENT)
+          advance
+          skip_newlines
+
+          while !eof? && !current_token.type?(DEDENT) && !current_token.type?(EOF)
+            skip_newlines
+            # :nocov: defensive guard — the enclosing `while` already exits on DEDENT/EOF,
+            # so this break's then-arm is unreachable.
+            break if current_token.type?(DEDENT) || current_token.type?(EOF)
+            # :nocov:
+
+            if current_token.type?(AT_BEHAVIOR)
+              behaviors << parse_behavior
+            elsif current_token.type?(FIELD_NAME)
+              fields << parse_field
+            else
+              break
+            end
+            skip_newlines
+          end
+
+          advance if current_token.type?(DEDENT)
+        end
+
+        AST::SchemaNode.new(
+          name: name,
+          fields: fields,
+          behaviors: behaviors,
+          line: token.line
+        )
+      end
+
+      # ==========================================================================
+
+      # Simulyra DSL - New Syntax Parsing
+      # ==========================================================================
+
+      # Parse a schema definition with new syntax: schema Name:
+      #
+      # Grammar: SCHEMA_KEYWORD SCHEMA_NAME COLON NEWLINE INDENT field* DEDENT
+      #
+      # @return [AST::SchemaDefinitionNode] the schema definition node
+      #
+
+      def parse_schema_definition
+        schema_kw_token = expect(SCHEMA_KEYWORD)
+        name_token = expect(SCHEMA_NAME)
+        name = name_token.value
+        expect(COLON)
+        skip_newlines
+
+        fields = []
+        behaviors = []
+
+        # Parse indented block of fields and behaviors
+        if current_token.type?(INDENT)
+          advance
+          skip_newlines
+
+          while !eof? && !current_token.type?(DEDENT) && !current_token.type?(EOF)
+            skip_newlines
+            # :nocov: defensive guard — the enclosing `while` already exits on DEDENT/EOF,
+            # so this break's then-arm is unreachable.
+            break if current_token.type?(DEDENT) || current_token.type?(EOF)
+            # :nocov:
+
+            if current_token.type?(AT_BEHAVIOR)
+              behaviors << parse_behavior
+            elsif current_token.type?(FIELD_NAME)
+              fields << parse_field
+            else
+              break
+            end
+            skip_newlines
+          end
+
+          advance if current_token.type?(DEDENT)
+        end
+
+        AST::SchemaDefinitionNode.new(
+          name: name,
+          fields: fields,
+          behaviors: behaviors,
+          line: schema_kw_token.line
+        )
+      end
+
+      # Parse an API definition: api METHOD /path:
+      #
+      # Grammar: API_KEYWORD HTTP_METHOD PATH COLON NEWLINE INDENT scenario* DEDENT
+      #
+      # @return [AST::ApiDefinitionNode] the API definition node
+      #
+
+      def parse_api_definition
+        api_kw_token = expect(API_KEYWORD)
+        method_token = expect(HTTP_METHOD)
+        http_method = method_token.value
+        path_token = expect(PATH)
+        path = path_token.value
+        expect(COLON)
+        skip_newlines
+
+        scenarios = []
+
+        # Parse indented block of scenarios
+        if current_token.type?(INDENT)
+          api_indent_level = current_token.value
+          advance
+          skip_newlines
+
+          loop do
+            skip_newlines
+            # :nocov: defensive guard — the loop exits via the non-scenario `else break`
+            # below before EOF is reached, so this break's then-arm is unreachable.
+            break if eof? || current_token.type?(EOF)
+            # :nocov:
+
+            # Check if we've returned to API's indent level (DEDENT)
+            # DEDENT token value indicates the new indent level
+            if current_token.type?(DEDENT)
+              # Only break if this is the final DEDENT for the API block
+              # (returning to level 0 or lower than API's content level)
+              # :nocov: a DEDENT inside the scenario loop always returns below the API
+              # content level, so the value-not-less-than else-arm is unreachable.
+              if current_token.value < api_indent_level
+                advance
+                break
+              end
+              # :nocov:
+            end
+
+            if current_token.type?(SCENARIO_KEYWORD)
+              scenarios << parse_scenario
+            else
+              break
+            end
+          end
+        end
+
+        AST::ApiDefinitionNode.new(
+          method: http_method,
+          path: path,
+          scenarios: scenarios,
+          line: api_kw_token.line
+        )
+      end
+
+      # Parse a scenario definition: scenario Name:
+      #
+      # Grammar: SCENARIO_KEYWORD IDENTIFIER COLON NEWLINE INDENT (directive | field)* DEDENT
+      #
+      # @return [AST::ScenarioNode] the scenario node
+      #
+
+      def parse_scenario
+        scenario_kw_token = expect(SCENARIO_KEYWORD)
+        name_token = expect(IDENTIFIER)
+        name = name_token.value
+        expect(COLON)
+        skip_newlines
+
+        directives = []
+        response_fields = []
+
+        # Parse indented block of directives and fields
+        if current_token.type?(INDENT)
+          advance
+          skip_newlines
+
+          while !eof? && !current_token.type?(DEDENT) && !current_token.type?(EOF)
+            skip_newlines
+            # :nocov: defensive guard — the enclosing `while` already exits on DEDENT/EOF,
+            # so this break's then-arm is unreachable.
+            break if current_token.type?(DEDENT) || current_token.type?(EOF)
+            # :nocov:
+
+            if current_token.type?(AT_BEHAVIOR)
+              directives << parse_scenario_directive
+            elsif current_token.type?(FIELD_NAME)
+              response_fields << parse_response_field
+            else
+              break
+            end
+            skip_newlines
+          end
+
+          advance if current_token.type?(DEDENT)
+        end
+
+        AST::ScenarioNode.new(
+          name: name,
+          directives: directives,
+          response_fields: response_fields,
+          line: scenario_kw_token.line
+        )
+      end
+
+      # Parse a scenario directive (@status, @probability, @header, @latency, @method)
+      #
+      # Grammar: AT_BEHAVIOR value
+      #
+      # @return [AST::DirectiveNode] the directive node
+      #
+
+      def parse_scenario_directive
+        token = expect(AT_BEHAVIOR)
+        directive_name = token.value.to_s
+
+        case directive_name
+        when "status"
+          status_code = parse_directive_value
+          AST::StatusDirective.new(status_code: status_code.to_i, line: token.line)
+        when "probability"
+          percentage = parse_directive_value
+          # Handle percentage format (e.g., "80" from "80%")
+          AST::ProbabilityDirective.new(percentage: percentage.to_i, line: token.line)
+        when "latency"
+          latency_value = parse_behavior_value
+          if latency_value.is_a?(Hash)
+            AST::LatencyDirective.new(
+              min_ms: latency_value[:min],
+              max_ms: latency_value[:max],
+              line: token.line
+            )
+          else
+            AST::LatencyDirective.new(min_ms: latency_value, max_ms: latency_value, line: token.line)
+          end
+        when "header"
+          key = expect(IDENTIFIER).value
+          expect(COLON)
+          value = parse_directive_string_value
+          AST::HeaderDirective.new(key: key, value: value, line: token.line)
+        when "method"
+          method_value = expect(IDENTIFIER).value.downcase.to_sym
+          AST::MethodDirective.new(http_method: method_value, line: token.line)
+        else
+          # Generic behavior - convert to behavior node for compatibility
+          value = parse_behavior_value
+          skip_newlines
+          AST::BehaviorNode.new(name: directive_name, value: value, line: token.line)
+        end
+      end
+
+      # Parse a directive value (number, identifier)
+      #
+      # @return [Object] the parsed value
+      #
+
+      def parse_directive_value
+        if current_token.type?(NUMBER)
+          value = current_token.value
+          advance
+          # Skip percentage sign if present
+          if current_token.type?(PERCENT)
+            advance
+          end
+          value
+        elsif current_token.type?(IDENTIFIER)
+          value = current_token.value
+          advance
+          value
+        else
+          nil
+        end
+      end
+
+      # Parse a directive string value (for headers)
+      #
+      # @return [String] the string value
+      #
+
+      def parse_directive_string_value
+        if current_token.type?(STRING)
+          value = current_token.value
+          advance
+          value
+        elsif current_token.type?(IDENTIFIER) || current_token.type?(TYPE)
+          value = current_token.value
+          advance
+          value.to_s
+        else
+          ""
+        end
+      end
+
+      # Parse a response field in a scenario
+      #
+      # Grammar: FIELD_NAME COLON type NEWLINE
+      #
+      # @return [AST::ResponseFieldNode] the response field node
+      #
+
+      def parse_response_field
+        field_token = expect(FIELD_NAME)
+        field_name = field_token.value.delete_suffix("?")
+        expect(COLON)
+        type_node = parse_type
+        skip_newlines
+
+        AST::ResponseFieldNode.new(
+          name: field_name,
+          type_node: type_node,
+          line: field_token.line
+        )
+      end
+
+      # ==========================================================================
+
+      # Field Parsing
+      # ==========================================================================
+
+      # Parse a field definition
+      #
+      # Grammar: FIELD_NAME COLON type behavior* condition? NEWLINE
+      #
+      # @return [AST::FieldNode] the field AST node
+      #
+
+      def parse_field
+        field_token = expect(FIELD_NAME)
+        field_name = field_token.value
+        optional = field_name.end_with?("?")
+        clean_name = field_name.delete_suffix("?")
+
+        expect(COLON)
+        type_node = parse_type
+
+        # Parse field-level behaviors (@partial_data, @latency, etc.)
+        behaviors = []
+        while current_token.type?(AT_BEHAVIOR)
+          behaviors << parse_field_behavior
+        end
+
+        # Parse condition (if field_name)
+        condition = nil
+        if current_token.type?(IF)
+          advance
+          cond_token = expect(IDENTIFIER)
+          condition = AST::ConditionNode.new(field_name: cond_token.value, line: cond_token.line)
+        end
+
+        skip_newlines
+
+        AST::FieldNode.new(
+          name: clean_name,
+          type_node: type_node,
+          optional: optional,
+          condition: condition,
+          behaviors: behaviors,
+          line: field_token.line
+        )
+      end
+
+      # ==========================================================================
+
+      # Type Parsing
+      # ==========================================================================
+
+      # Parse a type expression
+      #
+      # Handles:
+      # - Simple types: uuid, text, number
+      # - Nullable types: User?
+      # - Types with arguments: number(18..80), enum(a, b, c)
+      # - References: Ref(User.id)
+      # - Schema references: schema(:User), schema(:User).array
+      # - Arrays: array(text, 1..5)
+      # - Custom functions: custom(:my_function)
+      #
+      # @return [AST::TypeNode] the type AST node (or subclass)
+      #
+
+      def parse_type
+        # Handle schema(:Name) reference
+        if current_token.type?(SCHEMA_KEYWORD)
+          return parse_schema_reference
+        end
+
+        type_token = advance  # TYPE or schema reference
+
+        type_name = type_token.value
+        nullable = type_name.to_s.end_with?("?")
+        clean_type = type_name.to_s.delete_suffix("?")
+
+        arguments = {}
+
+        # Handle Ref(Schema.field) - cross-schema reference
+        if type_token.type?(REF)
+          return parse_reference(type_token.line)
+        end
+
+        # Handle type arguments in parentheses
+        if current_token.type?(LPAREN)
+          advance
+          arguments = parse_type_arguments(clean_type)
+          expect(RPAREN)
+        end
+
+        # Check for ? suffix after arguments (e.g., text(20..100)? or User?)
+        # The QUESTION token comes after RPAREN when type has arguments
+        if current_token.type?(QUESTION)
+          nullable = true
+          advance
+        end
+
+        # Special handling for array type
+        if clean_type == "array"
+          return parse_array_type(arguments, type_token.line, nullable)
+        end
+
+        # Special handling for custom function type
+        if clean_type == "custom"
+          func_name = arguments[:function] || arguments.values.first
+          return AST::CustomNode.new(function_name: func_name, line: type_token.line)
+        end
+
+        AST::TypeNode.new(
+          name: clean_type,
+          arguments: arguments,
+          nullable: nullable,
+          line: type_token.line
+        )
+      end
+
+      # Parse a schema reference: schema(:Name) or schema(:Name).array
+      #
+      # Grammar: SCHEMA_KEYWORD LPAREN SCHEMA_REF RPAREN (DOT array_modifier)?
+      #
+      # @return [AST::SchemaReferenceNode] the schema reference node
+      #
+
+      def parse_schema_reference
+        token = expect(SCHEMA_KEYWORD)
+        expect(LPAREN)
+        schema_ref_token = expect(SCHEMA_REF)
+        schema_name = schema_ref_token.value
+        expect(RPAREN)
+
+        is_array = false
+        array_range = nil
+        is_optional = false
+
+        # Check for modifiers: .array, .array(1..10), .optional
+        while current_token.type?(DOT)
+          advance
+          # :nocov: the lexer always emits an IDENTIFIER token after a DOT (even for digits
+          # or symbols), so the else-arm of this guard is unreachable.
+          if current_token.type?(IDENTIFIER)
+            # :nocov:
+            modifier = current_token.value
+            advance
+
+            case modifier
+            when "array"
+              is_array = true
+              # Check for array range: .array(1..10)
+              if current_token.type?(LPAREN)
+                advance
+                if current_token.type?(RANGE)
+                  range = current_token.value
+                  array_range = range[:min]..range[:max]
+                  advance
+                elsif current_token.type?(NUMBER)
+                  num = current_token.value
+                  array_range = num..num
+                  advance
+                end
+                expect(RPAREN)
+              end
+            when "optional"
+              is_optional = true
+            end
+          end
+        end
+
+        # Check for ? suffix
+        if current_token.type?(QUESTION)
+          is_optional = true
+          advance
+        end
+
+        AST::SchemaReferenceNode.new(
+          schema_name: schema_name,
+          array: is_array,
+          array_range: array_range,
+          optional: is_optional,
+          line: token.line
+        )
+      end
+
+      # Parse a Ref() expression
+      #
+      # Grammar: REF LPAREN IDENTIFIER DOT path RPAREN
+      # path := IDENTIFIER (DOT IDENTIFIER)*
+      #
+      # @param line [Integer] line number for error reporting
+      # @return [AST::TypeNode] type node wrapping a ReferenceNode
+      #
+
+      def parse_reference(line)
+        expect(LPAREN)
+        schema_token = advance
+        schema_name = schema_token.value
+        unless current_token.type?(DOT)
+          error("ref(#{schema_name}) needs a field — write ref(#{schema_name}.<field>), e.g. ref(#{schema_name}.id)")
+        end
+        expect(DOT)
+        field_token = advance
+        field_path = field_token.value
+
+        # Handle nested paths like address.city
+        while current_token.type?(DOT)
+          advance
+          next_token = advance
+          field_path = "#{field_path}.#{next_token.value}"
+        end
+
+        expect(RPAREN)
+
+        ref_node = AST::ReferenceNode.new(
+          schema_name: schema_name,
+          field_path: field_path,
+          line: line
+        )
+
+        # Wrap in TypeNode with name "reference"
+        AST::TypeNode.new(
+          name: "reference",
+          arguments: { ref: ref_node },
+          line: line
+        )
+      end
+
+      # Parse an array type from arguments
+      #
+      # @param arguments [Hash] parsed arguments (element, size)
+      # @param line [Integer] line number
+      # @param nullable [Boolean] whether the array can be null
+      # @return [AST::ArrayTypeNode] the array type node
+      #
+      # Parse an array type from arguments
+      #
+      # Creates an ArrayTypeNode from parsed arguments containing element
+      # type and size specification.
+      #
+      # @param arguments [Hash] parsed arguments (element, size)
+      # @param line [Integer] line number
+      # @param nullable [Boolean] whether the array can be null
+      # @return [AST::ArrayTypeNode] the array type node
+      #
+
+      def parse_array_type(arguments, line, nullable = false)
+        element_type = arguments[:element] || arguments.values.first
+        size_range = arguments[:size] || arguments[:range] || { min: 0, max: 10 }
+
+        AST::ArrayTypeNode.new(
+          element_type: element_type,
+          size_range: size_range,
+          nullable: nullable,
+          line: line
+        )
+      end
+
+      # ==========================================================================
+
+      # Argument Parsing
+      # ==========================================================================
+
+      # Parse type arguments based on type name
+      #
+      # Different types have different argument formats:
+      # - enum: comma-separated values with optional probabilities
+      # - boolean: true/false with probabilities
+      # - array: element type and size
+      # - custom: symbol function name
+      # - others: generic key:value pairs or ranges
+      #
+      # @param type_name [String] the type name
+      # @return [Hash] parsed arguments
+      #
+
+      def parse_type_arguments(type_name)
+        args = {}
+
+        case type_name
+        when "enum"
+          args[:values] = parse_enum_values
+        when "boolean"
+          args.merge!(parse_boolean_args)
+        when "array"
+          args.merge!(parse_array_args)
+        when "map_by_field"
+          args.merge!(parse_map_by_field_args)
+        when "shared"
+          args.merge!(parse_shared_args)
+        when "one_of"
+          args.merge!(parse_one_of_args)
+        when "snowflake_id", "unix_timestamp_ms"
+          args.merge!(parse_as_args)
+        when "custom"
+          args[:function] = parse_symbol_arg
+        when "const", "default_value", "default"
+          args.merge!(parse_const_args)
+        when "copy"
+          args.merge!(parse_copy_args)
+        when "regex"
+          args.merge!(parse_pattern_args(:pattern))
+        when "template"
+          args.merge!(parse_pattern_args(:template))
+        when "formula"
+          args.merge!(parse_formula_args)
+        when "repeating_element"
+          args.merge!(parse_repeating_element_args)
+        else
+          args.merge!(parse_generic_args)
+        end
+
+        args
+      end
+
+      # Parse enum values with optional probabilities
+      #
+      # Grammar: value (:NUMBER%)? (COMMA value (:NUMBER%)?)*
+      #
+      # @return [Array<AST::EnumValueNode>] list of enum value nodes
+      # @raise [InvalidProbabilityError] if total probability > 100%
+      #
+
+      def parse_enum_values
+        values = []
+        total_probability = 0
+
+        loop do
+          break if current_token.type?(RPAREN)
+
+          value_token = advance
+          value = value_token.value
+          probability = nil
+
+          # Check for :probability% syntax
+          if current_token.type?(COLON)
+            advance
+            num_token = expect(NUMBER)
+            expect(PERCENT)
+            probability = num_token.value
+            total_probability += probability
+          end
+
+          values << AST::EnumValueNode.new(value: value, probability: probability)
+
+          break unless current_token.type?(COMMA)
+
+          advance  # Skip comma
+        end
+
+        # Validate total probability doesn't exceed 100%
+        if total_probability > 100
+          raise InvalidProbabilityError.new(total_probability, line: current_token.line)
+        end
+
+        # Distribute remaining probability to unspecified values
+        unspecified = values.count { |v| v.probability.nil? }
+        if unspecified.positive? && total_probability < 100
+          remainder = (100 - total_probability) / unspecified
+          values.each do |v|
+            v.instance_variable_set(:@probability, remainder) if v.probability.nil?
+          end
+        end
+
+        values
+      end
+
+      # Parse boolean type arguments
+      #
+      # Handles true:X% and false:Y% probability specifications.
+      #
+      # @return [Hash] { true_probability: X, false_probability: Y }
+      #
+
+      def parse_boolean_args
+        args = {}
+
+        loop do
+          break if current_token.type?(RPAREN)
+
+          if current_token.type?(TRUE_KW) || current_token.type?(FALSE_KW)
+            bool_val = current_token.type?(TRUE_KW)
+            advance
+            if current_token.type?(COLON)
+              advance
+              num_token = expect(NUMBER)
+              expect(PERCENT)
+              args[bool_val ? :true_probability : :false_probability] = num_token.value
+            end
+          else
+            advance
+          end
+
+          break unless current_token.type?(COMMA)
+
+          advance
+        end
+
+        args
+      end
+
+      # Parse array type arguments
+      #
+      # Supports both positional and named arguments:
+      # - Positional: array(text, 1..5) or array(OrderItem, 3)
+      # - Named: array(element: text, size: 1..5)
+      #
+      # Grammar: (element_type | element: type) (COMMA (size_spec | size: spec))?
+      # size_spec := RANGE | NUMBER
+      #
+      # @return [Hash] { element: type_name, size: range }
+      #
+
+      def parse_array_args
+        args = {}
+
+        # Check for named arguments first (element: type, size: range)
+        # :nocov: peek_token never returns nil (it falls back to a synthetic EOF token), so
+        # the `&.` nil-receiver else-arm in this condition is unreachable.
+        if current_token.type?(IDENTIFIER) && current_token.value.to_s == "element" && peek_token(1)&.type?(COLON)
+          # :nocov:
+
+          # Named argument: element: type
+          advance  # Skip "element"
+          expect(COLON)
+          if current_token.type?(TYPE) || current_token.type?(IDENTIFIER)
+            args[:element] = current_token.value
+            advance
+          end
+
+          # Check for size: spec
+          if current_token.type?(COMMA)
+            advance
+            # :nocov: peek_token never returns nil (synthetic EOF fallback), so the `&.`
+            # nil-receiver else-arm in this condition is unreachable.
+            if current_token.type?(IDENTIFIER) && current_token.value.to_s == "size" && peek_token(1)&.type?(COLON)
+              # :nocov:
+              advance  # Skip "size"
+              expect(COLON)
+
+              if current_token.type?(RANGE)
+                args[:size] = current_token.value
+                advance
+              elsif current_token.type?(NUMBER)
+                min = current_token.value
+                advance
+                if current_token.type?(RANGE)
+                  args[:size] = current_token.value
+                  advance
+                else
+                  args[:size] = { min: min, max: min }
+                end
+              end
+
+            end
+          end
+        else
+
+          # Positional arguments: element_type (COMMA size_spec)?
+          if current_token.type?(TYPE) || current_token.type?(IDENTIFIER)
+            args[:element] = current_token.value
+            advance
+          end
+
+          if current_token.type?(COMMA)
+            advance
+
+            # Second arg is size range
+            if current_token.type?(RANGE)
+              range = current_token.value
+              args[:size] = range
+              advance
+            elsif current_token.type?(NUMBER)
+              min = current_token.value
+              advance
+              if current_token.type?(RANGE)
+                range = current_token.value
+                args[:size] = range
+                advance
+              else
+                args[:size] = { min: min, max: min }
+              end
+            end
+          end
+        end
+
+        args
+      end
+
+      # Parse map_by_field arguments
+      #
+      # Grammar: STRING COMMA entry (COMMA entry)*
+      # entry := IDENTIFIER COLON IDENTIFIER
+      #
+      # @example map_by_field("id", sender: TwitterUser, recipient: TwitterUser)
+      # @return [Hash] { key_field: "id", entries: { sender: "TwitterUser", ... } }
+      #
+
+      def parse_map_by_field_args
+        args = { entries: {} }
+
+        # First argument: key field name (string)
+        if current_token.type?(STRING)
+          args[:key_field] = current_token.value
+          advance
+        else
+          args[:key_field] = "id"  # Default
+        end
+
+        # Remaining arguments: name: SchemaType or name: shared(SchemaType) pairs
+        while current_token.type?(COMMA)
+          advance  # Skip comma
+
+          # Parse entry name
+          if current_token.type?(IDENTIFIER)
+            entry_name = current_token.value.to_sym
+            advance
+
+            # Expect colon
+            if current_token.type?(COLON)
+              advance
+
+              # Check if it's a shared() wrapper
+              if current_token.type?(IDENTIFIER) && current_token.value.to_s == "shared"
+                advance  # Skip "shared"
+                expect(LPAREN)
+                if current_token.type?(IDENTIFIER) || current_token.type?(TYPE)
+                  schema_name = current_token.value
+                  # Mark as shared by storing a hash instead of just the name
+                  args[:entries][entry_name] = { schema: schema_name.to_s, shared: true }
+                  advance
+                end
+                expect(RPAREN)
+              elsif current_token.type?(IDENTIFIER) || current_token.type?(TYPE)
+                # Regular schema type
+                schema_name = current_token.value
+                args[:entries][entry_name] = schema_name.to_s
+                advance
+              end
+            end
+          end
+        end
+
+        args
+      end
+
+
+      # Parse shared type arguments
+      #
+      # Grammar: TypeName (COMMA key: STRING)?
+      # Example: shared(TwitterUser) or shared(TwitterUser, key: "recipient")
+      #
+      # @return [Hash] { type_name:, type_args:, shared_key: }
+      #
+
+      def parse_shared_args
+        args = {}
+
+        # First argument: type/schema name
+        if current_token.type?(IDENTIFIER) || current_token.type?(TYPE)
+          args[:type_name] = current_token.value.to_s
+          advance
+        end
+
+        # Optional key: argument for custom cache key
+        if current_token.type?(COMMA)
+          advance
+          # :nocov: peek_token never returns nil (synthetic EOF fallback), so the `&.`
+          # nil-receiver else-arm in this condition is unreachable.
+          if current_token.type?(IDENTIFIER) && current_token.value.to_s == "key" && peek_token(1)&.type?(COLON)
+            # :nocov:
+            advance  # Skip "key"
+            expect(COLON)
+            if current_token.type?(STRING)
+              args[:shared_key] = current_token.value
+              advance
+            end
+          end
+        end
+
+        args
+      end
+
+
+      # Parse one_of type arguments
+      #
+      # Grammar: SchemaName (COMMA SchemaName)* | SchemaName:PERCENTAGE (COMMA SchemaName:PERCENTAGE)*
+      # Example: one_of(MessageCreate, TypingIndicator, ReadReceipt)
+      # Example with weights: one_of(CommonPayload:80%, RarePayload:20%)
+      #
+      # @return [Hash] { schemas: [...] }
+      #
+
+      def parse_one_of_args
+        args = { schemas: [] }
+
+        loop do
+          break if current_token.type?(RPAREN)
+
+          if current_token.type?(IDENTIFIER) || current_token.type?(TYPE)
+            schema_name = current_token.value.to_s
+            advance
+
+            # Check for weight (percentage)
+            if current_token.type?(COLON)
+              advance
+              if current_token.type?(NUMBER)
+                weight = current_token.value
+                advance
+                # Skip optional % sign
+                # :nocov: the lexer never emits a standalone "%" IDENTIFIER token after a
+                # weight literal, so this conditional advance's then-arm is unreachable.
+                advance if current_token.type?(IDENTIFIER) && current_token.value.to_s == "%"
+                # :nocov:
+                args[:schemas] << { schema: schema_name, weight: weight }
+              else
+                args[:schemas] << schema_name
+              end
+            else
+              args[:schemas] << schema_name
+            end
+          end
+
+          # Check for comma to continue
+          if current_token.type?(COMMA)
+            advance
+          else
+            break
+          end
+        end
+
+        args
+      end
+
+
+      # Parse as: argument for types that support string/integer output
+      #
+      # Grammar: (as: (string | integer))?
+      # Example: snowflake_id(as: string) or snowflake_id(as: integer)
+      #
+      # @return [Hash] { as: "string" | "integer" }
+      #
+
+      def parse_as_args
+        args = {}
+
+        # Check for as: argument
+        # :nocov: peek_token never returns nil (synthetic EOF fallback), so the `&.`
+        # nil-receiver else-arm in this condition is unreachable.
+        if current_token.type?(IDENTIFIER) && current_token.value.to_s == "as" && peek_token(1)&.type?(COLON)
+          # :nocov:
+          advance  # Skip "as"
+          expect(COLON)
+          if current_token.type?(IDENTIFIER) || current_token.type?(TYPE)
+            args[:as] = current_token.value.to_s
+            advance
+          end
+        end
+
+        args
+      end
+
+
+      # Parse const type arguments
+      #
+      # Grammar: STRING | NUMBER | TRUE_KW | FALSE_KW | IDENTIFIER
+      # Example: const("message_create") or const(42) or const(true)
+      #
+      # @return [Hash] { value: the_constant_value }
+      #
+
+      def parse_const_args
+        args = {}
+
+        case current_token.type
+        when STRING
+          args[:value] = current_token.value
+          advance
+        when NUMBER
+          args[:value] = current_token.value
+          advance
+        when TRUE_KW
+          args[:value] = true
+          advance
+        when FALSE_KW
+          args[:value] = false
+          advance
+        when IDENTIFIER
+          args[:value] = current_token.value.to_s
+          advance
+        end
+
+        args
+      end
+
+
+      # Parse a copy() argument: copy("path.to.field") or copy(bare_field).
+      #
+      # Stores the referenced path as a String under :path so the Copy generator
+      # (and PathValidator) can resolve it. The bare-identifier form previously
+      # fell through to parse_generic_args and was stored as a Symbol :value,
+      # which crashed the validator (Symbol#split).
+      #
+      # @return [Hash] { path: String }
+      #
+      def parse_copy_args
+        args = {}
+
+        case current_token.type
+        when STRING
+          args[:path] = current_token.value.to_s
+          advance
+        when IDENTIFIER, TYPE
+          args[:path] = current_token.value.to_s
+          advance
+        end
+
+        args
+      end
+
+      # Parse a single quoted/bare string argument for regex() and template().
+      #
+      # regex("\d{3}") and template("Hello ${a}") were previously routed through
+      # parse_generic_args, which stored the string under :path — so the
+      # generators (reading :pattern / :template) saw nil and returned "".
+      #
+      # Also accepts the explicit named form regex(pattern: "...") /
+      # template(template: "...") by delegating to parse_generic_args.
+      #
+      # @param key [Symbol] the argument key to store the string under
+      # @return [Hash] { key => String }
+      #
+      def parse_pattern_args(key)
+        # Named form (pattern:/template:/etc.) — let parse_generic_args map it.
+        return parse_generic_args if current_token.type?(IDENTIFIER) && peek_token.type?(COLON)
+
+        args = {}
+
+        if current_token.type?(STRING)
+          args[key] = current_token.value.to_s
+          advance
+        elsif current_token.type?(IDENTIFIER) || current_token.type?(TYPE)
+          args[key] = current_token.value.to_s
+          advance
+        end
+
+        args
+      end
+
+      # Parse a formula() argument list.
+      #
+      # Two supported forms:
+      #   1. Named:  formula(expression: "a * b")  /  formula(expr: "a * b")
+      #      — the documented, eval-safe form; delegated to parse_generic_args
+      #      which already maps `expression:`/`expr:` to the matching key.
+      #   2. Bare:   formula(a * b + 2)
+      #      — reconstructs the raw expression text from the token stream and
+      #      stores it under :expression. This is the form whose arithmetic
+      #      operators (STAR/SLASH/PLUS/MINUS) used to crash the lexer.
+      #
+      # Evaluation stays gated behind allow_eval in the generator either way.
+      #
+      # @return [Hash] { expression: String, ... }
+      #
+      def parse_formula_args
+        # Named form: leading IDENTIFIER ':' — let the generic parser handle it
+        # so formula(expression: "...") keeps mapping to args[:expression].
+        return parse_generic_args if current_token.type?(IDENTIFIER) && peek_token.type?(COLON)
+
+        parts = []
+        depth = 0
+
+        loop do
+          tok = current_token
+          break if tok.type?(EOF) || tok.type?(NEWLINE)
+          # The closing ) of the formula(...) call is at depth 0; inner grouping
+          # parens (e.g. formula((p + 1) * 2)) raise/lower depth so they don't
+          # terminate the loop early.
+          break if tok.type?(RPAREN) && depth.zero?
+
+          depth += 1 if tok.type?(LPAREN)
+          depth -= 1 if tok.type?(RPAREN)
+          parts << formula_token_text(tok)
+          advance
+        end
+
+        { expression: parts.join(" ").strip }
+      end
+
+      # Render a single token as a fragment of a formula expression string.
+      def formula_token_text(token)
+        case token.type
+        when STAR then "*"
+        when SLASH then "/"
+        when PLUS then "+"
+        when MINUS then "-"
+        when LPAREN then "("
+        when RPAREN then ")"
+        else token.value.to_s
+        end
+      end
+
+      # Parse a symbol argument (for custom functions)
+      #
+      # Grammar: COLON? IDENTIFIER
+      #
+      # @return [Symbol, nil] the symbol value
+      #
+
+      def parse_symbol_arg
+        if current_token.type?(COLON)
+          advance
+        end
+
+        if current_token.type?(IDENTIFIER) || current_token.type?(SYMBOL)
+          value = current_token.value.to_sym
+          advance
+          value
+        end
+      end
+
+      # Parse repeating_element arguments — positional or named.
+      #
+      #   repeating_element(uuid, 3)              => { type: "uuid", count: 3 }
+      #   repeating_element(type: uuid, count: 3) => { type: "uuid", count: 3 }
+      #   repeating_element("x", 3)               => { value: "x", count: 3 }
+      #
+      # A bare type/identifier is the element type, a bare number is the count, a
+      # bare string is a literal value to repeat. Without this the positional form
+      # fell through to parse_generic_args and mis-mapped both args onto :value
+      # (returning the count as a string).
+      #
+      # @return [Hash] parsed arguments
+      #
+      def parse_repeating_element_args
+        args = {}
+
+        loop do
+          break if current_token.type?(RPAREN)
+
+          if current_token.type?(IDENTIFIER) && peek_token.type?(COLON)
+            name = current_token.value.to_sym
+            advance
+            advance
+            args[name] = parse_arg_value
+          elsif current_token.type?(NUMBER)
+            args[:count] = current_token.value
+            advance
+          elsif current_token.type?(STRING)
+            args[:value] = current_token.value
+            advance
+          elsif current_token.type?(IDENTIFIER) || current_token.type?(TYPE)
+            args[:type] = current_token.value
+            advance
+          else
+            advance
+          end
+
+          break unless current_token.type?(COMMA)
+
+          advance
+        end
+
+        args
+      end
+
+      # Parse generic arguments (key:value pairs, ranges, etc.)
+      #
+      # Handles various argument formats:
+      # - Ranges: 18..80
+      # - Named args: min:10, max:100
+      # - Percentages: 50%
+      # - Booleans: true, false
+      # - Numbers: 42
+      #
+      # @return [Hash] parsed arguments
+      #
+
+      def parse_generic_args
+        args = {}
+
+        loop do
+          break if current_token.type?(RPAREN)
+
+          # Handle range like 18..80
+          if current_token.type?(RANGE)
+            range = current_token.value
+            args[:range] = range[:min]..range[:max]
+            advance
+
+          # Handle named args like min:10, max:100
+          elsif current_token.type?(IDENTIFIER)
+            name = current_token.value.to_sym
+            advance
+            if current_token.type?(COLON)
+              advance
+              value = parse_arg_value
+              args[name] = value
+            else
+              # Single identifier with no colon: check if it's a known locale code
+              if locale_code?(name)
+                args[:locale] = name
+              else
+                args[:value] = name
+              end
+            end
+
+          # Handle number
+          elsif current_token.type?(NUMBER)
+            num = current_token.value
+            advance
+            if current_token.type?(PERCENT)
+              advance
+              args[:probability] = num
+            else
+              args[:value] = num
+            end
+
+          # Handle true/false
+          elsif current_token.type?(TRUE_KW) || current_token.type?(FALSE_KW)
+            args[:value] = current_token.type?(TRUE_KW)
+            advance
+
+          # Handle string like "user_id" or "users.sender.id"
+          elsif current_token.type?(STRING)
+            args[:path] = current_token.value
+            advance
+          else
+            advance
+          end
+
+          break unless current_token.type?(COMMA)
+
+          advance
+        end
+
+        args
+      end
+
+      # Parse a single argument value
+      #
+      # @return [Object] the parsed value (number, string, boolean, etc.)
+      #
+
+      def parse_arg_value
+        token = current_token
+        case token.type
+        when NUMBER
+          advance
+          token.value
+        when TRUE_KW
+          advance
+          true
+        when FALSE_KW
+          advance
+          false
+        when STRING
+          advance
+          token.value
+        when SYMBOL
+
+          # Handle symbol literals like :ar, :en, :locale
+          advance
+          token.value
+        when IDENTIFIER
+          advance
+          token.value
+        when TYPE
+
+          # Handle uppercase identifiers like USD, HTTP, etc.
+          advance
+          token.value
+        when RANGE
+          advance
+          token.value[:min]..token.value[:max]
+        else
+          advance
+          token.value
+        end
+      end
+
+      # ==========================================================================
+
+      # Behavior Parsing
+      # ==========================================================================
+
+      # Parse a schema-level behavior
+      #
+      # Grammar: AT_BEHAVIOR value? NEWLINE
+      #
+      # @return [AST::BehaviorNode] the behavior node
+      #
+
+      def parse_behavior
+        token = expect(AT_BEHAVIOR)
+        name = token.value
+
+        value = parse_behavior_value
+        skip_newlines
+
+        AST::BehaviorNode.new(name: name, value: value, line: token.line)
+      end
+
+      # Parse a field-level behavior
+      #
+      # Grammar: AT_BEHAVIOR value?
+      #
+      # @return [AST::BehaviorNode] the behavior node
+      #
+
+      def parse_field_behavior
+        token = expect(AT_BEHAVIOR)
+        name = token.value
+        value = parse_behavior_value
+
+        AST::BehaviorNode.new(name: name, value: value, line: token.line)
+      end
+
+      # Parse a behavior value
+      #
+      # Handles:
+      # - Ranges: 100..500ms
+      # - Percentages: 10%
+      # - Numbers: 500
+      # - Duration values: 500ms, 2s
+      #
+      # @return [Object, nil] the parsed value
+      #
+      # Parse a behavior value
+      #
+      # Handles various behavior value formats including ranges with
+      # duration suffixes, percentages, and plain numbers.
+      #
+      # @return [Object, nil] the parsed value
+      #
+
+      def parse_behavior_value
+        if current_token.type?(RANGE)
+          range = current_token.value
+          advance
+          { min: range[:min], max: range[:max], suffix: range[:suffix] }
+        elsif current_token.type?(NUMBER)
+          num = current_token.value
+          advance
+          if current_token.type?(PERCENT)
+            advance
+            num  # Percentage as integer
+          elsif num.is_a?(Hash)
+            { value: num[:value], suffix: num[:suffix] }
+          else
+            num
+          end
+        else
+          nil
+        end
+      end
+
+      # Check if an identifier is a known locale code
+      #
+      # @param name [Symbol] Identifier to check
+      # @return [Boolean] true if the identifier is a known locale code
+      #
+      def locale_code?(name)
+        LOCALE_CODES.include?(name.to_s.downcase.to_sym)
+      end
+
+      # Known locale codes (two-letter or full locale identifiers)
+      LOCALE_CODES = %i[
+        en ar es fr de it pt ru zh ja ko hi
+        en_us en_gb ar_sa es_es fr_fr de_de it_it pt_br ru_ru zh_cn ja_jp ko_kr hi_in
+      ].freeze
+    end
+  end
+end