ast-merge 1.1.0 → 2.0.1

data/exe/ast-merge-recipe

@@ -0,0 +1,366 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# AST Merge Recipe Runner
+#
+# Run YAML-based merge recipes against target files.
+# This is a shipped executable that can be used after installing the ast-merge gem.
+#
+# Usage:
+#   ast-merge-recipe RECIPE_FILE [options]
+#
+# Examples:
+#   ast-merge-recipe .merge-recipes/gem_family_section.yml --dry-run
+#   ast-merge-recipe .merge-recipes/gem_family_section.yml --verbose --parser=commonmarker
+
+require "bundler/inline"
+require "optparse"
+require "yaml"
+
+# Parse options first to get merge_gems before bundler/inline
+options = {
+  dry_run: false,
+  verbose: false,
+  parser: :markly,
+  base_dir: Dir.pwd,
+  recipe_file: nil,
+  merge_gems: [],
+  dev_mode: ENV.fetch("KETTLE_RB_DEV", "false").casecmp?("true"),
+  dev_root: nil,
+}
+
+# Pre-parse to extract recipe file and check for merge_gems in recipe
+# We need to do this before bundler/inline to know which gems to load
+ARGV.each do |arg|
+  case arg
+  when /^--dev-root=(.+)$/
+    options[:dev_root] = File.expand_path($1)
+  when /^-/
+    # Skip options for now
+  else
+    options[:recipe_file] ||= arg
+  end
+end
+
+# If recipe file specified, try to load merge_gems from it
+recipe_merge_gems = []
+if options[:recipe_file] && File.exist?(options[:recipe_file])
+  begin
+    recipe_config = YAML.safe_load_file(options[:recipe_file], permitted_classes: [Symbol])
+    if recipe_config.is_a?(Hash) && recipe_config["merge_gems"]
+      recipe_merge_gems = Array(recipe_config["merge_gems"])
+    end
+  rescue
+    # Ignore errors here, we'll catch them later
+  end
+end
+
+# Determine dev root for local gems
+dev_root = options[:dev_root] || ENV["AST_MERGE_DEV_ROOT"]
+if options[:dev_mode] && dev_root.nil?
+  # Try to find dev root by looking for ast-merge directory
+  possible_roots = [
+    File.expand_path("../..", __FILE__),
+    File.expand_path("../../..", __FILE__),
+    Dir.pwd,
+  ]
+  dev_root = possible_roots.find { |p| File.exist?(File.join(p, "ast-merge.gemspec")) }
+end
+
+# Load dependencies via bundler/inline
+gemfile do
+  source "https://gem.coop"
+
+  if options[:dev_mode] && dev_root
+    # Development mode - use local gems
+    gem "ast-merge", path: dev_root
+    gem "tree_haver", path: File.join(dev_root, "vendor/tree_haver")
+    gem "markdown-merge", path: File.join(dev_root, "vendor/markdown-merge")
+    gem "markly-merge", path: File.join(dev_root, "vendor/markly-merge")
+    gem "commonmarker-merge", path: File.join(dev_root, "vendor/commonmarker-merge")
+    gem "prism-merge", path: File.join(dev_root, "vendor/prism-merge")
+    gem "psych-merge", path: File.join(dev_root, "vendor/psych-merge")
+  else
+    # Production mode - use released gems
+    # gem.coop gems need a source block
+    gem "ast-merge"
+    gem "tree_haver"
+    gem "markdown-merge"
+    gem "markly-merge"
+  end
+
+  # Load additional merge gems specified in recipe
+  recipe_merge_gems.each do |gem_spec|
+    case gem_spec
+    when String
+      gem(gem_spec)
+    when Hash
+      name = gem_spec["name"] || gem_spec[:name]
+      gem_opts = {}
+      gem_opts[:version] = gem_spec["version"] || gem_spec[:version] if gem_spec["version"] || gem_spec[:version]
+      gem_opts[:path] = gem_spec["path"] || gem_spec[:path] if gem_spec["path"] || gem_spec[:path]
+      gem_opts[:git] = gem_spec["git"] || gem_spec[:git] if gem_spec["git"] || gem_spec[:git]
+      gem_opts[:branch] = gem_spec["branch"] || gem_spec[:branch] if gem_spec["branch"] || gem_spec[:branch]
+      gem_opts[:require] = gem_spec["require"] || gem_spec[:require] if gem_spec.key?("require") || gem_spec.key?(:require)
+
+      if gem_opts.empty?
+        gem(name)
+      else
+        gem(name, **gem_opts)
+      end
+    end
+  end
+
+  # Try to load table_tennis for nice output
+  gem "table_tennis", require: false
+end
+
+# Now load the actual libraries
+require "ast-merge"
+
+# Try to load table_tennis
+begin
+  require "table_tennis"
+  HAS_TABLE_TENNIS = true
+rescue LoadError
+  HAS_TABLE_TENNIS = false
+end
+
+# ANSI color helpers
+module Colors
+  class << self
+    def green(str) = "\e[32m#{str}\e[0m"
+    def red(str) = "\e[31m#{str}\e[0m"
+    def yellow(str) = "\e[33m#{str}\e[0m"
+    def cyan(str) = "\e[36m#{str}\e[0m"
+    def bold(str) = "\e[1m#{str}\e[0m"
+    def dim(str) = "\e[2m#{str}\e[0m"
+  end
+end
+
+# Main runner class
+class AstMergeRecipeCLI
+  VERSION = Ast::Merge::VERSION
+
+  def initialize
+    @options = {
+      dry_run: false,
+      verbose: false,
+      parser: :markly,
+      base_dir: Dir.pwd,
+      recipe_file: nil,
+    }
+  end
+
+  def run(argv = ARGV)
+    parse_options(argv)
+    validate_options!
+    execute_recipe
+  rescue OptionParser::InvalidOption, OptionParser::MissingArgument => e
+    $stderr.puts Colors.red("ERROR: #{e.message}")
+    $stderr.puts
+    $stderr.puts @option_parser
+    exit(1)
+  rescue => e
+    $stderr.puts Colors.red("ERROR: #{e.message}")
+    $stderr.puts e.backtrace.first(5).join("\n") if @options[:verbose]
+    exit(1)
+  end
+
+  private
+
+  def parse_options(argv)
+    @option_parser = OptionParser.new do |opts|
+      opts.banner = "Usage: #{File.basename($0)} RECIPE_FILE [options]"
+      opts.separator("")
+      opts.separator("Run a YAML-based merge recipe against target files.")
+      opts.separator("")
+      opts.separator("Options:")
+
+      opts.on("-n", "--dry-run", "Show what would change without modifying files") do
+        @options[:dry_run] = true
+      end
+
+      opts.on("-v", "--verbose", "Show detailed output") do
+        @options[:verbose] = true
+      end
+
+      opts.on(
+        "-p",
+        "--parser=PARSER",
+        String,
+        "Parser to use (markly, commonmarker, prism, psych)",
+        "Default: markly",
+      ) do |parser|
+        @options[:parser] = parser.to_sym
+      end
+
+      opts.on(
+        "-d",
+        "--base-dir=DIR",
+        String,
+        "Base directory for path resolution",
+        "Default: current directory",
+      ) do |dir|
+        @options[:base_dir] = File.expand_path(dir)
+      end
+
+      opts.on(
+        "--dev-root=DIR",
+        String,
+        "Root directory for development gems (implies dev mode)",
+      ) do |dir|
+        # Already handled in pre-parse
+      end
+
+      opts.on("-V", "--version", "Show version") do
+        puts "ast-merge-recipe #{VERSION}"
+        exit(0)
+      end
+
+      opts.on("-h", "--help", "Show this help message") do
+        puts opts
+        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
+        puts "Recipe YAML format:"
+        puts "  See lib/ast/merge/recipe/README.md for full documentation"
+        exit(0)
+      end
+    end
+
+    # Parse options, leaving non-option arguments
+    remaining = @option_parser.parse(argv)
+
+    # 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
+  end
+
+  def validate_options!
+    unless @options[:recipe_file]
+      $stderr.puts Colors.red("ERROR: No recipe file specified")
+      $stderr.puts
+      $stderr.puts @option_parser
+      exit(1)
+    end
+
+    recipe_path = File.expand_path(@options[:recipe_file])
+    unless File.exist?(recipe_path)
+      $stderr.puts Colors.red("ERROR: Recipe file not found: #{recipe_path}")
+      exit(1)
+    end
+
+    @options[:recipe_file] = recipe_path
+  end
+
+  def execute_recipe
+    print_header
+
+    # Load recipe
+    recipe = Ast::Merge::Recipe::Config.load(@options[:recipe_file])
+    print_recipe_info(recipe)
+
+    # Create runner
+    runner = Ast::Merge::Recipe::Runner.new(
+      recipe,
+      dry_run: @options[:dry_run],
+      base_dir: @options[:base_dir],
+      parser: @options[:parser],
+      verbose: @options[:verbose],
+    )
+
+    # Run and display results
+    puts Colors.cyan("Processing files...")
+    puts
+
+    runner.run do |result|
+      print_result(result)
+    end
+
+    print_summary(runner)
+
+    # Exit with error if there were failures
+    exit(1) if runner.summary[:errors] > 0
+  end
+
+  def print_header
+    puts Colors.bold("=" * 70)
+    puts Colors.bold("AST Merge Recipe Runner")
+    puts Colors.bold("=" * 70)
+    puts
+  end
+
+  def print_recipe_info(recipe)
+    puts Colors.cyan("Recipe: #{recipe.name}")
+    puts Colors.dim("  #{recipe.description}") if recipe.description
+    puts
+    puts Colors.yellow("Mode: #{@options[:dry_run] ? "DRY RUN" : "LIVE"}")
+    puts Colors.dim("Parser: #{@options[:parser]}")
+    puts
+  end
+
+  def print_result(result)
+    symbol = status_symbol(result.status)
+    puts "  #{symbol} #{result.relative_path}"
+
+    if @options[:verbose] || result.status == :error
+      puts Colors.dim("      #{result.message}") if result.message
+    end
+
+    if @options[:verbose] && result.stats
+      puts Colors.dim("      Stats: #{result.stats.inspect}")
+    end
+
+    if result.error && @options[:verbose]
+      puts Colors.red("      #{result.error.class}: #{result.error.message}")
+      puts Colors.dim("      #{result.error.backtrace&.first(3)&.join("\n      ")}")
+    end
+  end
+
+  def print_summary(runner)
+    puts
+    puts Colors.bold("=" * 70)
+    puts Colors.bold("Summary")
+    puts Colors.bold("=" * 70)
+    puts
+
+    summary = runner.summary
+
+    if HAS_TABLE_TENNIS
+      puts TableTennis.new(runner.summary_table)
+    else
+      puts "  Total files:        #{summary[:total]}"
+      if @options[:dry_run]
+        puts "  Would update:       #{summary[:would_update]}"
+      else
+        puts "  Updated:            #{summary[:updated]}"
+      end
+      puts "  Unchanged:          #{summary[:unchanged]}"
+      puts "  Skipped (no anchor):#{summary[:skipped]}"
+      puts "  Errors:             #{summary[:errors]}" if summary[:errors] > 0
+    end
+
+    puts
+  end
+
+  def status_symbol(status)
+    case status
+    when :updated then Colors.green("✓")
+    when :would_update then Colors.yellow("~")
+    when :unchanged then Colors.dim("○")
+    when :skipped then Colors.dim("-")
+    when :error then Colors.red("✗")
+    else "?"
+    end
+  end
+end
+
+# Run the CLI
+AstMergeRecipeCLI.new.run

data/lib/ast/merge/conflict_resolver_base.rb

@@ -118,6 +118,9 @@ module Ast
       # @return [Boolean] Whether to add template-only nodes (batch strategy)
       attr_reader :add_template_only_nodes
 
+      # @return [Object, nil] Match refiner for fuzzy matching
+      attr_reader :match_refiner
+
       # Initialize the conflict resolver
       #
       # @param strategy [Symbol] Resolution strategy (:node, :batch, or :boundary)
@@ -129,7 +132,9 @@ module Ast
       # @param template_analysis [Object] Analysis of the template file
       # @param dest_analysis [Object] Analysis of the destination file
       # @param add_template_only_nodes [Boolean] Whether to add nodes only in template (batch/boundary strategy)
-      def initialize(strategy:, preference:, template_analysis:, dest_analysis:, add_template_only_nodes: false)
+      # @param match_refiner [#call, nil] Optional match refiner for fuzzy matching
+      # @param options [Hash] Additional options for forward compatibility
+      def initialize(strategy:, preference:, template_analysis:, dest_analysis:, add_template_only_nodes: false, match_refiner: nil, **options)
         unless %i[node batch boundary].include?(strategy)
           raise ArgumentError, "Invalid strategy: #{strategy}. Must be :node, :batch, or :boundary"
         end
@@ -141,6 +146,8 @@ module Ast
         @template_analysis = template_analysis
         @dest_analysis = dest_analysis
         @add_template_only_nodes = add_template_only_nodes
+        @match_refiner = match_refiner
+        # **options captured for forward compatibility - subclasses may use additional options
       end
 
       # Resolve conflicts using the configured strategy

data/lib/ast/merge/content_match_refiner.rb

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    # Match refiner for text content-based fuzzy matching.
+    #
+    # This refiner uses Levenshtein distance to pair nodes that have similar
+    # but not identical text content. It's useful for matching nodes where
+    # the content has been slightly modified (typos, rewording, etc.).
+    #
+    # Unlike signature-based matching which requires exact content hashes,
+    # this refiner allows fuzzy matching based on text similarity. This is
+    # particularly useful for:
+    # - Paragraphs with minor edits
+    # - Headings with slight rewording
+    # - Comments with updated text
+    # - Any text-based node type
+    #
+    # @example Basic usage
+    #   refiner = ContentMatchRefiner.new(threshold: 0.7)
+    #   matches = refiner.call(template_nodes, dest_nodes)
+    #
+    # @example With specific node types
+    #   # Only match paragraphs and headings
+    #   refiner = ContentMatchRefiner.new(
+    #     threshold: 0.6,
+    #     node_types: [:paragraph, :heading]
+    #   )
+    #
+    # @example With custom content extractor
+    #   refiner = ContentMatchRefiner.new(
+    #     threshold: 0.7,
+    #     content_extractor: ->(node) { node.text_content.downcase.strip }
+    #   )
+    #
+    # @example Combined with other refiners
+    #   merger = SmartMerger.new(
+    #     template,
+    #     destination,
+    #     match_refiner: [
+    #       ContentMatchRefiner.new(threshold: 0.7, node_types: [:paragraph]),
+    #       TableMatchRefiner.new(threshold: 0.5)
+    #     ]
+    #   )
+    #
+    # @see MatchRefinerBase Base class
+    class ContentMatchRefiner < MatchRefinerBase
+      # Default weights for content similarity scoring
+      DEFAULT_WEIGHTS = {
+        content: 0.7,   # Text content similarity (Levenshtein)
+        length: 0.15,   # Length similarity
+        position: 0.15, # Position similarity in document
+      }.freeze
+
+      # @return [Hash] Scoring weights
+      attr_reader :weights
+
+      # @return [Proc, nil] Custom content extraction function
+      attr_reader :content_extractor
+
+      # Initialize a content match refiner.
+      #
+      # @param threshold [Float] Minimum score to accept a match (default: 0.5)
+      # @param node_types [Array<Symbol>] Node types to process (empty = all)
+      # @param weights [Hash] Custom scoring weights
+      # @param content_extractor [Proc, nil] Custom function to extract text from nodes
+      #   Should accept a node and return a String
+      # @param options [Hash] Additional options for forward compatibility
+      def initialize(
+        threshold: DEFAULT_THRESHOLD,
+        node_types: [],
+        weights: {},
+        content_extractor: nil,
+        **options
+      )
+        super(threshold: threshold, node_types: node_types, **options)
+        @weights = DEFAULT_WEIGHTS.merge(weights)
+        @content_extractor = content_extractor
+      end
+
+      # Find matches between unmatched nodes based on content similarity.
+      #
+      # @param template_nodes [Array] Unmatched nodes from template
+      # @param dest_nodes [Array] Unmatched nodes from destination
+      # @param context [Hash] Additional context (may contain :template_analysis, :dest_analysis)
+      # @return [Array<MatchResult>] Array of content-based matches
+      def call(template_nodes, dest_nodes, context = {})
+        template_filtered = filter_nodes(template_nodes)
+        dest_filtered = filter_nodes(dest_nodes)
+
+        return [] if template_filtered.empty? || dest_filtered.empty?
+
+        # Build position information for scoring
+        total_template = template_filtered.size
+        total_dest = dest_filtered.size
+
+        greedy_match(template_filtered, dest_filtered) do |t_node, d_node|
+          t_idx = template_filtered.index(t_node) || 0
+          d_idx = dest_filtered.index(d_node) || 0
+
+          compute_content_similarity(
+            t_node,
+            d_node,
+            t_idx,
+            d_idx,
+            total_template,
+            total_dest,
+          )
+        end
+      end
+
+      protected
+
+      # Filter nodes by configured node types.
+      #
+      # @param nodes [Array] Nodes to filter
+      # @return [Array] Filtered nodes (matching node_types, or all if empty)
+      def filter_nodes(nodes)
+        return nodes if node_types.empty?
+
+        nodes.select { |n| handles_type?(extract_node_type(n)) }
+      end
+
+      # Extract the type from a node.
+      #
+      # Handles wrapped nodes (merge_type) and raw nodes (type).
+      #
+      # @param node [Object] The node
+      # @return [Symbol, nil] The node type
+      def extract_node_type(node)
+        if NodeTyping.typed_node?(node)
+          NodeTyping.merge_type_for(node)
+        elsif node.respond_to?(:merge_type) && node.merge_type
+          node.merge_type
+        elsif node.respond_to?(:type)
+          type = node.type
+          type.is_a?(Symbol) ? type : type.to_s.to_sym
+        end
+      end
+
+      # Extract text content from a node.
+      #
+      # Uses the custom content_extractor if provided, otherwise tries
+      # common methods for getting text content.
+      #
+      # @param node [Object] The node
+      # @return [String] The text content
+      def extract_content(node)
+        return @content_extractor.call(node) if @content_extractor
+
+        # Try common content extraction methods
+        if node.respond_to?(:text_content)
+          node.text_content.to_s
+        elsif node.respond_to?(:string_content)
+          node.string_content.to_s
+        elsif node.respond_to?(:content)
+          node.content.to_s
+        elsif node.respond_to?(:text)
+          node.text.to_s
+        elsif node.respond_to?(:to_s)
+          node.to_s
+        else
+          ""
+        end
+      end
+
+      # Compute similarity score between two nodes based on content.
+      #
+      # @param t_node [Object] Template node
+      # @param d_node [Object] Destination node
+      # @param t_idx [Integer] Template node index
+      # @param d_idx [Integer] Destination node index
+      # @param total_t [Integer] Total template nodes
+      # @param total_d [Integer] Total destination nodes
+      # @return [Float] Similarity score (0.0-1.0)
+      def compute_content_similarity(t_node, d_node, t_idx, d_idx, total_t, total_d)
+        t_content = extract_content(t_node)
+        d_content = extract_content(d_node)
+
+        # Calculate component scores
+        content_score = string_similarity(t_content, d_content)
+        length_score = length_similarity(t_content, d_content)
+        position_score = position_similarity(t_idx, d_idx, total_t, total_d)
+
+        # Weighted combination
+        weights[:content] * content_score +
+          weights[:length] * length_score +
+          weights[:position] * position_score
+      end
+
+      # Calculate string similarity using Levenshtein distance.
+      #
+      # @param str1 [String] First string
+      # @param str2 [String] Second string
+      # @return [Float] Similarity score (0.0-1.0)
+      def string_similarity(str1, str2)
+        return 1.0 if str1 == str2
+        return 0.0 if str1.empty? || str2.empty?
+
+        distance = levenshtein_distance(str1, str2)
+        max_len = [str1.length, str2.length].max
+        1.0 - (distance.to_f / max_len)
+      end
+
+      # Calculate length similarity between two strings.
+      #
+      # @param str1 [String] First string
+      # @param str2 [String] Second string
+      # @return [Float] Similarity score (0.0-1.0)
+      def length_similarity(str1, str2)
+        return 1.0 if str1.length == str2.length
+        return 0.0 if str1.empty? && str2.empty?
+
+        min_len = [str1.length, str2.length].min.to_f
+        max_len = [str1.length, str2.length].max.to_f
+        min_len / max_len
+      end
+
+      # Calculate position similarity in document.
+      #
+      # Nodes at similar relative positions score higher.
+      #
+      # @param idx1 [Integer] First node index
+      # @param idx2 [Integer] Second node index
+      # @param total1 [Integer] Total nodes in first collection
+      # @param total2 [Integer] Total nodes in second collection
+      # @return [Float] Similarity score (0.0-1.0)
+      def position_similarity(idx1, idx2, total1, total2)
+        # Normalize positions to 0.0-1.0 range
+        pos1 = (total1 > 1) ? idx1.to_f / (total1 - 1) : 0.5
+        pos2 = (total2 > 1) ? idx2.to_f / (total2 - 1) : 0.5
+
+        1.0 - (pos1 - pos2).abs
+      end
+
+      # Calculate Levenshtein distance between two strings.
+      #
+      # Uses Wagner-Fischer algorithm with space optimization.
+      #
+      # @param str1 [String] First string
+      # @param str2 [String] Second string
+      # @return [Integer] Edit distance
+      def levenshtein_distance(str1, str2)
+        return str2.length if str1.empty?
+        return str1.length if str2.empty?
+
+        # Use shorter string as columns for space efficiency
+        if str1.length > str2.length
+          str1, str2 = str2, str1
+        end
+
+        m = str1.length
+        n = str2.length
+
+        # Only need two rows at a time
+        prev_row = (0..m).to_a
+        curr_row = Array.new(m + 1)
+
+        (1..n).each do |j|
+          curr_row[0] = j
+
+          (1..m).each do |i|
+            cost = (str1[i - 1] == str2[j - 1]) ? 0 : 1
+            curr_row[i] = [
+              curr_row[i - 1] + 1,      # insertion
+              prev_row[i] + 1,          # deletion
+              prev_row[i - 1] + cost,   # substitution
+            ].min
+          end
+
+          prev_row, curr_row = curr_row, prev_row
+        end
+
+        prev_row[m]
+      end
+    end
+  end
+end

data/lib/ast/merge/debug_logger.rb

@@ -71,8 +71,9 @@ module Ast
     # @note Shared examples require +silent_stream+ and +rspec-stubbed_env+ gems.
     module DebugLogger
       # Benchmark is optional - gracefully degrade if not available
+      # Use autoload to defer loading until actually needed
       BENCHMARK_AVAILABLE = begin
-        require "benchmark"
+        autoload(:Benchmark, "benchmark")
         true
       rescue LoadError
         # :nocov: