ast-merge 1.0.0 → 2.0.0

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

@@ -1,23 +1,27 @@
 # frozen_string_literal: true
 
+require_relative "../ast_node"
+
 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.
       #
+      # Inherits from AstNode (SyntheticNode) to implement the TreeHaver::Node
+      # protocol, making it compatible with all tree_haver-based merge operations.
+      #
       # @example
       #   line = LineNode.new("Hello world!", line_number: 1)
       #   line.content       # => "Hello world!"
       #   line.words.size    # => 2
       #   line.signature     # => [:line, "Hello world!"]
-      class LineNode
+      #   line.type          # => "line_node" (TreeHaver protocol)
+      #   line.text          # => "Hello world!" (TreeHaver protocol)
+      class LineNode < AstNode
         # @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
 
@@ -27,10 +31,33 @@ module Ast
         # @param line_number [Integer] 1-based line number
         def initialize(content, line_number:)
           @content = content
-          @line_number = line_number
+
+          location = AstNode::Location.new(
+            start_line: line_number,
+            end_line: line_number,
+            start_column: 0,
+            end_column: content.length,
+          )
+
+          super(slice: content, location: location)
+
+          # Parse words AFTER super sets up location
           @words = parse_words
         end
 
+        # TreeHaver::Node protocol: type
+        # @return [String] "line_node"
+        def type
+          "line_node"
+        end
+
+        # TreeHaver::Node protocol: children
+        # Returns word nodes as children
+        # @return [Array<WordNode>]
+        def children
+          @words
+        end
+
         # Generate a signature for this line node.
         # The signature is used for matching lines across template/destination.
         #
@@ -61,18 +88,24 @@ module Ast
           @content.strip.start_with?("#")
         end
 
+        # Get the 1-based line number
+        # @return [Integer] 1-based line number
+        def line_number
+          location.start_line
+        end
+
         # Get the starting line (for compatibility with AST node interface)
         #
         # @return [Integer] 1-based start line
         def start_line
-          @line_number
+          location.start_line
         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
+          location.end_line
         end
 
         # Check equality with another LineNode
@@ -96,7 +129,7 @@ module Ast
         #
         # @return [String] Debug representation
         def inspect
-          "#<LineNode line=#{@line_number} #{@content.inspect} words=#{@words.size}>"
+          "#<LineNode line=#{line_number} #{@content.inspect} words=#{@words.size}>"
         end
 
         # Convert to string (returns content)
@@ -126,7 +159,7 @@ module Ast
 
             words << WordNode.new(
               word,
-              line_number: @line_number,
+              line_number: line_number,
               word_index: word_index,
               start_col: start_col,
               end_col: end_col,

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

@@ -265,16 +265,18 @@ module Ast
           normalize_name(section.name)
         end
 
-        # Validate splitter configuration.
-        #
-        # @param config [Hash, nil] Configuration to validate
-        # @raise [ArgumentError] If configuration is invalid
-        # @return [void]
-        def self.validate!(config)
-          return if config.nil?
-
-          unless config.is_a?(Hash)
-            raise ArgumentError, "splitter config must be a Hash, got #{config.class}"
+        class << self
+          # Validate a splitter configuration.
+          #
+          # @param config [Hash, nil] Configuration to validate
+          # @raise [ArgumentError] If configuration is invalid
+          # @return [void]
+          def validate!(config)
+            return if config.nil?
+
+            unless config.is_a?(Hash)
+              raise ArgumentError, "splitter config must be a Hash, got #{config.class}"
+            end
           end
         end
       end

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

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../ast_node"
+
 module Ast
   module Merge
     module Text
@@ -7,26 +9,21 @@ module Ast
       # Words are the nested level of the text-based AST.
       # They are identified by word boundaries (regex \b).
       #
+      # Inherits from AstNode (SyntheticNode) to implement the TreeHaver::Node
+      # protocol, making it compatible with all tree_haver-based merge operations.
+      #
       # @example
       #   word = WordNode.new("hello", line_number: 1, word_index: 0, start_col: 0, end_col: 5)
       #   word.content    # => "hello"
       #   word.signature  # => [:word, "hello"]
-      class WordNode
+      #   word.type       # => "word_node" (TreeHaver protocol)
+      class WordNode < AstNode
         # @return [String] The word content
         attr_reader :content
 
-        # @return [Integer] 1-based line number containing this word
-        attr_reader :line_number
-
         # @return [Integer] 0-based index of this word within the line
         attr_reader :word_index
 
-        # @return [Integer] 0-based starting column position
-        attr_reader :start_col
-
-        # @return [Integer] 0-based ending column position (exclusive)
-        attr_reader :end_col
-
         # Initialize a new WordNode
         #
         # @param content [String] The word content
@@ -36,10 +33,22 @@ module Ast
         # @param end_col [Integer] 0-based end column (exclusive)
         def initialize(content, line_number:, word_index:, start_col:, end_col:)
           @content = content
-          @line_number = line_number
           @word_index = word_index
-          @start_col = start_col
-          @end_col = end_col
+
+          location = AstNode::Location.new(
+            start_line: line_number,
+            end_line: line_number,
+            start_column: start_col,
+            end_column: end_col,
+          )
+
+          super(slice: content, location: location)
+        end
+
+        # TreeHaver::Node protocol: type
+        # @return [String] "word_node"
+        def type
+          "word_node"
         end
 
         # Generate a signature for this word node.
@@ -50,6 +59,30 @@ module Ast
           [:word, @content]
         end
 
+        # Get normalized content (the word itself for words)
+        # @return [String]
+        def normalized_content
+          @content
+        end
+
+        # Get the 1-based line number
+        # @return [Integer]
+        def line_number
+          location.start_line
+        end
+
+        # Get start column (0-based)
+        # @return [Integer]
+        def start_col
+          location.start_column
+        end
+
+        # Get end column (0-based, exclusive)
+        # @return [Integer]
+        def end_col
+          location.end_column
+        end
+
         # Check equality with another WordNode
         #
         # @param other [WordNode] Other node to compare
@@ -71,7 +104,7 @@ module Ast
         #
         # @return [String] Debug representation
         def inspect
-          "#<WordNode #{@content.inspect} line=#{@line_number} col=#{@start_col}..#{@end_col}>"
+          "#<WordNode #{@content.inspect} line=#{line_number} col=#{start_col}..#{end_col}>"
         end
 
         # Convert to string (returns content)

data/lib/ast/merge/version.rb

@@ -5,7 +5,7 @@ module Ast
     # Version information for Ast::Merge
     module Version
       # Current version of the ast-merge gem
-      VERSION = "1.0.0"
+      VERSION = "2.0.0"
     end
     VERSION = Version::VERSION # traditional location
   end

data/lib/ast/merge.rb

@@ -136,27 +136,31 @@ module Ast
       end
     end
 
+    # Core classes
     autoload :AstNode, "ast/merge/ast_node"
     autoload :Comment, "ast/merge/comment"
     autoload :ConflictResolverBase, "ast/merge/conflict_resolver_base"
+    autoload :ContentMatchRefiner, "ast/merge/content_match_refiner"
     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 :InjectionPoint, "ast/merge/navigable_statement"
+    autoload :InjectionPointFinder, "ast/merge/navigable_statement"
     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 :NavigableStatement, "ast/merge/navigable_statement"
     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 :PartialTemplateMerger, "ast/merge/partial_template_merger"
     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"
+
+    # Namespaces
+    autoload :Detector, "ast/merge/detector/base"  # Detector::Region, Detector::Base, Detector::Mergeable, etc.
+    autoload :Recipe, "ast/merge/recipe"
   end
 end
 

data/sig/ast/merge.rbs

@@ -167,13 +167,13 @@ module Ast
 
       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 add_template_only_nodes: add_template_only_nodes_type
       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,
+        ?add_template_only_nodes: add_template_only_nodes_type,
         ?freeze_token: String?,
         ?signature_generator: (^(untyped) -> (Array[untyped] | untyped | nil))?,
         ?node_splitter: Hash[Symbol, untyped]?
@@ -191,5 +191,392 @@ module Ast
 
       def validate_preference!: (Symbol preference) -> void
     end
+
+    # Type alias for node typing callables
+    type node_typing_callable = ^(untyped) -> untyped?
+    type node_typing_hash = Hash[Symbol | String, node_typing_callable]
+    type preference_type = Symbol | Hash[Symbol, Symbol]
+
+    # Type alias for add_template_only_nodes filter
+    # Can be: Boolean, or callable that receives (node, entry) and returns truthy/falsey
+    # Entry hash contains: { template_node:, signature:, template_index:, dest_index: nil }
+    type add_template_only_filter = ^(untyped node, Hash[Symbol, untyped] entry) -> boolish
+    type add_template_only_nodes_type = bool | add_template_only_filter
+
+    # Abstract base class for SmartMerger implementations
+    class SmartMergerBase
+      include Detector::Mergeable
+
+      attr_reader template_content: String
+      attr_reader dest_content: String
+      attr_reader template_analysis: untyped
+      attr_reader dest_analysis: untyped
+      attr_reader resolver: untyped
+      attr_reader result: untyped
+      attr_reader preference: preference_type
+      attr_reader add_template_only_nodes: add_template_only_nodes_type
+      attr_reader freeze_token: String
+      attr_reader signature_generator: (^(untyped) -> (Array[untyped] | untyped | nil))?
+      attr_reader match_refiner: untyped?
+      attr_reader node_typing: node_typing_hash?
+
+      def initialize: (
+        String template_content,
+        String dest_content,
+        ?signature_generator: (^(untyped) -> (Array[untyped] | untyped | nil))?,
+        ?preference: preference_type,
+        ?add_template_only_nodes: add_template_only_nodes_type,
+        ?freeze_token: String?,
+        ?match_refiner: untyped?,
+        ?regions: Array[Hash[Symbol, untyped]]?,
+        ?region_placeholder: String?,
+        ?node_typing: node_typing_hash?,
+        **untyped format_options
+      ) -> void
+
+      def merge: () -> String
+      def merge_result: () -> untyped
+
+      # Class method for convenient merging
+      def self.merge: (
+        String template_content,
+        String dest_content,
+        **untyped options
+      ) -> String
+
+      private
+
+      # Abstract methods that subclasses must implement
+      def analysis_class: () -> Class
+      def perform_merge: () -> untyped
+
+      # Optional hooks for subclasses
+      def default_freeze_token: () -> String
+      def resolver_class: () -> Class?
+      def result_class: () -> Class?
+      def aligner_class: () -> Class?
+      def build_analysis_options: () -> Hash[Symbol, untyped]
+      def build_resolver_options: () -> Hash[Symbol, untyped]
+      def build_full_analysis_options: (Symbol source) -> Hash[Symbol, untyped]
+      def update_result_content: (untyped result, String content) -> void
+      def template_parse_error_class: () -> Class
+      def destination_parse_error_class: () -> Class
+    end
+
+    # Abstract base class for ConflictResolver implementations
+    class ConflictResolverBase
+      # Decision constants
+      DECISION_KEPT_TEMPLATE: Symbol
+      DECISION_KEPT_DEST: Symbol
+      DECISION_MERGED: Symbol
+      DECISION_ADDED: Symbol
+      DECISION_FREEZE_BLOCK: Symbol
+      DECISION_APPENDED: Symbol
+      DECISION_REPLACED: Symbol
+
+      attr_reader strategy: Symbol
+      attr_reader preference: preference_type
+      attr_reader template_analysis: untyped
+      attr_reader dest_analysis: untyped
+      attr_reader add_template_only_nodes: bool
+      attr_reader match_refiner: untyped?
+
+      def initialize: (
+        strategy: Symbol,
+        preference: preference_type,
+        template_analysis: untyped,
+        dest_analysis: untyped,
+        ?add_template_only_nodes: bool,
+        ?match_refiner: untyped?,
+        **untyped options
+      ) -> void
+
+      def resolve: (*untyped args, **untyped kwargs) -> untyped
+
+      # Get preference for a specific node (supports Hash preference)
+      def preference_for: (untyped node) -> Symbol
+
+      private
+
+      def validate_preference!: (preference_type preference) -> void
+      def resolve_node_pair: (untyped template_node, untyped dest_node, **untyped kwargs) -> untyped
+      def resolve_batch: (*untyped args) -> untyped
+      def resolve_boundary: (*untyped args) -> untyped
+    end
+
+    # Abstract base class for MergeResult implementations
+    class MergeResultBase
+      # Decision constants
+      DECISION_KEPT_TEMPLATE: Symbol
+      DECISION_KEPT_DEST: Symbol
+      DECISION_MERGED: Symbol
+      DECISION_ADDED: Symbol
+      DECISION_FREEZE_BLOCK: Symbol
+      DECISION_APPENDED: Symbol
+      DECISION_REPLACED: Symbol
+
+      attr_reader template_analysis: untyped?
+      attr_reader dest_analysis: untyped?
+      attr_reader lines: Array[String]
+      attr_reader decisions: Array[Hash[Symbol, untyped]]
+      attr_reader conflicts: Array[Hash[Symbol, untyped]]
+      attr_reader frozen_blocks: Array[untyped]
+      attr_reader stats: Hash[Symbol, untyped]
+
+      def initialize: (
+        ?template_analysis: untyped?,
+        ?dest_analysis: untyped?,
+        ?conflicts: Array[Hash[Symbol, untyped]],
+        ?frozen_blocks: Array[untyped],
+        ?stats: Hash[Symbol, untyped],
+        **untyped options
+      ) -> void
+
+      def content: () -> Array[String]
+      def content?: () -> bool
+      def content_string: () -> String
+      def to_s: () -> String
+      def success?: () -> bool
+      def conflicts?: () -> bool
+      def track_decision: (Symbol decision, Symbol source, **untyped metadata) -> void
+    end
+
+    # Abstract base class for MatchRefiner implementations
+    class MatchRefinerBase
+      # Default similarity threshold
+      DEFAULT_THRESHOLD: Float
+
+      attr_reader threshold: Float
+      attr_reader node_types: Array[Symbol]?
+
+      def initialize: (
+        ?threshold: Float,
+        ?node_types: Array[Symbol]?,
+        **untyped options
+      ) -> void
+
+      # Find matches between unmatched nodes
+      def call: (
+        Array[untyped] template_nodes,
+        Array[untyped] dest_nodes,
+        ?Hash[Symbol, untyped] context
+      ) -> Array[MatchResult]
+
+      # Compute similarity score between two nodes
+      def similarity: (untyped template_node, untyped dest_node) -> Float
+
+      # Check if a node matches the configured types
+      def matches_type?: (untyped node) -> bool
+
+      private
+
+      # Levenshtein distance for string similarity
+      def levenshtein_distance: (String s1, String s2) -> Integer
+      def string_similarity: (String s1, String s2) -> Float
+    end
+
+    # Result of a match refinement operation
+    class MatchResult
+      attr_reader template_node: untyped
+      attr_reader dest_node: untyped
+      attr_reader score: Float
+      attr_reader metadata: Hash[Symbol, untyped]
+
+      def initialize: (
+        template_node: untyped,
+        dest_node: untyped,
+        score: Float,
+        ?metadata: Hash[Symbol, untyped]
+      ) -> void
+
+      def to_h: () -> Hash[Symbol, untyped]
+    end
+
+    # Detector namespace for region detection and merging
+    module Detector
+      # Represents a detected region within a document
+      class Region < Struct[untyped]
+        attr_accessor type: Symbol
+        attr_accessor content: String
+        attr_accessor start_line: Integer
+        attr_accessor end_line: Integer
+        attr_accessor delimiters: Array[String]?
+        attr_accessor metadata: Hash[Symbol, untyped]?
+
+        def line_range: () -> Range[Integer]
+        def line_count: () -> Integer
+        def full_text: () -> String
+        def contains_line?: (Integer line) -> bool
+        def overlaps?: (Region other) -> bool
+        def to_s: () -> String
+        def inspect: () -> String
+      end
+
+      # Abstract base class for region detectors
+      class Base
+        def region_type: () -> Symbol
+        def detect_all: (String source) -> Array[Region]
+        def strip_delimiters?: () -> bool
+        def name: () -> String
+        def inspect: () -> String
+
+        private
+
+        def build_region: (
+          type: Symbol,
+          content: String,
+          start_line: Integer,
+          end_line: Integer,
+          ?delimiters: Array[String]?,
+          ?metadata: Hash[Symbol, untyped]?
+        ) -> Region
+      end
+
+      # Detects fenced code blocks
+      class FencedCodeBlock < Base
+        attr_reader language: String
+        attr_reader aliases: Array[String]
+
+        def initialize: (String language, ?aliases: Array[String]) -> void
+        def self.ruby: () -> FencedCodeBlock
+        def self.yaml: () -> FencedCodeBlock
+        def self.json: () -> FencedCodeBlock
+        def self.bash: () -> FencedCodeBlock
+      end
+
+      # Detects YAML frontmatter
+      class YamlFrontmatter < Base
+        FRONTMATTER_PATTERN: Regexp
+      end
+
+      # Detects TOML frontmatter
+      class TomlFrontmatter < Base
+        FRONTMATTER_PATTERN: Regexp
+      end
+
+      # Mixin for region-aware merging
+      module Mergeable
+        DEFAULT_PLACEHOLDER_PREFIX: String
+        DEFAULT_PLACEHOLDER_SUFFIX: String
+
+        # Configuration for a region type
+        class Config < Struct[untyped]
+          attr_accessor detector: Base
+          attr_accessor merger_class: Class?
+          attr_accessor merger_options: Hash[Symbol, untyped]
+          attr_accessor regions: Array[Hash[Symbol, untyped]]
+        end
+
+        # Extracted region with placeholder
+        class ExtractedRegion < Struct[untyped]
+          attr_accessor region: Region
+          attr_accessor config: Config
+          attr_accessor placeholder: String
+          attr_accessor merged_content: String?
+        end
+
+        def regions_configured?: () -> bool
+        def setup_regions: (regions: Array[Hash[Symbol, untyped]], ?region_placeholder: String?) -> void
+        def extract_template_regions: (String content) -> String
+        def extract_dest_regions: (String content) -> String
+        def substitute_merged_regions: (String content) -> String
+      end
+    end
+
+    # Recipe namespace for YAML-based merge recipes
+    module Recipe
+      # Recipe configuration loaded from YAML
+      class Config
+        attr_reader name: String
+        attr_reader description: String?
+        attr_reader template_path: String
+        attr_reader targets: Array[String]
+        attr_reader injection: Hash[String, untyped]
+        attr_reader merge_options: Hash[String, untyped]
+        attr_reader when_missing: Symbol
+        attr_reader recipe_path: String?
+
+        def self.load: (String path) -> Config
+        def initialize: (Hash[String, untyped] config, ?recipe_path: String?) -> void
+        def anchor_config: () -> Hash[String, untyped]
+        def boundary_config: () -> Hash[String, untyped]?
+        def position: () -> Symbol
+        def preference: () -> Symbol
+        def add_missing?: () -> bool
+        def replace_mode?: () -> bool
+      end
+
+      # Executes recipes against target files
+      class Runner
+        # Result of processing a single file
+        class Result < Struct[untyped]
+          attr_accessor path: String
+          attr_accessor relative_path: String
+          attr_accessor status: Symbol
+          attr_accessor changed: bool
+          attr_accessor has_anchor: bool
+          attr_accessor message: String?
+          attr_accessor stats: Hash[Symbol, untyped]?
+          attr_accessor error: String?
+        end
+
+        attr_reader recipe: Config
+        attr_reader dry_run: bool
+        attr_reader verbose: bool
+        attr_reader parser: Symbol
+        attr_reader base_dir: String
+        attr_reader results: Array[Result]
+
+        def initialize: (
+          Config recipe,
+          ?dry_run: bool,
+          ?verbose: bool,
+          ?parser: Symbol,
+          ?base_dir: String
+        ) -> void
+
+        def run: () ?{ (Result) -> void } -> Array[Result]
+        def summary: () -> Hash[Symbol, Integer]
+        def summary_table: () -> Array[Hash[Symbol, untyped]]
+      end
+
+      # Loads Ruby scripts referenced by recipes
+      class ScriptLoader
+        attr_reader base_dir: String?
+        attr_reader cache: Hash[String, untyped]
+
+        def initialize: (?recipe_path: String?, ?base_dir: String?) -> void
+        def load_callable: (String script_ref) -> (^(*untyped) -> untyped)?
+        def resolve_path: (String script_ref) -> String?
+
+        private
+
+        def load_from_file: (String path) -> untyped
+        def parse_inline_lambda: (String code) -> (^(*untyped) -> untyped)?
+      end
+    end
+
+    # Module for node typing support
+    module NodeTyping
+      # Wrapper class for typed nodes
+      class Wrapper
+        attr_reader node: untyped
+        attr_reader merge_type: Symbol
+
+        def initialize: (untyped node, Symbol merge_type) -> void
+        def method_missing: (Symbol method, *untyped args) ?{ (*untyped) -> untyped } -> untyped
+        def respond_to_missing?: (Symbol method, ?bool include_private) -> bool
+        def typed_node?: () -> bool
+        def unwrap: () -> untyped
+        def ==: (untyped other) -> bool
+        def hash: () -> Integer
+        def eql?: (untyped other) -> bool
+        def inspect: () -> String
+      end
+
+      def self.with_merge_type: (untyped node, Symbol merge_type) -> Wrapper
+      def self.validate!: (node_typing_hash? node_typing) -> void
+      def self.apply: (untyped node, node_typing_hash? node_typing) -> untyped
+    end
   end
 end