ast-merge 1.1.0 → 2.0.1

data/sig/ast/merge.rbs

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ast-merge
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.0.1
 platform: ruby
 authors:
 - Peter H. Boling
@@ -66,7 +66,7 @@ dependencies:
         version: '3.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.1.0
+        version: 3.1.2
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -76,7 +76,7 @@ dependencies:
         version: '3.1'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 3.1.0
+        version: 3.1.2
 - !ruby/object:Gem::Dependency
   name: kettle-dev
   requirement: !ruby/object:Gem::Requirement
@@ -153,6 +153,40 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: benchmark
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.5'
+- !ruby/object:Gem::Dependency
+  name: kettle-soup-cover
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.1
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.1'
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.1.1
 - !ruby/object:Gem::Dependency
   name: kettle-test
   requirement: !ruby/object:Gem::Requirement
@@ -162,7 +196,7 @@ dependencies:
         version: '1.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.6
+        version: 1.0.7
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
@@ -172,7 +206,7 @@ dependencies:
         version: '1.0'
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.0.6
+        version: 1.0.7
 - !ruby/object:Gem::Dependency
   name: ruby-progressbar
   requirement: !ruby/object:Gem::Requirement
@@ -232,7 +266,8 @@ description: "☯️ Ast::Merge provides base classes, modules, and RSpec shared
   psych-merge, json-merge, and other format-specific merge gems."
 email:
 - floss@galtzo.com
-executables: []
+executables:
+- ast-merge-recipe
 extensions: []
 extra_rdoc_files:
 - CHANGELOG.md
@@ -256,6 +291,7 @@ files:
 - REEK
 - RUBOCOP.md
 - SECURITY.md
+- exe/ast-merge-recipe
 - lib/ast-merge.rb
 - lib/ast/merge.rb
 - lib/ast/merge/ast_node.rb
@@ -266,8 +302,13 @@ files:
 - lib/ast/merge/comment/parser.rb
 - lib/ast/merge/comment/style.rb
 - lib/ast/merge/conflict_resolver_base.rb
+- lib/ast/merge/content_match_refiner.rb
 - lib/ast/merge/debug_logger.rb
-- lib/ast/merge/fenced_code_block_detector.rb
+- lib/ast/merge/detector/base.rb
+- lib/ast/merge/detector/fenced_code_block.rb
+- lib/ast/merge/detector/mergeable.rb
+- lib/ast/merge/detector/toml_frontmatter.rb
+- lib/ast/merge/detector/yaml_frontmatter.rb
 - lib/ast/merge/file_analyzable.rb
 - lib/ast/merge/freezable.rb
 - lib/ast/merge/freeze_node_base.rb
@@ -275,11 +316,16 @@ files:
 - lib/ast/merge/match_score_base.rb
 - lib/ast/merge/merge_result_base.rb
 - lib/ast/merge/merger_config.rb
+- lib/ast/merge/navigable_statement.rb
 - lib/ast/merge/node_typing.rb
-- lib/ast/merge/region.rb
-- lib/ast/merge/region_detector_base.rb
-- lib/ast/merge/region_mergeable.rb
+- lib/ast/merge/partial_template_merger.rb
+- lib/ast/merge/recipe.rb
+- lib/ast/merge/recipe/config.rb
+- lib/ast/merge/recipe/preset.rb
+- lib/ast/merge/recipe/runner.rb
+- lib/ast/merge/recipe/script_loader.rb
 - lib/ast/merge/rspec.rb
+- lib/ast/merge/rspec/dependency_tags.rb
 - lib/ast/merge/rspec/shared_examples.rb
 - lib/ast/merge/rspec/shared_examples/conflict_resolver_base.rb
 - lib/ast/merge/rspec/shared_examples/debug_logger.rb
@@ -299,19 +345,17 @@ files:
 - lib/ast/merge/text/section_splitter.rb
 - lib/ast/merge/text/smart_merger.rb
 - lib/ast/merge/text/word_node.rb
-- lib/ast/merge/toml_frontmatter_detector.rb
 - lib/ast/merge/version.rb
-- lib/ast/merge/yaml_frontmatter_detector.rb
 - sig/ast/merge.rbs
 homepage: https://github.com/kettle-rb/ast-merge
 licenses:
 - MIT
 metadata:
   homepage_uri: https://ast-merge.galtzo.com/
-  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
+  source_code_uri: https://github.com/kettle-rb/ast-merge/tree/v2.0.1
+  changelog_uri: https://github.com/kettle-rb/ast-merge/blob/v2.0.1/CHANGELOG.md
   bug_tracker_uri: https://github.com/kettle-rb/ast-merge/issues
-  documentation_uri: https://www.rubydoc.info/gems/ast-merge/1.1.0
+  documentation_uri: https://www.rubydoc.info/gems/ast-merge/2.0.1
   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
@@ -340,7 +384,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 4.0.1
+rubygems_version: 4.0.3
 specification_version: 4
 summary: "☯️ Shared infrastructure for the *-merge gem family"
 test_files: []