canon 0.1.7 → 0.1.9

data/lib/canon/tree_diff/operation_converter_helpers/metadata_enricher.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative "../../diff/path_builder"
+require_relative "../../diff/node_serializer"
+
+module Canon
+  module TreeDiff
+    module OperationConverterHelpers
+      # Metadata enrichment for DiffNodes
+      # Handles path building, serialization, and attribute extraction
+      module MetadataEnricher
+        # Enrich DiffNode with canonical path, serialized content, and attributes
+        # This extracts presentation-ready metadata from TreeNodes for Stage 4 rendering
+        #
+        # @param tree_node1 [Canon::TreeDiff::Core::TreeNode, nil] First tree node
+        # @param tree_node2 [Canon::TreeDiff::Core::TreeNode, nil] Second tree node
+        # @param format [Symbol] Document format
+        # @return [Hash] Enriched metadata hash
+        def self.enrich(tree_node1, tree_node2, format)
+          {
+            path: build_path(tree_node1 || tree_node2, format),
+            serialized_before: serialize(tree_node1),
+            serialized_after: serialize(tree_node2),
+            attributes_before: extract_attributes(tree_node1),
+            attributes_after: extract_attributes(tree_node2),
+          }
+        end
+
+        # Build canonical path for a TreeNode
+        #
+        # @param tree_node [Canon::TreeDiff::Core::TreeNode] Tree node
+        # @param format [Symbol] Document format
+        # @return [String, nil] Canonical path with ordinal indices
+        def self.build_path(tree_node, format)
+          return nil if tree_node.nil?
+
+          Canon::Diff::PathBuilder.build(tree_node,
+                                         format: format == :xml ? :document : :fragment)
+        end
+
+        # Serialize a TreeNode's source node to string
+        #
+        # @param tree_node [Canon::TreeDiff::Core::TreeNode, nil] Tree node
+        # @return [String, nil] Serialized content
+        def self.serialize(tree_node)
+          return nil if tree_node.nil?
+
+          # Extract source node from TreeNode
+          source = if tree_node.respond_to?(:source_node)
+                     tree_node.source_node
+                   else
+                     tree_node
+                   end
+
+          Canon::Diff::NodeSerializer.serialize(source)
+        end
+
+        # Extract attributes from a TreeNode
+        #
+        # @param tree_node [Canon::TreeDiff::Core::TreeNode, nil] Tree node
+        # @return [Hash, nil] Attributes hash
+        def self.extract_attributes(tree_node)
+          return nil if tree_node.nil?
+
+          # Use TreeNode's attributes directly (already normalized by adapter)
+          tree_node.respond_to?(:attributes) ? (tree_node.attributes || {}) : {}
+        end
+      end
+    end
+  end
+end

data/lib/canon/tree_diff/operation_converter_helpers/post_processor.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+module Canon
+  module TreeDiff
+    module OperationConverterHelpers
+      # Post-processing of DiffNodes
+      # Handles detection of attribute-order-only differences and other optimizations
+      module PostProcessor
+        # Detect INSERT/DELETE pairs that differ only in attribute order
+        # and reclassify them to use the attribute_order dimension
+        #
+        # @param diff_nodes [Array<DiffNode>] Diff nodes to process
+        # @param normative_determiner [#call] Proc/object to determine normative status
+        # @return [Array<DiffNode>] Processed diff nodes
+        def self.detect_attribute_order_diffs(diff_nodes, normative_determiner)
+          # Group nodes by parent and element type
+          deletes = diff_nodes.select { |dn| dn.node1 && !dn.node2 }
+          inserts = diff_nodes.select { |dn| !dn.node1 && dn.node2 }
+
+          # For each DELETE, try to find a matching INSERT
+          deletes.each do |delete_node|
+            node1 = delete_node.node1
+            next unless node1.respond_to?(:name) && node1.respond_to?(:attributes)
+
+            # Skip if node has no attributes (can't be attribute order diff)
+            next if node1.attributes.nil? || node1.attributes.empty?
+
+            # Find inserts with same element name at same position
+            matching_insert = inserts.find do |insert_node|
+              node2 = insert_node.node2
+              next false unless node2.respond_to?(:name) && node2.respond_to?(:attributes)
+              next false unless node1.name == node2.name
+
+              # Must have attributes to differ in order
+              next false if node2.attributes.nil? || node2.attributes.empty?
+
+              # Check if they differ only in attribute order
+              next false unless attributes_equal_ignoring_order?(
+                node1.attributes, node2.attributes
+              )
+
+              # Ensure same content (text and children structure)
+              nodes_same_except_attr_order?(node1, node2)
+            end
+
+            next unless matching_insert
+
+            # Found an attribute-order-only difference
+            # Reclassify both nodes to use attribute_order dimension
+            delete_node.dimension = :attribute_order
+            delete_node.reason = "attribute order changed"
+            delete_node.normative = normative_determiner.call(:attribute_order)
+
+            matching_insert.dimension = :attribute_order
+            matching_insert.reason = "attribute order changed"
+            matching_insert.normative = normative_determiner.call(:attribute_order)
+          end
+
+          diff_nodes
+        end
+
+        # Check if two attribute hashes are equal ignoring order
+        #
+        # @param attrs1 [Hash] First attribute hash
+        # @param attrs2 [Hash] Second attribute hash
+        # @return [Boolean] True if attributes are equal (ignoring order)
+        def self.attributes_equal_ignoring_order?(attrs1, attrs2)
+          return true if attrs1.nil? && attrs2.nil?
+          return false if attrs1.nil? || attrs2.nil?
+
+          # Convert to hashes if needed
+          attrs1 = attrs1.to_h if attrs1.respond_to?(:to_h)
+          attrs2 = attrs2.to_h if attrs2.respond_to?(:to_h)
+
+          # Compare as sets (order-independent)
+          attrs1.sort.to_h == attrs2.sort.to_h
+        end
+
+        # Check if two nodes are the same except for attribute order
+        #
+        # @param node1 [Nokogiri::XML::Node] First node
+        # @param node2 [Nokogiri::XML::Node] Second node
+        # @return [Boolean] True if nodes are same except attribute order
+        def self.nodes_same_except_attr_order?(node1, node2)
+          # Same text content
+          return false if node1.text != node2.text
+
+          # Same number of children
+          return false if node1.children.length != node2.children.length
+
+          # If has children, they should have same structure
+          if node1.children.any?
+            node1.children.zip(node2.children).all? do |child1, child2|
+              child1.name == child2.name
+            end
+          else
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/canon/tree_diff/operation_converter_helpers/reason_builder.rb

@@ -0,0 +1,168 @@
+# frozen_string_literal: true
+
+require "set"
+
+module Canon
+  module TreeDiff
+    module OperationConverterHelpers
+      # Reason string builders for operations
+      # Handles creation of human-readable reason messages for DiffNodes
+      module ReasonBuilder
+        # Build reason string for INSERT operation
+        #
+        # @param operation [Operation] Operation
+        # @return [String] Reason description
+        def self.build_insert_reason(operation)
+          node = operation[:node]
+          content = operation[:content]
+
+          if node.respond_to?(:label)
+            # Include content preview for clarity
+            "Element inserted: #{content || "<#{node.label}>"}"
+          else
+            "Element inserted"
+          end
+        end
+
+        # Build reason string for DELETE operation
+        #
+        # @param operation [Operation] Operation
+        # @return [String] Reason description
+        def self.build_delete_reason(operation)
+          node = operation[:node]
+          content = operation[:content]
+
+          if node.respond_to?(:label)
+            # Include content preview for clarity
+            "Element deleted: #{content || "<#{node.label}>"}"
+          else
+            "Element deleted"
+          end
+        end
+
+        # Build reason string for UPDATE operation
+        #
+        # @param operation [Operation] Operation
+        # @return [String] Reason description
+        def self.build_update_reason(operation)
+          change_type = operation[:change_type] || "content"
+          "updated #{change_type}"
+        end
+
+        # Build reason string for MOVE operation
+        #
+        # @param operation [Operation] Operation
+        # @return [String] Reason description
+        def self.build_move_reason(operation)
+          from_pos = operation[:from_position]
+          to_pos = operation[:to_position]
+
+          if from_pos && to_pos
+            "moved from position #{from_pos} to #{to_pos}"
+          else
+            "moved to different position"
+          end
+        end
+
+        # Build detailed reason for attribute differences
+        #
+        # @param old_attrs [Hash] Old attributes
+        # @param new_attrs [Hash] New attributes
+        # @return [String] Detailed reason
+        def self.build_attribute_diff_details(old_attrs, new_attrs)
+          old_keys = Set.new(old_attrs.keys)
+          new_keys = Set.new(new_attrs.keys)
+
+          missing = old_keys - new_keys
+          extra = new_keys - old_keys
+          changed = (old_keys & new_keys).reject do |k|
+            old_attrs[k] == new_attrs[k]
+          end
+
+          parts = []
+          parts << "Missing: #{missing.to_a.join(', ')}" if missing.any?
+          parts << "Extra: #{extra.to_a.join(', ')}" if extra.any?
+          if changed.any?
+            parts << "Changed: #{changed.map do |k|
+              "#{k}=\"#{truncate(old_attrs[k],
+                                 20)}\" → \"#{truncate(new_attrs[k], 20)}\""
+            end.join(', ')}"
+          end
+
+          parts.any? ? "Attributes differ (#{parts.join('; ')})" : "Attribute values differ"
+        end
+
+        # Build reason for attribute value changes
+        #
+        # @param changes [Hash] Changes hash
+        # @return [String] Reason description
+        def self.build_attribute_value_reason(changes)
+          # Changes can be either true (flag) or { old: ..., new: ... } (detailed)
+          if changes.is_a?(Hash) && changes.key?(:old)
+            build_attribute_diff_details(changes[:old], changes[:new])
+          else
+            "attribute values differ"
+          end
+        end
+
+        # Build reason for attribute order changes
+        #
+        # @param changes [Hash] Changes hash
+        # @return [String] Reason description
+        def self.build_attribute_order_reason(changes)
+          if changes.is_a?(Hash) && changes.key?(:old)
+            old_order = changes[:old]
+            new_order = changes[:new]
+            "Attribute order changed: [#{old_order.join(', ')}] → [#{new_order.join(', ')}]"
+          else
+            "attribute order differs"
+          end
+        end
+
+        # Build reason for text content changes
+        #
+        # @param changes [Hash] Changes hash
+        # @return [String] Reason description
+        def self.build_text_content_reason(changes)
+          if changes.is_a?(Hash) && changes.key?(:old)
+            old_val = changes[:old] || ""
+            new_val = changes[:new] || ""
+            preview_old = truncate(old_val.to_s, 40)
+            preview_new = truncate(new_val.to_s, 40)
+            "Text content changed: \"#{preview_old}\" → \"#{preview_new}\""
+          else
+            "text content differs"
+          end
+        end
+
+        # Build reason for element name changes
+        #
+        # @param changes [Hash] Changes hash
+        # @return [String] Reason description
+        def self.build_element_name_reason(changes)
+          if changes.is_a?(Hash) && changes.key?(:old)
+            old_label = changes[:old]
+            new_label = changes[:new]
+            "Element name changed: <#{old_label}> → <#{new_label}>"
+          else
+            "element name differs"
+          end
+        end
+
+        # Truncate text for reason messages
+        #
+        # @param text [String] Text to truncate
+        # @param max_length [Integer] Maximum length
+        # @return [String] Truncated text
+        def self.truncate(text, max_length)
+          return "" if text.nil?
+
+          text = text.to_s
+          return text if text.length <= max_length
+
+          "#{text[0...max_length - 3]}..."
+        end
+      end
+    end
+  end
+end

data/lib/canon/tree_diff/operation_converter_helpers/update_change_handler.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require_relative "../operation_converter_helpers/reason_builder"
+
+module Canon
+  module TreeDiff
+    module OperationConverterHelpers
+      # Handles UPDATE operation conversion
+      # Processes different change types (attributes, attribute_order, value, label)
+      module UpdateChangeHandler
+        # Convert UPDATE operation to DiffNode(s)
+        #
+        # May return multiple DiffNodes if multiple dimensions changed
+        #
+        # @param operation [Operation] Update operation
+        # @param metadata [Hash] Enriched metadata from MetadataEnricher
+        # @param is_metadata [Boolean] Whether nodes are metadata elements
+        # @param normative_determiner [#call] Proc/object to determine normative status
+        # @return [Array<DiffNode>] Diff nodes representing updates
+        def self.convert(operation, metadata, is_metadata, normative_determiner)
+          tree_node1 = operation[:node1] # TreeNode from adapter
+          tree_node2 = operation[:node2] # TreeNode from adapter
+          node1 = tree_node1.respond_to?(:source_node) ? tree_node1.source_node : tree_node1
+          node2 = tree_node2.respond_to?(:source_node) ? tree_node2.source_node : tree_node2
+          changes = operation[:changes]
+
+          # Handle case where changes is a boolean or non-hash value
+          changes = {} unless changes.is_a?(Hash)
+
+          diff_nodes = []
+
+          # Create separate DiffNode for each change dimension
+          # This ensures each dimension can be classified independently
+
+          if changes.key?(:attributes)
+            diff_nodes << create_attribute_value_diff(
+              node1, node2, changes[:attributes], metadata, is_metadata, normative_determiner
+            )
+          end
+
+          if changes.key?(:attribute_order)
+            diff_nodes << create_attribute_order_diff(
+              node1, node2, changes[:attribute_order], metadata, is_metadata, normative_determiner
+            )
+          end
+
+          if changes.key?(:value)
+            diff_nodes << create_text_content_diff(
+              node1, node2, changes[:value], metadata, is_metadata, normative_determiner
+            )
+          end
+
+          if changes.key?(:label)
+            diff_nodes << create_element_name_diff(
+              node1, node2, changes[:label], metadata, is_metadata, normative_determiner
+            )
+          end
+
+          # If no specific changes detected, create a generic update
+          if diff_nodes.empty?
+            diff_nodes << create_generic_update_diff(
+              node1, node2, metadata, is_metadata, normative_determiner
+            )
+          end
+
+          diff_nodes
+        end
+
+        # Create DiffNode for attribute value differences
+        #
+        # @param node1 [Object] First node
+        # @param node2 [Object] Second node
+        # @param changes [Object] Attribute changes
+        # @param metadata [Hash] Enriched metadata
+        # @param is_metadata [Boolean] Whether nodes are metadata elements
+        # @param normative_determiner [#call] Proc to determine normative status
+        # @return [DiffNode] Diff node for attribute value differences
+        def self.create_attribute_value_diff(node1, node2, changes, metadata,
+is_metadata, normative_determiner)
+          diff_details = ReasonBuilder.build_attribute_value_reason(changes)
+
+          diff_node = Canon::Diff::DiffNode.new(
+            node1: node1,
+            node2: node2,
+            dimension: :attribute_values,
+            reason: diff_details,
+            **metadata,
+          )
+          diff_node.normative = is_metadata ? false : normative_determiner.call(:attribute_values)
+          diff_node
+        end
+
+        # Create DiffNode for attribute order differences
+        #
+        # @param node1 [Object] First node
+        # @param node2 [Object] Second node
+        # @param changes [Object] Attribute order changes
+        # @param metadata [Hash] Enriched metadata
+        # @param is_metadata [Boolean] Whether nodes are metadata elements
+        # @param normative_determiner [#call] Proc to determine normative status
+        # @return [DiffNode] Diff node for attribute order differences
+        def self.create_attribute_order_diff(node1, node2, changes, metadata,
+is_metadata, normative_determiner)
+          reason = ReasonBuilder.build_attribute_order_reason(changes)
+
+          diff_node = Canon::Diff::DiffNode.new(
+            node1: node1,
+            node2: node2,
+            dimension: :attribute_order,
+            reason: reason,
+            **metadata,
+          )
+          diff_node.normative = is_metadata ? false : normative_determiner.call(:attribute_order)
+          diff_node
+        end
+
+        # Create DiffNode for text content differences
+        #
+        # @param node1 [Object] First node
+        # @param node2 [Object] Second node
+        # @param changes [Object] Value changes
+        # @param metadata [Hash] Enriched metadata
+        # @param is_metadata [Boolean] Whether nodes are metadata elements
+        # @param normative_determiner [#call] Proc to determine normative status
+        # @return [DiffNode] Diff node for text content differences
+        def self.create_text_content_diff(node1, node2, changes, metadata,
+is_metadata, normative_determiner)
+          reason = ReasonBuilder.build_text_content_reason(changes)
+
+          diff_node = Canon::Diff::DiffNode.new(
+            node1: node1,
+            node2: node2,
+            dimension: :text_content,
+            reason: reason,
+            **metadata,
+          )
+          diff_node.normative = is_metadata ? false : normative_determiner.call(:text_content)
+          diff_node
+        end
+
+        # Create DiffNode for element name differences
+        #
+        # @param node1 [Object] First node
+        # @param node2 [Object] Second node
+        # @param changes [Object] Label changes
+        # @param metadata [Hash] Enriched metadata
+        # @param is_metadata [Boolean] Whether nodes are metadata elements
+        # @param normative_determiner [#call] Proc to determine normative status
+        # @return [DiffNode] Diff node for element name differences
+        def self.create_element_name_diff(node1, node2, changes, metadata,
+is_metadata, normative_determiner)
+          reason = ReasonBuilder.build_element_name_reason(changes)
+
+          diff_node = Canon::Diff::DiffNode.new(
+            node1: node1,
+            node2: node2,
+            dimension: :element_structure,
+            reason: reason,
+            **metadata,
+          )
+          diff_node.normative = is_metadata ? false : normative_determiner.call(:element_structure)
+          diff_node
+        end
+
+        # Create generic update DiffNode
+        #
+        # @param node1 [Object] First node
+        # @param node2 [Object] Second node
+        # @param metadata [Hash] Enriched metadata
+        # @param is_metadata [Boolean] Whether nodes are metadata elements
+        # @param normative_determiner [#call] Proc to determine normative status
+        # @return [DiffNode] Generic update diff node
+        def self.create_generic_update_diff(node1, node2, metadata,
+is_metadata, normative_determiner)
+          diff_node = Canon::Diff::DiffNode.new(
+            node1: node1,
+            node2: node2,
+            dimension: :text_content,
+            reason: "content differs",
+            **metadata,
+          )
+          diff_node.normative = is_metadata ? false : normative_determiner.call(:text_content)
+          diff_node
+        end
+      end
+    end
+  end
+end

data/lib/canon/version.rb

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

data/lib/canon/xml/data_model.rb

@@ -18,8 +18,9 @@ module Canon
       # Build XPath data model from XML string
       #
       # @param xml_string [String] XML content to parse
+      # @param preserve_whitespace [Boolean] Whether to preserve whitespace-only text nodes
       # @return [Nodes::RootNode] Root of the data model tree
-      def self.from_xml(xml_string)
+      def self.from_xml(xml_string, preserve_whitespace: false)
         # Parse with Nokogiri
         doc = Nokogiri::XML(xml_string) do |config|
           config.nonet     # Disable network access
@@ -30,7 +31,7 @@ module Canon
         check_for_relative_namespace_uris(doc)
 
         # Convert to XPath data model
-        build_from_nokogiri(doc)
+        build_from_nokogiri(doc, preserve_whitespace: preserve_whitespace)
       end
 
       # Alias for compatibility with base class interface
@@ -74,19 +75,21 @@ module Canon
 
       # Build XPath data model from Nokogiri document or fragment
       # rubocop:disable Metrics/MethodLength
-      def self.build_from_nokogiri(nokogiri_doc)
+      def self.build_from_nokogiri(nokogiri_doc, preserve_whitespace: false)
         root = Nodes::RootNode.new
 
         if nokogiri_doc.respond_to?(:root) && nokogiri_doc.root
           # For Documents (XML, HTML4, HTML5, Moxml): process the root element
-          root.add_child(build_element_node(nokogiri_doc.root))
+          root.add_child(build_element_node(nokogiri_doc.root,
+                                            preserve_whitespace: preserve_whitespace))
 
           # Process PIs and comments outside doc element
           nokogiri_doc.children.each do |child|
             next if child == nokogiri_doc.root
             next if child.is_a?(Nokogiri::XML::DTD)
 
-            node = build_node_from_nokogiri(child)
+            node = build_node_from_nokogiri(child,
+                                            preserve_whitespace: preserve_whitespace)
             root.add_child(node) if node
           end
         else
@@ -95,7 +98,8 @@ module Canon
           nokogiri_doc.children.each do |child|
             next if child.is_a?(Nokogiri::XML::DTD)
 
-            node = build_node_from_nokogiri(child)
+            node = build_node_from_nokogiri(child,
+                                            preserve_whitespace: preserve_whitespace)
             root.add_child(node) if node
           end
         end
@@ -104,12 +108,15 @@ module Canon
       end
 
       # Build node from Nokogiri node
-      def self.build_node_from_nokogiri(nokogiri_node)
+      def self.build_node_from_nokogiri(nokogiri_node,
+preserve_whitespace: false)
         case nokogiri_node
         when Nokogiri::XML::Element
-          build_element_node(nokogiri_node)
+          build_element_node(nokogiri_node,
+                             preserve_whitespace: preserve_whitespace)
         when Nokogiri::XML::Text
-          build_text_node(nokogiri_node)
+          build_text_node(nokogiri_node,
+                          preserve_whitespace: preserve_whitespace)
         when Nokogiri::XML::Comment
           build_comment_node(nokogiri_node)
         when Nokogiri::XML::ProcessingInstruction
@@ -119,7 +126,7 @@ module Canon
 
       # Build element node from Nokogiri element
       # rubocop:disable Metrics/MethodLength
-      def self.build_element_node(nokogiri_element)
+      def self.build_element_node(nokogiri_element, preserve_whitespace: false)
         element = Nodes::ElementNode.new(
           name: nokogiri_element.name,
           namespace_uri: nokogiri_element.namespace&.href,
@@ -134,7 +141,8 @@ module Canon
 
         # Build child nodes
         nokogiri_element.children.each do |child|
-          node = build_node_from_nokogiri(child)
+          node = build_node_from_nokogiri(child,
+                                          preserve_whitespace: preserve_whitespace)
           element.add_child(node) if node
         end
 
@@ -195,13 +203,16 @@ module Canon
       end
 
       # Build text node from Nokogiri text node
-      def self.build_text_node(nokogiri_text)
+      def self.build_text_node(nokogiri_text, preserve_whitespace: false)
         # 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)
+        # UNLESS preserve_whitespace is true (for structural_whitespace: :strict)
+        if !preserve_whitespace && content.strip.empty? && nokogiri_text.parent.is_a?(Nokogiri::XML::Element)
+          return nil
+        end
 
         # Nokogiri already handles CDATA conversion and entity resolution
         Nodes::TextNode.new(value: content)