ast-merge 2.0.6 → 2.0.7

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 86f9ef0462fcd809046dfc7c0486d9ab739badaab3faf4dfa898089479b7b5b1
-  data.tar.gz: f77f27ebd8b050a209c2d94283b93f1282b4f5e3c689229c3ea19432e1d3bafa
+  metadata.gz: ac53c3bf60949d4ce02f751351d3f4be08368945140d94dd8c090b700c92a0dc
+  data.tar.gz: 1eed56c786b9f3b9d86183dabe7aecaad8c989a68987abeb4133a12f20aea6ac
 SHA512:
-  metadata.gz: de6c91e8cb0a86dd1d13a52a2dbda3cd52951f2d4cfd45c171344412a992d59e5db7593c861467df256a798184774c978ddd47abf3c157e5a73b3c994ad337b5
-  data.tar.gz: 3ec3274c3366c5bbcd2362ebc0abf71e54292afefa42022fa673996141a43f5385b54c87ca5bf5c15ee2d5267a73544e8316d81bae47ff0ec37dd7772d990566
+  metadata.gz: d693729fe0371f440fd8223c7896d1cbfc267229a384aa36484d891a3b5b9e59c872646a721f168e696382d23f7fa54d4dd80073615e45dfb30e3e065b9a85d5
+  data.tar.gz: 487bc8bf2ad2c2031c37f0fccbce0aeffc06aa21d2e0d962b74a71586b99d60011177abc92fc1fddc6b0675cf4e6a1894d60743c23d6e3dcf7746d42f9fd9153

data/CHANGELOG.md

@@ -30,6 +30,33 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [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 +407,9 @@ 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.7...HEAD
+[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.640-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,195 @@
+# 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
+        def self.extended(base)
+          base.instance_variable_set(:@normalizer_mutex, Mutex.new)
+          base.instance_variable_set(:@backend_mappings, {})
+        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/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.7"
     end
     VERSION = Version::VERSION # traditional location
   end

data/sig/ast/merge.rbs

@@ -574,9 +574,59 @@ 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
+        def configure_normalizer: (**Hash[Symbol, Symbol] mappings) -> 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.7
 platform: ruby
 authors:
 - Peter H. Boling
@@ -318,6 +318,9 @@ 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/partial_template_merger.rb
 - lib/ast/merge/recipe.rb
 - lib/ast/merge/recipe/config.rb
@@ -352,10 +355,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.7
+  changelog_uri: https://github.com/kettle-rb/ast-merge/blob/v2.0.7/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.7
   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