ast-merge 4.0.2 → 4.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29e3c1eb54812e59b30a8ae0dc42792486ef2e4992dbd43234452cfce0f2b1ab
-  data.tar.gz: bb1b200aa2a2d8a48c127952510984cf2ccd71e2517ced1d422fe542a7969c78
+  metadata.gz: e10cc78b855b0a28a19d476767d5cb49b880e0101b940a8846be8cb01c736882
+  data.tar.gz: 03dde93b3c46ceec1859268a538c917162f3737eb719a2138e9923fe4f3b05e6
 SHA512:
-  metadata.gz: b0823b5b64b77947faa3213463c18289a4275b5b8fd7d5a0dcf258c1ae4088dcc50a34923f459944473cfae67e7c18dd646e3236f7ff6eb0898edfdb8b5d9ab2
-  data.tar.gz: 0f8dafa6c932a75504c898793fb0f51dfa9977d288f70e6e8e9fc8aff9f0f3452742a0302dbdd23aee33db8ab4528834048322af37d7c4d44ec9fb473e682855
+  metadata.gz: 5e0715a8946d00becd61e3e8cf6418f6fcb57b89d735dacf60728e62db78e9ea95691fe55b96c30bb7e7bb14255de1919bb4962af4bef2e66460988db9242bd9
+  data.tar.gz: 04f7fde08c4419a7b5fa086d0575bf4cdbe5bcd748519eda89dcb7c161a8b6aa322521bbe5d9ca008dc1875186c0a2795b5976621449c8c864ca2b6640b6209b

data/CHANGELOG.md

@@ -30,6 +30,75 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [4.0.4] - 2026-01-20
+
+- TAG: [v4.0.4][4.0.4t]
+- COVERAGE: 96.37% -- 2552/2648 lines in 50 files
+- BRANCH COVERAGE: 87.22% -- 812/931 branches in 50 files
+- 98.81% documented
+
+### Added
+
+- **RSpec Split Loading Pattern**: New files for granular RSpec dependency tag loading
+  - `lib/ast/merge/rspec/setup.rb` - Loads only registry and helper classes (no RSpec configuration)
+  - `lib/ast/merge/rspec/dependency_tags_helpers.rb` - DependencyTags helper module
+  - `lib/ast/merge/rspec/dependency_tags_config.rb` - RSpec.configure block with exclusion filters
+  - Enables registering known gems before RSpec.configure runs (solving catch-22 problem)
+  - Required for ast-merge test suite to preserve SimpleCov coverage
+  - Required for merge gems that register other merge gems as dependencies
+- **`Ast::Merge::RSpec::MergeGemRegistry.force_check_availability!`**: Deferred availability checking for accurate test coverage
+  - Called automatically in `before(:suite)` hook AFTER SimpleCov is loaded
+  - Prevents premature gem loading that would bypass coverage instrumentation
+  - Ensures accurate coverage reporting in merge gem test suites
+
+### Changed
+
+- **RSpec Dependency Tags**: Fixed exclusion filter setup to properly skip tests when optional gems unavailable
+  - Exclusion filters now set during `RSpec.configure` (not in `before(:suite)` which runs too late)
+  - Fixed RSpec API usage: `config.filter_run_excluding tag => true` (not `[tag] = true`)
+  - `ast-merge` uses split loading pattern in `spec/spec_helper.rb` and `spec/config/tree_haver.rb`
+  - `markdown-merge` uses split pattern (registers `:commonmarker_merge`, `:markly_merge`)
+  - `markly-merge` uses split pattern (registers `:prism_merge`)
+  - `commonmarker-merge` uses simple pattern (no registrations needed)
+
+### Fixed
+
+- **Test coverage accuracy**: Fixed premature gem loading that bypassed SimpleCov instrumentation
+  - `MergeGemRegistry.registered_gems` now returns ONLY explicitly registered gems, not all KNOWN_GEMS
+  - RSpec exclusion filters are configured in `before(:suite)` hook after `force_check_availability!` runs
+  - This ensures gems are loaded AFTER SimpleCov sets up coverage instrumentation
+  - Previously, commonmarker-merge reported only 11 lines covered when it should have been far more
+- **RSpec Dependency Tags**: Tests with tags like `:markdown_merge`, `:markly_merge` now properly skip when those gems aren't available
+  - Fixed 141 test failures caused by tests running without required gems loaded
+  - Removed `require` statements from integration specs - dependency tags handle gem loading
+  - Fixed tag usage: Tests using `Markdown::Merge::PartialTemplateMerger` with `:markly` backend now correctly tagged with both `:markdown_merge` and `:markly_merge`
+- **Thread-Safety Spec**: Fixed JRuby concurrency test failure in `NodeTyping::Normalizer#canonical_type`
+  - Changed from unsynchronized `Array` to thread-safe `Queue` for collecting results from concurrent threads
+  - Eliminates `ConcurrencyError: Detected invalid array contents due to unsynchronized modifications`
+
+## [4.0.3] - 2026-01-19
+
+- TAG: [v4.0.3][4.0.3t]
+- COVERAGE: 97.30% -- 2739/2815 lines in 53 files
+- BRANCH COVERAGE: 89.84% -- 893/994 branches in 53 files
+- 98.81% documented
+
+### Added
+
+- **`Ast::Merge::RSpec::MergeGemRegistry.register_known_gems`**: Selective registration of known merge gems for RSpec dependency tags
+  - Allows test suites to explicitly register only the merge gems they need, avoiding overhead of registering all known gems
+  - Usage in `spec/config/tree_haver.rb`: `MergeGemRegistry.register_known_gems(:prism_merge, :commonmarker_merge)`
+  - Enables proper RSpec tag-based test skipping for optional merge gem dependencies
+  - Example: Tests tagged with `:prism_merge` are automatically skipped when prism-merge isn't available
+
+### Changed
+
+- Upgrade to [tree_haver v5.0.2](https://github.com/kettle-rb/tree_haver/releases/tag/v5.0.2)
+- **RSpec dependency tag load order pattern**: Merge gems now load tree_haver and dependency tags early via `spec/config/tree_haver.rb`
+  - Ensures `TreeHaver::RSpec::DependencyTags` is loaded before gems register themselves
+  - Pattern: Load tree_haver/rspec → Load ast/merge/rspec → Register known gems → Load library
+  - Applied to markdown-merge and markly-merge; other merge gems should follow this pattern
+
 ## [4.0.2] - 2026-01-12
 
 - TAG: [v4.0.2][4.0.2t]
@@ -664,7 +733,11 @@ 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.3...HEAD
+[Unreleased]: https://github.com/kettle-rb/ast-merge/compare/v4.0.4...HEAD
+[4.0.5]: https://github.com/kettle-rb/ast-merge/compare/v4.0.4...v4.0.5
+[4.0.5t]: https://github.com/kettle-rb/ast-merge/releases/tag/v4.0.5
+[4.0.4]: https://github.com/kettle-rb/ast-merge/compare/v4.0.3...v4.0.4
+[4.0.4t]: https://github.com/kettle-rb/ast-merge/releases/tag/v4.0.4
 [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

data/README.md

@@ -62,7 +62,7 @@ The `*-merge` gem family provides intelligent, AST-based merging for various fil
 
 | Gem                                      | Version                                                        | CI                                                           |          | Language<br>/ Format                                                                                  | Parser Backend(s)                                                                | Description |
 |------------------------------------------|----------------------------------------------------------------|--------------------------------------------------------------|----------|-------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------|-------------|
-| [tree_haver][tree_haver]                 | [![Version][tree_haver-gem-i]][tree_haver-gem]                 | [![Version][tree_haver-ci-i]][tree_haver-ci]                 | Multi    | MRI C, Rust, FFI, Java, Prism, Psych, Commonmarker, Markly, Citrus, Parslet                           | **Foundation**: Cross-Ruby adapter for parsing libraries (like Faraday for HTTP) |
+| [tree_haver][tree_haver]                 | [![Version][tree_haver-gem-i]][tree_haver-gem]                 | [![Version][tree_haver-ci-i]][tree_haver-ci]                 | Multi    | Supported Backends: MRI C, Rust, FFI, Java, Prism, Psych, Commonmarker, Markly, Citrus, Parslet       | **Foundation**: Cross-Ruby adapter for parsing libraries (like Faraday for HTTP) |
 | [ast-merge][ast-merge]                   | [![Version][ast-merge-gem-i]][ast-merge-gem]                   | [![Version][ast-merge-ci-i]][ast-merge-ci]                   | Text     | internal                                                                                              | **Infrastructure**: Shared base classes and merge logic for all `*-merge` gems   |
 | [bash-merge][bash-merge]                 | [![Version][bash-merge-gem-i]][bash-merge-gem]                 | [![Version][bash-merge-ci-i]][bash-merge-ci]                 | Bash     | [tree-sitter-bash][ts-bash] (via tree_haver)                                                          | Smart merge for Bash scripts                                                     |
 | [commonmarker-merge][commonmarker-merge] | [![Version][commonmarker-merge-gem-i]][commonmarker-merge-gem] | [![Version][commonmarker-merge-ci-i]][commonmarker-merge-ci] | Markdown | [Commonmarker][commonmarker] (via tree_haver)                                                         | Smart merge for Markdown (CommonMark via comrak Rust)                            |
@@ -80,18 +80,18 @@ The `*-merge` gem family provides intelligent, AST-based merging for various fil
 
 tree_haver supports multiple parsing backends, but not all backends work on all Ruby platforms:
 
-| Platform 👉️<br> TreeHaver Backend 👇️         | MRI | JRuby | TruffleRuby | Notes                                               |
-|------------------------------------------------|:---:|:-----:|:-----------:|-----------------------------------------------------|
-| **MRI** ([ruby_tree_sitter][ruby_tree_sitter]) |  ✅  |   ❌   |      ❌      | C extension, MRI only                               |
-| **Rust** ([tree_stump][tree_stump])            |  ✅  |   ❌   |      ❌      | Rust extension via magnus/rb-sys, MRI only          |
-| **FFI**                                        |  ✅  |   ✅   |      ❌      | TruffleRuby's FFI doesn't support `STRUCT_BY_VALUE` |
-| **Java** ([jtreesitter][jtreesitter])          |  ❌  |   ✅   |      ❌      | JRuby only, requires grammar JARs                   |
-| **Prism**                                      |  ✅  |   ✅   |      ✅      | Ruby parsing, stdlib in Ruby 3.4+                   |
-| **Psych**                                      |  ✅  |   ✅   |      ✅      | YAML parsing, stdlib                                |
-| **Citrus**                                     |  ✅  |   ✅   |      ✅      | Pure Ruby PEG parser, no native dependencies        |
-| **Parslet**                                    |  ✅  |   ✅   |      ✅      | Pure Ruby PEG parser, no native dependencies        |
-| **Commonmarker**                               |  ✅  |   ❌   |      ❓      | Rust extension for Markdown                         |
-| **Markly**                                     |  ✅  |   ❌   |      ❓      | C extension for Markdown                            |
+| Platform 👉️<br> TreeHaver Backend 👇️          | MRI | JRuby | TruffleRuby | Notes                                                                      |
+|-------------------------------------------------|:---:|:-----:|:-----------:|----------------------------------------------------------------------------|
+| **MRI** ([ruby_tree_sitter][ruby_tree_sitter])  |  ✅  |   ❌   |      ❌      | C extension, MRI only                                                      |
+| **Rust** ([tree_stump][tree_stump])             |  ✅  |   ❌   |      ❌      | Rust extension via magnus/rb-sys, MRI only                                 |
+| **FFI** ([ffi][ffi])                            |  ✅  |   ✅   |      ❌      | TruffleRuby's FFI doesn't support `STRUCT_BY_VALUE`                        |
+| **Java** ([jtreesitter][jtreesitter])           |  ❌  |   ✅   |      ❌      | JRuby only, requires grammar JARs                                          |
+| **Prism** ([prism][prism])                      |  ✅  |   ✅   |      ✅      | Ruby parsing, stdlib in Ruby 3.4+                                          |
+| **Psych** ([psych][psych])                      |  ✅  |   ✅   |      ✅      | YAML parsing, stdlib                                                       |
+| **Citrus** ([citrus][citrus])                   |  ✅  |   ✅   |      ✅      | Pure Ruby PEG parser, no native dependencies                               |
+| **Parslet** ([parslet][parslet])                |  ✅  |   ✅   |      ✅      | Pure Ruby PEG parser, no native dependencies                               |
+| **Commonmarker** ([commonmarker][commonmarker]) |  ✅  |   ❌   |      ❓      | Rust extension for Markdown (via [commonmarker-merge][commonmarker-merge]) |
+| **Markly** ([markly][markly])                   |  ✅  |   ❌   |      ❓      | C extension for Markdown  (via [markly-merge][markly-merge])               |
 
 **Legend**: ✅ = Works, ❌ = Does not work, ❓ = Untested
 
@@ -185,6 +185,7 @@ tree_haver supports multiple parsing backends, but not all backends work on all
 [kettle-jem-ci]: https://github.com/kettle-rb/kettle-jem/actions/workflows/current.yml
 [prism]: https://github.com/ruby/prism
 [psych]: https://github.com/ruby/psych
+[ffi]: https://github.com/ffi/ffi
 [ts-json]: https://github.com/tree-sitter/tree-sitter-json
 [ts-jsonc]: https://gitlab.com/WhyNotHugo/tree-sitter-jsonc
 [ts-bash]: https://github.com/tree-sitter/tree-sitter-bash
@@ -199,6 +200,8 @@ tree_haver supports multiple parsing backends, but not all backends work on all
 [ruby_tree_sitter]: https://github.com/Faveod/ruby-tree-sitter
 [tree_stump]: https://github.com/joker1007/tree_stump
 [jtreesitter]: https://central.sonatype.com/artifact/io.github.tree-sitter/jtreesitter
+[citrus]: https://github.com/mjackson/citrus
+[parslet]: https://github.com/kschiess/parslet
 
 ### Architecture: tree\_haver + ast-merge
 
@@ -788,7 +791,7 @@ Support us with a monthly donation and help us continue our activities. \[[Becom
 NOTE: [kettle-readme-backers][kettle-readme-backers] updates this list every day, automatically.
 
 <!-- OPENCOLLECTIVE-INDIVIDUALS:START -->
-No backers yet. Be the first\!
+No backers yet. Be the first!
 <!-- OPENCOLLECTIVE-INDIVIDUALS:END -->
 
 ### Open Collective for Organizations
@@ -798,7 +801,7 @@ Become a sponsor and get your logo on our README on GitHub with a link to your s
 NOTE: [kettle-readme-backers][kettle-readme-backers] updates this list every day, automatically.
 
 <!-- OPENCOLLECTIVE-ORGANIZATIONS:START -->
-No sponsors yet. Be the first\!
+No sponsors yet. Be the first!
 <!-- OPENCOLLECTIVE-ORGANIZATIONS:END -->
 
 [kettle-readme-backers]: https://github.com/kettle-rb/ast-merge/blob/main/exe/kettle-readme-backers
@@ -1103,7 +1106,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.815-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-2.648-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/rspec/dependency_tags.rb

@@ -1,125 +1,35 @@
 # frozen_string_literal: true
 
-require_relative "merge_gem_registry"
-
-# Ast::Merge RSpec Dependency Tags
+# Ast::Merge RSpec Dependency Tags - Combined Loader
+#
+# This file provides the standard entry point for RSpec dependency tags.
+# It loads both the helper module and the RSpec configuration.
+#
+# **When to use the split loading pattern:**
+# - ast-merge: MUST use split pattern (to preserve SimpleCov coverage of ast-merge itself)
+# - Merge gems that register other merge gems: MUST use split pattern (to avoid catch-22)
+# - Other gems: Can use simple `require "ast/merge/rspec"` (this file)
 #
-# This module provides dependency detection helpers for conditional test execution
-# in the ast-merge gem family. It uses MergeGemRegistry for dynamic merge gem detection.
+# @example Simple pattern (for gems that DON'T register other gems)
+#   # In spec/config/tree_haver.rb:
+#   require "ast-merge"
+#   require "ast/merge/rspec"  # Loads everything
 #
-# @example Loading in spec_helper.rb
-#   require "ast/merge/rspec/dependency_tags"
+# @example Split pattern (for ast-merge or gems that register other merge gems)
+#   # In spec/config/tree_haver.rb:
+#   require "ast-merge"
+#   require "ast/merge/rspec/setup"  # Load registry/helpers only
+#   Ast::Merge::RSpec::MergeGemRegistry.register_known_gems(:markly_merge)
+#   require "ast/merge/rspec/dependency_tags_config"  # Load RSpec config
+#   require "ast/merge/rspec/shared_examples"
 #
 # @example Usage in specs
 #   it "requires markly-merge", :markly_merge do
 #     # This test only runs when markly-merge is available
 #   end
-#
-#   it "requires prism-merge", :prism_merge do
-#     # This test only runs when prism-merge is available
-#   end
-#
-# == Dynamic Tag Registration
-#
-# Merge gems register themselves with MergeGemRegistry, which automatically:
-# - Defines `*_available?` methods on DependencyTags
-# - Configures RSpec exclusion filters for the tag
-# - Supports negated tags (`:not_*`)
-#
-# @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
-#   )
-#
-# == Built-in Composite Tags
-#
-# [:any_markdown_merge]
-#   At least one markdown merge gem is available (category: :markdown).
-
-module Ast
-  module Merge
-    module RSpec
-      # Dependency detection helpers for conditional test execution
-      module DependencyTags
-        class << self
-          # ============================================================
-          # Composite Availability Checks
-          # ============================================================
-
-          # Check if at least one markdown merge gem is available
-          #
-          # @return [Boolean] true if any markdown merge gem works
-          def any_markdown_merge_available?
-            MergeGemRegistry.gems_by_category(:markdown).any? do |tag|
-              MergeGemRegistry.available?(tag)
-            end
-          end
-
-          # ============================================================
-          # Summary and Reset
-          # ============================================================
-
-          # Get a summary of available dependencies (for debugging)
-          #
-          # @return [Hash{Symbol => Boolean}] map of dependency name to availability
-          def summary
-            result = MergeGemRegistry.summary
-            result[:any_markdown_merge] = any_markdown_merge_available?
-            result
-          end
-
-          # Reset all memoized availability checks
-          #
-          # @return [void]
-          def reset!
-            MergeGemRegistry.reset_availability!
-          end
-        end
-      end
-    end
-  end
-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
-    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"
-        puts "  #{dep}: #{status}"
-      end
-      puts "=====================================\n"
-    end
-  end
-
-  # ============================================================
-  # 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.
-
-  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
 
-  # ============================================================
-  # Composite Tags
-  # ============================================================
+# Load the helper module (DependencyTags methods)
+require_relative "dependency_tags_helpers"
 
-  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
+# Load the RSpec configuration (exclusion filters)
+require_relative "dependency_tags_config"

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

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "dependency_tags_helpers"
+
+# Ast::Merge RSpec Dependency Tags - RSpec Configuration
+#
+# This file configures RSpec with dependency-based exclusion filters.
+# It should be loaded AFTER gems have been registered with MergeGemRegistry.
+#
+# @example Loading in spec_helper.rb (for merge gem test suites)
+#   require "ast/merge/rspec"  # Loads this file automatically
+#
+# @example For ast-merge test suite (split loading)
+#   # In spec_helper.rb BEFORE requiring ast-merge:
+#   require "ast/merge/rspec/setup"
+#
+#   # Register known gems:
+#   Ast::Merge::RSpec::MergeGemRegistry.register_known_gems(:markly_merge)
+#
+#   # Then AFTER requiring ast-merge, load config:
+#   require "ast/merge/rspec/dependency_tags_config"
+
+# Configure RSpec with dependency-based exclusion filters
+RSpec.configure do |config|
+  deps = Ast::Merge::RSpec::DependencyTags
+  registry = Ast::Merge::RSpec::MergeGemRegistry
+
+  # CRITICAL: Exclusion filters MUST be set during RSpec.configure, not in before(:suite)
+  # because RSpec filters tests before before(:suite) runs!
+
+  # Force availability checking for all registered gems
+  # This loads the gems NOW during configuration, which is after SimpleCov has instrumented
+  # the code (since this file is required AFTER ast-merge loads in spec_helper.rb)
+  registry.force_check_availability!
+
+  # Now configure exclusion filters based on actual availability
+  registry.registered_gems.each do |tag|
+    if registry.available?(tag)
+      # Gem is available - exclude tests tagged with :not_tag
+      negated_tag = :"not_#{tag}"
+      config.filter_run_excluding(negated_tag => true)
+    else
+      # Gem is NOT available - exclude tests tagged with :tag
+      config.filter_run_excluding(tag => true)
+    end
+  end
+
+  # Configure composite tags (these also trigger gem loading, so must be here)
+  if deps.any_markdown_merge_available?
+    config.filter_run_excluding(not_any_markdown_merge: true)
+  else
+    config.filter_run_excluding(any_markdown_merge: true)
+  end
+
+  # Print dependency summary if AST_MERGE_DEBUG is set
+  config.before(:suite) do
+    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"
+        puts "  #{dep}: #{status}"
+      end
+      puts "=====================================\n"
+    end
+  end
+
+  # ============================================================
+  # Dynamic Merge Gem Tags - Initial Setup
+  # ============================================================
+  # Note: We don't set exclusions here because that would require checking
+  # availability (loading gems) before SimpleCov. The actual exclusions are
+  # set in the before(:suite) hook above after force_check_availability! runs.
+  # This includes composite tags like :any_markdown_merge.
+end

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require_relative "merge_gem_registry"
+
+# Ast::Merge RSpec Dependency Tags - Helper Module Only
+#
+# This module provides dependency detection helpers for conditional test execution
+# in the ast-merge gem family. It uses MergeGemRegistry for dynamic merge gem detection.
+#
+# NOTE: This file contains ONLY the helper module, not the RSpec configuration.
+# The RSpec configuration is in dependency_tags_config.rb and is loaded by
+# ast/merge/rspec (the full entry point).
+
+module Ast
+  module Merge
+    module RSpec
+      # Dependency detection helpers for conditional test execution
+      module DependencyTags
+        class << self
+          # ============================================================
+          # Composite Availability Checks
+          # ============================================================
+
+          # Check if at least one markdown merge gem is available
+          #
+          # @return [Boolean] true if any markdown merge gem works
+          def any_markdown_merge_available?
+            MergeGemRegistry.gems_by_category(:markdown).any? do |tag|
+              MergeGemRegistry.available?(tag)
+            end
+          end
+
+          # ============================================================
+          # Summary and Reset
+          # ============================================================
+
+          # Get a summary of available dependencies (for debugging)
+          #
+          # @return [Hash{Symbol => Boolean}] map of dependency name to availability
+          def summary
+            result = MergeGemRegistry.summary
+            result[:any_markdown_merge] = any_markdown_merge_available?
+            result
+          end
+
+          # Reset all memoized availability checks
+          #
+          # @return [void]
+          def reset!
+            MergeGemRegistry.reset_availability!
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -253,12 +253,59 @@ module Ast
           end
         end
 
-        # Get all registered gem tag names (including pre-configured known gems)
+        # Register one or more known gems for RSpec dependency tag support
+        #
+        # This allows test suites to explicitly register only the merge gems they need
+        # for their tests, avoiding the overhead of registering all known gems.
+        #
+        # @param gem_names [Array<Symbol>] list of gem names from KNOWN_GEMS to register
+        # @return [void]
+        #
+        # @example In spec/config/tree_haver.rb
+        #   # Only register the markdown merge gems that markly-merge tests depend on
+        #   Ast::Merge::RSpec::MergeGemRegistry.register_known_gems(:prism_merge)
+        #
+        # @example Register multiple gems
+        #   Ast::Merge::RSpec::MergeGemRegistry.register_known_gems(
+        #     :commonmarker_merge,
+        #     :markly_merge
+        #   )
+        def register_known_gems(*gem_names)
+          gem_names.each do |tag_name|
+            tag_sym = tag_name.to_sym
+
+            # Skip if not in KNOWN_GEMS
+            unless KNOWN_GEMS.key?(tag_sym)
+              warn("Unknown gem: #{tag_name}. Available: #{KNOWN_GEMS.keys.join(", ")}")
+              next
+            end
+
+            # Skip if already registered
+            next if registered?(tag_sym)
+
+            metadata = KNOWN_GEMS[tag_sym]
+            register(
+              tag_sym,
+              require_path: metadata[:require_path],
+              merger_class: metadata[:merger_class],
+              test_source: metadata[:test_source],
+              category: metadata[:category],
+              skip_instantiation: metadata[:skip_instantiation],
+            )
+          end
+        end
+
+        # Get all explicitly registered gem tag names
+        #
+        # This returns ONLY gems that were explicitly registered via register() or
+        # register_known_gems(), NOT all gems in KNOWN_GEMS. This prevents premature
+        # loading of gems during RSpec tag setup, which would happen before SimpleCov
+        # and ruin coverage reporting.
         #
         # @return [Array<Symbol>] list of registered tag names
         def registered_gems
           @mutex.synchronize do
-            (KNOWN_GEMS.keys + @registry.keys).uniq
+            @registry.keys
           end
         end
 
@@ -274,6 +321,31 @@ module Ast
           end
         end
 
+        # Force availability checking for all registered gems
+        #
+        # This method should be called AFTER SimpleCov is loaded (typically at the end
+        # of spec_helper.rb) to trigger gem loading and availability checking. Calling
+        # this ensures RSpec exclusion filters are properly configured based on which
+        # gems are actually available.
+        #
+        # This is necessary because register_known_gems() only registers gems without
+        # checking availability. The actual availability check (which requires loading
+        # the gem) must happen AFTER coverage instrumentation is set up.
+        #
+        # @return [void]
+        #
+        # @example At the end of spec_helper.rb (after SimpleCov loads)
+        #   # Force availability checking now that coverage is instrumented
+        #   Ast::Merge::RSpec::MergeGemRegistry.force_check_availability!
+        def force_check_availability!
+          registered_gems.each do |tag|
+            # This will trigger gem_works? which loads the gem
+            # Results are cached, so subsequent calls are fast
+            available?(tag)
+          end
+          nil
+        end
+
         # Get registration info for a gem
         #
         # @param tag_name [Symbol] the tag name

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Ast::Merge RSpec Setup (Registry Only)
+#
+# This file loads ONLY the registry and helper classes without configuring RSpec.
+# It's used in the ast-merge test suite to allow registering known gems before
+# SimpleCov loads the library code.
+#
+# DO NOT load this in merge gem test suites - they should use require "ast/merge/rspec"
+# which includes the full RSpec configuration.
+#
+# @example Loading in ast-merge's spec_helper.rb (BEFORE requiring ast-merge)
+#   require "ast/merge/rspec/setup"
+#
+#   # Now you can register known gems:
+#   Ast::Merge::RSpec::MergeGemRegistry.register_known_gems(:markly_merge, :prism_merge)
+#
+# @example For merge gem test suites (normal pattern)
+#   # Don't use this file! Use the full loader instead:
+#   require "ast/merge/rspec"  # Loads setup + RSpec configuration
+
+# Load only the registry - no RSpec configuration
+require_relative "merge_gem_registry"
+require_relative "dependency_tags_helpers"

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.2"
+      VERSION = "4.0.4"
     end
     VERSION = Version::VERSION # traditional location
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ast-merge
 version: !ruby/object:Gem::Version
-  version: 4.0.2
+  version: 4.0.4
 platform: ruby
 authors:
 - Peter H. Boling
@@ -66,7 +66,7 @@ dependencies:
         version: '5.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 5.0.1
+        version: 5.0.2
   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.1
+        version: 5.0.2
 - !ruby/object:Gem::Dependency
   name: kettle-dev
   requirement: !ruby/object:Gem::Requirement
@@ -355,7 +355,10 @@ files:
 - lib/ast/merge/recipe/script_loader.rb
 - lib/ast/merge/rspec.rb
 - lib/ast/merge/rspec/dependency_tags.rb
+- lib/ast/merge/rspec/dependency_tags_config.rb
+- lib/ast/merge/rspec/dependency_tags_helpers.rb
 - lib/ast/merge/rspec/merge_gem_registry.rb
+- lib/ast/merge/rspec/setup.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
@@ -382,10 +385,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://ast-merge.galtzo.com/
-  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
+  source_code_uri: https://github.com/kettle-rb/ast-merge/tree/v4.0.4
+  changelog_uri: https://github.com/kettle-rb/ast-merge/blob/v4.0.4/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-rb/ast-merge/issues
-  documentation_uri: https://www.rubydoc.info/gems/ast-merge/4.0.2
+  documentation_uri: https://www.rubydoc.info/gems/ast-merge/4.0.4
   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
@@ -414,7 +417,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.3
+rubygems_version: 4.0.4
 specification_version: 4
 summary: "☯️ Shared infrastructure for the *-merge gem family"
 test_files: []