markly-merge 1.0.0

data/lib/markly/merge/smart_merger.rb

@@ -0,0 +1,159 @@
+# frozen_string_literal: true
+
+module Markly
+  module Merge
+    # Orchestrates the smart merge process for Markdown files using Markly.
+    #
+    # This is a thin wrapper around Markdown::Merge::SmartMerger that:
+    # - Forces the :markly backend
+    # - Sets markly-specific defaults (freeze token, inner_merge_code_blocks)
+    # - Exposes markly-specific options (flags, extensions)
+    #
+    # @example Basic merge (destination customizations preserved)
+    #   merger = SmartMerger.new(template_content, dest_content)
+    #   result = merger.merge
+    #   if result.success?
+    #     File.write("output.md", result.content)
+    #   end
+    #
+    # @example Template updates win
+    #   merger = SmartMerger.new(
+    #     template_content,
+    #     dest_content,
+    #     preference: :template,
+    #     add_template_only_nodes: true
+    #   )
+    #   result = merger.merge
+    #
+    # @example Custom signature matching
+    #   sig_gen = ->(node) {
+    #     canonical_type = Ast::Merge::NodeTyping.merge_type_for(node) || node.type
+    #     if canonical_type == :heading
+    #       [:heading, node.header_level]  # Match by level only, not content
+    #     else
+    #       node  # Fall through to default
+    #     end
+    #   }
+    #   merger = SmartMerger.new(
+    #     template_content,
+    #     dest_content,
+    #     signature_generator: sig_gen
+    #   )
+    #
+    # @example Disable inner-merge for code blocks
+    #   merger = SmartMerger.new(
+    #     template_content,
+    #     dest_content,
+    #     inner_merge_code_blocks: false
+    #   )
+    #
+    # @see Markdown::Merge::SmartMerger Underlying implementation
+    class SmartMerger < Markdown::Merge::SmartMerger
+      # Creates a new SmartMerger for intelligent Markdown file merging.
+      #
+      # @param template_content [String] Template Markdown source code
+      # @param dest_content [String] Destination Markdown source code
+      #
+      # @param signature_generator [Proc, nil] Optional proc to generate custom node signatures.
+      #   The proc receives a node (wrapped with canonical merge_type) and should return one of:
+      #   - An array representing the node's signature
+      #   - `nil` to indicate the node should have no signature
+      #   - The original node to fall through to default signature computation
+      #
+      # @param preference [Symbol] Controls which version to use when nodes
+      #   have matching signatures but different content:
+      #   - `:destination` (default) - Use destination version (preserves customizations)
+      #   - `:template` - Use template version (applies updates)
+      #
+      # @param add_template_only_nodes [Boolean] Controls whether to add nodes that only
+      #   exist in template:
+      #   - `false` (default) - Skip template-only nodes
+      #   - `true` - Add template-only nodes to result
+      #
+      # @param inner_merge_code_blocks [Boolean, CodeBlockMerger] Controls inner-merge for
+      #   fenced code blocks:
+      #   - `true` (default for markly-merge) - Enable inner-merge using default CodeBlockMerger
+      #   - `false` - Disable inner-merge (use standard conflict resolution)
+      #   - `CodeBlockMerger` instance - Use custom CodeBlockMerger
+      #
+      # @param freeze_token [String] Token to use for freeze block markers.
+      #   Default: "markly-merge"
+      #   Looks for: <!-- markly-merge:freeze --> / <!-- markly-merge:unfreeze -->
+      #
+      # @param flags [Integer] Markly parse flags (e.g., Markly::FOOTNOTES | Markly::SMART).
+      #   Default: Markly::DEFAULT
+      #
+      # @param extensions [Array<Symbol>] Markly extensions to enable (e.g., [:table, :strikethrough])
+      #   Available extensions: :table, :strikethrough, :autolink, :tagfilter, :tasklist
+      #
+      # @param match_refiner [#call, nil] Optional match refiner for fuzzy matching of
+      #   unmatched nodes. Default: nil (fuzzy matching disabled).
+      #
+      # @param node_typing [Hash{Symbol,String => #call}, nil] Node typing configuration
+      #   for per-node-type merge preferences.
+      # @param options [Hash] Additional options for forward compatibility
+      #
+      # @raise [TemplateParseError] If template has syntax errors
+      # @raise [DestinationParseError] If destination has syntax errors
+      def initialize(
+        template_content,
+        dest_content,
+        signature_generator: nil,
+        preference: :destination,
+        add_template_only_nodes: false,
+        inner_merge_code_blocks: DEFAULT_INNER_MERGE_CODE_BLOCKS,
+        freeze_token: DEFAULT_FREEZE_TOKEN,
+        flags: ::Markly::DEFAULT,
+        extensions: [:table],
+        match_refiner: nil,
+        node_typing: nil,
+        **options
+      )
+        super(
+          template_content,
+          dest_content,
+          backend: :markly,
+          signature_generator: signature_generator,
+          preference: preference,
+          add_template_only_nodes: add_template_only_nodes,
+          inner_merge_code_blocks: inner_merge_code_blocks,
+          freeze_token: freeze_token,
+          match_refiner: match_refiner,
+          node_typing: node_typing,
+          flags: flags,
+          extensions: extensions,
+          **options
+        )
+      end
+
+      # Returns the TemplateParseError class to use.
+      #
+      # @return [Class] Markly::Merge::TemplateParseError
+      def template_parse_error_class
+        TemplateParseError
+      end
+
+      # Returns the DestinationParseError class to use.
+      #
+      # @return [Class] Markly::Merge::DestinationParseError
+      def destination_parse_error_class
+        DestinationParseError
+      end
+
+      # Create a FileAnalysis instance for parsing.
+      #
+      # @param content [String] Markdown content to analyze
+      # @param options [Hash] Analysis options
+      # @return [Markly::Merge::FileAnalysis] File analysis instance
+      def create_file_analysis(content, **opts)
+        FileAnalysis.new(
+          content,
+          freeze_token: opts[:freeze_token],
+          signature_generator: opts[:signature_generator],
+          flags: opts[:flags] || ::Markly::DEFAULT,
+          extensions: opts[:extensions] || [:table],
+        )
+      end
+    end
+  end
+end

data/lib/markly/merge/version.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Markly
+  module Merge
+    # Version information for Markly::Merge
+    module Version
+      # Current version of the markly-merge gem
+      VERSION = "1.0.0"
+    end
+    VERSION = Version::VERSION # traditional location
+  end
+end

data/lib/markly/merge.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+# Hard dependency - ensures markly gem is installed
+require "markly"
+
+# External gems
+require "version_gem"
+
+# Shared merge infrastructure (includes tree_haver)
+require "markdown/merge"
+
+# This gem
+require_relative "merge/version"
+
+module Markly
+  # Smart merging for Markdown files using Markly AST.
+  #
+  # Markly::Merge provides intelligent merging of Markdown files by:
+  # - Parsing Markdown into AST using Markly (cmark-gfm) via tree_haver
+  # - Matching structural elements (headings, paragraphs, lists, etc.) between files
+  # - Preserving frozen sections marked with HTML comments
+  # - Resolving conflicts based on configurable preferences
+  #
+  # This is a thin wrapper around Markdown::Merge that:
+  # - Provides hard dependency on the markly gem
+  # - Sets markly-specific defaults (freeze token, inner_merge_code_blocks)
+  # - Exposes markly-specific options (flags, extensions)
+  # - Maintains API compatibility for existing users
+  #
+  # @example Basic merge
+  #   merger = Markly::Merge::SmartMerger.new(template, destination)
+  #   result = merger.merge
+  #   puts result.content if result.success?
+  #
+  # @example With freeze blocks
+  #   # In your Markdown file:
+  #   # <!-- markly-merge:freeze -->
+  #   # ## Custom Section
+  #   # This content is preserved during merges.
+  #   # <!-- markly-merge:unfreeze -->
+  #
+  # @see SmartMerger Main entry point for merging
+  # @see Markdown::Merge::SmartMerger Underlying implementation
+  module Merge
+    # Base error class for Markly::Merge
+    # Inherits from Markdown::Merge::Error for consistency across merge gems.
+    class Error < Markdown::Merge::Error; end
+
+    # Raised when a Markdown file has parsing errors.
+    # Inherits from Markdown::Merge::ParseError for consistency across merge gems.
+    class ParseError < Markdown::Merge::ParseError; end
+
+    # Raised when the template file has syntax errors.
+    class TemplateParseError < ParseError; end
+
+    # Raised when the destination file has syntax errors.
+    class DestinationParseError < ParseError; end
+
+    # Default freeze token for markly-merge
+    # @return [String]
+    DEFAULT_FREEZE_TOKEN = "markly-merge"
+
+    # Default inner_merge_code_blocks setting for markly-merge
+    # @return [Boolean]
+    DEFAULT_INNER_MERGE_CODE_BLOCKS = true
+
+    # Re-export shared classes from markdown-merge
+    # Re-export shared classes from markdown-merge
+    FileAligner = Markdown::Merge::FileAligner
+    ConflictResolver = Markdown::Merge::ConflictResolver
+    MergeResult = Markdown::Merge::MergeResult
+    TableMatchAlgorithm = Markdown::Merge::TableMatchAlgorithm
+    TableMatchRefiner = Markdown::Merge::TableMatchRefiner
+    CodeBlockMerger = Markdown::Merge::CodeBlockMerger
+    NodeTypeNormalizer = Markdown::Merge::NodeTypeNormalizer
+
+    autoload :DebugLogger, "markly/merge/debug_logger"
+    autoload :FreezeNode, "markly/merge/freeze_node"
+    autoload :FileAnalysis, "markly/merge/file_analysis"
+    autoload :SmartMerger, "markly/merge/smart_merger"
+    autoload :Backend, "markly/merge/backend"
+
+    # Eagerly load and register backend when this module is loaded
+    # This ensures the backend is available for tree_haver before any parsing happens
+    class << self
+      def ensure_backend_loaded!
+        Backend # Access constant to trigger autoload
+      end
+    end
+  end
+end
+
+# Ensure backend is loaded and registered
+Markly::Merge.ensure_backend_loaded!
+
+# Register with ast-merge's MergeGemRegistry for RSpec dependency tags
+# Only register if MergeGemRegistry is loaded (i.e., in test environment)
+if defined?(Ast::Merge::RSpec::MergeGemRegistry)
+  Ast::Merge::RSpec::MergeGemRegistry.register(
+    :markly_merge,
+    require_path: "markly/merge",
+    merger_class: "Markly::Merge::SmartMerger",
+    test_source: "# Test\n\nParagraph",
+    category: :markdown,
+  )
+end
+
+Markly::Merge::Version.class_eval do
+  extend VersionGem::Basic
+end

data/lib/markly-merge.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# For technical reasons, if we move to Zeitwerk, this cannot be require_relative.
+#   See: https://github.com/fxn/zeitwerk#for_gem_extension
+# Hook for other libraries to load this library (e.g. via bundler)
+require "markly/merge"

data/sig/markly/merge.rbs

@@ -0,0 +1,106 @@
+module Markly
+  module Merge
+    VERSION: String
+
+    # Base error class for Markly::Merge
+    class Error < Markdown::Merge::Error
+    end
+
+    # Raised when a Markdown file has parsing errors
+    class ParseError < Markdown::Merge::ParseError
+      def initialize: (?String? message, ?content: String?, ?errors: Array[untyped]) -> void
+    end
+
+    # Raised when the template file has syntax errors
+    class TemplateParseError < ParseError
+    end
+
+    # Raised when the destination file has syntax errors
+    class DestinationParseError < ParseError
+    end
+
+    # Re-exported shared classes from markdown-merge
+    FileAligner: singleton(Markdown::Merge::FileAligner)
+    ConflictResolver: singleton(Markdown::Merge::ConflictResolver)
+    MergeResult: singleton(Markdown::Merge::MergeResult)
+    TableMatchAlgorithm: singleton(Markdown::Merge::TableMatchAlgorithm)
+    TableMatchRefiner: singleton(Markdown::Merge::TableMatchRefiner)
+    CodeBlockMerger: singleton(Markdown::Merge::CodeBlockMerger)
+
+    # Debug logging utility for Markly::Merge
+    module DebugLogger
+      extend Ast::Merge::DebugLogger
+
+      def self.env_var_name: () -> String
+      def self.env_var_name=: (String name) -> String
+      def self.log_prefix: () -> String
+      def self.log_prefix=: (String prefix) -> String
+      def self.enabled?: () -> bool
+      def self.debug: (*untyped args) -> void
+      def self.info: (*untyped args) -> void
+      def self.warning: (*untyped args) -> void
+      def self.time: [T] (String label) { () -> T } -> T
+      def self.log_node: (untyped node, ?label: String) -> void
+    end
+
+    # Represents a frozen block of Markdown content
+    class FreezeNode < Ast::Merge::FreezeNodeBase
+      def initialize: (
+        start_line: Integer,
+        end_line: Integer,
+        content: String,
+        start_marker: String,
+        end_marker: String,
+        ?nodes: Array[untyped],
+        ?reason: String?
+      ) -> void
+
+      def signature: () -> Array[Symbol | String]
+      def full_text: () -> String
+      def line_count: () -> Integer
+      def contains_type?: (Symbol type_symbol) -> bool
+      def inspect: () -> String
+    end
+
+    # File analysis for Markdown files using Markly
+    class FileAnalysis < Markdown::Merge::FileAnalysisBase
+      DEFAULT_FREEZE_TOKEN: String
+
+      def initialize: (
+        String source,
+        ?freeze_token: String,
+        ?signature_generator: (^(untyped) -> (Array[untyped] | untyped | nil))?,
+        ?flags: Integer,
+        ?extensions: Array[Symbol]
+      ) -> void
+
+      def parse_document: (String source) -> untyped
+      def next_sibling: (untyped node) -> untyped?
+      def freeze_node_class: () -> Class
+      def parser_node?: (untyped value) -> bool
+      def fallthrough_node?: (untyped value) -> bool
+      def compute_parser_signature: (untyped node) -> Array[untyped]?
+    end
+
+    # Orchestrates the smart merge process for Markdown files using Markly
+    class SmartMerger < Markdown::Merge::SmartMergerBase
+      def initialize: (
+        String template_content,
+        String dest_content,
+        ?signature_generator: (^(untyped) -> (Array[untyped] | untyped | nil))?,
+        ?preference: Symbol,
+        ?add_template_only_nodes: bool,
+        ?inner_merge_code_blocks: (bool | Markdown::Merge::CodeBlockMerger),
+        ?freeze_token: String,
+        ?match_refiner: (^(Array[untyped], Array[untyped], Hash[Symbol, untyped]) -> Array[Markdown::Merge::MatchResult])?,
+        ?flags: Integer,
+        ?extensions: Array[Symbol]
+      ) -> void
+
+      def create_file_analysis: (String content, **untyped options) -> FileAnalysis
+      def node_to_source: (untyped node, FileAnalysis analysis) -> String
+      def template_parse_error_class: () -> Class
+      def destination_parse_error_class: () -> Class
+    end
+  end
+end