ast-merge 1.0.0

data/lib/ast/merge/toml_frontmatter_detector.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    ##
+    # Detects TOML frontmatter at the beginning of a document.
+    #
+    # TOML frontmatter is delimited by `+++` at the start and end,
+    # and must begin on the first line of the document (optionally
+    # preceded by a UTF-8 BOM). This format is commonly used by
+    # Hugo and other static site generators.
+    #
+    # @example TOML frontmatter
+    #   +++
+    #   title = "My Document"
+    #   author = "Jane Doe"
+    #   +++
+    #
+    # @example Usage
+    #   detector = TomlFrontmatterDetector.new
+    #   regions = detector.detect_all(markdown_source)
+    #   # => [#<Region type=:toml_frontmatter content="title = \"My Document\"\n...">]
+    #
+    class TomlFrontmatterDetector < RegionDetectorBase
+      ##
+      # Pattern for detecting TOML frontmatter.
+      # - Must start at beginning of document (or after BOM)
+      # - Opening delimiter is `+++` followed by optional whitespace and newline
+      # - Content is captured (non-greedy)
+      # - Closing delimiter is `+++` at start of line, followed by optional whitespace and newline/EOF
+      #
+      FRONTMATTER_PATTERN = /\A(?:\xEF\xBB\xBF)?(\+\+\+[ \t]*\r?\n)(.*?)(^\+\+\+[ \t]*(?:\r?\n|\z))/m
+
+      ##
+      # @return [Symbol] the type identifier for TOML frontmatter regions
+      #
+      def region_type
+        :toml_frontmatter
+      end
+
+      ##
+      # Detects TOML frontmatter at the beginning of the document.
+      #
+      # @param source [String] the source document to scan
+      # @return [Array<Region>] array containing at most one Region for frontmatter
+      #
+      def detect_all(source)
+        return [] if source.nil? || source.empty?
+
+        match = source.match(FRONTMATTER_PATTERN)
+        return [] unless match
+
+        opening_delimiter = match[1]
+        content = match[2]
+        closing_delimiter = match[3]
+
+        # Calculate line numbers
+        start_line = 1
+
+        # Count total newlines in the full match to determine end line
+        full_match = match[0]
+        total_newlines = full_match.count("\n")
+        end_line = total_newlines + (full_match.end_with?("\n") ? 0 : 1)
+
+        [
+          Region.new(
+            type: region_type,
+            content: content,
+            start_line: start_line,
+            end_line: end_line,
+            delimiters: [opening_delimiter.strip, closing_delimiter.strip],
+            metadata: {format: :toml},
+          ),
+        ]
+      end
+
+      private
+
+      ##
+      # @return [Array<Region>] array containing at most one Region
+      #
+      def build_regions(source, matches)
+        # Not used - detect_all is overridden directly
+        raise NotImplementedError, "TomlFrontmatterDetector overrides detect_all directly"
+      end
+    end
+  end
+end

data/lib/ast/merge/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    # Version information for Ast::Merge
+    module Version
+      # Current version of the ast-merge gem
+      VERSION = "1.0.0"
+    end
+    VERSION = Version::VERSION # traditional location
+  end
+end

data/lib/ast/merge/yaml_frontmatter_detector.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    ##
+    # Detects YAML frontmatter at the beginning of a document.
+    #
+    # YAML frontmatter is delimited by `---` at the start and end,
+    # and must begin on the first line of the document (optionally
+    # preceded by a UTF-8 BOM).
+    #
+    # @example YAML frontmatter
+    #   ---
+    #   title: My Document
+    #   author: Jane Doe
+    #   ---
+    #
+    # @example Usage
+    #   detector = YamlFrontmatterDetector.new
+    #   regions = detector.detect_all(markdown_source)
+    #   # => [#<Region type=:yaml_frontmatter content="title: My Document\n...">]
+    #
+    class YamlFrontmatterDetector < RegionDetectorBase
+      ##
+      # Pattern for detecting YAML frontmatter.
+      # - Must start at beginning of document (or after BOM)
+      # - Opening delimiter is `---` followed by optional whitespace and newline
+      # - Content is captured (non-greedy)
+      # - Closing delimiter is `---` at start of line, followed by optional whitespace and newline/EOF
+      #
+      FRONTMATTER_PATTERN = /\A(?:\xEF\xBB\xBF)?(---[ \t]*\r?\n)(.*?)(^---[ \t]*(?:\r?\n|\z))/m
+
+      ##
+      # @return [Symbol] the type identifier for YAML frontmatter regions
+      #
+      def region_type
+        :yaml_frontmatter
+      end
+
+      ##
+      # Detects YAML frontmatter at the beginning of the document.
+      #
+      # @param source [String] the source document to scan
+      # @return [Array<Region>] array containing at most one Region for frontmatter
+      #
+      def detect_all(source)
+        return [] if source.nil? || source.empty?
+
+        match = source.match(FRONTMATTER_PATTERN)
+        return [] unless match
+
+        opening_delimiter = match[1]
+        content = match[2]
+        closing_delimiter = match[3]
+
+        # Calculate line numbers
+        # Frontmatter starts at line 1 (or after BOM)
+        start_line = 1
+        # Count newlines in content to determine end line
+        # Opening delimiter ends at line 1
+        # Content spans from line 2 to line 2 + content_lines - 1
+        # Closing delimiter is on the next line
+        content_newlines = content.count("\n")
+        # end_line is the line with the closing ---
+        end_line = start_line + 1 + content_newlines
+
+        # Adjust if content ends without newline
+        end_line - 1 if content.end_with?("\n") && content_newlines > 0
+
+        # Actually, let's calculate more carefully
+        # Line 1: ---
+        # Line 2 to N: content
+        # Line N+1: ---
+        if content.empty?
+          0
+        else
+          content.count("\n") + (content.end_with?("\n") ? 0 : 1)
+        end
+
+        # Simplify: count total newlines in the full match to determine end line
+        full_match = match[0]
+        total_newlines = full_match.count("\n")
+        end_line = total_newlines + (full_match.end_with?("\n") ? 0 : 1)
+
+        [
+          Region.new(
+            type: region_type,
+            content: content,
+            start_line: start_line,
+            end_line: end_line,
+            delimiters: [opening_delimiter.strip, closing_delimiter.strip],
+            metadata: {format: :yaml},
+          ),
+        ]
+      end
+
+      private
+
+      ##
+      # @return [Array<Region>] array containing at most one Region
+      #
+      def build_regions(source, matches)
+        # Not used - detect_all is overridden directly
+        raise NotImplementedError, "YamlFrontmatterDetector overrides detect_all directly"
+      end
+    end
+  end
+end

data/lib/ast/merge.rb

@@ -0,0 +1,165 @@
+# frozen_string_literal: true
+
+# External gems
+require "version_gem"
+
+# This gem - only version can be required (never autoloaded)
+require_relative "merge/version"
+
+module Ast
+  module Merge
+    # Base error class for all AST merge operations.
+    # All *-merge gems should have their Error class inherit from this.
+    # @api public
+    class Error < StandardError; end
+
+    # Base class for parse errors in merge operations.
+    #
+    # This class provides a flexible interface that can be extended by
+    # specific merge implementations. It supports:
+    # - An `errors` array for parser-specific error objects
+    # - An optional `content` attribute for the source that failed to parse
+    #
+    # Subclasses (TemplateParseError, DestinationParseError) identify whether
+    # the error occurred in the template or destination file.
+    #
+    # @example Basic usage with errors array
+    #   raise ParseError.new(errors: [syntax_error])
+    #
+    # @example With content for debugging
+    #   raise ParseError.new(errors: parse_result.errors, content: source_code)
+    #
+    # @example With custom message
+    #   raise ParseError.new("Custom message", errors: [e])
+    #
+    # @api public
+    class ParseError < Error
+      # @return [Array] Parser-specific error objects (e.g., Prism::ParseError, RBS::BaseError)
+      attr_reader :errors
+
+      # @return [String, nil] The source content that failed to parse (optional)
+      attr_reader :content
+
+      # Initialize a new ParseError.
+      #
+      # @param message [String, nil] Custom error message (auto-generated if nil)
+      # @param errors [Array] Array of parser-specific error objects
+      # @param content [String, nil] The source content that failed to parse
+      def initialize(message = nil, errors: [], content: nil)
+        @errors = Array(errors)
+        @content = content
+        super(message || build_message)
+      end
+
+      private
+
+      # Build a default error message from the errors array.
+      # Override in subclasses for more specific messages.
+      #
+      # @return [String] Error message
+      def build_message
+        if @errors.empty?
+          "Unknown #{self.class.name.split("::").map(&:downcase).join(" ")}"
+        else
+          error_messages = @errors.map { |e| e.respond_to?(:message) ? e.message : e.to_s }
+          "#{self.class.name.split("::").map(&:downcase).join(" ")}: #{error_messages.join(", ")}"
+        end
+      end
+    end
+
+    # Raised when the template file has syntax errors.
+    #
+    # Template files are the "source of truth" that destination files
+    # are merged against. When a template cannot be parsed, the merge
+    # operation cannot proceed.
+    #
+    # @example Handling template parse errors
+    #   begin
+    #     merger = SmartMerger.new(template, destination)
+    #   rescue Ast::Merge::TemplateParseError => e
+    #     puts "Template syntax error: #{e.message}"
+    #     e.errors.each { |error| puts "  #{error.message}" }
+    #   end
+    #
+    # @api public
+    class TemplateParseError < ParseError; end
+
+    # Raised when the destination file has syntax errors.
+    #
+    # Destination files contain user customizations that should be preserved
+    # during merges. When a destination cannot be parsed, the merge operation
+    # cannot proceed.
+    #
+    # @example Handling destination parse errors
+    #   begin
+    #     merger = SmartMerger.new(template, destination)
+    #   rescue Ast::Merge::DestinationParseError => e
+    #     puts "Destination syntax error: #{e.message}"
+    #     e.errors.each { |error| puts "  #{error.message}" }
+    #   end
+    #
+    # @api public
+    class DestinationParseError < ParseError; end
+
+    # Raised when the document contains text that matches the region placeholder.
+    #
+    # Region placeholders are used internally to mark positions in a document
+    # where nested regions will be substituted after merging. If the document
+    # already contains text that looks like a placeholder, the merge cannot
+    # proceed safely.
+    #
+    # @example Handling placeholder collision
+    #   begin
+    #     merger = SmartMerger.new(template, destination, regions: [...])
+    #   rescue Ast::Merge::PlaceholderCollisionError => e
+    #     # Use a custom placeholder to avoid the collision
+    #     merger = SmartMerger.new(template, destination,
+    #       regions: [...],
+    #       region_placeholder: "###MY_CUSTOM_PLACEHOLDER_"
+    #     )
+    #   end
+    #
+    # @api public
+    class PlaceholderCollisionError < Error
+      # @return [String] The placeholder that caused the collision
+      attr_reader :placeholder
+
+      # Initialize a new PlaceholderCollisionError.
+      #
+      # @param placeholder [String] The placeholder string that was found in the document
+      def initialize(placeholder)
+        @placeholder = placeholder
+        super(
+          "Document contains placeholder text '#{placeholder}'. " \
+            "Use the :region_placeholder option to specify a custom placeholder."
+        )
+      end
+    end
+
+    autoload :AstNode, "ast/merge/ast_node"
+    autoload :Comment, "ast/merge/comment"
+    autoload :ConflictResolverBase, "ast/merge/conflict_resolver_base"
+    autoload :DebugLogger, "ast/merge/debug_logger"
+    autoload :FencedCodeBlockDetector, "ast/merge/fenced_code_block_detector"
+    autoload :FileAnalyzable, "ast/merge/file_analyzable"
+    autoload :Freezable, "ast/merge/freezable"
+    autoload :FreezeNodeBase, "ast/merge/freeze_node_base"
+    autoload :MatchRefinerBase, "ast/merge/match_refiner_base"
+    autoload :MatchScoreBase, "ast/merge/match_score_base"
+    autoload :MergeResultBase, "ast/merge/merge_result_base"
+    autoload :MergerConfig, "ast/merge/merger_config"
+    autoload :NodeTyping, "ast/merge/node_typing"
+    autoload :Region, "ast/merge/region"
+    autoload :RegionDetectorBase, "ast/merge/region_detector_base"
+    autoload :RegionMergeable, "ast/merge/region_mergeable"
+    autoload :SectionTyping, "ast/merge/section_typing"
+    autoload :SmartMergerBase, "ast/merge/smart_merger_base"
+    autoload :Text, "ast/merge/text"
+    autoload :TomlFrontmatterDetector, "ast/merge/toml_frontmatter_detector"
+    autoload :YamlFrontmatterDetector, "ast/merge/yaml_frontmatter_detector"
+  end
+end
+
+Ast::Merge::Version.class_eval do
+  extend VersionGem::Basic
+end

data/lib/ast-merge.rb

@@ -0,0 +1,4 @@
+# For technical reasons, if we move to Zeitwerk, this cannot be require_relative.
+#   See: https://github.com/fxn/zeitwerk#for_gem_extension
+# Hook for other libraries to load this library (e.g. via bundler)
+require "ast/merge"

data/sig/ast/merge.rbs

@@ -0,0 +1,195 @@
+module Ast
+  module Merge
+    VERSION: String
+
+    # Base error class for all merge operations
+    class Error < StandardError
+    end
+
+    # Raised when parsing fails (template or destination)
+    class ParseError < Error
+      attr_reader errors: untyped
+      attr_reader content: String?
+
+      def initialize: (?String? message, ?errors: untyped, ?content: String?) -> void
+    end
+
+    # Raised when parsing the template (source) content fails
+    class TemplateParseError < ParseError
+      def initialize: (?String? message, ?errors: untyped, ?content: String?) -> void
+    end
+
+    # Raised when parsing the destination content fails
+    class DestinationParseError < ParseError
+      def initialize: (?String? message, ?errors: untyped, ?content: String?) -> void
+    end
+
+    # Base class for freeze block nodes in AST merge libraries.
+    class FreezeNode
+      # Pattern configuration for freeze block markers
+      MARKER_PATTERNS: Hash[Symbol, Hash[Symbol, Regexp]]
+
+      # Default pattern when none specified
+      DEFAULT_PATTERN: Symbol
+
+      # Error raised when a freeze block has invalid structure
+      class InvalidStructureError < StandardError
+        attr_reader start_line: Integer?
+        attr_reader end_line: Integer?
+        attr_reader unclosed_nodes: Array[untyped]
+
+        def initialize: (
+          String message,
+          ?start_line: Integer?,
+          ?end_line: Integer?,
+          ?unclosed_nodes: Array[untyped]
+        ) -> void
+      end
+
+      # Simple location struct for compatibility with AST nodes
+      class Location < Struct[Integer]
+        attr_accessor start_line: Integer
+        attr_accessor end_line: Integer
+
+        def cover?: (Integer line) -> bool
+      end
+
+      # Class methods
+      def self.register_pattern: (Symbol name, start: Regexp, end_pattern: Regexp) -> Hash[Symbol, Regexp]
+      def self.start_pattern: (?Symbol pattern_type) -> Regexp
+      def self.end_pattern: (?Symbol pattern_type) -> Regexp
+      def self.freeze_start?: (String? line, ?Symbol pattern_type) -> bool
+      def self.freeze_end?: (String? line, ?Symbol pattern_type) -> bool
+      def self.pattern_types: () -> Array[Symbol]
+
+      # Instance attributes
+      attr_reader start_line: Integer
+      attr_reader end_line: Integer
+      attr_reader content: String?
+      attr_reader start_marker: String?
+      attr_reader end_marker: String?
+      attr_reader pattern_type: Symbol
+
+      def initialize: (
+        start_line: Integer,
+        end_line: Integer,
+        ?start_marker: String?,
+        ?end_marker: String?,
+        ?pattern_type: Symbol
+      ) -> void
+
+      def location: () -> Location
+      def slice: () -> String?
+      def freeze_node?: () -> bool
+      def signature: () -> Array[untyped]
+      def inspect: () -> String
+      def to_s: () -> String
+
+      private
+
+      def validate_line_order!: () -> void
+    end
+
+    # Debug logging module
+    module DebugLogger
+      def self.env_var_name: () -> String
+      def self.env_var_name=: (String name) -> String
+      def self.log_prefix: () -> String
+      def self.log_prefix=: (String prefix) -> String
+      def self.enabled?: () -> bool
+      def self.debug: (*untyped args) -> void
+      def self.info: (*untyped args) -> void
+      def self.warning: (*untyped args) -> void
+      def self.time: (String label) { () -> untyped } -> untyped
+      def self.log_node: (untyped node, ?label: String) -> void
+      def self.extract_lines: (untyped node) -> String
+      def self.safe_type_name: (untyped node) -> String
+    end
+
+    # Base module for file analysis classes
+    module FileAnalysisBase
+      # Required instance attributes (must be defined by including class)
+      attr_reader statements: Array[untyped]
+      attr_reader lines: Array[String]
+      attr_reader signature_generator: (^(untyped) -> (Array[untyped] | untyped | nil))?
+
+      # Get all freeze blocks from statements
+      def freeze_blocks: () -> Array[FreezeNode]
+
+      # Check if a line is within a freeze block
+      def in_freeze_block?: (Integer line_num) -> bool
+
+      # Get the freeze block containing the given line
+      def freeze_block_at: (Integer line_num) -> FreezeNode?
+
+      # Get structural signature for a statement at given index
+      def signature_at: (Integer index) -> Array[untyped]?
+
+      # Get a specific line (1-indexed)
+      def line_at: (Integer line_num) -> String?
+
+      # Get a normalized line (whitespace-trimmed)
+      def normalized_line: (Integer line_num) -> String?
+
+      # Generate signature for a node
+      def generate_signature: (untyped node) -> Array[untyped]?
+
+      # Check if a value represents a fallthrough node
+      def fallthrough_node?: (untyped value) -> bool
+
+      # Compute default signature for a node (abstract - must be implemented)
+      def compute_node_signature: (untyped node) -> Array[untyped]?
+    end
+
+    # Base merge result tracking
+    class MergeResult
+      DECISION_KEPT_TEMPLATE: Symbol
+      DECISION_KEPT_DEST: Symbol
+      DECISION_MERGED: Symbol
+      DECISION_ADDED: Symbol
+      DECISION_FREEZE_BLOCK: Symbol
+      DECISION_REPLACED: Symbol
+      DECISION_APPENDED: Symbol
+
+      attr_reader decisions: Array[Hash[Symbol, untyped]]
+
+      def initialize: () -> void
+      def track_decision: (
+        untyped node,
+        Symbol decision,
+        ?reason: String?
+      ) -> void
+    end
+
+    # Configuration object for SmartMerger options
+    class MergerConfig
+      VALID_PREFERENCES: Array[Symbol]
+
+      attr_reader signature_match_preference: Symbol | Hash[Symbol, Symbol]
+      attr_reader node_splitter: Hash[Symbol, untyped]?
+      attr_reader add_template_only_nodes: bool
+      attr_reader freeze_token: String?
+      attr_reader signature_generator: (^(untyped) -> (Array[untyped] | untyped | nil))?
+
+      def initialize: (
+        ?signature_match_preference: (Symbol | Hash[Symbol, Symbol]),
+        ?add_template_only_nodes: bool,
+        ?freeze_token: String?,
+        ?signature_generator: (^(untyped) -> (Array[untyped] | untyped | nil))?,
+        ?node_splitter: Hash[Symbol, untyped]?
+      ) -> void
+
+      def prefer_destination?: () -> bool
+      def prefer_template?: () -> bool
+      def to_h: (?default_freeze_token: String?) -> Hash[Symbol, untyped]
+      def with: (**untyped options) -> MergerConfig
+
+      def self.destination_wins: (?freeze_token: String?, ?signature_generator: (^(untyped) -> (Array[untyped] | untyped | nil))?, ?node_splitter: Hash[Symbol, untyped]?) -> MergerConfig
+      def self.template_wins: (?freeze_token: String?, ?signature_generator: (^(untyped) -> (Array[untyped] | untyped | nil))?, ?node_splitter: Hash[Symbol, untyped]?) -> MergerConfig
+
+      private
+
+      def validate_preference!: (Symbol preference) -> void
+    end
+  end
+end