ast-merge 1.0.0

data/lib/ast/merge/text/file_analysis.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require_relative "line_node"
+require_relative "word_node"
+
+module Ast
+  module Merge
+    module Text
+      # Text file analysis class for the text-based AST.
+      #
+      # This class parses plain text files into a simple AST structure where:
+      # - Top-level nodes are LineNodes (one per line)
+      # - Nested nodes are WordNodes (words within each line, split on word boundaries)
+      #
+      # This provides a minimal AST implementation that can be used to test
+      # the merge infrastructure with any text-based content.
+      #
+      # @example Basic usage
+      #   analysis = FileAnalysis.new("Hello world\nGoodbye world")
+      #   analysis.statements.size  # => 2
+      #   analysis.statements[0].words.size  # => 2
+      #
+      # @example With freeze blocks
+      #   content = <<~TEXT
+      #     Line one
+      #     # text-merge:freeze
+      #     Frozen content
+      #     # text-merge:unfreeze
+      #     Line four
+      #   TEXT
+      #   analysis = FileAnalysis.new(content, freeze_token: "text-merge")
+      #   analysis.freeze_blocks.size  # => 1
+      class FileAnalysis
+        include FileAnalyzable
+
+        # Default freeze token for text files
+        DEFAULT_FREEZE_TOKEN = "text-merge"
+
+        # Initialize a new FileAnalysis
+        #
+        # @param source [String] Source text content
+        # @param freeze_token [String] Token for freeze block markers
+        # @param signature_generator [Proc, nil] Custom signature generator
+        def initialize(source, freeze_token: DEFAULT_FREEZE_TOKEN, signature_generator: nil)
+          @source = source
+          # Split preserving empty lines, but remove trailing empty line from final newline
+          @lines = source.split("\n", -1)
+          @lines.pop if @lines.last&.empty? && source.end_with?("\n")
+          @freeze_token = freeze_token
+          @signature_generator = signature_generator
+          @statements = parse_statements
+        end
+
+        # Get all top-level statements (LineNodes and FreezeNodes)
+        #
+        # @return [Array<LineNode, FreezeNodeBase>] All top-level statements
+        attr_reader :statements
+
+        # Compute signature for a node
+        #
+        # @param node [Object] Node to compute signature for
+        # @return [Array, nil] Signature array or nil
+        def compute_node_signature(node)
+          case node
+          when LineNode
+            node.signature
+          when FreezeNodeBase
+            [:freeze_block, node.start_line, node.end_line]
+          end
+        end
+
+        # Check if a value is a fallthrough node
+        #
+        # @param value [Object] Value to check
+        # @return [Boolean] True if fallthrough node
+        def fallthrough_node?(value)
+          value.is_a?(LineNode) || value.is_a?(FreezeNodeBase) || super
+        end
+
+        private
+
+        # Parse source into statements (LineNodes and FreezeNodes)
+        #
+        # @return [Array] Parsed statements
+        def parse_statements
+          statements = []
+          freeze_start = nil
+          freeze_start_line = nil
+
+          @lines.each_with_index do |line, idx|
+            line_number = idx + 1
+
+            # Check for freeze markers
+            if freeze_marker?(line, :freeze)
+              freeze_start = line_number
+              freeze_start_line = line
+              next
+            end
+
+            if freeze_marker?(line, :unfreeze)
+              if freeze_start
+                # Create freeze block
+                freeze_content = @lines[(freeze_start - 1)..(line_number - 1)].join("\n")
+                statements << FreezeNodeBase.new(
+                  start_line: freeze_start,
+                  end_line: line_number,
+                  content: freeze_content,
+                  reason: extract_freeze_reason(freeze_start_line),
+                )
+                freeze_start = nil
+                freeze_start_line = nil
+              end
+              next
+            end
+
+            # Skip lines inside freeze blocks
+            next if freeze_start
+
+            # Regular line
+            statements << LineNode.new(line, line_number: line_number)
+          end
+
+          # Handle unclosed freeze block
+          if freeze_start
+            raise FreezeNodeBase::InvalidStructureError.new(
+              "Unclosed freeze block starting at line #{freeze_start}",
+              start_line: freeze_start,
+            )
+          end
+
+          statements
+        end
+
+        # Check if a line is a freeze marker
+        #
+        # @param line [String] Line to check
+        # @param type [Symbol] :freeze or :unfreeze
+        # @return [Boolean] True if line is a marker
+        def freeze_marker?(line, type)
+          pattern = FreezeNodeBase.pattern_for(:hash_comment, @freeze_token)
+          match = line.match(pattern)
+          return false unless match
+
+          marker_type = match[1]&.downcase
+          case type
+          when :freeze
+            marker_type == "freeze"
+          when :unfreeze
+            marker_type == "unfreeze"
+          else
+            false
+          end
+        end
+
+        # Extract freeze reason from marker line
+        #
+        # @param line [String] Freeze marker line
+        # @return [String, nil] Reason or nil
+        def extract_freeze_reason(line)
+          pattern = FreezeNodeBase.pattern_for(:hash_comment, @freeze_token)
+          match = line.match(pattern)
+          reason = match[2]&.strip
+          (reason.nil? || reason.empty?) ? nil : reason
+        end
+      end
+    end
+  end
+end

data/lib/ast/merge/text/line_node.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    module Text
+      # Represents a line of text in the text-based AST.
+      # Lines are top-level nodes, with words as nested children.
+      #
+      # @example
+      #   line = LineNode.new("Hello world!", line_number: 1)
+      #   line.content       # => "Hello world!"
+      #   line.words.size    # => 2
+      #   line.signature     # => [:line, "Hello world!"]
+      class LineNode
+        # @return [String] The full line content (without trailing newline)
+        attr_reader :content
+
+        # @return [Integer] 1-based line number
+        attr_reader :line_number
+
+        # @return [Array<WordNode>] Words contained in this line
+        attr_reader :words
+
+        # Initialize a new LineNode
+        #
+        # @param content [String] The line content (without trailing newline)
+        # @param line_number [Integer] 1-based line number
+        def initialize(content, line_number:)
+          @content = content
+          @line_number = line_number
+          @words = parse_words
+        end
+
+        # Generate a signature for this line node.
+        # The signature is used for matching lines across template/destination.
+        #
+        # @return [Array] Signature array [:line, normalized_content]
+        def signature
+          [:line, normalized_content]
+        end
+
+        # Get normalized content (trimmed whitespace for comparison)
+        #
+        # @return [String] Whitespace-trimmed content
+        def normalized_content
+          @content.strip
+        end
+
+        # Check if this line is blank (empty or whitespace only)
+        #
+        # @return [Boolean] True if line is blank
+        def blank?
+          @content.strip.empty?
+        end
+
+        # Check if this line is a comment (starts with # after whitespace)
+        # This is a simple heuristic for text files.
+        #
+        # @return [Boolean] True if line appears to be a comment
+        def comment?
+          @content.strip.start_with?("#")
+        end
+
+        # Get the starting line (for compatibility with AST node interface)
+        #
+        # @return [Integer] 1-based start line
+        def start_line
+          @line_number
+        end
+
+        # Get the ending line (for compatibility with AST node interface)
+        #
+        # @return [Integer] 1-based end line (same as start for single line)
+        def end_line
+          @line_number
+        end
+
+        # Check equality with another LineNode
+        #
+        # @param other [LineNode] Other node to compare
+        # @return [Boolean] True if content matches exactly
+        def ==(other)
+          other.is_a?(LineNode) && @content == other.content
+        end
+
+        alias_method :eql?, :==
+
+        # Hash code for use in Hash keys
+        #
+        # @return [Integer] Hash code
+        def hash
+          @content.hash
+        end
+
+        # String representation for debugging
+        #
+        # @return [String] Debug representation
+        def inspect
+          "#<LineNode line=#{@line_number} #{@content.inspect} words=#{@words.size}>"
+        end
+
+        # Convert to string (returns content)
+        #
+        # @return [String] Line content
+        def to_s
+          @content
+        end
+
+        private
+
+        # Parse words from the line content using word boundaries
+        #
+        # @return [Array<WordNode>] Parsed word nodes
+        def parse_words
+          words = []
+          word_index = 0
+
+          # Match words using word boundary regex
+          # This captures sequences of word characters (\w+)
+          @content.scan(/\b(\w+)\b/) do |match|
+            word = match[0]
+            # Get the match position
+            match_data = Regexp.last_match
+            start_col = match_data.begin(0)
+            end_col = match_data.end(0)
+
+            words << WordNode.new(
+              word,
+              line_number: @line_number,
+              word_index: word_index,
+              start_col: start_col,
+              end_col: end_col,
+            )
+            word_index += 1
+          end
+
+          words
+        end
+      end
+    end
+  end
+end

data/lib/ast/merge/text/merge_result.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    module Text
+      # Merge result for text-based AST merging.
+      # Tracks merged lines and decisions made during the merge process.
+      class MergeResult < MergeResultBase
+        # Add a line to the result
+        #
+        # @param line [String] Line content to add
+        # @return [void]
+        def add_line(line)
+          @lines << line
+        end
+
+        # Add multiple lines to the result
+        #
+        # @param lines [Array<String>] Lines to add
+        # @return [void]
+        def add_lines(lines)
+          @lines.concat(lines)
+        end
+
+        # Record a merge decision
+        #
+        # @param decision [Symbol] Decision constant
+        # @param template_node [Object, nil] Template node involved
+        # @param dest_node [Object, nil] Destination node involved
+        # @return [void]
+        def record_decision(decision, template_node, dest_node)
+          @decisions << {
+            decision: decision,
+            template_node: template_node,
+            dest_node: dest_node,
+            line: @lines.length,
+          }
+        end
+      end
+    end
+  end
+end

data/lib/ast/merge/text/section.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    module Text
+      # Represents a named section within text content.
+      #
+      # Sections are logical units of text that can be matched and merged
+      # independently. For example, in Markdown, sections might be delimited by
+      # headings; in plain text, sections might be delimited by comment markers.
+      #
+      # This is used for text-based splitting of leaf node content, NOT for
+      # AST-level node classification (see SectionTyping for that).
+      #
+      # @example A Markdown section
+      #   Section.new(
+      #     name: "Installation",
+      #     header: "## Installation\n",
+      #     body: "Install the gem...\n",
+      #     start_line: 10,
+      #     end_line: 25,
+      #     metadata: { heading_level: 2 }
+      #   )
+      #
+      # @api public
+      Section = Struct.new(
+        # @return [String, Symbol] Unique identifier for matching sections
+        #   (e.g., heading text, comment marker, :preamble for content before first section)
+        :name,
+
+        # @return [String, nil] Header content (heading line, comment marker, etc.)
+        :header,
+
+        # @return [String] The section body content
+        :body,
+
+        # @return [Integer, nil] 1-indexed start line in the original content
+        :start_line,
+
+        # @return [Integer, nil] 1-indexed end line in the original content
+        :end_line,
+
+        # @return [Hash, nil] Optional metadata for splitter-specific information
+        #   (e.g., { heading_level: 2 }, { marker_type: :comment })
+        :metadata,
+        keyword_init: true,
+      ) do
+        # Returns the line range covered by this section.
+        #
+        # @return [Range, nil] The range from start_line to end_line (inclusive)
+        def line_range
+          return unless start_line && end_line
+          start_line..end_line
+        end
+
+        # Returns the number of lines this section spans.
+        #
+        # @return [Integer, nil] The number of lines
+        def line_count
+          return unless start_line && end_line
+          end_line - start_line + 1
+        end
+
+        # Reconstructs the full section text including header.
+        #
+        # @return [String] The complete section with header and body
+        def full_text
+          result = +""
+          result << header.to_s if header
+          result << body.to_s
+          result
+        end
+
+        # Check if this is the preamble section (content before first split point).
+        #
+        # @return [Boolean] true if this is the preamble
+        def preamble?
+          name == :preamble
+        end
+
+        # Normalize the section name for matching.
+        # Strips whitespace, downcases, and normalizes spaces.
+        #
+        # @return [String] Normalized name for matching
+        def normalized_name
+          return "" if name.nil?
+          return name.to_s if name.is_a?(Symbol)
+          name.to_s.strip.downcase.gsub(/\s+/, " ")
+        end
+      end
+    end
+  end
+end