ast-merge 4.0.0 → 4.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 871eebc1f2c69aa75278023c250fd90905cf2fb4e23677fbcfd49633bad5ebb1
-  data.tar.gz: 3804ee9f9f61effc21c49862a96b0092481067813c79b1b4fdb09a748b935570
+  metadata.gz: 29e3c1eb54812e59b30a8ae0dc42792486ef2e4992dbd43234452cfce0f2b1ab
+  data.tar.gz: bb1b200aa2a2d8a48c127952510984cf2ccd71e2517ced1d422fe542a7969c78
 SHA512:
-  metadata.gz: 340c3feee108349b603db2150baa68467b45c7414be0d1fdcfaac10038d3cfca2dc893dc81a489adae66bbfc8d9474f7128e7f0817abc9703ba6694719a48b91
-  data.tar.gz: 5f135b944efe203fe0f83cf2d141e18de4e64be096a3293c0db09b3f5672790b6cdbad6956ef511c657b43c0e0b162050ec57d46d7da659895554c16e2eac6c4
+  metadata.gz: b0823b5b64b77947faa3213463c18289a4275b5b8fd7d5a0dcf258c1ae4088dcc50a34923f459944473cfae67e7c18dd646e3236f7ff6eb0898edfdb8b5d9ab2
+  data.tar.gz: 0f8dafa6c932a75504c898793fb0f51dfa9977d288f70e6e8e9fc8aff9f0f3452742a0302dbdd23aee33db8ab4528834048322af37d7c4d44ec9fb473e682855

data/CHANGELOG.md

@@ -30,6 +30,73 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [4.0.2] - 2026-01-12
+
+- TAG: [v4.0.2][4.0.2t]
+- COVERAGE: 97.30% -- 2739/2815 lines in 53 files
+- BRANCH COVERAGE: 89.84% -- 893/994 branches in 53 files
+- 98.81% documented
+
+### Added
+
+- **`Recipe::Runner` target file override**: Accept `target_files` parameter to override recipe targets
+  - `Runner.new(recipe, target_files: ["file1.md", "file2.md"])` - Process only specified files
+  - Paths are expanded relative to `base_dir`
+  - When not specified, falls back to recipe's configured targets
+- **`exe/ast-merge-recipe` file arguments**: Accept target files on command line
+  - `ast-merge-recipe recipe.yml file1.md file2.md` - Override recipe targets
+  - Updated help text and banner to document new usage
+- **`bin/update_gem_family_section` file arguments**: Accept target files on command line
+  - `bin/update_gem_family_section vendor/my-gem/README.md` - Process specific file(s)
+  - If no files specified, defaults to `README.md` + `vendor/*/README.md`
+  - Added `--skip-fix` option to skip the formatting fix step
+
+### Changed
+
+- **`bin/update_gem_family_section`**: Refactored to use `OptionParser` for clean option handling
+  - Consistent with `bin/fix_readme_formatting` style
+  - Properly separates options from file arguments
+
+## [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 +664,13 @@ 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.3...HEAD
+[4.0.3]: https://github.com/kettle-rb/ast-merge/compare/v4.0.2...v4.0.3
+[4.0.3t]: https://github.com/kettle-rb/ast-merge/releases/tag/v4.0.3
+[4.0.2]: https://github.com/kettle-rb/ast-merge/compare/v4.0.1...v4.0.2
+[4.0.2t]: https://github.com/kettle-rb/ast-merge/releases/tag/v4.0.2
+[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/README.md

@@ -208,24 +208,24 @@ The `*-merge` gem family is built on a two-layer architecture:
 
 [tree\_haver][tree_haver] provides cross-Ruby parsing capabilities:
 
-  - **Universal Backend Support**: Automatically selects the best parsing backend for your Ruby implementation (MRI, JRuby, TruffleRuby)
-  - **10 Backend Options**: MRI C extensions, Rust bindings, FFI, Java (JRuby), language-specific parsers (Prism, Psych, Commonmarker, Markly), and pure Ruby fallback (Citrus)
-  - **Unified API**: Write parsing code once, run on any Ruby implementation
-  - **Grammar Discovery**: Built-in `GrammarFinder` for platform-aware grammar library discovery
-  - **Thread-Safe**: Language registry with thread-safe caching
+- **Universal Backend Support**: Automatically selects the best parsing backend for your Ruby implementation (MRI, JRuby, TruffleRuby)
+- **10 Backend Options**: MRI C extensions, Rust bindings, FFI, Java (JRuby), language-specific parsers (Prism, Psych, Commonmarker, Markly), and pure Ruby fallback (Citrus)
+- **Unified API**: Write parsing code once, run on any Ruby implementation
+- **Grammar Discovery**: Built-in `GrammarFinder` for platform-aware grammar library discovery
+- **Thread-Safe**: Language registry with thread-safe caching
 
 #### Layer 2: ast-merge (Merge Infrastructure)
 
 Ast::Merge builds on tree\_haver to provide:
 
-  - **Base Classes**: `FreezeNode`, `MergeResult` base classes with unified constructors
-  - **Shared Modules**: `FileAnalysisBase`, `FileAnalyzable`, `MergerConfig`, `DebugLogger`
-  - **Freeze Block Support**: Configurable marker patterns for multiple comment syntaxes (preserve sections during merge)
-  - **Node Typing System**: `NodeTyping` for canonical node type identification across different parsers
-  - **Conflict Resolution**: `ConflictResolverBase` with pluggable strategies
-  - **Error Classes**: `ParseError`, `TemplateParseError`, `DestinationParseError`
-  - **Region Detection**: `RegionDetectorBase`, `FencedCodeBlockDetector` for text-based analysis
-  - **RSpec Shared Examples**: Test helpers for implementing new merge gems
+- **Base Classes**: `FreezeNode`, `MergeResult` base classes with unified constructors
+- **Shared Modules**: `FileAnalysisBase`, `FileAnalyzable`, `MergerConfig`, `DebugLogger`
+- **Freeze Block Support**: Configurable marker patterns for multiple comment syntaxes (preserve sections during merge)
+- **Node Typing System**: `NodeTyping` for canonical node type identification across different parsers
+- **Conflict Resolution**: `ConflictResolverBase` with pluggable strategies
+- **Error Classes**: `ParseError`, `TemplateParseError`, `DestinationParseError`
+- **Region Detection**: `RegionDetectorBase`, `FencedCodeBlockDetector` for text-based analysis
+- **RSpec Shared Examples**: Test helpers for implementing new merge gems
 
 ### Creating a New Merge Gem
 
@@ -372,10 +372,10 @@ merger = MyFormat::SmartMerger.new(
 
 This is particularly useful for:
 
-  - Paragraphs with minor edits (typos, rewording)
-  - Headings with slight changes
-  - Comments with updated text
-  - Any text-based node that may have been slightly modified
+- Paragraphs with minor edits (typos, rewording)
+- Headings with slight changes
+- Comments with updated text
+- Any text-based node that may have been slightly modified
 
 ### Namespace Reference
 
@@ -391,11 +391,11 @@ The `Ast::Merge` module is organized into several namespaces, each with detailed
 
 **Key Classes by Namespace:**
 
-  - **Detector**: `Region`, `Base`, `Mergeable`, `FencedCodeBlock`, `YamlFrontmatter`, `TomlFrontmatter`
-  - **Recipe**: `Config`, `Runner`, `ScriptLoader`
-  - **Comment**: `Line`, `Block`, `Empty`, `Parser`, `Style`
-  - **Text**: `SmartMerger`, `FileAnalysis`, `LineNode`, `WordNode`, `Section`
-  - **RSpec**: Shared examples and dependency tags for testing `*-merge` implementations
+- **Detector**: `Region`, `Base`, `Mergeable`, `FencedCodeBlock`, `YamlFrontmatter`, `TomlFrontmatter`
+- **Recipe**: `Config`, `Runner`, `ScriptLoader`
+- **Comment**: `Line`, `Block`, `Empty`, `Parser`, `Style`
+- **Text**: `SmartMerger`, `FileAnalysis`, `LineNode`, `WordNode`, `Section`
+- **RSpec**: Shared examples and dependency tags for testing `*-merge` implementations
 
 ## 💡 Info you can shake a stick at
 
@@ -447,18 +447,13 @@ The maintainers of this and thousands of other packages are working with Tidelif
 
 [![Get help from me on Tidelift][🏙️entsup-tidelift-img]][🏙️entsup-tidelift]
 
-  - 💡Subscribe for support guarantees covering *all* your FLOSS dependencies
-
-  - 💡Tidelift is part of [Sonar][🏙️entsup-tidelift-sonar]
-
-  - 💡Tidelift pays maintainers to maintain the software you depend on\!<br/>📊`@`Pointy Haired Boss: An [enterprise support][🏙️entsup-tidelift] subscription is "[never gonna let you down][🧮kloc]", and *supports* open source maintainers
-    Alternatively:
-
-  - [![Live Chat on Discord][✉️discord-invite-img-ftb]][🖼️galtzo-discord]
-
-  - [![Get help from me on Upwork][👨🏼‍🏫expsup-upwork-img]][👨🏼‍🏫expsup-upwork]
-
-  - [![Get help from me on Codementor][👨🏼‍🏫expsup-codementor-img]][👨🏼‍🏫expsup-codementor]
+- 💡Subscribe for support guarantees covering *all* your FLOSS dependencies
+- 💡Tidelift is part of [Sonar][🏙️entsup-tidelift-sonar]
+- 💡Tidelift pays maintainers to maintain the software you depend on\!<br/>📊`@`Pointy Haired Boss: An [enterprise support][🏙️entsup-tidelift] subscription is "[never gonna let you down][🧮kloc]", and *supports* open source maintainers
+  Alternatively:
+- [![Live Chat on Discord][✉️discord-invite-img-ftb]][🖼️galtzo-discord]
+- [![Get help from me on Upwork][👨🏼‍🏫expsup-upwork-img]][👨🏼‍🏫expsup-upwork]
+- [![Get help from me on Codementor][👨🏼‍🏫expsup-codementor-img]][👨🏼‍🏫expsup-codementor]
 
 </details>
 
@@ -537,17 +532,17 @@ merger = SomeFormat::Merge::SmartMerger.new(
 
 Control which source wins when both files have the same structural element:
 
-  - **`:template`** - Template values replace destination values
-  - **`:destination`** (default) - Destination values are preserved
-  - **Hash** - Per-node-type preference (see Advanced Configuration)
+- **`:template`** - Template values replace destination values
+- **`:destination`** (default) - Destination values are preserved
+- **Hash** - Per-node-type preference (see Advanced Configuration)
 
 ### Template-Only Nodes
 
 Control whether to add nodes that only exist in the template:
 
-  - **`true`** - Add all template-only nodes
-  - **`false`** (default) - Skip template-only nodes
-  - **Callable** - Filter which template-only nodes to add
+- **`true`** - Add all template-only nodes
+- **`false`** (default) - Skip template-only nodes
+- **Callable** - Filter which template-only nodes to add
 
 #### Callable Filter
 
@@ -577,10 +572,10 @@ merger = Markly::Merge::SmartMerger.new(
 
 The `entry` hash contains:
 
-  - `:template_node` - The node being considered for addition
-  - `:signature` - The node's signature (Array or other value)
-  - `:template_index` - Index in the template statements
-  - `:dest_index` - Always `nil` for template-only nodes
+- `:template_node` - The node being considered for addition
+- `:signature` - The node's signature (Array or other value)
+- `:template_index` - Index in the template statements
+- `:dest_index` - Always `nil` for template-only nodes
 
 ## 🔧 Basic Usage
 
@@ -606,11 +601,11 @@ end
 
 ### Available Shared Examples
 
-  - `"Ast::Merge::FreezeNode"` - Tests for FreezeNode implementations
-  - `"Ast::Merge::MergeResult"` - Tests for MergeResult implementations
-  - `"Ast::Merge::DebugLogger"` - Tests for DebugLogger implementations
-  - `"Ast::Merge::FileAnalysisBase"` - Tests for FileAnalysis implementations
-  - `"Ast::Merge::MergerConfig"` - Tests for SmartMerger implementations
+- `"Ast::Merge::FreezeNode"` - Tests for FreezeNode implementations
+- `"Ast::Merge::MergeResult"` - Tests for MergeResult implementations
+- `"Ast::Merge::DebugLogger"` - Tests for DebugLogger implementations
+- `"Ast::Merge::FileAnalysisBase"` - Tests for FileAnalysis implementations
+- `"Ast::Merge::MergerConfig"` - Tests for SmartMerger implementations
 
 ## 🎛️ Advanced Configuration
 
@@ -622,9 +617,9 @@ This is useful for hand-edited customizations you never want overwritten.
 
 A freeze block consists of:
 
-  - A **start marker** comment (e.g., `# mytoken:freeze`)
-  - The protected content
-  - An **end marker** comment (e.g., `# mytoken:unfreeze`)
+- A **start marker** comment (e.g., `# mytoken:freeze`)
+- The protected content
+- An **end marker** comment (e.g., `# mytoken:unfreeze`)
 
 ```ruby
 # In a Ruby file with prism-merge:
@@ -669,13 +664,13 @@ preferences for different types of nodes (e.g., prefer template for linter confi
 
 1.  **Define a `node_typing`**: A Hash mapping node type symbols to callables that receive a node and return either:
 
-      - The original node (no special handling)
-      - A wrapped node with a `merge_type` attribute (via `Ast::Merge::NodeTyping::Wrapper`)
+    - The original node (no special handling)
+    - A wrapped node with a `merge_type` attribute (via `Ast::Merge::NodeTyping::Wrapper`)
 
 2.  **Use a Hash-based preference**: Instead of a simple `:destination` or `:template` Symbol, pass a Hash with:
 
-      - `:default` key for the fallback preference
-      - Custom keys matching the `merge_type` values from your `node_typing`
+    - `:default` key for the fallback preference
+    - Custom keys matching the `merge_type` values from your `node_typing`
 
 ```ruby
 # Example: Prefer template for lint gem configs, destination for everything else
@@ -903,7 +898,7 @@ is a *breaking change* to an API, and for that reason the bike shedding is endle
 To get a better understanding of how SemVer is intended to work over a project's lifetime,
 read this article from the creator of SemVer:
 
-  - ["Major Version Numbers are Not Sacred"][📌major-versions-not-sacred]
+- ["Major Version Numbers are Not Sacred"][📌major-versions-not-sacred]
 
 </details>
 
@@ -1108,7 +1103,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.647-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-2.815-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/exe/ast-merge-recipe

@@ -171,9 +171,10 @@ class AstMergeRecipeCLI
 
   def parse_options(argv)
     @option_parser = OptionParser.new do |opts|
-      opts.banner = "Usage: #{File.basename($0)} RECIPE_FILE [options]"
+      opts.banner = "Usage: #{File.basename($0)} RECIPE_FILE [FILES...] [options]"
       opts.separator("")
       opts.separator("Run a YAML-based merge recipe against target files.")
+      opts.separator("If FILES are specified, they override the recipe's targets.")
       opts.separator("")
       opts.separator("Options:")
 
@@ -225,9 +226,15 @@ class AstMergeRecipeCLI
       opts.on("-h", "--help", "Show this help message") do
         puts opts
         puts
+        puts "Arguments:"
+        puts "  RECIPE_FILE    Path to the YAML recipe file (required)"
+        puts "  [FILES...]     Target files to process (optional, overrides recipe targets)"
+        puts
         puts "Examples:"
         puts "  #{File.basename($0)} .merge-recipes/gem_family_section.yml --dry-run"
         puts "  #{File.basename($0)} recipe.yml --verbose --parser=commonmarker"
+        puts "  #{File.basename($0)} recipe.yml vendor/my-gem/README.md"
+        puts "  #{File.basename($0)} recipe.yml README.md vendor/*/README.md"
         puts
         puts "Recipe YAML format:"
         puts "  See lib/ast/merge/recipe/README.md for full documentation"
@@ -241,10 +248,8 @@ class AstMergeRecipeCLI
     # First non-option argument is the recipe file
     @options[:recipe_file] = remaining.shift
 
-    # Warn about extra arguments
-    if remaining.any?
-      $stderr.puts Colors.yellow("WARNING: Ignoring extra arguments: #{remaining.join(", ")}")
-    end
+    # Remaining arguments are target files (override recipe targets)
+    @options[:target_files] = remaining if remaining.any?
   end
 
   def validate_options!
@@ -271,14 +276,19 @@ class AstMergeRecipeCLI
     recipe = Ast::Merge::Recipe::Config.load(@options[:recipe_file])
     print_recipe_info(recipe)
 
-    # Create runner
-    runner = Ast::Merge::Recipe::Runner.new(
-      recipe,
+    # Build runner options
+    runner_opts = {
       dry_run: @options[:dry_run],
       base_dir: @options[:base_dir],
       parser: @options[:parser],
       verbose: @options[:verbose],
-    )
+    }
+
+    # If target files specified on command line, override recipe targets
+    runner_opts[:target_files] = @options[:target_files] if @options[:target_files]
+
+    # Create runner
+    runner = Ast::Merge::Recipe::Runner.new(recipe, **runner_opts)
 
     # Run and display results
     puts Colors.cyan("Processing files...")

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/recipe/runner.rb

@@ -40,6 +40,9 @@ module Ast
         # @return [Symbol] Parser to use (:markly, :commonmarker, :prism, :psych, etc.)
         attr_reader :parser
 
+        # @return [Array<String>, nil] Target files override (from command line)
+        attr_reader :target_files
+
         # @return [Array<Result>] Results from the last run
         attr_reader :results
 
@@ -50,12 +53,14 @@ module Ast
         # @param base_dir [String, nil] Base directory for path resolution
         # @param parser [Symbol] Which parser to use
         # @param verbose [Boolean] Enable verbose output
-        def initialize(recipe, dry_run: false, base_dir: nil, parser: :markly, verbose: false)
+        # @param target_files [Array<String>, nil] Override recipe targets with these files
+        def initialize(recipe, dry_run: false, base_dir: nil, parser: :markly, verbose: false, target_files: nil, **options)
           @recipe = recipe
           @dry_run = dry_run
           @base_dir = base_dir || Dir.pwd
           @parser = parser
           @verbose = verbose
+          @target_files = target_files
           @results = []
         end
 
@@ -66,10 +71,17 @@ module Ast
           @results = []
 
           template_content = load_template
-          # Let the recipe expand targets from its own location
-          target_files = recipe.expand_targets
 
-          target_files.each do |target_path|
+          # Use command-line targets if provided, otherwise expand from recipe
+          files_to_process = if @target_files && !@target_files.empty?
+            # Expand paths relative to base_dir
+            @target_files.map { |f| File.expand_path(f, @base_dir) }
+          else
+            # Let the recipe expand targets from its own location
+            recipe.expand_targets
+          end
+
+          files_to_process.each do |target_path|
             result = process_file(target_path, template_content)
             @results << result
             yield result if block_given?

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.2"
     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.2
 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.2
+  changelog_uri: https://github.com/kettle-rb/ast-merge/blob/v4.0.2/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.2
   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