commonmarker-merge 1.0.0

data/lib/commonmarker/merge.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+# Hard dependency - ensures commonmarker gem is installed
+require "commonmarker"
+
+# External gems
+require "version_gem"
+
+# Shared merge infrastructure (includes tree_haver)
+require "markdown/merge"
+
+# This gem
+require_relative "merge/version"
+
+module Commonmarker
+  # Smart merging for Markdown files using CommonMarker AST.
+  #
+  # Commonmarker::Merge provides intelligent merging of Markdown files by:
+  # - Parsing Markdown into AST using CommonMarker 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 commonmarker gem
+  # - Sets commonmarker-specific defaults (freeze token, inner_merge_code_blocks)
+  # - Maintains API compatibility for existing users
+  #
+  # @example Basic merge
+  #   merger = Commonmarker::Merge::SmartMerger.new(template, destination)
+  #   result = merger.merge
+  #   puts result.content if result.success?
+  #
+  # @example With freeze blocks
+  #   # In your Markdown file:
+  #   # <!-- commonmarker-merge:freeze -->
+  #   # ## Custom Section
+  #   # This content is preserved during merges.
+  #   # <!-- commonmarker-merge:unfreeze -->
+  #
+  # @see SmartMerger Main entry point for merging
+  # @see Markdown::Merge::SmartMerger Underlying implementation
+  module Merge
+    # Base error class for Commonmarker::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 commonmarker-merge
+    # @return [String]
+    DEFAULT_FREEZE_TOKEN = "commonmarker-merge"
+
+    # Default inner_merge_code_blocks setting for commonmarker-merge
+    # @return [Boolean]
+    DEFAULT_INNER_MERGE_CODE_BLOCKS = false
+
+    # 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, "commonmarker/merge/debug_logger"
+    autoload :FreezeNode, "commonmarker/merge/freeze_node"
+    autoload :FileAnalysis, "commonmarker/merge/file_analysis"
+    autoload :SmartMerger, "commonmarker/merge/smart_merger"
+    autoload :Backend, "commonmarker/merge/backend"
+
+    class << self
+      # Eagerly load and register backend when this module is loaded
+      # This ensures the backend is available for tree_haver before any parsing happens
+      def ensure_backend_loaded!
+        Backend # Access constant to trigger autoload
+      end
+    end
+  end
+end
+
+# Ensure backend is loaded and registered
+Commonmarker::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(
+    :commonmarker_merge,
+    require_path: "commonmarker/merge",
+    merger_class: "Commonmarker::Merge::SmartMerger",
+    test_source: "# Test\n\nParagraph",
+    category: :markdown,
+  )
+end
+
+Commonmarker::Merge::Version.class_eval do
+  extend VersionGem::Basic
+end

data/lib/commonmarker-merge.rb

@@ -0,0 +1,4 @@
+# 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 "commonmarker/merge"

data/sig/commonmarker/merge/conflict_resolver.rbs

@@ -0,0 +1,48 @@
+# Type signatures for Commonmarker::Merge::ConflictResolver
+#
+# Resolves conflicts between matching Markdown elements.
+# Determines which version to use based on configured preference.
+
+module Commonmarker
+  module Merge
+    class ConflictResolver
+      # Decision constants
+      DECISION_DESTINATION: Symbol
+      DECISION_TEMPLATE: Symbol
+      DECISION_ADDED: Symbol
+      DECISION_FROZEN: Symbol
+
+      # Merge preference
+      attr_reader preference: Symbol
+
+      # Template file analysis
+      attr_reader template_analysis: FileAnalysis
+
+      # Destination file analysis
+      attr_reader dest_analysis: FileAnalysis
+
+      # Initialize a conflict resolver
+      def initialize: (
+        preference: Symbol,
+        template_analysis: FileAnalysis,
+        dest_analysis: FileAnalysis
+      ) -> void
+
+      # Resolve a conflict between template and destination nodes
+      def resolve: (
+        untyped template_node,
+        untyped dest_node,
+        template_index: Integer,
+        dest_index: Integer
+      ) -> Hash[Symbol, untyped]
+
+      private
+
+      # Check if two nodes have identical content
+      def content_identical?: (untyped template_node, untyped dest_node) -> bool
+
+      # Convert a node to its source text
+      def node_to_text: (untyped node, FileAnalysis analysis) -> String
+    end
+  end
+end

data/sig/commonmarker/merge/debug_logger.rbs

@@ -0,0 +1,36 @@
+# Type signatures for Commonmarker::Merge::DebugLogger
+#
+# Debug logging utility for Commonmarker::Merge operations.
+# Extends Ast::Merge::DebugLogger module.
+
+module Commonmarker
+  module Merge
+    module DebugLogger
+      # Configured environment variable name
+      def self.env_var_name: () -> String
+      def self.env_var_name=: (String) -> String
+
+      # Configured log prefix
+      def self.log_prefix: () -> String
+      def self.log_prefix=: (String) -> String
+
+      # Check if debug mode is enabled
+      def self.enabled?: () -> bool
+
+      # Log a debug message with optional context
+      def self.debug: (String message, ?Hash[Symbol, untyped] context) -> void
+
+      # Log an info message
+      def self.info: (String message) -> void
+
+      # Log a warning message
+      def self.warning: (String message) -> void
+
+      # Time a block and log the duration
+      def self.time: [T] (String operation) { () -> T } -> T
+
+      # Extract node information for logging
+      def self.extract_node_info: (untyped node) -> Hash[Symbol, untyped]
+    end
+  end
+end

data/sig/commonmarker/merge/file_aligner.rbs

@@ -0,0 +1,27 @@
+# Type signatures for Commonmarker::Merge::FileAligner
+#
+# Aligns Markdown block elements between template and destination files.
+# Uses structural signatures to match elements.
+
+module Commonmarker
+  module Merge
+    class FileAligner
+      # Template file analysis
+      attr_reader template_analysis: FileAnalysis
+
+      # Destination file analysis
+      attr_reader dest_analysis: FileAnalysis
+
+      # Initialize a file aligner
+      def initialize: (FileAnalysis template_analysis, FileAnalysis dest_analysis) -> void
+
+      # Perform alignment between template and destination statements
+      def align: () -> Array[Hash[Symbol, untyped]]
+
+      private
+
+      # Build a map from signatures to statement indices
+      def build_signature_map: (Array[untyped] statements, FileAnalysis analysis) -> Hash[Array[untyped], Array[Integer]]
+    end
+  end
+end

data/sig/commonmarker/merge/file_analysis.rbs

@@ -0,0 +1,95 @@
+# Type signatures for Commonmarker::Merge::FileAnalysis
+#
+# File analysis for Markdown files using CommonMarker.
+# Parses Markdown and extracts block elements and freeze blocks.
+
+module Commonmarker
+  module Merge
+    class FileAnalysis
+      # Default freeze token for identifying freeze blocks
+      DEFAULT_FREEZE_TOKEN: String
+
+      # The root document node
+      attr_reader document: untyped
+
+      # Source Markdown content
+      attr_reader source: String
+
+      # Lines of source code
+      attr_reader lines: Array[String]
+
+      # Token used to mark freeze blocks
+      attr_reader freeze_token: String
+
+      # Custom signature generator
+      attr_reader signature_generator: (^(untyped) -> (Array[untyped] | nil | untyped))?
+
+      # All statements (nodes and freeze blocks)
+      attr_reader statements: Array[untyped]
+
+      # Initialize file analysis
+      def initialize: (
+        String source,
+        ?freeze_token: String,
+        ?signature_generator: (^(untyped) -> (Array[untyped] | nil | untyped))?,
+        ?options: Hash[Symbol, untyped]
+      ) -> void
+
+      # Check if parse was successful
+      def valid?: () -> bool
+
+      # Get freeze blocks
+      def freeze_blocks: () -> Array[FreezeNode]
+
+      # Get a specific line (1-indexed)
+      def line_at: (Integer line_number) -> String?
+
+      # Get a normalized line
+      def normalized_line: (Integer line_number) -> String?
+
+      # Get signature at index
+      def signature_at: (Integer index) -> Array[untyped]?
+
+      # Generate signature for a node
+      def generate_signature: (untyped node) -> Array[untyped]?
+
+      # Compute default signature for a node
+      def compute_node_signature: (untyped node) -> Array[untyped]?
+
+      # Compute signature for CommonMarker node
+      def compute_commonmarker_signature: (untyped node) -> Array[untyped]?
+
+      # Extract all text content from a node
+      def extract_text_content: (untyped node) -> String
+
+      # Get source text for a range of lines
+      def source_range: (Integer start_line, Integer end_line) -> String
+
+      private
+
+      # Count children of a node
+      def count_children: (untyped node) -> Integer
+
+      # Get node name
+      def node_name: (untyped node) -> String?
+
+      # Extract all nodes and integrate freeze blocks
+      def extract_and_integrate_all_nodes: () -> Array[untyped]
+
+      # Collect top-level nodes from document
+      def collect_top_level_nodes: () -> Array[untyped]
+
+      # Find freeze markers in source
+      def find_freeze_markers: () -> Array[Hash[Symbol, untyped]]
+
+      # Build freeze blocks from markers
+      def build_freeze_blocks: (Array[Hash[Symbol, untyped]] markers) -> Array[FreezeNode]
+
+      # Create a freeze block from start and end markers
+      def create_freeze_block: (Hash[Symbol, untyped] start_marker, Hash[Symbol, untyped] end_marker) -> FreezeNode
+
+      # Integrate nodes with freeze blocks
+      def integrate_nodes_with_freeze_blocks: (Array[FreezeNode] freeze_blocks) -> Array[untyped]
+    end
+  end
+end

data/sig/commonmarker/merge/freeze_node.rbs

@@ -0,0 +1,65 @@
+# Type signatures for Commonmarker::Merge::FreezeNode
+#
+# Represents a frozen block of Markdown content that should be
+# preserved during merges. Marked with HTML comments.
+
+module Commonmarker
+  module Merge
+    class FreezeNode < Ast::Merge::FreezeNode
+      # Regex pattern for HTML comment freeze markers
+      HTML_COMMENT_PATTERN: Regexp
+
+      # Build regex pattern for freeze markers
+      def self.pattern_for: (Symbol pattern_type, ?String? token) -> Regexp
+
+      # Start line number (1-indexed)
+      attr_reader start_line: Integer
+
+      # End line number (1-indexed)
+      attr_reader end_line: Integer
+
+      # Raw Markdown content within the freeze block
+      attr_reader content: String
+
+      # The start marker comment
+      attr_reader start_marker: String
+
+      # The end marker comment
+      attr_reader end_marker: String
+
+      # Parsed nodes within the freeze block
+      attr_reader nodes: Array[untyped]
+
+      # Initialize a new FreezeNode
+      def initialize: (
+        start_line: Integer,
+        end_line: Integer,
+        content: String,
+        start_marker: String,
+        end_marker: String,
+        ?nodes: Array[untyped],
+        ?reason: String?
+      ) -> void
+
+      # Generate a signature for matching this freeze block
+      def signature: () -> Array[Symbol | String]
+
+      # Get the full text including markers
+      def full_text: () -> String
+
+      # Get line count of the freeze block
+      def line_count: () -> Integer
+
+      # Check if block contains a specific node type
+      def contains_type?: (Symbol `type`) -> bool
+
+      # String representation for debugging
+      def inspect: () -> String
+
+      private
+
+      # Extract reason from the start marker comment
+      def extract_reason_from_marker: (String? marker) -> String?
+    end
+  end
+end

data/sig/commonmarker/merge/merge_result.rbs

@@ -0,0 +1,59 @@
+# Type signatures for Commonmarker::Merge::MergeResult
+#
+# Represents the result of a Markdown merge operation.
+# Contains merged content and metadata about the operation.
+
+module Commonmarker
+  module Merge
+    class MergeResult < Ast::Merge::MergeResult
+      # The merged Markdown content
+      attr_reader content: String?
+
+      # List of conflicts encountered during merge
+      attr_reader conflicts: Array[Hash[Symbol, untyped]]
+
+      # List of frozen blocks preserved during merge
+      attr_reader frozen_blocks: Array[Hash[Symbol, untyped]]
+
+      # Statistics about the merge operation
+      attr_reader stats: Hash[Symbol, untyped]
+
+      # Initialize a new MergeResult
+      def initialize: (
+        content: String?,
+        ?conflicts: Array[Hash[Symbol, untyped]],
+        ?frozen_blocks: Array[Hash[Symbol, untyped]],
+        ?stats: Hash[Symbol, untyped]
+      ) -> void
+
+      # Check if merge was successful
+      def success?: () -> bool
+
+      # Check if there are unresolved conflicts
+      def conflicts?: () -> bool
+
+      # Check if any frozen blocks were preserved
+      def has_frozen_blocks?: () -> bool
+
+      # Get count of nodes added during merge
+      def nodes_added: () -> Integer
+
+      # Get count of nodes removed during merge
+      def nodes_removed: () -> Integer
+
+      # Get count of nodes modified during merge
+      def nodes_modified: () -> Integer
+
+      # Get count of frozen blocks preserved
+      def frozen_count: () -> Integer
+
+      # String representation for debugging
+      def inspect: () -> String
+
+      private
+
+      # Default statistics hash
+      def default_stats: () -> Hash[Symbol, untyped]
+    end
+  end
+end

data/sig/commonmarker/merge/smart_merger.rbs

@@ -0,0 +1,53 @@
+# Type signatures for Commonmarker::Merge::SmartMerger
+#
+# Orchestrates the smart merge process for Markdown files.
+# Main entry point for intelligent Markdown merging.
+
+module Commonmarker
+  module Merge
+    class SmartMerger
+      # Analysis of the template file
+      attr_reader template_analysis: FileAnalysis
+
+      # Analysis of the destination file
+      attr_reader dest_analysis: FileAnalysis
+
+      # Aligner for finding matches and differences
+      attr_reader aligner: FileAligner
+
+      # Resolver for handling conflicting content
+      attr_reader resolver: ConflictResolver
+
+      # Initialize a SmartMerger
+      def initialize: (
+        String template_content,
+        String dest_content,
+        ?signature_generator: (^(untyped) -> (Array[untyped] | nil | untyped))?,
+        ?signature_match_preference: Symbol,
+        ?add_template_only_nodes: bool,
+        ?freeze_token: String,
+        ?options: Hash[Symbol, untyped]
+      ) -> void
+
+      # Perform the merge operation
+      def merge: () -> MergeResult
+
+      private
+
+      # Process alignment entries and build result
+      def process_alignment: (Array[Hash[Symbol, untyped]] alignment) -> [Array[String], Hash[Symbol, untyped], Array[Hash[Symbol, untyped]], Array[Hash[Symbol, untyped]]]
+
+      # Process a matched node pair
+      def process_match: (Hash[Symbol, untyped] entry, Hash[Symbol, untyped] stats) -> [String?, Hash[Symbol, untyped]?]
+
+      # Process a template-only node
+      def process_template_only: (Hash[Symbol, untyped] entry, Hash[Symbol, untyped] stats) -> String?
+
+      # Process a destination-only node
+      def process_dest_only: (Hash[Symbol, untyped] entry, Hash[Symbol, untyped] stats) -> [String?, Hash[Symbol, untyped]?]
+
+      # Convert a node to its source text
+      def node_to_source: (untyped node, FileAnalysis analysis) -> String
+    end
+  end
+end