canon 0.1.7 → 0.1.9

data/lib/canon/diff/diff_node.rb

@@ -5,9 +5,19 @@ module Canon
     # Represents a semantic difference between two nodes in a comparison tree
     # This is created during the Comparison Layer and carries information about
     # which dimension caused the difference and whether it's normative or informative
+    #
+    # DiffNode is library-agnostic - it works with data extracted from nodes,
+    # not the raw node references themselves. This allows Canon to work with
+    # any parsing library (Nokogiri, Moxml, etc.) without being tied to it.
     class DiffNode
       attr_reader :node1, :node2
-      attr_accessor :dimension, :reason, :normative, :formatting
+      attr_accessor :dimension, :reason, :normative, :formatting,
+                    # Enriched metadata for Stage 4 rendering
+                    :path, # Canonical path with ordinal indices
+                    :serialized_before,  # Serialized content for display (before)
+                    :serialized_after,   # Serialized content for display (after)
+                    :attributes_before,  # Normalized attributes hash (before)
+                    :attributes_after    # Normalized attributes hash (after)
 
       # @param node1 [Object] The first node being compared
       # @param node2 [Object] The second node being compared
@@ -15,13 +25,26 @@ module Canon
       #   (e.g., :text_content, :attribute_whitespace, :structural_whitespace,
       #   :comments, :key_order)
       # @param reason [String] Human-readable explanation of the difference
-      def initialize(node1:, node2:, dimension:, reason:)
+      # @param path [String, nil] Optional canonical path with ordinal indices
+      # @param serialized_before [String, nil] Optional serialized content for display
+      # @param serialized_after [String, nil] Optional serialized content for display
+      # @param attributes_before [Hash, nil] Optional normalized attributes hash
+      # @param attributes_after [Hash, nil] Optional normalized attributes hash
+      def initialize(node1:, node2:, dimension:, reason:,
+                     path: nil, serialized_before: nil, serialized_after: nil,
+                     attributes_before: nil, attributes_after: nil)
         @node1 = node1
         @node2 = node2
         @dimension = dimension
         @reason = reason
         @normative = nil # Will be set by DiffClassifier
         @formatting = nil # Will be set by DiffClassifier
+        # Enriched metadata (optional, populated by PathBuilder and NodeSerializer)
+        @path = path
+        @serialized_before = serialized_before
+        @serialized_after = serialized_after
+        @attributes_before = attributes_before
+        @attributes_after = attributes_after
       end
 
       # @return [Boolean] true if this diff is normative (affects equivalence)
@@ -54,6 +77,11 @@ module Canon
           reason: reason,
           normative: normative,
           formatting: formatting,
+          path: path,
+          serialized_before: serialized_before,
+          serialized_after: serialized_after,
+          attributes_before: attributes_before,
+          attributes_after: attributes_after,
         }
       end
 
@@ -65,6 +93,8 @@ module Canon
           reason == other.reason &&
           normative == other.normative &&
           formatting == other.formatting
+        # Note: path and serialized content are not part of equality
+        # since they're derived from nodes, not independent properties
       end
     end
   end

data/lib/canon/diff/formatting_detector.rb

@@ -11,7 +11,7 @@ module Canon
       # @param line2 [String, nil] Second line to compare
       # @return [Boolean] true if lines differ only in formatting
       def self.formatting_only?(line1, line2)
-        # If both are nil or empty, not a formatting diff
+        # If both are nil or empty, not a formatting diff (no difference)
         return false if blank?(line1) && blank?(line2)
 
         # If only one is blank, it's not just formatting

data/lib/canon/diff/node_serializer.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require_relative "../xml/data_model"
+require_relative "../xml/nodes/text_node"
+require_relative "../xml/nodes/comment_node"
+require_relative "../xml/nodes/element_node"
+require_relative "../xml/nodes/processing_instruction_node"
+require_relative "../xml/nodes/root_node"
+
+module Canon
+  module Diff
+    # Serializes nodes from different parsing libraries into canonical strings
+    # This abstraction allows Canon to work with any parsing library
+    # (Nokogiri, Moxml, etc.) without being tied to a specific implementation.
+    #
+    # This is library-agnostic because it detects node type and uses
+    # the appropriate serialization method.
+    class NodeSerializer
+      # Serialize a node to a string for display
+      # Handles both Nokogiri and Canon nodes
+      #
+      # @param node [Object] Node to serialize (Nokogiri, Canon, or nil)
+      # @return [String] Serialized string representation
+      def self.serialize(node)
+        return "" if node.nil?
+
+        # Handle Canon::Xml::Nodes::TextNode
+        if node.is_a?(Canon::Xml::Nodes::TextNode)
+          return node.value.to_s
+        end
+
+        # Handle Canon::Xml::Nodes::CommentNode
+        if node.is_a?(Canon::Xml::Nodes::CommentNode)
+          return "<!--#{node.value}-->"
+        end
+
+        # Handle Canon::Xml::Nodes::ElementNode
+        if node.is_a?(Canon::Xml::Nodes::ElementNode)
+          return serialize_element_node(node)
+        end
+
+        # Handle Canon::Xml::Nodes::ProcessingInstructionNode
+        if node.is_a?(Canon::Xml::Nodes::ProcessingInstructionNode)
+          return "<?#{node.target} #{node.data}?>"
+        end
+
+        # Handle Canon::Xml::Nodes::RootNode - serialize children
+        if node.is_a?(Canon::Xml::Nodes::RootNode)
+          return node.children.map { |child| serialize(child) }.join
+        end
+
+        # Handle Nokogiri nodes
+        if node.respond_to?(:to_html)
+          return node.to_html
+        end
+
+        if node.respond_to?(:to_xml)
+          return node.to_xml
+        end
+
+        # Fallback to string
+        node.to_s
+      end
+
+      # Serialize an ElementNode to HTML/XML string
+      #
+      # @param element [Canon::Xml::Nodes::ElementNode] Element to serialize
+      # @return [String] Serialized element
+      def self.serialize_element_node(element)
+        # Build opening tag with attributes
+        tag = "<#{element.name}"
+
+        # Add attributes
+        element.sorted_attribute_nodes.each do |attr|
+          tag += " #{attr.name}=\"#{attr.value}\""
+        end
+
+        # Check if element has children
+        if element.children.empty?
+          # Self-closing tag for empty elements
+          "#{tag}/>"
+        else
+          # Full element with children
+          content = element.children.map { |child| serialize(child) }.join
+          "#{tag}>#{content}</#{element.name}>"
+        end
+      end
+
+      # Extract attributes from a node as a normalized hash
+      # Handles both Nokogiri and Canon nodes
+      #
+      # @param node [Object] Node to extract attributes from
+      # @return [Hash] Normalized attributes hash
+      def self.extract_attributes(node)
+        return {} if node.nil?
+
+        # Handle Canon::Xml::Nodes::ElementNode
+        if node.is_a?(Canon::Xml::Nodes::ElementNode)
+          attrs = {}
+          node.attribute_nodes.each do |attr|
+            attrs[attr.name] = attr.value
+          end
+          return attrs
+        end
+
+        # Handle Nokogiri elements
+        if node.respond_to?(:attributes) && node.attributes.is_a?(Hash)
+          attrs = {}
+          node.attributes.each do |name, attr|
+            # Nokogiri attributes have different structure
+            value = if attr.respond_to?(:value)
+                      attr.value
+                    elsif attr.is_a?(String)
+                      attr
+                    else
+                      attr.to_s
+                    end
+            attrs[name] = value
+          end
+          return attrs
+        end
+
+        # Handle TreeNode attributes (already a hash)
+        if node.is_a?(Hash)
+          return node
+        end
+
+        {}
+      end
+
+      # Get element name from a node
+      # Handles both Nokogiri and Canon nodes
+      #
+      # @param node [Object] Node to get name from
+      # @return [String] Element name
+      def self.element_name(node)
+        return "" if node.nil?
+
+        # Handle Canon::Xml::Nodes::ElementNode
+        if node.is_a?(Canon::Xml::Nodes::ElementNode)
+          return node.name
+        end
+
+        # Handle Nokogiri elements
+        if node.respond_to?(:name)
+          return node.name.to_s
+        end
+
+        ""
+      end
+
+      # Get text content from a node
+      # Handles both Nokogiri and Canon nodes
+      #
+      # @param node [Object] Node to get text from
+      # @return [String] Text content
+      def self.text_content(node)
+        return "" if node.nil?
+
+        # Handle Canon::Xml::Nodes::TextNode
+        if node.is_a?(Canon::Xml::Nodes::TextNode)
+          return node.value.to_s
+        end
+
+        # Handle Nokogiri text nodes
+        if node.respond_to?(:text)
+          return node.text.to_s
+        end
+
+        if node.respond_to?(:content)
+          return node.content.to_s
+        end
+
+        ""
+      end
+
+      # Serialize attributes to string format
+      # Returns attributes in " name=\"value\"" format
+      #
+      # @param attributes [Hash] Attributes hash
+      # @return [String] Serialized attributes
+      def self.serialize_attributes(attributes)
+        return "" if attributes.nil? || attributes.empty?
+
+        attributes.sort.map do |name, value|
+          " #{name}=\"#{value}\""
+        end.join
+      end
+    end
+  end
+end

data/lib/canon/diff/path_builder.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Canon
+  module Diff
+    # Builds canonical XPath-like paths from TreeNodes or raw nodes
+    # Generates paths with ordinal indices to uniquely identify nodes
+    # regardless of the parsing library used (Nokogiri, Moxml, Canon, etc.)
+    #
+    # This is library-agnostic because it operates on different node types:
+    # - TreeNodes (from semantic diff adapters) - uses `label` attribute
+    # - Canon::Xml::Node (from DOM diff) - uses `name` attribute
+    # - Nokogiri nodes (from HTML DOM diff) - uses `name` method
+    #
+    # @example Build path for a TreeNode
+    #   path = PathBuilder.build(tree_node)
+    #   # => "/#document-fragment/div[0]/p[1]/span[2]"
+    #
+    # @example Build path for a Canon::Xml::Node
+    #   path = PathBuilder.build(canon_node)
+    #   # => "/#document/root[0]/body[0]/p[1]"
+    #
+    # @example Build path for a Nokogiri node
+    #   path = PathBuilder.build(nokogiri_node)
+    #   # => "/#document/div[0]/p[1]/span[2]"
+    class PathBuilder
+      # Build canonical path from a node (TreeNode, Canon::Xml::Node, or Nokogiri)
+      #
+      # @param node [Object] Node to build path for
+      # @param format [Symbol] Format (:document or :fragment)
+      # @return [String] Canonical path with ordinal indices
+      def self.build(node, format: :fragment)
+        return "" if node.nil?
+
+        # Build path segments from root to node
+        segments = build_segments(node)
+
+        # Join segments with /
+        "/#{segments.join('/')}"
+      end
+
+      # Build path segments (node names with ordinal indices)
+      # Traverses from node up to root, then reverses
+      # Handles both TreeNodes and raw nodes (Canon::Xml::Node, Nokogiri)
+      #
+      # @param tree_node [Object] Node to build segments for
+      # @return [Array<String>] Path segments from root to node
+      def self.build_segments(tree_node)
+        segments = []
+        current = tree_node
+        max_depth = 1000 # Prevent infinite loops
+        depth = 0
+
+        # Traverse up to root
+        while current && depth < max_depth
+          segments.unshift(segment_for_node(current))
+
+          # Move to parent if available
+          break unless current.respond_to?(:parent)
+
+          current = current.parent
+          depth += 1
+        end
+
+        segments
+      end
+
+      # Build path segment for a single node
+      # Returns label with ordinal index: "div[0]", "span[1]", etc.
+      # Handles both TreeNodes (with label) and raw nodes (with name)
+      #
+      # @param tree_node [Object] Node (TreeNode, Canon::Xml::Node, or Nokogiri)
+      # @return [String] Path segment with ordinal index
+      def self.segment_for_node(tree_node)
+        # Handle both TreeNodes (with label) and raw nodes (with name)
+        label = if tree_node.respond_to?(:label)
+                  tree_node.label
+                elsif tree_node.respond_to?(:name)
+                  tree_node.name
+                else
+                  "unknown"
+                end
+
+        # Get ordinal index (position among siblings with same label)
+        index = ordinal_index(tree_node)
+
+        "#{label}[#{index}]"
+      end
+
+      # Get ordinal index of node among its siblings with the same label
+      # Handles both TreeNodes (with Array children) and raw nodes (with NodeSet children)
+      #
+      # @param tree_node [Object] Node (TreeNode, Canon::Xml::Node, or Nokogiri)
+      # @return [Integer] Zero-based ordinal index
+      def self.ordinal_index(tree_node)
+        # Defensive: return 0 if no parent or doesn't respond to parent
+        return 0 unless tree_node.respond_to?(:parent)
+        return 0 unless tree_node.parent
+
+        # Check if parent has children
+        return 0 unless tree_node.parent.respond_to?(:children)
+
+        siblings = tree_node.parent.children
+        return 0 unless siblings
+
+        # Convert to array if it's a NodeSet (Nokogiri) or similar
+        siblings = siblings.to_a unless siblings.is_a?(Array)
+
+        # Get the label/name for comparison
+        my_label = if tree_node.respond_to?(:label)
+                     tree_node.label
+                   elsif tree_node.respond_to?(:name)
+                     tree_node.name
+                   end
+
+        return 0 unless my_label
+
+        # Count siblings with same label that appear before this node
+        same_label_siblings = siblings.select do |s|
+          sibling_label = if s.respond_to?(:label)
+                            s.label
+                          elsif s.respond_to?(:name)
+                            s.name
+                          end
+          sibling_label == my_label
+        end
+
+        # Find position in same-label siblings
+        same_label_siblings.index(tree_node) || 0
+      end
+
+      # Build human-readable path description
+      # Alternative format that may be more useful for error messages
+      # Handles both TreeNodes and raw nodes
+      #
+      # @param tree_node [Object] Node (TreeNode, Canon::Xml::Node, or Nokogiri)
+      # @return [String] Human-readable path
+      def self.human_path(tree_node)
+        segments = build_segments(tree_node)
+        segments.join(" → ")
+      end
+    end
+  end
+end

data/lib/canon/diff_formatter/by_line/base_formatter.rb

@@ -456,6 +456,257 @@ module Canon
           # Default to 10,000 if config not available
           config&.xml&.diff&.max_diff_lines || 10_000
         end
+
+        # Build set of children of matched parents
+        #
+        # @param matches [Array<Match>] Element matches
+        # @return [Set] Set of child elements
+        def build_children_set(matches)
+          require "set"
+
+          children = Set.new
+
+          matches.each do |match|
+            next unless match.status == :matched
+
+            [match.elem1, match.elem2].compact.each do |elem|
+              next unless elem.respond_to?(:children)
+
+              elem.children.each do |child|
+                children.add(child) if child.respond_to?(:name)
+              end
+            end
+          end
+
+          children
+        end
+
+        # Build set of individual elements that have semantic diffs
+        #
+        # @return [Set] Set of elements with semantic diffs
+        def build_elements_with_semantic_diffs_set
+          require "set"
+
+          elements = Set.new
+
+          return elements if @differences.nil? || @differences.empty?
+
+          @differences.each do |diff|
+            next unless diff.is_a?(Canon::Diff::DiffNode)
+
+            # Add both nodes if they exist
+            elements.add(diff.node1) if diff.node1
+            elements.add(diff.node2) if diff.node2
+          end
+
+          elements
+        end
+
+        # Check if an element or its children have semantic diffs
+        #
+        # @param element [Object] Element to check
+        # @param elements_with_semantic_diffs [Set] Set of elements with diffs
+        # @return [Boolean] True if element or descendants have semantic diffs
+        def has_semantic_diff_in_subtree?(element, elements_with_semantic_diffs)
+          # Check the element itself
+          return true if elements_with_semantic_diffs.include?(element)
+
+          # Check all descendants
+          if element.respond_to?(:children)
+            element.children.any? do |child|
+              has_semantic_diff_in_subtree?(child, elements_with_semantic_diffs)
+            end
+          else
+            false
+          end
+        end
+
+        # Check if diff display should be skipped
+        # Returns true when:
+        # 1. show_diffs is :normative AND there are no normative differences
+        # 2. show_diffs is :informative AND there are no informative differences
+        #
+        # @return [Boolean] True if diff display should be skipped
+        def should_skip_diff_display?
+          return false if @differences.nil? || @differences.empty?
+
+          case @show_diffs
+          when :normative
+            # Skip if no normative diffs
+            @differences.none? do |diff|
+              diff.is_a?(Canon::Diff::DiffNode) && diff.normative?
+            end
+          when :informative
+            # Skip if no informative diffs
+            @differences.none? do |diff|
+              diff.is_a?(Canon::Diff::DiffNode) && diff.informative?
+            end
+          else
+            # :all or other - never skip
+            false
+          end
+        end
+
+        # Group diff sections by proximity
+        #
+        # @param sections [Array<Hash>] Diff sections
+        # @param grouping_lines [Integer] Maximum gap to group
+        # @return [Array<Array>] Grouped sections
+        def group_diff_sections(sections, grouping_lines)
+          return [] if sections.empty?
+
+          groups = []
+          current_group = [sections[0]]
+
+          sections[1..].each do |section|
+            last_section = current_group.last
+
+            # Calculate gap
+            gap1 = if last_section[:end_line1] && section[:start_line1]
+                     section[:start_line1] - last_section[:end_line1] - 1
+                   else
+                     Float::INFINITY
+                   end
+
+            gap2 = if last_section[:end_line2] && section[:start_line2]
+                     section[:start_line2] - last_section[:end_line2] - 1
+                   else
+                     Float::INFINITY
+                   end
+
+            max_gap = [gap1, gap2].max
+
+            if max_gap <= grouping_lines
+              current_group << section
+            else
+              groups << current_group
+              current_group = [section]
+            end
+          end
+
+          groups << current_group unless current_group.empty?
+          groups
+        end
+
+        # Format groups of diffs
+        #
+        # @param groups [Array<Array>] Grouped diff sections
+        # @return [String] Formatted groups
+        def format_diff_groups(groups)
+          output = []
+
+          groups.each_with_index do |group, group_idx|
+            output << "" if group_idx.positive?
+
+            if group.length > 1
+              output << colorize("Context block has #{group.length} diffs",
+                                 :yellow, :bold)
+              output << ""
+              group.each do |section|
+                output << section[:formatted] if section[:formatted]
+              end
+            elsif group[0][:formatted]
+              output << group[0][:formatted]
+            end
+          end
+
+          output.join("\n")
+        end
+
+        # Format matched element with metadata
+        # Subclasses may override to customize behavior
+        #
+        # @param match [Match] Element match
+        # @param map1 [Hash] Line range map for doc1
+        # @param map2 [Hash] Line range map for doc2
+        # @param lines1 [Array<String>] Lines from doc1
+        # @param lines2 [Array<String>] Lines from doc2
+        # @return [Hash, nil] Metadata hash or nil
+        def format_matched_element_with_metadata(match, map1, map2, lines1,
+lines2)
+          range1 = map1[match.elem1]
+          range2 = map2[match.elem2]
+          return nil unless range1 && range2
+
+          # Subclasses must implement format_matched_element
+          formatted = format_matched_element(match, map1, map2, lines1, lines2)
+          return nil unless formatted
+
+          {
+            formatted: formatted,
+            start_line1: range1.start_line,
+            end_line1: range1.end_line,
+            start_line2: range2.start_line,
+            end_line2: range2.end_line,
+            path: match.path.join("/"),
+          }
+        end
+
+        # Format deleted element with metadata
+        # Subclasses may override to customize behavior
+        #
+        # @param match [Match] Element match
+        # @param map1 [Hash] Line range map for doc1
+        # @param lines1 [Array<String>] Lines from doc1
+        # @return [Hash, nil] Metadata hash or nil
+        def format_deleted_element_with_metadata(match, map1, lines1)
+          range1 = map1[match.elem1]
+          return nil unless range1
+
+          # Subclasses must implement format_deleted_element
+          formatted = format_deleted_element(match, map1, lines1)
+          return nil unless formatted
+
+          {
+            formatted: formatted,
+            start_line1: range1.start_line,
+            end_line1: range1.end_line,
+            start_line2: nil,
+            end_line2: nil,
+            path: match.path.join("/"),
+          }
+        end
+
+        # Format inserted element with metadata
+        # Subclasses may override to customize behavior
+        #
+        # @param match [Match] Element match
+        # @param map2 [Hash] Line range map for doc2
+        # @param lines2 [Array<String>] Lines from doc2
+        # @return [Hash, nil] Metadata hash or nil
+        def format_inserted_element_with_metadata(match, map2, lines2)
+          range2 = map2[match.elem2]
+          return nil unless range2
+
+          # Subclasses must implement format_inserted_element
+          formatted = format_inserted_element(match, map2, lines2)
+          return nil unless formatted
+
+          {
+            formatted: formatted,
+            start_line1: nil,
+            end_line1: nil,
+            start_line2: range2.start_line,
+            end_line2: range2.end_line,
+            path: match.path.join("/"),
+          }
+        end
+
+        # Subclasses must implement these element formatting methods
+        def format_matched_element(_match, _map1, _map2, _lines1, _lines2)
+          raise NotImplementedError,
+                "Subclasses must implement format_matched_element"
+        end
+
+        def format_deleted_element(_match, _map1, _lines1)
+          raise NotImplementedError,
+                "Subclasses must implement format_deleted_element"
+        end
+
+        def format_inserted_element(_match, _map2, _lines2)
+          raise NotImplementedError,
+                "Subclasses must implement format_inserted_element"
+        end
       end
     end
   end