ast-merge 1.1.0 → 2.0.1

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

@@ -0,0 +1,171 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Ast
+  module Merge
+    module Recipe
+      # Base configuration for merge presets.
+      #
+      # A Preset provides merge configuration (signature generators, node typing,
+      # preferences) without requiring a template file. This is useful for
+      # defining reusable merge behaviors that can be applied to any merge operation.
+      #
+      # `Config` inherits from `Preset` and adds template/target file handling
+      # for standalone recipe execution.
+      #
+      # @example Loading a preset
+      #   preset = Preset.load("presets/gemfile.yml")
+      #   merger = Prism::Merge::SmartMerger.new(
+      #     template, destination,
+      #     **preset.to_h
+      #   )
+      #
+      # @example Creating a preset programmatically
+      #   preset = Preset.new(
+      #     "name" => "my_preset",
+      #     "merge" => { "preference" => "template" }
+      #   )
+      #
+      # @see Config For full recipe with template/target support
+      # @see ScriptLoader For loading Ruby scripts from companion folders
+      class Preset
+        # @return [String] Preset name
+        attr_reader :name
+
+        # @return [String, nil] Preset description
+        attr_reader :description
+
+        # @return [Symbol] Parser to use (:prism, :markly, :psych, etc.)
+        attr_reader :parser
+
+        # @return [Hash] Merge configuration
+        attr_reader :merge_config
+
+        # @return [String, nil] Freeze token for preserving sections
+        attr_reader :freeze_token
+
+        # @return [String, nil] Path to the preset file (for script resolution)
+        attr_reader :preset_path
+
+        class << self
+          # Load a preset from a YAML file.
+          #
+          # @param path [String] Path to the preset YAML file
+          # @return [Preset]
+          # @raise [ArgumentError] If file not found
+          def load(path)
+            raise ArgumentError, "Preset file not found: #{path}" unless File.exist?(path)
+
+            yaml = YAML.safe_load_file(path, permitted_classes: [Regexp, Symbol])
+            new(yaml, preset_path: path)
+          end
+        end
+
+        # Initialize a preset from a hash.
+        #
+        # @param config [Hash] Parsed YAML config or programmatic config
+        # @param preset_path [String, nil] Path to preset file (for script resolution)
+        def initialize(config, preset_path: nil)
+          @preset_path = preset_path
+          @name = config["name"] || "unnamed"
+          @description = config["description"]
+          @parser = (config["parser"] || "prism").to_sym
+          @merge_config = parse_merge_config(config["merge"] || {})
+          @freeze_token = config["freeze_token"]
+        end
+
+        # Get the merge preference setting.
+        #
+        # @return [Symbol, Hash] Preference (:template, :destination, or per-type hash)
+        def preference
+          merge_config[:preference] || :template
+        end
+
+        # Get the add_missing setting, loading as callable if it's a script reference.
+        #
+        # @return [Boolean, Proc] Boolean value or callable filter
+        def add_missing
+          value = merge_config[:add_missing]
+          return true if value.nil?
+          return value if value == true || value == false
+          return value if value.respond_to?(:call)
+
+          # It's a script reference - load it
+          script_loader.load_callable(value)
+        end
+
+        # Convenience alias for boolean check.
+        #
+        # @return [Boolean, Proc]
+        def add_missing?
+          add_missing
+        end
+
+        # Get the signature_generator callable, loading from script if needed.
+        #
+        # @return [Proc, nil] Signature generator callable
+        def signature_generator
+          value = merge_config[:signature_generator]
+          return if value.nil?
+          return value if value.respond_to?(:call)
+
+          script_loader.load_callable(value)
+        end
+
+        # Get the node_typing configuration with callables loaded.
+        #
+        # @return [Hash, nil] Hash of type => callable
+        def node_typing
+          value = merge_config[:node_typing]
+          return if value.nil?
+          return value if value.is_a?(Hash) && value.values.all? { |v| v.respond_to?(:call) }
+
+          script_loader.load_callable_hash(value)
+        end
+
+        # Convert preset to a hash suitable for SmartMerger options.
+        #
+        # @return [Hash]
+        def to_h
+          {
+            preference: preference,
+            add_template_only_nodes: add_missing,
+            signature_generator: signature_generator,
+            node_typing: node_typing,
+            freeze_token: freeze_token,
+          }.compact
+        end
+
+        # Get the script loader instance.
+        #
+        # @return [ScriptLoader]
+        def script_loader
+          @script_loader ||= ScriptLoader.new(recipe_path: preset_path)
+        end
+
+        protected
+
+        def parse_merge_config(config)
+          {
+            preference: parse_preference(config["preference"]),
+            add_missing: config["add_missing"],
+            replace_mode: config["replace_mode"] == true,
+            match_by: Array(config["match_by"]).map(&:to_sym),
+            deep: config["deep"] == true,
+            signature_generator: config["signature_generator"],
+            node_typing: config["node_typing"],
+          }
+        end
+
+        def parse_preference(pref)
+          return :template if pref.nil?
+          return pref.to_sym if pref.is_a?(String)
+
+          # Hash of type => preference
+          pref.transform_keys(&:to_sym).transform_values(&:to_sym) if pref.is_a?(Hash)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    module Recipe
+      # Executes a merge recipe against target files.
+      #
+      # The runner:
+      # 1. Loads the template file
+      # 2. Expands target file globs
+      # 3. For each target, finds the injection point and performs the merge
+      # 4. Collects results for reporting
+      #
+      # @example Running a recipe
+      #   recipe = Recipe::Config.load(".merge-recipes/gem_family_section.yml")
+      #   runner = Recipe::Runner.new(recipe, dry_run: true)
+      #   results = runner.run
+      #   puts runner.summary
+      #
+      # @example With custom parser
+      #   runner = Recipe::Runner.new(recipe, parser: :markly, base_dir: "/path/to/project")
+      #   results = runner.run
+      #
+      # @see Config For recipe configuration
+      # @see ScriptLoader For loading Ruby scripts from recipe folders
+      #
+      class Runner
+        # Result of processing a single file
+        Result = Struct.new(:path, :relative_path, :status, :changed, :has_anchor, :message, :stats, :error, keyword_init: true)
+
+        # @return [Config] The recipe being executed
+        attr_reader :recipe
+
+        # @return [Boolean] Whether this is a dry run
+        attr_reader :dry_run
+
+        # @return [String] Base directory for path resolution
+        attr_reader :base_dir
+
+        # @return [Symbol] Parser to use (:markly, :commonmarker, :prism, :psych, etc.)
+        attr_reader :parser
+
+        # @return [Array<Result>] Results from the last run
+        attr_reader :results
+
+        # Initialize a recipe runner.
+        #
+        # @param recipe [Config] The recipe to execute
+        # @param dry_run [Boolean] If true, don't write files
+        # @param base_dir [String, nil] Base directory for path resolution
+        # @param parser [Symbol] Which parser to use
+        # @param verbose [Boolean] Enable verbose output
+        def initialize(recipe, dry_run: false, base_dir: nil, parser: :markly, verbose: false)
+          @recipe = recipe
+          @dry_run = dry_run
+          @base_dir = base_dir || Dir.pwd
+          @parser = parser
+          @verbose = verbose
+          @results = []
+        end
+
+        # Run the recipe against all target files.
+        #
+        # @return [Array<Result>] Results for each processed file
+        def run
+          @results = []
+
+          template_content = load_template
+          # Let the recipe expand targets from its own location
+          target_files = recipe.expand_targets
+
+          target_files.each do |target_path|
+            result = process_file(target_path, template_content)
+            @results << result
+            yield result if block_given?
+          end
+
+          @results
+        end
+
+        # Get results grouped by status.
+        #
+        # @return [Hash<Symbol, Array<Result>>]
+        def results_by_status
+          @results.group_by(&:status)
+        end
+
+        # Get a summary hash of the run.
+        #
+        # @return [Hash]
+        def summary
+          by_status = results_by_status
+          {
+            total: @results.size,
+            updated: (by_status[:updated] || []).size,
+            would_update: (by_status[:would_update] || []).size,
+            unchanged: (by_status[:unchanged] || []).size,
+            skipped: (by_status[:skipped] || []).size,
+            errors: (by_status[:error] || []).size,
+          }
+        end
+
+        # Format results as an array of hashes for TableTennis.
+        #
+        # @return [Array<Hash>]
+        def results_table
+          @results.map do |r|
+            {
+              file: r.relative_path,
+              status: r.status.to_s,
+              changed: r.changed ? "yes" : "no",
+              message: r.message,
+            }
+          end
+        end
+
+        # Format summary as an array of hashes for TableTennis.
+        #
+        # @return [Array<Hash>]
+        def summary_table
+          s = summary
+          [
+            {metric: "Total files", value: s[:total]},
+            {metric: "Updated", value: dry_run ? s[:would_update] : s[:updated]},
+            {metric: "Unchanged", value: s[:unchanged]},
+            {metric: "Skipped (no anchor)", value: s[:skipped]},
+            {metric: "Errors", value: s[:errors]},
+          ]
+        end
+
+        private
+
+        def load_template
+          # Let the recipe resolve the template path from its own location
+          path = recipe.template_absolute_path
+          raise ArgumentError, "Template not found: #{path}" unless File.exist?(path)
+
+          File.read(path)
+        end
+
+        def process_file(target_path, template_content)
+          relative_path = make_relative(target_path)
+
+          begin
+            destination_content = File.read(target_path)
+
+            # Use PartialTemplateMerger which handles finding injection point and merging
+            merger = PartialTemplateMerger.new(
+              template: template_content,
+              destination: destination_content,
+              anchor: recipe.injection[:anchor] || {},
+              boundary: recipe.injection[:boundary],
+              parser: parser,
+              preference: recipe.preference,
+              add_missing: recipe.add_missing,
+              when_missing: recipe.when_missing,
+              replace_mode: recipe.replace_mode?,
+              signature_generator: recipe.signature_generator,
+              node_typing: recipe.node_typing,
+            )
+
+            result = merger.merge
+
+            if result.section_found?
+              create_result_from_merge(target_path, relative_path, destination_content, result)
+            else
+              handle_missing_anchor_result(target_path, relative_path, result)
+            end
+          rescue => e
+            Result.new(
+              path: target_path,
+              relative_path: relative_path,
+              status: :error,
+              changed: false,
+              has_anchor: false,
+              message: e.message,
+              error: e,
+            )
+          end
+        end
+
+        def create_result_from_merge(target_path, relative_path, _destination_content, merge_result)
+          changed = merge_result.changed
+
+          if changed
+            unless dry_run
+              File.write(target_path, merge_result.content)
+            end
+
+            Result.new(
+              path: target_path,
+              relative_path: relative_path,
+              status: dry_run ? :would_update : :updated,
+              changed: true,
+              has_anchor: true,
+              message: dry_run ? "Would update" : "Updated",
+              stats: merge_result.stats,
+            )
+          else
+            Result.new(
+              path: target_path,
+              relative_path: relative_path,
+              status: :unchanged,
+              changed: false,
+              has_anchor: true,
+              message: "No changes needed",
+              stats: merge_result.stats,
+            )
+          end
+        end
+
+        def handle_missing_anchor_result(target_path, relative_path, merge_result)
+          # PartialTemplateMerger already handled when_missing logic
+          status = if merge_result.changed
+            dry_run ? :would_update : :updated
+          else
+            :skipped
+          end
+
+          if merge_result.changed && !dry_run
+            File.write(target_path, merge_result.content)
+          end
+
+          Result.new(
+            path: target_path,
+            relative_path: relative_path,
+            status: status,
+            changed: merge_result.changed,
+            has_anchor: false,
+            message: merge_result.message || "No matching anchor found",
+          )
+        end
+
+        def make_relative(path)
+          # Try to make path relative to base_dir first
+          if path.start_with?(base_dir)
+            return path.sub("#{base_dir}/", "")
+          end
+
+          # If recipe has a path, try relative to recipe's parent directory
+          if recipe.recipe_path
+            recipe_base = File.dirname(recipe.recipe_path, 2)
+            if path.start_with?(recipe_base)
+              return path.sub("#{recipe_base}/", "")
+            end
+          end
+
+          # Fall back to the path itself
+          path
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,181 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    module Recipe
+      # Loads Ruby scripts referenced by a recipe from a companion folder.
+      #
+      # Convention: A recipe at `.merge-recipes/my_recipe.yml` can reference
+      # scripts in `.merge-recipes/my_recipe/` folder.
+      #
+      # Scripts must define a callable object (lambda, proc, or object with #call method).
+      #
+      # @example Script reference in recipe YAML
+      #   merge:
+      #     signature_generator: scripts/signature_generator.rb
+      #     node_typing:
+      #       heading: scripts/heading_typing.rb
+      #     add_missing: scripts/add_missing_filter.rb
+      #
+      # @example Script file content (signature_generator.rb)
+      #   # Must return a callable
+      #   lambda do |node|
+      #     text = node.respond_to?(:to_plaintext) ? node.to_plaintext.to_s : node.to_s
+      #     if text.include?("gem family")
+      #       [:gem_family, :section]
+      #     else
+      #       nil
+      #     end
+      #   end
+      #
+      # @see Config For recipe configuration
+      # @see Runner For recipe execution
+      #
+      class ScriptLoader
+        # @return [String, nil] Base directory for script resolution
+        attr_reader :base_dir
+
+        # @return [Hash] Cache of loaded scripts
+        attr_reader :script_cache
+
+        # Initialize a script loader.
+        #
+        # @param recipe_path [String, nil] Path to recipe file (determines script folder)
+        # @param base_dir [String, nil] Override base directory for scripts
+        def initialize(recipe_path: nil, base_dir: nil)
+          @base_dir = determine_base_dir(recipe_path, base_dir)
+          @script_cache = {}
+        end
+
+        # Load a callable from a script reference.
+        #
+        # @param reference [String, Proc, nil] Script path, inline expression, or existing callable
+        # @return [Proc, nil] The callable, or nil if reference is nil
+        # @raise [ArgumentError] If script not found or doesn't return a callable
+        def load_callable(reference)
+          return if reference.nil?
+          return reference if reference.respond_to?(:call)
+
+          # Check if it's an inline lambda expression
+          if inline_expression?(reference)
+            return evaluate_inline_expression(reference)
+          end
+
+          # It's a file path reference
+          load_script_file(reference)
+        end
+
+        # Load a hash of callables (e.g., node_typing config).
+        #
+        # @param config [Hash, nil] Hash with script references as values
+        # @return [Hash, nil] Hash with callables as values
+        def load_callable_hash(config)
+          return if config.nil? || config.empty?
+
+          config.transform_values { |ref| load_callable(ref) }
+        end
+
+        # Check if scripts directory exists.
+        #
+        # @return [Boolean]
+        def scripts_available?
+          !!(base_dir && Dir.exist?(base_dir))
+        end
+
+        # List available scripts.
+        #
+        # @return [Array<String>] Script filenames
+        def available_scripts
+          return [] unless scripts_available?
+
+          Dir.glob(File.join(base_dir, "**/*.rb")).map do |path|
+            path.sub("#{base_dir}/", "")
+          end
+        end
+
+        private
+
+        def determine_base_dir(recipe_path, override_base_dir)
+          return override_base_dir if override_base_dir
+
+          return unless recipe_path
+
+          # Convention: scripts folder has same name as recipe (without extension)
+          recipe_dir = File.dirname(recipe_path)
+          recipe_basename = File.basename(recipe_path, ".*")
+          scripts_dir = File.join(recipe_dir, recipe_basename)
+
+          scripts_dir if Dir.exist?(scripts_dir)
+        end
+
+        def inline_expression?(reference)
+          return false unless reference.is_a?(String)
+
+          # Check for inline lambda/proc syntax
+          reference.strip.start_with?("->", "lambda", "proc", "->(")
+        end
+
+        def evaluate_inline_expression(expression)
+          # Evaluate the expression in a clean binding
+          # rubocop:disable Security/Eval
+          result = eval(expression, TOPLEVEL_BINDING.dup, "(inline)", 1)
+          # rubocop:enable Security/Eval
+
+          unless result.respond_to?(:call)
+            raise ArgumentError, "Inline expression must return a callable, got: #{result.class}"
+          end
+
+          result
+        rescue SyntaxError => e
+          raise ArgumentError, "Invalid inline expression syntax: #{e.message}"
+        rescue => e
+          raise ArgumentError, "Failed to evaluate inline expression: #{e.message}"
+        end
+
+        def load_script_file(path)
+          # Check cache first
+          return script_cache[path] if script_cache.key?(path)
+
+          absolute_path = resolve_script_path(path)
+
+          unless File.exist?(absolute_path)
+            raise ArgumentError, "Script not found: #{path} (looked in #{absolute_path})"
+          end
+
+          script_content = File.read(absolute_path)
+
+          # Evaluate the script - it should return a callable
+          # rubocop:disable Security/Eval
+          result = eval(script_content, TOPLEVEL_BINDING.dup, absolute_path, 1)
+          # rubocop:enable Security/Eval
+
+          unless result.respond_to?(:call)
+            raise ArgumentError, "Script #{path} must return a callable (lambda, proc, or object with #call), got: #{result.class}"
+          end
+
+          # Cache and return
+          script_cache[path] = result
+          result
+        rescue SyntaxError => e
+          raise ArgumentError, "Syntax error in script #{path}: #{e.message}"
+        rescue => e
+          raise ArgumentError, "Failed to load script #{path}: #{e.message}"
+        end
+
+        def resolve_script_path(path)
+          # If path is absolute, use it directly
+          return path if File.absolute_path?(path)
+
+          # If we have a base_dir, resolve relative to it
+          if base_dir
+            resolved = File.expand_path(path, base_dir)
+            return resolved if File.exist?(resolved)
+          end
+
+          # Fall back to current directory
+          File.expand_path(path)
+        end
+      end
+    end
+  end
+end

data/lib/ast/merge/recipe.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Ast
+  module Merge
+    # Recipe namespace for YAML-based merge recipe functionality.
+    #
+    # This module contains classes for loading, configuring, and executing
+    # merge recipes that define how to perform partial template merges.
+    #
+    # @example Loading and running a recipe
+    #   recipe = Ast::Merge::Recipe::Config.load("my_recipe.yml")
+    #   runner = Ast::Merge::Recipe::Runner.new(recipe, dry_run: true)
+    #   results = runner.run
+    #
+    # @see Recipe::Config Recipe configuration and loading
+    # @see Recipe::Runner Recipe execution
+    # @see Recipe::ScriptLoader Loading Ruby scripts from recipe folders
+    #
+    module Recipe
+      autoload :Config, "ast/merge/recipe/config"
+      autoload :Preset, "ast/merge/recipe/preset"
+      autoload :Runner, "ast/merge/recipe/runner"
+      autoload :ScriptLoader, "ast/merge/recipe/script_loader"
+    end
+  end
+end