ast-merge 1.0.0

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

@@ -0,0 +1,278 @@
+# frozen_string_literal: true
+
+require_relative "style"
+require_relative "line"
+require_relative "empty"
+require_relative "block"
+
+module Ast
+  module Merge
+    module Comment
+      # Parser for building comment AST from source lines.
+      #
+      # This parser takes an array of source lines and produces an array of
+      # AstNode objects (Block, Line, Empty) that represent the structure
+      # of a comment-only file or section.
+      #
+      # The parser is style-aware and can handle:
+      # - Line comments (`#`, `//`, `--`, `;`)
+      # - HTML-style comments (`<!-- ... -->`)
+      # - C-style block comments (`/* ... */`)
+      #
+      # @example Parsing Ruby-style comments
+      #   lines = ["# frozen_string_literal: true", "", "# A comment block"]
+      #   parser = Parser.new(lines)
+      #   nodes = parser.parse
+      #   # => [Block(...), Empty(...), Block(...)]
+      #
+      # @example Parsing C-style block comments
+      #   lines = ["/* Header comment", " * with multiple lines", " */"]
+      #   parser = Parser.new(lines, style: :c_style_block)
+      #   nodes = parser.parse
+      #   # => [Block(raw_content: "/* Header comment\n * with multiple lines\n */")]
+      #
+      # @example Auto-detecting comment style
+      #   lines = ["// JavaScript comment", "// continues here"]
+      #   parser = Parser.new(lines, style: :auto)
+      #   nodes = parser.parse
+      #
+      class Parser
+        # @return [Array<String>] The source lines
+        attr_reader :lines
+
+        # @return [Style] The comment style configuration
+        attr_reader :style
+
+        # Initialize a new Parser.
+        #
+        # @param lines [Array<String>] Source lines (without trailing newlines)
+        # @param style [Style, Symbol, nil] The comment style (:hash_comment, :c_style_line, etc.)
+        #   Pass :auto to attempt auto-detection.
+        def initialize(lines, style: nil)
+          @lines = lines || []
+          @style = resolve_style(style)
+        end
+
+        # Parse the lines into an AST.
+        #
+        # Groups contiguous comment lines into Block nodes,
+        # and represents blank lines as Empty nodes.
+        #
+        # @return [Array<AstNode>] Array of parsed nodes
+        def parse
+          return [] if lines.empty?
+
+          if style.supports_block_comments?
+            parse_with_block_comments
+          else
+            parse_line_comments
+          end
+        end
+
+        # Class method for convenient one-shot parsing.
+        #
+        # @param lines [Array<String>] Source lines
+        # @param style [Style, Symbol, nil] Comment style
+        # @return [Array<AstNode>] Parsed nodes
+        def self.parse(lines, style: nil)
+          new(lines, style: style).parse
+        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 :auto
+            auto_detect_style
+          when Symbol
+            Style.for(style)
+          when nil
+            Style.for(Style::DEFAULT_STYLE)
+          else
+            raise ArgumentError, "Invalid style: #{style.inspect}"
+          end
+        end
+
+        # Auto-detect the comment style from the source lines.
+        #
+        # Looks at the first non-empty line to determine the style.
+        #
+        # @return [Style] Detected style (defaults to hash_comment)
+        def auto_detect_style
+          first_content = lines.find { |l| !l.to_s.strip.empty? }
+          return Style.for(:hash_comment) unless first_content
+
+          stripped = first_content.to_s.strip
+
+          # Check each style's pattern
+          Style::STYLES.each do |name, config|
+            if config[:line_pattern]&.match?(stripped)
+              return Style.for(name)
+            end
+            if config[:block_start_pattern]&.match?(stripped)
+              return Style.for(name)
+            end
+          end
+
+          # Default to hash_comment
+          Style.for(:hash_comment)
+        end
+
+        # Parse lines using line-comment style (e.g., #, //, --, ;).
+        #
+        # Groups contiguous comment lines into Block nodes.
+        #
+        # @return [Array<AstNode>] Parsed nodes
+        def parse_line_comments
+          nodes = []
+          current_block = []
+
+          lines.each_with_index do |line, idx|
+            line_number = idx + 1
+            stripped = line.to_s.rstrip
+
+            if stripped.empty?
+              # Blank line - flush current block and add Empty
+              if current_block.any?
+                nodes << build_block(current_block)
+                current_block = []
+              end
+              nodes << Empty.new(line_number: line_number, text: line.to_s)
+            elsif style.match_line?(stripped)
+              # Comment line - add to current block
+              current_block << Line.new(
+                text: stripped,
+                line_number: line_number,
+                style: style,
+              )
+            else
+              # Non-comment, non-empty line
+              # Flush current block and treat this as content
+              if current_block.any?
+                nodes << build_block(current_block)
+                current_block = []
+              end
+              # Add as a single line (non-comment content in a comment-only context)
+              nodes << Line.new(
+                text: stripped,
+                line_number: line_number,
+                style: Style.for(:hash_comment), # Fallback style for non-comment lines
+              )
+            end
+          end
+
+          # Flush remaining block
+          if current_block.any?
+            nodes << build_block(current_block)
+          end
+
+          nodes
+        end
+
+        # Parse lines that may contain block comments (e.g., /* ... */, <!-- ... -->).
+        #
+        # Handles both single-line and multi-line block comments.
+        #
+        # @return [Array<AstNode>] Parsed nodes
+        def parse_with_block_comments
+          nodes = []
+          current_block_lines = []
+          in_block_comment = false
+
+          lines.each_with_index do |line, idx|
+            line_number = idx + 1
+            stripped = line.to_s.rstrip
+
+            if stripped.empty? && !in_block_comment
+              # Blank line outside block comment
+              if current_block_lines.any?
+                nodes << build_raw_block(current_block_lines)
+                current_block_lines = []
+              end
+              nodes << Empty.new(line_number: line_number, text: line.to_s)
+            elsif style.match_block_start?(stripped)
+              # Starting a block comment
+              # Flush any pending content first
+              if current_block_lines.any? && !in_block_comment
+                nodes << build_raw_block(current_block_lines)
+                current_block_lines = []
+              end
+
+              current_block_lines << {line: stripped, line_number: line_number}
+              in_block_comment = true
+
+              # Check if block ends on same line
+              if style.match_block_end?(stripped)
+                nodes << build_raw_block(current_block_lines)
+                current_block_lines = []
+                in_block_comment = false
+              end
+            elsif in_block_comment
+              # Inside a block comment
+              current_block_lines << {line: stripped.empty? ? line.to_s : stripped, line_number: line_number}
+
+              # Check if block ends
+              if style.match_block_end?(stripped)
+                nodes << build_raw_block(current_block_lines)
+                current_block_lines = []
+                in_block_comment = false
+              end
+            elsif style.supports_line_comments? && style.match_line?(stripped)
+              # Line comment (in a style that supports both line and block)
+              current_block_lines << {line: stripped, line_number: line_number}
+            else
+              # Other content - flush and add as-is
+              if current_block_lines.any?
+                nodes << build_raw_block(current_block_lines)
+                current_block_lines = []
+              end
+              nodes << Line.new(
+                text: stripped,
+                line_number: line_number,
+                style: style,
+              )
+            end
+          end
+
+          # Flush remaining block
+          if current_block_lines.any?
+            nodes << build_raw_block(current_block_lines)
+          end
+
+          nodes
+        end
+
+        # Build a Block from accumulated line comment nodes.
+        #
+        # @param comment_lines [Array<Line>] The comment lines
+        # @return [Block] Block containing the lines
+        def build_block(comment_lines)
+          Block.new(children: comment_lines, style: style)
+        end
+
+        # Build a Block from accumulated raw lines (for block-style comments).
+        #
+        # @param line_data [Array<Hash>] Array of { line:, line_number: } hashes
+        # @return [Block] Block with raw content
+        def build_raw_block(line_data)
+          raw_content = line_data.map { |d| d[:line] }.join("\n")
+          start_line = line_data.first[:line_number]
+          end_line = line_data.last[:line_number]
+
+          Block.new(
+            raw_content: raw_content,
+            start_line: start_line,
+            end_line: end_line,
+            style: style,
+          )
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    module Comment
+      # Configuration for different comment syntax styles.
+      #
+      # Supports multiple comment syntax patterns used across programming languages:
+      # - `:hash_comment` - Ruby/Python/YAML/Shell style (`# comment`)
+      # - `:html_comment` - HTML/XML/Markdown style (`<!-- comment -->`)
+      # - `:c_style_line` - C/JavaScript/Go line comments (`// comment`)
+      # - `:c_style_block` - C/JavaScript/CSS block comments (`/* comment */`)
+      # - `:semicolon_comment` - Lisp/Clojure/Assembly style (`; comment`)
+      # - `:double_dash_comment` - SQL/Haskell/Lua style (`-- comment`)
+      #
+      # @example Using a predefined style
+      #   style = Style.for(:hash_comment)
+      #   style.line_start #=> "#"
+      #   style.match_line?("# hello") #=> true
+      #
+      # @example Registering a custom style
+      #   Style.register(:percent_comment,
+      #     line_start: "%",
+      #     line_pattern: /^\s*%/
+      #   )
+      #
+      class Style
+        # @return [Symbol] The style identifier
+        attr_reader :name
+
+        # @return [String, nil] Line comment start delimiter (e.g., "#", "//")
+        attr_reader :line_start
+
+        # @return [String, nil] Line comment end delimiter (for HTML-style: "-->")
+        attr_reader :line_end
+
+        # @return [String, nil] Block comment start delimiter (e.g., "/*")
+        attr_reader :block_start
+
+        # @return [String, nil] Block comment end delimiter (e.g., "*/")
+        attr_reader :block_end
+
+        # @return [Regexp] Pattern to match a single comment line
+        attr_reader :line_pattern
+
+        # @return [Regexp, nil] Pattern to match block comment start
+        attr_reader :block_start_pattern
+
+        # @return [Regexp, nil] Pattern to match block comment end
+        attr_reader :block_end_pattern
+
+        # Predefined comment styles.
+        # Mutable to allow runtime registration of custom styles.
+        # @return [Hash{Symbol => Hash}] Registered comment styles
+        STYLES = {
+          hash_comment: {
+            line_start: "#",
+            line_end: nil,
+            block_start: nil,
+            block_end: nil,
+            line_pattern: /^\s*#/,
+            block_start_pattern: nil,
+            block_end_pattern: nil,
+          },
+          html_comment: {
+            line_start: "<!--",
+            line_end: "-->",
+            block_start: "<!--",
+            block_end: "-->",
+            line_pattern: /^\s*<!--.*-->\s*$/,
+            block_start_pattern: /^\s*<!--/,
+            block_end_pattern: /-->\s*$/,
+          },
+          c_style_line: {
+            line_start: "//",
+            line_end: nil,
+            block_start: nil,
+            block_end: nil,
+            line_pattern: %r{^\s*//},
+            block_start_pattern: nil,
+            block_end_pattern: nil,
+          },
+          c_style_block: {
+            line_start: nil,
+            line_end: nil,
+            block_start: "/*",
+            block_end: "*/",
+            line_pattern: nil,
+            block_start_pattern: %r{^\s*/\*},
+            block_end_pattern: %r{\*/\s*$},
+          },
+          semicolon_comment: {
+            line_start: ";",
+            line_end: nil,
+            block_start: nil,
+            block_end: nil,
+            line_pattern: /^\s*;/,
+            block_start_pattern: nil,
+            block_end_pattern: nil,
+          },
+          double_dash_comment: {
+            line_start: "--",
+            line_end: nil,
+            block_start: nil,
+            block_end: nil,
+            line_pattern: /^\s*--/,
+            block_start_pattern: nil,
+            block_end_pattern: nil,
+          },
+        }.freeze
+
+        # Default style when none specified
+        # @return [Symbol]
+        DEFAULT_STYLE = :hash_comment
+
+        class << self
+          # Get a Style instance for a given style name.
+          #
+          # @param name [Symbol] Style name (e.g., :hash_comment, :c_style_line)
+          # @return [Style] The style configuration
+          # @raise [ArgumentError] if style name is not registered
+          def for(name)
+            name = name&.to_sym || DEFAULT_STYLE
+            config = STYLES[name]
+            raise ArgumentError, "Unknown comment style: #{name}" unless config
+
+            new(name, **config)
+          end
+
+          # Register a custom comment style.
+          #
+          # @param name [Symbol] Style identifier
+          # @param line_start [String, nil] Line comment start delimiter
+          # @param line_end [String, nil] Line comment end delimiter
+          # @param block_start [String, nil] Block comment start delimiter
+          # @param block_end [String, nil] Block comment end delimiter
+          # @param line_pattern [Regexp, nil] Pattern to match comment lines
+          # @param block_start_pattern [Regexp, nil] Pattern to match block start
+          # @param block_end_pattern [Regexp, nil] Pattern to match block end
+          # @return [Hash] The registered style configuration
+          # @raise [ArgumentError] if name already exists
+          def register(name, line_start: nil, line_end: nil, block_start: nil, block_end: nil,
+            line_pattern: nil, block_start_pattern: nil, block_end_pattern: nil)
+            name = name.to_sym
+            if STYLES.key?(name)
+              raise ArgumentError, "Style :#{name} already registered"
+            end
+
+            config = {
+              line_start: line_start,
+              line_end: line_end,
+              block_start: block_start,
+              block_end: block_end,
+              line_pattern: line_pattern,
+              block_start_pattern: block_start_pattern,
+              block_end_pattern: block_end_pattern,
+            }
+
+            # Modify STYLES (it's frozen, so we need to work around)
+            STYLES.dup.tap do |styles|
+              styles[name] = config
+              remove_const(:STYLES)
+              const_set(:STYLES, styles.freeze)
+            end
+
+            config
+          end
+
+          # List all registered style names.
+          #
+          # @return [Array<Symbol>] Available style names
+          def available_styles
+            STYLES.keys
+          end
+
+          # Check if a style supports line comments.
+          #
+          # @param name [Symbol] Style name
+          # @return [Boolean] true if style has line comment support
+          def supports_line_comments?(name)
+            config = STYLES[name.to_sym]
+            config && config[:line_pattern]
+          end
+
+          # Check if a style supports block comments.
+          #
+          # @param name [Symbol] Style name
+          # @return [Boolean] true if style has block comment support
+          def supports_block_comments?(name)
+            config = STYLES[name.to_sym]
+            config && config[:block_start_pattern]
+          end
+        end
+
+        # Initialize a new Style.
+        #
+        # @param name [Symbol] Style identifier
+        # @param line_start [String, nil] Line comment start delimiter
+        # @param line_end [String, nil] Line comment end delimiter
+        # @param block_start [String, nil] Block comment start delimiter
+        # @param block_end [String, nil] Block comment end delimiter
+        # @param line_pattern [Regexp, nil] Pattern to match comment lines
+        # @param block_start_pattern [Regexp, nil] Pattern to match block start
+        # @param block_end_pattern [Regexp, nil] Pattern to match block end
+        def initialize(name, line_start: nil, line_end: nil, block_start: nil, block_end: nil,
+          line_pattern: nil, block_start_pattern: nil, block_end_pattern: nil)
+          @name = name
+          @line_start = line_start
+          @line_end = line_end
+          @block_start = block_start
+          @block_end = block_end
+          @line_pattern = line_pattern
+          @block_start_pattern = block_start_pattern
+          @block_end_pattern = block_end_pattern
+        end
+
+        # Check if a line matches this style's line comment pattern.
+        #
+        # @param line [String] The line to check
+        # @return [Boolean] true if line is a comment in this style
+        def match_line?(line)
+          return false unless line_pattern
+
+          line_pattern.match?(line.to_s)
+        end
+
+        # Check if a line starts a block comment.
+        #
+        # @param line [String] The line to check
+        # @return [Boolean] true if line starts a block comment
+        def match_block_start?(line)
+          return false unless block_start_pattern
+
+          block_start_pattern.match?(line.to_s)
+        end
+
+        # Check if a line ends a block comment.
+        #
+        # @param line [String] The line to check
+        # @return [Boolean] true if line ends a block comment
+        def match_block_end?(line)
+          return false unless block_end_pattern
+
+          block_end_pattern.match?(line.to_s)
+        end
+
+        # Extract content from a line comment, removing the delimiter.
+        #
+        # @param line [String] The comment line
+        # @return [String] The comment content without delimiters
+        def extract_line_content(line)
+          return line.to_s unless line_start
+
+          content = line.to_s.sub(/^\s*#{Regexp.escape(line_start)}\s?/, "")
+          if line_end
+            content = content.sub(/\s*#{Regexp.escape(line_end)}\s*$/, "")
+          end
+          content.rstrip
+        end
+
+        # Check if this style supports line comments.
+        #
+        # @return [Boolean] true if line comments are supported
+        def supports_line_comments?
+          !line_pattern.nil?
+        end
+
+        # Check if this style supports block comments.
+        #
+        # @return [Boolean] true if block comments are supported
+        def supports_block_comments?
+          !block_start_pattern.nil?
+        end
+
+        # @return [String] Human-readable representation
+        def inspect
+          "#<Comment::Style:#{name}>"
+        end
+      end
+    end
+  end
+end

data/lib/ast/merge/comment.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    # Comment AST nodes for representing comment-only content.
+    #
+    # This module provides generic, language-agnostic comment representation
+    # that supports multiple comment syntax styles:
+    # - `:hash_comment` - Ruby/Python/YAML/Shell style (`# comment`)
+    # - `:html_comment` - HTML/XML/Markdown style (`<!-- comment -->`)
+    # - `:c_style_line` - C/JavaScript/Go line comments (`// comment`)
+    # - `:c_style_block` - C/JavaScript/CSS block comments (`/* comment */`)
+    # - `:semicolon_comment` - Lisp/Clojure/Assembly style (`; comment`)
+    # - `:double_dash_comment` - SQL/Haskell/Lua style (`-- comment`)
+    #
+    # @example Parsing Ruby-style comments
+    #   lines = ["# frozen_string_literal: true", "", "# Main comment"]
+    #   nodes = Comment::Parser.parse(lines, style: :hash_comment)
+    #
+    # @example Parsing JavaScript-style comments
+    #   lines = ["// Header comment", "// continues here"]
+    #   nodes = Comment::Parser.parse(lines, style: :c_style_line)
+    #
+    # @example Auto-detecting style
+    #   lines = ["<!-- HTML comment -->"]
+    #   nodes = Comment::Parser.parse(lines, style: :auto)
+    #
+    module Comment
+      autoload :Style, "ast/merge/comment/style"
+      autoload :Line, "ast/merge/comment/line"
+      autoload :Empty, "ast/merge/comment/empty"
+      autoload :Block, "ast/merge/comment/block"
+      autoload :Parser, "ast/merge/comment/parser"
+    end
+  end
+end