ast-merge 2.0.6 → 2.0.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86f9ef0462fcd809046dfc7c0486d9ab739badaab3faf4dfa898089479b7b5b1
-  data.tar.gz: f77f27ebd8b050a209c2d94283b93f1282b4f5e3c689229c3ea19432e1d3bafa
+  metadata.gz: ca82f3d67dd5ed8339d2ebad3032875db7c22bb5446747c7f6cf9a03080a1da4
+  data.tar.gz: c523f74b6be2660bd2c41c63d1d3afd895d4e849d5b1858813b252000e71093f
 SHA512:
-  metadata.gz: de6c91e8cb0a86dd1d13a52a2dbda3cd52951f2d4cfd45c171344412a992d59e5db7593c861467df256a798184774c978ddd47abf3c157e5a73b3c994ad337b5
-  data.tar.gz: 3ec3274c3366c5bbcd2362ebc0abf71e54292afefa42022fa673996141a43f5385b54c87ca5bf5c15ee2d5267a73544e8316d81bae47ff0ec37dd7772d990566
+  metadata.gz: a41a7321e1fafe4882c59b77b16822eabc70f2d255ed6de92ef373bbbbc98a2855895c22175a0ad72270b97a6de9ff8e8246f72110f98ddf7fecc8682799048a
+  data.tar.gz: 30bc1323ae070faf65765549aeb479cb2e4c6b060676997ca1a35f31cf45658dab6f1d3adb55f70bf43ac103748b34f0b87e41d8349372f6cea811e55547fc83

data/CHANGELOG.md

@@ -30,6 +30,55 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [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]
+- COVERAGE: 97.31% -- 2569/2640 lines in 47 files
+- BRANCH COVERAGE: 89.87% -- 869/967 branches in 47 files
+- 98.84% documented
+
+### Added
+
+- `Ast::Merge::NodeTyping::Normalizer` module for thread-safe backend type normalization
+  - Provides shared infrastructure for format-specific normalizers (toml-merge, markdown-merge)
+  - Thread-safe backend registration via mutex-protected operations
+  - `configure_normalizer` for initial backend mappings configuration
+  - `register_backend` for runtime registration of new backends
+  - `canonical_type` for mapping backend-specific types to canonical types
+  - `wrap` for wrapping nodes with canonical merge_type
+  - `registered_backends`, `backend_registered?`, `mappings_for`, `canonical_types` query methods
+- `Ast::Merge::NodeTyping::FrozenWrapper` class for frozen AST nodes
+  - Includes `Freezable` behavior for freeze marker support
+  - `frozen_node?`, `slice`, `signature` methods
+- Split `NodeTyping` module into separate files following autoload pattern:
+  - `ast/merge/node_typing/wrapper.rb`
+  - `ast/merge/node_typing/frozen_wrapper.rb`
+  - `ast/merge/node_typing/normalizer.rb`
+- Comprehensive specs for `NodeTyping::Normalizer` including thread-safety tests
+- RBS type signatures for `NodeTyping::Normalizer` and `NodeTyping::FrozenWrapper`
+
 ## [2.0.6] - 2026-01-01
 
 - TAG: [v2.0.6][2.0.6t]
@@ -380,7 +429,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.6...HEAD
+[Unreleased]: https://github.com/kettle-rb/ast-merge/compare/v2.0.8...HEAD
+[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
 [2.0.6t]: https://github.com/kettle-rb/ast-merge/releases/tag/v2.0.6
 [2.0.5]: https://github.com/kettle-rb/ast-merge/compare/v2.0.4...v2.0.5

data/README.md

@@ -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.595-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-2.715-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/node_typing/frozen_wrapper.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    module NodeTyping
+      # Wrapper for frozen AST nodes that includes Freezable behavior.
+      #
+      # FrozenWrapper extends Wrapper to add freeze node semantics, making the
+      # wrapped node satisfy both the NodeTyping API and the Freezable API.
+      # This enables composition where frozen nodes are:
+      # - Wrapped AST nodes (can unwrap to get original)
+      # - Typed nodes (have merge_type)
+      # - Freeze nodes (satisfy is_a?(Freezable) and freeze_node?)
+      #
+      # ## Key Distinction from FreezeNodeBase
+      #
+      # FrozenWrapper and FreezeNodeBase both include Freezable, but they represent
+      # fundamentally different concepts:
+      #
+      # ### FrozenWrapper (this class)
+      # - Wraps an AST node that has a freeze marker in its leading comments
+      # - The node is still a structural AST node (e.g., a `gem` call in a gemspec)
+      # - During matching, we want to match by the underlying node's IDENTITY
+      #   (e.g., the gem name), NOT by the full content
+      # - Signature generation should unwrap and use the underlying node's structure
+      # - Example: `# token:freeze\ngem "example_gem", "~> 1.0"` wraps a CallNode
+      #
+      # ### FreezeNodeBase
+      # - Represents an explicit freeze block with `# token:freeze ... # token:unfreeze`
+      # - The entire block is opaque content that should be preserved verbatim
+      # - During matching, we match by the full CONTENT of the block
+      # - Signature generation uses freeze_signature (content-based)
+      # - Example: A multi-line comment block with custom formatting
+      #
+      # ## Signature Generation Behavior
+      #
+      # When FileAnalyzable#generate_signature encounters a FrozenWrapper:
+      # 1. It unwraps to get the underlying AST node
+      # 2. Passes the unwrapped node to the signature_generator
+      # 3. This allows the signature generator to recognize the node type
+      #    (e.g., Prism::CallNode) and generate appropriate signatures
+      #
+      # This is critical because signature generators check for specific AST types.
+      # If we passed the wrapper, the generator wouldn't recognize it as a CallNode
+      # and would fall back to a generic signature, breaking matching.
+      #
+      # @example Creating a frozen wrapper
+      #   frozen = NodeTyping::FrozenWrapper.new(prism_node, :frozen)
+      #   frozen.freeze_node?  # => true
+      #   frozen.is_a?(Ast::Merge::Freezable)  # => true
+      #   frozen.unwrap  # => prism_node
+      #
+      # @see Wrapper
+      # @see Ast::Merge::Freezable
+      # @see FreezeNodeBase
+      # @see FileAnalyzable#generate_signature
+      class FrozenWrapper < Wrapper
+        include Ast::Merge::Freezable
+
+        # Create a frozen wrapper for an AST node.
+        #
+        # @param node [Object] The AST node to wrap
+        # @param merge_type [Symbol] The merge type (defaults to :frozen)
+        def initialize(node, merge_type = :frozen)
+          super(node, merge_type)
+        end
+
+        # Returns true to indicate this is a frozen node.
+        # Overrides both Wrapper#typed_node? context and provides freeze_node? from Freezable.
+        #
+        # @return [Boolean] true
+        def frozen_node?
+          true
+        end
+
+        # Returns the content of this frozen node.
+        # Delegates to the wrapped node's slice method.
+        #
+        # @return [String] The node content
+        def slice
+          @node.slice
+        end
+
+        # Returns the signature for this frozen node.
+        # Uses the freeze_signature from Freezable module.
+        #
+        # @return [Array] Signature in the form [:FreezeNode, content]
+        def signature
+          freeze_signature
+        end
+
+        # Forward inspect to show frozen status.
+        def inspect
+          "#<NodeTyping::FrozenWrapper merge_type=#{@merge_type.inspect} node=#{@node.inspect}>"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,197 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    module NodeTyping
+      # Thread-safe backend registration and type normalization for AST merge libraries.
+      #
+      # Normalizer provides a shared, thread-safe mechanism for registering backend-specific
+      # node type mappings and normalizing them to canonical types. This enables portable
+      # merge rules across different parsers/backends for the same file format.
+      #
+      # ## Thread Safety
+      #
+      # All registration and lookup operations are protected by a mutex to ensure
+      # thread-safe access to the backend mappings. This follows the same pattern
+      # used in TreeHaver::LanguageRegistry and TreeHaver::PathValidator.
+      #
+      # ## Usage Pattern
+      #
+      # File-format-specific merge libraries (e.g., toml-merge, markdown-merge) should:
+      # 1. Create their own NodeTypeNormalizer module
+      # 2. Include or extend Ast::Merge::NodeTyping::Normalizer
+      # 3. Define their canonical types and default backend mappings
+      # 4. Call `configure_normalizer` with their initial mappings
+      #
+      # @example Creating a format-specific normalizer
+      #   module Toml
+      #     module Merge
+      #       module NodeTypeNormalizer
+      #         extend Ast::Merge::NodeTyping::Normalizer
+      #
+      #         configure_normalizer(
+      #           tree_sitter_toml: {
+      #             table_array_element: :array_of_tables,
+      #             pair: :pair,
+      #             # ...
+      #           }.freeze,
+      #           citrus_toml: {
+      #             table_array_element: :array_of_tables,
+      #             pair: :pair,
+      #             # ...
+      #           }.freeze
+      #         )
+      #
+      #         # Optional: Add format-specific helper methods
+      #         def self.table_type?(type)
+      #           %i[table array_of_tables].include?(type.to_sym)
+      #         end
+      #       end
+      #     end
+      #   end
+      #
+      # @see TreeHaver::LanguageRegistry
+      # @see TreeHaver::PathValidator
+      module Normalizer
+        # Called when this module is extended into another module.
+        # Sets up the mutex and backend mappings storage.
+        #
+        # @param base [Module] The module extending this one
+        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.
+        #
+        # This should be called once when defining the format-specific normalizer,
+        # providing the default backend mappings. Additional backends can be
+        # registered later via `register_backend`.
+        #
+        # @param mappings [Hash{Symbol => Hash{Symbol => Symbol}}] Initial backend mappings
+        #   Keys are backend identifiers, values are hashes mapping backend types to canonical types
+        # @return [void]
+        #
+        # @example
+        #   configure_normalizer(
+        #     tree_sitter_toml: { table_array_element: :array_of_tables }.freeze,
+        #     citrus_toml: { table_array_element: :array_of_tables }.freeze
+        #   )
+        def configure_normalizer(**mappings)
+          @normalizer_mutex.synchronize do
+            mappings.each do |backend, type_mappings|
+              @backend_mappings[backend.to_sym] = type_mappings.frozen? ? type_mappings : type_mappings.freeze
+            end
+          end
+          nil
+        end
+
+        # Register type mappings for a new backend.
+        #
+        # This allows extending the normalizer to support additional parsers
+        # beyond those configured initially. Thread-safe for runtime registration.
+        #
+        # @param backend [Symbol] Backend identifier (e.g., :my_parser)
+        # @param mappings [Hash{Symbol => Symbol}] Backend type → canonical type mappings
+        # @return [void]
+        #
+        # @example
+        #   NodeTypeNormalizer.register_backend(:my_parser, {
+        #     my_table: :table,
+        #     my_pair: :pair,
+        #   })
+        def register_backend(backend, mappings)
+          @normalizer_mutex.synchronize do
+            @backend_mappings[backend.to_sym] = mappings.frozen? ? mappings : mappings.freeze
+          end
+          nil
+        end
+
+        # Get the canonical type for a backend-specific type.
+        #
+        # If no mapping exists, returns the original type unchanged (passthrough).
+        # This allows backend-specific types to pass through for backend-specific
+        # merge rules.
+        #
+        # @param backend_type [Symbol, String, nil] The backend's node type
+        # @param backend [Symbol] The backend identifier
+        # @return [Symbol, nil] Canonical type (or original if no mapping), nil if input was nil
+        #
+        # @example
+        #   NodeTypeNormalizer.canonical_type(:table_array_element, :tree_sitter_toml)
+        #   # => :array_of_tables
+        #
+        #   NodeTypeNormalizer.canonical_type(:unknown_type, :tree_sitter_toml)
+        #   # => :unknown_type (passthrough)
+        def canonical_type(backend_type, backend = nil)
+          return backend_type if backend_type.nil?
+
+          type_sym = backend_type.to_sym
+          @normalizer_mutex.synchronize do
+            @backend_mappings.dig(backend, type_sym) || type_sym
+          end
+        end
+
+        # Wrap a node with its canonical type as merge_type.
+        #
+        # Uses Ast::Merge::NodeTyping.with_merge_type to create a wrapper
+        # that delegates all methods to the underlying node while adding
+        # a canonical merge_type attribute.
+        #
+        # @param node [Object] The backend node to wrap (must respond to #type)
+        # @param backend [Symbol] The backend identifier
+        # @return [Ast::Merge::NodeTyping::Wrapper] Wrapped node with canonical merge_type
+        #
+        # @example
+        #   wrapped = NodeTypeNormalizer.wrap(node, :tree_sitter_toml)
+        #   wrapped.type        # => :table_array_element (original)
+        #   wrapped.merge_type  # => :array_of_tables (canonical)
+        #   wrapped.unwrap      # => node (original node)
+        def wrap(node, backend)
+          canonical = canonical_type(node.type, backend)
+          Ast::Merge::NodeTyping.with_merge_type(node, canonical)
+        end
+
+        # Get all registered backends.
+        #
+        # @return [Array<Symbol>] Backend identifiers
+        def registered_backends
+          @normalizer_mutex.synchronize do
+            @backend_mappings.keys
+          end
+        end
+
+        # Check if a backend is registered.
+        #
+        # @param backend [Symbol] Backend identifier
+        # @return [Boolean]
+        def backend_registered?(backend)
+          @normalizer_mutex.synchronize do
+            @backend_mappings.key?(backend.to_sym)
+          end
+        end
+
+        # Get the mappings for a specific backend.
+        #
+        # @param backend [Symbol] Backend identifier
+        # @return [Hash{Symbol => Symbol}, nil] The mappings or nil if not registered
+        def mappings_for(backend)
+          @normalizer_mutex.synchronize do
+            @backend_mappings[backend.to_sym]
+          end
+        end
+
+        # Get all canonical types across all backends.
+        #
+        # @return [Array<Symbol>] Unique canonical type symbols
+        def canonical_types
+          @normalizer_mutex.synchronize do
+            @backend_mappings.values.flat_map(&:values).uniq
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    module NodeTyping
+      # Node wrapper that adds a merge_type attribute to an existing node.
+      # This uses a simple delegation pattern to preserve all original node
+      # behavior while adding the merge_type.
+      class Wrapper
+        # @return [Object] The original node being wrapped
+        attr_reader :node
+
+        # @return [Symbol] The custom merge type for this node
+        attr_reader :merge_type
+
+        # Create a new node type wrapper.
+        #
+        # @param node [Object] The original node to wrap
+        # @param merge_type [Symbol] The custom merge type
+        def initialize(node, merge_type)
+          @node = node
+          @merge_type = merge_type
+        end
+
+        # Delegate all unknown methods to the wrapped node.
+        # This allows the wrapper to be used transparently in place of the node.
+        def method_missing(method, *args, &block)
+          if @node.respond_to?(method)
+            @node.send(method, *args, &block)
+          else
+            super
+          end
+        end
+
+        # Check if the wrapped node responds to a method.
+        def respond_to_missing?(method, include_private = false)
+          @node.respond_to?(method, include_private) || super
+        end
+
+        # Returns true to indicate this is a node type wrapper.
+        def typed_node?
+          true
+        end
+
+        # Unwrap to get the original node.
+        # @return [Object] The original unwrapped node
+        def unwrap
+          @node
+        end
+
+        # Forward equality check to the wrapped node.
+        def ==(other)
+          if other.is_a?(Wrapper)
+            @node == other.node && @merge_type == other.merge_type
+          else
+            @node == other
+          end
+        end
+
+        # Forward hash to the wrapped node.
+        def hash
+          [@node, @merge_type].hash
+        end
+
+        # Forward eql? to the wrapped node.
+        def eql?(other)
+          self == other
+        end
+
+        # Forward inspect to show both the type and node.
+        def inspect
+          "#<NodeTyping::Wrapper merge_type=#{@merge_type.inspect} node=#{@node.inspect}>"
+        end
+      end
+    end
+  end
+end

data/lib/ast/merge/node_typing.rb

@@ -46,167 +46,9 @@ module Ast
     # @see MergerConfig
     # @see ConflictResolverBase
     module NodeTyping
-      # Node wrapper that adds a merge_type attribute to an existing node.
-      # This uses a simple delegation pattern to preserve all original node
-      # behavior while adding the merge_type.
-      class Wrapper
-        # @return [Object] The original node being wrapped
-        attr_reader :node
-
-        # @return [Symbol] The custom merge type for this node
-        attr_reader :merge_type
-
-        # Create a new node type wrapper.
-        #
-        # @param node [Object] The original node to wrap
-        # @param merge_type [Symbol] The custom merge type
-        def initialize(node, merge_type)
-          @node = node
-          @merge_type = merge_type
-        end
-
-        # Delegate all unknown methods to the wrapped node.
-        # This allows the wrapper to be used transparently in place of the node.
-        def method_missing(method, *args, &block)
-          if @node.respond_to?(method)
-            @node.send(method, *args, &block)
-          else
-            super
-          end
-        end
-
-        # Check if the wrapped node responds to a method.
-        def respond_to_missing?(method, include_private = false)
-          @node.respond_to?(method, include_private) || super
-        end
-
-        # Returns true to indicate this is a node type wrapper.
-        def typed_node?
-          true
-        end
-
-        # Unwrap to get the original node.
-        # @return [Object] The original unwrapped node
-        def unwrap
-          @node
-        end
-
-        # Forward equality check to the wrapped node.
-        def ==(other)
-          if other.is_a?(Wrapper)
-            @node == other.node && @merge_type == other.merge_type
-          else
-            @node == other
-          end
-        end
-
-        # Forward hash to the wrapped node.
-        def hash
-          [@node, @merge_type].hash
-        end
-
-        # Forward eql? to the wrapped node.
-        def eql?(other)
-          self == other
-        end
-
-        # Forward inspect to show both the type and node.
-        def inspect
-          "#<NodeTyping::Wrapper merge_type=#{@merge_type.inspect} node=#{@node.inspect}>"
-        end
-      end
-
-      # Wrapper for frozen AST nodes that includes Freezable behavior.
-      #
-      # FrozenWrapper extends Wrapper to add freeze node semantics, making the
-      # wrapped node satisfy both the NodeTyping API and the Freezable API.
-      # This enables composition where frozen nodes are:
-      # - Wrapped AST nodes (can unwrap to get original)
-      # - Typed nodes (have merge_type)
-      # - Freeze nodes (satisfy is_a?(Freezable) and freeze_node?)
-      #
-      # ## Key Distinction from FreezeNodeBase
-      #
-      # FrozenWrapper and FreezeNodeBase both include Freezable, but they represent
-      # fundamentally different concepts:
-      #
-      # ### FrozenWrapper (this class)
-      # - Wraps an AST node that has a freeze marker in its leading comments
-      # - The node is still a structural AST node (e.g., a `gem` call in a gemspec)
-      # - During matching, we want to match by the underlying node's IDENTITY
-      #   (e.g., the gem name), NOT by the full content
-      # - Signature generation should unwrap and use the underlying node's structure
-      # - Example: `# token:freeze\ngem "example_gem", "~> 1.0"` wraps a CallNode
-      #
-      # ### FreezeNodeBase
-      # - Represents an explicit freeze block with `# token:freeze ... # token:unfreeze`
-      # - The entire block is opaque content that should be preserved verbatim
-      # - During matching, we match by the full CONTENT of the block
-      # - Signature generation uses freeze_signature (content-based)
-      # - Example: A multi-line comment block with custom formatting
-      #
-      # ## Signature Generation Behavior
-      #
-      # When FileAnalyzable#generate_signature encounters a FrozenWrapper:
-      # 1. It unwraps to get the underlying AST node
-      # 2. Passes the unwrapped node to the signature_generator
-      # 3. This allows the signature generator to recognize the node type
-      #    (e.g., Prism::CallNode) and generate appropriate signatures
-      #
-      # This is critical because signature generators check for specific AST types.
-      # If we passed the wrapper, the generator wouldn't recognize it as a CallNode
-      # and would fall back to a generic signature, breaking matching.
-      #
-      # @example Creating a frozen wrapper
-      #   frozen = NodeTyping::FrozenWrapper.new(prism_node, :frozen)
-      #   frozen.freeze_node?  # => true
-      #   frozen.is_a?(Ast::Merge::Freezable)  # => true
-      #   frozen.unwrap  # => prism_node
-      #
-      # @see Wrapper
-      # @see Ast::Merge::Freezable
-      # @see FreezeNodeBase
-      # @see FileAnalyzable#generate_signature
-      class FrozenWrapper < Wrapper
-        include Ast::Merge::Freezable
-
-        # Create a frozen wrapper for an AST node.
-        #
-        # @param node [Object] The AST node to wrap
-        # @param merge_type [Symbol] The merge type (defaults to :frozen)
-        def initialize(node, merge_type = :frozen)
-          super(node, merge_type)
-        end
-
-        # Returns true to indicate this is a frozen node.
-        # Overrides both Wrapper#typed_node? context and provides freeze_node? from Freezable.
-        #
-        # @return [Boolean] true
-        def frozen_node?
-          true
-        end
-
-        # Returns the content of this frozen node.
-        # Delegates to the wrapped node's slice method.
-        #
-        # @return [String] The node content
-        def slice
-          @node.slice
-        end
-
-        # Returns the signature for this frozen node.
-        # Uses the freeze_signature from Freezable module.
-        #
-        # @return [Array] Signature in the form [:FreezeNode, content]
-        def signature
-          freeze_signature
-        end
-
-        # Forward inspect to show frozen status.
-        def inspect
-          "#<NodeTyping::FrozenWrapper merge_type=#{@merge_type.inspect} node=#{@node.inspect}>"
-        end
-      end
+      autoload :FrozenWrapper, "ast/merge/node_typing/frozen_wrapper"
+      autoload :Normalizer, "ast/merge/node_typing/normalizer"
+      autoload :Wrapper, "ast/merge/node_typing/wrapper"
 
       class << self
         # Wrap a node with a custom merge_type.

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.6"
+      VERSION = "2.0.8"
     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

@@ -574,9 +574,60 @@ module Ast
         def inspect: () -> String
       end
 
+      # Wrapper for frozen AST nodes that includes Freezable behavior
+      class FrozenWrapper < Wrapper
+        include Freezable
+
+        def initialize: (untyped node, ?Symbol merge_type) -> void
+        def frozen_node?: () -> bool
+        def slice: () -> String
+        def signature: () -> Array[untyped]
+        def inspect: () -> String
+      end
+
+      # Thread-safe backend registration and type normalization module.
+      # Extended by format-specific normalizers (e.g., Toml::Merge::NodeTypeNormalizer).
+      module Normalizer
+        @normalizer_mutex: Mutex
+        @backend_mappings: Hash[Symbol, Hash[Symbol, Symbol]]
+
+        # Called when this module is extended into another module
+        def self.extended: (Module base) -> void
+
+        # Configure initial backend mappings
+        # @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
+
+        # Get the canonical type for a backend-specific type
+        def canonical_type: (Symbol | String | nil backend_type, ?Symbol? backend) -> Symbol?
+
+        # Wrap a node with its canonical type as merge_type
+        def wrap: (untyped node, Symbol backend) -> Wrapper
+
+        # Get all registered backends
+        def registered_backends: () -> Array[Symbol]
+
+        # Check if a backend is registered
+        def backend_registered?: (Symbol | String backend) -> bool
+
+        # Get the mappings for a specific backend
+        def mappings_for: (Symbol backend) -> Hash[Symbol, Symbol]?
+
+        # Get all canonical types across all backends
+        def canonical_types: () -> Array[Symbol]
+      end
+
       def self.with_merge_type: (untyped node, Symbol merge_type) -> Wrapper
-      def self.validate!: (node_typing_hash? node_typing) -> void
-      def self.apply: (untyped node, node_typing_hash? node_typing) -> untyped
+      def self.frozen: (untyped node, ?Symbol merge_type) -> FrozenWrapper
+      def self.frozen_node?: (untyped node) -> bool
+      def self.typed_node?: (untyped node) -> bool
+      def self.merge_type_for: (untyped node) -> Symbol?
+      def self.unwrap: (untyped node) -> untyped
+      def self.process: (untyped node, node_typing_hash? typing_config) -> untyped?
+      def self.validate!: (node_typing_hash? typing_config) -> void
     end
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ast-merge
 version: !ruby/object:Gem::Version
-  version: 2.0.6
+  version: 2.0.8
 platform: ruby
 authors:
 - Peter H. Boling
@@ -318,6 +318,10 @@ files:
 - lib/ast/merge/merger_config.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
+- 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
@@ -352,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.6
-  changelog_uri: https://github.com/kettle-rb/ast-merge/blob/v2.0.6/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-rb/ast-merge/tree/v2.0.8
+  changelog_uri: https://github.com/kettle-rb/ast-merge/blob/v2.0.8/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-rb/ast-merge/issues
-  documentation_uri: https://www.rubydoc.info/gems/ast-merge/2.0.6
+  documentation_uri: https://www.rubydoc.info/gems/ast-merge/2.0.8
   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