canon 0.1.7 → 0.1.8

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.8"
 end

data/old-docs/ADVANCED_TOPICS.adoc

@@ -0,0 +1,20 @@
+---
+layout: default
+title: Advanced Topics
+nav_order: 5
+has_children: true
+---
+= Advanced topics
+
+For developers and advanced users:
+
+* **link:VERBOSE[Verbose mode]** - Two-tier diff output architecture
+* **link:SEMANTIC_DIFF_REPORT[Semantic diff report]** - Detailed report
+format
+* **link:NORMATIVE_INFORMATIVE_DIFFS[Normative vs informative diffs]** - Diff
+classification
+* **link:DIFF_ARCHITECTURE[Diff architecture]** - Six-layer technical
+pipeline
+
+These documents cover Canon's internal architecture and advanced features for
+developers extending or maintaining Canon.

data/old-docs/BASIC_USAGE.adoc

@@ -0,0 +1,16 @@
+---
+layout: default
+title: Basic Usage
+nav_order: 2
+has_children: true
+---
+= Basic usage
+
+Choose your interface for working with Canon:
+
+* **link:RUBY_API[Ruby API]** - Using Canon from Ruby code
+* **link:CLI[Command-line interface]** - Terminal commands and options
+* **link:RSPEC[RSpec matchers]** - Testing with Canon in RSpec
+
+These guides provide practical examples and complete API reference for each
+interface.