ast-merge 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79e0b486476d9494e6e1065d71b13ef8b940bd7d5db8caffd4784231ce239ad2
-  data.tar.gz: 941f9604854c537b087b76a253945f35dbc81f8f5b701f60dcad0ab1b9a35026
+  metadata.gz: 4ce2b23f374b6f178709f84a66ccbed7b997a05d170d7b1f63ede714fc844469
+  data.tar.gz: d0ae1bc694c669108b5ddaac372424c02f8528f3c59642ced6fb7bb1af67dcf4
 SHA512:
-  metadata.gz: f8b51479340dd11352faac1e7ca2933481dcbf012b1fbff8176a5f425e07717848dce99f4b631cdc5562fc897e4ae2bb7af06d9380d105a6f25ab612473cd231
-  data.tar.gz: d45e550372da739a549ba78c27fe15836a8ca17b674c88dcee958f0f58732f54b7d52d6d9b99a22ee635f2ad1862c9a2631e8cc15fb4fa3c38aca528d58142cc
+  metadata.gz: 41981f4b37122e224ecc1b3047156ec15871742fbca09b8203acb91c27df7acf61164871c2ee7eac07db32a12acccc7c8dda3b83b8cd7dafd8f86ade604a82a6
+  data.tar.gz: 29c07de568c15bc8a78b6363c438e6c7902af5f24d8d441aaa9f9417bceeedb62107f40e95a226864be3492b16373ae4493efa0ed956c780448bf4a3168980b9

data/CHANGELOG.md

@@ -30,6 +30,32 @@ 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]
@@ -507,7 +533,9 @@ Please file a bug if you notice a violation of semantic versioning.
 
 - Initial release
 
-[Unreleased]: https://github.com/kettle-rb/ast-merge/compare/v3.0.0...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

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.540-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/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/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/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) {

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 = "3.0.0"
+      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"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ast-merge
 version: !ruby/object:Gem::Version
-  version: 3.0.0
+  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.5
+        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.5
+        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
@@ -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/v3.0.0
-  changelog_uri: https://github.com/kettle-rb/ast-merge/blob/v3.0.0/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/3.0.0
+  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