canon 0.1.5 → 0.1.7

data/lib/canon/tree_diff/matchers/similarity_matcher.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require_relative "../core/tree_node"
+require_relative "../core/node_signature"
+require_relative "../core/matching"
+
+module Canon
+  module TreeDiff
+    module Matchers
+      # SimilarityMatcher performs similarity-based matching
+      #
+      # Based on JATS-diff (2022) approach:
+      # - Use Jaccard index for content similarity
+      # - Configurable similarity threshold (default 0.95)
+      # - Group candidates by signature for efficiency
+      # - Extend matches for unmatched nodes
+      #
+      # Features:
+      # - Handles text-centric documents
+      # - Fuzzy matching for similar but not identical nodes
+      # - Threshold-based filtering
+      # - Efficient signature-based grouping
+      class SimilarityMatcher
+        attr_reader :tree1, :tree2, :matching, :threshold
+
+        # Initialize matcher with two trees and existing matching
+        #
+        # @param tree1 [TreeNode] First tree root
+        # @param tree2 [TreeNode] Second tree root
+        # @param matching [Core::Matching] Existing matching from previous phase
+        # @param threshold [Float] Similarity threshold (0.0 to 1.0)
+        def initialize(tree1, tree2, matching, threshold: 0.95)
+          @tree1 = tree1
+          @tree2 = tree2
+          @matching = matching
+          @threshold = threshold
+        end
+
+        # Perform similarity-based matching
+        #
+        # @return [Core::Matching] Updated matching
+        def match
+          # Get unmatched nodes from both trees
+          all_nodes1 = collect_nodes(tree1)
+          all_nodes2 = collect_nodes(tree2)
+
+          unmatched1 = @matching.unmatched1(all_nodes1)
+          unmatched2 = @matching.unmatched2(all_nodes2)
+
+          # Group unmatched nodes by signature for efficiency
+          groups1 = group_by_signature(unmatched1)
+          groups2 = group_by_signature(unmatched2)
+
+          # For each signature group, find similar matches
+          groups2.each do |sig, nodes2|
+            # Find corresponding group in tree1
+            nodes1 = groups1[sig] || []
+            next if nodes1.empty?
+
+            # Match nodes within this signature group
+            match_group(nodes1, nodes2)
+          end
+
+          @matching
+        end
+
+        private
+
+        # Collect all nodes from a tree
+        #
+        # @param root [TreeNode] Root of tree
+        # @return [Array<TreeNode>]
+        def collect_nodes(root)
+          nodes = [root]
+          nodes.concat(root.descendants)
+          nodes
+        end
+
+        # Group nodes by signature
+        #
+        # For similarity matching, we use LOOSE signatures (element name only,
+        # no attributes) so that nodes with different attributes can still be
+        # compared for similarity. This allows matching nodes like:
+        #   <note id="A"> vs <note id="A" autonum="1">
+        #
+        # @param nodes [Array<TreeNode>] Nodes to group
+        # @return [Hash<NodeSignature, Array<TreeNode>>]
+        def group_by_signature(nodes)
+          nodes.group_by { |node| Core::NodeSignature.for(node, include_attributes: false) }
+        end
+
+        # Match nodes within a signature group
+        #
+        # @param nodes1 [Array<TreeNode>] Nodes from tree1
+        # @param nodes2 [Array<TreeNode>] Nodes from tree2
+        def match_group(nodes1, nodes2)
+          # Create similarity matrix
+          matches = []
+
+          nodes2.each do |node2|
+            next if @matching.matched2?(node2)
+
+            # Find best match in nodes1
+            best_match = nil
+            best_similarity = @threshold
+
+            nodes1.each do |node1|
+              next if @matching.matched1?(node1)
+
+              # CRITICAL: For whitespace-sensitive elements, require exact text match
+              # Don't fuzzy-match <pre>, <code>, etc. with different whitespace
+              if (whitespace_sensitive?(node1) || whitespace_sensitive?(node2)) && node1.value != node2.value
+                # For whitespace-sensitive elements, text must match exactly
+                next
+              end
+
+              similarity = node1.similarity_to(node2)
+
+              if similarity > best_similarity
+                best_similarity = similarity
+                best_match = node1
+              end
+            end
+
+            # Record match if found
+            if best_match
+              matches << [best_match, node2, best_similarity]
+            end
+          end
+
+          # Sort matches by similarity (highest first)
+          matches.sort_by! { |_, _, sim| -sim }
+
+          # Add matches in order of similarity
+          matches.each do |node1, node2, _similarity|
+            # Skip if already matched (by a higher-similarity match)
+            next if @matching.matched1?(node1)
+            next if @matching.matched2?(node2)
+
+            # Try to add match
+            @matching.add(node1, node2)
+          end
+        end
+
+        # Check if a node is whitespace-sensitive
+        #
+        # HTML elements where whitespace is significant: <pre>, <code>, <textarea>, <script>, <style>
+        #
+        # @param node [TreeNode] Node to check
+        # @return [Boolean] True if node is whitespace-sensitive
+        def whitespace_sensitive?(node)
+          return false unless node
+
+          # List of HTML elements where whitespace is semantically significant
+          whitespace_sensitive_tags = %w[pre code textarea script style]
+
+          # Check if this node is whitespace-sensitive
+          if node.respond_to?(:label)
+            label = node.label.to_s.downcase
+            return true if whitespace_sensitive_tags.include?(label)
+          end
+
+          false
+        end
+      end
+    end
+  end
+end

data/lib/canon/tree_diff/matchers/structural_propagator.rb

@@ -0,0 +1,242 @@
+# frozen_string_literal: true
+
+require_relative "../core/tree_node"
+require_relative "../core/node_weight"
+require_relative "../core/matching"
+
+module Canon
+  module TreeDiff
+    module Matchers
+      # StructuralPropagator extends matches using structural relationships
+      #
+      # Based on XyDiff/Cobena (2002, INRIA) propagation strategies:
+      # - Bottom-up: Match parents of matched children
+      # - Top-down: Match children of matched parents (lazy propagation)
+      #
+      # Propagation depth formula: 1 + (W / W₀)
+      # where W = node weight, W₀ = base weight threshold
+      #
+      # Features:
+      # - Conservative propagation (only when safe)
+      # - Weight-based depth control
+      # - Handles unique child labels
+      # - Preserves matching constraints
+      class StructuralPropagator
+        attr_reader :tree1, :tree2, :matching
+
+        # Base weight threshold for propagation depth
+        BASE_WEIGHT_THRESHOLD = 10.0
+
+        # Initialize propagator with trees and existing matching
+        #
+        # @param tree1 [TreeNode] First tree root
+        # @param tree2 [TreeNode] Second tree root
+        # @param matching [Core::Matching] Existing matching
+        def initialize(tree1, tree2, matching)
+          @tree1 = tree1
+          @tree2 = tree2
+          @matching = matching
+        end
+
+        # Perform structural propagation
+        #
+        # @return [Core::Matching] Updated matching
+        def propagate
+          # Phase 1: Bottom-up propagation
+          propagate_bottom_up
+
+          # Phase 2: Top-down propagation
+          propagate_top_down
+
+          @matching
+        end
+
+        private
+
+        # Bottom-up propagation: match parents of matched children
+        #
+        # If multiple children are matched and parents are compatible,
+        # match the parents too
+        def propagate_bottom_up
+          # Get all matched pairs
+          matched_pairs = @matching.to_a
+
+          # Process in reverse (children before parents)
+          matched_pairs.reverse.each do |node1, node2|
+            propagate_to_parent(node1, node2)
+          end
+        end
+
+        # Try to match parents of a matched pair
+        #
+        # @param node1 [TreeNode] Node from tree1
+        # @param node2 [TreeNode] Node from tree2
+        def propagate_to_parent(node1, node2)
+          parent1 = node1.parent
+          parent2 = node2.parent
+
+          return unless parent1 && parent2
+          return if @matching.matched1?(parent1)
+          return if @matching.matched2?(parent2)
+
+          # Check if parents are compatible
+          return unless parents_compatible?(parent1, parent2)
+
+          # Check propagation depth
+          weight1 = Core::NodeWeight.for(parent1).value
+          depth = propagation_depth(weight1)
+
+          return if depth < 1
+
+          # Try to match parents
+          @matching.add(parent1, parent2)
+        end
+
+        # Check if two parent nodes are compatible for matching
+        #
+        # Parents are compatible if:
+        # - Same label
+        # - Similar attributes
+        # - Matched children align properly
+        #
+        # @param parent1 [TreeNode] Parent from tree1
+        # @param parent2 [TreeNode] Parent from tree2
+        # @return [Boolean]
+        def parents_compatible?(parent1, parent2)
+          # Must have same label
+          return false unless parent1.label == parent2.label
+
+          # Must have similar attributes (allow some differences)
+          attr_sim = 1.0 - parent1.attribute_difference(parent2)
+          return false if attr_sim < 0.5
+
+          # Check that matched children align
+          matched_children_align?(parent1, parent2)
+        end
+
+        # Check if matched children of two parents align
+        #
+        # @param parent1 [TreeNode] Parent from tree1
+        # @param parent2 [TreeNode] Parent from tree2
+        # @return [Boolean]
+        def matched_children_align?(parent1, parent2)
+          # Get matched children
+          matched1 = parent1.children.select { |c| @matching.matched1?(c) }
+          parent2.children.select { |c| @matching.matched2?(c) }
+
+          return false if matched1.empty?
+
+          # Check each matched child in parent1
+          matched1.all? do |child1|
+            # Get its match in tree2
+            child2 = @matching.match_for1(child1)
+
+            # Check if child2 is actually a child of parent2
+            parent2.children.include?(child2)
+          end
+        end
+
+        # Top-down propagation: match children of matched parents
+        #
+        # If parents are matched and have unique corresponding children,
+        # match those children too
+        def propagate_top_down
+          # Get all matched pairs
+          matched_pairs = @matching.to_a
+
+          # Process each matched pair
+          matched_pairs.each do |node1, node2|
+            propagate_to_children(node1, node2)
+          end
+        end
+
+        # Try to match children of a matched pair
+        #
+        # @param node1 [TreeNode] Node from tree1
+        # @param node2 [TreeNode] Node from tree2
+        def propagate_to_children(node1, node2)
+          # Get unmatched children
+          unmatched1 = node1.children.reject { |c| @matching.matched1?(c) }
+          unmatched2 = node2.children.reject { |c| @matching.matched2?(c) }
+
+          return if unmatched1.empty? || unmatched2.empty?
+
+          # Find unique label correspondences
+          find_unique_matches(unmatched1, unmatched2)
+        end
+
+        # Find and match children with unique labels
+        #
+        # If a label appears exactly once in each parent's unmatched children,
+        # match those children
+        #
+        # @param children1 [Array<TreeNode>] Unmatched children from tree1
+        # @param children2 [Array<TreeNode>] Unmatched children from tree2
+        def find_unique_matches(children1, children2)
+          # Group children by label
+          by_label1 = children1.group_by(&:label)
+          by_label2 = children2.group_by(&:label)
+
+          # Find labels that appear exactly once in both
+          by_label1.each do |label, nodes1|
+            next unless nodes1.size == 1
+
+            nodes2 = by_label2[label]
+            next unless nodes2 && nodes2.size == 1
+
+            child1 = nodes1.first
+            child2 = nodes2.first
+
+            # CRITICAL: For whitespace-sensitive elements, check text values match
+            # Don't auto-match <pre>, <code>, etc. with different whitespace
+            if (whitespace_sensitive?(child1) || whitespace_sensitive?(child2)) && child1.value != child2.value
+              # For whitespace-sensitive elements, text must match exactly
+              next
+            end
+
+            # Check propagation depth
+            weight1 = Core::NodeWeight.for(child1).value
+            depth = propagation_depth(weight1)
+
+            next if depth < 1
+
+            # Try to match
+            @matching.add(child1, child2)
+          end
+        end
+
+        # Check if a node is whitespace-sensitive
+        #
+        # HTML elements where whitespace is significant: <pre>, <code>, <textarea>, <script>, <style>
+        #
+        # @param node [TreeNode] Node to check
+        # @return [Boolean] True if node is whitespace-sensitive
+        def whitespace_sensitive?(node)
+          return false unless node
+
+          # List of HTML elements where whitespace is semantically significant
+          whitespace_sensitive_tags = %w[pre code textarea script style]
+
+          # Check if this node is whitespace-sensitive
+          if node.respond_to?(:label)
+            label = node.label.to_s.downcase
+            return true if whitespace_sensitive_tags.include?(label)
+          end
+
+          false
+        end
+
+        # Calculate propagation depth based on node weight
+        #
+        # Formula: 1 + floor(W / W₀)
+        # where W = node weight, W₀ = base threshold
+        #
+        # @param weight [Float] Node weight
+        # @return [Integer] Propagation depth
+        def propagation_depth(weight)
+          1 + (weight / BASE_WEIGHT_THRESHOLD).floor
+        end
+      end
+    end
+  end
+end

data/lib/canon/tree_diff/matchers/universal_matcher.rb

@@ -0,0 +1,220 @@
+# frozen_string_literal: true
+
+module Canon
+  module TreeDiff
+    module Matchers
+      # UniversalMatcher orchestrates the complete matching process by combining
+      # hash-based, similarity-based, and structural propagation matching strategies.
+      #
+      # This is the main entry point for tree matching and follows a multi-phase
+      # pipeline approach:
+      #
+      # Phase 1: Hash Matching (XyDiff BULD)
+      #   - Exact signature matching for identical subtrees
+      #   - O(n log n) complexity via priority queue
+      #   - Processes heaviest nodes first
+      #
+      # Phase 2: Similarity Matching (JATS-diff)
+      #   - Content-based similarity via Jaccard index
+      #   - Configurable threshold (default 0.95)
+      #   - Groups by signature for efficiency
+      #
+      # Phase 3: Structural Propagation (XyDiff)
+      #   - Bottom-up: match parents of matched children
+      #   - Top-down: match children of matched parents
+      #   - Adaptive propagation depth based on weight
+      #
+      # @example Basic usage
+      #   matcher = UniversalMatcher.new
+      #   matching = matcher.match(tree1, tree2)
+      #   puts "Matched #{matching.size} nodes"
+      #
+      # @example With custom options
+      #   matcher = UniversalMatcher.new(
+      #     similarity_threshold: 0.9,
+      #     enable_propagation: false
+      #   )
+      #   matching = matcher.match(tree1, tree2)
+      #
+      class UniversalMatcher
+        # Default options for the matching process
+        DEFAULT_OPTIONS = {
+          # Minimum Jaccard similarity for content matching
+          similarity_threshold: 0.95,
+
+          # Enable hash-based exact matching
+          enable_hash_matching: true,
+
+          # Enable similarity-based matching
+          enable_similarity_matching: true,
+
+          # Enable structural propagation
+          enable_propagation: true,
+
+          # Maximum propagation depth (nil = adaptive)
+          max_propagation_depth: nil,
+
+          # Minimum weight for propagation
+          min_propagation_weight: 2.0,
+        }.freeze
+
+        attr_reader :options, :statistics
+
+        # Initialize a new UniversalMatcher
+        #
+        # @param options [Hash] Configuration options
+        # @option options [Float] :similarity_threshold (0.95)
+        #   Minimum similarity for content matching
+        # @option options [Boolean] :enable_hash_matching (true)
+        #   Enable hash-based exact matching
+        # @option options [Boolean] :enable_similarity_matching (true)
+        #   Enable similarity-based matching
+        # @option options [Boolean] :enable_propagation (true)
+        #   Enable structural propagation
+        # @option options [Integer, nil] :max_propagation_depth (nil)
+        #   Maximum propagation depth (nil = adaptive)
+        # @option options [Float] :min_propagation_weight (2.0)
+        #   Minimum weight for propagation
+        def initialize(options = {})
+          @options = DEFAULT_OPTIONS.merge(options)
+          @statistics = {}
+        end
+
+        # Match two trees and return a Matching object
+        #
+        # @param tree1 [TreeNode] First tree root
+        # @param tree2 [TreeNode] Second tree root
+        # @return [Matching] Matching object with all matched pairs
+        def match(tree1, tree2)
+          reset_statistics(tree1, tree2)
+
+          matching = Core::Matching.new
+
+          # Phase 1: Hash-based exact matching
+          if @options[:enable_hash_matching]
+            hash_matching_phase(tree1, tree2, matching)
+          end
+
+          # Phase 2: Similarity-based matching
+          if @options[:enable_similarity_matching]
+            similarity_matching_phase(tree1, tree2, matching)
+          end
+
+          # Phase 3: Structural propagation
+          if @options[:enable_propagation]
+            propagation_phase(tree1, tree2, matching)
+          end
+
+          finalize_statistics(matching)
+          matching
+        end
+
+        private
+
+        # Reset statistics for a new matching process
+        #
+        # @param tree1 [TreeNode] First tree root
+        # @param tree2 [TreeNode] Second tree root
+        def reset_statistics(tree1, tree2)
+          @statistics = {
+            tree1_nodes: count_nodes(tree1),
+            tree2_nodes: count_nodes(tree2),
+            hash_matches: 0,
+            similarity_matches: 0,
+            propagation_matches: 0,
+            total_matches: 0,
+            match_ratio_tree1: 0.0,
+            match_ratio_tree2: 0.0,
+            phases_executed: [],
+          }
+        end
+
+        # Execute hash-based matching phase
+        #
+        # @param tree1 [TreeNode] First tree root
+        # @param tree2 [TreeNode] Second tree root
+        # @param matching [Matching] Matching object to update
+        def hash_matching_phase(tree1, tree2, matching)
+          @statistics[:phases_executed] << :hash_matching
+
+          hash_matcher = HashMatcher.new(tree1, tree2, @options)
+          temp_matching = hash_matcher.match
+
+          # Transfer matches to the main matching object
+          temp_matching.pairs.each do |node1, node2|
+            matching.add(node1, node2)
+          end
+
+          @statistics[:hash_matches] = temp_matching.size
+        end
+
+        # Execute similarity-based matching phase
+        #
+        # @param tree1 [TreeNode] First tree root
+        # @param tree2 [TreeNode] Second tree root
+        # @param matching [Matching] Matching object to update
+        def similarity_matching_phase(tree1, tree2, matching)
+          @statistics[:phases_executed] << :similarity_matching
+
+          before_count = matching.size
+
+          similarity_matcher = SimilarityMatcher.new(
+            tree1,
+            tree2,
+            matching,
+            threshold: @options[:similarity_threshold],
+          )
+          similarity_matcher.match
+
+          @statistics[:similarity_matches] = matching.size - before_count
+        end
+
+        # Execute structural propagation phase
+        #
+        # @param tree1 [TreeNode] First tree root
+        # @param tree2 [TreeNode] Second tree root
+        # @param matching [Matching] Matching object to update
+        def propagation_phase(tree1, tree2, matching)
+          @statistics[:phases_executed] << :propagation
+
+          before_count = matching.size
+
+          propagator = StructuralPropagator.new(tree1, tree2, matching)
+          propagator.propagate
+
+          @statistics[:propagation_matches] = matching.size - before_count
+        end
+
+        # Finalize statistics after matching is complete
+        #
+        # @param matching [Matching] Final matching object
+        def finalize_statistics(matching)
+          @statistics[:total_matches] = matching.size
+
+          # Calculate match ratios
+          if @statistics[:tree1_nodes].positive?
+            @statistics[:match_ratio_tree1] =
+              matching.size.to_f / @statistics[:tree1_nodes]
+          end
+
+          if @statistics[:tree2_nodes].positive?
+            @statistics[:match_ratio_tree2] =
+              matching.size.to_f / @statistics[:tree2_nodes]
+          end
+        end
+
+        # Count total nodes in a tree
+        #
+        # @param node [TreeNode] Tree root
+        # @return [Integer] Total node count
+        def count_nodes(node)
+          count = 1
+          node.children.each do |child|
+            count += count_nodes(child)
+          end
+          count
+        end
+      end
+    end
+  end
+end