ast-merge 1.0.0 → 2.0.0

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/ast_node.rb

@@ -2,27 +2,78 @@
 
 module Ast
   module Merge
-    # Base class for AST nodes in the ast-merge framework.
+    # Base class for synthetic AST nodes in the ast-merge framework.
     #
-    # This provides a common API that works across different AST implementations
-    # (Prism, TreeSitter, custom comment nodes, etc.) enabling uniform handling
-    # in merge operations.
+    # "Synthetic" nodes are nodes that aren't backed by a real parser - they're
+    # created by ast-merge for representing content that doesn't have a native
+    # AST (comments, text lines, env file entries, etc.).
     #
-    # Subclasses should implement:
-    # - #slice - returns the source text for the node
-    # - #location - returns an object responding to start_line/end_line
-    # - #children - returns child nodes (empty array for leaf nodes)
-    # - #signature - returns a signature array for matching (optional, can use default)
+    # 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.
     #
-    # @abstract
+    # Implements the TreeHaver::Node protocol:
+    # - type → String node type
+    # - text / slice → Source text content
+    # - start_byte / end_byte → Byte offsets
+    # - start_point / end_point → Point (row, column)
+    # - children → Array of child nodes
+    # - named? / structural? → Node classification
+    # - inner_node → Returns self (no wrapping layer for synthetic nodes)
+    #
+    # Adds merge-specific methods:
+    # - signature → Array used for matching nodes across files
+    # - normalized_content → Cleaned text for comparison
+    #
+    # @example Subclassing for custom node types
+    #   class MyNode < AstNode
+    #     def type
+    #       "my_node"
+    #     end
+    #
+    #     def signature
+    #       [:my_node, normalized_content]
+    #     end
+    #   end
+    #
+    # @see TreeHaver::Node The protocol this class implements
+    # @see Comment::Line Example synthetic node for comments
+    # @see Text::LineNode Example synthetic node for text lines
     class AstNode
-      # Simple location struct for nodes that don't have a native location object
+      include Comparable
+
+      # 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
+        # Hash-like access for compatibility
+        def [](key)
+          case key
+          when :row, "row" then row
+          when :column, "column" then column
+          end
+        end
+
+        def to_h
+          {row: row, column: column}
+        end
+
+        def to_s
+          "(#{row}, #{column})"
+        end
+
+        def inspect
+          "#<Ast::Merge::AstNode::Point row=#{row} column=#{column}>"
+        end
+      end
+
+      # Location struct for tracking source positions
+      # Compatible with TreeHaver location expectations
       Location = Struct.new(:start_line, :end_line, :start_column, :end_column, keyword_init: true) do
         # Check if a line number falls within this location
-        # @param line_number [Integer] The line number to check
+        # @param line_number [Integer] The line number to check (1-based)
         # @return [Boolean] true if the line number is within the range
         def cover?(line_number)
-          line_number >= start_line && line_number <= end_line
+          line_number.between?(start_line, end_line)
         end
       end
 
@@ -32,28 +83,164 @@ 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
-      # @param location [Location, #start_line] Location object or anything responding to start_line/end_line
-      def initialize(slice:, location:)
+      # @param location [Location, #start_line] Location object
+      # @param source [String, nil] Full source text (optional)
+      def initialize(slice:, location:, source: nil)
         @slice = slice
         @location = location
+        @source = source
       end
 
+      # TreeHaver::Node protocol: inner_node
+      # For synthetic nodes, this returns self (no wrapping layer)
+      #
+      # @return [AstNode] self
+      def inner_node
+        self
+      end
+
+      # TreeHaver::Node protocol: type
+      # Returns the node type as a string.
+      # Subclasses should override this with specific type names.
+      #
+      # @return [String] Node type
+      def type
+        # Default: derive from class name (MyNode → "my_node")
+        self.class.name.split("::").last
+          .gsub(/([A-Z])/, '_\1')
+          .downcase
+          .sub(/^_/, "")
+      end
+
+      # Alias for tree-sitter compatibility
+      alias_method :kind, :type
+
+      # TreeHaver::Node protocol: text
+      # @return [String] The source text
+      def text
+        slice.to_s
+      end
+
+      # TreeHaver::Node protocol: start_byte
+      # Calculates byte offset from source if available, otherwise estimates from lines
+      #
+      # @return [Integer] Starting byte offset
+      def start_byte
+        return 0 unless source && location
+
+        # Calculate byte offset from line/column
+        lines = source.lines
+        byte_offset = 0
+        (0...(location.start_line - 1)).each do |i|
+          byte_offset += lines[i]&.bytesize || 0
+        end
+        byte_offset + (location.start_column || 0)
+      end
+
+      # TreeHaver::Node protocol: end_byte
+      #
+      # @return [Integer] Ending byte offset
+      def end_byte
+        start_byte + slice.to_s.bytesize
+      end
+
+      # TreeHaver::Node protocol: start_point
+      # Returns a Point with row (0-based) and column
+      #
+      # @return [Point] Starting position
+      def start_point
+        Point.new(
+          row: (location&.start_line || 1) - 1,  # Convert to 0-based
+          column: location&.start_column || 0,
+        )
+      end
+
+      # TreeHaver::Node protocol: end_point
+      # Returns a Point with row (0-based) and column
+      #
+      # @return [Point] Ending position
+      def end_point
+        Point.new(
+          row: (location&.end_line || 1) - 1,  # Convert to 0-based
+          column: location&.end_column || 0,
+        )
+      end
+
+      # TreeHaver::Node protocol: children
       # @return [Array<AstNode>] Child nodes (empty for leaf nodes)
       def children
         []
       end
 
+      # TreeHaver::Node protocol: child_count
+      # @return [Integer] Number of children
+      def child_count
+        children.size
+      end
+
+      # TreeHaver::Node protocol: child(index)
+      # @param index [Integer] Child index
+      # @return [AstNode, nil] Child at index
+      def child(index)
+        children[index]
+      end
+
+      # TreeHaver::Node protocol: named?
+      # Synthetic nodes are always "named" (structural) nodes
+      #
+      # @return [Boolean] true
+      def named?
+        true
+      end
+
+      # TreeHaver::Node protocol: structural?
+      # Synthetic nodes are always structural
+      #
+      # @return [Boolean] true
+      def structural?
+        true
+      end
+
+      # TreeHaver::Node protocol: has_error?
+      # Synthetic nodes don't have parse errors
+      #
+      # @return [Boolean] false
+      def has_error?
+        false
+      end
+
+      # TreeHaver::Node protocol: missing?
+      # Synthetic nodes are never "missing"
+      #
+      # @return [Boolean] false
+      def missing?
+        false
+      end
+
+      # TreeHaver::Node protocol: each
+      # Iterate over children
+      #
+      # @yield [AstNode] Each child node
+      # @return [Enumerator, nil]
+      def each(&block)
+        return to_enum(__method__) unless block_given?
+        children.each(&block)
+      end
+
       # Generate a signature for this node for matching purposes.
       #
       # Override in subclasses for custom signature logic.
-      # Default returns the node class name and a normalized form of the slice.
+      # Default returns the node type and a normalized form of the slice.
       #
       # @return [Array] Signature array for matching
       def signature
-        [self.class.name, normalized_content]
+        [type.to_sym, normalized_content]
       end
 
       # @return [String] Normalized content for signature comparison
@@ -61,9 +248,22 @@ module Ast
         slice.to_s.strip
       end
 
+      # Comparable: compare nodes by position
+      #
+      # @param other [AstNode] node to compare with
+      # @return [Integer, nil] -1, 0, 1, or nil if not comparable
+      def <=>(other)
+        return unless other.respond_to?(:start_byte) && other.respond_to?(:end_byte)
+
+        cmp = start_byte <=> other.start_byte
+        return cmp if cmp.nonzero?
+
+        end_byte <=> other.end_byte
+      end
+
       # @return [String] Human-readable representation
       def inspect
-        "#<#{self.class.name} lines=#{location.start_line}..#{location.end_line} slice=#{slice.to_s[0..50].inspect}>"
+        "#<#{self.class.name} type=#{type} lines=#{location&.start_line}..#{location&.end_line}>"
       end
 
       # @return [String] The source text
@@ -76,12 +276,12 @@ module Ast
       def unwrap
         self
       end
-
-      # Check if this node responds to the Prism-style location API
-      # @return [Boolean] true
-      def respond_to_missing?(method, include_private = false)
-        [:location, :slice].include?(method) || super
-      end
     end
+
+    # Alias for clarity - SyntheticNode clearly indicates "not backed by a real parser"
+    # Use this alias when the distinction between synthetic and parser-backed nodes matters.
+    #
+    # @see AstNode
+    SyntheticNode = AstNode
   end
 end

data/lib/ast/merge/comment/block.rb

@@ -41,6 +41,12 @@ module Ast
         # @return [Style] The comment style configuration
         attr_reader :style
 
+        # TreeHaver::Node protocol: type
+        # @return [String] "comment_block"
+        def type
+          "comment_block"
+        end
+
         # Initialize a new Block.
         #
         # For line-based comments, pass `children` array.

data/lib/ast/merge/comment/empty.rb

@@ -28,6 +28,12 @@ module Ast
         # @return [String] The actual line content (may have whitespace)
         attr_reader :text
 
+        # TreeHaver::Node protocol: type
+        # @return [String] "empty_line"
+        def type
+          "empty_line"
+        end
+
         # Initialize a new Empty line.
         #
         # @param line_number [Integer] The 1-based line number

data/lib/ast/merge/comment/line.rb

@@ -38,6 +38,12 @@ module Ast
         # @return [Style] The comment style configuration
         attr_reader :style
 
+        # TreeHaver::Node protocol: type
+        # @return [String] "comment_line"
+        def type
+          "comment_line"
+        end
+
         # Initialize a new Line.
         #
         # @param text [String] The full comment text including delimiter