canon 0.1.6 → 0.1.7

data/lib/canon/tree_diff/tree_diff_integrator.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+module Canon
+  module TreeDiff
+    # TreeDiffIntegrator provides integration between Canon's DOM diff system
+    # and the new semantic tree diff system.
+    #
+    # This class orchestrates:
+    # - Format-specific adapter selection
+    # - Tree conversion from parsed documents
+    # - Tree matching via UniversalMatcher
+    # - Operation detection
+    # - Results formatting
+    #
+    # @example XML tree diff
+    #   integrator = TreeDiffIntegrator.new(format: :xml)
+    #   result = integrator.diff(doc1, doc2)
+    #   result[:operations] # => [Operation(...), ...]
+    #
+    class TreeDiffIntegrator
+      attr_reader :format, :adapter, :matcher, :match_options
+
+      # Initialize integrator for a specific format
+      #
+      # @param format [Symbol] Format type (:xml, :json, :html, :yaml)
+      # @param options [Hash] Configuration options (match options from Canon::Comparison)
+      # @option options [Float] :similarity_threshold Threshold for similarity matching (default: 0.95)
+      # @option options [Boolean] :hash_matching Enable hash matching phase (default: true)
+      # @option options [Boolean] :similarity_matching Enable similarity matching phase (default: true)
+      # @option options [Boolean] :propagation Enable propagation phase (default: true)
+      # @option options [Symbol] :text_content How to compare text (:strict, :normalize)
+      # @option options [Symbol] :attribute_order How to compare attributes (:strict, :ignore)
+      def initialize(format:, options: {})
+        @format = format
+        @options = options
+        @match_options = options # Store full match options for downstream use
+
+        # Initialize format-specific adapter WITH match options
+        @adapter = create_adapter(format, options)
+
+        # Initialize matcher with options
+        matcher_options = {
+          similarity_threshold: options[:similarity_threshold] || 0.95,
+          hash_matching: options.fetch(:hash_matching, true),
+          similarity_matching: options.fetch(:similarity_matching, true),
+          propagation: options.fetch(:propagation, true),
+          attribute_order: options[:attribute_order] || :ignore,
+        }
+        @matcher = Matchers::UniversalMatcher.new(matcher_options)
+      end
+
+      # Perform tree diff on two documents
+      #
+      # @param doc1 [Object] First document (format-specific)
+      # @param doc2 [Object] Second document (format-specific)
+      # @return [Hash] Diff results with :operations, :matching, :statistics
+      def diff(doc1, doc2)
+        # Convert documents to tree nodes
+        tree1 = @adapter.to_tree(doc1)
+        tree2 = @adapter.to_tree(doc2)
+
+        # Check node count limits
+        check_node_count_limit(tree1)
+        check_node_count_limit(tree2)
+
+        # Match trees
+        matching = @matcher.match(tree1, tree2)
+
+        # Detect operations with match_options for proper normalization
+        detector = Operations::OperationDetector.new(tree1, tree2, matching,
+                                                     @match_options)
+        operations = detector.detect
+
+        # Return comprehensive results
+        {
+          operations: operations,
+          matching: matching,
+          statistics: @matcher.statistics,
+          trees: { tree1: tree1, tree2: tree2 },
+        }
+      end
+
+      # Check if two documents are semantically equivalent
+      #
+      # @param doc1 [Object] First document
+      # @param doc2 [Object] Second document
+      # @return [Boolean] true if no operations detected
+      def equivalent?(doc1, doc2)
+        result = diff(doc1, doc2)
+        result[:operations].empty?
+      end
+
+      private
+
+      # Create format-specific adapter
+      #
+      # @param format [Symbol] Format type
+      # @param match_options [Hash] Match options for text/attribute normalization
+      # @return [Object] Adapter instance
+      def create_adapter(format, match_options = {})
+        case format
+        when :xml
+          Adapters::XMLAdapter.new(match_options: match_options)
+        when :html, :html4, :html5
+          Adapters::HTMLAdapter.new(match_options: match_options)
+        when :json
+          Adapters::JSONAdapter.new(match_options: match_options)
+        when :yaml
+          Adapters::YAMLAdapter.new(match_options: match_options)
+        else
+          raise ArgumentError, "Unsupported format: #{format}. " \
+                               "Supported formats: :xml, :html, :html4, :html5, :json, :yaml"
+        end
+      end
+
+      # Check if tree node count exceeds configured limit
+      #
+      # @param tree [TreeNode] Root node of tree
+      # @raise [Canon::SizeLimitExceededError] if node count exceeds limit
+      def check_node_count_limit(tree)
+        node_count = tree.size
+        max_count = get_max_node_count
+
+        return unless max_count&.positive?
+        return if node_count <= max_count
+
+        raise Canon::SizeLimitExceededError.new(:node_count, node_count,
+                                                max_count)
+      end
+
+      # Get max node count limit for current format
+      #
+      # @return [Integer, nil] Max node count
+      def get_max_node_count
+        # Get from options if provided, otherwise use default
+        @options[:max_node_count] || 10_000
+      end
+    end
+  end
+end

data/lib/canon/tree_diff.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+module Canon
+  module TreeDiff
+    # Tree diff module for semantic object tree diffing
+  end
+end
+
+# Load core components
+require_relative "tree_diff/core/tree_node"
+require_relative "tree_diff/core/node_signature"
+require_relative "tree_diff/core/node_weight"
+require_relative "tree_diff/core/matching"
+
+# Load matchers
+require_relative "tree_diff/matchers/hash_matcher"
+require_relative "tree_diff/matchers/similarity_matcher"
+require_relative "tree_diff/matchers/structural_propagator"
+require_relative "tree_diff/matchers/universal_matcher"
+
+# Load operations
+require_relative "tree_diff/operations/operation"
+require_relative "tree_diff/operations/operation_detector"
+require_relative "tree_diff/operation_converter"
+
+# Load adapters
+require_relative "tree_diff/adapters/xml_adapter"
+require_relative "tree_diff/adapters/json_adapter"
+require_relative "tree_diff/adapters/html_adapter"
+require_relative "tree_diff/adapters/yaml_adapter"
+
+# Load integrator
+require_relative "tree_diff/tree_diff_integrator"

data/lib/canon/validators/json_validator.rb

@@ -17,7 +17,9 @@ module Canon
       # @raise [Canon::ValidationError] If JSON is malformed
       # @return [void]
       def self.validate!(input)
-        return if input.nil? || input.strip.empty?
+        return if input.nil?
+        return if input.is_a?(Hash) || input.is_a?(Array) # Already parsed
+        return if input.strip.empty?
 
         JSON.parse(input)
       rescue JSON::ParserError => e

data/lib/canon/validators/yaml_validator.rb

@@ -19,7 +19,9 @@ module Canon
       # @raise [Canon::ValidationError] If YAML is malformed
       # @return [void]
       def self.validate!(input)
-        return if input.nil? || input.strip.empty?
+        return if input.nil?
+        return if input.is_a?(Hash) || input.is_a?(Array) # Already parsed
+        return if input.strip.empty?
 
         YAML.safe_load(input, permitted_classes: [Symbol, Date, Time])
       rescue Psych::SyntaxError => e

data/lib/canon/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Canon
-  VERSION = "0.1.6"
+  VERSION = "0.1.7"
 end

data/lib/canon/xml/data_model.rb

@@ -2,6 +2,7 @@
 
 require "nokogiri"
 require "set"
+require_relative "../data_model"
 require_relative "nodes/root_node"
 require_relative "nodes/element_node"
 require_relative "nodes/namespace_node"
@@ -13,8 +14,11 @@ require_relative "nodes/processing_instruction_node"
 module Canon
   module Xml
     # Builds XPath data model from XML
-    class DataModel
+    class DataModel < Canon::DataModel
       # Build XPath data model from XML string
+      #
+      # @param xml_string [String] XML content to parse
+      # @return [Nodes::RootNode] Root of the data model tree
       def self.from_xml(xml_string)
         # Parse with Nokogiri
         doc = Nokogiri::XML(xml_string) do |config|
@@ -29,24 +33,19 @@ module Canon
         build_from_nokogiri(doc)
       end
 
-      # Build XPath data model from HTML string
-      #
-      # @param html_string [String] HTML content to parse
-      # @param version [Symbol] HTML version (:html4 or :html5)
-      # @return [Nodes::RootNode] Root of the data model tree
-      def self.from_html(html_string, version: :html4)
-        # Parse with Nokogiri using appropriate HTML parser
-        doc = if version == :html5
-                Nokogiri::HTML5.fragment(html_string)
-              else
-                Nokogiri::HTML4.fragment(html_string)
-              end
-
-        # HTML doesn't have strict namespace requirements like XML,
-        # so skip the relative namespace URI check
+      # Alias for compatibility with base class interface
+      def self.parse(xml_string)
+        from_xml(xml_string)
+      end
 
-        # Convert to XPath data model (reuse XML infrastructure)
-        build_from_nokogiri(doc)
+      # Serialize XML node to string
+      #
+      # @param node [Nodes::RootNode, Nodes::ElementNode] Node to serialize
+      # @return [String] Serialized XML string
+      def self.serialize(node)
+        # Implementation will delegate to existing XML serialization
+        # This is a placeholder for the base class interface
+        node.to_s
       end
 
       # Check for relative namespace URIs (prohibited by C14N 1.1)
@@ -184,9 +183,7 @@ module Canon
 
       # Build attribute nodes for an element
       def self.build_attribute_nodes(nokogiri_element, element)
-        nokogiri_element.attributes.each do |name, attr|
-          next if name.start_with?("xmlns")
-
+        nokogiri_element.attributes.each_value do |attr|
           attr_node = Nodes::AttributeNode.new(
             name: attr.name,
             value: attr.value,
@@ -199,9 +196,11 @@ module Canon
 
       # Build text node from Nokogiri text node
       def self.build_text_node(nokogiri_text)
-        # Skip text nodes that are only whitespace between elements
-        # unless they have significant content
+        # XML text nodes: preserve all content including whitespace
+        # Unlike HTML, XML treats all whitespace as significant
         content = nokogiri_text.content
+
+        # Skip empty text nodes between elements (common formatting whitespace)
         return nil if content.strip.empty? && nokogiri_text.parent.is_a?(Nokogiri::XML::Element)
 
         # Nokogiri already handles CDATA conversion and entity resolution

data/lib/canon/xml/element_matcher.rb

@@ -55,19 +55,63 @@ module Canon
       # Default attributes used to identify elements
       DEFAULT_IDENTITY_ATTRS = %w[id ref name key].freeze
 
-      # Match result for an element
-      MatchResult = Struct.new(:status, :elem1, :elem2, :path) do
+      # Represents the result of matching an element across two DOM trees
+      #
+      # A MatchResult indicates whether an element was found in both trees
+      # (matched), only in the first tree (deleted), or only in the second
+      # tree (inserted).
+      #
+      # == Attributes
+      #
+      # - status: Symbol indicating match type (:matched, :deleted, :inserted)
+      # - elem1: Element from first tree (nil if inserted)
+      # - elem2: Element from second tree (nil if deleted)
+      # - path: Array of element names showing location in tree
+      # - pos1: Integer index of elem1 in its parent's children (nil if inserted)
+      # - pos2: Integer index of elem2 in its parent's children (nil if deleted)
+      #
+      # == Position Change Detection
+      #
+      # When status is :matched and pos1 ≠ pos2, the element has moved positions.
+      # This is tracked as a semantic difference via the :element_position dimension.
+      #
+      class MatchResult
+        attr_reader :status, :elem1, :elem2, :path, :pos1, :pos2
+
+        # @param status [Symbol] Match status (:matched, :deleted, :inserted)
+        # @param elem1 [Object, nil] Element from first tree
+        # @param elem2 [Object, nil] Element from second tree
+        # @param path [Array<String>] Element path in tree
+        # @param pos1 [Integer, nil] Position index in first tree
+        # @param pos2 [Integer, nil] Position index in second tree
+        def initialize(status:, elem1:, elem2:, path:, pos1: nil, pos2: nil)
+          @status = status
+          @elem1 = elem1
+          @elem2 = elem2
+          @path = path
+          @pos1 = pos1
+          @pos2 = pos2
+        end
+
+        # @return [Boolean] true if element found in both trees
         def matched?
           status == :matched
         end
 
+        # @return [Boolean] true if element only in second tree
         def inserted?
           status == :inserted
         end
 
+        # @return [Boolean] true if element only in first tree
         def deleted?
           status == :deleted
         end
+
+        # @return [Boolean] true if element moved to different position
+        def position_changed?
+          matched? && pos1 && pos2 && pos1 != pos2
+        end
       end
 
       def initialize(identity_attrs: DEFAULT_IDENTITY_ATTRS)
@@ -105,13 +149,32 @@ module Canon
         map1.each do |identity, elem1|
           if map2.key?(identity)
             elem2 = map2[identity]
-            elem_path = path + [elem1.name]
-            @matches << MatchResult.new(:matched, elem1, elem2, elem_path)
+
+            # Build path with namespace information for clarity
+            elem_path_with_ns = if elem1.namespace_uri && !elem1.namespace_uri.empty?
+                                  path + ["{#{elem1.namespace_uri}}#{elem1.name}"]
+                                else
+                                  path + [elem1.name]
+                                end
+
+            # Track positions
+            pos1 = elems1.index(elem1)
+            pos2 = elems2.index(elem2)
+
+            @matches << MatchResult.new(
+              status: :matched,
+              elem1: elem1,
+              elem2: elem2,
+              path: elem_path_with_ns,
+              pos1: pos1,
+              pos2: pos2,
+            )
+
             matched1.add(elem1)
             matched2.add(elem2)
 
             # Recursively match children
-            match_children(elem1.children, elem2.children, elem_path)
+            match_children(elem1.children, elem2.children, elem_path_with_ns)
           end
         end
 
@@ -125,44 +188,89 @@ module Canon
         unmatched1.each do |elem1|
           next if matched1.include?(elem1)
 
-          elem_path = path + [elem1.name]
-          @matches << MatchResult.new(:deleted, elem1, nil, elem_path)
+          elem_path_with_ns = if elem1.namespace_uri && !elem1.namespace_uri.empty?
+                                path + ["{#{elem1.namespace_uri}}#{elem1.name}"]
+                              else
+                                path + [elem1.name]
+                              end
+          pos1 = elems1.index(elem1)
+
+          @matches << MatchResult.new(
+            status: :deleted,
+            elem1: elem1,
+            elem2: nil,
+            path: elem_path_with_ns,
+            pos1: pos1,
+            pos2: nil,
+          )
         end
 
         unmatched2.each do |elem2|
           next if matched2.include?(elem2)
 
-          elem_path = path + [elem2.name]
-          @matches << MatchResult.new(:inserted, nil, elem2, elem_path)
+          elem_path_with_ns = if elem2.namespace_uri && !elem2.namespace_uri.empty?
+                                path + ["{#{elem2.namespace_uri}}#{elem2.name}"]
+                              else
+                                path + [elem2.name]
+                              end
+          pos2 = elems2.index(elem2)
+
+          @matches << MatchResult.new(
+            status: :inserted,
+            elem1: nil,
+            elem2: elem2,
+            path: elem_path_with_ns,
+            pos1: nil,
+            pos2: pos2,
+          )
         end
       end
 
       # Match remaining elements by name and position
       def match_by_position(elems1, elems2, path, matched1, matched2)
-        # Group by element name
-        by_name1 = elems1.group_by(&:name)
-        by_name2 = elems2.group_by(&:name)
-
-        # For each name, match by position
-        by_name1.each do |name, list1|
-          next unless by_name2.key?(name)
+        # Group by element name AND namespace_uri
+        by_identity1 = elems1.group_by { |e| [e.name, e.namespace_uri] }
+        by_identity2 = elems2.group_by { |e| [e.name, e.namespace_uri] }
 
-          list2 = by_name2[name]
+        # For each name+namespace combination, match by position
+        by_identity1.each do |identity, list1|
+          next unless by_identity2.key?(identity)
 
           # Match pairs by position
+          list2 = by_identity2[identity]
+          name = identity[0] # Extract name from [name, namespace_uri] tuple
+          namespace_uri = identity[1] # Extract namespace_uri
+
           [list1.length, list2.length].min.times do |i|
             elem1 = list1[i]
             elem2 = list2[i]
 
             next if matched1.include?(elem1) || matched2.include?(elem2)
 
-            elem_path = path + [name]
-            @matches << MatchResult.new(:matched, elem1, elem2, elem_path)
+            # Build path with namespace information for clarity
+            elem_path_with_ns = if namespace_uri && !namespace_uri.empty?
+                                  path + ["{#{namespace_uri}}#{name}"]
+                                else
+                                  path + [name]
+                                end
+
+            # Track positions in original element lists
+            pos1 = elems1.index(elem1)
+            pos2 = elems2.index(elem2)
+
+            @matches << MatchResult.new(
+              status: :matched,
+              elem1: elem1,
+              elem2: elem2,
+              path: elem_path_with_ns,
+              pos1: pos1,
+              pos2: pos2,
+            )
             matched1.add(elem1)
             matched2.add(elem2)
 
             # Recursively match children
-            match_children(elem1.children, elem2.children, elem_path)
+            match_children(elem1.children, elem2.children, elem_path_with_ns)
           end
         end
       end

data/lib/canon/xml/namespace_helper.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+module Canon
+  module Xml
+    # Helper module for formatting namespace information in diff output
+    module NamespaceHelper
+      # Format a namespace URI for display in diff output
+      #
+      # @param namespace_uri [String, nil] The namespace URI to format
+      # @return [String] Formatted namespace string
+      #
+      # @example Empty namespace
+      #   format_namespace(nil) #=> "ns:[{blank}]"
+      #   format_namespace("") #=> "ns:[{blank}]"
+      #
+      # @example Populated namespace
+      #   format_namespace("http://example.com") #=> "ns:[http://example.com]"
+      def self.format_namespace(namespace_uri)
+        if namespace_uri.nil? || namespace_uri.empty?
+          "ns:[{blank}]"
+        else
+          "ns:[#{namespace_uri}]"
+        end
+      end
+
+      # Determine the type of mismatch between two nodes
+      #
+      # @param node1 [Object] First node (ElementNode or AttributeNode)
+      # @param node2 [Object] Second node (ElementNode or AttributeNode)
+      # @return [Symbol] Type of mismatch (:name, :namespace, :both, :none)
+      def self.mismatch_type(node1, node2)
+        return :none unless node1 && node2
+
+        name_differs = node1.name != node2.name
+        namespace_differs = normalize_namespace(node1.namespace_uri) !=
+          normalize_namespace(node2.namespace_uri)
+
+        if name_differs && namespace_differs
+          :both
+        elsif name_differs
+          :name
+        elsif namespace_differs
+          :namespace
+        else
+          :none
+        end
+      end
+
+      # Generate a mismatch message for element differences
+      #
+      # @param node1 [ElementNode] First element
+      # @param node2 [ElementNode] Second element
+      # @return [String] Human-readable mismatch message
+      def self.element_mismatch_message(node1, node2)
+        type = mismatch_type(node1, node2)
+
+        case type
+        when :name
+          ns = format_namespace(node1.namespace_uri)
+          "mismatched element name: '#{node1.name}' vs '#{node2.name}' (#{ns})"
+        when :namespace
+          "mismatched element namespace: '#{node1.name}' " \
+          "(#{format_namespace(node1.namespace_uri)} vs " \
+          "#{format_namespace(node2.namespace_uri)})"
+        when :both
+          "mismatched element name and namespace: " \
+          "'#{node1.name}' (#{format_namespace(node1.namespace_uri)}) vs " \
+          "'#{node2.name}' (#{format_namespace(node2.namespace_uri)})"
+        else
+          "elements differ"
+        end
+      end
+
+      # Generate a mismatch message for attribute differences
+      #
+      # @param node1 [AttributeNode] First attribute
+      # @param node2 [AttributeNode] Second attribute
+      # @return [String] Human-readable mismatch message
+      def self.attribute_mismatch_message(node1, node2)
+        type = mismatch_type(node1, node2)
+
+        case type
+        when :name
+          ns = format_namespace(node1.namespace_uri)
+          "mismatched attribute name: '#{node1.name}' vs '#{node2.name}' (#{ns})"
+        when :namespace
+          "mismatched attribute namespace: '#{node1.name}' " \
+          "(#{format_namespace(node1.namespace_uri)} vs " \
+          "#{format_namespace(node2.namespace_uri)})"
+        when :both
+          "mismatched attribute name and namespace: " \
+          "'#{node1.name}' (#{format_namespace(node1.namespace_uri)}) vs " \
+          "'#{node2.name}' (#{format_namespace(node2.namespace_uri)})"
+        else
+          "attributes differ"
+        end
+      end
+
+      # Normalize namespace URI for comparison
+      #
+      # @param namespace_uri [String, nil] Namespace URI
+      # @return [String] Normalized namespace (empty string for nil)
+      def self.normalize_namespace(namespace_uri)
+        namespace_uri.to_s
+      end
+
+      private_class_method :normalize_namespace
+    end
+  end
+end

data/lib/canon.rb

@@ -2,6 +2,9 @@
 
 require_relative "canon/version"
 require_relative "canon/errors"
+require_relative "canon/config"
+require_relative "canon/data_model"
+require_relative "canon/html"
 require_relative "canon/formatters/xml_formatter"
 require_relative "canon/formatters/yaml_formatter"
 require_relative "canon/formatters/json_formatter"