ast-merge 2.0.10 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9659c263184e27b07b7fa51f976e398c82f5da9610411fbe867e2a7319042ba8
-  data.tar.gz: 5dda81d19a9deb7bc2c9cfad0a8ab28b348cfb243ced1b453495bdef232d446f
+  metadata.gz: 4ce2b23f374b6f178709f84a66ccbed7b997a05d170d7b1f63ede714fc844469
+  data.tar.gz: d0ae1bc694c669108b5ddaac372424c02f8528f3c59642ced6fb7bb1af67dcf4
 SHA512:
-  metadata.gz: 129fb9114b909bf56c1adacbf0b0f3b1527a006d12ad4df61f8f209fee482f681a18f67f4cea21f994fac7ee268ac032ef567ff3fb4dec5ed178f88506c122c5
-  data.tar.gz: 671afd9a6960261dd3918577a8111e05bd71ecd9291388938e93baeb62b29002036e3e36d23e78e8bada44f0cd47d8e385df6052d252281cd4ea1b49bb057b9c
+  metadata.gz: 41981f4b37122e224ecc1b3047156ec15871742fbca09b8203acb91c27df7acf61164871c2ee7eac07db32a12acccc7c8dda3b83b8cd7dafd8f86ade604a82a6
+  data.tar.gz: 29c07de568c15bc8a78b6363c438e6c7902af5f24d8d441aaa9f9417bceeedb62107f40e95a226864be3492b16373ae4493efa0ed956c780448bf4a3168980b9

data/CHANGELOG.md

@@ -30,6 +30,76 @@ Please file a bug if you notice a violation of semantic versioning.
 
 ### Security
 
+## [3.1.0] - 2026-01-08
+
+- TAG: [v3.1.0][3.1.0t]
+- COVERAGE: 96.89% -- 2465/2544 lines in 47 files
+- BRANCH COVERAGE: 89.62% -- 794/886 branches in 47 files
+- 98.75% documented
+
+### Added
+
+- `Ast::Merge::EmitterBase` - Abstract base class for format-specific emitters
+  - Provides common infrastructure for converting AST structures back to text
+  - Tracks indentation level with configurable `indent_size` (default: 2 spaces)
+  - Manages output lines collection with `#lines` accessor
+  - `#emit_blank_line` - Emit an empty line
+  - `#emit_leading_comments` - Emit comments from CommentTracker
+  - `#emit_raw_lines` - Emit lines without modification (preserves exact formatting)
+  - `#to_s` - Get output as a single string with trailing newline
+  - `#clear` - Reset emitter state
+  - `#indent` / `#dedent` - Increase/decrease indentation level
+  - Subclass hooks: `#initialize_subclass_state`, `#clear_subclass_state`, `#emit_tracked_comment`
+  - Used by jsonc-merge, json-merge, bash-merge, toml-merge, and psych-merge emitters
+
+### Changed
+
+- tree_haver v4.0.0
+
+## [3.0.0] - 2026-01-05
+
+- TAG: [v3.0.0][3.0.0t]
+- COVERAGE: 96.93% -- 2462/2540 lines in 47 files
+- BRANCH COVERAGE: 89.62% -- 794/886 branches in 47 files
+- 98.72% documented
+
+### Added
+
+- `TestableNode` spec helper class that wraps a mock in a real `TreeHaver::Node`, providing consistent API testing without relying on fragile mocks
+- `Recipe::Preset#match_refiner` accessor method (was missing, causing errors in Recipe::Runner)
+- Minimal reproduction specs for `to_commonmark` normalization behavior:
+  - `spec/integration/link_reference_preservation_spec.rb` - tests link ref preservation
+  - `spec/integration/table_formatting_preservation_spec.rb` - tests table padding preservation
+- `Ast::Merge::PartialTemplateMergerBase` - Abstract base class for parser-agnostic partial template merging
+  - `#build_position_based_signature_generator` - Creates signature generators that match elements by position
+  - Position counters reset per document key, enabling tables at same position to match regardless of structure
+
+### Changed
+
+- **BREAKING**: `NavigableStatement#text` now requires nodes to conform to TreeHaver Node API (must have `#text` method)
+  - Removed conditional fallbacks for `to_plaintext`, `to_commonmark`, `slice`
+  - Nodes must now implement `#text` directly (all TreeHaver backends already do)
+- **BREAKING**: `ContentMatchRefiner#extract_content` now requires nodes to conform to TreeHaver Node API
+  - Removed conditional fallbacks for `text_content`, `string_content`, `content`, `to_s`
+  - Custom `content_extractor` proc still supported for non-standard nodes
+- Signature generators and typing scripts now receive TreeHaver nodes directly (no NavigableStatement wrapping)
+- Removed NavigableStatement wrapping from `FileAnalyzable#generate_signature` and `NodeTyping.process`
+
+### Removed
+
+- **BREAKING**: `Ast::Merge::PartialTemplateMerger` removed. Use `Markdown::Merge::PartialTemplateMerger` directly.
+  - The base class `Ast::Merge::PartialTemplateMergerBase` remains for other parsers to extend
+  - Migration: change `Ast::Merge::PartialTemplateMerger.new(parser: :markly, ...)` to
+    `Markdown::Merge::PartialTemplateMerger.new(backend: :markly, ...)`
+
+### Fixed
+
+- **Source-based rendering**: `Markdown::Merge::PartialTemplateMerger#node_to_text` now prefers extracting
+  original source text using `analysis.source_range` instead of `to_commonmark`. This preserves:
+  - Link reference definitions (no conversion to inline links)
+  - Table column padding/alignment
+  - Original formatting exactly as written
+
 ## [2.0.10] - 2026-01-04
 
 - TAG: [v2.0.10][2.0.10t]
@@ -463,7 +533,11 @@ Please file a bug if you notice a violation of semantic versioning.
 
 - Initial release
 
-[Unreleased]: https://github.com/kettle-rb/ast-merge/compare/v2.0.10...HEAD
+[Unreleased]: https://github.com/kettle-rb/ast-merge/compare/v3.1.0...HEAD
+[3.1.0]: https://github.com/kettle-rb/ast-merge/compare/v3.0.0...v3.1.0
+[3.1.0t]: https://github.com/kettle-rb/ast-merge/releases/tag/v3.1.0
+[3.0.0]: https://github.com/kettle-rb/ast-merge/compare/v2.0.10...v3.0.0
+[3.0.0t]: https://github.com/kettle-rb/ast-merge/releases/tag/v3.0.0
 [2.0.10]: https://github.com/kettle-rb/ast-merge/compare/v2.0.9...v2.0.10
 [2.0.10t]: https://github.com/kettle-rb/ast-merge/releases/tag/v2.0.10
 [2.0.9]: https://github.com/kettle-rb/ast-merge/compare/v2.0.8...v2.0.9

data/README.md

@@ -75,12 +75,36 @@ The `*-merge` gem family provides intelligent, AST-based merging for various fil
 | [rbs-merge][rbs-merge]                   | RBS                  | [tree-sitter-bash][ts-rbs] (via tree_haver), [RBS][rbs] (`rbs` std lib gem)                         | Smart merge for Ruby type signatures                                             |
 | [toml-merge][toml-merge]                 | TOML                 | [Citrus + toml-rb][toml-rb] (default, via tree_haver), [tree-sitter-toml][ts-toml] (via tree_haver) | Smart merge for TOML files                                                       |
 
+#### Backend Platform Compatibility
+
+tree_haver supports multiple parsing backends, but not all backends work on all Ruby platforms:
+
+| Platform 👉️<br> TreeHaver Backend 👇️         | MRI | JRuby | TruffleRuby | Notes                                               |
+|------------------------------------------------|:---:|:-----:|:-----------:|-----------------------------------------------------|
+| **MRI** ([ruby_tree_sitter][ruby_tree_sitter]) |  ✅  |   ❌   |      ❌      | C extension, MRI only                               |
+| **Rust** ([tree_stump][tree_stump])            |  ✅  |   ❌   |      ❌      | Rust extension via magnus/rb-sys, MRI only          |
+| **FFI**                                        |  ✅  |   ✅   |      ❌      | TruffleRuby's FFI doesn't support `STRUCT_BY_VALUE` |
+| **Java** ([jtreesitter][jtreesitter])          |  ❌  |   ✅   |      ❌      | JRuby only, requires grammar JARs                   |
+| **Prism**                                      |  ✅  |   ✅   |      ✅      | Ruby parsing, stdlib in Ruby 3.4+                   |
+| **Psych**                                      |  ✅  |   ✅   |      ✅      | YAML parsing, stdlib                                |
+| **Citrus**                                     |  ✅  |   ✅   |      ✅      | Pure Ruby, no native dependencies                   |
+| **Commonmarker**                               |  ✅  |   ❌   |      ❓      | Rust extension for Markdown                         |
+| **Markly**                                     |  ✅  |   ❌   |      ❓      | C extension for Markdown                            |
+
+**Legend**: ✅ = Works, ❌ = Does not work, ❓ = Untested
+
+**Why some backends don't work on certain platforms**:
+
+- **JRuby**: Runs on the JVM; cannot load native C/Rust extensions (`.so` files)
+- **TruffleRuby**: Has C API emulation via Sulong/LLVM, but it doesn't expose all MRI internals that native extensions require (e.g., `RBasic.flags`, `rb_gc_writebarrier`)
+- **FFI on TruffleRuby**: TruffleRuby's FFI implementation doesn't support returning structs by value, which tree-sitter's C API requires
+
 **Example implementations** for the gem templating use case:
 
-| Gem | Purpose | Description |
-| --- | --- | --- |
-| [kettle-dev](https://github.com/kettle-rb/kettle-dev) | Gem Development | Gem templating tool using `*-merge` gems |
-| [kettle-jem](https://github.com/kettle-rb/kettle-jem) | Gem Templating | Gem template library with smart merge support |
+| Gem                      | Purpose         | Description                                   |
+|--------------------------|-----------------|-----------------------------------------------|
+| [kettle-dev][kettle-dev] | Gem Development | Gem templating tool using `*-merge` gems      |
+| [kettle-jem][kettle-jem] | Gem Templating  | Gem template library with smart merge support |
 
 [tree_haver]: https://github.com/kettle-rb/tree_haver
 [ast-merge]: https://github.com/kettle-rb/ast-merge
@@ -100,8 +124,11 @@ The `*-merge` gem family provides intelligent, AST-based merging for various fil
 [prism]: https://github.com/ruby/prism
 [psych]: https://github.com/ruby/psych
 [ts-json]: https://github.com/tree-sitter/tree-sitter-json
+[ts-jsonc]: https://gitlab.com/WhyNotHugo/tree-sitter-jsonc
 [ts-bash]: https://github.com/tree-sitter/tree-sitter-bash
+[ts-rbs]: https://github.com/joker1007/tree-sitter-rbs
 [ts-toml]: https://github.com/tree-sitter-grammars/tree-sitter-toml
+[dotenv]: https://github.com/bkeepers/dotenv
 [rbs]: https://github.com/ruby/rbs
 [toml-rb]: https://github.com/emancu/toml-rb
 [markly]: https://github.com/ioquatix/markly
@@ -110,10 +137,6 @@ The `*-merge` gem family provides intelligent, AST-based merging for various fil
 [tree_stump]: https://github.com/joker1007/tree_stump
 [jtreesitter]: https://central.sonatype.com/artifact/io.github.tree-sitter/jtreesitter
 
-
-[ts-jsonc]: https://gitlab.com/WhyNotHugo/tree-sitter-jsonc
-[dotenv]: https://github.com/bkeepers/dotenv
-
 #### Backend Platform Compatibility
 
 tree\_haver supports multiple parsing backends, but not all backends work on all Ruby platforms:
@@ -1033,7 +1056,7 @@ Thanks for RTFM. ☺️
 [📌gitmoji]: https://gitmoji.dev
 [📌gitmoji-img]: https://img.shields.io/badge/gitmoji_commits-%20%F0%9F%98%9C%20%F0%9F%98%8D-34495e.svg?style=flat-square
 [🧮kloc]: https://www.youtube.com/watch?v=dQw4w9WgXcQ
-[🧮kloc-img]: https://img.shields.io/badge/KLOC-2.721-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
+[🧮kloc-img]: https://img.shields.io/badge/KLOC-2.544-FFDD67.svg?style=for-the-badge&logo=YouTube&logoColor=blue
 [🔐security]: SECURITY.md
 [🔐security-img]: https://img.shields.io/badge/security-policy-259D6C.svg?style=flat
 [📄copyright-notice-explainer]: https://opensource.stackexchange.com/questions/5778/why-do-licenses-such-as-the-mit-license-specify-a-single-year

data/lib/ast/merge/content_match_refiner.rb

@@ -140,28 +140,17 @@ module Ast
 
       # Extract text content from a node.
       #
-      # Uses the custom content_extractor if provided, otherwise tries
-      # common methods for getting text content.
+      # Uses the custom content_extractor if provided, otherwise uses the
+      # standard #text method that all TreeHaver nodes provide.
       #
-      # @param node [Object] The node
+      # @param node [Object] The node (must conform to TreeHaver Node API)
       # @return [String] The text content
       def extract_content(node)
         return @content_extractor.call(node) if @content_extractor
 
-        # Try common content extraction methods
-        if node.respond_to?(:text_content)
-          node.text_content.to_s
-        elsif node.respond_to?(:string_content)
-          node.string_content.to_s
-        elsif node.respond_to?(:content)
-          node.content.to_s
-        elsif node.respond_to?(:text)
-          node.text.to_s
-        elsif node.respond_to?(:to_s)
-          node.to_s
-        else
-          ""
-        end
+        # TreeHaver nodes (and any node conforming to the unified API) provide #text.
+        # No conditional fallbacks - nodes must conform to the API.
+        node.text.to_s
       end
 
       # Compute similarity score between two nodes based on content.

data/lib/ast/merge/emitter_base.rb

@@ -0,0 +1,123 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    # Base class for emitters that convert AST structures back to text.
+    # Provides common functionality for tracking indentation, managing output lines,
+    # and handling comments.
+    #
+    # Subclasses implement format-specific emission methods (e.g., emit_pair for JSON,
+    # emit_variable_assignment for Bash, etc.)
+    #
+    # @example Implementing a custom emitter
+    #   class MyEmitter < Ast::Merge::EmitterBase
+    #     def emit_my_construct(data)
+    #       add_comma_if_needed if @needs_separator
+    #       @lines << "#{current_indent}my_syntax: #{data}"
+    #       @needs_separator = true
+    #     end
+    #   end
+    class EmitterBase
+      # @return [Array<String>] Output lines
+      attr_reader :lines
+
+      # @return [Integer] Current indentation level
+      attr_reader :indent_level
+
+      # @return [Integer] Spaces per indent level
+      attr_reader :indent_size
+
+      # Initialize a new emitter
+      #
+      # @param indent_size [Integer] Number of spaces per indent level
+      # @param options [Hash] Additional options for subclasses
+      def initialize(indent_size: 2, **options)
+        @lines = []
+        @indent_level = 0
+        @indent_size = indent_size
+        initialize_subclass_state(**options)
+      end
+
+      # Hook for subclasses to initialize their own state
+      # @param options [Hash] Additional options
+      def initialize_subclass_state(**options)
+        # Override in subclasses if needed
+      end
+
+      # Emit a blank line
+      def emit_blank_line
+        @lines << ""
+      end
+
+      # Emit leading comments from CommentTracker
+      #
+      # @param comments [Array<Hash>] Comment hashes with :text, :indent, etc.
+      def emit_leading_comments(comments)
+        comments.each do |comment|
+          emit_tracked_comment(comment)
+        end
+      end
+
+      # Emit a comment from CommentTracker hash
+      # Subclasses should override this to handle format-specific comment syntax
+      #
+      # @param comment [Hash] Comment hash with :text, :indent, :block, etc.
+      def emit_tracked_comment(comment)
+        raise NotImplementedError, "Subclasses must implement emit_tracked_comment"
+      end
+
+      # Emit raw lines as-is (for preserving exact formatting)
+      #
+      # @param raw_lines [Array<String>] Lines to emit without modification
+      def emit_raw_lines(raw_lines)
+        raw_lines.each { |line| @lines << line.chomp }
+      end
+
+      # Get the output as a single string
+      # Subclasses may override to customize output format (e.g., to_json, to_yaml)
+      #
+      # @return [String]
+      def to_s
+        content = @lines.join("\n")
+        content += "\n" unless content.empty? || content.end_with?("\n")
+        content
+      end
+
+      # Clear the emitter state
+      def clear
+        @lines = []
+        @indent_level = 0
+        clear_subclass_state
+      end
+
+      # Hook for subclasses to clear their own state
+      def clear_subclass_state
+        # Override in subclasses if needed
+      end
+
+      # Increase indentation level
+      def indent
+        @indent_level += 1
+      end
+
+      # Decrease indentation level
+      def dedent
+        @indent_level -= 1 if @indent_level > 0
+      end
+
+      protected
+
+      # Get the current indentation string
+      # @return [String]
+      def current_indent
+        " " * (@indent_level * @indent_size)
+      end
+
+      # Add a line with current indentation
+      # @param content [String] Line content
+      def add_indented_line(content)
+        @lines << "#{current_indent}#{content}"
+      end
+    end
+  end
+end

data/lib/ast/merge/file_analyzable.rb

@@ -224,6 +224,10 @@ module Ast
           # - Type checks work (e.g., `node.is_a?(Prism::CallNode)`)
           # - The generator sees the real AST structure
           # - Frozen nodes match by their underlying identity
+          #
+          # NOTE: For TreeHaver-based backends, the node already has a unified API
+          # with #text, #type, #source_position methods. For other backends, they
+          # must conform to the same API (either via TreeHaver or equivalent adapter).
           custom_result = signature_generator.call(actual_node)
           case custom_result
           when Array, nil

data/lib/ast/merge/freeze_node_base.rb

@@ -354,6 +354,15 @@ module Ast
         true
       end
 
+      # Node type for merge classification
+      # @return [Symbol] :freeze_block
+      def merge_type
+        :freeze_block
+      end
+
+      # Alias for compatibility
+      alias_method :type, :merge_type
+
       # Returns a stable signature for this freeze block.
       # Override in subclasses for file-type-specific normalization.
       # @return [Array] Signature array

data/lib/ast/merge/navigable_statement.rb

@@ -270,17 +270,9 @@ module Ast
 
       # @return [String] Node text content
       def text
-        if node.respond_to?(:to_plaintext)
-          node.to_plaintext.to_s
-        elsif node.respond_to?(:to_commonmark)
-          node.to_commonmark.to_s
-        elsif node.respond_to?(:slice)
-          node.slice.to_s
-        elsif node.respond_to?(:text)
-          node.text.to_s
-        else
-          node.to_s
-        end
+        # TreeHaver nodes (and any node conforming to the unified API) provide #text.
+        # No conditional fallbacks - nodes must conform to the API.
+        node.text.to_s
       end
 
       # @return [Hash, nil] Source position info

data/lib/ast/merge/node_typing.rb

@@ -13,6 +13,27 @@ module Ast
     # The `merge_type` attribute can then be used by other merge tools like
     # `signature_generator`, `match_refiner`, and per-node-type `preference` settings.
     #
+    # ## Important: Two Uses of merge_type
+    #
+    # The `merge_type` method serves two complementary purposes in the codebase:
+    #
+    # ### 1. NodeTyping-specific (gated by typed_node?)
+    # Wrapped nodes (Wrapper/FrozenWrapper) with custom type tagging for:
+    # - Per-node-type preferences (e.g., `:lint_gem` → `:template`)
+    # - Match refinement based on custom categories
+    # - Only applies when `typed_node?` returns true
+    # - Accessed via `NodeTyping.merge_type_for(node)`
+    #
+    # ### 2. General node classification (any node)
+    # Any node can implement `merge_type` for category identification:
+    # - FreezeNodeBase has `merge_type` → `:freeze_block`
+    # - GapLineNode has `merge_type` → `:gap_line`
+    # - Used by systems like MarkdownStructure for structural spacing rules
+    # - These nodes are NOT "typed nodes" (typed_node? returns false)
+    #
+    # The key distinction: **typed_node? is the gate** for NodeTyping wrapper
+    # semantics. A node can have `merge_type` without being a NodeTyping wrapper.
+    #
     # @example Basic node typing for different gem types
     #   node_typing = {
     #     CallNode: ->(node) {
@@ -139,7 +160,10 @@ module Ast
           callable = find_typing_callable(typing_config, type_key, node)
           return node unless callable
 
-          # Call the typing callable with the node
+          # Call the typing callable with the node.
+          # NOTE: For TreeHaver-based backends, the node already has a unified API
+          # with #text, #type, #source_position methods. For other backends, they
+          # must conform to the same API (either via TreeHaver or equivalent adapter).
           callable.call(node)
         end
 

data/lib/ast/merge/{partial_template_merger.rb → partial_template_merger_base.rb}

@@ -2,36 +2,23 @@
 
 module Ast
   module Merge
-    # Merges a partial template into a specific section of a destination document.
+    # Base class for merging a partial template into a specific section of a destination document.
     #
-    # Unlike the full SmartMerger which merges entire documents, PartialTemplateMerger:
+    # Unlike the full SmartMerger which merges entire documents, PartialTemplateMergerBase:
     # 1. Finds a specific section in the destination (using InjectionPoint)
     # 2. Replaces/merges only that section with the template
     # 3. Leaves the rest of the destination unchanged
     #
-    # This is useful for updating a specific section (like a "Gem Family" section)
-    # across multiple files while preserving file-specific content.
+    # This is an abstract base class. Subclasses must implement:
+    # - #create_analysis(content) - Create a FileAnalysis for the given content
+    # - #create_smart_merger(template, section) - Create a SmartMerger for the section merge
+    # - #find_section_end(statements, injection_point) - Find where the section ends
+    # - #node_to_text(node, analysis) - Convert a node to source text
     #
-    # @example Basic usage
-    #   merger = PartialTemplateMerger.new(
-    #     template: template_content,
-    #     destination: destination_content,
-    #     anchor: { type: :heading, text: /Gem Family/ },
-    #     parser: :markly
-    #   )
-    #   result = merger.merge
-    #   puts result.content
+    # @abstract Subclass and implement parser-specific methods
+    # @see Markdown::Merge::PartialTemplateMerger For markdown implementation
     #
-    # @example With boundary
-    #   merger = PartialTemplateMerger.new(
-    #     template: template_content,
-    #     destination: destination_content,
-    #     anchor: { type: :heading, text: /Installation/ },
-    #     boundary: { type: :heading },  # Stop at next heading
-    #     parser: :markly
-    #   )
-    #
-    class PartialTemplateMerger
+    class PartialTemplateMergerBase
       # Result of a partial template merge
       class Result
         # @return [String] The merged content
@@ -79,9 +66,6 @@ module Ast
       # @return [Hash, nil] Boundary matcher configuration
       attr_reader :boundary
 
-      # @return [Symbol] Parser to use (:markly, :commonmarker, etc.)
-      attr_reader :parser
-
       # @return [Symbol, Hash] Merge preference (:template, :destination, or per-type hash)
       attr_reader :preference
 
@@ -97,43 +81,46 @@ module Ast
       # @return [Hash, nil] Node typing configuration for per-type preferences
       attr_reader :node_typing
 
-      # Initialize a PartialTemplateMerger.
+      # @return [Object, nil] Match refiner for fuzzy matching unmatched nodes
+      attr_reader :match_refiner
+
+      # Initialize a PartialTemplateMergerBase.
       #
       # @param template [String] The template content (the section to merge in)
       # @param destination [String] The destination content
       # @param anchor [Hash] Anchor matcher: { type: :heading, text: /pattern/ }
       # @param boundary [Hash, nil] Boundary matcher (defaults to same type as anchor)
-      # @param parser [Symbol] Parser to use (:markly, :commonmarker, :prism, :psych)
       # @param preference [Symbol, Hash] Which content wins (:template, :destination, or per-type hash)
       # @param add_missing [Boolean, Proc] Whether to add template nodes not in destination
       # @param when_missing [Symbol] What to do if section not found (:skip, :append, :prepend)
       # @param replace_mode [Boolean] If true, template replaces section entirely (no merge)
       # @param signature_generator [Proc, nil] Custom signature generator for SmartMerger
       # @param node_typing [Hash, nil] Node typing configuration for per-type preferences
+      # @param match_refiner [Object, nil] Match refiner for fuzzy matching (e.g., ContentMatchRefiner)
       def initialize(
         template:,
         destination:,
         anchor:,
         boundary: nil,
-        parser: :markly,
         preference: :template,
         add_missing: true,
         when_missing: :skip,
         replace_mode: false,
         signature_generator: nil,
-        node_typing: nil
+        node_typing: nil,
+        match_refiner: nil
       )
         @template = template
         @destination = destination
         @anchor = normalize_matcher(anchor)
         @boundary = boundary ? normalize_matcher(boundary) : nil
-        @parser = parser
         @preference = preference
         @add_missing = add_missing
         @when_missing = when_missing
         @replace_mode = replace_mode
         @signature_generator = signature_generator
         @node_typing = node_typing
+        @match_refiner = match_refiner
       end
 
       # Perform the partial template merge.
@@ -161,6 +148,47 @@ module Ast
         perform_section_merge(d_analysis, d_statements, injection_point)
       end
 
+      protected
+
+      # Create a FileAnalysis for the given content.
+      #
+      # @abstract Subclasses must implement this method
+      # @param content [String] The content to analyze
+      # @return [Object] A FileAnalysis instance
+      def create_analysis(content)
+        raise NotImplementedError, "#{self.class} must implement #create_analysis"
+      end
+
+      # Create a SmartMerger for merging the section.
+      #
+      # @abstract Subclasses must implement this method
+      # @param template_content [String] The template content
+      # @param destination_content [String] The destination section content
+      # @return [Object] A SmartMerger instance
+      def create_smart_merger(template_content, destination_content)
+        raise NotImplementedError, "#{self.class} must implement #create_smart_merger"
+      end
+
+      # Find where the section ends.
+      #
+      # @abstract Subclasses must implement this method
+      # @param statements [Array<NavigableStatement>] All statements
+      # @param injection_point [InjectionPoint] The injection point
+      # @return [Integer] Index of the last statement in the section
+      def find_section_end(statements, injection_point)
+        raise NotImplementedError, "#{self.class} must implement #find_section_end"
+      end
+
+      # Convert a node to its source text.
+      #
+      # @abstract Subclasses must implement this method
+      # @param node [Object] The node to convert
+      # @param analysis [Object, nil] The analysis object for source lookup
+      # @return [String] The source text
+      def node_to_text(node, analysis = nil)
+        raise NotImplementedError, "#{self.class} must implement #node_to_text"
+      end
+
       private
 
       def normalize_matcher(matcher)
@@ -187,17 +215,10 @@ module Ast
         end
       end
 
-      def handle_missing_section(_d_analysis)
+      def handle_missing_section(d_analysis)
         case when_missing
-        when :skip
-          Result.new(
-            content: destination,
-            has_section: false,
-            changed: false,
-            message: "Section not found, skipping",
-          )
         when :append
-          # Append template at end of document
+          # Append template to end of destination
           new_content = destination.chomp + "\n\n" + template
           Result.new(
             content: new_content,
@@ -206,7 +227,7 @@ module Ast
             message: "Section not found, appended template",
           )
         when :prepend
-          # Prepend template at start (after any frontmatter)
+          # Prepend template to beginning of destination
           new_content = template + "\n\n" + destination
           Result.new(
             content: new_content,
@@ -219,12 +240,12 @@ module Ast
             content: destination,
             has_section: false,
             changed: false,
-            message: "Section not found, no action taken",
+            message: "Section not found, skipping",
           )
         end
       end
 
-      def perform_section_merge(_d_analysis, d_statements, injection_point)
+      def perform_section_merge(d_analysis, d_statements, injection_point)
         # Determine section boundaries in destination
         section_start_idx = injection_point.anchor.index
         section_end_idx = find_section_end(d_statements, injection_point)
@@ -235,12 +256,12 @@ module Ast
         after_statements = d_statements[(section_end_idx + 1)..]
 
         # Determine the merged section content
-        section_content = statements_to_content(section_statements)
+        section_content = statements_to_content(section_statements, d_analysis)
         merged_section, stats = merge_section_content(section_content)
 
-        # Reconstruct the document
-        before_content = statements_to_content(before_statements)
-        after_content = statements_to_content(after_statements)
+        # Reconstruct the document using source-based extraction
+        before_content = statements_to_content(before_statements, d_analysis)
+        after_content = statements_to_content(after_statements, d_analysis)
 
         new_content = build_merged_content(before_content, merged_section, after_content)
 
@@ -280,83 +301,15 @@ module Ast
         @replace_mode == true
       end
 
-      def find_section_end(statements, injection_point)
-        # If boundary was specified and found, use it (exclusive - section ends before boundary)
-        if injection_point.boundary
-          return injection_point.boundary.index - 1
-        end
-
-        # Otherwise, find the next node of same type (for headings, same or higher level)
-        anchor = injection_point.anchor
-        anchor_type = anchor.type
-
-        # For headings, find next heading of same or higher level
-        if heading_type?(anchor_type)
-          anchor_level = get_heading_level(anchor)
-
-          ((anchor.index + 1)...statements.length).each do |idx|
-            stmt = statements[idx]
-            if heading_type?(stmt.type)
-              stmt_level = get_heading_level(stmt)
-              if stmt_level && anchor_level && stmt_level <= anchor_level
-                # Found next heading of same or higher level - section ends before it
-                return idx - 1
-              end
-            end
-          end
-        else
-          # For non-headings, find next node of same type
-          ((anchor.index + 1)...statements.length).each do |idx|
-            stmt = statements[idx]
-            if stmt.type == anchor_type
-              return idx - 1
-            end
-          end
-        end
-
-        # Section extends to end of document
-        statements.length - 1
-      end
-
-      def heading_type?(type)
-        type.to_s == "heading" || type == :heading || type == :header
-      end
-
-      def get_heading_level(stmt)
-        inner = stmt.respond_to?(:unwrapped_node) ? stmt.unwrapped_node : stmt.node
-
-        if inner.respond_to?(:header_level)
-          inner.header_level
-        elsif inner.respond_to?(:level)
-          inner.level
-        end
-      end
-
-      def statements_to_content(statements)
+      def statements_to_content(statements, analysis = nil)
         return "" if statements.nil? || statements.empty?
 
         statements.map do |stmt|
           node = stmt.respond_to?(:node) ? stmt.node : stmt
-          node_to_text(node)
+          node_to_text(node, analysis)
         end.join
       end
 
-      def node_to_text(node)
-        # Unwrap if needed
-        inner = node
-        while inner.respond_to?(:inner_node) && inner.inner_node != inner
-          inner = inner.inner_node
-        end
-
-        if inner.respond_to?(:to_commonmark)
-          inner.to_commonmark.to_s
-        elsif inner.respond_to?(:to_s)
-          inner.to_s
-        else
-          ""
-        end
-      end
-
       def build_merged_content(before, section, after)
         result = +""
 
@@ -388,54 +341,6 @@ module Ast
         result << "\n" unless result.empty? || result.end_with?("\n")
         result
       end
-
-      def create_analysis(content)
-        case parser
-        when :markly
-          require "markly/merge" unless defined?(Markly::Merge)
-          Markly::Merge::FileAnalysis.new(content)
-        when :commonmarker
-          require "commonmarker/merge" unless defined?(Commonmarker::Merge)
-          Commonmarker::Merge::FileAnalysis.new(content)
-        when :prism
-          require "prism/merge" unless defined?(Prism::Merge)
-          Prism::Merge::FileAnalysis.new(content)
-        when :psych
-          require "psych/merge" unless defined?(Psych::Merge)
-          Psych::Merge::FileAnalysis.new(content)
-        else
-          raise ArgumentError, "Unknown parser: #{parser}"
-        end
-      end
-
-      def create_smart_merger(template_content, destination_content)
-        merger_class = case parser
-        when :markly
-          require "markly/merge" unless defined?(Markly::Merge)
-          Markly::Merge::SmartMerger
-        when :commonmarker
-          require "commonmarker/merge" unless defined?(Commonmarker::Merge)
-          Commonmarker::Merge::SmartMerger
-        when :prism
-          require "prism/merge" unless defined?(Prism::Merge)
-          Prism::Merge::SmartMerger
-        when :psych
-          require "psych/merge" unless defined?(Psych::Merge)
-          Psych::Merge::SmartMerger
-        else
-          raise ArgumentError, "Unknown parser: #{parser}"
-        end
-
-        # Build options hash, only including non-nil values
-        options = {
-          preference: preference,
-          add_template_only_nodes: add_missing,
-        }
-        options[:signature_generator] = signature_generator if signature_generator
-        options[:node_typing] = node_typing if node_typing
-
-        merger_class.new(template_content, destination_content, **options)
-      end
     end
   end
 end

data/lib/ast/merge/recipe/preset.rb

@@ -124,6 +124,17 @@ module Ast
           script_loader.load_callable_hash(value)
         end
 
+        # Get the match_refiner callable, loading from script if needed.
+        #
+        # @return [Object, nil] Match refiner instance or callable
+        def match_refiner
+          value = merge_config[:match_refiner]
+          return if value.nil?
+          return value if value.respond_to?(:call) || value.is_a?(Ast::Merge::MatchRefinerBase)
+
+          script_loader.load_callable(value)
+        end
+
         # Convert preset to a hash suitable for SmartMerger options.
         #
         # @return [Hash]
@@ -133,6 +144,7 @@ module Ast
             add_template_only_nodes: add_missing,
             signature_generator: signature_generator,
             node_typing: node_typing,
+            match_refiner: match_refiner,
             freeze_token: freeze_token,
           }.compact
         end
@@ -155,6 +167,7 @@ module Ast
             deep: config["deep"] == true,
             signature_generator: config["signature_generator"],
             node_typing: config["node_typing"],
+            match_refiner: config["match_refiner"],
           }
         end
 

data/lib/ast/merge/recipe/runner.rb

@@ -144,19 +144,19 @@ module Ast
           begin
             destination_content = File.read(target_path)
 
-            # Use PartialTemplateMerger which handles finding injection point and merging
-            merger = PartialTemplateMerger.new(
+            # Use the appropriate PartialTemplateMerger based on parser
+            merger = create_partial_template_merger(
               template: template_content,
               destination: destination_content,
               anchor: recipe.injection[:anchor] || {},
               boundary: recipe.injection[:boundary],
-              parser: parser,
               preference: recipe.preference,
               add_missing: recipe.add_missing,
               when_missing: recipe.when_missing,
               replace_mode: recipe.replace_mode?,
               signature_generator: recipe.signature_generator,
               node_typing: recipe.node_typing,
+              match_refiner: recipe.match_refiner,
             )
 
             result = merger.merge
@@ -179,6 +179,26 @@ module Ast
           end
         end
 
+        # Create the appropriate PartialTemplateMerger based on parser type.
+        #
+        # @param options [Hash] Merger options
+        # @return [Object] A PartialTemplateMerger instance
+        def create_partial_template_merger(**options)
+          case parser.to_sym
+          when :markly, :commonmarker
+            require "markdown/merge" unless defined?(Markdown::Merge)
+            Markdown::Merge::PartialTemplateMerger.new(backend: parser, **options)
+          when :prism
+            require "prism/merge" unless defined?(Prism::Merge)
+            raise NotImplementedError, "Prism PartialTemplateMerger not yet implemented"
+          when :psych
+            require "psych/merge" unless defined?(Psych::Merge)
+            raise NotImplementedError, "Psych PartialTemplateMerger not yet implemented"
+          else
+            raise ArgumentError, "Unknown parser: #{parser}. Supported: :markly, :commonmarker"
+          end
+        end
+
         def create_result_from_merge(target_path, relative_path, _destination_content, merge_result)
           changed = merge_result.changed
 

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 = "2.0.10"
+      VERSION = "3.1.0"
     end
     VERSION = Version::VERSION # traditional location
   end

data/lib/ast/merge.rb

@@ -142,6 +142,7 @@ module Ast
     autoload :ConflictResolverBase, "ast/merge/conflict_resolver_base"
     autoload :ContentMatchRefiner, "ast/merge/content_match_refiner"
     autoload :DebugLogger, "ast/merge/debug_logger"
+    autoload :EmitterBase, "ast/merge/emitter_base"
     autoload :FileAnalyzable, "ast/merge/file_analyzable"
     autoload :Freezable, "ast/merge/freezable"
     autoload :FreezeNodeBase, "ast/merge/freeze_node_base"
@@ -154,7 +155,7 @@ module Ast
     autoload :NavigableStatement, "ast/merge/navigable_statement"
     autoload :NodeTyping, "ast/merge/node_typing"
     autoload :NodeWrapperBase, "ast/merge/node_wrapper_base"
-    autoload :PartialTemplateMerger, "ast/merge/partial_template_merger"
+    autoload :PartialTemplateMergerBase, "ast/merge/partial_template_merger_base"
     autoload :SectionTyping, "ast/merge/section_typing"
     autoload :SmartMergerBase, "ast/merge/smart_merger_base"
     autoload :Text, "ast/merge/text"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ast-merge
 version: !ruby/object:Gem::Version
-  version: 2.0.10
+  version: 3.1.0
 platform: ruby
 authors:
 - Peter H. Boling
@@ -63,20 +63,20 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.2'
+        version: '4.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.3
+        version: 4.0.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '3.2'
+        version: '4.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.2.3
+        version: 4.0.0
 - !ruby/object:Gem::Dependency
   name: kettle-dev
   requirement: !ruby/object:Gem::Requirement
@@ -309,6 +309,7 @@ files:
 - lib/ast/merge/detector/mergeable.rb
 - lib/ast/merge/detector/toml_frontmatter.rb
 - lib/ast/merge/detector/yaml_frontmatter.rb
+- lib/ast/merge/emitter_base.rb
 - lib/ast/merge/file_analyzable.rb
 - lib/ast/merge/freezable.rb
 - lib/ast/merge/freeze_node_base.rb
@@ -322,7 +323,7 @@ files:
 - lib/ast/merge/node_typing/normalizer.rb
 - lib/ast/merge/node_typing/wrapper.rb
 - lib/ast/merge/node_wrapper_base.rb
-- lib/ast/merge/partial_template_merger.rb
+- lib/ast/merge/partial_template_merger_base.rb
 - lib/ast/merge/recipe.rb
 - lib/ast/merge/recipe/config.rb
 - lib/ast/merge/recipe/preset.rb
@@ -356,10 +357,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://ast-merge.galtzo.com/
-  source_code_uri: https://github.com/kettle-rb/ast-merge/tree/v2.0.10
-  changelog_uri: https://github.com/kettle-rb/ast-merge/blob/v2.0.10/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-rb/ast-merge/tree/v3.1.0
+  changelog_uri: https://github.com/kettle-rb/ast-merge/blob/v3.1.0/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-rb/ast-merge/issues
-  documentation_uri: https://www.rubydoc.info/gems/ast-merge/2.0.10
+  documentation_uri: https://www.rubydoc.info/gems/ast-merge/3.1.0
   funding_uri: https://github.com/sponsors/pboling
   wiki_uri: https://github.com/kettle-rb/ast-merge/wiki
   news_uri: https://www.railsbling.com/tags/ast-merge