expressir 2.1.31 → 2.2.0

data/lib/expressir/express/builder.rb

@@ -0,0 +1,350 @@
+# frozen_string_literal: true
+
+require_relative "error"
+
+module Expressir
+  module Express
+    # Builder registry for AST node type handlers.
+    # Each builder is a callable object that transforms AST data into Model objects.
+    # This is the ONLY way to build models from AST - no Transformer fallback.
+    module Builder
+      class << self
+        attr_reader :source, :include_source
+
+        # Cache for snake_case conversions
+        SNAKE_CASE_CACHE = {} # rubocop:disable Style/MutableConstant
+
+        # Register a builder for a node type.
+        # @param node_type [Symbol] The AST node type
+        # @param builder [#call] Optional callable that takes (ast_data)
+        # @yield Block that takes (ast_data) if builder not provided
+        def register(node_type, builder = nil, &block)
+          @register ||= {}
+          @register[node_type] = builder || block
+        end
+
+        # Build a Model object from AST data.
+        # @param ast [Hash] The AST with node type as key
+        # @param source [String, nil] The original source code
+        # @param include_source [Boolean, nil] Whether to include source
+        # @return [Model::ModelElement] The built model object
+        def build(ast, source: nil, include_source: nil)
+          return nil unless ast
+
+          # Only set instance variables on first call (when they're provided)
+          # Recursive calls pass nil which shouldn't override the saved values
+          @source = source unless source.nil?
+          @include_source = include_source unless include_source.nil?
+
+          # Optimized: Hash is 90%+ of cases, check it first
+          case ast
+          when Hash
+            node_type = ast.keys.first
+            node_data = ast[node_type]
+
+            handler_key = cached_snake_case(node_type)
+            snake_data = fast_convert_keys(node_data)
+
+            builder = @register[handler_key]
+            raise Error::UnknownNodeTypeError, node_type unless builder
+
+            result = builder.call(snake_data)
+
+            # Always store source_offset for remark attachment (if source is available)
+            # Only store source text when include_source is requested
+            if @source && result.is_a?(Model::ModelElement)
+              source_info = extract_source_info(node_data)
+              if source_info
+                # Store offset for remark attachment (always needed)
+                result.source_offset = source_info[:offset]
+                # Store source text only when explicitly requested
+                if @include_source
+                  result.source = source_info[:text]
+                end
+              end
+            end
+
+            result
+          when Array
+            ast.map do |item|
+              build(item)
+            end
+          when Parsanol::Slice
+            ast.to_s
+          else
+            ast
+          end
+        end
+
+        # Build with remark attachment
+        def build_with_remarks(ast, source: nil, include_source: nil)
+          # Reset instance variables at the start of a top-level build
+          # This ensures state from previous parses is cleared
+          @source = source
+          @include_source = include_source
+
+          result = build(ast)
+
+          if source && result
+            attacher = RemarkAttacher.new(source)
+            attacher.attach(result)
+          end
+
+          result
+        end
+
+        # Check if a builder is registered for a node type.
+        def registered?(node_type)
+          @register&.key?(node_type)
+        end
+
+        # Get all registered node types.
+        def registered_types
+          @register&.keys || []
+        end
+
+        # Build optional (returns nil if ast is nil)
+        def build_optional(ast)
+          return nil unless ast
+
+          build(ast)
+        end
+
+        # Build children (array of AST nodes)
+        # Optimized to avoid intermediate array allocations
+        def build_children(ast_array)
+          return [] unless ast_array
+
+          # Handle single element (common case)
+          unless ast_array.is_a?(Array)
+            return ast_array.nil? ? [] : [build(ast_array)].compact
+          end
+
+          # Build result in single pass, avoiding flatten/compact/map chain
+          result = []
+          ast_array.each do |item|
+            next if item.nil?
+
+            case item
+            when Array
+              item.each do |sub|
+                result << build(sub) unless sub.nil?
+              end
+            else
+              built = build(item)
+              result << built if built
+            end
+          end
+          result
+        end
+
+        # Fast build methods - call registered builder directly without hash wrapping
+        # These are optimized for hot paths in expression building
+        # NOTE: These assume data is already snake_case (no key conversion needed)
+
+        # Call a registered builder directly with data (avoids hash wrapper allocation)
+        # @param node_type [Symbol] The node type key
+        # @param data The data to pass to the builder (already snake_case)
+        def build_node(node_type, data)
+          builder = @register&.[](node_type)
+          raise Error::UnknownNodeTypeError, node_type unless builder
+
+          builder.call(data)
+        end
+
+        # Fast path for term nodes
+        def build_term(data)
+          build_node(:term, data)
+        end
+
+        # Fast path for factor nodes
+        def build_factor(data)
+          build_node(:factor, data)
+        end
+
+        # Fast path for simple_factor nodes
+        def build_simple_factor(data)
+          build_node(:simple_factor, data)
+        end
+
+        # Fast path for primary nodes
+        def build_primary(data)
+          build_node(:primary, data)
+        end
+
+        # Fast path for expression nodes
+        def build_expression(data)
+          build_node(:expression, data)
+        end
+
+        # Fast path for simple_expression nodes
+        def build_simple_expression(data)
+          build_node(:simple_expression, data)
+        end
+
+        private
+
+        # Cached snake_case conversion
+        def cached_snake_case(name)
+          SNAKE_CASE_CACHE[name] ||= begin
+            str = name.to_s
+            # Check if already snake_case
+            if /^[a-z_]+$/.match?(str)
+              str.to_sym
+            else
+              str
+                .gsub(/([A-Z]+)([A-Z][a-z])/, '\1_\2')
+                .gsub(/([a-z\d])([A-Z])/, '\1_\2')
+                .downcase
+                .to_sym
+            end
+          end
+        end
+
+        # Optimized key conversion - returns original object when no conversion needed
+        # This avoids unnecessary allocations for AST nodes that don't need key conversion
+        def fast_convert_keys(obj)
+          case obj
+          when Hash
+            return obj if obj.empty?
+
+            # First pass: check if any conversion is needed
+            keys = obj.keys
+            needs_conversion = false
+            converted_values = nil
+
+            keys.each do |k|
+              key_str = k.to_s
+              # Check if key needs conversion (has uppercase)
+              if key_str.match?(/[A-Z]/)
+                needs_conversion = true
+              end
+
+              # Check if value needs conversion
+              val = obj[k]
+              case val
+              when Hash
+                next if val.empty?
+
+                converted_val = fast_convert_keys(val)
+                if !converted_val.equal?(val) # Identity check - same object?
+                  needs_conversion = true
+                  converted_values ||= {}
+                  converted_values[k] = converted_val
+                end
+              when Array
+                next if val.empty?
+
+                converted_val = fast_convert_keys(val)
+                if !converted_val.equal?(val)
+                  needs_conversion = true
+                  converted_values ||= {}
+                  converted_values[k] = converted_val
+                end
+              end
+            end
+
+            # Return original if no conversion needed (zero allocation!)
+            return obj unless needs_conversion
+
+            # Build result only when necessary
+            result = {}
+            keys.each do |k|
+              key_str = k.to_s
+              new_key = key_str.match?(/[A-Z]/) ? cached_snake_case(k) : k
+              new_val = converted_values&.key?(k) ? converted_values[k] : obj[k]
+              result[new_key] = new_val
+            end
+            result
+          when Array
+            return obj if obj.empty?
+
+            # Check if any element needs conversion
+            needs_conversion = false
+            result = []
+
+            obj.each do |item|
+              case item
+              when Hash
+                next if item.empty?
+
+                converted = fast_convert_keys(item)
+                result << converted
+                needs_conversion = true unless converted.equal?(item)
+              when Array
+                next if item.empty?
+
+                converted = fast_convert_keys(item)
+                result << converted
+                needs_conversion = true unless converted.equal?(item)
+              else
+                result << item
+              end
+            end
+
+            # Return original if no conversion needed
+            needs_conversion ? result : obj
+          else
+            obj
+          end
+        end
+
+        def to_snake_case(name)
+          cached_snake_case(name)
+        end
+
+        def convert_keys_to_snake_case(obj)
+          fast_convert_keys(obj)
+        end
+
+        def extract_source_info(data)
+          return nil unless data
+          return nil unless @source
+
+          slice = find_slice(data)
+          return nil unless slice
+
+          {
+            text: @source[slice.offset...(slice.offset + slice.length)]&.strip,
+            offset: slice.offset,
+          }
+        end
+
+        def find_slice(data, depth = 0)
+          return nil if depth > 10
+
+          case data
+          when Parsanol::Slice
+            data
+          when Hash
+            # Skip 'spaces' key which contains whitespace/comments before content
+            # Look for 'str' key first as it usually contains the actual content
+            if data.key?(:str) && data[:str].is_a?(Parsanol::Slice)
+              return data[:str]
+            end
+
+            # Then look in other keys, skipping 'spaces'
+            data.each do |key, value|
+              next if key == :spaces
+
+              return value if value.is_a?(Parsanol::Slice)
+
+              result = find_slice(value, depth + 1)
+              return result if result
+            end
+            nil
+          when Array
+            data.each do |item|
+              result = find_slice(item, depth + 1)
+              return result if result
+            end
+            nil
+          end
+        end
+      end
+    end
+  end
+end
+
+# Top-level alias for convenience in builder files
+Builder = Expressir::Express::Builder

data/lib/expressir/express/builders/attribute_decl_builder.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+
+module Expressir
+  module Express
+    module Builders
+      # Builds attribute_decl nodes.
+      class AttributeDeclBuilder
+        include Helpers
+
+        def call(ast_data)
+          id = Builder.build_optional(ast_data[:attribute_id])
+          supertype_attribute = nil
+
+          if ast_data[:redeclared_attribute].is_a?(Hash)
+            redeclared = ast_data[:redeclared_attribute]
+            if redeclared[:qualified_attribute].is_a?(Hash)
+              supertype_attribute = Builder.build({ qualified_attribute: redeclared[:qualified_attribute] })
+
+              if supertype_attribute.is_a?(Expressir::Model::References::AttributeReference)
+                id ||= supertype_attribute.attribute&.id
+              end
+            end
+            id = Builder.build_optional(redeclared[:attribute_id]) if redeclared[:attribute_id]
+          end
+
+          Expressir::Model::Declarations::Attribute.new(
+            id: id,
+            supertype_attribute: supertype_attribute,
+          )
+        end
+      end
+    end
+  end
+end
+
+Builder.register(:attribute_decl, Expressir::Express::Builders::AttributeDeclBuilder.new)

data/lib/expressir/express/builders/built_in_builder.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+
+module Expressir
+  module Express
+    module Builders
+      # Builds built-in constant, function, and procedure reference nodes.
+      class BuiltInBuilder
+        include Helpers
+
+        def build_built_in_constant(ast_data)
+          id = extract_nested_text(ast_data)
+          Expressir::Model::References::SimpleReference.new(id: id)
+        end
+
+        def build_built_in_function(ast_data)
+          id = extract_text(ast_data[:str])
+          Expressir::Model::References::SimpleReference.new(id: id)
+        end
+
+        def build_built_in_procedure(ast_data)
+          id = extract_text(ast_data[:str])
+          Expressir::Model::References::SimpleReference.new(id: id)
+        end
+
+        def build_general_ref(ast_data)
+          if ast_data[:constant_ref]
+            Builder.build({ constant_ref: ast_data[:constant_ref] })
+          elsif ast_data[:function_ref]
+            Builder.build({ function_ref: ast_data[:function_ref] })
+          elsif ast_data[:parameter_ref]
+            Builder.build({ parameter_ref: ast_data[:parameter_ref] })
+          elsif ast_data[:variable_ref]
+            Builder.build({ variable_ref: ast_data[:variable_ref] })
+          elsif ast_data[:entity_ref]
+            Builder.build({ entity_ref: ast_data[:entity_ref] })
+          elsif ast_data[:type_ref]
+            Builder.build({ type_ref: ast_data[:type_ref] })
+          elsif ast_data[:attribute_ref]
+            Builder.build({ attribute_ref: ast_data[:attribute_ref] })
+          elsif ast_data[:enumeration_ref]
+            Builder.build({ enumeration_ref: ast_data[:enumeration_ref] })
+          end
+        end
+
+        def build_named_types(ast_data)
+          if ast_data[:entity_ref]
+            Builder.build({ entity_ref: ast_data[:entity_ref] })
+          elsif ast_data[:type_ref]
+            Builder.build({ type_ref: ast_data[:type_ref] })
+          end
+        end
+
+        def build_item(ast_data)
+          if ast_data[:entity_ref]
+            Builder.build({ entity_ref: ast_data[:entity_ref] })
+          elsif ast_data[:type_ref]
+            Builder.build({ type_ref: ast_data[:type_ref] })
+          end
+        end
+
+        def build_procedure_ref(ast_data)
+          id = extract_id_ref(ast_data)
+          Expressir::Model::References::SimpleReference.new(id: id)
+        end
+
+        def build_schema_ref(ast_data)
+          id = extract_id_ref(ast_data)
+          Expressir::Model::References::SimpleReference.new(id: id)
+        end
+      end
+    end
+  end
+end
+
+builder = Expressir::Express::Builders::BuiltInBuilder.new
+
+Builder.register(:built_in_constant) { |d| builder.build_built_in_constant(d) }
+Builder.register(:built_in_function) { |d| builder.build_built_in_function(d) }
+Builder.register(:built_in_procedure) do |d|
+  builder.build_built_in_procedure(d)
+end
+Builder.register(:general_ref) { |d| builder.build_general_ref(d) }
+Builder.register(:named_types) { |d| builder.build_named_types(d) }
+Builder.register(:item) { |d| builder.build_item(d) }
+Builder.register(:procedure_ref) { |d| builder.build_procedure_ref(d) }
+Builder.register(:schema_ref) { |d| builder.build_schema_ref(d) }

data/lib/expressir/express/builders/constant_builder.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+
+module Expressir
+  module Express
+    module Builders
+      # Builds constant and local variable nodes.
+      class ConstantBuilder
+        include Helpers
+
+        def build_constant_decl(ast_data)
+          Builder.build_children(ast_data[:constant_body])
+        end
+
+        def build_constant_body(ast_data)
+          id = Builder.build_optional(ast_data[:constant_id])
+          type = Builder.build_optional(ast_data[:instantiable_type])
+          expression = Builder.build_optional(ast_data[:expression])
+
+          Expressir::Model::Declarations::Constant.new(id: id, type: type,
+                                                       expression: expression)
+        end
+
+        def build_local_decl(ast_data)
+          Builder.build_children(ast_data[:local_variable]).flatten.compact
+        end
+
+        def build_local_variable(ast_data)
+          var_id_data = ast_data[:list_of_variable_id] || ast_data
+
+          ids_data = if var_id_data.is_a?(Hash) && var_id_data[:variable_id]
+                       var_id_data[:variable_id]
+                     else
+                       var_id_data
+                     end
+
+          ids = if ids_data.is_a?(Hash)
+                  [Builder.build({ variable_id: ids_data })]
+                elsif ids_data.is_a?(Array)
+                  ids_data.map { |id| Builder.build({ variable_id: id }) }
+                else
+                  []
+                end
+
+          type = Builder.build_optional(ast_data[:parameter_type])
+          expression = if ast_data[:expression]
+                         Builder.build({ expression: ast_data[:expression] })
+                       end
+
+          ids.flatten.compact.map do |id|
+            Expressir::Model::Declarations::Variable.new(id: id, type: type,
+                                                         expression: expression)
+          end
+        end
+
+        def build_formal_parameter(ast_data)
+          param_id_data = ast_data[:list_of_parameter_id] || ast_data
+
+          ids_data = if param_id_data.is_a?(Hash) && param_id_data[:parameter_id]
+                       param_id_data[:parameter_id]
+                     else
+                       param_id_data
+                     end
+
+          ids = if ids_data.is_a?(Hash)
+                  [Builder.build({ parameter_id: ids_data })]
+                elsif ids_data.is_a?(Array)
+                  ids_data.map { |id| Builder.build({ parameter_id: id }) }
+                else
+                  []
+                end
+
+          type = Builder.build_optional(ast_data[:parameter_type])
+          ids.flatten.compact.map { |id| Expressir::Model::Declarations::Parameter.new(id: id, type: type) }
+        end
+
+        def build_procedure_head_parameter(ast_data)
+          formal_param_data = ast_data[:formal_parameter]
+          params = if formal_param_data.is_a?(Hash)
+                     result = Builder.build({ formal_parameter: formal_param_data })
+                     [result].flatten.compact
+                   elsif formal_param_data.is_a?(Array)
+                     formal_param_data.map do |fp|
+                       Builder.build({ formal_parameter: fp })
+                     end.flatten.compact
+                   else
+                     []
+                   end
+          is_var = !ast_data[:t_var].nil?
+
+          if is_var
+            params.map do |p|
+              Expressir::Model::Declarations::Parameter.new(id: p.id,
+                                                            var: true, type: p.type)
+            end
+          else
+            params
+          end
+        end
+      end
+    end
+  end
+end
+
+builder = Expressir::Express::Builders::ConstantBuilder.new
+
+Builder.register(:constant_decl) { |d| builder.build_constant_decl(d) }
+Builder.register(:constant_body) { |d| builder.build_constant_body(d) }
+Builder.register(:local_decl) { |d| builder.build_local_decl(d) }
+Builder.register(:local_variable) { |d| builder.build_local_variable(d) }
+Builder.register(:formal_parameter) { |d| builder.build_formal_parameter(d) }
+Builder.register(:procedure_head_parameter) do |d|
+  builder.build_procedure_head_parameter(d)
+end

data/lib/expressir/express/builders/declaration_builder.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require_relative "helpers"
+
+module Expressir
+  module Express
+    module Builders
+      # Builds declaration nodes - dispatches to specific declaration type.
+      class DeclarationBuilder
+        def call(ast_data)
+          %i[entity_decl function_decl procedure_decl subtype_constraint_decl
+             type_decl].each do |key|
+            if ast_data[key]
+              return Builder.build({ key => ast_data[key] })
+            end
+          end
+          nil
+        end
+      end
+    end
+  end
+end
+
+Builder.register(:declaration, Expressir::Express::Builders::DeclarationBuilder.new)

data/lib/expressir/express/builders/derive_clause_builder.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Expressir
+  module Express
+    module Builders
+      # Builds derive_clause nodes.
+      class DeriveClauseBuilder
+        def call(ast_data)
+          Builder.build_children(ast_data[:derived_attr])
+        end
+      end
+    end
+  end
+end
+
+Builder.register(:derive_clause, Expressir::Express::Builders::DeriveClauseBuilder.new)

data/lib/expressir/express/builders/derived_attr_builder.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Expressir
+  module Express
+    module Builders
+      # Builds derived_attr nodes.
+      class DerivedAttrBuilder
+        def call(ast_data)
+          attr_decl_data = ast_data[:attribute_decl]
+          attr = if attr_decl_data.is_a?(Hash)
+                   Builder.build({ attribute_decl: attr_decl_data })
+                 end
+          type = Builder.build_optional(ast_data[:parameter_type])
+          expression = Builder.build_optional(ast_data[:expression])
+
+          Expressir::Model::Declarations::DerivedAttribute.new(
+            id: attr&.id,
+            supertype_attribute: attr&.supertype_attribute,
+            type: type,
+            expression: expression,
+          )
+        end
+      end
+    end
+  end
+end
+
+Builder.register(:derived_attr, Expressir::Express::Builders::DerivedAttrBuilder.new)

data/lib/expressir/express/builders/domain_rule_builder.rb

@@ -0,0 +1,21 @@
+# frozen_string_literal: true
+
+module Expressir
+  module Express
+    module Builders
+      # Builds domain_rule nodes.
+      class DomainRuleBuilder
+        def call(ast_data)
+          inner_data = ast_data[:domain_rule] || ast_data
+
+          id = Builder.build_optional(inner_data[:rule_label_id])
+          expression = Builder.build_optional(inner_data[:expression])
+          Expressir::Model::Declarations::WhereRule.new(id: id,
+                                                        expression: expression)
+        end
+      end
+    end
+  end
+end
+
+Builder.register(:domain_rule, Expressir::Express::Builders::DomainRuleBuilder.new)