bash-merge 1.0.0

data/lib/bash/merge/file_analysis.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+module Bash
+  module Merge
+    # Analyzes Bash script structure, extracting nodes, comments, and freeze blocks.
+    # This is the main analysis class that prepares Bash content for merging.
+    #
+    # @example Basic usage
+    #   analysis = FileAnalysis.new(bash_source)
+    #   analysis.valid? # => true
+    #   analysis.nodes # => [NodeWrapper, FreezeNodeBase, ...]
+    #   analysis.freeze_blocks # => [FreezeNodeBase, ...]
+    class FileAnalysis
+      include Ast::Merge::FileAnalyzable
+
+      # Default freeze token for identifying freeze blocks
+      DEFAULT_FREEZE_TOKEN = "bash-merge"
+
+      # @return [CommentTracker] Comment tracker for this file
+      attr_reader :comment_tracker
+
+      # @return [TreeHaver::Tree, nil] Parsed AST
+      attr_reader :ast
+
+      # @return [Array] Parse errors if any
+      attr_reader :errors
+
+      class << self
+        # Find the parser library path using TreeHaver::GrammarFinder
+        #
+        # @return [String, nil] Path to the parser library or nil if not found
+        # @raise [TreeHaver::NotAvailable] if ENV is set to invalid path
+        def find_parser_path
+          TreeHaver::GrammarFinder.new(:bash).find_library_path
+        end
+      end
+
+      # Initialize file analysis
+      #
+      # @param source [String] Bash source code to analyze
+      # @param freeze_token [String] Token for freeze block markers
+      # @param signature_generator [Proc, nil] Custom signature generator
+      # @param parser_path [String, nil] Path to tree-sitter-bash parser library
+      # @param options [Hash] Additional options (forward compatibility - ignored by FileAnalysis)
+      def initialize(source, freeze_token: DEFAULT_FREEZE_TOKEN, signature_generator: nil, parser_path: nil, **options)
+        @source = source
+        @lines = source.lines.map(&:chomp)
+        @freeze_token = freeze_token
+        @signature_generator = signature_generator
+        @parser_path = parser_path || self.class.find_parser_path
+        @errors = []
+        # **options captures any additional parameters (e.g., node_typing) for forward compatibility
+
+        # Initialize comment tracking
+        @comment_tracker = CommentTracker.new(source)
+
+        # Parse the Bash script
+        DebugLogger.time("FileAnalysis#parse_bash") { parse_bash }
+
+        # Extract freeze blocks and integrate with nodes
+        @freeze_blocks = extract_freeze_blocks
+        @nodes = integrate_nodes_and_freeze_blocks
+
+        DebugLogger.debug("FileAnalysis initialized", {
+          signature_generator: signature_generator ? "custom" : "default",
+          nodes_count: @nodes.size,
+          freeze_blocks: @freeze_blocks.size,
+          valid: valid?,
+        })
+      end
+
+      # Check if parse was successful
+      # @return [Boolean]
+      def valid?
+        @errors.empty? && !@ast.nil?
+      end
+
+      # The base module uses 'statements' - provide both names for compatibility
+      # @return [Array<NodeWrapper, FreezeNodeBase>]
+      def statements
+        @nodes ||= []
+      end
+
+      # Alias for convenience - bash-merge prefers "nodes" terminology
+      alias_method :nodes, :statements
+
+      # Check if a line is within a freeze block.
+      #
+      # @param line_num [Integer] 1-based line number
+      # @return [Boolean]
+      def in_freeze_block?(line_num)
+        @freeze_blocks.any? { |fb| fb.location.cover?(line_num) }
+      end
+
+      # Get the freeze block containing the given line.
+      #
+      # @param line_num [Integer] 1-based line number
+      # @return [FreezeNode, nil]
+      def freeze_block_at(line_num)
+        @freeze_blocks.find { |fb| fb.location.cover?(line_num) }
+      end
+
+      # Override to detect tree-sitter nodes for signature generator fallthrough
+      # @param value [Object] The value to check
+      # @return [Boolean] true if this is a fallthrough node
+      def fallthrough_node?(value)
+        value.is_a?(NodeWrapper) || value.is_a?(FreezeNode) || super
+      end
+
+      # Get the root node of the parse tree
+      # @return [NodeWrapper, nil]
+      def root_node
+        return unless valid?
+
+        NodeWrapper.new(@ast.root_node, lines: @lines, source: @source)
+      end
+
+      # Get top-level statements from the script
+      # @return [Array<NodeWrapper>]
+      def top_level_statements
+        return [] unless valid?
+
+        root = @ast.root_node
+        return [] unless root
+
+        statements = []
+        root.each do |child|
+          next if child.type.to_s == "comment" # Comments handled separately
+
+          statements << NodeWrapper.new(child, lines: @lines, source: @source)
+        end
+        statements
+      end
+
+      private
+
+      def parse_bash
+        # TreeHaver handles grammar discovery and backend selection
+        # Set TREE_HAVER_BACKEND=ffi for bash (MRI/Rust have compatibility issues)
+        parser = TreeHaver.parser_for(:bash, library_path: @parser_path)
+        @ast = parser.parse(@source)
+
+        # Check for parse errors in the tree
+        if @ast&.root_node&.has_error?
+          collect_parse_errors(@ast.root_node)
+        end
+      rescue TreeHaver::NotAvailable => e
+        @errors << e.message
+        @ast = nil
+      rescue StandardError => e
+        @errors << e.message
+        @ast = nil
+      end
+
+      def collect_parse_errors(node)
+        # Collect ERROR and MISSING nodes from the tree
+        if node.type.to_s == "ERROR" || node.missing?
+          @errors << {
+            type: node.type.to_s,
+            start_point: node.start_point,
+            end_point: node.end_point,
+            text: node.to_s,
+          }
+        end
+
+        node.each { |child| collect_parse_errors(child) }
+      end
+
+      def extract_freeze_blocks
+        # Use shared pattern from Ast::Merge::FreezeNodeBase with our specific token
+        freeze_pattern = Ast::Merge::FreezeNodeBase.pattern_for(:hash_comment, @freeze_token)
+
+        freeze_starts = []
+        freeze_ends = []
+
+        @lines.each_with_index do |line, idx|
+          line_num = idx + 1
+          next unless (match = line.match(freeze_pattern))
+
+          marker_type = match[1]&.downcase # 'freeze' or 'unfreeze'
+          if marker_type == "freeze"
+            freeze_starts << {line: line_num, marker: line}
+          elsif marker_type == "unfreeze"
+            freeze_ends << {line: line_num, marker: line}
+          end
+        end
+
+        # Match freeze starts with ends
+        blocks = []
+        freeze_starts.each do |start_info|
+          # Find the next unfreeze after this freeze
+          matching_end = freeze_ends.find { |e| e[:line] > start_info[:line] }
+          next unless matching_end
+
+          # Remove used end marker
+          freeze_ends.delete(matching_end)
+
+          blocks << FreezeNode.new(
+            start_line: start_info[:line],
+            end_line: matching_end[:line],
+            lines: @lines,
+            start_marker: start_info[:marker],
+            end_marker: matching_end[:marker],
+          )
+        end
+
+        blocks
+      end
+
+      def integrate_nodes_and_freeze_blocks
+        return @freeze_blocks.dup unless valid?
+
+        result = []
+        processed_lines = ::Set.new
+
+        # Mark freeze block lines as processed
+        @freeze_blocks.each do |fb|
+          (fb.start_line..fb.end_line).each { |ln| processed_lines << ln }
+          result << fb
+        end
+
+        # Add top-level statements that aren't in freeze blocks
+        top_level_statements.each do |stmt|
+          next unless stmt.start_line && stmt.end_line
+
+          # Skip if any part of this statement is in a freeze block
+          stmt_lines = (stmt.start_line..stmt.end_line).to_a
+          next if stmt_lines.any? { |ln| processed_lines.include?(ln) }
+
+          result << stmt
+        end
+
+        # Sort by start line
+        result.sort_by { |node| node.start_line || 0 }
+      end
+
+      def compute_node_signature(node)
+        case node
+        when FreezeNode
+          node.signature
+        when NodeWrapper
+          node.signature
+        end
+      end
+    end
+  end
+end

data/lib/bash/merge/freeze_node.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module Bash
+  module Merge
+    # Wrapper to represent freeze blocks as first-class nodes in Bash scripts.
+    # A freeze block is a section marked with freeze/unfreeze comment markers that
+    # should be preserved from the destination during merges.
+    #
+    # Inherits from Ast::Merge::FreezeNodeBase for shared functionality including
+    # the Location struct, InvalidStructureError, and configurable marker patterns.
+    #
+    # Uses the `:hash_comment` pattern type by default for Bash files (# comments).
+    #
+    # @example Freeze block in Bash
+    #   # bash-merge:freeze
+    #   SECRET_KEY="my-secret-value"
+    #   API_ENDPOINT="https://custom.example.com"
+    #   # bash-merge:unfreeze
+    class FreezeNode < Ast::Merge::FreezeNodeBase
+      # Inherit InvalidStructureError from base class
+      InvalidStructureError = Ast::Merge::FreezeNodeBase::InvalidStructureError
+
+      # Inherit Location from base class
+      Location = Ast::Merge::FreezeNodeBase::Location
+
+      # @param start_line [Integer] Line number of freeze marker
+      # @param end_line [Integer] Line number of unfreeze marker
+      # @param lines [Array<String>] All source lines
+      # @param start_marker [String, nil] The freeze start marker text
+      # @param end_marker [String, nil] The freeze end marker text
+      # @param pattern_type [Symbol] Pattern type for marker matching (defaults to :hash_comment)
+      def initialize(start_line:, end_line:, lines:, start_marker: nil, end_marker: nil, pattern_type: Ast::Merge::FreezeNodeBase::DEFAULT_PATTERN)
+        # Extract lines for the entire block (lines param is all source lines)
+        block_lines = (start_line..end_line).map { |ln| lines[ln - 1] }
+
+        super(
+          start_line: start_line,
+          end_line: end_line,
+          lines: block_lines,
+          start_marker: start_marker,
+          end_marker: end_marker,
+          pattern_type: pattern_type
+        )
+
+        validate_structure!
+      end
+
+      # Returns a stable signature for this freeze block.
+      # Signature includes the normalized content to detect changes.
+      # @return [Array] Signature array
+      def signature
+        # Normalize by stripping each line and joining
+        normalized = @lines.map { |l| l&.strip }.compact.reject(&:empty?).join("\n")
+        [:FreezeNode, normalized]
+      end
+
+      # Check if this is a function definition (always false for FreezeNode)
+      # @return [Boolean]
+      def function_definition?
+        false
+      end
+
+      # Check if this is a variable assignment (always false for FreezeNode)
+      # @return [Boolean]
+      def variable_assignment?
+        false
+      end
+
+      # Check if this is a command (always false for FreezeNode)
+      # @return [Boolean]
+      def command?
+        false
+      end
+
+      # String representation for debugging
+      # @return [String]
+      def inspect
+        # :nocov:
+        # Defensive: slice is always set via resolve_content in FreezeNodeBase#initialize
+        # The || 0 branch is normally unreachable because validate_structure! ensures non-empty content
+        content_length = slice&.length || 0
+        # :nocov:
+        "#<#{self.class.name} lines=#{start_line}..#{end_line} content_length=#{content_length}>"
+      end
+
+      private
+
+      def validate_structure!
+        validate_line_order!
+
+        if @lines.empty? || @lines.all?(&:nil?)
+          raise InvalidStructureError.new(
+            "Freeze block is empty",
+            start_line: @start_line,
+            end_line: @end_line,
+          )
+        end
+      end
+    end
+  end
+end

data/lib/bash/merge/merge_result.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Bash
+  module Merge
+    # Tracks the result of a merge operation, including the merged content,
+    # decisions made, and statistics.
+    #
+    # Inherits decision constants and base functionality from Ast::Merge::MergeResultBase.
+    #
+    # @example Basic usage
+    #   result = MergeResult.new
+    #   result.add_line("echo 'hello'", decision: :kept_template, source: :template)
+    #   result.to_bash # => "echo 'hello'\n"
+    class MergeResult < Ast::Merge::MergeResultBase
+      # Inherit decision constants from base class
+      DECISION_KEPT_TEMPLATE = Ast::Merge::MergeResultBase::DECISION_KEPT_TEMPLATE
+      DECISION_KEPT_DEST = Ast::Merge::MergeResultBase::DECISION_KEPT_DEST
+      DECISION_MERGED = Ast::Merge::MergeResultBase::DECISION_MERGED
+      DECISION_ADDED = Ast::Merge::MergeResultBase::DECISION_ADDED
+      DECISION_FREEZE_BLOCK = Ast::Merge::MergeResultBase::DECISION_FREEZE_BLOCK
+
+      # @return [Hash] Statistics about the merge
+      attr_reader :statistics
+
+      # Initialize a new merge result
+      # @param options [Hash] Additional options for forward compatibility
+      def initialize(**options)
+        super(**options)
+        @statistics = {
+          template_lines: 0,
+          dest_lines: 0,
+          merged_lines: 0,
+          freeze_preserved_lines: 0,
+          total_decisions: 0,
+        }
+      end
+
+      # Add a single line to the result
+      #
+      # @param line [String] Line content
+      # @param decision [Symbol] Decision that led to this line
+      # @param source [Symbol] Source of the line (:template, :destination, :merged)
+      # @param original_line [Integer, nil] Original line number
+      def add_line(line, decision:, source:, original_line: nil)
+        @lines << {
+          content: line,
+          decision: decision,
+          source: source,
+          original_line: original_line,
+        }
+
+        track_statistics(decision, source)
+        track_decision(decision, source, line: original_line)
+      end
+
+      # Add multiple lines to the result
+      #
+      # @param lines [Array<String>] Lines to add
+      # @param decision [Symbol] Decision for all lines
+      # @param source [Symbol] Source of the lines
+      # @param start_line [Integer, nil] Starting original line number
+      def add_lines(lines, decision:, source:, start_line: nil)
+        lines.each_with_index do |line, idx|
+          original_line = start_line ? start_line + idx : nil
+          add_line(line, decision: decision, source: source, original_line: original_line)
+        end
+      end
+
+      # Add a blank line
+      #
+      # @param decision [Symbol] Decision for the blank line
+      # @param source [Symbol] Source
+      def add_blank_line(decision: DECISION_MERGED, source: :merged)
+        add_line("", decision: decision, source: source)
+      end
+
+      # Add content from a freeze block
+      #
+      # @param freeze_node [FreezeNode] Freeze block to add
+      def add_freeze_block(freeze_node)
+        freeze_node.lines.each_with_index do |line, idx|
+          add_line(
+            line.chomp,
+            decision: DECISION_FREEZE_BLOCK,
+            source: :destination,
+            original_line: freeze_node.start_line + idx,
+          )
+        end
+      end
+
+      # Add content from a node wrapper
+      #
+      # @param node [NodeWrapper] Node to add
+      # @param decision [Symbol] Decision that led to keeping this node
+      # @param source [Symbol] Source of the node
+      # @param analysis [FileAnalysis] Analysis for accessing source lines
+      def add_node(node, decision:, source:, analysis:)
+        return unless node.start_line && node.end_line
+
+        (node.start_line..node.end_line).each do |line_num|
+          line = analysis.line_at(line_num)
+          next unless line
+
+          add_line(line.chomp, decision: decision, source: source, original_line: line_num)
+        end
+      end
+
+      # Get the merged content as a Bash string
+      #
+      # @return [String]
+      def to_bash
+        content = @lines.map { |l| l[:content] }.join("\n")
+        # Ensure trailing newline
+        content += "\n" unless content.end_with?("\n") || content.empty?
+        content
+      end
+
+      # Alias for to_bash
+      # @return [String]
+      def content
+        to_bash
+      end
+
+      private
+
+      def track_statistics(decision, source)
+        @statistics[:total_decisions] += 1
+
+        case decision
+        when DECISION_KEPT_TEMPLATE
+          @statistics[:template_lines] += 1
+        when DECISION_KEPT_DEST
+          @statistics[:dest_lines] += 1
+        when DECISION_FREEZE_BLOCK
+          @statistics[:freeze_preserved_lines] += 1
+        else
+          @statistics[:merged_lines] += 1
+        end
+      end
+    end
+  end
+end