ast-merge 3.0.0 → 4.0.0

data/lib/ast/merge/navigable/injection_point_finder.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    module Navigable
+      # Finds injection points in a document based on matching rules.
+      #
+      # This is language-agnostic - the matching rules work on the unified
+      # Statement interface regardless of the underlying parser.
+      #
+      # @example Find where to inject constants in a Ruby class
+      #   finder = InjectionPointFinder.new(statements)
+      #   point = finder.find(
+      #     type: :class,
+      #     text: /class Choo/,
+      #     position: :first_child
+      #   )
+      #
+      # @example Find and replace a constant definition
+      #   point = finder.find(
+      #     type: :constant_assignment,
+      #     text: /DAR\s*=/,
+      #     position: :replace
+      #   )
+      #
+      class InjectionPointFinder
+        # @return [Array<Statement>] The statement list to search
+        attr_reader :statements
+
+        def initialize(statements)
+          @statements = statements
+        end
+
+        # Find an injection point based on matching criteria.
+        #
+        # @param type [Symbol, String, nil] Node type to match
+        # @param text [String, Regexp, nil] Text pattern to match
+        # @param position [Symbol] Where to inject (:before, :after, :first_child, :last_child, :replace)
+        # @param boundary_type [Symbol, String, nil] Node type for replacement boundary
+        # @param boundary_text [String, Regexp, nil] Text pattern for replacement boundary
+        # @param boundary_matcher [Proc, nil] Custom matcher for boundary (receives Statement, returns boolean)
+        # @param boundary_same_or_shallower [Boolean] If true, boundary is next node at same or shallower tree depth
+        # @yield [Statement] Optional custom matcher
+        # @return [InjectionPoint, nil] Injection point if anchor found
+        def find(type: nil, text: nil, position:, boundary_type: nil, boundary_text: nil, boundary_matcher: nil, boundary_same_or_shallower: false, &block)
+          anchor = Statement.find_first(statements, type: type, text: text, &block)
+          return unless anchor
+
+          boundary = nil
+          if position == :replace && (boundary_type || boundary_text || boundary_matcher || boundary_same_or_shallower)
+            # Find boundary starting after anchor
+            remaining = statements[(anchor.index + 1)..]
+
+            if boundary_same_or_shallower
+              # Find next node at same or shallower tree depth
+              # This is language-agnostic: ends section at next sibling or ancestor's sibling
+              anchor_depth = anchor.tree_depth
+              boundary = remaining.find do |stmt|
+                # Must match type if specified
+                next false if boundary_type && stmt.type.to_s != boundary_type.to_s
+                next false if boundary_text && !stmt.text_matches?(boundary_text)
+                # Check tree depth
+                stmt.same_or_shallower_than?(anchor_depth)
+              end
+            elsif boundary_matcher
+              # Use custom matcher
+              boundary = remaining.find { |stmt| boundary_matcher.call(stmt) }
+            else
+              boundary = Statement.find_first(
+                remaining,
+                type: boundary_type,
+                text: boundary_text,
+              )
+            end
+          end
+
+          InjectionPoint.new(
+            anchor: anchor,
+            position: position,
+            boundary: boundary,
+            match: {type: type, text: text},
+          )
+        end
+
+        # Find all injection points matching criteria.
+        #
+        # @param (see #find)
+        # @return [Array<InjectionPoint>] All matching injection points
+        def find_all(type: nil, text: nil, position:, &block)
+          anchors = Statement.find_matching(statements, type: type, text: text, &block)
+          anchors.map do |anchor|
+            InjectionPoint.new(anchor: anchor, position: position)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ast/merge/navigable/statement.rb

@@ -0,0 +1,380 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    module Navigable
+      # Wraps any node (parser-backed or synthetic) with uniform navigation.
+      #
+      # Provides two levels of navigation:
+      # 1. **Flat list navigation**: prev_statement, next_statement, index
+      #    - Works for ALL nodes (synthetic and parser-backed)
+      #    - Represents position in the flattened statement list
+      #
+      # 2. **Tree navigation**: tree_parent, tree_next, tree_previous, tree_children
+      #    - Only available for parser-backed nodes
+      #    - Delegates to inner_node's tree methods
+      #
+      # This allows code to work with the flat list for simple merging,
+      # while still accessing tree structure for section-aware operations.
+      #
+      # @example Basic usage
+      #   statements = Statement.build_list(raw_statements)
+      #   stmt = statements[0]
+      #
+      #   # Flat navigation (always works)
+      #   stmt.next           # => next statement in flat list
+      #   stmt.previous       # => previous statement in flat list
+      #   stmt.index          # => position in array
+      #
+      #   # Tree navigation (when available)
+      #   stmt.tree_parent    # => parent in original AST (or nil)
+      #   stmt.tree_next      # => next sibling in original AST (or nil)
+      #   stmt.tree_children  # => children in original AST (or [])
+      #
+      # @example Section grouping
+      #   # Group statements into sections by heading level
+      #   sections = Statement.group_by_heading(statements, level: 3)
+      #   sections.each do |section|
+      #     puts "Section: #{section.heading.text}"
+      #     section.statements.each { |s| puts "  - #{s.type}" }
+      #   end
+      #
+      class Statement
+        # @return [Object] The wrapped node (parser-backed or synthetic)
+        attr_reader :node
+
+        # @return [Integer] Index in the flattened statement list
+        attr_reader :index
+
+        # @return [Statement, nil] Previous statement in flat list
+        attr_accessor :prev_statement
+
+        # @return [Statement, nil] Next statement in flat list
+        attr_accessor :next_statement
+
+        # @return [Object, nil] Optional context/metadata for this statement
+        attr_accessor :context
+
+        # Initialize a Statement wrapper.
+        #
+        # @param node [Object] The node to wrap
+        # @param index [Integer] Position in the statement list
+        def initialize(node, index:)
+          @node = node
+          @index = index
+          @prev_statement = nil
+          @next_statement = nil
+          @context = nil
+        end
+
+        class << self
+          # Build a linked list of Statements from raw statements.
+          #
+          # @param raw_statements [Array<Object>] Raw statement nodes
+          # @return [Array<Statement>] Linked statement list
+          def build_list(raw_statements)
+            statements = raw_statements.each_with_index.map do |node, i|
+              new(node, index: i)
+            end
+
+            # Link siblings in flat list
+            statements.each_cons(2) do |prev_stmt, next_stmt|
+              prev_stmt.next_statement = next_stmt
+              next_stmt.prev_statement = prev_stmt
+            end
+
+            statements
+          end
+
+          # Find statements matching a query.
+          #
+          # @param statements [Array<Statement>] Statement list
+          # @param type [Symbol, String, nil] Node type to match (nil = any)
+          # @param text [String, Regexp, nil] Text pattern to match
+          # @yield [Statement] Optional block for custom matching
+          # @return [Array<Statement>] Matching statements
+          def find_matching(statements, type: nil, text: nil, &block)
+            # If no criteria specified, return empty array (nothing to match)
+            return [] if type.nil? && text.nil? && !block_given?
+
+            statements.select do |stmt|
+              matches = true
+              matches &&= stmt.type.to_s == type.to_s if type
+              matches &&= text.is_a?(Regexp) ? stmt.text.match?(text) : stmt.text.include?(text.to_s) if text
+              matches &&= yield(stmt) if block_given?
+              matches
+            end
+          end
+
+          # Find the first statement matching criteria.
+          #
+          # @param statements [Array<Statement>] Statement list
+          # @param type [Symbol, String, nil] Node type to match
+          # @param text [String, Regexp, nil] Text pattern to match
+          # @yield [Statement] Optional block for custom matching
+          # @return [Statement, nil] First matching statement
+          def find_first(statements, type: nil, text: nil, &block)
+            find_matching(statements, type: type, text: text, &block).first
+          end
+        end
+
+        # ============================================================
+        # Flat list navigation (always available)
+        # ============================================================
+
+        # @return [Statement, nil] Next statement in flat list
+        def next
+          next_statement
+        end
+
+        # @return [Statement, nil] Previous statement in flat list
+        def previous
+          prev_statement
+        end
+
+        # @return [Boolean] true if this is the first statement
+        def first?
+          prev_statement.nil?
+        end
+
+        # @return [Boolean] true if this is the last statement
+        def last?
+          next_statement.nil?
+        end
+
+        # Iterate from this statement to the end (or until block returns false).
+        #
+        # @yield [Statement] Each statement
+        # @return [Enumerator, nil]
+        def each_following(&block)
+          return to_enum(:each_following) unless block_given?
+
+          current = self.next
+          while current
+            break unless yield(current)
+            current = current.next
+          end
+        end
+
+        # Collect statements until a condition is met.
+        #
+        # @yield [Statement] Each statement
+        # @return [Array<Statement>] Statements until condition
+        def take_until(&block)
+          result = []
+          each_following do |stmt|
+            break if yield(stmt)
+            result << stmt
+            true
+          end
+          result
+        end
+
+        # ============================================================
+        # Tree navigation (delegates to inner_node when available)
+        # ============================================================
+
+        # @return [Object, nil] Parent node in original AST
+        def tree_parent
+          inner = unwrapped_node
+          inner.parent if inner.respond_to?(:parent)
+        end
+
+        # @return [Object, nil] Next sibling in original AST
+        def tree_next
+          inner = unwrapped_node
+          inner.next if inner.respond_to?(:next)
+        end
+
+        # @return [Object, nil] Previous sibling in original AST
+        def tree_previous
+          inner = unwrapped_node
+          inner.previous if inner.respond_to?(:previous)
+        end
+
+        # @return [Array<Object>] Children in original AST
+        def tree_children
+          inner = unwrapped_node
+          if inner.respond_to?(:each)
+            inner.to_a
+          elsif inner.respond_to?(:children)
+            inner.children
+          else
+            []
+          end
+        end
+
+        # @return [Object, nil] First child in original AST
+        def tree_first_child
+          inner = unwrapped_node
+          inner.first_child if inner.respond_to?(:first_child)
+        end
+
+        # @return [Object, nil] Last child in original AST
+        def tree_last_child
+          inner = unwrapped_node
+          inner.last_child if inner.respond_to?(:last_child)
+        end
+
+        # @return [Boolean] true if tree navigation is available
+        def has_tree_navigation?
+          inner = unwrapped_node
+          inner.respond_to?(:parent) || inner.respond_to?(:next)
+        end
+
+        # @return [Boolean] true if this is a synthetic node (no tree navigation)
+        def synthetic?
+          !has_tree_navigation?
+        end
+
+        # Calculate the tree depth (distance from root).
+        #
+        # @return [Integer] Depth in tree (0 = root level)
+        def tree_depth
+          depth = 0
+          current = tree_parent
+          while current
+            depth += 1
+            # Navigate up through parents
+            if current.respond_to?(:parent)
+              current = current.parent
+            else
+              break
+            end
+          end
+          depth
+        end
+
+        # Check if this node is at same or shallower depth than another.
+        # Useful for determining section boundaries.
+        #
+        # @param other [Statement, Integer] Other statement or depth value
+        # @return [Boolean] true if this node is at same or shallower depth
+        def same_or_shallower_than?(other)
+          other_depth = other.is_a?(Integer) ? other : other.tree_depth
+          tree_depth <= other_depth
+        end
+
+        # ============================================================
+        # Node delegation
+        # ============================================================
+
+        # @return [Symbol, String] Node type
+        def type
+          return node.type if node.respond_to?(:type)
+
+          # Fallback: derive type from class name (handle anonymous classes)
+          class_name = node.class.name
+          class_name ? class_name.split("::").last : "Anonymous"
+        end
+
+        # @return [Array, Object, nil] Node signature for matching
+        def signature
+          node.signature if node.respond_to?(:signature)
+        end
+
+        # @return [String] Node text content
+        def text
+          # TreeHaver nodes (and any node conforming to the unified API) provide #text.
+          # No conditional fallbacks - nodes must conform to the API.
+          node.text.to_s
+        end
+
+        # @return [Hash, nil] Source position info
+        def source_position
+          node.source_position if node.respond_to?(:source_position)
+        end
+
+        # @return [Integer, nil] Start line number
+        def start_line
+          pos = source_position
+          pos[:start_line] if pos
+        end
+
+        # @return [Integer, nil] End line number
+        def end_line
+          pos = source_position
+          pos[:end_line] if pos
+        end
+
+        # ============================================================
+        # Node attribute helpers (language-agnostic)
+        # ============================================================
+
+        # Check if this node matches a type.
+        #
+        # @param expected_type [Symbol, String] Type to check
+        # @return [Boolean]
+        def type?(expected_type)
+          type.to_s == expected_type.to_s
+        end
+
+        # Check if this node's text matches a pattern.
+        #
+        # @param pattern [String, Regexp] Pattern to match
+        # @return [Boolean]
+        def text_matches?(pattern)
+          case pattern
+          when Regexp
+            text.match?(pattern)
+          else
+            text.include?(pattern.to_s)
+          end
+        end
+
+        # Get an attribute from the underlying node.
+        #
+        # Tries multiple method names to support different parser APIs.
+        #
+        # @param name [Symbol, String] Attribute name
+        # @param aliases [Array<Symbol>] Alternative method names
+        # @return [Object, nil] Attribute value
+        def node_attribute(name, *aliases)
+          inner = unwrapped_node
+          [name, *aliases].each do |method_name|
+            return inner.send(method_name) if inner.respond_to?(method_name)
+          end
+          nil
+        end
+
+        # ============================================================
+        # Utilities
+        # ============================================================
+
+        # Get the unwrapped inner node.
+        #
+        # @return [Object] The innermost node
+        def unwrapped_node
+          current = node
+          while current.respond_to?(:inner_node) && current.inner_node != current
+            current = current.inner_node
+          end
+          current
+        end
+
+        # @return [String] Human-readable representation
+        def inspect
+          "#<Navigable::Statement[#{index}] type=#{type} tree=#{has_tree_navigation?}>"
+        end
+
+        # @return [String] String representation
+        def to_s
+          text.to_s.strip[0, 50]
+        end
+
+        # Delegate unknown methods to the wrapped node.
+        def method_missing(method, *args, &block)
+          if node.respond_to?(method)
+            node.send(method, *args, &block)
+          else
+            super
+          end
+        end
+
+        def respond_to_missing?(method, include_private = false)
+          node.respond_to?(method, include_private) || super
+        end
+      end
+    end
+  end
+end

data/lib/ast/merge/navigable.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    # Namespace for navigation-related classes.
+    #
+    # Provides unified navigation over AST nodes regardless of the underlying parser.
+    # Classes in this namespace work together to enable finding and manipulating
+    # positions in document structures.
+    #
+    # @see Navigable::Statement Wraps nodes with navigation capabilities
+    # @see Navigable::InjectionPoint Represents a location for content injection
+    # @see Navigable::InjectionPointFinder Finds injection points by matching rules
+    module Navigable
+      autoload :Statement, "ast/merge/navigable/statement"
+      autoload :InjectionPoint, "ast/merge/navigable/injection_point"
+      autoload :InjectionPointFinder, "ast/merge/navigable/injection_point_finder"
+    end
+  end
+end

data/lib/ast/merge/node_typing.rb

@@ -13,6 +13,27 @@ module Ast
     # The `merge_type` attribute can then be used by other merge tools like
     # `signature_generator`, `match_refiner`, and per-node-type `preference` settings.
     #
+    # ## Important: Two Uses of merge_type
+    #
+    # The `merge_type` method serves two complementary purposes in the codebase:
+    #
+    # ### 1. NodeTyping-specific (gated by typed_node?)
+    # Wrapped nodes (Wrapper/FrozenWrapper) with custom type tagging for:
+    # - Per-node-type preferences (e.g., `:lint_gem` → `:template`)
+    # - Match refinement based on custom categories
+    # - Only applies when `typed_node?` returns true
+    # - Accessed via `NodeTyping.merge_type_for(node)`
+    #
+    # ### 2. General node classification (any node)
+    # Any node can implement `merge_type` for category identification:
+    # - FreezeNodeBase has `merge_type` → `:freeze_block`
+    # - GapLineNode has `merge_type` → `:gap_line`
+    # - Used by systems like MarkdownStructure for structural spacing rules
+    # - These nodes are NOT "typed nodes" (typed_node? returns false)
+    #
+    # The key distinction: **typed_node? is the gate** for NodeTyping wrapper
+    # semantics. A node can have `merge_type` without being a NodeTyping wrapper.
+    #
     # @example Basic node typing for different gem types
     #   node_typing = {
     #     CallNode: ->(node) {

data/lib/ast/merge/partial_template_merger_base.rb

@@ -129,15 +129,16 @@ module Ast
       def merge
         # Parse destination and find injection point
         d_analysis = create_analysis(destination)
-        d_statements = NavigableStatement.build_list(d_analysis.statements)
+        d_statements = Navigable::Statement.build_list(d_analysis.statements)
 
-        finder = InjectionPointFinder.new(d_statements)
+        finder = Navigable::InjectionPointFinder.new(d_statements)
         injection_point = finder.find(
           type: anchor[:type],
           text: anchor[:text],
           position: :replace,
           boundary_type: boundary&.dig(:type),
           boundary_text: boundary&.dig(:text),
+          boundary_same_or_shallower: boundary&.dig(:same_or_shallower) || false,
         )
 
         if injection_point.nil?
@@ -200,6 +201,7 @@ module Ast
         result[:level] = matcher[:level] if matcher[:level]
         result[:level_lte] = matcher[:level_lte] if matcher[:level_lte]
         result[:level_gte] = matcher[:level_gte] if matcher[:level_gte]
+        result[:same_or_shallower] = matcher[:same_or_shallower] if matcher.key?(:same_or_shallower)
         result.compact
       end
 

data/lib/ast/merge/recipe/preset.rb

@@ -135,6 +135,20 @@ module Ast
           script_loader.load_callable(value)
         end
 
+        # Get the normalize_whitespace setting.
+        #
+        # @return [Boolean] Whether to collapse excessive blank lines
+        def normalize_whitespace
+          merge_config[:normalize_whitespace] == true
+        end
+
+        # Get the rehydrate_link_references setting.
+        #
+        # @return [Boolean] Whether to convert inline links to reference style
+        def rehydrate_link_references
+          merge_config[:rehydrate_link_references] == true
+        end
+
         # Convert preset to a hash suitable for SmartMerger options.
         #
         # @return [Hash]
@@ -146,6 +160,8 @@ module Ast
             node_typing: node_typing,
             match_refiner: match_refiner,
             freeze_token: freeze_token,
+            normalize_whitespace: normalize_whitespace,
+            rehydrate_link_references: rehydrate_link_references,
           }.compact
         end
 
@@ -168,6 +184,8 @@ module Ast
             signature_generator: config["signature_generator"],
             node_typing: config["node_typing"],
             match_refiner: config["match_refiner"],
+            normalize_whitespace: config["normalize_whitespace"] == true,
+            rehydrate_link_references: config["rehydrate_link_references"] == true,
           }
         end
 

data/lib/ast/merge/recipe/runner.rb

@@ -26,7 +26,7 @@ module Ast
       #
       class Runner
         # Result of processing a single file
-        Result = Struct.new(:path, :relative_path, :status, :changed, :has_anchor, :message, :stats, :error, keyword_init: true)
+        Result = Struct.new(:path, :relative_path, :status, :changed, :has_anchor, :message, :stats, :problems, :error, keyword_init: true)
 
         # @return [Config] The recipe being executed
         attr_reader :recipe
@@ -157,6 +157,8 @@ module Ast
               signature_generator: recipe.signature_generator,
               node_typing: recipe.node_typing,
               match_refiner: recipe.match_refiner,
+              normalize_whitespace: recipe.normalize_whitespace,
+              rehydrate_link_references: recipe.rehydrate_link_references,
             )
 
             result = merger.merge
@@ -202,6 +204,9 @@ module Ast
         def create_result_from_merge(target_path, relative_path, _destination_content, merge_result)
           changed = merge_result.changed
 
+          # Extract problems from stats if present (PartialTemplateMerger stores them there)
+          problems = merge_result.stats[:problems] if merge_result.stats.is_a?(Hash)
+
           if changed
             unless dry_run
               File.write(target_path, merge_result.content)
@@ -215,6 +220,7 @@ module Ast
               has_anchor: true,
               message: dry_run ? "Would update" : "Updated",
               stats: merge_result.stats,
+              problems: problems,
             )
           else
             Result.new(
@@ -225,6 +231,7 @@ module Ast
               has_anchor: true,
               message: "No changes needed",
               stats: merge_result.stats,
+              problems: problems,
             )
           end
         end

data/lib/ast/merge/version.rb

@@ -5,7 +5,7 @@ module Ast
     # Version information for Ast::Merge
     module Version
       # Current version of the ast-merge gem
-      VERSION = "3.0.0"
+      VERSION = "4.0.0"
     end
     VERSION = Version::VERSION # traditional location
   end

data/lib/ast/merge.rb

@@ -142,16 +142,16 @@ module Ast
     autoload :ConflictResolverBase, "ast/merge/conflict_resolver_base"
     autoload :ContentMatchRefiner, "ast/merge/content_match_refiner"
     autoload :DebugLogger, "ast/merge/debug_logger"
+    autoload :DiffMapperBase, "ast/merge/diff_mapper_base"
+    autoload :EmitterBase, "ast/merge/emitter_base"
     autoload :FileAnalyzable, "ast/merge/file_analyzable"
     autoload :Freezable, "ast/merge/freezable"
     autoload :FreezeNodeBase, "ast/merge/freeze_node_base"
-    autoload :InjectionPoint, "ast/merge/navigable_statement"
-    autoload :InjectionPointFinder, "ast/merge/navigable_statement"
     autoload :MatchRefinerBase, "ast/merge/match_refiner_base"
     autoload :MatchScoreBase, "ast/merge/match_score_base"
     autoload :MergeResultBase, "ast/merge/merge_result_base"
     autoload :MergerConfig, "ast/merge/merger_config"
-    autoload :NavigableStatement, "ast/merge/navigable_statement"
+    autoload :Navigable, "ast/merge/navigable"
     autoload :NodeTyping, "ast/merge/node_typing"
     autoload :NodeWrapperBase, "ast/merge/node_wrapper_base"
     autoload :PartialTemplateMergerBase, "ast/merge/partial_template_merger_base"