ast-merge 3.1.0 → 4.0.0

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/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.1.0"
+      VERSION = "4.0.0"
     end
     VERSION = Version::VERSION # traditional location
   end

data/lib/ast/merge.rb

@@ -142,17 +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"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ast-merge
 version: !ruby/object:Gem::Version
-  version: 3.1.0
+  version: 4.0.0
 platform: ruby
 authors:
 - Peter H. Boling
@@ -63,20 +63,20 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '5.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.0.0
+        version: 5.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.0'
+        version: '5.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 4.0.0
+        version: 5.0.0
 - !ruby/object:Gem::Dependency
   name: kettle-dev
   requirement: !ruby/object:Gem::Requirement
@@ -261,6 +261,26 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.0.3
+- !ruby/object:Gem::Dependency
+  name: ostruct
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.3
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.6'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.6.3
 description: "☯️ Ast::Merge provides base classes, modules, and RSpec shared examples
   for building intelligent file mergers using AST analysis. It powers prism-merge,
   psych-merge, json-merge, and other format-specific merge gems."
@@ -309,6 +329,7 @@ files:
 - lib/ast/merge/detector/mergeable.rb
 - lib/ast/merge/detector/toml_frontmatter.rb
 - lib/ast/merge/detector/yaml_frontmatter.rb
+- lib/ast/merge/diff_mapper_base.rb
 - lib/ast/merge/emitter_base.rb
 - lib/ast/merge/file_analyzable.rb
 - lib/ast/merge/freezable.rb
@@ -317,7 +338,10 @@ files:
 - lib/ast/merge/match_score_base.rb
 - lib/ast/merge/merge_result_base.rb
 - lib/ast/merge/merger_config.rb
-- lib/ast/merge/navigable_statement.rb
+- lib/ast/merge/navigable.rb
+- lib/ast/merge/navigable/injection_point.rb
+- lib/ast/merge/navigable/injection_point_finder.rb
+- lib/ast/merge/navigable/statement.rb
 - lib/ast/merge/node_typing.rb
 - lib/ast/merge/node_typing/frozen_wrapper.rb
 - lib/ast/merge/node_typing/normalizer.rb
@@ -357,10 +381,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://ast-merge.galtzo.com/
-  source_code_uri: https://github.com/kettle-rb/ast-merge/tree/v3.1.0
-  changelog_uri: https://github.com/kettle-rb/ast-merge/blob/v3.1.0/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-rb/ast-merge/tree/v4.0.0
+  changelog_uri: https://github.com/kettle-rb/ast-merge/blob/v4.0.0/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-rb/ast-merge/issues
-  documentation_uri: https://www.rubydoc.info/gems/ast-merge/3.1.0
+  documentation_uri: https://www.rubydoc.info/gems/ast-merge/4.0.0
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/kettle-rb/ast-merge/wiki
   news_uri: https://www.railsbling.com/tags/ast-merge