expressir 2.4.1 → 2.4.3

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

@@ -28,14 +28,6 @@ module Expressir
           current_context&.include_source
         end
 
-        # Thread-local snake_case conversion cache. Thread-local avoids the
-        # mutable-constant anti-pattern while remaining thread-safe.
-        # Each thread gets its own cache; the cache grows with the number of
-        # unique AST node-type names encountered (bounded by grammar size).
-        def snake_case_cache
-          Thread.current[:expressir_snake_case_cache] ||= {}
-        end
-
         # Register a builder for a node type.
         # @param node_type [Symbol] The AST node type
         # @param builder [#call] Optional callable that takes (ast_data)
@@ -57,8 +49,8 @@ module Expressir
             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
@@ -80,12 +72,12 @@ module Expressir
               ast.each_key do |key|
                 next if key == node_type
 
-                h_key = cached_snake_case(key)
+                h_key = AstKeyConverter.snake_case(key)
                 h_builder = @register[h_key]
                 next unless h_builder
 
                 n_data = ast[key]
-                s_data = fast_convert_keys(n_data)
+                s_data = AstKeyConverter.convert(n_data)
                 result = h_builder.call(s_data)
 
                 unless result.nil?
@@ -219,113 +211,10 @@ module Expressir
           builder.call(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
 

data/lib/expressir/express/error.rb

@@ -45,6 +45,23 @@ module Expressir
         end
       end
 
+      # Error raised when parallel file parsing loses a worker or its data
+      class ParallelParseError < ExpressError
+        def initialize(message = "Parallel parsing failed")
+          super
+        end
+      end
+
+      # Error raised when streaming parsing is requested but unavailable.
+      # The streaming paths require a parsanol release whose
+      # parse_with_builder is stable; parse_fresh cannot parse EXPRESS
+      # without packrat memoization (see parsanol-ruby#52).
+      class StreamingUnsupportedError < ExpressError
+        def initialize(message = "Streaming parsing is not supported by the installed parsanol release")
+          super
+        end
+      end
+
       # Base class for visitor-related errors
       class VisitorError < ExpressError; end
 

data/lib/expressir/express/node_position_index.rb

@@ -13,6 +13,9 @@ module Expressir
     # instances; this module turns those spans into a line-keyed index that
     # remark attachment can query.
     class NodePositionIndex
+      EMPTY = [].freeze
+      private_constant :EMPTY
+
       # Single source of truth for "what collections does this node have"
       # lives on the model — each class declares its own via the
       # `collection_attributes` macro. Referenced by both RemarkAttacher
@@ -21,31 +24,133 @@ module Expressir
 
       attr_reader :nodes
 
+      # Semantic entries starting on `line` (node order).
+      def starting_at(line)
+        semantic_by_line[line] || EMPTY
+      end
+
+      # Semantic entries ending on `line` (node order).
+      def ending_at(line)
+        semantic_by_end_line[line] || EMPTY
+      end
+
+      # Semantic entries whose span covers `line` (node order within the
+      # covering band).
+      def spanning(line)
+        band = line / BAND
+        bands = span_bands
+        return EMPTY unless bands.key?(band)
+
+        bands[band].select { |n| line.between?(n[:line], n[:end_line]) }
+      end
+
+      # Semantic entries with end_line < line, ascending by end_line.
+      def semantic_ending_before(line)
+        sorted = semantic_by_end_line_list
+        idx = sorted.bsearch_index { |n| n[:end_line] >= line } || sorted.size
+        sorted[0...idx]
+      end
+
+      # The first semantic entry (smallest line), for preamble remarks.
+      def first_semantic
+        first_by_line = semantic_by_line.keys.min
+        first_by_line && semantic_by_line[first_by_line]&.first
+      end
+
+      # Entries owned by `owner` within any of `collections`, in node order.
+      # Identity-keyed: ownership is object identity (the tree-walker's
+      # `.equal?` semantics), and value-equal model objects must not
+      # collide.
+      def children_in(owner, collections)
+        per_collection = children_index[owner]
+        return EMPTY unless per_collection
+
+        entries = per_collection.values_at(*collections).compact.flatten(1)
+        entries.sort_by { |n| node_order(n) }
+      end
+
+      # First node (in node order) that is_a?(type), memoized per type.
+      def first_node_of_type(type)
+        @first_of_type ||= {}
+        @first_of_type[type] ||= @nodes.find { |n| n[:node].is_a?(type) }&.dig(:node)
+      end
+
+      def semantic_entries
+        @semantic_entries ||=
+          @nodes.select { |n| n[:line] && semantic?(n[:node]) }
+      end
+
+      # Non-vivifying: missed lookups must not materialize keys, or
+      # `keys.min`-style queries see phantom lines.
+      def semantic_by_line
+        @semantic_by_line ||= begin
+          h = {}
+          semantic_entries.each { |n| (h[n[:line]] ||= []) << n }
+          h
+        end
+      end
+
+      def semantic_by_end_line
+        @semantic_by_end_line ||= begin
+          h = {}
+          semantic_entries.each { |n| (h[n[:end_line]] ||= []) << n if n[:end_line] }
+          h
+        end
+      end
+
+      def semantic_by_end_line_list
+        @semantic_by_end_line_list ||=
+          semantic_entries.select { |n| n[:end_line] }.sort_by { |n| n[:end_line] }
+      end
+
+      def children_index
+        @children_index ||= begin
+          index = {}.compare_by_identity
+          @nodes.each do |n|
+            next unless n[:owner] && n[:line]
+
+            per_owner = (index[n[:owner]] ||= {})
+            (per_owner[n[:collection]] ||= []) << n
+          end
+          index
+        end
+      end
+
+      def span_bands
+        @span_bands ||= begin
+          bands = Hash.new { |hash, key| hash[key] = [] }
+          semantic_entries.each do |n|
+            next unless n[:end_line]
+
+            ((n[:line] / BAND)..(n[:end_line] / BAND)).each do |band|
+              bands[band] << n
+            end
+          end
+          bands
+        end
+      end
+
+      BAND = 1024
+      private_constant :BAND
+
       def initialize(model, line_map)
         @model = model
         @line_map = line_map
         @nodes = build_sorted_nodes
+        @node_order = nil
       end
 
       # Returns the most-specific node whose span contains `remark_line`,
       # preferring same-line starts/ends, then smallest containing span.
       # Excludes Repository and Cache (not semantic scopes for remarks).
       def nearest_node_to(remark_line)
-        same_start = nodes.select do |n|
-          n[:line] == remark_line && semantic?(n[:node])
-        end
+        same_start = starting_at(remark_line)
         return same_start.last[:node] if same_start.any?
 
-        same_end = nodes.select do |n|
-          n[:end_line] == remark_line && semantic?(n[:node])
-        end
+        same_end = ending_at(remark_line)
         return same_end.last[:node] if same_end.any?
 
-        containing = nodes.select do |n|
-          n[:line] && n[:end_line] &&
-            n[:line] <= remark_line && n[:end_line] >= remark_line &&
-            semantic?(n[:node])
-        end
+        containing = spanning(remark_line)
 
         if containing.any?
           exp_file_node = containing.find { |n| n[:node].is_a?(Model::ExpFile) }
@@ -62,16 +167,13 @@ module Expressir
           candidates = containing if candidates.empty?
           candidates.min_by { |n| n[:end_line] - n[:line] }[:node]
         else
-          before = nodes.select do |n|
-            n[:end_line] && n[:end_line] < remark_line && semantic?(n[:node])
-          end
+          before = semantic_ending_before(remark_line)
           if before.any?
             before.max_by { |n| n[:end_line] }[:node]
           else
             # Remark is before all nodes (e.g., preamble comment before SCHEMA).
             # Attach to the first semantic node.
-            after = nodes.select { |n| n[:line] && semantic?(n[:node]) }
-            after.min_by { |n| n[:line] }[:node] if after.any?
+            first_semantic&.dig(:node)
           end
         end
       end
@@ -90,17 +192,28 @@ module Expressir
                     end
         return nil unless node_type
 
-        matching = nodes.select do |n|
+        candidates = (0..2).flat_map do |back|
+          ending_at(remark_line - back)
+        end.select do |n|
           n[:node].is_a?(node_type) &&
-            (n[:end_line] == remark_line ||
-             (n[:end_line] && n[:end_line] <= remark_line && n[:end_line] >= remark_line - 2))
+            n[:end_line] <= remark_line && n[:end_line] >= remark_line - 2
         end
 
-        matching.first&.dig(:node) || nodes.find { |n| n[:node].is_a?(node_type) }&.dig(:node)
+        candidates.min_by { |n| node_order(n) }&.dig(:node) ||
+          first_node_of_type(node_type)
       end
 
       private
 
+      def node_order(entry)
+        @node_order ||= begin
+          map = {}.compare_by_identity
+          @nodes.each_with_index { |n, i| map[n] = i }
+          map
+        end
+        @node_order[entry]
+      end
+
       def semantic?(node)
         !node.is_a?(Model::Repository) && !node.is_a?(Model::Cache)
       end