bash-merge 1.0.0

data/lib/bash/merge/node_wrapper.rb

@@ -0,0 +1,342 @@
+# frozen_string_literal: true
+
+module Bash
+  module Merge
+    # Wraps TreeHaver nodes with comment associations, line information, and signatures.
+    # This provides a unified interface for working with Bash AST nodes during merging.
+    #
+    # @example Basic usage
+    #   parser = TreeHaver::Parser.new
+    #   parser.language = TreeHaver::Language.bash
+    #   tree = parser.parse(source)
+    #   wrapper = NodeWrapper.new(tree.root_node, lines: source.lines, source: source)
+    #   wrapper.signature # => [:program, ...]
+    class NodeWrapper
+      # @return [TreeHaver::Node] The wrapped tree-haver node
+      attr_reader :node
+
+      # @return [Array<Hash>] Leading comments associated with this node
+      attr_reader :leading_comments
+
+      # @return [Hash, nil] Inline/trailing comment on the same line
+      attr_reader :inline_comment
+
+      # @return [Integer] Start line (1-based)
+      attr_reader :start_line
+
+      # @return [Integer] End line (1-based)
+      attr_reader :end_line
+
+      # @return [Array<String>] Source lines
+      attr_reader :lines
+
+      # @return [String] The original source string
+      attr_reader :source
+
+      # @param node [TreeHaver::Node] tree-haver node to wrap
+      # @param lines [Array<String>] Source lines for content extraction
+      # @param source [String] Original source string for byte-based text extraction
+      # @param leading_comments [Array<Hash>] Comments before this node
+      # @param inline_comment [Hash, nil] Inline comment on the node's line
+      def initialize(node, lines:, source: nil, leading_comments: [], inline_comment: nil)
+        @node = node
+        @lines = lines
+        @source = source || lines.join("\n")
+        @leading_comments = leading_comments
+        @inline_comment = inline_comment
+
+        # Extract line information from the tree-haver node (0-indexed to 1-indexed)
+        if node.respond_to?(:start_point)
+          point = node.start_point
+          @start_line = (point.respond_to?(:row) ? point.row : point[:row]) + 1
+        end
+        if node.respond_to?(:end_point)
+          point = node.end_point
+          @end_line = (point.respond_to?(:row) ? point.row : point[:row]) + 1
+        end
+
+        # Handle edge case where end_line might be before start_line
+        @end_line = @start_line if @start_line && @end_line && @end_line < @start_line
+      end
+
+      # Generate a signature for this node for matching purposes.
+      # Signatures are used to identify corresponding nodes between template and destination.
+      #
+      # @return [Array, nil] Signature array or nil if not signaturable
+      def signature
+        compute_signature(@node)
+      end
+
+      # Check if this is a freeze node
+      # @return [Boolean]
+      def freeze_node?
+        false
+      end
+
+      # Get the node type as a symbol
+      # @return [Symbol]
+      def type
+        @node.type.to_sym
+      end
+
+      # Check if this node has a specific type
+      # @param type_name [Symbol, String] Type to check
+      # @return [Boolean]
+      def type?(type_name)
+        @node.type.to_s == type_name.to_s
+      end
+
+      # Check if this is a function definition
+      # @return [Boolean]
+      def function_definition?
+        @node.type.to_s == "function_definition"
+      end
+
+      # Check if this is a variable assignment
+      # @return [Boolean]
+      def variable_assignment?
+        @node.type.to_s == "variable_assignment"
+      end
+
+      # Check if this is an if statement
+      # @return [Boolean]
+      def if_statement?
+        @node.type.to_s == "if_statement"
+      end
+
+      # Check if this is a for loop
+      # @return [Boolean]
+      def for_statement?
+        %w[for_statement c_style_for_statement].include?(@node.type.to_s)
+      end
+
+      # Check if this is a while loop
+      # @return [Boolean]
+      def while_statement?
+        @node.type.to_s == "while_statement"
+      end
+
+      # Check if this is a case statement
+      # @return [Boolean]
+      def case_statement?
+        @node.type.to_s == "case_statement"
+      end
+
+      # Check if this is a command
+      # @return [Boolean]
+      def command?
+        @node.type.to_s == "command"
+      end
+
+      # Check if this is a pipeline
+      # @return [Boolean]
+      def pipeline?
+        @node.type.to_s == "pipeline"
+      end
+
+      # Check if this is a comment
+      # @return [Boolean]
+      def comment?
+        @node.type.to_s == "comment"
+      end
+
+      # Get the function name if this is a function definition
+      # @return [String, nil]
+      def function_name
+        return unless function_definition?
+
+        # In bash tree-sitter, function name is in a 'name' or 'word' child
+        name_node = find_child_by_type("word") || find_child_by_field("name")
+        node_text(name_node) if name_node
+      end
+
+      # Get the variable name if this is a variable assignment
+      # @return [String, nil]
+      def variable_name
+        return unless variable_assignment?
+
+        # In bash tree-sitter, variable name is a child of type 'variable_name'
+        name_node = find_child_by_type("variable_name")
+        node_text(name_node) if name_node
+      end
+
+      # Get the command name if this is a command
+      # @return [String, nil]
+      def command_name
+        return unless command?
+
+        # First child that is a word or simple_expansion
+        @node.each do |child|
+          next if %w[comment file_redirect heredoc_redirect].include?(child.type.to_s)
+
+          return node_text(child) if %w[word command_name].include?(child.type.to_s)
+        end
+        nil
+      end
+
+      # Get children wrapped as NodeWrappers
+      # @return [Array<NodeWrapper>]
+      def children
+        return [] unless @node.respond_to?(:each)
+
+        result = []
+        @node.each do |child|
+          result << NodeWrapper.new(child, lines: @lines, source: @source)
+        end
+        result
+      end
+
+      # Find a child by field name
+      # @param field_name [String] Field name to look for
+      # @return [TreeSitter::Node, nil]
+      def find_child_by_field(field_name)
+        return unless @node.respond_to?(:child_by_field_name)
+
+        @node.child_by_field_name(field_name)
+      end
+
+      # Find a child by type
+      # @param type_name [String] Type name to look for
+      # @return [TreeSitter::Node, nil]
+      def find_child_by_type(type_name)
+        return unless @node.respond_to?(:each)
+
+        @node.each do |child|
+          return child if child.type.to_s == type_name
+        end
+        nil
+      end
+
+      # Get the text content for this node by extracting from source using byte positions
+      # @return [String]
+      def text
+        node_text(@node)
+      end
+
+      # Extract text from a tree-sitter node using byte positions
+      # @param ts_node [TreeSitter::Node] The tree-sitter node
+      # @return [String]
+      def node_text(ts_node)
+        return "" unless ts_node.respond_to?(:start_byte) && ts_node.respond_to?(:end_byte)
+
+        @source[ts_node.start_byte...ts_node.end_byte] || ""
+      end
+
+      # Get the content for this node from source lines
+      # @return [String]
+      def content
+        return "" unless @start_line && @end_line
+
+        (@start_line..@end_line).map { |ln| @lines[ln - 1] }.compact.join("\n")
+      end
+
+      # String representation for debugging
+      # @return [String]
+      def inspect
+        "#<#{self.class.name} type=#{@node.type} lines=#{@start_line}..#{@end_line}>"
+      end
+
+      private
+
+      def compute_signature(node)
+        node_type = node.type.to_s
+
+        case node_type
+        when "program"
+          # Root node - signature based on direct children structure
+          child_types = []
+          node.each { |child| child_types << child.type.to_s unless child.type.to_s == "comment" }
+          [:program, child_types.length]
+        when "function_definition"
+          # Functions are identified by their name
+          name = function_name
+          [:function_definition, name]
+        when "variable_assignment"
+          # Variable assignments are identified by variable name
+          name = variable_name
+          [:variable_assignment, name]
+        when "command"
+          # Commands identified by their command name
+          name = command_name
+          [:command, name, extract_command_signature_context(node)]
+        when "if_statement"
+          # If statements identified by their condition pattern
+          condition = extract_condition_pattern(node)
+          [:if_statement, condition]
+        when "for_statement", "c_style_for_statement"
+          # For loops identified by their loop variable
+          var = extract_loop_variable(node)
+          [:for_statement, var]
+        when "while_statement"
+          # While loops identified by condition
+          condition = extract_condition_pattern(node)
+          [:while_statement, condition]
+        when "case_statement"
+          # Case statements identified by the expression being matched
+          expr = extract_case_expression(node)
+          [:case_statement, expr]
+        when "pipeline"
+          # Pipelines identified by command names in order
+          commands = extract_pipeline_commands(node)
+          [:pipeline, commands]
+        when "comment"
+          # Comments identified by their content
+          [:comment, node_text(node).strip]
+        else
+          # Generic fallback - type and first few chars of content
+          content_preview = node_text(node).slice(0, 50).strip
+          [node_type.to_sym, content_preview]
+        end
+      end
+
+      def extract_command_signature_context(node)
+        # Extract additional context like redirections
+        redirections = []
+        node.each do |child|
+          if child.type.to_s.include?("redirect")
+            redirections << child.type.to_s
+          end
+        end
+        redirections.empty? ? nil : redirections.sort
+      end
+
+      def extract_condition_pattern(node)
+        # Try to extract the test/condition from if/while statements
+        # Look for test_command, compound_statement, etc.
+        node.each do |child|
+          if %w[test_command bracket_command].include?(child.type.to_s)
+            return node_text(child).slice(0, 100).strip
+          end
+        end
+        nil
+      end
+
+      def extract_loop_variable(node)
+        # Extract the loop variable from for statements
+        var_node = node.each.find { |child| child.type.to_s == "variable_name" }
+        node_text(var_node) if var_node
+      end
+
+      def extract_case_expression(node)
+        # Extract the expression being matched in a case statement
+        node.each do |child|
+          return node_text(child).slice(0, 50).strip if child.type.to_s == "word" || child.type.to_s == "variable_name"
+        end
+        nil
+      end
+
+      def extract_pipeline_commands(node)
+        # Extract command names from a pipeline
+        commands = []
+        node.each do |child|
+          if child.type.to_s == "command"
+            wrapper = NodeWrapper.new(child, lines: @lines, source: @source)
+            cmd_name = wrapper.command_name
+            commands << cmd_name if cmd_name
+          end
+        end
+        commands
+      end
+    end
+  end
+end

data/lib/bash/merge/smart_merger.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+module Bash
+  module Merge
+    # Main entry point for intelligent Bash script merging.
+    # SmartMerger orchestrates the merge process using FileAnalysis,
+    # ConflictResolver, and MergeResult to merge two Bash scripts intelligently.
+    #
+    # @example Basic merge (destination customizations preserved)
+    #   merger = SmartMerger.new(template_bash, dest_bash)
+    #   result = merger.merge
+    #   File.write("output.sh", result)
+    #
+    # @example Template updates win
+    #   merger = SmartMerger.new(
+    #     template_bash,
+    #     dest_bash,
+    #     preference: :template,
+    #     add_template_only_nodes: true
+    #   )
+    #   result = merger.merge
+    #
+    # @example With custom signature generator
+    #   sig_gen = ->(node) {
+    #     if node.is_a?(NodeWrapper) && node.function_definition? && node.function_name == "main"
+    #       [:special_main]
+    #     else
+    #       node # Fall through to default
+    #     end
+    #   }
+    #   merger = SmartMerger.new(template, dest, signature_generator: sig_gen)
+    #
+    # @example With node_typing for per-node-type preferences
+    #   merger = SmartMerger.new(template, dest,
+    #     node_typing: { "function_definition" => ->(n) { NodeTyping.with_merge_type(n, :func) } },
+    #     preference: { default: :destination, func: :template })
+    class SmartMerger < ::Ast::Merge::SmartMergerBase
+      # Creates a new SmartMerger for intelligent Bash script merging.
+      #
+      # @param template_content [String] Template Bash source code
+      # @param dest_content [String] Destination Bash source code
+      # @param signature_generator [Proc, nil] Custom signature generator
+      # @param preference [Symbol, Hash] :destination, :template, or per-type Hash
+      # @param add_template_only_nodes [Boolean] Whether to add nodes only in template
+      # @param freeze_token [String] Token for freeze block markers
+      # @param match_refiner [#call, nil] Match refiner for fuzzy matching
+      # @param regions [Array<Hash>, nil] Region configurations for nested merging
+      # @param region_placeholder [String, nil] Custom placeholder for regions
+      # @param node_typing [Hash{Symbol,String => #call}, nil] Node typing configuration
+      #
+      # @note To specify a custom parser path, use the TREE_SITTER_BASH_PATH environment
+      #   variable. This is handled by tree_haver's GrammarFinder.
+      # @param options [Hash] Additional options for forward compatibility
+      #
+      # @raise [TemplateParseError] If template has syntax errors
+      # @raise [DestinationParseError] If destination has syntax errors
+      def initialize(
+        template_content,
+        dest_content,
+        signature_generator: nil,
+        preference: :destination,
+        add_template_only_nodes: false,
+        freeze_token: nil,
+        match_refiner: nil,
+        regions: nil,
+        region_placeholder: nil,
+        node_typing: nil,
+        **options
+      )
+        super(
+          template_content,
+          dest_content,
+          signature_generator: signature_generator,
+          preference: preference,
+          add_template_only_nodes: add_template_only_nodes,
+          freeze_token: freeze_token,
+          match_refiner: match_refiner,
+          regions: regions,
+          region_placeholder: region_placeholder,
+          node_typing: node_typing,
+          **options
+        )
+      end
+
+      # Perform the merge and return the result as a Bash string.
+      #
+      # @return [String] Merged Bash content
+      def merge
+        merge_result.to_bash
+      end
+
+      # Perform the merge and return detailed results including debug info.
+      #
+      # @return [Hash] Hash containing :content, :statistics, :decisions
+      def merge_with_debug
+        content = merge
+
+        {
+          content: content,
+          statistics: @result.statistics,
+          decisions: @result.decision_summary,
+          template_analysis: {
+            valid: @template_analysis.valid?,
+            nodes: @template_analysis.nodes.size,
+            freeze_blocks: @template_analysis.freeze_blocks.size,
+          },
+          dest_analysis: {
+            valid: @dest_analysis.valid?,
+            nodes: @dest_analysis.nodes.size,
+            freeze_blocks: @dest_analysis.freeze_blocks.size,
+          },
+        }
+      end
+
+      # Check if both files were parsed successfully.
+      #
+      # @return [Boolean]
+      def valid?
+        @template_analysis.valid? && @dest_analysis.valid?
+      end
+
+      # Get any parse errors from template or destination.
+      #
+      # @return [Array] Array of errors
+      def errors
+        errors = []
+        errors.concat(@template_analysis.errors.map { |e| {source: :template, error: e} })
+        errors.concat(@dest_analysis.errors.map { |e| {source: :destination, error: e} })
+        errors
+      end
+
+      protected
+
+      # @return [Class] The analysis class for Bash files
+      def analysis_class
+        FileAnalysis
+      end
+
+      # @return [String] The default freeze token
+      def default_freeze_token
+        "bash-merge"
+      end
+
+      # @return [Class] The resolver class for Bash files
+      def resolver_class
+        ConflictResolver
+      end
+
+      # @return [Class] The result class for Bash files
+      def result_class
+        MergeResult
+      end
+
+      # @return [Class] The template parse error class for Bash
+      def template_parse_error_class
+        TemplateParseError
+      end
+
+      # @return [Class] The destination parse error class for Bash
+      def destination_parse_error_class
+        DestinationParseError
+      end
+
+      # Perform the Bash-specific merge
+      #
+      # @return [MergeResult] The merge result
+      def perform_merge
+        @resolver.resolve(@result)
+        @result
+      end
+
+      # Build the resolver with Bash-specific options
+      def build_resolver
+        ConflictResolver.new(
+          @template_analysis,
+          @dest_analysis,
+          preference: @preference,
+          add_template_only_nodes: @add_template_only_nodes,
+        )
+      end
+
+      # Build the result (no-arg constructor for Bash)
+      def build_result
+        MergeResult.new
+      end
+    end
+  end
+end

data/lib/bash/merge/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Bash
+  module Merge
+    # Version information for Bash::Merge
+    module Version
+      # Current version of the bash-merge gem
+      VERSION = "1.0.0"
+    end
+    VERSION = Version::VERSION # traditional location
+  end
+end

data/lib/bash/merge.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+# External gems
+# TreeHaver provides a unified cross-Ruby interface to tree-sitter
+require "tree_haver"
+
+# BACKEND COMPATIBILITY for Bash:
+# - FFI: Most portable and reliable with bash grammar (recommended)
+# - MRI: Has ABI incompatibility with bash grammar
+# - Rust: Has version mismatch with bash grammar
+#
+# Set TREE_HAVER_BACKEND=ffi (or mri/rust) to control backend selection.
+# When MRI loads a grammar first, FFI gets incompatible pointers (symbol conflict).
+# MRI statically links tree-sitter, FFI dynamically links libtree-sitter.so.
+
+# Register tree-sitter bash grammar
+bash_finder = TreeHaver::GrammarFinder.new(:bash)
+bash_available = bash_finder.available?
+bash_finder.register! if bash_available
+
+# Only warn if the grammar file is actually missing (not just runtime unavailable)
+# When the runtime isn't available, tree-sitter backends just won't be used,
+# which is expected behavior - no need to warn the user.
+unless bash_available
+  grammar_path = bash_finder.find_library_path
+  unless grammar_path
+    warn "WARNING: Bash grammar not available. #{bash_finder.not_found_message}"
+  end
+end
+
+require "version_gem"
+require "set"
+
+# Shared merge infrastructure
+require "ast/merge"
+
+# This gem
+require_relative "merge/version"
+
+# Bash::Merge provides a generic Bash script smart merge system using tree-sitter AST analysis.
+# It intelligently merges template and destination Bash scripts by identifying matching
+# statements and resolving differences using structural signatures.
+#
+# @example Basic usage
+#   template = File.read("template.sh")
+#   destination = File.read("destination.sh")
+#   merger = Bash::Merge::SmartMerger.new(template, destination)
+#   result = merger.merge
+#
+# @example With debug information
+#   merger = Bash::Merge::SmartMerger.new(template, destination)
+#   debug_result = merger.merge_with_debug
+#   puts debug_result[:content]
+#   puts debug_result[:statistics]
+module Bash
+  # Smart merge system for Bash scripts using tree-sitter AST analysis.
+  # Provides intelligent merging by understanding Bash structure
+  # rather than treating files as plain text.
+  #
+  # @see SmartMerger Main entry point for merge operations
+  # @see FileAnalysis Analyzes Bash structure
+  # @see ConflictResolver Resolves content conflicts
+  module Merge
+    # Base error class for Bash::Merge
+    # Inherits from Ast::Merge::Error for consistency across merge gems.
+    class Error < Ast::Merge::Error; end
+
+    # Raised when a Bash script has parsing errors.
+    # Inherits from Ast::Merge::ParseError for consistency across merge gems.
+    #
+    # @example Handling parse errors
+    #   begin
+    #     analysis = FileAnalysis.new(bash_content)
+    #   rescue ParseError => e
+    #     puts "Bash syntax error: #{e.message}"
+    #     e.errors.each { |error| puts "  #{error}" }
+    #   end
+    class ParseError < Ast::Merge::ParseError
+      # @param message [String, nil] Error message (auto-generated if nil)
+      # @param content [String, nil] The Bash source that failed to parse
+      # @param errors [Array] Parse errors from tree-sitter
+      def initialize(message = nil, content: nil, errors: [])
+        super(message, errors: errors, content: content)
+      end
+    end
+
+    # Raised when the template file has syntax errors.
+    #
+    # @example Handling template parse errors
+    #   begin
+    #     merger = SmartMerger.new(template, destination)
+    #     result = merger.merge
+    #   rescue TemplateParseError => e
+    #     puts "Template syntax error: #{e.message}"
+    #     e.errors.each do |error|
+    #       puts "  #{error.message}"
+    #     end
+    #   end
+    class TemplateParseError < ParseError; end
+
+    # Raised when the destination file has syntax errors.
+    #
+    # @example Handling destination parse errors
+    #   begin
+    #     merger = SmartMerger.new(template, destination)
+    #     result = merger.merge
+    #   rescue DestinationParseError => e
+    #     puts "Destination syntax error: #{e.message}"
+    #     e.errors.each do |error|
+    #       puts "  #{error.message}"
+    #     end
+    #   end
+    class DestinationParseError < ParseError; end
+
+    autoload :CommentTracker, "bash/merge/comment_tracker"
+    autoload :DebugLogger, "bash/merge/debug_logger"
+    autoload :Emitter, "bash/merge/emitter"
+    autoload :FreezeNode, "bash/merge/freeze_node"
+    autoload :FileAnalysis, "bash/merge/file_analysis"
+    autoload :MergeResult, "bash/merge/merge_result"
+    autoload :NodeWrapper, "bash/merge/node_wrapper"
+    autoload :ConflictResolver, "bash/merge/conflict_resolver"
+    autoload :SmartMerger, "bash/merge/smart_merger"
+  end
+end
+
+Bash::Merge::Version.class_eval do
+  extend VersionGem::Basic
+end

data/lib/bash-merge.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# For technical reasons, if we move to Zeitwerk, this cannot be require_relative.
+#   See: https://github.com/fxn/zeitwerk#for_gem_extension
+# Hook for other libraries to load this library (e.g. via bundler)
+require "bash/merge"