ast-merge 2.0.7 → 2.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ac53c3bf60949d4ce02f751351d3f4be08368945140d94dd8c090b700c92a0dc
-  data.tar.gz: 1eed56c786b9f3b9d86183dabe7aecaad8c989a68987abeb4133a12f20aea6ac
+  metadata.gz: b3751d56fac80906392c20aabf12c17f7dfc658b677a26866c42d842666e51f6
+  data.tar.gz: 41d59c958a7f0edae861bb0b3c5516f1b7120c85b4dc240880c5e9179017d210
 SHA512:
-  metadata.gz: d693729fe0371f440fd8223c7896d1cbfc267229a384aa36484d891a3b5b9e59c872646a721f168e696382d23f7fa54d4dd80073615e45dfb30e3e065b9a85d5
-  data.tar.gz: 487bc8bf2ad2c2031c37f0fccbce0aeffc06aa21d2e0d962b74a71586b99d60011177abc92fc1fddc6b0675cf4e6a1894d60743c23d6e3dcf7746d42f9fd9153
+  metadata.gz: 70ae22f513f5de125cbdea642483dbbc9c073f9133dd45b7b78d1a3dc0892757c3007fc252a9eb38b0d61e0423595976b1fb6f4581ff225792d5d12cf133138f
+  data.tar.gz: 802ed0bb804cbd92f1d85250726a573e953783e325debba0a87d5fc344cef48bac5b2f15d585e91d789a11f9d6fb02230d1d3971f40172aab5d01217a55c8138

data/CHANGELOG.md

@@ -30,6 +30,43 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [2.0.9] - 2026-01-02
+
+- TAG: [v2.0.9][2.0.9t]
+- COVERAGE: 97.09% -- 2637/2716 lines in 48 files
+- BRANCH COVERAGE: 89.64% -- 883/985 branches in 48 files
+- 98.71% documented
+
+### Fixed
+
+- **`NavigableStatement.find_matching` now returns empty array when no criteria specified** -
+  Previously, when both `type: nil` and `text: nil` and no block was given, the method would
+  match ALL statements (since no conditions filtered anything out). This caused
+  `PartialTemplateMerger` to incorrectly report `has_section: true` when `anchor: nil` was passed.
+  Now returns an empty array when no criteria are specified.
+
+## [2.0.8] - 2026-01-01
+
+- TAG: [v2.0.8][2.0.8t]
+- COVERAGE: 97.09% -- 2636/2715 lines in 48 files
+- BRANCH COVERAGE: 89.73% -- 882/983 branches in 48 files
+- 98.71% documented
+
+### Added
+
+- `Ast::Merge::NodeWrapperBase` abstract base class for format-specific node wrappers
+  - Provides common functionality shared by `*::Merge::NodeWrapper` classes across gems
+  - Handles source context (lines, source string), line info, comments, content extraction
+  - Defines abstract `#compute_signature` that subclasses must implement
+  - Includes `#node_wrapper?` to distinguish from `NodeTyping::Wrapper`
+  - Includes `#underlying_node` to access the raw TreeHaver node (NOT `#unwrap` to avoid
+    conflict with `NodeTyping::Wrapper#unwrap` semantics in `FileAnalyzable`)
+  - Documents relationship between `NodeWrapperBase` and `NodeTyping::Wrapper`:
+    - `NodeWrapperBase`: Format-specific functionality (line info, signatures, type predicates)
+    - `NodeTyping::Wrapper`: Custom merge classification (`merge_type` attribute)
+  - Nodes can be double-wrapped: `NodeTyping::Wrapper(Format::Merge::NodeWrapper(tree_sitter_node))`
+  - Accepts `**options` in initialize for subclass-specific parameters (e.g., `backend`, `document_root`)
+
 ## [2.0.7] - 2026-01-01
 
 - TAG: [v2.0.7][2.0.7t]
@@ -407,7 +444,11 @@ Please file a bug if you notice a violation of semantic versioning.
 
 - Initial release
 
-[Unreleased]: https://github.com/kettle-rb/ast-merge/compare/v2.0.7...HEAD
+[Unreleased]: https://github.com/kettle-rb/ast-merge/compare/v2.0.9...HEAD
+[2.0.9]: https://github.com/kettle-rb/ast-merge/compare/v2.0.8...v2.0.9
+[2.0.9t]: https://github.com/kettle-rb/ast-merge/releases/tag/v2.0.9
+[2.0.8]: https://github.com/kettle-rb/ast-merge/compare/v2.0.7...v2.0.8
+[2.0.8t]: https://github.com/kettle-rb/ast-merge/releases/tag/v2.0.8
 [2.0.7]: https://github.com/kettle-rb/ast-merge/compare/v2.0.6...v2.0.7
 [2.0.7t]: https://github.com/kettle-rb/ast-merge/releases/tag/v2.0.7
 [2.0.6]: https://github.com/kettle-rb/ast-merge/compare/v2.0.5...v2.0.6

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2025 Peter H. Boling
+Copyright (c) 2025-2026 Peter H. Boling
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -842,7 +842,7 @@ See [LICENSE.txt](LICENSE.txt) for the official [Copyright Notice](https://opens
 
 <ul>
     <li>
-        Copyright (c) 2025 Peter H. Boling, of
+        Copyright (c) 2025-2026 Peter H. Boling, of
         <a href="https://discord.gg/3qme4XHNKN">
             Galtzo.com
             <picture>
@@ -1032,7 +1032,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-2.640-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-2.716-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/lib/ast/merge/navigable_statement.rb

@@ -93,6 +93,9 @@ module Ast
         # @yield [NavigableStatement] Optional block for custom matching
         # @return [Array<NavigableStatement>] 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

data/lib/ast/merge/node_typing/normalizer.rb

@@ -57,9 +57,11 @@ module Ast
         # Sets up the mutex and backend mappings storage.
         #
         # @param base [Module] The module extending this one
-        def self.extended(base)
-          base.instance_variable_set(:@normalizer_mutex, Mutex.new)
-          base.instance_variable_set(:@backend_mappings, {})
+        class << self
+          def extended(base)
+            base.instance_variable_set(:@normalizer_mutex, Mutex.new)
+            base.instance_variable_set(:@backend_mappings, {})
+          end
         end
 
         # Configure the normalizer with initial backend mappings.

data/lib/ast/merge/node_wrapper_base.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    # Base class for format-specific node wrappers used in *-merge gems.
+    #
+    # This provides common functionality for wrapping TreeHaver nodes with:
+    # - Source context (lines, source string)
+    # - Line information (start_line, end_line)
+    # - Comment associations (leading_comments, inline_comment)
+    # - Content extraction (text, content)
+    # - Signature generation (abstract)
+    #
+    # ## Relationship to NodeTyping::Wrapper
+    #
+    # This class is DIFFERENT from `Ast::Merge::NodeTyping::Wrapper`:
+    #
+    # - **NodeWrapperBase**: Provides format-specific functionality (line info,
+    #   signatures, comments, type predicates). Used to wrap raw TreeHaver nodes
+    #   with rich context needed for merging.
+    #
+    # - **NodeTyping::Wrapper**: Adds a custom `merge_type` attribute for merge
+    #   classification. Used by SmartMergerBase to apply custom typing rules.
+    #
+    # A node CAN be wrapped by both:
+    # ```
+    # NodeTyping::Wrapper(Toml::Merge::NodeWrapper(tree_sitter_node))
+    # ```
+    #
+    # The `NodeTyping.unwrap` method handles unwrapping `NodeTyping::Wrapper`,
+    # while `NodeWrapperBase#node` provides access to the underlying TreeHaver node.
+    #
+    # ## Subclass Responsibilities
+    #
+    # Subclasses MUST implement:
+    # - `#compute_signature(node)` - Generate a signature for node matching
+    #
+    # Subclasses SHOULD implement format-specific type predicates:
+    # - TOML: `#table?`, `#pair?`, `#array_of_tables?`, etc.
+    # - JSON: `#object?`, `#array?`, `#pair?`, etc.
+    # - Bash: `#function_definition?`, `#variable_assignment?`, etc.
+    #
+    # @example Creating a format-specific wrapper
+    #   class NodeWrapper < Ast::Merge::NodeWrapperBase
+    #     def table?
+    #       type == :table
+    #     end
+    #
+    #     private
+    #
+    #     def compute_signature(node)
+    #       case node.type.to_sym
+    #       when :table
+    #         [:table, table_name]
+    #       else
+    #         [node.type.to_sym]
+    #       end
+    #     end
+    #   end
+    #
+    # @abstract Subclass and implement `#compute_signature`
+    class NodeWrapperBase
+      # @return [Object] The wrapped TreeHaver node
+      attr_reader :node
+
+      # @return [Array<String>] Source lines for content extraction
+      attr_reader :lines
+
+      # @return [String] The original source string
+      attr_reader :source
+
+      # @return [Array<Hash>] Leading comments associated with this node
+      attr_reader :leading_comments
+
+      # @return [Hash, nil] Inline/trailing comment on the same line
+      attr_reader :inline_comment
+
+      # @return [Integer, nil] Start line (1-based)
+      attr_reader :start_line
+
+      # @return [Integer, nil] End line (1-based)
+      attr_reader :end_line
+
+      # Initialize the node wrapper with source context.
+      #
+      # @param node [Object] TreeHaver node to wrap
+      # @param lines [Array<String>] Source lines for content extraction
+      # @param source [String, nil] Original source string for byte-based text extraction
+      # @param leading_comments [Array<Hash>] Comments before this node
+      # @param inline_comment [Hash, nil] Inline comment on the node's line
+      # @param options [Hash] Additional options for subclasses (forward compatibility)
+      def initialize(node, lines:, source: nil, leading_comments: [], inline_comment: nil, **options)
+        @node = node
+        @lines = lines
+        @source = source || lines.join("\n")
+        @leading_comments = leading_comments
+        @inline_comment = inline_comment
+
+        # Store additional options for subclasses to use
+        process_additional_options(options)
+
+        # Extract line information from the node (0-indexed to 1-indexed)
+        extract_line_info(node)
+
+        # Handle edge case where end_line might be before start_line
+        @end_line = @start_line if @start_line && @end_line && @end_line < @start_line
+      end
+
+      # Process additional options. Override in subclasses to handle format-specific options.
+      # @param options [Hash] Additional options
+      def process_additional_options(options)
+        # Default: no-op. Subclasses can override to process options like :backend, :document_root
+      end
+
+      # Generate a signature for this node for matching purposes.
+      # Signatures are used to identify corresponding nodes between template and destination.
+      #
+      # @return [Array, nil] Signature array or nil if not signaturable
+      def signature
+        compute_signature(@node)
+      end
+
+      # Get the node type as a symbol.
+      # @return [Symbol]
+      def type
+        @node.type.to_sym
+      end
+
+      # Check if this node has a specific type.
+      # @param type_name [Symbol, String] Type to check
+      # @return [Boolean]
+      def type?(type_name)
+        @node.type.to_s == type_name.to_s
+      end
+
+      # Check if this is a freeze node.
+      # Override in subclasses if freeze node detection differs.
+      # @return [Boolean]
+      def freeze_node?
+        false
+      end
+
+      # Get the text content for this node by extracting from source using byte positions.
+      # @return [String]
+      def text
+        node_text(@node)
+      end
+
+      # Extract text from a node using byte positions.
+      # @param ts_node [Object] The TreeHaver node
+      # @return [String]
+      def node_text(ts_node)
+        return "" unless ts_node.respond_to?(:start_byte) && ts_node.respond_to?(:end_byte)
+
+        @source[ts_node.start_byte...ts_node.end_byte] || ""
+      end
+
+      # Get the content for this node from source lines.
+      # @return [String]
+      def content
+        return "" unless @start_line && @end_line
+
+        (@start_line..@end_line).map { |ln| @lines[ln - 1] }.compact.join("\n")
+      end
+
+      # Check if this node is a container (has children for merging).
+      # Override in subclasses to define container types.
+      # @return [Boolean]
+      def container?
+        false
+      end
+
+      # Check if this node is a leaf (no mergeable children).
+      # @return [Boolean]
+      def leaf?
+        !container?
+      end
+
+      # Get children wrapped as NodeWrappers.
+      # Override in subclasses to return wrapped children.
+      # @return [Array<NodeWrapperBase>]
+      def children
+        return [] unless @node.respond_to?(:each)
+
+        result = []
+        @node.each do |child|
+          result << wrap_child(child)
+        end
+        result
+      end
+
+      # Get mergeable children - the semantically meaningful children for tree merging.
+      # Override in subclasses to return format-specific mergeable children.
+      # @return [Array<NodeWrapperBase>]
+      def mergeable_children
+        children
+      end
+
+      # String representation for debugging.
+      # @return [String]
+      def inspect
+        "#<#{self.class.name} type=#{@node.type} lines=#{@start_line}..#{@end_line}>"
+      end
+
+      # Returns true to indicate this is a node wrapper.
+      # Used to distinguish from NodeTyping::Wrapper.
+      # @return [Boolean]
+      def node_wrapper?
+        true
+      end
+
+      # Get the underlying TreeHaver node.
+      # Note: This is NOT the same as NodeTyping::Wrapper#unwrap which removes
+      # the typing wrapper. This method provides access to the raw parser node.
+      # @return [Object] The underlying TreeHaver node
+      def underlying_node
+        @node
+      end
+
+      protected
+
+      # Wrap a child node. Override in subclasses to use the specific wrapper class.
+      # @param child [Object] Child node to wrap
+      # @return [NodeWrapperBase]
+      def wrap_child(child)
+        self.class.new(child, lines: @lines, source: @source)
+      end
+
+      # Compute signature for a node. Subclasses MUST implement this.
+      # @param node [Object] The node to compute signature for
+      # @return [Array, nil] Signature array
+      # @abstract
+      def compute_signature(node)
+        raise NotImplementedError, "#{self.class} must implement #compute_signature"
+      end
+
+      private
+
+      # Extract line information from the node.
+      # @param node [Object] The node to extract line info from
+      def extract_line_info(node)
+        if node.respond_to?(:start_point)
+          point = node.start_point
+          @start_line = extract_row(point) + 1
+        end
+
+        if node.respond_to?(:end_point)
+          point = node.end_point
+          @end_line = extract_row(point) + 1
+        end
+      end
+
+      # Extract row from a point, handling different point implementations.
+      # @param point [Object] The point object
+      # @return [Integer]
+      def extract_row(point)
+        if point.respond_to?(:row)
+          point.row
+        elsif point.is_a?(Hash)
+          point[:row]
+        else
+          0
+        end
+      end
+    end
+  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 = "2.0.7"
+      VERSION = "2.0.9"
     end
     VERSION = Version::VERSION # traditional location
   end

data/lib/ast/merge.rb

@@ -153,6 +153,7 @@ module Ast
     autoload :MergerConfig, "ast/merge/merger_config"
     autoload :NavigableStatement, "ast/merge/navigable_statement"
     autoload :NodeTyping, "ast/merge/node_typing"
+    autoload :NodeWrapperBase, "ast/merge/node_wrapper_base"
     autoload :PartialTemplateMerger, "ast/merge/partial_template_merger"
     autoload :SectionTyping, "ast/merge/section_typing"
     autoload :SmartMergerBase, "ast/merge/smart_merger_base"

data/sig/ast/merge.rbs

@@ -595,7 +595,8 @@ module Ast
         def self.extended: (Module base) -> void
 
         # Configure initial backend mappings
-        def configure_normalizer: (**Hash[Symbol, Symbol] mappings) -> void
+        # @param mappings Keyword args where keys are backend symbols and values are type mapping hashes
+        def configure_normalizer: (**untyped) -> void
 
         # Register type mappings for a new backend (thread-safe)
         def register_backend: (Symbol backend, Hash[Symbol, Symbol] mappings) -> void

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ast-merge
 version: !ruby/object:Gem::Version
-  version: 2.0.7
+  version: 2.0.9
 platform: ruby
 authors:
 - Peter H. Boling
@@ -66,7 +66,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.2
+        version: 3.2.3
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -76,7 +76,7 @@ dependencies:
         version: '3.2'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.2
+        version: 3.2.3
 - !ruby/object:Gem::Dependency
   name: kettle-dev
   requirement: !ruby/object:Gem::Requirement
@@ -321,6 +321,7 @@ files:
 - lib/ast/merge/node_typing/frozen_wrapper.rb
 - lib/ast/merge/node_typing/normalizer.rb
 - lib/ast/merge/node_typing/wrapper.rb
+- lib/ast/merge/node_wrapper_base.rb
 - lib/ast/merge/partial_template_merger.rb
 - lib/ast/merge/recipe.rb
 - lib/ast/merge/recipe/config.rb
@@ -355,10 +356,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://ast-merge.galtzo.com/
-  source_code_uri: https://github.com/kettle-rb/ast-merge/tree/v2.0.7
-  changelog_uri: https://github.com/kettle-rb/ast-merge/blob/v2.0.7/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-rb/ast-merge/tree/v2.0.9
+  changelog_uri: https://github.com/kettle-rb/ast-merge/blob/v2.0.9/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-rb/ast-merge/issues
-  documentation_uri: https://www.rubydoc.info/gems/ast-merge/2.0.7
+  documentation_uri: https://www.rubydoc.info/gems/ast-merge/2.0.9
   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