ast-merge 4.0.0 → 4.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 871eebc1f2c69aa75278023c250fd90905cf2fb4e23677fbcfd49633bad5ebb1
-  data.tar.gz: 3804ee9f9f61effc21c49862a96b0092481067813c79b1b4fdb09a748b935570
+  metadata.gz: e6af6467980a8e2076bd454a35bea42e18064fed0651704754f459353a85087a
+  data.tar.gz: 1d89bad2aa237d11aafd957f68391d8ca83248cc0f7946bad54e788cc1fa05c2
 SHA512:
-  metadata.gz: 340c3feee108349b603db2150baa68467b45c7414be0d1fdcfaac10038d3cfca2dc893dc81a489adae66bbfc8d9474f7128e7f0817abc9703ba6694719a48b91
-  data.tar.gz: 5f135b944efe203fe0f83cf2d141e18de4e64be096a3293c0db09b3f5672790b6cdbad6956ef511c657b43c0e0b162050ec57d46d7da659895554c16e2eac6c4
+  metadata.gz: a45b949a5b6b835ba26d0422eb855daa9a62e513131bf06627abe8b68dba2daae28dd835f51fce43758c36f652fb44851885adcec3f82a64519bc2baed6f77f9
+  data.tar.gz: c2a7c05cedc23b3552f5eaef980cc890cf034060efe82f51f0c7acc98cba5b5df3bc2441a96bcde188c48391baebe5474dd76f735e5a2dbda053ff85b07a6748

data/CHANGELOG.md

@@ -30,6 +30,46 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [4.0.1] - 2026-01-11
+
+- TAG: [v4.0.1][4.0.1t]
+- COVERAGE: 96.45% -- 2553/2647 lines in 51 files
+- BRANCH COVERAGE: 87.41% -- 812/929 branches in 51 files
+- 98.80% documented
+
+### Added
+
+- **`Ast::Merge::RSpec::MergeGemRegistry`** - Fully dynamic merge gem registration for RSpec dependency tags
+  - `register(tag_name, require_path:, merger_class:, test_source:, category:)` - Register a merge gem
+  - `available?(tag_name)` - Check if a merge gem is available and functional
+  - `registered_gems` - Get all registered gem tag names
+  - `gems_by_category(category)` - Filter gems by category (:markdown, :data, :code, :config, :other)
+  - `summary` - Get availability status of all registered gems
+  - Automatically defines `*_available?` methods on `DependencyTags` at registration time
+  - External merge gems can now get full RSpec tag support without modifying ast-merge
+
+### Changed
+
+- Upgrade to [tree_haver v5.0.1](https://github.com/kettle-rb/tree_haver/releases/tag/v5.0.1)
+- **`Ast::Merge::AstNode` now inherits from `TreeHaver::Base::Node`**
+  - Ensures synthetic nodes stay in sync with the canonical Node API
+  - Inherits `Comparable`, `Enumerable` from base class
+  - Retains all existing methods and behavior (Point, Location, signature, etc.)
+  - Constructor calls `super(self, source: source)` to properly initialize base class
+- **RSpec Dependency Tags refactored to use MergeGemRegistry**
+  - Removed hardcoded merge gem availability checks
+  - Removed `MERGE_GEM_TEST_SOURCES` constant
+  - `*_available?` methods are now defined dynamically when gems register
+  - `any_markdown_merge_available?` now queries registry by category
+  - RSpec exclusion filters are configured dynamically from registry
+- `Ast::Merge::Testing::TestableNode` now delegates to `TreeHaver::RSpec::TestableNode`
+  - The TestableNode implementation has been moved to tree_haver for sharing across all merge gems
+  - `spec/support/testable_node.rb` now requires and re-exports the tree_haver version
+  - Backward compatible: existing tests continue to work unchanged
+- `spec/ast/merge/node_wrapper_base_spec.rb` refactored to use `TestableNode` instead of mocks
+  - Real TreeHaver::Node behavior for most tests
+  - Mocks only retained for edge case testing (e.g., invalid end_line before start_line)
+
 ## [4.0.0] - 2026-01-11
 
 - TAG: [v4.0.0][4.0.0t]
@@ -597,7 +637,9 @@ Please file a bug if you notice a violation of semantic versioning.
 
 - Initial release
 
-[Unreleased]: https://github.com/kettle-rb/ast-merge/compare/v4.0.0...HEAD
+[Unreleased]: https://github.com/kettle-rb/ast-merge/compare/v4.0.1...HEAD
+[4.0.1]: https://github.com/kettle-rb/ast-merge/compare/v4.0.0...v4.0.1
+[4.0.1t]: https://github.com/kettle-rb/ast-merge/releases/tag/v4.0.1
 [4.0.0]: https://github.com/kettle-rb/ast-merge/compare/v3.1.0...v4.0.0
 [4.0.0t]: https://github.com/kettle-rb/ast-merge/releases/tag/v4.0.0
 [3.1.0]: https://github.com/kettle-rb/ast-merge/compare/v3.0.0...v3.1.0

data/lib/ast/merge/ast_node.rb

@@ -8,9 +8,9 @@ module Ast
     # created by ast-merge for representing content that doesn't have a native
     # AST (comments, text lines, env file entries, etc.).
     #
-    # This class implements the TreeHaver::Node protocol, making it compatible
-    # with all code that expects TreeHaver nodes. This allows synthetic nodes
-    # to be used interchangeably with parser-backed nodes in merge operations.
+    # This class inherits from TreeHaver::Base::Node, ensuring it stays in sync
+    # with the canonical Node API. This allows synthetic nodes to be used
+    # interchangeably with parser-backed nodes in merge operations.
     #
     # Implements the TreeHaver::Node protocol:
     # - type → String node type
@@ -36,12 +36,10 @@ module Ast
     #     end
     #   end
     #
-    # @see TreeHaver::Node The protocol this class implements
+    # @see TreeHaver::Base::Node The base class defining the canonical Node API
     # @see Comment::Line Example synthetic node for comments
     # @see Text::LineNode Example synthetic node for text lines
-    class AstNode
-      include Comparable
-
+    class AstNode < TreeHaver::Base::Node
       # Point class compatible with TreeHaver::Point
       # Provides both method and hash-style access to row/column
       Point = Struct.new(:row, :column, keyword_init: true) do
@@ -83,9 +81,6 @@ module Ast
       # @return [String] The source text for this node
       attr_reader :slice
 
-      # @return [String, nil] The full source text (for text extraction)
-      attr_reader :source
-
       # Initialize a new AstNode.
       #
       # @param slice [String] The source text for this node
@@ -94,15 +89,14 @@ module Ast
       def initialize(slice:, location:, source: nil)
         @slice = slice
         @location = location
-        @source = source
+        # Call parent constructor with self as inner_node
+        super(self, source: source)
       end
 
-      # TreeHaver::Node protocol: inner_node
-      # For synthetic nodes, this returns self (no wrapping layer)
-      #
-      # @return [AstNode] self
-      def inner_node
-        self
+      # Override source to return stored value (not parent's)
+      # @return [String, nil] The full source text (for text extraction)
+      def source
+        @source || super
       end
 
       # TreeHaver::Node protocol: type
@@ -132,10 +126,11 @@ module Ast
       #
       # @return [Integer] Starting byte offset
       def start_byte
-        return 0 unless source && location
+        src = source
+        return 0 unless src && location
 
         # Calculate byte offset from line/column
-        lines = source.lines
+        lines = src.lines
         byte_offset = 0
         (0...(location.start_line - 1)).each do |i|
           byte_offset += lines[i]&.bytesize || 0
@@ -249,6 +244,7 @@ module Ast
       end
 
       # Comparable: compare nodes by position
+      # Note: Inherits Comparable from TreeHaver::Base::Node
       #
       # @param other [AstNode] node to compare with
       # @return [Integer, nil] -1, 0, 1, or nil if not comparable

data/lib/ast/merge/diff_mapper_base.rb

@@ -227,7 +227,7 @@ module Ast
           next unless node.respond_to?(:start_line) && node.respond_to?(:end_line)
           next unless node.start_line && node.end_line
 
-          line_num >= node.start_line && line_num <= node.end_line
+          line_num.between?(node.start_line, node.end_line)
         end
       end
 

data/lib/ast/merge/rspec/dependency_tags.rb

@@ -1,10 +1,11 @@
 # frozen_string_literal: true
 
+require_relative "merge_gem_registry"
+
 # Ast::Merge RSpec Dependency Tags
 #
 # This module provides dependency detection helpers for conditional test execution
-# in the ast-merge gem family. It extends tree_haver's dependency tags with
-# merge-gem-specific checks.
+# in the ast-merge gem family. It uses MergeGemRegistry for dynamic merge gem detection.
 #
 # @example Loading in spec_helper.rb
 #   require "ast/merge/rspec/dependency_tags"
@@ -18,50 +19,26 @@
 #     # This test only runs when prism-merge is available
 #   end
 #
-# == Available Tags
-#
-# === Merge Gem Tags (run when dependency IS available)
-#
-# [:markly_merge]
-#   markly-merge gem is available and functional.
-#
-# [:commonmarker_merge]
-#   commonmarker-merge gem is available and functional.
-#
-# [:markdown_merge]
-#   markdown-merge gem is available and functional.
-#
-# [:prism_merge]
-#   prism-merge gem is available and functional.
-#
-# [:json_merge]
-#   json-merge gem is available and functional.
+# == Dynamic Tag Registration
 #
-# [:jsonc_merge]
-#   jsonc-merge gem is available and functional.
+# Merge gems register themselves with MergeGemRegistry, which automatically:
+# - Defines `*_available?` methods on DependencyTags
+# - Configures RSpec exclusion filters for the tag
+# - Supports negated tags (`:not_*`)
 #
-# [:toml_merge]
-#   toml-merge gem is available and functional.
+# @example How merge gems register (in their lib file)
+#   Ast::Merge::RSpec::MergeGemRegistry.register(
+#     :markly_merge,
+#     require_path: "markly/merge",
+#     merger_class: "Markly::Merge::SmartMerger",
+#     test_source: "# Test\n\nParagraph",
+#     category: :markdown
+#   )
 #
-# [:bash_merge]
-#   bash-merge gem is available and functional.
-#
-# [:psych_merge]
-#   psych-merge gem is available and functional.
-#
-# [:rbs_merge]
-#   rbs-merge gem is available and functional.
+# == Built-in Composite Tags
 #
 # [:any_markdown_merge]
-#   At least one markdown merge gem (markly-merge or commonmarker-merge) is available.
-#
-# === Negated Tags (run when dependency is NOT available)
-#
-# All positive tags have negated versions prefixed with `not_`:
-# - :not_markly_merge, :not_commonmarker_merge, :not_markdown_merge
-# - :not_prism_merge, :not_json_merge, :not_jsonc_merge
-# - :not_toml_merge, :not_bash_merge, :not_psych_merge, :not_rbs_merge
-# - :not_any_markdown_merge
+#   At least one markdown merge gem is available (category: :markdown).
 
 module Ast
   module Merge
@@ -70,96 +47,16 @@ module Ast
       module DependencyTags
         class << self
           # ============================================================
-          # Merge Gem Availability
+          # Composite Availability Checks
           # ============================================================
 
-          # rubocop:disable ThreadSafety/ClassInstanceVariable
-          # Check if markly-merge is available and functional
-          #
-          # @return [Boolean] true if markly-merge works
-          def markly_merge_available?
-            return @markly_merge_available if defined?(@markly_merge_available)
-            @markly_merge_available = merge_gem_works?("markly/merge", "Markly::Merge::SmartMerger", "# Test\n\nParagraph")
-          end
-
-          # Check if commonmarker-merge is available and functional
-          #
-          # @return [Boolean] true if commonmarker-merge works
-          def commonmarker_merge_available?
-            return @commonmarker_merge_available if defined?(@commonmarker_merge_available)
-            @commonmarker_merge_available = merge_gem_works?("commonmarker/merge", "Commonmarker::Merge::SmartMerger", "# Test\n\nParagraph")
-          end
-
-          # Check if markdown-merge is available and functional
-          #
-          # @return [Boolean] true if markdown-merge works
-          def markdown_merge_available?
-            return @markdown_merge_available if defined?(@markdown_merge_available)
-            @markdown_merge_available = merge_gem_works?("markdown/merge", "Markdown::Merge::SmartMerger", "# Test\n\nParagraph")
-          end
-
-          # Check if prism-merge is available and functional
-          #
-          # @return [Boolean] true if prism-merge works
-          def prism_merge_available?
-            return @prism_merge_available if defined?(@prism_merge_available)
-            @prism_merge_available = merge_gem_works?("prism/merge", "Prism::Merge::SmartMerger", "puts 1")
-          end
-
-          # Check if json-merge is available and functional
-          #
-          # @return [Boolean] true if json-merge works
-          def json_merge_available?
-            return @json_merge_available if defined?(@json_merge_available)
-            @json_merge_available = merge_gem_works?("json/merge", "Json::Merge::SmartMerger", '{"key": "value"}')
-          end
-
-          # Check if jsonc-merge is available and functional
-          #
-          # @return [Boolean] true if jsonc-merge works
-          def jsonc_merge_available?
-            return @jsonc_merge_available if defined?(@jsonc_merge_available)
-            @jsonc_merge_available = merge_gem_works?("jsonc/merge", "Jsonc::Merge::SmartMerger", '{"key": "value" /* comment */}')
-          end
-
-          # Check if toml-merge is available and functional
-          #
-          # @return [Boolean] true if toml-merge works
-          def toml_merge_available?
-            return @toml_merge_available if defined?(@toml_merge_available)
-            @toml_merge_available = merge_gem_works?("toml/merge", "Toml::Merge::SmartMerger", 'key = "value"')
-          end
-
-          # Check if bash-merge is available and functional
-          #
-          # @return [Boolean] true if bash-merge works
-          def bash_merge_available?
-            return @bash_merge_available if defined?(@bash_merge_available)
-            @bash_merge_available = merge_gem_works?("bash/merge", "Bash::Merge::SmartMerger", "echo hello")
-          end
-
-          # Check if psych-merge is available and functional
-          #
-          # @return [Boolean] true if psych-merge works
-          def psych_merge_available?
-            return @psych_merge_available if defined?(@psych_merge_available)
-            @psych_merge_available = merge_gem_works?("psych/merge", "Psych::Merge::SmartMerger", "key: value")
-          end
-
-          # Check if rbs-merge is available and functional
-          #
-          # @return [Boolean] true if rbs-merge works
-          def rbs_merge_available?
-            return @rbs_merge_available if defined?(@rbs_merge_available)
-            @rbs_merge_available = merge_gem_works?("rbs/merge", "Rbs::Merge::SmartMerger", "class Foo end")
-          end
-          # rubocop:enable ThreadSafety/ClassInstanceVariable
-
           # Check if at least one markdown merge gem is available
           #
           # @return [Boolean] true if any markdown merge gem works
           def any_markdown_merge_available?
-            markly_merge_available? || commonmarker_merge_available? || markdown_merge_available?
+            MergeGemRegistry.gems_by_category(:markdown).any? do |tag|
+              MergeGemRegistry.available?(tag)
+            end
           end
 
           # ============================================================
@@ -170,45 +67,16 @@ module Ast
           #
           # @return [Hash{Symbol => Boolean}] map of dependency name to availability
           def summary
-            {
-              markly_merge: markly_merge_available?,
-              commonmarker_merge: commonmarker_merge_available?,
-              markdown_merge: markdown_merge_available?,
-              prism_merge: prism_merge_available?,
-              json_merge: json_merge_available?,
-              jsonc_merge: jsonc_merge_available?,
-              toml_merge: toml_merge_available?,
-              bash_merge: bash_merge_available?,
-              psych_merge: psych_merge_available?,
-              rbs_merge: rbs_merge_available?,
-              any_markdown_merge: any_markdown_merge_available?,
-            }
+            result = MergeGemRegistry.summary
+            result[:any_markdown_merge] = any_markdown_merge_available?
+            result
           end
 
           # Reset all memoized availability checks
           #
           # @return [void]
           def reset!
-            instance_variables.each do |ivar|
-              remove_instance_variable(ivar) if ivar.to_s.end_with?("_available")
-            end
-          end
-
-          private
-
-          # Generic helper to check if a merge gem is available and functional
-          #
-          # @param require_path [String] the require path for the gem
-          # @param merger_class [String] the full class name of the SmartMerger
-          # @param test_source [String] sample source code to test merging
-          # @return [Boolean] true if the merger can be instantiated
-          def merge_gem_works?(require_path, merger_class, test_source)
-            require require_path
-            klass = Object.const_get(merger_class)
-            klass.new(test_source, test_source)
-            true
-          rescue LoadError, StandardError
-            false
+            MergeGemRegistry.reset_availability!
           end
         end
       end
@@ -219,10 +87,11 @@ end
 # Configure RSpec with dependency-based exclusion filters
 RSpec.configure do |config|
   deps = Ast::Merge::RSpec::DependencyTags
+  registry = Ast::Merge::RSpec::MergeGemRegistry
 
   config.before(:suite) do
     # Print dependency summary if AST_MERGE_DEBUG is set
-    if ENV["AST_MERGE_DEBUG"]
+    unless ENV.fetch("AST_MERGE_DEBUG", "false").casecmp?("false")
       puts "\n=== Ast::Merge Test Dependencies ==="
       deps.summary.each do |dep, available|
         status = available ? "✓ available" : "✗ not available"
@@ -233,34 +102,24 @@ RSpec.configure do |config|
   end
 
   # ============================================================
-  # Merge Gem Tags
+  # Dynamic Merge Gem Tags
   # ============================================================
+  # Tags are configured dynamically based on what's registered in MergeGemRegistry.
+  # Each merge gem registers itself, and exclusion filters are set up automatically.
 
-  config.filter_run_excluding(markly_merge: true) unless deps.markly_merge_available?
-  config.filter_run_excluding(commonmarker_merge: true) unless deps.commonmarker_merge_available?
-  config.filter_run_excluding(markdown_merge: true) unless deps.markdown_merge_available?
-  config.filter_run_excluding(prism_merge: true) unless deps.prism_merge_available?
-  config.filter_run_excluding(json_merge: true) unless deps.json_merge_available?
-  config.filter_run_excluding(jsonc_merge: true) unless deps.jsonc_merge_available?
-  config.filter_run_excluding(toml_merge: true) unless deps.toml_merge_available?
-  config.filter_run_excluding(bash_merge: true) unless deps.bash_merge_available?
-  config.filter_run_excluding(psych_merge: true) unless deps.psych_merge_available?
-  config.filter_run_excluding(rbs_merge: true) unless deps.rbs_merge_available?
-  config.filter_run_excluding(any_markdown_merge: true) unless deps.any_markdown_merge_available?
+  registry.registered_gems.each do |tag|
+    # Positive tag: run when gem IS available
+    config.filter_run_excluding(tag => true) unless registry.available?(tag)
+
+    # Negated tag: run when gem is NOT available
+    negated_tag = :"not_#{tag}"
+    config.filter_run_excluding(negated_tag => true) if registry.available?(tag)
+  end
 
   # ============================================================
-  # Negated Tags (run when dependency is NOT available)
+  # Composite Tags
   # ============================================================
 
-  config.filter_run_excluding(not_markly_merge: true) if deps.markly_merge_available?
-  config.filter_run_excluding(not_commonmarker_merge: true) if deps.commonmarker_merge_available?
-  config.filter_run_excluding(not_markdown_merge: true) if deps.markdown_merge_available?
-  config.filter_run_excluding(not_prism_merge: true) if deps.prism_merge_available?
-  config.filter_run_excluding(not_json_merge: true) if deps.json_merge_available?
-  config.filter_run_excluding(not_jsonc_merge: true) if deps.jsonc_merge_available?
-  config.filter_run_excluding(not_toml_merge: true) if deps.toml_merge_available?
-  config.filter_run_excluding(not_bash_merge: true) if deps.bash_merge_available?
-  config.filter_run_excluding(not_psych_merge: true) if deps.psych_merge_available?
-  config.filter_run_excluding(not_rbs_merge: true) if deps.rbs_merge_available?
+  config.filter_run_excluding(any_markdown_merge: true) unless deps.any_markdown_merge_available?
   config.filter_run_excluding(not_any_markdown_merge: true) if deps.any_markdown_merge_available?
 end

data/lib/ast/merge/rspec/merge_gem_registry.rb

@@ -0,0 +1,382 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    module RSpec
+      # Registry for merge gem dependency tag availability checkers
+      #
+      # This module allows merge gems (like markly-merge, prism-merge, json-merge)
+      # to register their availability checker for RSpec dependency tags without
+      # ast-merge needing to know about them directly.
+      #
+      # == Purpose
+      #
+      # When running RSpec tests with dependency tags (e.g., `:markly_merge`),
+      # ast-merge needs to know if each merge gem is available. The MergeGemRegistry
+      # provides a way for gems to register their availability checkers, and also
+      # pre-configures known merge gems so they can be checked before being loaded.
+      #
+      # == Pre-configured Gems
+      #
+      # The following merge gems are pre-configured so that their availability can
+      # be checked before they are loaded (e.g., during RSpec setup):
+      # - :markly_merge, :commonmarker_merge, :markdown_merge (markdown)
+      # - :prism_merge, :bash_merge, :rbs_merge (code)
+      # - :json_merge, :jsonc_merge (data)
+      # - :toml_merge, :psych_merge, :dotenv_merge (config)
+      #
+      # External merge gems can also register themselves by calling {register}
+      # when loaded.
+      #
+      # == Registration
+      #
+      # Each merge gem registers itself when loaded using {register}:
+      # - Tag name (e.g., :markly_merge)
+      # - Require path (e.g., "markly/merge")
+      # - Merger class name (e.g., "Markly::Merge::SmartMerger")
+      # - Test source code to verify the merger works
+      # - Optional category for grouping (e.g., :markdown, :data, :code)
+      #
+      # When a tag is registered, an availability method is automatically defined
+      # on `Ast::Merge::RSpec::DependencyTags`.
+      #
+      # == Thread Safety
+      #
+      # All operations are thread-safe using a Mutex for synchronization.
+      # Results are cached after first check for performance.
+      #
+      # @example Registering a merge gem (in your gem's lib file)
+      #   # In markly-merge/lib/markly/merge.rb
+      #   if defined?(Ast::Merge::RSpec::MergeGemRegistry)
+      #     Ast::Merge::RSpec::MergeGemRegistry.register(
+      #       :markly_merge,
+      #       require_path: "markly/merge",
+      #       merger_class: "Markly::Merge::SmartMerger",
+      #       test_source: "# Test\n\nParagraph",
+      #       category: :markdown
+      #     )
+      #   end
+      #
+      # @example Checking availability
+      #   Ast::Merge::RSpec::MergeGemRegistry.available?(:markly_merge)  # => true/false
+      #
+      # @example Getting all registered gems
+      #   Ast::Merge::RSpec::MergeGemRegistry.registered_gems # => [:markly_merge, :prism_merge, ...]
+      #
+      # @see Ast::Merge::RSpec::DependencyTags Uses MergeGemRegistry for dynamic gem detection
+      # @api public
+      module MergeGemRegistry
+        @mutex = Mutex.new
+        @registry = {} # rubocop:disable ThreadSafety/MutableClassInstanceVariable
+        @availability_cache = {} # rubocop:disable ThreadSafety/MutableClassInstanceVariable
+
+        # Valid categories for merge gems
+        CATEGORIES = %i[markdown data code config other].freeze
+
+        # Pre-configured known merge gems
+        # These can be checked before the gems are actually loaded
+        KNOWN_GEMS = {
+          # Markdown gems
+          markly_merge: {
+            require_path: "markly/merge",
+            merger_class: "Markly::Merge::SmartMerger",
+            test_source: "# Test\n\nParagraph",
+            category: :markdown,
+            skip_instantiation: false,
+          },
+          commonmarker_merge: {
+            require_path: "commonmarker/merge",
+            merger_class: "Commonmarker::Merge::SmartMerger",
+            test_source: "# Test\n\nParagraph",
+            category: :markdown,
+            skip_instantiation: false,
+          },
+          markdown_merge: {
+            require_path: "markdown/merge",
+            merger_class: "Markdown::Merge::SmartMerger",
+            test_source: "# Test\n\nParagraph",
+            category: :markdown,
+            skip_instantiation: true, # Requires backend
+          },
+          # Code gems
+          prism_merge: {
+            require_path: "prism/merge",
+            merger_class: "Prism::Merge::SmartMerger",
+            test_source: "def foo; end",
+            category: :code,
+            skip_instantiation: false,
+          },
+          bash_merge: {
+            require_path: "bash/merge",
+            merger_class: "Bash::Merge::SmartMerger",
+            test_source: "#!/bin/bash\necho hello",
+            category: :code,
+            skip_instantiation: false,
+          },
+          rbs_merge: {
+            require_path: "rbs/merge",
+            merger_class: "Rbs::Merge::SmartMerger",
+            test_source: "class Foo\nend",
+            category: :code,
+            skip_instantiation: false,
+          },
+          # Data gems
+          json_merge: {
+            require_path: "json/merge",
+            merger_class: "Json::Merge::SmartMerger",
+            test_source: '{"key": "value"}',
+            category: :data,
+            skip_instantiation: false,
+          },
+          jsonc_merge: {
+            require_path: "jsonc/merge",
+            merger_class: "Jsonc::Merge::SmartMerger",
+            test_source: "// comment\n{\"key\": \"value\"}",
+            category: :data,
+            skip_instantiation: false,
+          },
+          # Config gems
+          toml_merge: {
+            require_path: "toml/merge",
+            merger_class: "Toml::Merge::SmartMerger",
+            test_source: "[section]\nkey = \"value\"",
+            category: :config,
+            skip_instantiation: false,
+          },
+          psych_merge: {
+            require_path: "psych/merge",
+            merger_class: "Psych::Merge::SmartMerger",
+            test_source: "key: value",
+            category: :config,
+            skip_instantiation: false,
+          },
+          dotenv_merge: {
+            require_path: "dotenv/merge",
+            merger_class: "Dotenv::Merge::SmartMerger",
+            test_source: "KEY=value",
+            category: :config,
+            skip_instantiation: false,
+          },
+        }.freeze
+
+        module_function
+
+        # Register a merge gem for dependency tag support
+        #
+        # When a gem is registered, this also dynamically defines a `*_available?` method
+        # on `Ast::Merge::RSpec::DependencyTags` if it doesn't already exist.
+        #
+        # @param tag_name [Symbol] the RSpec tag name (e.g., :markly_merge)
+        # @param require_path [String] the require path for the gem (e.g., "markly/merge")
+        # @param merger_class [String] the full class name of the SmartMerger
+        # @param test_source [String] sample source code to test merging
+        # @param category [Symbol] category for grouping (:markdown, :data, :code, :config, :other)
+        # @param skip_instantiation [Boolean] if true, only check class exists (for gems requiring backends)
+        # @return [void]
+        #
+        # @example Register a merge gem
+        #   Ast::Merge::RSpec::MergeGemRegistry.register(
+        #     :markly_merge,
+        #     require_path: "markly/merge",
+        #     merger_class: "Markly::Merge::SmartMerger",
+        #     test_source: "# Test\n\nParagraph",
+        #     category: :markdown
+        #   )
+        def register(tag_name, require_path:, merger_class:, test_source:, category: :other, skip_instantiation: false)
+          raise ArgumentError, "Invalid category: #{category}" unless CATEGORIES.include?(category)
+
+          tag_sym = tag_name.to_sym
+
+          @mutex.synchronize do
+            @registry[tag_sym] = {
+              require_path: require_path,
+              merger_class: merger_class,
+              test_source: test_source,
+              category: category,
+              skip_instantiation: skip_instantiation,
+            }
+            # Clear cache when re-registering
+            @availability_cache.delete(tag_sym)
+          end
+
+          # Define availability method on DependencyTags
+          define_availability_method(tag_sym)
+
+          nil
+        end
+
+        # Check if a merge gem is available and functional
+        #
+        # This method will try to load the gem if it's not yet registered but
+        # is known (in KNOWN_GEMS). This allows availability checking before
+        # the gem is explicitly loaded.
+        #
+        # @param tag_name [Symbol] the tag name to check
+        # @return [Boolean] true if the merge gem is available and works
+        def available?(tag_name)
+          tag_sym = tag_name.to_sym
+
+          # Check cache first
+          @mutex.synchronize do
+            return @availability_cache[tag_sym] if @availability_cache.key?(tag_sym)
+          end
+
+          # Get registration info (from registry or known gems)
+          info = @mutex.synchronize { @registry[tag_sym] }
+          info ||= KNOWN_GEMS[tag_sym]
+
+          return false unless info
+
+          # Check if gem works
+          result = gem_works?(
+            info[:require_path],
+            info[:merger_class],
+            info[:test_source],
+            info[:skip_instantiation],
+          )
+
+          # Cache result
+          @mutex.synchronize do
+            @availability_cache[tag_sym] = result
+          end
+
+          result
+        end
+
+        # Check if a tag is registered
+        #
+        # @param tag_name [Symbol] the tag name
+        # @return [Boolean] true if the tag is registered
+        def registered?(tag_name)
+          @mutex.synchronize do
+            @registry.key?(tag_name.to_sym)
+          end
+        end
+
+        # Get all registered gem tag names (including pre-configured known gems)
+        #
+        # @return [Array<Symbol>] list of registered tag names
+        def registered_gems
+          @mutex.synchronize do
+            (KNOWN_GEMS.keys + @registry.keys).uniq
+          end
+        end
+
+        # Get gems filtered by category
+        #
+        # @param category [Symbol] one of :markdown, :data, :code, :config, :other
+        # @return [Array<Symbol>] list of tag names in that category
+        def gems_by_category(category)
+          @mutex.synchronize do
+            known = KNOWN_GEMS.select { |_, info| info[:category] == category }.keys
+            registered = @registry.select { |_, info| info[:category] == category }.keys
+            (known + registered).uniq
+          end
+        end
+
+        # Get registration info for a gem
+        #
+        # @param tag_name [Symbol] the tag name
+        # @return [Hash, nil] registration info or nil if not registered/known
+        def info(tag_name)
+          tag_sym = tag_name.to_sym
+          @mutex.synchronize do
+            @registry[tag_sym]&.dup || KNOWN_GEMS[tag_sym]&.dup
+          end
+        end
+
+        # Get a summary of all registered gems and their availability
+        #
+        # @return [Hash{Symbol => Boolean}] map of tag name to availability
+        def summary
+          registered_gems.each_with_object({}) do |tag, result|
+            result[tag] = available?(tag)
+          end
+        end
+
+        # Clear the availability cache
+        #
+        # @return [void]
+        def clear_cache!
+          @mutex.synchronize do
+            @availability_cache.clear
+          end
+          nil
+        end
+
+        # Clear all registrations and cache
+        #
+        # @return [void]
+        def clear!
+          @mutex.synchronize do
+            @registry.clear
+            @availability_cache.clear
+          end
+          nil
+        end
+
+        # Reset memoized availability on DependencyTags
+        #
+        # @return [void]
+        def reset_availability!
+          clear_cache!
+          return unless defined?(DependencyTags)
+
+          registered_gems.each do |tag|
+            ivar = :"@#{tag}_available"
+            DependencyTags.remove_instance_variable(ivar) if DependencyTags.instance_variable_defined?(ivar)
+          end
+        end
+
+        # ============================================================
+        # Private Helpers
+        # ============================================================
+
+        # Check if a merge gem is available and functional
+        #
+        # @param require_path [String] the require path for the gem
+        # @param merger_class [String] the full class name of the SmartMerger
+        # @param test_source [String] sample source code to test merging
+        # @param skip_instantiation [Boolean] if true, only check class exists
+        # @return [Boolean] true if the merger can be loaded/instantiated
+        # @api private
+        def gem_works?(require_path, merger_class, test_source, skip_instantiation)
+          require require_path
+          klass = Object.const_get(merger_class)
+
+          if skip_instantiation
+            # Just check that the class exists and looks like a SmartMerger
+            klass.is_a?(Class) && klass.ancestors.any? { |a| a.name&.include?("SmartMergerBase") }
+          else
+            klass.new(test_source, test_source)
+            true
+          end
+        rescue LoadError, StandardError
+          false
+        end
+        private_class_method :gem_works?
+
+        # Dynamically define an availability method on DependencyTags
+        #
+        # @param tag_name [Symbol] the tag name (e.g., :markly_merge)
+        # @return [void]
+        # @api private
+        def define_availability_method(tag_name)
+          method_name = :"#{tag_name}_available?"
+
+          # Only define if DependencyTags is loaded
+          return unless defined?(DependencyTags)
+
+          # Don't override existing methods
+          return if DependencyTags.respond_to?(method_name)
+
+          # Define the method dynamically - MergeGemRegistry.available? handles caching
+          DependencyTags.define_singleton_method(method_name) do
+            MergeGemRegistry.available?(tag_name)
+          end
+        end
+        private_class_method :define_availability_method
+      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 = "4.0.0"
+      VERSION = "4.0.1"
     end
     VERSION = Version::VERSION # traditional location
   end

data/lib/ast/merge.rb

@@ -3,6 +3,9 @@
 # External gems
 require "version_gem"
 
+# Normalized AST for all languages, parsers, and platforms
+require "tree_haver"
+
 # This gem - only version can be required (never autoloaded)
 require_relative "merge/version"
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ast-merge
 version: !ruby/object:Gem::Version
-  version: 4.0.0
+  version: 4.0.1
 platform: ruby
 authors:
 - Peter H. Boling
@@ -66,7 +66,7 @@ dependencies:
         version: '5.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.0.0
+        version: 5.0.1
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -76,7 +76,7 @@ dependencies:
         version: '5.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.0.0
+        version: 5.0.1
 - !ruby/object:Gem::Dependency
   name: kettle-dev
   requirement: !ruby/object:Gem::Requirement
@@ -355,6 +355,7 @@ files:
 - lib/ast/merge/recipe/script_loader.rb
 - lib/ast/merge/rspec.rb
 - lib/ast/merge/rspec/dependency_tags.rb
+- lib/ast/merge/rspec/merge_gem_registry.rb
 - lib/ast/merge/rspec/shared_examples.rb
 - lib/ast/merge/rspec/shared_examples/conflict_resolver_base.rb
 - lib/ast/merge/rspec/shared_examples/debug_logger.rb
@@ -381,10 +382,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://ast-merge.galtzo.com/
-  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
+  source_code_uri: https://github.com/kettle-rb/ast-merge/tree/v4.0.1
+  changelog_uri: https://github.com/kettle-rb/ast-merge/blob/v4.0.1/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-rb/ast-merge/issues
-  documentation_uri: https://www.rubydoc.info/gems/ast-merge/4.0.0
+  documentation_uri: https://www.rubydoc.info/gems/ast-merge/4.0.1
   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