expressir 2.4.0 → 2.4.2

data/lib/expressir/coverage.rb

@@ -3,53 +3,39 @@ require "pathname"
 module Expressir
   # Coverage module for calculating documentation coverage of EXPRESS entities
   module Coverage
-    # Mapping of EXPRESS entity type names to their corresponding class names
-    ENTITY_TYPE_MAP = {
-      "TYPE" => "Expressir::Model::Declarations::Type",
-      "ENTITY" => "Expressir::Model::Declarations::Entity",
-      "CONSTANT" => "Expressir::Model::Declarations::Constant",
-      "FUNCTION" => "Expressir::Model::Declarations::Function",
-      "RULE" => "Expressir::Model::Declarations::Rule",
-      "PROCEDURE" => "Expressir::Model::Declarations::Procedure",
-      "SUBTYPE_CONSTRAINT" => "Expressir::Model::Declarations::SubtypeConstraint",
-      "PARAMETER" => "Expressir::Model::Declarations::Parameter",
-      "VARIABLE" => "Expressir::Model::Declarations::Variable",
-      "ATTRIBUTE" => "Expressir::Model::Declarations::Attribute",
-      "DERIVED_ATTRIBUTE" => "Expressir::Model::Declarations::DerivedAttribute",
-      "INVERSE_ATTRIBUTE" => "Expressir::Model::Declarations::InverseAttribute",
-      "UNIQUE_RULE" => "Expressir::Model::Declarations::UniqueRule",
-      "WHERE_RULE" => "Expressir::Model::Declarations::WhereRule",
-      "ENUMERATION_ITEM" => "Expressir::Model::DataTypes::EnumerationItem",
-      "INTERFACE" => "Expressir::Model::Declarations::Interface",
-      "INTERFACE_ITEM" => "Expressir::Model::Declarations::InterfaceItem",
-      "INTERFACED_ITEM" => "Expressir::Model::Declarations::InterfacedItem",
-      "SCHEMA_VERSION" => "Expressir::Model::Declarations::SchemaVersion",
-      "SCHEMA_VERSION_ITEM" => "Expressir::Model::Declarations::SchemaVersionItem",
-    }.freeze
-
-    # Mapping of class names to EXPRESS entity type names (for proper formatting)
-    CLASS_TO_EXPRESS_TYPE_MAP = {
-      "Type" => "TYPE",
-      "Entity" => "ENTITY",
-      "Constant" => "CONSTANT",
-      "Function" => "FUNCTION",
-      "Rule" => "RULE",
-      "Procedure" => "PROCEDURE",
-      "SubtypeConstraint" => "SUBTYPE_CONSTRAINT",
-      "Parameter" => "PARAMETER",
-      "Variable" => "VARIABLE",
-      "Attribute" => "ATTRIBUTE",
-      "DerivedAttribute" => "DERIVED_ATTRIBUTE",
-      "InverseAttribute" => "INVERSE_ATTRIBUTE",
-      "UniqueRule" => "UNIQUE_RULE",
-      "WhereRule" => "WHERE_RULE",
-      "EnumerationItem" => "ENUMERATION_ITEM",
-      "Interface" => "INTERFACE",
-      "InterfaceItem" => "INTERFACE_ITEM",
-      "InterfacedItem" => "INTERFACED_ITEM",
-      "SchemaVersion" => "SCHEMA_VERSION",
-      "SchemaVersionItem" => "SCHEMA_VERSION_ITEM",
-    }.freeze
+    # Single source of truth: EXPRESS type name → Ruby class name pairs.
+    # ENTITY_TYPE_MAP and CLASS_TO_EXPRESS_TYPE_MAP are derived from this
+    # so the two never drift out of sync.
+    TYPE_PAIRS = [
+      ["TYPE", "Expressir::Model::Declarations::Type"],
+      ["ENTITY", "Expressir::Model::Declarations::Entity"],
+      ["CONSTANT", "Expressir::Model::Declarations::Constant"],
+      ["FUNCTION", "Expressir::Model::Declarations::Function"],
+      ["RULE", "Expressir::Model::Declarations::Rule"],
+      ["PROCEDURE", "Expressir::Model::Declarations::Procedure"],
+      ["SUBTYPE_CONSTRAINT", "Expressir::Model::Declarations::SubtypeConstraint"],
+      ["PARAMETER", "Expressir::Model::Declarations::Parameter"],
+      ["VARIABLE", "Expressir::Model::Declarations::Variable"],
+      ["ATTRIBUTE", "Expressir::Model::Declarations::Attribute"],
+      ["DERIVED_ATTRIBUTE", "Expressir::Model::Declarations::DerivedAttribute"],
+      ["INVERSE_ATTRIBUTE", "Expressir::Model::Declarations::InverseAttribute"],
+      ["UNIQUE_RULE", "Expressir::Model::Declarations::UniqueRule"],
+      ["WHERE_RULE", "Expressir::Model::Declarations::WhereRule"],
+      ["ENUMERATION_ITEM", "Expressir::Model::DataTypes::EnumerationItem"],
+      ["INTERFACE", "Expressir::Model::Declarations::Interface"],
+      ["INTERFACE_ITEM", "Expressir::Model::Declarations::InterfaceItem"],
+      ["INTERFACED_ITEM", "Expressir::Model::Declarations::InterfacedItem"],
+      ["SCHEMA_VERSION", "Expressir::Model::Declarations::SchemaVersion"],
+      ["SCHEMA_VERSION_ITEM", "Expressir::Model::Declarations::SchemaVersionItem"],
+    ].freeze
+
+    # EXPRESS entity type name → Ruby class name.
+    ENTITY_TYPE_MAP = TYPE_PAIRS.to_h.freeze
+
+    # Short Ruby class name → EXPRESS entity type name.
+    CLASS_TO_EXPRESS_TYPE_MAP = TYPE_PAIRS.to_h do |express_name, ruby_class|
+      [ruby_class.split("::").last, express_name]
+    end.freeze
 
     # Available TYPE subtypes based on data types
     TYPE_SUBTYPES = %w[
@@ -401,78 +387,24 @@ module Expressir
         entities.concat(container.unique_rules) if container.unique_rules
         entities.concat(container.where_rules) if container.where_rules
 
-      when Expressir::Model::Declarations::Function
-        # Function nested entities
-        entities.concat(container.parameters) if container.parameters
-        entities.concat(container.variables) if container.variables
-        entities.concat(container.constants) if container.constants
-        entities.concat(container.types) if container.types
-        entities.concat(container.entities) if container.entities
-        entities.concat(container.functions) if container.functions
-        entities.concat(container.procedures) if container.procedures
-        entities.concat(container.subtype_constraints) if container.subtype_constraints
-
-        # Recursively find nested entities in nested containers
-        container.types&.each do |type|
-          entities.concat(find_nested_entities(type))
-        end
-        container.entities&.each do |entity|
-          entities.concat(find_nested_entities(entity))
-        end
-        container.functions&.each do |function|
-          entities.concat(find_nested_entities(function))
-        end
-        container.procedures&.each do |procedure|
-          entities.concat(find_nested_entities(procedure))
-        end
-
-      when Expressir::Model::Declarations::Rule
-        # Rule nested entities
-        entities.concat(container.variables) if container.variables
-        entities.concat(container.constants) if container.constants
-        entities.concat(container.types) if container.types
-        entities.concat(container.entities) if container.entities
-        entities.concat(container.functions) if container.functions
-        entities.concat(container.procedures) if container.procedures
-        entities.concat(container.subtype_constraints) if container.subtype_constraints
-
-        # Recursively find nested entities in nested containers
-        container.types&.each do |type|
-          entities.concat(find_nested_entities(type))
-        end
-        container.entities&.each do |entity|
-          entities.concat(find_nested_entities(entity))
-        end
-        container.functions&.each do |function|
-          entities.concat(find_nested_entities(function))
-        end
-        container.procedures&.each do |procedure|
-          entities.concat(find_nested_entities(procedure))
+      when Expressir::Model::Declarations::Function,
+           Expressir::Model::Declarations::Procedure,
+           Expressir::Model::Declarations::Rule
+        # All three scope containers follow the same nested-entity pattern.
+        # Derive the collection list from the model's own declaration rather
+        # than maintaining three separate hand-coded branches.
+        nested_attrs = container.class.collection_attributes_list - %i[
+          statements remark_items where_rules informal_propositions applies_to
+        ]
+        nested_attrs.each do |attr|
+          collection = container.public_send(attr)
+          entities.concat(collection) if collection.is_a?(Array)
         end
 
-      when Expressir::Model::Declarations::Procedure
-        # Procedure nested entities
-        entities.concat(container.parameters) if container.parameters
-        entities.concat(container.variables) if container.variables
-        entities.concat(container.constants) if container.constants
-        entities.concat(container.types) if container.types
-        entities.concat(container.entities) if container.entities
-        entities.concat(container.functions) if container.functions
-        entities.concat(container.procedures) if container.procedures
-        entities.concat(container.subtype_constraints) if container.subtype_constraints
-
-        # Recursively find nested entities in nested containers
-        container.types&.each do |type|
-          entities.concat(find_nested_entities(type))
-        end
-        container.entities&.each do |entity|
-          entities.concat(find_nested_entities(entity))
-        end
-        container.functions&.each do |function|
-          entities.concat(find_nested_entities(function))
-        end
-        container.procedures&.each do |procedure|
-          entities.concat(find_nested_entities(procedure))
+        # Recursively find nested entities in nested scope containers
+        %i[types entities functions procedures].each do |attr|
+          collection = container.public_send(attr)
+          collection&.each { |item| entities.concat(find_nested_entities(item)) }
         end
 
       when Expressir::Model::Declarations::Interface

data/lib/expressir/express/ast_key_converter.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+module Expressir
+  module Express
+    # Converts native-AST CamelCase keys to the snake_case keys the
+    # builders consume.
+    #
+    # build() descends into child nodes whose subtrees the parent already
+    # converted, so unchanged containers are marked with an invisible
+    # instance variable and skipped on re-visits — without it, every
+    # subtree is re-scanned once per ancestor level (~60 convert calls per
+    # model node on real schemas). The marker is invisible to equality,
+    # hashing, and inspection.
+    class AstKeyConverter
+      SNAKED_MARKER = :@_expressir_keys_snaked
+      UPPERCASE_PATTERN = /[A-Z]/
+
+      class << self
+        # Thread-local snake_case conversion cache. Thread-local avoids the
+        # mutable-constant anti-pattern while remaining thread-safe. The
+        # cache is bounded by the number of unique AST node-type names.
+        def snake_case(name)
+          cache[name] ||= begin
+            str = name.to_s
+            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
+
+        # Returns the original object when no conversion is needed; the
+        # common no-conversion case allocates nothing and the conversion
+        # case walks the keys once.
+        def convert(obj)
+          case obj
+          when Hash
+            return obj if obj.empty?
+            return obj if obj.instance_variable_defined?(SNAKED_MARKER)
+
+            keys = obj.keys
+            converted_values = nil
+            new_keys = nil
+
+            keys.each_with_index do |k, i|
+              val = obj[k]
+              case val
+              when Hash, Array
+                unless val.empty?
+                  converted_val = convert(val)
+                  (converted_values ||= {})[k] = converted_val unless converted_val.equal?(val)
+                end
+              end
+
+              if k.match?(UPPERCASE_PATTERN)
+                (new_keys ||= keys.dup)[i] = snake_case(k)
+              end
+            end
+
+            return mark_snaked(obj) unless new_keys || converted_values
+
+            result = {}
+            keys.each_with_index do |k, i|
+              key = new_keys&.[](i) || k
+              result[key] = converted_values&.key?(k) ? converted_values[k] : obj[k]
+            end
+            mark_snaked(result)
+          when Array
+            return obj if obj.empty?
+            return obj if obj.instance_variable_defined?(SNAKED_MARKER)
+
+            needs_conversion = false
+            result = []
+
+            obj.each do |item|
+              case item
+              when Hash, Array
+                next if item.empty?
+
+                converted = convert(item)
+                result << converted
+                needs_conversion = true unless converted.equal?(item)
+              else
+                result << item
+              end
+            end
+
+            needs_conversion ? mark_snaked(result) : mark_snaked(obj)
+          else
+            obj
+          end
+        end
+
+        private
+
+        def cache
+          Thread.current[:expressir_snake_case_cache] ||= {}
+        end
+
+        def mark_snaked(obj)
+          obj.instance_variable_set(SNAKED_MARKER, true)
+          obj
+        rescue FrozenError
+          obj
+        end
+      end
+    end
+  end
+end

data/lib/expressir/express/builder.rb

@@ -7,10 +7,26 @@ module Expressir
     # This is the ONLY way to build models from AST - no Transformer fallback.
     module Builder
       class << self
-        attr_reader :source, :include_source
+        # Thread-local key under which the current BuilderContext is stored
+        # for the duration of a build_with_remarks call. Recursive build
+        # calls read source/include_source from here instead of from
+        # class-level mutable state.
+        CONTEXT_KEY = :expressir_builder_context
+
+        # Returns the BuilderContext for the current thread, or nil if no
+        # build is in progress.
+        def current_context
+          Thread.current[CONTEXT_KEY]
+        end
+
+        # Convenience accessors — read from the current context.
+        def source
+          current_context&.source
+        end
 
-        # Cache for snake_case conversions
-        SNAKE_CASE_CACHE = {} # rubocop:disable Style/MutableConstant
+        def include_source
+          current_context&.include_source
+        end
 
         # Register a builder for a node type.
         # @param node_type [Symbol] The AST node type
@@ -23,40 +39,18 @@ module Expressir
 
         # 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
-        # Operator tokens that return nil (separators, punctuation)
-        # When these appear as the first key in a multi-key hash, they should be
-        # skipped in favor of the content key. This handles grammar patterns like
-        # `element >> (op_comma >> element).repeat` which produce
-        # {:op_comma => ..., :element => {...}}.
-        OPERATOR_TOKENS = Set.new(%i[
-                                    op_comma op_colon op_decl op_delim op_leftparen op_rightparen
-                                    op_leftbracket op_rightbracket op_left_curly_brace op_right_curly_brace
-                                    op_period op_pipe op_double_backslash op_double_pipe op_double_asterisk
-                                    op_asterisk op_slash op_plus op_minus op_less_equal op_greater_equal
-                                    op_less_greater op_less_than op_greater_than op_equals
-                                    op_colon_less_greater_colon op_colon_equals_colon
-                                    op_query_begin op_query_end op_question_mark
-                                  ]).freeze
-
-        def build(ast, source: nil, include_source: nil)
+        def build(ast)
           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)
+            handler_key = AstKeyConverter.snake_case(node_type)
+            snake_data = AstKeyConverter.convert(node_data)
 
             builder = @register[handler_key]
             if builder
@@ -68,26 +62,27 @@ module Expressir
                 return result
               end
 
-              # Slow path: operator token returned nil in multi-key hash.
-              # Try other keys for actual content. This handles
-              # {:op_comma => ..., :element => {...}} where the first key
-              # is an operator separator rather than a content key.
-              if OPERATOR_TOKENS.include?(handler_key)
-                ast.each_key do |key|
-                  next if key == node_type
-
-                  h_key = cached_snake_case(key)
-                  h_builder = @register[h_key]
-                  next unless h_builder
-
-                  n_data = ast[key]
-                  s_data = fast_convert_keys(n_data)
-                  result = h_builder.call(s_data)
-
-                  unless result.nil?
-                    attach_source_info(result, n_data)
-                    return result
-                  end
+              # Slow path: first-key builder returned nil in a multi-key
+              # hash. Try remaining keys for actual content. This handles
+              # grammar patterns like `element >> (op_comma >> element).repeat`
+              # which produce {:op_comma => ..., :element => {...}} where
+              # the first key is an operator separator.
+              # Previously gated by a hand-maintained OPERATOR_TOKENS set;
+              # now tries all remaining keys unconditionally (TODO.bugs/21).
+              ast.each_key do |key|
+                next if key == node_type
+
+                h_key = AstKeyConverter.snake_case(key)
+                h_builder = @register[h_key]
+                next unless h_builder
+
+                n_data = ast[key]
+                s_data = AstKeyConverter.convert(n_data)
+                result = h_builder.call(s_data)
+
+                unless result.nil?
+                  attach_source_info(result, n_data)
+                  return result
                 end
               end
             else
@@ -105,12 +100,23 @@ module Expressir
           end
         end
 
-        # Build with remark attachment
+        # Build with remark attachment.
+        #
+        # Sets up a BuilderContext as a thread-local for the duration of the
+        # build so recursive build calls can read source/include_source via
+        # `Builder.source` / `Builder.include_source`. The previous context
+        # (if any) is restored on exit so nested builds are reentrant.
         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
+          # Trigger BuilderRegistry autoload so all AST node type handlers
+          # are registered before build() runs. The reference to
+          # BuilderRegistry resolves the autoload defined in express.rb.
+          BuilderRegistry
+
+          previous = Thread.current[CONTEXT_KEY]
+          Thread.current[CONTEXT_KEY] = BuilderContext.new(
+            source: source,
+            include_source: include_source,
+          )
 
           result = build(ast)
 
@@ -122,6 +128,8 @@ module Expressir
           end
 
           result
+        ensure
+          Thread.current[CONTEXT_KEY] = previous
         end
 
         # Check if a builder is registered for a node type.
@@ -203,164 +211,33 @@ module Expressir
           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
-
+        # Keys containing uppercase need snake-casing; testing the key
+        # directly avoids allocating `to_s` strings per key per pass.
+        # Key conversion lives in AstKeyConverter (MECE: converting AST
+        # keys is not building models).
         def extract_source_info(data)
           return nil unless data
-          return nil unless @source
+
+          src = source
+          return nil unless src
 
           slice = find_slice(data)
           return nil unless slice
 
           {
-            text: @source[slice.offset...(slice.offset + slice.length)]&.strip,
+            text: src[slice.offset...(slice.offset + slice.length)]&.strip,
             offset: slice.offset,
           }
         end
 
         def attach_source_info(result, data)
-          return unless @source && result.is_a?(Expressir::Model::ModelElement)
+          return unless source && result.is_a?(Expressir::Model::ModelElement)
 
           source_info = extract_source_info(data)
           return unless source_info
 
           result.source_offset = source_info[:offset]
-          result.source = source_info[:text] if @include_source
+          result.source = source_info[:text] if include_source
         end
 
         def find_slice(data, depth = 0)

data/lib/expressir/express/builder_context.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Expressir
+  module Express
+    # Value object carrying the per-build context that Builder needs to
+    # attach source info to model elements.
+    #
+    # Stored as a thread-local by Builder.build_with_remarks so that recursive
+    # build calls can read `Builder.source` / `Builder.include_source` without
+    # the module mutating class-level state. Thread-local means concurrent
+    # builds in different threads don't corrupt each other; the save/restore
+    # pattern in build_with_remarks means nested builds are reentrant.
+    class BuilderContext
+      attr_reader :source, :include_source
+
+      def initialize(source:, include_source:)
+        @source = source
+        @include_source = include_source
+      end
+    end
+  end
+end