bash-merge 1.0.0

data/RUBOCOP.md

@@ -0,0 +1,71 @@
+# RuboCop Usage Guide
+
+## Overview
+
+A tale of two RuboCop plugin gems.
+
+### RuboCop Gradual
+
+This project uses `rubocop_gradual` instead of vanilla RuboCop for code style checking. The `rubocop_gradual` tool allows for gradual adoption of RuboCop rules by tracking violations in a lock file.
+
+### RuboCop LTS
+
+This project uses `rubocop-lts` to ensure, on a best-effort basis, compatibility with Ruby >= 1.9.2.
+RuboCop rules are meticulously configured by the `rubocop-lts` family of gems to ensure that a project is compatible with a specific version of Ruby. See: https://rubocop-lts.gitlab.io for more.
+
+## Checking RuboCop Violations
+
+To check for RuboCop violations in this project, always use:
+
+```bash
+bundle exec rake rubocop_gradual:check
+```
+
+**Do not use** the standard RuboCop commands like:
+- `bundle exec rubocop`
+- `rubocop`
+
+## Understanding the Lock File
+
+The `.rubocop_gradual.lock` file tracks all current RuboCop violations in the project. This allows the team to:
+
+1. Prevent new violations while gradually fixing existing ones
+2. Track progress on code style improvements
+3. Ensure CI builds don't fail due to pre-existing violations
+
+## Common Commands
+
+- **Check violations**
+    - `bundle exec rake rubocop_gradual`
+    - `bundle exec rake rubocop_gradual:check`
+- **(Safe) Autocorrect violations, and update lockfile if no new violations**
+  - `bundle exec rake rubocop_gradual:autocorrect`
+- **Force update the lock file (w/o autocorrect) to match violations present in code**
+  - `bundle exec rake rubocop_gradual:force_update`
+
+## Workflow
+
+1. Before submitting a PR, run `bundle exec rake rubocop_gradual:autocorrect`
+   a. or just the default `bundle exec rake`, as autocorrection is a pre-requisite of the default task.
+2. If there are new violations, either:
+   - Fix them in your code
+   - Run `bundle exec rake rubocop_gradual:force_update` to update the lock file (only for violations you can't fix immediately)
+3. Commit the updated `.rubocop_gradual.lock` file along with your changes
+
+## Never add inline RuboCop disables
+
+Do not add inline `rubocop:disable` / `rubocop:enable` comments anywhere in the codebase (including specs, except when following the few existing `rubocop:disable` patterns for a rule already being disabled elsewhere in the code). We handle exceptions in two supported ways:
+
+- Permanent/structural exceptions: prefer adjusting the RuboCop configuration (e.g., in `.rubocop.yml`) to exclude a rule for a path or file pattern when it makes sense project-wide.
+- Temporary exceptions while improving code: record the current violations in `.rubocop_gradual.lock` via the gradual workflow:
+  - `bundle exec rake rubocop_gradual:autocorrect` (preferred; will autocorrect what it can and update the lock only if no new violations were introduced)
+  - If needed, `bundle exec rake rubocop_gradual:force_update` (as a last resort when you cannot fix the newly reported violations immediately)
+
+In general, treat the rules as guidance to follow; fix violations rather than ignore them. For example, RSpec conventions in this project expect `described_class` to be used in specs that target a specific class under test.
+
+## Benefits of rubocop_gradual
+
+- Allows incremental adoption of code style rules
+- Prevents CI failures due to pre-existing violations
+- Provides a clear record of code style debt
+- Enables focused efforts on improving code quality over time

data/SECURITY.md

@@ -0,0 +1,21 @@
+# Security Policy
+
+## Supported Versions
+
+| Version  | Supported |
+|----------|-----------|
+| 1.latest | ✅         |
+
+## Security contact information
+
+To report a security vulnerability, please use the
+[Tidelift security contact](https://tidelift.com/security).
+Tidelift will coordinate the fix and disclosure.
+
+## Additional Support
+
+If you are interested in support for versions older than the latest release,
+please consider sponsoring the project / maintainer @ https://liberapay.com/pboling/donate,
+or find other sponsorship links in the [README].
+
+[README]: README.md

data/lib/bash/merge/comment_tracker.rb

@@ -0,0 +1,153 @@
+# frozen_string_literal: true
+
+module Bash
+  module Merge
+    # Extracts and tracks comments with their line numbers from Bash source.
+    # Bash comments use the # syntax, making freeze block detection straightforward.
+    #
+    # @example Basic usage
+    #   tracker = CommentTracker.new(bash_source)
+    #   tracker.comments # => [{line: 1, indent: 0, text: "This is a comment"}]
+    #   tracker.comment_at(1) # => {line: 1, indent: 0, text: "This is a comment"}
+    #
+    # @example Comment types
+    #   # Full-line comment
+    #   command # Inline comment
+    class CommentTracker
+      # Regex to match full-line comments (line is only whitespace + comment)
+      FULL_LINE_COMMENT_REGEX = /\A(\s*)#\s?(.*)\z/
+
+      # Regex to match inline comments (comment after Bash content)
+      # Note: This is simplified and doesn't handle all edge cases like comments in strings
+      INLINE_COMMENT_REGEX = /\s+#\s?(.*)$/
+
+      # @return [Array<Hash>] All extracted comments with metadata
+      attr_reader :comments
+
+      # @return [Array<String>] Source lines
+      attr_reader :lines
+
+      # Initialize comment tracker by scanning the source
+      #
+      # @param source [String] Bash source code
+      def initialize(source)
+        @source = source
+        @lines = source.lines.map(&:chomp)
+        @comments = extract_comments
+        @comments_by_line = @comments.group_by { |c| c[:line] }
+      end
+
+      # Get comment at a specific line
+      #
+      # @param line_num [Integer] 1-based line number
+      # @return [Hash, nil] Comment info or nil
+      def comment_at(line_num)
+        @comments_by_line[line_num]&.first
+      end
+
+      # Get all comments in a line range
+      #
+      # @param range [Range] Range of 1-based line numbers
+      # @return [Array<Hash>] Comments in the range
+      def comments_in_range(range)
+        @comments.select { |c| range.cover?(c[:line]) }
+      end
+
+      # Get leading comments before a line (consecutive comment lines immediately above)
+      #
+      # @param line_num [Integer] 1-based line number
+      # @return [Array<Hash>] Leading comments
+      def leading_comments_before(line_num)
+        leading = []
+        current = line_num - 1
+
+        while current >= 1
+          comment = comment_at(current)
+          break unless comment && comment[:full_line]
+
+          leading.unshift(comment)
+          current -= 1
+        end
+
+        leading
+      end
+
+      # Get trailing comment on the same line (inline comment)
+      #
+      # @param line_num [Integer] 1-based line number
+      # @return [Hash, nil] Inline comment or nil
+      def inline_comment_at(line_num)
+        comment = comment_at(line_num)
+        comment if comment && !comment[:full_line]
+      end
+
+      # Check if a line is a full-line comment
+      #
+      # @param line_num [Integer] 1-based line number
+      # @return [Boolean]
+      def full_line_comment?(line_num)
+        comment = comment_at(line_num)
+        comment&.dig(:full_line) || false
+      end
+
+      # Check if a line is blank
+      #
+      # @param line_num [Integer] 1-based line number
+      # @return [Boolean]
+      def blank_line?(line_num)
+        return false if line_num < 1 || line_num > @lines.length
+
+        @lines[line_num - 1].strip.empty?
+      end
+
+      # Check if a line is a shebang
+      #
+      # @param line_num [Integer] 1-based line number
+      # @return [Boolean]
+      def shebang?(line_num)
+        return false if line_num < 1 || line_num > @lines.length
+
+        @lines[line_num - 1].start_with?("#!")
+      end
+
+      private
+
+      def extract_comments
+        comments = []
+
+        @lines.each_with_index do |line, idx|
+          line_num = idx + 1
+
+          # Skip shebang lines
+          next if line.start_with?("#!")
+
+          # Check for full-line comment
+          if (match = line.match(FULL_LINE_COMMENT_REGEX))
+            comments << {
+              line: line_num,
+              indent: match[1].length,
+              text: match[2],
+              full_line: true,
+              raw: line,
+            }
+          # Check for inline comment (simplified - doesn't handle quotes)
+          elsif line.include?(" #") && !line.strip.start_with?("#")
+            # Try to extract inline comment, but be careful with strings
+            # This is a simplified approach
+            if (inline_match = line.match(INLINE_COMMENT_REGEX))
+              comments << {
+                line: line_num,
+                indent: 0,
+                text: inline_match[1],
+                full_line: false,
+                raw: "# #{inline_match[1]}",
+              }
+            end
+          end
+        end
+
+        comments
+      end
+    end
+  end
+end

data/lib/bash/merge/conflict_resolver.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Bash
+  module Merge
+    # Resolves conflicts between template and destination Bash content
+    # using structural signatures and configurable preferences.
+    #
+    # @example Basic usage
+    #   resolver = ConflictResolver.new(template_analysis, dest_analysis)
+    #   resolver.resolve(result)
+    class ConflictResolver < ::Ast::Merge::ConflictResolverBase
+      # Alias for backward compatibility with existing API
+      alias_method :preference, :preference
+
+      # Creates a new ConflictResolver
+      #
+      # @param template_analysis [FileAnalysis] Analyzed template file
+      # @param dest_analysis [FileAnalysis] Analyzed destination file
+      # @param preference [Symbol] Which version to prefer when
+      #   nodes have matching signatures:
+      #   - :destination (default) - Keep destination version (customizations)
+      #   - :template - Use template version (updates)
+      # @param add_template_only_nodes [Boolean] Whether to add nodes only in template
+      # @param match_refiner [#call, nil] Optional match refiner for fuzzy matching
+      # @param options [Hash] Additional options for forward compatibility
+      def initialize(template_analysis, dest_analysis, preference: :destination, add_template_only_nodes: false, match_refiner: nil, **options)
+        super(
+          strategy: :batch,
+          preference: preference,
+          template_analysis: template_analysis,
+          dest_analysis: dest_analysis,
+          add_template_only_nodes: add_template_only_nodes,
+          match_refiner: match_refiner,
+          **options
+        )
+      end
+
+      # Resolve conflicts and populate the result
+      #
+      # @param result [MergeResult] Result object to populate
+      def resolve(result)
+        DebugLogger.time("ConflictResolver#resolve") do
+          template_nodes = @template_analysis.nodes
+          dest_nodes = @dest_analysis.nodes
+
+          # Build signature maps
+          template_by_sig = build_signature_map(template_nodes, @template_analysis)
+          dest_by_sig = build_signature_map(dest_nodes, @dest_analysis)
+
+          # Track which nodes have been processed
+          processed_template_sigs = ::Set.new
+          processed_dest_sigs = ::Set.new
+
+          # Process nodes in order, preferring destination order when nodes match
+          merge_nodes(
+            template_nodes,
+            dest_nodes,
+            template_by_sig,
+            dest_by_sig,
+            processed_template_sigs,
+            processed_dest_sigs,
+            result,
+          )
+
+          DebugLogger.debug("Conflict resolution complete", {
+            template_nodes: template_nodes.size,
+            dest_nodes: dest_nodes.size,
+            result_lines: result.line_count,
+          })
+        end
+      end
+
+      private
+
+      def merge_nodes(template_nodes, dest_nodes, template_by_sig, dest_by_sig, processed_template_sigs, processed_dest_sigs, result)
+        # Determine the output order based on preference
+        # We'll iterate through destination nodes first (to preserve dest order for matches)
+        # then add any template-only nodes if configured
+
+        # First pass: Process destination nodes and find matches
+        dest_nodes.each do |dest_node|
+          dest_sig = @dest_analysis.generate_signature(dest_node)
+
+          # Freeze blocks from destination are always preserved
+          if freeze_node?(dest_node)
+            add_node_to_result(dest_node, result, :destination, DECISION_FREEZE_BLOCK)
+            processed_dest_sigs << dest_sig if dest_sig
+            next
+          end
+
+          if dest_sig && template_by_sig[dest_sig]
+            # Found matching node in template
+            template_info = template_by_sig[dest_sig].first
+            template_node = template_info[:node]
+
+            # Decide which to keep based on preference
+            if @preference == :destination
+              add_node_to_result(dest_node, result, :destination, DECISION_KEPT_DEST)
+            else
+              add_node_to_result(template_node, result, :template, DECISION_KEPT_TEMPLATE)
+            end
+
+            processed_dest_sigs << dest_sig
+            processed_template_sigs << dest_sig
+          else
+            # Destination-only node - always keep
+            add_node_to_result(dest_node, result, :destination, DECISION_KEPT_DEST)
+            processed_dest_sigs << dest_sig if dest_sig
+          end
+        end
+
+        # Second pass: Add template-only nodes if configured
+        return unless @add_template_only_nodes
+
+        template_nodes.each do |template_node|
+          template_sig = @template_analysis.generate_signature(template_node)
+
+          # Skip if already processed (matched with dest)
+          next if template_sig && processed_template_sigs.include?(template_sig)
+
+          # Skip freeze blocks from template (they shouldn't exist, but just in case)
+          next if freeze_node?(template_node)
+
+          # Add template-only node
+          add_node_to_result(template_node, result, :template, DECISION_ADDED)
+          processed_template_sigs << template_sig if template_sig
+        end
+      end
+
+      def add_node_to_result(node, result, source, decision)
+        if freeze_node?(node)
+          result.add_freeze_block(node)
+        elsif node.is_a?(NodeWrapper)
+          add_wrapper_to_result(node, result, source, decision)
+        else
+          DebugLogger.debug("Unknown node type", {node_type: node.class.name})
+        end
+      end
+
+      def add_wrapper_to_result(wrapper, result, source, decision)
+        return unless wrapper.start_line && wrapper.end_line
+
+        analysis = (source == :template) ? @template_analysis : @dest_analysis
+
+        # Include leading comments
+        leading = analysis.comment_tracker.leading_comments_before(wrapper.start_line)
+        leading.each do |comment|
+          result.add_line(comment[:raw], decision: decision, source: source, original_line: comment[:line])
+        end
+
+        # Add the node content
+        (wrapper.start_line..wrapper.end_line).each do |line_num|
+          line = analysis.line_at(line_num)
+          next unless line
+
+          result.add_line(line.chomp, decision: decision, source: source, original_line: line_num)
+        end
+      end
+    end
+  end
+end

data/lib/bash/merge/debug_logger.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module Bash
+  module Merge
+    # Debug logging utility for Bash::Merge.
+    # Extends the base Ast::Merge::DebugLogger with Bash-specific configuration.
+    #
+    # @example Enable debug logging
+    #   ENV['BASH_MERGE_DEBUG'] = '1'
+    #   DebugLogger.debug("Processing node", {type: "function_definition", line: 5})
+    #
+    # @example Disable debug logging (default)
+    #   DebugLogger.debug("This won't be printed", {})
+    module DebugLogger
+      extend Ast::Merge::DebugLogger
+
+      # Bash-specific configuration
+      self.env_var_name = "BASH_MERGE_DEBUG"
+      self.log_prefix = "[Bash::Merge]"
+
+      class << self
+        # Override log_node to handle Bash-specific node types.
+        #
+        # @param node [Object] Node to log information about
+        # @param label [String] Label for the node
+        def log_node(node, label: "Node")
+          return unless enabled?
+
+          info = case node
+          when Bash::Merge::FreezeNode
+            {type: "FreezeNode", lines: "#{node.start_line}..#{node.end_line}"}
+          when Bash::Merge::NodeWrapper
+            {type: node.type.to_s, lines: "#{node.start_line}..#{node.end_line}"}
+          else
+            extract_node_info(node)
+          end
+
+          debug(label, info)
+        end
+      end
+    end
+  end
+end

data/lib/bash/merge/emitter.rb

@@ -0,0 +1,218 @@
+# frozen_string_literal: true
+
+module Bash
+  module Merge
+    # Custom Bash emitter that preserves comments and formatting.
+    # This class provides utilities for emitting Bash while maintaining
+    # the original structure, comments, and style choices.
+    #
+    # @example Basic usage
+    #   emitter = Emitter.new
+    #   emitter.emit_comment("This is a comment")
+    #   emitter.emit_line("echo 'hello'")
+    class Emitter
+      # @return [Array<String>] Output lines
+      attr_reader :lines
+
+      # @return [Integer] Current indentation level
+      attr_reader :indent_level
+
+      # @return [Integer] Spaces per indent level
+      attr_reader :indent_size
+
+      # Initialize a new emitter
+      #
+      # @param indent_size [Integer] Number of spaces per indent level
+      def initialize(indent_size: 2)
+        @lines = []
+        @indent_level = 0
+        @indent_size = indent_size
+      end
+
+      # Emit a comment line
+      #
+      # @param text [String] Comment text (without #)
+      # @param inline [Boolean] Whether this is an inline comment
+      def emit_comment(text, inline: false)
+        if inline
+          # Inline comments are appended to the last line
+          return if @lines.empty?
+
+          @lines[-1] = "#{@lines[-1]} # #{text}"
+        else
+          @lines << "#{current_indent}# #{text}"
+        end
+      end
+
+      # Emit leading comments
+      #
+      # @param comments [Array<Hash>] Comment hashes from CommentTracker
+      def emit_leading_comments(comments)
+        comments.each do |comment|
+          # Preserve original indentation from comment
+          indent = " " * (comment[:indent] || 0)
+          @lines << "#{indent}# #{comment[:text]}"
+        end
+      end
+
+      # Emit a blank line
+      def emit_blank_line
+        @lines << ""
+      end
+
+      # Emit a shebang line
+      #
+      # @param interpreter [String] Interpreter path (e.g., "/bin/bash")
+      def emit_shebang(interpreter = "/bin/bash")
+        @lines << "#!#{interpreter}"
+      end
+
+      # Emit a variable assignment
+      #
+      # @param name [String] Variable name
+      # @param value [String] Variable value
+      # @param export [Boolean] Whether to export the variable
+      # @param inline_comment [String, nil] Optional inline comment
+      def emit_variable_assignment(name, value, export: false, inline_comment: nil)
+        prefix = export ? "export " : ""
+        line = "#{current_indent}#{prefix}#{name}=#{value}"
+        line += " # #{inline_comment}" if inline_comment
+        @lines << line
+      end
+
+      # Emit a function definition start
+      #
+      # @param name [String] Function name
+      def emit_function_start(name)
+        @lines << "#{current_indent}#{name}() {"
+        @indent_level += 1
+      end
+
+      # Emit a function definition end
+      def emit_function_end
+        @indent_level -= 1 if @indent_level > 0
+        @lines << "#{current_indent}}"
+      end
+
+      # Emit an if statement start
+      #
+      # @param condition [String] Condition expression
+      def emit_if_start(condition)
+        @lines << "#{current_indent}if #{condition}; then"
+        @indent_level += 1
+      end
+
+      # Emit an elif clause
+      #
+      # @param condition [String] Condition expression
+      def emit_elif(condition)
+        @indent_level -= 1 if @indent_level > 0
+        @lines << "#{current_indent}elif #{condition}; then"
+        @indent_level += 1
+      end
+
+      # Emit an else clause
+      def emit_else
+        @indent_level -= 1 if @indent_level > 0
+        @lines << "#{current_indent}else"
+        @indent_level += 1
+      end
+
+      # Emit an if statement end
+      def emit_fi
+        @indent_level -= 1 if @indent_level > 0
+        @lines << "#{current_indent}fi"
+      end
+
+      # Emit a for loop start
+      #
+      # @param var [String] Loop variable name
+      # @param items [String] Items to iterate over
+      def emit_for_start(var, items)
+        @lines << "#{current_indent}for #{var} in #{items}; do"
+        @indent_level += 1
+      end
+
+      # Emit a for loop end
+      def emit_done
+        @indent_level -= 1 if @indent_level > 0
+        @lines << "#{current_indent}done"
+      end
+
+      # Emit a while loop start
+      #
+      # @param condition [String] Condition expression
+      def emit_while_start(condition)
+        @lines << "#{current_indent}while #{condition}; do"
+        @indent_level += 1
+      end
+
+      # Emit a case statement start
+      #
+      # @param expression [String] Expression to match
+      def emit_case_start(expression)
+        @lines << "#{current_indent}case #{expression} in"
+        @indent_level += 1
+      end
+
+      # Emit a case pattern
+      #
+      # @param pattern [String] Pattern to match
+      def emit_case_pattern(pattern)
+        @lines << "#{current_indent}#{pattern})"
+        @indent_level += 1
+      end
+
+      # Emit a case pattern terminator
+      def emit_case_pattern_end
+        @indent_level -= 1 if @indent_level > 0
+        @lines << "#{current_indent};;"
+      end
+
+      # Emit a case statement end
+      def emit_esac
+        @indent_level -= 1 if @indent_level > 0
+        @lines << "#{current_indent}esac"
+      end
+
+      # Emit a raw line of code
+      #
+      # @param line [String] Line to emit
+      def emit_line(line)
+        @lines << "#{current_indent}#{line}"
+      end
+
+      # Emit raw lines (for preserving existing content)
+      #
+      # @param raw_lines [Array<String>] Lines to emit as-is
+      def emit_raw_lines(raw_lines)
+        raw_lines.each { |line| @lines << line.chomp }
+      end
+
+      # Get the output as a single string
+      #
+      # @return [String]
+      def to_bash
+        content = @lines.join("\n")
+        content += "\n" unless content.empty? || content.end_with?("\n")
+        content
+      end
+
+      # Alias for consistency with other merge gems
+      # @return [String]
+      alias_method :to_s, :to_bash
+
+      # Clear the output
+      def clear
+        @lines = []
+        @indent_level = 0
+      end
+
+      private
+
+      def current_indent
+        " " * (@indent_level * @indent_size)
+      end
+    end
+  end
+end