RubyGems - ast-merge - Versions diffs - 1.0.0 → 1.1.0 - Mend

ast-merge 1.0.0 → 1.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (25) hide show

checksums.yaml +4 -4
checksums.yaml.gz.sig +0 -0
data/CHANGELOG.md +35 -0
data/README.md +40 -27
data/lib/ast/merge/ast_node.rb +224 -24
data/lib/ast/merge/comment/block.rb +6 -0
data/lib/ast/merge/comment/empty.rb +6 -0
data/lib/ast/merge/comment/line.rb +6 -0
data/lib/ast/merge/comment/parser.rb +9 -7
data/lib/ast/merge/debug_logger.rb +4 -0
data/lib/ast/merge/fenced_code_block_detector.rb +102 -0
data/lib/ast/merge/file_analyzable.rb +5 -3
data/lib/ast/merge/freeze_node_base.rb +1 -1
data/lib/ast/merge/match_refiner_base.rb +1 -1
data/lib/ast/merge/match_score_base.rb +1 -1
data/lib/ast/merge/merger_config.rb +33 -31
data/lib/ast/merge/section_typing.rb +52 -50
data/lib/ast/merge/text/line_node.rb +42 -9
data/lib/ast/merge/text/section_splitter.rb +12 -10
data/lib/ast/merge/text/word_node.rb +47 -14
data/lib/ast/merge/version.rb +1 -1
data/lib/ast/merge/yaml_frontmatter_detector.rb +0 -20
data.tar.gz.sig +0 -0
metadata +24 -4
metadata.gz.sig +0 -0

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a871b962617929e2c8ed159fd0b971f0f45eb2ed023927fb7d07be2213c26b2f
-  data.tar.gz: 7dbc474b7d376d4388c00bae81e6bbeb8108faf37e19c6a2c6a87e045f09ad0f
+  metadata.gz: 86acfad0e867d5098d34fa4ec30fca07677e8b094a4bbeee27afa4dd236f6ba8
+  data.tar.gz: 61b3c5e9b24b4bc396dfa6562ebdf85d7a27153b67f96d53e977d04cc668c653
 SHA512:
-  metadata.gz: 9f91eb7a729e6c6c1dff895a715a01c6230ff97c4e87ee697ac5d7c01581f0bc94591c619bd00f5f1304209974d5d769336e89b032e8983a6e1c812cb799abe6
-  data.tar.gz: 48f14b886f7a2fb7fd547e9aee58cc28f6217193957271995b2917e295bab8d6b62faca337793278982c7f9d89e953aea6b6bb21ce6834ef5a20f1053769fd9b
+  metadata.gz: d610aa4ba48cd7b4476c041412dcb661761464a49966af6045af8f3c0e0a6f87cb75b89d1f706caa58505fab9cdbee9aa3681f9b615a79f6db3fb31f2f25aabb
+  data.tar.gz: 5dfbdb16cebda587a4c2a460b71a3a6a794ab6dcee048d293f1b39aa679291368e221348439974782ec2cfc5cfca3b9d4f62cb12b566931e34913dfc3a8790dc

checksums.yaml.gz.sig CHANGED Viewed

Binary file

data/CHANGELOG.md CHANGED Viewed

@@ -20,14 +20,49 @@ Please file a bug if you notice a violation of semantic versioning.
 ### Added
+- **tree_haver Integration**: Major architectural enhancement
+  - Added `tree_haver` (~> 3.1) as a runtime dependency
+  - `Ast::Merge::AstNode` now implements the TreeHaver::Node protocol for compatibility with tree_haver-based merge operations
+    - Adds: `type`, `kind`, `text`, `start_byte`, `end_byte`, `start_point`, `end_point`, `children`, `child_count`, `child(index)`, `each`, `named?`, `structural?`, `has_error?`, `missing?`, `inner_node`
+    - Adds `Point` struct compatible with `TreeHaver::Point`
+    - Adds `SyntheticNode` alias for clarity (synthetic = not backed by a real parser)
+  - `Comment::Line`, `Comment::Block`, `Comment::Empty` now have explicit `type` methods
+  - `Text::LineNode` and `Text::WordNode` now inherit from `AstNode`, gaining TreeHaver::Node protocol compliance
+  - This enables `*-merge` gems to leverage tree_haver's cross-Ruby parsing capabilities (MRI, JRuby, TruffleRuby)
+- **Documentation**: Comprehensive updates across the gem family
+  - Updated all vendor gem READMEs with standardized gem family tables
+  - Added `tree_haver` as the foundation layer in architecture documentation
+  - Clarified the two-layer architecture: tree_haver (parsing) → ast-merge (merge infrastructure)
+  - Added detailed documentation to `FencedCodeBlockDetector` explaining when to use native AST nodes vs text-based detection
+  - Updated markdown-merge documentation to highlight inner code block merging capabilities
+- **Example Scripts**: Added comprehensive examples demonstrating inner-merge capabilities
+  - `examples/markdown_code_merge.rb` - Shows how markdown-merge delegates to language-specific parsers for semantic merging
+  - Documentation proving that language-specific parsers create full ASTs of embedded code blocks
 ### Changed
+- **Architecture**: Refactored to use tree_haver as the parsing foundation
+  - All tree-sitter-based gems (bash-merge, json-merge, jsonc-merge, toml-merge) now use tree_haver
+  - Parser-specific gems (prism-merge, psych-merge, markdown-merge, markly-merge, commonmarker-merge) use tree_haver backends
+  - Provides unified API across different Ruby implementations and parsing backends
+- **Documentation Structure**: Standardized gem family tables across all 12 vendor gems
+  - Changed from 3-column to 4-column format: Gem | Format | Parser Backend(s) | Description
+  - All parser backends now annotated with "(via tree_haver)" where applicable
+  - ast-merge description updated from "Shared infrastructure" to "**Infrastructure**: Shared base classes and merge logic"
+  - markdown-merge description updated to "**Foundation**: Shared base for Markdown mergers with inner code block merging"
+- **Configuration Documentation**: Enhanced backend selection documentation
 ### Deprecated
 ### Removed
 ### Fixed
+- Fixed gemspec and Appraisals alignment with tree_haver requirements
+- Fixed CI workflow conditions and retry logic
+- Fixed badge rendering in documentation
+- Fixed README structure issues (removed H3 duplicates, standardized gem family tables)
 ### Security
 ## [1.0.0] - 2025-12-12

data/README.md CHANGED Viewed

@@ -42,7 +42,7 @@
 # ☯️ Ast::Merge
-[![Version][👽versioni]][👽version] [![GitHub tag (latest SemVer)][⛳️tag-img]][⛳️tag] [![License: MIT][📄license-img]][📄license-ref] [![Downloads Rank][👽dl-ranki]][👽dl-rank] [![Open Source Helpers][👽oss-helpi]][👽oss-help] [![CodeCov Test Coverage][🏀codecovi]][🏀codecov] [![Coveralls Test Coverage][🏀coveralls-img]][🏀coveralls] [![QLTY Test Coverage][🏀qlty-covi]][🏀qlty-cov] [![QLTY Maintainability][🏀qlty-mnti]][🏀qlty-mnt] [![CI Heads][🚎3-hd-wfi]][🚎3-hd-wf] [![CI Runtime Dependencies @ HEAD][🚎12-crh-wfi]][🚎12-crh-wf] [![CI Current][🚎11-c-wfi]][🚎11-c-wf] [![CI Truffle Ruby][🚎9-t-wfi]][🚎9-t-wf] [![CI JRuby][🚎10-j-wfi]][🚎10-j-wf] [![Deps Locked][🚎13-🔒️-wfi]][🚎13-🔒️-wf] [![Deps Unlocked][🚎14-🔓️-wfi]][🚎14-🔓️-wf] [![CI Supported][🚎6-s-wfi]][🚎6-s-wf] [![CI Legacy][🚎4-lg-wfi]][🚎4-lg-wf] [![CI Unsupported][🚎7-us-wfi]][🚎7-us-wf] [![CI Ancient][🚎1-an-wfi]][🚎1-an-wf] [![CI Test Coverage][🚎2-cov-wfi]][🚎2-cov-wf] [![CI Style][🚎5-st-wfi]][🚎5-st-wf] [![CodeQL][🖐codeQL-img]][🖐codeQL] [![Apache SkyWalking Eyes License Compatibility Check][🚎15-🪪-wfi]][🚎15-🪪-wf]
+[![Version][👽versioni]][👽version] [![GitHub tag (latest SemVer)][⛳️tag-img]][⛳️tag] [![License: MIT][📄license-img]][📄license-ref] [![Downloads Rank][👽dl-ranki]][👽dl-rank] [![Open Source Helpers][👽oss-helpi]][👽oss-help] [![CodeCov Test Coverage][🏀codecovi]][🏀codecov] [![Coveralls Test Coverage][🏀coveralls-img]][🏀coveralls] [![QLTY Test Coverage][🏀qlty-covi]][🏀qlty-cov] [![QLTY Maintainability][🏀qlty-mnti]][🏀qlty-mnt] [![CI Heads][🚎3-hd-wfi]][🚎3-hd-wf] [![CI Runtime Dependencies @ HEAD][🚎12-crh-wfi]][🚎12-crh-wf] [![CI Current][🚎11-c-wfi]][🚎11-c-wf] [![CI Truffle Ruby][🚎9-t-wfi]][🚎9-t-wf] [![Deps Locked][🚎13-🔒️-wfi]][🚎13-🔒️-wf] [![Deps Unlocked][🚎14-🔓️-wfi]][🚎14-🔓️-wf] [![CI Supported][🚎6-s-wfi]][🚎6-s-wf] [![CI Test Coverage][🚎2-cov-wfi]][🚎2-cov-wf] [![CI Style][🚎5-st-wfi]][🚎5-st-wf] [![CodeQL][🖐codeQL-img]][🖐codeQL] [![Apache SkyWalking Eyes License Compatibility Check][🚎15-🪪-wfi]][🚎15-🪪-wf]
 `if ci_badges.map(&:color).detect { it != "green"}` ☝️ [let me know][🖼️galtzo-discord], as I may have missed the [discord notification][🖼️galtzo-discord].
@@ -58,20 +58,23 @@ Ast::Merge is **not typically used directly** - instead, use one of the format-s
 ### The `*-merge` Gem Family
-| Gem | Format | Parser | Description |
-|-----|--------|--------|-------------|
-| [ast-merge][ast-merge] | Text | internal | Shared infrastructure for all `*-merge` gems |
-| [prism-merge][prism-merge] | Ruby | [Prism][prism] | Smart merge for Ruby source files |
-| [psych-merge][psych-merge] | YAML | [Psych][psych] | Smart merge for YAML files |
-| [json-merge][json-merge] | JSON | [tree-sitter-json][ts-json] | Smart merge for JSON files |
-| [jsonc-merge][jsonc-merge] | JSONC | [tree-sitter-jsonc][ts-jsonc] | ⚠️ Proof of concept; Smart merge for JSON with Comments |
-| [bash-merge][bash-merge] | Bash | [tree-sitter-bash][ts-bash] | Smart merge for Bash scripts |
+The `*-merge` gem family provides intelligent, AST-based merging for various file formats. At the foundation is [tree_haver][tree_haver], which provides a unified cross-Ruby parsing API that works seamlessly across MRI, JRuby, and TruffleRuby.
+| Gem | Format | Parser Backend(s) | Description |
+|-----|--------|-------------------|-------------|
+| [tree_haver][tree_haver] | Multi | MRI C, Rust, FFI, Java, Prism, Psych, Commonmarker, Markly, Citrus | **Foundation**: Cross-Ruby adapter for parsing libraries (like Faraday for HTTP) |
+| [ast-merge][ast-merge] | Text | internal | **Infrastructure**: Shared base classes and merge logic for all `*-merge` gems |
+| [prism-merge][prism-merge] | Ruby | [Prism][prism] (via tree_haver) | Smart merge for Ruby source files |
+| [psych-merge][psych-merge] | YAML | [Psych][psych] (via tree_haver) | Smart merge for YAML files |
+| [json-merge][json-merge] | JSON | [tree-sitter-json][ts-json] (via tree_haver) | Smart merge for JSON files |
+| [jsonc-merge][jsonc-merge] | JSONC | [tree-sitter-jsonc][ts-jsonc] (via tree_haver) | ⚠️ Proof of concept; Smart merge for JSON with Comments |
+| [bash-merge][bash-merge] | Bash | [tree-sitter-bash][ts-bash] (via tree_haver) | Smart merge for Bash scripts |
 | [rbs-merge][rbs-merge] | RBS | [RBS][rbs] | Smart merge for Ruby type signatures |
 | [dotenv-merge][dotenv-merge] | Dotenv | internal ([dotenv][dotenv]) | Smart merge for `.env` files |
-| [toml-merge][toml-merge] | TOML | [tree-sitter-toml][ts-toml] | Smart merge for TOML files |
-| [markdown-merge][markdown-merge] | Markdown | _base classes_ | Shared foundation for Markdown mergers |
-| [markly-merge][markly-merge] | Markdown | [Markly][markly] | Smart merge for Markdown (CommonMark via libcmark-gfm) |
-| [commonmarker-merge][commonmarker-merge] | Markdown | [Commonmarker][commonmarker] | Smart merge for Markdown (CommonMark via comrak) |
+| [toml-merge][toml-merge] | TOML | [tree-sitter-toml][ts-toml] (via tree_haver) | Smart merge for TOML files |
+| [markdown-merge][markdown-merge] | Markdown | [Commonmarker][commonmarker] / [Markly][markly] (via tree_haver) | **Foundation**: Shared base for Markdown mergers with inner code block merging |
+| [markly-merge][markly-merge] | Markdown | [Markly][markly] (via tree_haver) | Smart merge for Markdown (CommonMark via cmark-gfm C) |
+| [commonmarker-merge][commonmarker-merge] | Markdown | [Commonmarker][commonmarker] (via tree_haver) | Smart merge for Markdown (CommonMark via comrak Rust) |
 **Example implementations** for the gem templating use case:
@@ -80,6 +83,7 @@ Ast::Merge is **not typically used directly** - instead, use one of the format-s
 | [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
 [prism-merge]: https://github.com/kettle-rb/prism-merge
 [psych-merge]: https://github.com/kettle-rb/psych-merge
@@ -102,15 +106,34 @@ Ast::Merge is **not typically used directly** - instead, use one of the format-s
 [ts-toml]: https://github.com/tree-sitter-grammars/tree-sitter-toml
 [rbs]: https://github.com/ruby/rbs
 [dotenv]: https://github.com/bkeepers/dotenv
-[markly]: https://github.com/kivikakk/markly
+[markly]: https://github.com/ioquatix/markly
 [commonmarker]: https://github.com/gjtorikian/commonmarker
-### What Ast::Merge Provides
+### Architecture: tree_haver + ast-merge
+The `*-merge` gem family is built on a two-layer architecture:
+#### Layer 1: tree_haver (Parsing Foundation)
+[tree_haver][tree_haver] provides cross-Ruby parsing capabilities:
+- **Universal Backend Support**: Automatically selects the best parsing backend for your Ruby implementation (MRI, JRuby, TruffleRuby)
+- **10 Backend Options**: MRI C extensions, Rust bindings, FFI, Java (JRuby), language-specific parsers (Prism, Psych, Commonmarker, Markly), and pure Ruby fallback (Citrus)
+- **Unified API**: Write parsing code once, run on any Ruby implementation
+- **Grammar Discovery**: Built-in `GrammarFinder` for platform-aware grammar library discovery
+- **Thread-Safe**: Language registry with thread-safe caching
+#### Layer 2: ast-merge (Merge Infrastructure)
+Ast::Merge builds on tree_haver to provide:
 - **Base Classes**: `FreezeNode`, `MergeResult` base classes with unified constructors
-- **Shared Modules**: `FileAnalysisBase`, `MergerConfig`, `DebugLogger`
-- **Freeze Block Support**: Configurable marker patterns for multiple comment syntaxes
+- **Shared Modules**: `FileAnalysisBase`, `FileAnalyzable`, `MergerConfig`, `DebugLogger`
+- **Freeze Block Support**: Configurable marker patterns for multiple comment syntaxes (preserve sections during merge)
+- **Node Typing System**: `NodeTyping` for canonical node type identification across different parsers
+- **Conflict Resolution**: `ConflictResolverBase` with pluggable strategies
 - **Error Classes**: `ParseError`, `TemplateParseError`, `DestinationParseError`
+- **Region Detection**: `RegionDetectorBase`, `FencedCodeBlockDetector` for text-based analysis
 - **RSpec Shared Examples**: Test helpers for implementing new merge gems
 ### Creating a New Merge Gem
@@ -765,26 +788,16 @@ Thanks for RTFM. ☺️
 [🏀coveralls-img]: https://coveralls.io/repos/github/kettle-rb/ast-merge/badge.svg?branch=main
 [🖐codeQL]: https://github.com/kettle-rb/ast-merge/security/code-scanning
 [🖐codeQL-img]: https://github.com/kettle-rb/ast-merge/actions/workflows/codeql-analysis.yml/badge.svg
-[🚎1-an-wf]: https://github.com/kettle-rb/ast-merge/actions/workflows/ancient.yml
-[🚎1-an-wfi]: https://github.com/kettle-rb/ast-merge/actions/workflows/ancient.yml/badge.svg
 [🚎2-cov-wf]: https://github.com/kettle-rb/ast-merge/actions/workflows/coverage.yml
 [🚎2-cov-wfi]: https://github.com/kettle-rb/ast-merge/actions/workflows/coverage.yml/badge.svg
 [🚎3-hd-wf]: https://github.com/kettle-rb/ast-merge/actions/workflows/heads.yml
 [🚎3-hd-wfi]: https://github.com/kettle-rb/ast-merge/actions/workflows/heads.yml/badge.svg
-[🚎4-lg-wf]: https://github.com/kettle-rb/ast-merge/actions/workflows/legacy.yml
-[🚎4-lg-wfi]: https://github.com/kettle-rb/ast-merge/actions/workflows/legacy.yml/badge.svg
 [🚎5-st-wf]: https://github.com/kettle-rb/ast-merge/actions/workflows/style.yml
 [🚎5-st-wfi]: https://github.com/kettle-rb/ast-merge/actions/workflows/style.yml/badge.svg
 [🚎6-s-wf]: https://github.com/kettle-rb/ast-merge/actions/workflows/supported.yml
 [🚎6-s-wfi]: https://github.com/kettle-rb/ast-merge/actions/workflows/supported.yml/badge.svg
-[🚎7-us-wf]: https://github.com/kettle-rb/ast-merge/actions/workflows/unsupported.yml
-[🚎7-us-wfi]: https://github.com/kettle-rb/ast-merge/actions/workflows/unsupported.yml/badge.svg
-[🚎8-ho-wf]: https://github.com/kettle-rb/ast-merge/actions/workflows/hoary.yml
-[🚎8-ho-wfi]: https://github.com/kettle-rb/ast-merge/actions/workflows/hoary.yml/badge.svg
 [🚎9-t-wf]: https://github.com/kettle-rb/ast-merge/actions/workflows/truffle.yml
 [🚎9-t-wfi]: https://github.com/kettle-rb/ast-merge/actions/workflows/truffle.yml/badge.svg
-[🚎10-j-wf]: https://github.com/kettle-rb/ast-merge/actions/workflows/jruby.yml
-[🚎10-j-wfi]: https://github.com/kettle-rb/ast-merge/actions/workflows/jruby.yml/badge.svg
 [🚎11-c-wf]: https://github.com/kettle-rb/ast-merge/actions/workflows/current.yml
 [🚎11-c-wfi]: https://github.com/kettle-rb/ast-merge/actions/workflows/current.yml/badge.svg
 [🚎12-crh-wf]: https://github.com/kettle-rb/ast-merge/actions/workflows/dep-heads.yml

data/lib/ast/merge/ast_node.rb CHANGED Viewed

@@ -2,27 +2,78 @@
 module Ast
   module Merge
-    # Base class for AST nodes in the ast-merge framework.
+    # Base class for synthetic AST nodes in the ast-merge framework.
     #
-    # This provides a common API that works across different AST implementations
-    # (Prism, TreeSitter, custom comment nodes, etc.) enabling uniform handling
-    # in merge operations.
+    # "Synthetic" nodes are nodes that aren't backed by a real parser - they're
+    # created by ast-merge for representing content that doesn't have a native
+    # AST (comments, text lines, env file entries, etc.).
     #
-    # Subclasses should implement:
-    # - #slice - returns the source text for the node
-    # - #location - returns an object responding to start_line/end_line
-    # - #children - returns child nodes (empty array for leaf nodes)
-    # - #signature - returns a signature array for matching (optional, can use default)
+    # This class implements the TreeHaver::Node protocol, making it compatible
+    # with all code that expects TreeHaver nodes. This allows synthetic nodes
+    # to be used interchangeably with parser-backed nodes in merge operations.
     #
-    # @abstract
+    # Implements the TreeHaver::Node protocol:
+    # - type → String node type
+    # - text / slice → Source text content
+    # - start_byte / end_byte → Byte offsets
+    # - start_point / end_point → Point (row, column)
+    # - children → Array of child nodes
+    # - named? / structural? → Node classification
+    # - inner_node → Returns self (no wrapping layer for synthetic nodes)
+    #
+    # Adds merge-specific methods:
+    # - signature → Array used for matching nodes across files
+    # - normalized_content → Cleaned text for comparison
+    #
+    # @example Subclassing for custom node types
+    #   class MyNode < AstNode
+    #     def type
+    #       "my_node"
+    #     end
+    #
+    #     def signature
+    #       [:my_node, normalized_content]
+    #     end
+    #   end
+    #
+    # @see TreeHaver::Node The protocol this class implements
+    # @see Comment::Line Example synthetic node for comments
+    # @see Text::LineNode Example synthetic node for text lines
     class AstNode
-      # Simple location struct for nodes that don't have a native location object
+      include Comparable
+      # Point class compatible with TreeHaver::Point
+      # Provides both method and hash-style access to row/column
+      Point = Struct.new(:row, :column, keyword_init: true) do
+        # Hash-like access for compatibility
+        def [](key)
+          case key
+          when :row, "row" then row
+          when :column, "column" then column
+          end
+        end
+        def to_h
+          {row: row, column: column}
+        end
+        def to_s
+          "(#{row}, #{column})"
+        end
+        def inspect
+          "#<Ast::Merge::AstNode::Point row=#{row} column=#{column}>"
+        end
+      end
+      # Location struct for tracking source positions
+      # Compatible with TreeHaver location expectations
       Location = Struct.new(:start_line, :end_line, :start_column, :end_column, keyword_init: true) do
         # Check if a line number falls within this location
-        # @param line_number [Integer] The line number to check
+        # @param line_number [Integer] The line number to check (1-based)
         # @return [Boolean] true if the line number is within the range
         def cover?(line_number)
-          line_number >= start_line && line_number <= end_line
+          line_number.between?(start_line, end_line)
         end
       end
@@ -32,28 +83,164 @@ module Ast
       # @return [String] The source text for this node
       attr_reader :slice
+      # @return [String, nil] The full source text (for text extraction)
+      attr_reader :source
       # Initialize a new AstNode.
       #
       # @param slice [String] The source text for this node
-      # @param location [Location, #start_line] Location object or anything responding to start_line/end_line
-      def initialize(slice:, location:)
+      # @param location [Location, #start_line] Location object
+      # @param source [String, nil] Full source text (optional)
+      def initialize(slice:, location:, source: nil)
         @slice = slice
         @location = location
+        @source = source
       end
+      # TreeHaver::Node protocol: inner_node
+      # For synthetic nodes, this returns self (no wrapping layer)
+      #
+      # @return [AstNode] self
+      def inner_node
+        self
+      end
+      # TreeHaver::Node protocol: type
+      # Returns the node type as a string.
+      # Subclasses should override this with specific type names.
+      #
+      # @return [String] Node type
+      def type
+        # Default: derive from class name (MyNode → "my_node")
+        self.class.name.split("::").last
+          .gsub(/([A-Z])/, '_\1')
+          .downcase
+          .sub(/^_/, "")
+      end
+      # Alias for tree-sitter compatibility
+      alias_method :kind, :type
+      # TreeHaver::Node protocol: text
+      # @return [String] The source text
+      def text
+        slice.to_s
+      end
+      # TreeHaver::Node protocol: start_byte
+      # Calculates byte offset from source if available, otherwise estimates from lines
+      #
+      # @return [Integer] Starting byte offset
+      def start_byte
+        return 0 unless source && location
+        # Calculate byte offset from line/column
+        lines = source.lines
+        byte_offset = 0
+        (0...(location.start_line - 1)).each do |i|
+          byte_offset += lines[i]&.bytesize || 0
+        end
+        byte_offset + (location.start_column || 0)
+      end
+      # TreeHaver::Node protocol: end_byte
+      #
+      # @return [Integer] Ending byte offset
+      def end_byte
+        start_byte + slice.to_s.bytesize
+      end
+      # TreeHaver::Node protocol: start_point
+      # Returns a Point with row (0-based) and column
+      #
+      # @return [Point] Starting position
+      def start_point
+        Point.new(
+          row: (location&.start_line || 1) - 1,  # Convert to 0-based
+          column: location&.start_column || 0,
+        )
+      end
+      # TreeHaver::Node protocol: end_point
+      # Returns a Point with row (0-based) and column
+      #
+      # @return [Point] Ending position
+      def end_point
+        Point.new(
+          row: (location&.end_line || 1) - 1,  # Convert to 0-based
+          column: location&.end_column || 0,
+        )
+      end
+      # TreeHaver::Node protocol: children
       # @return [Array<AstNode>] Child nodes (empty for leaf nodes)
       def children
         []
       end
+      # TreeHaver::Node protocol: child_count
+      # @return [Integer] Number of children
+      def child_count
+        children.size
+      end
+      # TreeHaver::Node protocol: child(index)
+      # @param index [Integer] Child index
+      # @return [AstNode, nil] Child at index
+      def child(index)
+        children[index]
+      end
+      # TreeHaver::Node protocol: named?
+      # Synthetic nodes are always "named" (structural) nodes
+      #
+      # @return [Boolean] true
+      def named?
+        true
+      end
+      # TreeHaver::Node protocol: structural?
+      # Synthetic nodes are always structural
+      #
+      # @return [Boolean] true
+      def structural?
+        true
+      end
+      # TreeHaver::Node protocol: has_error?
+      # Synthetic nodes don't have parse errors
+      #
+      # @return [Boolean] false
+      def has_error?
+        false
+      end
+      # TreeHaver::Node protocol: missing?
+      # Synthetic nodes are never "missing"
+      #
+      # @return [Boolean] false
+      def missing?
+        false
+      end
+      # TreeHaver::Node protocol: each
+      # Iterate over children
+      #
+      # @yield [AstNode] Each child node
+      # @return [Enumerator, nil]
+      def each(&block)
+        return to_enum(__method__) unless block_given?
+        children.each(&block)
+      end
       # Generate a signature for this node for matching purposes.
       #
       # Override in subclasses for custom signature logic.
-      # Default returns the node class name and a normalized form of the slice.
+      # Default returns the node type and a normalized form of the slice.
       #
       # @return [Array] Signature array for matching
       def signature
-        [self.class.name, normalized_content]
+        [type.to_sym, normalized_content]
       end
       # @return [String] Normalized content for signature comparison
@@ -61,9 +248,22 @@ module Ast
         slice.to_s.strip
       end
+      # Comparable: compare nodes by position
+      #
+      # @param other [AstNode] node to compare with
+      # @return [Integer, nil] -1, 0, 1, or nil if not comparable
+      def <=>(other)
+        return unless other.respond_to?(:start_byte) && other.respond_to?(:end_byte)
+        cmp = start_byte <=> other.start_byte
+        return cmp if cmp.nonzero?
+        end_byte <=> other.end_byte
+      end
       # @return [String] Human-readable representation
       def inspect
-        "#<#{self.class.name} lines=#{location.start_line}..#{location.end_line} slice=#{slice.to_s[0..50].inspect}>"
+        "#<#{self.class.name} type=#{type} lines=#{location&.start_line}..#{location&.end_line}>"
       end
       # @return [String] The source text
@@ -76,12 +276,12 @@ module Ast
       def unwrap
         self
       end
-      # Check if this node responds to the Prism-style location API
-      # @return [Boolean] true
-      def respond_to_missing?(method, include_private = false)
-        [:location, :slice].include?(method) || super
-      end
     end
+    # Alias for clarity - SyntheticNode clearly indicates "not backed by a real parser"
+    # Use this alias when the distinction between synthetic and parser-backed nodes matters.
+    #
+    # @see AstNode
+    SyntheticNode = AstNode
   end
 end

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

@@ -41,6 +41,12 @@ module Ast
         # @return [Style] The comment style configuration
         attr_reader :style
+        # TreeHaver::Node protocol: type
+        # @return [String] "comment_block"
+        def type
+          "comment_block"
+        end
         # Initialize a new Block.
         #
         # For line-based comments, pass `children` array.

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

@@ -28,6 +28,12 @@ module Ast
         # @return [String] The actual line content (may have whitespace)
         attr_reader :text
+        # TreeHaver::Node protocol: type
+        # @return [String] "empty_line"
+        def type
+          "empty_line"
+        end
         # Initialize a new Empty line.
         #
         # @param line_number [Integer] The 1-based line number

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

@@ -38,6 +38,12 @@ module Ast
         # @return [Style] The comment style configuration
         attr_reader :style
+        # TreeHaver::Node protocol: type
+        # @return [String] "comment_line"
+        def type
+          "comment_line"
+        end
         # Initialize a new Line.
         #
         # @param text [String] The full comment text including delimiter

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

@@ -69,13 +69,15 @@ module Ast
           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
+        class << self
+          # Parse lines as comments.
+          #
+          # @param lines [Array<String>] Source lines
+          # @param style [Style, Symbol, nil] Comment style
+          # @return [Array<AstNode>] Parsed nodes
+          def parse(lines, style: nil)
+            new(lines, style: style).parse
+          end
         end
         private

data/lib/ast/merge/debug_logger.rb CHANGED Viewed

@@ -83,10 +83,14 @@ module Ast
       class << self
         # @return [String] Environment variable name to check for debug mode
+        # rubocop:disable ThreadSafety/ClassAndModuleAttributes - Configuration attribute, set once at load time
         attr_accessor :env_var_name
+        # rubocop:enable ThreadSafety/ClassAndModuleAttributes
         # @return [String] Prefix for log messages
+        # rubocop:disable ThreadSafety/ClassAndModuleAttributes - Configuration attribute, set once at load time
         attr_accessor :log_prefix
+        # rubocop:enable ThreadSafety/ClassAndModuleAttributes
         # Hook called when a module extends Ast::Merge::DebugLogger.
         # Sets up attr_accessor for env_var_name and log_prefix on the extending module,

data/lib/ast/merge/fenced_code_block_detector.rb CHANGED Viewed

@@ -8,6 +8,108 @@ module Ast
     # that have a specific language identifier. It can be configured for any
     # language: ruby, json, yaml, mermaid, etc.
     #
+    # ## When to Use This Detector
+    #
+    # **Use FencedCodeBlockDetector when:**
+    # - Working with raw Markdown text without parsing to AST
+    # - Quick extraction from strings without parser dependencies
+    # - Custom text processing requiring line-level precision
+    # - Operating on source text directly (e.g., linters, formatters)
+    #
+    # **Do NOT use FencedCodeBlockDetector when:**
+    # - Working with parsed Markdown AST (use native code block nodes instead)
+    # - Integrating with markdown-merge's CodeBlockMerger (it uses native nodes)
+    # - Using tree_haver's unified Markdown backend API
+    #
+    # ## Comparison: FencedCodeBlockDetector vs Native AST Nodes
+    #
+    # ### Native AST Approach (Preferred for AST-based Tools)
+    #
+    # When working with parsed Markdown AST via tree_haver (commonmarker/markly backends):
+    #
+    # ```ruby
+    # # markdown-merge's CodeBlockMerger uses this approach:
+    # language = node.fence_info.split(/\s+/).first  # e.g., "ruby"
+    # content = node.string_content                   # Raw code inside block
+    #
+    # # Then delegate to language-specific parser:
+    # case language
+    # when "ruby"
+    #   merger = Prism::Merge::SmartMerger.new(template, dest, preference: :destination)
+    #   merged_content = merger.merge  # Prism parses Ruby code into full AST!
+    # when "yaml"
+    #   merger = Psych::Merge::SmartMerger.new(template, dest, preference: :destination)
+    #   merged_content = merger.merge  # Psych parses YAML into AST!
+    # when "json"
+    #   merger = Json::Merge::SmartMerger.new(template, dest, preference: :destination)
+    #   merged_content = merger.merge  # JSON parser creates AST!
+    # when "bash"
+    #   merger = Bash::Merge::SmartMerger.new(template, dest, preference: :destination)
+    #   merged_content = merger.merge  # tree-sitter parses bash into AST!
+    # end
+    # ```
+    #
+    # **Advantages of Native AST approach:**
+    # - ✓ Parser handles all edge cases (nested backticks, indentation, etc.)
+    # - ✓ Respects node boundaries from authoritative source
+    # - ✓ No regex brittleness
+    # - ✓ Automatic handling of ``` and ~~~ fence styles
+    # - ✓ Enables TRUE language-aware merging (not just text replacement)
+    # - ✓ Language-specific parsers create full ASTs of embedded code
+    # - ✓ Smart merging at semantic level (method definitions, YAML keys, JSON properties)
+    #
+    # ### Text-Based Approach (This Class)
+    #
+    # When working with raw text:
+    #
+    # ```ruby
+    # detector = FencedCodeBlockDetector.ruby
+    # regions = detector.detect_all(markdown_text)
+    # regions.each do |region|
+    #   puts "Ruby code at lines #{region.start_line}-#{region.end_line}"
+    #   # region.content is just a string - NO parsing happens
+    # end
+    # ```
+    #
+    # **Limitations of text-based approach:**
+    # - • Uses regex to find blocks (may miss edge cases)
+    # - • Returns strings, not parsed structures
+    # - • Cannot perform semantic merging
+    # - • Manual handling of fence variations
+    # - • No language-specific intelligence
+    #
+    # ## Real-World Example: markdown-merge Inner Code Block Merging
+    #
+    # When `inner_merge_code_blocks: true` is enabled in markdown-merge:
+    #
+    # 1. **Markdown Parser** (commonmarker/markly) parses markdown into AST
+    #    - Creates code_block nodes with `fence_info` and `string_content`
+    #
+    # 2. **CodeBlockMerger** extracts code using native node properties:
+    #    ```ruby
+    #    language = node.fence_info.split(/\s+/).first
+    #    template_code = template_node.string_content
+    #    dest_code = dest_node.string_content
+    #    ```
+    #
+    # 3. **Language-Specific Parser** creates FULL AST of the embedded code:
+    #    - `Prism::Merge` → Prism parses Ruby into complete AST (ClassNode, DefNode, etc.)
+    #    - `Psych::Merge` → Psych parses YAML into document structure
+    #    - `Json::Merge` → JSON parser creates object/array tree
+    #    - `Bash::Merge` → tree-sitter creates bash statement AST
+    #
+    # 4. **Smart Merger** performs SEMANTIC merging at AST level:
+    #    - Ruby: Merges class definitions, preserves custom methods
+    #    - YAML: Merges keys, preserves custom configuration values
+    #    - JSON: Merges objects, destination values win on conflicts
+    #    - Bash: Merges statements, preserves custom exports
+    #
+    # 5. **Result** is intelligently merged code, not simple text concatenation!
+    #
+    # **This means:** The embedded code is FULLY PARSED by its native language parser,
+    # enabling true semantic-level merging. FencedCodeBlockDetector would only find
+    # the text boundaries - it cannot perform this semantic merging.
+    #
     # @example Detecting Ruby code blocks
     #   detector = FencedCodeBlockDetector.new("ruby", aliases: ["rb"])
     #   regions = detector.detect_all(markdown_source)

data/lib/ast/merge/file_analyzable.rb CHANGED Viewed

@@ -48,9 +48,11 @@ module Ast
       #   @return [String] Token used to mark freeze blocks (e.g., "prism-merge", "psych-merge")
       # @!attribute [r] signature_generator
       #   @return [Proc, nil] Custom signature generator, or nil to use default
-      def self.included(base)
-        base.class_eval do
-          attr_reader(:source, :lines, :freeze_token, :signature_generator)
+      class << self
+        def included(base)
+          base.class_eval do
+            attr_reader(:source, :lines, :freeze_token, :signature_generator)
+          end
         end
       end

data/lib/ast/merge/freeze_node_base.rb CHANGED Viewed

@@ -379,7 +379,7 @@ module Ast
       # Validate that end_line is not before start_line
       # @raise [InvalidStructureError] if structure is invalid
       def validate_line_order!
-        return unless @end_line < @start_line
+        return if @end_line >= @start_line
         raise InvalidStructureError.new(
           "Freeze block end line (#{@end_line}) is before start line (#{@start_line})",

data/lib/ast/merge/match_refiner_base.rb CHANGED Viewed

@@ -169,7 +169,7 @@ module Ast
       # @param threshold [Float] Minimum score to accept a match (0.0-1.0)
       # @param node_types [Array<Symbol>] Node types to process (empty = all)
       def initialize(threshold: DEFAULT_THRESHOLD, node_types: [])
-        @threshold = [[threshold.to_f, 0.0].max, 1.0].min
+        @threshold = threshold.to_f.clamp(0.0, 1.0)
         @node_types = Array(node_types)
       end

data/lib/ast/merge/match_score_base.rb CHANGED Viewed

@@ -128,7 +128,7 @@ module Ast
       def compute_score
         result = algorithm.call(node_a, node_b)
         # Clamp to valid range
-        [[result.to_f, 0.0].max, 1.0].min
+        result.to_f.clamp(0.0, 1.0)
       end
     end
   end

data/lib/ast/merge/merger_config.rb CHANGED Viewed

@@ -193,38 +193,40 @@ module Ast
         )
       end
-      # Create a config preset for "destination wins" merging.
-      # Destination customizations are preserved, template-only content is skipped.
-      #
-      # @param freeze_token [String, nil] Optional freeze token
-      # @param signature_generator [Proc, nil] Optional signature generator
-      # @param node_typing [Hash, nil] Optional node typing configuration
-      # @return [MergerConfig] Config preset
-      def self.destination_wins(freeze_token: nil, signature_generator: nil, node_typing: nil)
-        new(
-          preference: :destination,
-          add_template_only_nodes: false,
-          freeze_token: freeze_token,
-          signature_generator: signature_generator,
-          node_typing: node_typing,
-        )
-      end
+      class << self
+        # Create a config preset for "destination wins" merging.
+        # Destination customizations are preserved, template-only content is skipped.
+        #
+        # @param freeze_token [String, nil] Optional freeze token
+        # @param signature_generator [Proc, nil] Optional signature generator
+        # @param node_typing [Hash, nil] Optional node typing configuration
+        # @return [MergerConfig] Config preset
+        def destination_wins(freeze_token: nil, signature_generator: nil, node_typing: nil)
+          new(
+            preference: :destination,
+            add_template_only_nodes: false,
+            freeze_token: freeze_token,
+            signature_generator: signature_generator,
+            node_typing: node_typing,
+          )
+        end
-      # Create a config preset for "template wins" merging.
-      # Template updates are applied, template-only content is added.
-      #
-      # @param freeze_token [String, nil] Optional freeze token
-      # @param signature_generator [Proc, nil] Optional signature generator
-      # @param node_typing [Hash, nil] Optional node typing configuration
-      # @return [MergerConfig] Config preset
-      def self.template_wins(freeze_token: nil, signature_generator: nil, node_typing: nil)
-        new(
-          preference: :template,
-          add_template_only_nodes: true,
-          freeze_token: freeze_token,
-          signature_generator: signature_generator,
-          node_typing: node_typing,
-        )
+        # Create a config preset for "template wins" merging.
+        # Template updates are applied, template-only content is added.
+        #
+        # @param freeze_token [String, nil] Optional freeze token
+        # @param signature_generator [Proc, nil] Optional signature generator
+        # @param node_typing [Hash, nil] Optional node typing configuration
+        # @return [MergerConfig] Config preset
+        def template_wins(freeze_token: nil, signature_generator: nil, node_typing: nil)
+          new(
+            preference: :template,
+            add_template_only_nodes: true,
+            freeze_token: freeze_token,
+            signature_generator: signature_generator,
+            node_typing: node_typing,
+          )
+        end
       end
       private

data/lib/ast/merge/section_typing.rb CHANGED Viewed

@@ -235,68 +235,70 @@ module Ast
       # Merge typed sections from template and destination.
       #
       # Similar to `Text::SectionSplitter#merge_section_lists` but works with
-      # TypedSection objects wrapping AST nodes.
-      #
-      # @param template_sections [Array<TypedSection>] Sections from template
-      # @param dest_sections [Array<TypedSection>] Sections from destination
-      # @param preference [Symbol, Hash] Merge preference (:template, :destination, or per-section Hash)
-      # @param add_template_only [Boolean] Whether to add sections only in template
-      # @return [Array<TypedSection>] Merged sections
-      def self.merge_sections(template_sections, dest_sections, preference: :destination, add_template_only: false)
-        dest_by_name = dest_sections.each_with_object({}) do |section, hash|
-          key = section.normalized_name
-          hash[key] = section unless section.unclassified?
-        end
+      class << self
+        # TypedSection objects wrapping AST nodes.
+        #
+        # @param template_sections [Array<TypedSection>] Sections from template
+        # @param dest_sections [Array<TypedSection>] Sections from destination
+        # @param preference [Symbol, Hash] Merge preference (:template, :destination, or per-section Hash)
+        # @param add_template_only [Boolean] Whether to add sections only in template
+        # @return [Array<TypedSection>] Merged sections
+        def merge_sections(template_sections, dest_sections, preference: :destination, add_template_only: false)
+          dest_by_name = dest_sections.each_with_object({}) do |section, hash|
+            key = section.normalized_name
+            hash[key] = section unless section.unclassified?
+          end
-        merged = []
-        seen_names = Set.new
+          merged = []
+          seen_names = Set.new
-        template_sections.each do |template_section|
-          if template_section.unclassified?
-            # Unclassified sections are typically kept as-is or merged specially
-            merged << template_section if add_template_only
-            next
-          end
+          template_sections.each do |template_section|
+            if template_section.unclassified?
+              # Unclassified sections are typically kept as-is or merged specially
+              merged << template_section if add_template_only
+              next
+            end
-          key = template_section.normalized_name
-          seen_names << key
+            key = template_section.normalized_name
+            seen_names << key
-          dest_section = dest_by_name[key]
+            dest_section = dest_by_name[key]
-          if dest_section
-            # Section exists in both - choose based on preference
-            section_pref = preference_for(template_section.name, preference)
-            merged << ((section_pref == :template) ? template_section : dest_section)
-          elsif add_template_only
-            merged << template_section
+            if dest_section
+              # Section exists in both - choose based on preference
+              section_pref = preference_for(template_section.name, preference)
+              merged << ((section_pref == :template) ? template_section : dest_section)
+            elsif add_template_only
+              merged << template_section
+            end
           end
-        end
-        # Append destination-only sections
-        dest_sections.each do |dest_section|
-          next if dest_section.unclassified?
-          key = dest_section.normalized_name
-          next if seen_names.include?(key)
-          merged << dest_section
+          # Append destination-only sections
+          dest_sections.each do |dest_section|
+            next if dest_section.unclassified?
+            key = dest_section.normalized_name
+            next if seen_names.include?(key)
+            merged << dest_section
+          end
+          merged
         end
-        merged
-      end
+        # Get preference for a specific section.
+        #
+        # @param section_name [String, Symbol] The section name
+        # @param preference [Symbol, Hash] Overall preference
+        # @return [Symbol] :template or :destination
+        def preference_for(section_name, preference)
+          return preference unless preference.is_a?(Hash)
-      # Get preference for a specific section.
-      #
-      # @param section_name [String, Symbol] The section name
-      # @param preference [Symbol, Hash] Overall preference
-      # @return [Symbol] :template or :destination
-      def self.preference_for(section_name, preference)
-        return preference unless preference.is_a?(Hash)
+          normalized = section_name.to_s.strip.downcase
+          preference.each do |key, value|
+            return value if key.to_s.strip.downcase == normalized
+          end
-        normalized = section_name.to_s.strip.downcase
-        preference.each do |key, value|
-          return value if key.to_s.strip.downcase == normalized
+          preference.fetch(:default, :destination)
         end
-        preference.fetch(:default, :destination)
       end
     end
   end

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

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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 = "1.1.0"
     end
     VERSION = Version::VERSION # traditional location
   end

data/lib/ast/merge/yaml_frontmatter_detector.rb CHANGED Viewed

@@ -56,26 +56,6 @@ module Ast
         # 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]

data.tar.gz.sig CHANGED Viewed

Binary file

metadata CHANGED Viewed

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ast-merge
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Peter H. Boling
@@ -57,6 +57,26 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 1.1.9
+- !ruby/object:Gem::Dependency
+  name: tree_haver
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.1.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.1.0
 - !ruby/object:Gem::Dependency
   name: kettle-dev
   requirement: !ruby/object:Gem::Requirement
@@ -288,10 +308,10 @@ licenses:
 - MIT
 metadata:
   homepage_uri: https://ast-merge.galtzo.com/
-  source_code_uri: https://github.com/kettle-rb/ast-merge/tree/v1.0.0
-  changelog_uri: https://github.com/kettle-rb/ast-merge/blob/v1.0.0/CHANGELOG.md
+  source_code_uri: https://github.com/kettle-rb/ast-merge/tree/v1.1.0
+  changelog_uri: https://github.com/kettle-rb/ast-merge/blob/v1.1.0/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-rb/ast-merge/issues
-  documentation_uri: https://www.rubydoc.info/gems/ast-merge/1.0.0
+  documentation_uri: https://www.rubydoc.info/gems/ast-merge/1.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

metadata.gz.sig CHANGED Viewed

Binary file