ast-merge 1.1.0 → 2.0.0

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

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+# 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.
+#
+# @example Loading in spec_helper.rb
+#   require "ast/merge/rspec/dependency_tags"
+#
+# @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
+#
+# == 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.
+#
+# [:jsonc_merge]
+#   jsonc-merge gem is available and functional.
+#
+# [:toml_merge]
+#   toml-merge gem is available and functional.
+#
+# [:bash_merge]
+#   bash-merge gem is available and functional.
+#
+# [:psych_merge]
+#   psych-merge gem is available and functional.
+#
+# [: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_any_markdown_merge
+
+module Ast
+  module Merge
+    module RSpec
+      # Dependency detection helpers for conditional test execution
+      module DependencyTags
+        class << self
+          # ============================================================
+          # Merge Gem Availability
+          # ============================================================
+
+          # 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
+          # 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?
+          end
+
+          # ============================================================
+          # Summary and Reset
+          # ============================================================
+
+          # Get a summary of available dependencies (for debugging)
+          #
+          # @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?,
+              any_markdown_merge: any_markdown_merge_available?,
+            }
+          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
+          end
+        end
+      end
+    end
+  end
+end
+
+# Configure RSpec with dependency-based exclusion filters
+RSpec.configure do |config|
+  deps = Ast::Merge::RSpec::DependencyTags
+
+  config.before(:suite) do
+    # Print dependency summary if AST_MERGE_DEBUG is set
+    if ENV["AST_MERGE_DEBUG"]
+      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
+
+  # ============================================================
+  # Merge Gem Tags
+  # ============================================================
+
+  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(any_markdown_merge: true) unless deps.any_markdown_merge_available?
+
+  # ============================================================
+  # Negated Tags (run when dependency is NOT available)
+  # ============================================================
+
+  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_any_markdown_merge: true) if deps.any_markdown_merge_available?
+end

data/lib/ast/merge/rspec/shared_examples/reproducible_merge.rb

@@ -77,8 +77,9 @@ RSpec.shared_examples("a reproducible merge") do |scenario, options = {}|
     result = merger.merge
 
     # Normalize trailing newlines for comparison
-    expected = fixture[:expected]
-    actual = result.to_s
+    # Different backends may or may not add a trailing newline
+    expected = fixture[:expected].chomp
+    actual = result.to_s.chomp
 
     expect(actual).to(
       eq(expected),

data/lib/ast/merge/rspec.rb

@@ -1,4 +1,35 @@
-# Ensure the main ast-merge library is loaded first
-require "ast/merge"
+# frozen_string_literal: true
 
+# Ast::Merge RSpec Support
+#
+# This file provides a single entry point for all RSpec helpers in the ast-merge family.
+# It loads:
+# - TreeHaver dependency tags (parser backend availability)
+# - Ast::Merge dependency tags (merge gem availability)
+# - Ast::Merge shared examples (for testing *-merge implementations)
+#
+# @example Loading in spec_helper.rb
+#   require "ast/merge/rspec"
+#
+# @example Usage in specs
+#   # Dependency tags for conditional execution
+#   it "requires markly-merge", :markly_merge do
+#     # Skipped if markly-merge not available
+#   end
+#
+#   # Shared examples for implementation validation
+#   RSpec.describe MyMerge::ConflictResolver do
+#     it_behaves_like "Ast::Merge::ConflictResolverBase"
+#   end
+#
+# @see https://github.com/kettle-rb/tree_haver/blob/main/lib/tree_haver/rspec/README.md
+#   TreeHaver RSpec documentation for parser backend tags
+
+# Load TreeHaver dependency tags first (provides parser backend tags like :markly, :prism_backend, etc.)
+require "tree_haver/rspec/dependency_tags"
+
+# Load Ast::Merge dependency tags (provides merge gem tags like :markly_merge, :prism_merge, etc.)
+require_relative "rspec/dependency_tags"
+
+# Load Ast::Merge shared examples (for testing *-merge implementations)
 require_relative "rspec/shared_examples"

data/lib/ast/merge/smart_merger_base.rb

@@ -12,13 +12,14 @@ module Ast
     #
     # All SmartMerger implementations support these common options:
     #
-    # - `preference` - `:destination` (default) or `:template`
+    # - `preference` - `:destination` (default) or `:template`, or Hash for per-type
     # - `add_template_only_nodes` - `false` (default) or `true`
     # - `signature_generator` - Custom signature proc or `nil`
     # - `freeze_token` - Token for freeze block markers
     # - `match_refiner` - Fuzzy match refiner or `nil`
     # - `regions` - Region configurations for nested merging
     # - `region_placeholder` - Custom placeholder for regions
+    # - `node_typing` - Hash mapping node types to callables for per-type preferences
     #
     # ## Implementing a SmartMerger
     #
@@ -35,6 +36,53 @@ module Ast
     # - `build_analysis_options` - Additional analysis options
     # - `build_resolver_options` - Additional resolver options
     #
+    # ## FileAnalysis Error Handling Pattern
+    #
+    # All FileAnalysis classes must follow this consistent error handling pattern:
+    #
+    # 1. **Catch backend errors internally** - Handle `TreeHaver::NotAvailable` and
+    #    similar backend errors inside the FileAnalysis class, storing them in `@errors`
+    #    and setting `@ast = nil`. Do NOT re-raise these errors.
+    #
+    # 2. **Collect parse errors without raising** - When the parser detects syntax errors
+    #    (e.g., `has_error?` returns true), collect them in `@errors` but do NOT raise.
+    #
+    # 3. **Implement `valid?`** - Return `false` when there are errors or no AST:
+    #    ```ruby
+    #    def valid?
+    #      @errors.empty? && !@ast.nil?
+    #    end
+    #    ```
+    #
+    # 4. **SmartMergerBase handles the rest** - After FileAnalysis creation,
+    #    `parse_and_analyze` checks `valid?` and raises the appropriate parse error
+    #    (TemplateParseError or DestinationParseError) if the analysis is invalid.
+    #
+    # This pattern ensures:
+    # - Consistent error handling across all *-merge gems
+    # - TreeHaver::NotAvailable (which inherits from Exception) is handled safely
+    # - Parse errors are properly wrapped in format-specific error classes
+    # - No need to rescue Exception in SmartMergerBase
+    #
+    # @example FileAnalysis error handling
+    #   def parse_content
+    #     parser = TreeHaver.parser_for(:myformat, library_path: @parser_path)
+    #     @ast = parser.parse(@source)
+    #
+    #     if @ast&.root_node&.has_error?
+    #       collect_parse_errors(@ast.root_node)
+    #       # Do NOT raise here - SmartMergerBase will check valid?
+    #     end
+    #   rescue TreeHaver::NotAvailable => e
+    #     @errors << e.message
+    #     @ast = nil
+    #     # Do NOT re-raise - SmartMergerBase will check valid?
+    #   rescue StandardError => e
+    #     @errors << e
+    #     @ast = nil
+    #     # Do NOT re-raise - SmartMergerBase will check valid?
+    #   end
+    #
     # @example Implementing a custom SmartMerger
     #   class MyFormat::SmartMerger < Ast::Merge::SmartMergerBase
     #     def analysis_class
@@ -57,7 +105,7 @@ module Ast
     # @abstract Subclass and implement {#analysis_class} and {#perform_merge}
     # @api public
     class SmartMergerBase
-      include RegionMergeable
+      include Detector::Mergeable
 
       # @return [String] Template source content
       attr_reader :template_content
@@ -95,6 +143,9 @@ module Ast
       # @return [Object, nil] Match refiner for fuzzy matching
       attr_reader :match_refiner
 
+      # @return [Hash{Symbol,String => #call}, nil] Node typing configuration
+      attr_reader :node_typing
+
       # Creates a new SmartMerger for intelligent file merging.
       #
       # @param template_content [String] Template source content
@@ -140,6 +191,16 @@ module Ast
       #   - Commonmarker: `options: { parse: { smart: true } }`
       #   - Prism: (no additional parser options needed)
       #
+      # @param node_typing [Hash{Symbol,String => #call}, nil] Node typing configuration
+      #   for per-node-type merge preferences. Maps node type names to callables that
+      #   can wrap nodes with custom merge_types for use with Hash-based preference.
+      #   @example
+      #     node_typing = {
+      #       CallNode: ->(node) {
+      #         NodeTyping.with_merge_type(node, :special) if special_node?(node)
+      #       }
+      #     }
+      #
       # @raise [Ast::Merge::TemplateParseError] If template has syntax errors
       # @raise [Ast::Merge::DestinationParseError] If destination has syntax errors
       def initialize(
@@ -152,6 +213,7 @@ module Ast
         match_refiner: nil,
         regions: nil,
         region_placeholder: nil,
+        node_typing: nil,
         **format_options
       )
         @template_content = template_content
@@ -161,8 +223,12 @@ module Ast
         @add_template_only_nodes = add_template_only_nodes
         @freeze_token = freeze_token || default_freeze_token
         @match_refiner = match_refiner
+        @node_typing = node_typing
         @format_options = format_options
 
+        # Validate node_typing if provided
+        NodeTyping.validate!(node_typing) if node_typing
+
         # Set up region support
         setup_regions(regions: regions || [], region_placeholder: region_placeholder)
 
@@ -321,19 +387,36 @@ module Ast
 
       # Parse and analyze content, raising appropriate errors.
       #
+      # Error handling:
+      # - All FileAnalysis classes handle TreeHaver::NotAvailable internally,
+      #   storing the error and setting valid? to false
+      # - The validity check catches silent failures (grammar not available, parse errors)
+      # - StandardError from FileAnalysis initialization is wrapped in parse error
+      #
       # @param content [String] Content to parse
       # @param source [Symbol] :template or :destination
       # @return [Object] The analysis result
       def parse_and_analyze(content, source)
         options = build_full_analysis_options
 
-        DebugLogger.time("#{self.class.name}#analyze_#{source}") do
+        analysis = DebugLogger.time("#{self.class.name}#analyze_#{source}") do
           analysis_class.new(content, **options)
         end
+
+        # Check if the analysis is valid - if not, raise a parse error
+        # This catches cases where parsing fails silently (e.g., grammar not available)
+        if analysis.respond_to?(:valid?) && !analysis.valid?
+          error_class = (source == :template) ? template_parse_error_class : destination_parse_error_class
+          errors = analysis.respond_to?(:errors) ? analysis.errors : []
+          raise error_class.new(errors: errors, content: content)
+        end
+
+        analysis
       rescue StandardError => e
         # Don't re-wrap our own parse errors
         raise if e.is_a?(template_parse_error_class) || e.is_a?(destination_parse_error_class)
 
+        # Wrap the error in our parse error class
         error_class = (source == :template) ? template_parse_error_class : destination_parse_error_class
         raise error_class.new(errors: [e], content: content)
       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 = "1.1.0"
+      VERSION = "2.0.0"
     end
     VERSION = Version::VERSION # traditional location
   end

data/lib/ast/merge.rb

@@ -136,27 +136,31 @@ module Ast
       end
     end
 
+    # Core classes
     autoload :AstNode, "ast/merge/ast_node"
     autoload :Comment, "ast/merge/comment"
     autoload :ConflictResolverBase, "ast/merge/conflict_resolver_base"
+    autoload :ContentMatchRefiner, "ast/merge/content_match_refiner"
     autoload :DebugLogger, "ast/merge/debug_logger"
-    autoload :FencedCodeBlockDetector, "ast/merge/fenced_code_block_detector"
     autoload :FileAnalyzable, "ast/merge/file_analyzable"
     autoload :Freezable, "ast/merge/freezable"
     autoload :FreezeNodeBase, "ast/merge/freeze_node_base"
+    autoload :InjectionPoint, "ast/merge/navigable_statement"
+    autoload :InjectionPointFinder, "ast/merge/navigable_statement"
     autoload :MatchRefinerBase, "ast/merge/match_refiner_base"
     autoload :MatchScoreBase, "ast/merge/match_score_base"
     autoload :MergeResultBase, "ast/merge/merge_result_base"
     autoload :MergerConfig, "ast/merge/merger_config"
+    autoload :NavigableStatement, "ast/merge/navigable_statement"
     autoload :NodeTyping, "ast/merge/node_typing"
-    autoload :Region, "ast/merge/region"
-    autoload :RegionDetectorBase, "ast/merge/region_detector_base"
-    autoload :RegionMergeable, "ast/merge/region_mergeable"
+    autoload :PartialTemplateMerger, "ast/merge/partial_template_merger"
     autoload :SectionTyping, "ast/merge/section_typing"
     autoload :SmartMergerBase, "ast/merge/smart_merger_base"
     autoload :Text, "ast/merge/text"
-    autoload :TomlFrontmatterDetector, "ast/merge/toml_frontmatter_detector"
-    autoload :YamlFrontmatterDetector, "ast/merge/yaml_frontmatter_detector"
+
+    # Namespaces
+    autoload :Detector, "ast/merge/detector/base"  # Detector::Region, Detector::Base, Detector::Mergeable, etc.
+    autoload :Recipe, "ast/merge/recipe"
   end
 end