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

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    # Base class for 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.
+    #
+    # 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)
+    #
+    # @abstract
+    class AstNode
+      # Simple location struct for nodes that don't have a native location object
+      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
+        # @return [Boolean] true if the line number is within the range
+        def cover?(line_number)
+          line_number >= start_line && line_number <= end_line
+        end
+      end
+
+      # @return [Location] The location of this node in source
+      attr_reader :location
+
+      # @return [String] The source text for this node
+      attr_reader :slice
+
+      # 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:)
+        @slice = slice
+        @location = location
+      end
+
+      # @return [Array<AstNode>] Child nodes (empty for leaf nodes)
+      def children
+        []
+      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.
+      #
+      # @return [Array] Signature array for matching
+      def signature
+        [self.class.name, normalized_content]
+      end
+
+      # @return [String] Normalized content for signature comparison
+      def normalized_content
+        slice.to_s.strip
+      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}>"
+      end
+
+      # @return [String] The source text
+      def to_s
+        slice.to_s
+      end
+
+      # Support unwrap protocol (returns self for non-wrapper nodes)
+      # @return [AstNode] self
+      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
+  end
+end

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

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require_relative "../ast_node"
+require_relative "style"
+
+module Ast
+  module Merge
+    module Comment
+      # Represents a contiguous block of comment content.
+      #
+      # A comment block can represent:
+      # - A sequence of line comments not separated by blank lines
+      # - A C-style block comment (`/* ... */`)
+      # - An HTML comment block (`<!-- ... -->`)
+      #
+      # The block acts as a grouping mechanism for signature matching and
+      # merge operations.
+      #
+      # @example Line comment block (Ruby/Python style)
+      #   block = Block.new(children: [
+      #     Line.new(text: "# First line", line_number: 1),
+      #     Line.new(text: "# Second line", line_number: 2),
+      #   ])
+      #   block.signature #=> [:comment_block, "first line"]
+      #
+      # @example C-style block comment
+      #   block = Block.new(
+      #     raw_content: "/* This is a\n   multi-line comment */",
+      #     start_line: 1,
+      #     end_line: 2,
+      #     style: :c_style_block
+      #   )
+      #
+      class Block < AstNode
+        # @return [Array<Line, Empty>] The child nodes in this block (for line-based blocks)
+        attr_reader :children
+
+        # @return [String, nil] Raw content for block-style comments (e.g., /* ... */)
+        attr_reader :raw_content
+
+        # @return [Style] The comment style configuration
+        attr_reader :style
+
+        # Initialize a new Block.
+        #
+        # For line-based comments, pass `children` array.
+        # For block-style comments (/* ... */), pass `raw_content`.
+        #
+        # @param children [Array<Line, Empty>, nil] Child nodes (for line comments)
+        # @param raw_content [String, nil] Raw block content (for block comments)
+        # @param start_line [Integer, nil] Start line (required for raw_content)
+        # @param end_line [Integer, nil] End line (required for raw_content)
+        # @param style [Style, Symbol, nil] Comment style (default: :hash_comment)
+        def initialize(children: nil, raw_content: nil, start_line: nil, end_line: nil, style: nil)
+          @style = resolve_style(style)
+          @children = children || []
+          @raw_content = raw_content
+
+          if raw_content
+            # Block-style comment (e.g., /* ... */)
+            @start_line = start_line || 1
+            @end_line = end_line || @start_line
+            combined_slice = raw_content
+          else
+            # Line-based comment block
+            first_child = @children.first
+            last_child = @children.last
+            @start_line = first_child&.location&.start_line || 1
+            @end_line = last_child&.location&.end_line || @start_line
+            combined_slice = @children.map(&:slice).join("\n")
+          end
+
+          location = AstNode::Location.new(
+            start_line: @start_line,
+            end_line: @end_line,
+            start_column: 0,
+            end_column: combined_slice.split("\n").last&.length || 0,
+          )
+
+          super(slice: combined_slice, location: location)
+        end
+
+        # Generate signature for matching.
+        #
+        # For line-based blocks, uses the first non-empty line's content.
+        # For block-style comments, uses the first meaningful line of content.
+        #
+        # @return [Array] Signature for matching
+        def signature
+          content = first_meaningful_content
+          [:comment_block, content[0..120]] # Limit signature length
+        end
+
+        # @return [String] Normalized combined content
+        def normalized_content
+          if raw_content
+            extract_block_content
+          else
+            children
+              .select { |c| c.is_a?(Line) }
+              .map { |c| c.content.strip }
+              .join("\n")
+          end
+        end
+
+        # Check if this block contains a freeze marker.
+        #
+        # @param freeze_token [String] The freeze token to look for
+        # @return [Boolean] true if any child contains a freeze marker
+        def freeze_marker?(freeze_token)
+          return false unless freeze_token
+
+          if raw_content
+            pattern = /#{Regexp.escape(freeze_token)}:(freeze|unfreeze)/i
+            raw_content.match?(pattern)
+          else
+            children.any? { |c| c.respond_to?(:freeze_marker?) && c.freeze_marker?(freeze_token) }
+          end
+        end
+
+        # @return [String] Human-readable representation
+        def inspect
+          if raw_content
+            "#<Comment::Block lines=#{@start_line}..#{@end_line} style=#{style.name} block_comment>"
+          else
+            "#<Comment::Block lines=#{@start_line}..#{@end_line} style=#{style.name} children=#{children.size}>"
+          end
+        end
+
+        private
+
+        # Resolve the style parameter to a Style instance.
+        #
+        # @param style [Style, Symbol, nil] Style configuration
+        # @return [Style] Resolved style instance
+        def resolve_style(style)
+          case style
+          when Style
+            style
+          when Symbol
+            Style.for(style)
+          when nil
+            Style.for(Style::DEFAULT_STYLE)
+          else
+            raise ArgumentError, "Invalid style: #{style.inspect}"
+          end
+        end
+
+        # Get the first meaningful content for signature generation.
+        #
+        # @return [String] First non-empty content, lowercased
+        def first_meaningful_content
+          if raw_content
+            # Extract first line of content from block comment
+            extract_block_content.split("\n").first&.strip&.downcase || ""
+          else
+            # Find first comment line with actual content
+            first_content = children.find { |c| c.is_a?(Line) && !c.content.strip.empty? }
+            first_content&.content&.strip&.downcase || ""
+          end
+        end
+
+        # Extract content from a block-style comment.
+        #
+        # Removes the opening and closing delimiters.
+        #
+        # @return [String] The content without delimiters
+        def extract_block_content
+          return "" unless raw_content
+
+          content = raw_content.to_s
+
+          # Remove block start delimiter
+          if style.block_start
+            content = content.sub(/^\s*#{Regexp.escape(style.block_start)}\s*/, "")
+          end
+
+          # Remove block end delimiter
+          if style.block_end
+            content = content.sub(/\s*#{Regexp.escape(style.block_end)}\s*$/, "")
+          end
+
+          # Clean up common patterns in multi-line block comments
+          # (leading asterisks on each line, common in /* ... */ style)
+          lines = content.split("\n")
+          if lines.size > 1 && lines[1..].all? { |l| l.match?(/^\s*\*/) }
+            lines = lines.map { |l| l.sub(/^\s*\*\s?/, "") }
+          end
+
+          lines.map(&:strip).join("\n")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative "../ast_node"
+
+module Ast
+  module Merge
+    module Comment
+      # Represents an empty/blank line in source code.
+      #
+      # Empty lines are important for preserving document structure and
+      # separating comment blocks. They serve as natural boundaries between
+      # logical sections of comments.
+      #
+      # @example
+      #   empty = Empty.new(line_number: 5)
+      #   empty.slice #=> ""
+      #   empty.signature #=> [:empty_line]
+      #
+      # @example With whitespace-only content
+      #   empty = Empty.new(line_number: 5, text: "   ")
+      #   empty.slice #=> "   "
+      #   empty.signature #=> [:empty_line]
+      #
+      class Empty < AstNode
+        # @return [Integer] The line number in source
+        attr_reader :line_number
+
+        # @return [String] The actual line content (may have whitespace)
+        attr_reader :text
+
+        # Initialize a new Empty line.
+        #
+        # @param line_number [Integer] The 1-based line number
+        # @param text [String] The actual line content (may have whitespace)
+        def initialize(line_number:, text: "")
+          @line_number = line_number
+          @text = text.to_s
+
+          location = AstNode::Location.new(
+            start_line: line_number,
+            end_line: line_number,
+            start_column: 0,
+            end_column: @text.length,
+          )
+
+          super(slice: @text, location: location)
+        end
+
+        # Empty lines have a generic signature - they don't match by content.
+        #
+        # All empty lines are considered equivalent for matching purposes.
+        #
+        # @return [Array] Signature for matching
+        def signature
+          [:empty_line]
+        end
+
+        # @return [String] Empty normalized content
+        def normalized_content
+          ""
+        end
+
+        # Empty lines never contain freeze markers.
+        #
+        # @param _freeze_token [String] Ignored
+        # @return [Boolean] Always false
+        def freeze_marker?(_freeze_token)
+          false
+        end
+
+        # @return [String] Human-readable representation
+        def inspect
+          "#<Comment::Empty line=#{line_number}>"
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require_relative "../ast_node"
+require_relative "style"
+
+module Ast
+  module Merge
+    module Comment
+      # Represents a single comment line in source code.
+      #
+      # A comment line is a line that starts with a comment delimiter
+      # (e.g., `#` in Ruby, `//` in JavaScript, `<!--` in HTML).
+      # The style determines how the comment is parsed and normalized.
+      #
+      # @example Ruby-style hash comment
+      #   line = Line.new(text: "# frozen_string_literal: true", line_number: 1)
+      #   line.slice #=> "# frozen_string_literal: true"
+      #   line.content #=> "frozen_string_literal: true"
+      #   line.signature #=> [:comment_line, "frozen_string_literal: true"]
+      #
+      # @example JavaScript-style line comment
+      #   style = Style.for(:c_style_line)
+      #   line = Line.new(text: "// TODO: fix this", line_number: 5, style: style)
+      #   line.content #=> "TODO: fix this"
+      #
+      # @example HTML-style comment
+      #   style = Style.for(:html_comment)
+      #   line = Line.new(text: "<!-- Important note -->", line_number: 1, style: style)
+      #   line.content #=> "Important note"
+      #
+      class Line < AstNode
+        # @return [String] The raw text of the comment line
+        attr_reader :text
+
+        # @return [Integer] The line number in source
+        attr_reader :line_number
+
+        # @return [Style] The comment style configuration
+        attr_reader :style
+
+        # Initialize a new Line.
+        #
+        # @param text [String] The full comment text including delimiter
+        # @param line_number [Integer] The 1-based line number
+        # @param style [Style, Symbol, nil] The comment style (default: :hash_comment)
+        def initialize(text:, line_number:, style: nil)
+          @text = text.to_s
+          @line_number = line_number
+          @style = resolve_style(style)
+
+          location = AstNode::Location.new(
+            start_line: line_number,
+            end_line: line_number,
+            start_column: 0,
+            end_column: @text.length,
+          )
+
+          super(slice: @text, location: location)
+        end
+
+        # Extract the comment content without the delimiter.
+        #
+        # Uses the style configuration to properly strip delimiters.
+        #
+        # @return [String] The comment text without the leading delimiter and whitespace
+        def content
+          @content ||= style.extract_line_content(text)
+        end
+
+        # Generate signature for matching.
+        # Uses normalized content (without delimiter) for better matching across files.
+        #
+        # @return [Array] Signature for matching
+        def signature
+          [:comment_line, normalized_content.downcase]
+        end
+
+        # @return [String] Normalized content for comparison
+        def normalized_content
+          content.strip
+        end
+
+        # Check if this comment contains a specific token pattern.
+        #
+        # Useful for detecting freeze markers or other special directives.
+        #
+        # @param token [String] The token to look for
+        # @param action [String, nil] Optional action suffix (e.g., "freeze", "unfreeze")
+        # @return [Boolean] true if the token is found
+        def contains_token?(token, action: nil)
+          return false unless token
+
+          pattern = if action
+            /#{Regexp.escape(token)}:#{action}/i
+          else
+            /#{Regexp.escape(token)}/i
+          end
+          text.match?(pattern)
+        end
+
+        # Check if this comment contains a freeze marker.
+        #
+        # @param freeze_token [String] The freeze token to look for
+        # @return [Boolean] true if this comment contains a freeze marker
+        def freeze_marker?(freeze_token)
+          return false unless freeze_token
+
+          pattern = /#{Regexp.escape(freeze_token)}:(freeze|unfreeze)/i
+          text.match?(pattern)
+        end
+
+        # @return [String] Human-readable representation
+        def inspect
+          "#<Comment::Line line=#{line_number} style=#{style.name} #{text.inspect}>"
+        end
+
+        private
+
+        # Resolve the style parameter to a Style instance.
+        #
+        # @param style [Style, Symbol, nil] Style configuration
+        # @return [Style] Resolved style instance
+        def resolve_style(style)
+          case style
+          when Style
+            style
+          when Symbol
+            Style.for(style)
+          when nil
+            Style.for(Style::DEFAULT_STYLE)
+          else
+            raise ArgumentError, "Invalid style: #{style.inspect}"
+          end
+        end
+      end
+    end
+  end
+end