canon 0.1.6 → 0.1.7

data/lib/canon/tree_diff/core/attribute_comparator.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Canon
+  module TreeDiff
+    module Core
+      # AttributeComparator provides order-independent attribute comparison
+      #
+      # This class encapsulates the logic for comparing node attributes
+      # in a way that respects match options, particularly attribute_order.
+      #
+      # Key responsibilities:
+      # - Compare attributes with configurable order sensitivity
+      # - Provide hash-based equality for matching algorithms
+      # - Support both strict and normalized comparison modes
+      #
+      # @example
+      #   comparator = AttributeComparator.new(attribute_order: :ignore)
+      #   attrs1 = {class: "TOC", id: "_"}
+      #   attrs2 = {id: "_", class: "TOC"}
+      #   comparator.equal?(attrs1, attrs2) # => true
+      #
+      class AttributeComparator
+        attr_reader :attribute_order
+
+        # Initialize comparator with match options
+        #
+        # @param attribute_order [Symbol] :strict or :ignore/:normalize
+        def initialize(attribute_order: :strict)
+          @attribute_order = attribute_order
+        end
+
+        # Compare two attribute hashes for equality
+        #
+        # @param attrs1 [Hash] First attribute hash
+        # @param attrs2 [Hash] Second attribute hash
+        # @return [Boolean] True if attributes are considered equal
+        def equal?(attrs1, attrs2)
+          # Handle nil/empty cases
+          return true if attrs1.nil? && attrs2.nil?
+          return false if attrs1.nil? || attrs2.nil?
+
+          attrs1 = attrs1.to_h if attrs1.respond_to?(:to_h)
+          attrs2 = attrs2.to_h if attrs2.respond_to?(:to_h)
+
+          if attribute_order == :strict
+            # Strict mode: order matters
+            attrs1 == attrs2
+          else
+            # Ignore/normalize mode: sort keys for comparison
+            normalize_for_comparison(attrs1) == normalize_for_comparison(attrs2)
+          end
+        end
+
+        # Generate a comparison hash for attribute matching
+        #
+        # This is used by hash-based matchers to ensure nodes with
+        # equivalent attributes (according to match options) get the
+        # same hash value.
+        #
+        # @param attrs [Hash] Attribute hash
+        # @return [Hash] Normalized hash for comparison
+        def comparison_hash(attrs)
+          return {} if attrs.nil? || attrs.empty?
+
+          if attribute_order == :strict
+            attrs
+          else
+            normalize_for_comparison(attrs)
+          end
+        end
+
+        private
+
+        # Normalize attributes for order-independent comparison
+        #
+        # @param attrs [Hash] Attribute hash
+        # @return [Hash] Sorted attribute hash
+        def normalize_for_comparison(attrs)
+          attrs.sort.to_h
+        end
+      end
+    end
+  end
+end

data/lib/canon/tree_diff/core/matching.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+module Canon
+  module TreeDiff
+    module Core
+      # Matching stores and manages node pair matches
+      #
+      # A matching is a set of pairs (n1, n2) where:
+      # 1. One-to-one: Each node appears in at most one pair
+      # 2. Prefix closure: If (n1, n2) matched, ancestors can match
+      #
+      # Features:
+      # - Efficient lookup: O(1) for checking if node is matched
+      # - Validation: Ensures constraints are maintained
+      # - Iteration: Supports enumeration of all pairs
+      class Matching
+        attr_reader :pairs
+
+        # Initialize empty matching
+        def initialize
+          @pairs = []
+          @tree1_map = {} # node => matched_node
+          @tree2_map = {} # node => matched_node
+        end
+
+        # Add a matched pair
+        #
+        # @param node1 [TreeNode] Node from tree 1
+        # @param node2 [TreeNode] Node from tree 2
+        # @return [Boolean] true if added, false if violates constraints
+        def add(node1, node2)
+          return false unless valid_pair?(node1, node2)
+
+          @pairs << [node1, node2]
+          @tree1_map[node1] = node2
+          @tree2_map[node2] = node1
+
+          true
+        end
+
+        # Remove a matched pair
+        #
+        # @param node1 [TreeNode] Node from tree 1
+        # @param node2 [TreeNode] Node from tree 2
+        # @return [Boolean] true if removed, false if not found
+        def remove(node1, node2)
+          removed = @pairs.delete([node1, node2])
+          return false unless removed
+
+          @tree1_map.delete(node1)
+          @tree2_map.delete(node2)
+
+          true
+        end
+
+        # Check if a node from tree 1 is matched
+        #
+        # @param node [TreeNode] Node to check
+        # @return [Boolean]
+        def matched1?(node)
+          @tree1_map.key?(node)
+        end
+
+        # Check if a node from tree 2 is matched
+        #
+        # @param node [TreeNode] Node to check
+        # @return [Boolean]
+        def matched2?(node)
+          @tree2_map.key?(node)
+        end
+
+        # Get the match for a node from tree 1
+        #
+        # @param node [TreeNode] Node from tree 1
+        # @return [TreeNode, nil] Matched node from tree 2, or nil
+        def match_for1(node)
+          @tree1_map[node]
+        end
+
+        # Get the match for a node from tree 2
+        #
+        # @param node [TreeNode] Node from tree 2
+        # @return [TreeNode, nil] Matched node from tree 1, or nil
+        def match_for2(node)
+          @tree2_map[node]
+        end
+
+        # Get all unmatched nodes from tree 1
+        #
+        # @param nodes [Array<TreeNode>] All nodes from tree 1
+        # @return [Array<TreeNode>]
+        def unmatched1(nodes)
+          nodes.reject { |node| matched1?(node) }
+        end
+
+        # Get all unmatched nodes from tree 2
+        #
+        # @param nodes [Array<TreeNode>] All nodes from tree 2
+        # @return [Array<TreeNode>]
+        def unmatched2(nodes)
+          nodes.reject { |node| matched2?(node) }
+        end
+
+        # Get number of matched pairs
+        #
+        # @return [Integer]
+        def size
+          @pairs.size
+        end
+
+        # Check if matching is empty
+        #
+        # @return [Boolean]
+        def empty?
+          @pairs.empty?
+        end
+
+        # Iterate over all pairs
+        #
+        # @yield [node1, node2]
+        def each(&block)
+          @pairs.each(&block)
+        end
+
+        # Check if matching satisfies all constraints
+        #
+        # @return [Boolean]
+        def valid?
+          # Check one-to-one constraint
+          return false unless one_to_one?
+
+          # Check prefix closure constraint
+          return false unless prefix_closure?
+
+          true
+        end
+
+        # Check one-to-one constraint
+        #
+        # Each node appears in at most one pair
+        #
+        # @return [Boolean]
+        def one_to_one?
+          # Check tree1 map has unique values
+          tree1_values = @tree1_map.values
+          return false unless tree1_values.size == tree1_values.uniq.size
+
+          # Check tree2 map has unique values
+          tree2_values = @tree2_map.values
+          return false unless tree2_values.size == tree2_values.uniq.size
+
+          # Check maps are consistent
+          @tree1_map.all? { |n1, n2| @tree2_map[n2] == n1 }
+        end
+
+        # Check prefix closure constraint
+        #
+        # If (n1, n2) matched and ancestors (a1, a2) matched,
+        # then a1 is ancestor of n1 iff a2 is ancestor of n2
+        #
+        # @return [Boolean]
+        def prefix_closure?
+          @pairs.each do |node1, node2|
+            # Check each ancestor pair
+            node1.ancestors.each_with_index do |anc1, idx|
+              anc2 = node2.ancestors[idx]
+
+              # If ancestor matched, must be to corresponding ancestor
+              if matched1?(anc1)
+                match = match_for1(anc1)
+                return false unless match == anc2
+              end
+            end
+          end
+
+          true
+        end
+
+        # Convert to array of pairs
+        #
+        # @return [Array<Array<TreeNode, TreeNode>>]
+        def to_a
+          @pairs.dup
+        end
+
+        # String representation
+        #
+        # @return [String]
+        def to_s
+          "#<Matching #{size} pairs>"
+        end
+
+        # Detailed inspection
+        #
+        # @return [String]
+        def inspect
+          pairs_str = @pairs.map do |n1, n2|
+            "(#{n1.label} ↔ #{n2.label})"
+          end.join(", ")
+
+          "#<Matching [#{pairs_str}]>"
+        end
+
+        private
+
+        # Check if a pair can be added without violating constraints
+        #
+        # @param node1 [TreeNode] Node from tree 1
+        # @param node2 [TreeNode] Node from tree 2
+        # @return [Boolean]
+        def valid_pair?(node1, node2)
+          # Check one-to-one constraint
+          return false if matched1?(node1)
+          return false if matched2?(node2)
+
+          # Check prefix closure constraint
+          # If ancestors are matched, they must be matched to each other
+          node1.ancestors.each_with_index do |anc1, idx|
+            # Get corresponding ancestor in tree2
+            anc2_ancestors = node2.ancestors
+            return false if idx >= anc2_ancestors.size
+
+            anc2 = anc2_ancestors[idx]
+
+            # If anc1 is matched, it must be matched to anc2
+            if matched1?(anc1) && match_for1(anc1) != anc2
+              return false
+            end
+
+            # If anc2 is matched, it must be matched to anc1
+            if matched2?(anc2) && match_for2(anc2) != anc1
+              return false
+            end
+          end
+
+          true
+        end
+      end
+    end
+  end
+end

data/lib/canon/tree_diff/core/node_signature.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Canon
+  module TreeDiff
+    module Core
+      # NodeSignature computes unique signatures for tree nodes
+      #
+      # Based on XDiff (2002, U. Wisconsin) approach:
+      # - Signature is the path from root to node
+      # - Format: /ancestor1/ancestor2/.../node/type
+      # - Used for fast exact matching via hash lookup
+      #
+      # Features:
+      # - Deterministic: Same path always produces same signature
+      # - Hierarchical: Parent-child relationships encoded
+      # - Type-aware: Distinguishes element vs text nodes
+      class NodeSignature
+        attr_reader :path, :signature_string
+
+        # Initialize signature for a node
+        #
+        # @param node [TreeNode] Node to compute signature for
+        # @param include_attributes [Boolean] Whether to include attributes
+        def initialize(node, include_attributes: true)
+          @node = node
+          @include_attributes = include_attributes
+          @path = compute_path
+          @signature_string = compute_signature_string
+        end
+
+        # Compute and cache signature for a node
+        #
+        # @param node [TreeNode] Node to compute signature for
+        # @param include_attributes [Boolean] Whether to include attributes in signature
+        # @return [NodeSignature]
+        def self.for(node, include_attributes: true)
+          if include_attributes
+            node.signature ||= new(node, include_attributes: true)
+          else
+            # Don't cache loose signatures
+            new(node, include_attributes: false)
+          end
+        end
+
+        # Check if two signatures are equal
+        #
+        # @param other [NodeSignature] Signature to compare with
+        # @return [Boolean]
+        def ==(other)
+          return false unless other.is_a?(NodeSignature)
+
+          signature_string == other.signature_string
+        end
+
+        alias eql? ==
+
+        # Hash value for use in Hash/Set
+        #
+        # @return [Integer]
+        def hash
+          signature_string.hash
+        end
+
+        # String representation
+        #
+        # @return [String]
+        def to_s
+          signature_string
+        end
+
+        # Detailed inspection
+        #
+        # @return [String]
+        def inspect
+          "#<NodeSignature #{signature_string.inspect}>"
+        end
+
+        private
+
+        # Compute the path from root to this node
+        #
+        # @return [Array<String>] Path components
+        def compute_path
+          components = []
+
+          # Build path from root to node
+          ancestors = @node.ancestors.reverse
+          ancestors.each do |ancestor|
+            components << path_component(ancestor)
+          end
+
+          # Add the node itself
+          components << path_component(@node)
+
+          components
+        end
+
+        # Get path component for a node
+        #
+        # @param node [TreeNode] Node to get component for
+        # @return [String]
+        def path_component(node)
+          # For element nodes: use label with sorted attributes
+          # For text nodes: use "#text"
+          # CRITICAL: Text nodes should use "#text" not "text"
+          # Check the label - actual text nodes have no label or label == "text"
+          label_str = node.label.to_s.downcase
+          if node.label.nil? || label_str.empty? || label_str == "#text" || label_str == "text"
+            "#text"
+          else
+            component = node.label.to_s
+
+            # Include sorted attributes to distinguish nodes with same label
+            # but different attributes (while ignoring attribute order)
+            # Only include attributes if requested (for hash matching)
+            if @include_attributes && !node.attributes.empty?
+              sorted_attrs = node.attributes.sort.to_h
+              attrs_str = sorted_attrs.map { |k, v| "#{k}=#{v}" }.join(",")
+              component += "{#{attrs_str}}"
+            end
+
+            # CRITICAL: For whitespace-sensitive HTML elements, include the text value
+            # in the signature to prevent incorrect matching of nodes with different whitespace
+            if @include_attributes && whitespace_sensitive?(node) && node.value
+              # Include text value in signature for whitespace-sensitive elements
+              # Use inspect to make whitespace visible and handle special characters
+              component += "[text=#{node.value.inspect}]"
+            end
+
+            component
+          end
+        end
+
+        # Check if a node is in a whitespace-sensitive context
+        #
+        # 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
+
+        # Compute signature string from path
+        #
+        # @return [String]
+        def compute_signature_string
+          "/#{path.join('/')}"
+        end
+      end
+    end
+  end
+end

data/lib/canon/tree_diff/core/node_weight.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+module Canon
+  module TreeDiff
+    module Core
+      # NodeWeight computes weights for tree nodes
+      #
+      # Based on XyDiff/Cobena (2002, INRIA) approach:
+      # - Weight reflects subtree size/importance
+      # - Formula: 1 + Σ(child_weights)
+      # - Text nodes: 1 + log(text_length) for significant text
+      # - Used to prioritize matching (heaviest first)
+      #
+      # Features:
+      # - Hierarchical: Parent weight includes all descendants
+      # - Text-aware: Longer text has higher weight
+      # - Cached: Computed once and reused
+      class NodeWeight
+        attr_reader :value
+
+        # Initialize weight for a node
+        #
+        # @param node [TreeNode] Node to compute weight for
+        def initialize(node)
+          @node = node
+          @value = compute_weight
+        end
+
+        # Compute and cache weight for a node
+        #
+        # @param node [TreeNode] Node to compute weight for
+        # @return [NodeWeight]
+        def self.for(node)
+          node.weight ||= new(node)
+        end
+
+        # Compare weights (for sorting)
+        #
+        # @param other [NodeWeight] Weight to compare with
+        # @return [Integer] -1, 0, or 1
+        def <=>(other)
+          return nil unless other.is_a?(NodeWeight)
+
+          value <=> other.value
+        end
+
+        # Check if equal
+        #
+        # @param other [NodeWeight] Weight to compare with
+        # @return [Boolean]
+        def ==(other)
+          return false unless other.is_a?(NodeWeight)
+
+          value == other.value
+        end
+
+        # Numeric value for calculations
+        #
+        # @return [Float]
+        def to_f
+          value
+        end
+
+        # Integer value for calculations
+        #
+        # @return [Integer]
+        def to_i
+          value.to_i
+        end
+
+        # String representation
+        #
+        # @return [String]
+        def to_s
+          value.to_s
+        end
+
+        # Detailed inspection
+        #
+        # @return [String]
+        def inspect
+          "#<NodeWeight #{value}>"
+        end
+
+        private
+
+        # Compute weight based on node type and structure
+        #
+        # @return [Float]
+        def compute_weight
+          if @node.text?
+            compute_text_weight
+          else
+            compute_element_weight
+          end
+        end
+
+        # Compute weight for text nodes
+        #
+        # Formula: 1 + log(text_length)
+        # - Minimum weight is 1.0 (empty text)
+        # - Grows logarithmically with text length
+        # - Prevents very long text from dominating
+        #
+        # @return [Float]
+        def compute_text_weight
+          text = @node.value.to_s
+          return 1.0 if text.empty?
+
+          # Use natural logarithm (log base e)
+          # Add 1 to avoid log(0)
+          1.0 + Math.log(text.length + 1)
+        end
+
+        # Compute weight for element nodes
+        #
+        # Formula: 1 + Σ(child_weights)
+        # - Each node has base weight of 1
+        # - Parent weight includes all descendants
+        # - Recursive computation
+        #
+        # @return [Float]
+        def compute_element_weight
+          return 1.0 if @node.children.empty?
+
+          child_weights = @node.children.map do |child|
+            self.class.for(child).value
+          end
+
+          1.0 + child_weights.sum
+        end
+      end
+    end
+  end
+end