Class: Canon::Comparison::DiffNodeBuilder

Inherits:
Object
  • Object
show all
Defined in:
lib/canon/comparison/xml_comparator/diff_node_builder.rb

Overview

Builder for creating enriched DiffNode objects Handles path building, serialization, and attribute extraction

Class Method Summary collapse

Class Method Details

.build(node1:, node2:, diff1:, diff2:, dimension:, **_opts) ⇒ DiffNode?

Build an enriched DiffNode

Parameters:

  • node1 (Object, nil) —

    First node

  • node2 (Object, nil) —

    Second node

  • diff1 (String) —

    Difference type for node1

  • diff2 (String) —

    Difference type for node2

  • dimension (Symbol) —

    The match dimension causing this difference

Returns:

  • (DiffNode, nil) —

    Enriched DiffNode or nil if dimension is nil



22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
 
# File 'lib/canon/comparison/xml_comparator/diff_node_builder.rb', line 22

def self.build(node1:, node2:, diff1:, diff2:, dimension:, **_opts)
  # Validate dimension is required
  if dimension.nil?
    raise ArgumentError,
          "dimension required for DiffNode"
  end

  # Build informative reason message
  reason = build_reason(node1, node2, diff1, diff2, dimension)

  # Enrich with path, serialized content, and attributes for Stage 4 rendering
  metadata = enrich_metadata(node1, node2)

  Canon::Diff::DiffNode.new(
    node1: node1,
    node2: node2,
    dimension: dimension,
    reason: reason,
    **metadata,
  )
end

.build_attribute_difference_reason(attrs1, attrs2) ⇒ String

Build a clear reason message for attribute presence differences Shows which attributes are only in node1, only in node2, or different values

Parameters:

  • attrs1 (Hash, nil) —

    First node’s attributes

  • attrs2 (Hash, nil) —

    Second node’s attributes

Returns:

  • (String) —

    Clear explanation of the attribute difference



156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
 
# File 'lib/canon/comparison/xml_comparator/diff_node_builder.rb', line 156

def self.build_attribute_difference_reason(attrs1, attrs2)
  return "#{attrs1&.keys&.size || 0} vs #{attrs2&.keys&.size || 0} attributes" unless attrs1 && attrs2

  keys1 = attrs1.keys.to_set
  keys2 = attrs2.keys.to_set

  only_in_1 = keys1 - keys2
  only_in_2 = keys2 - keys1
  common = keys1 & keys2

  # Check if values differ for common keys
  different_values = common.reject { |k| attrs1[k] == attrs2[k] }

  parts = []
  parts << "only in first: #{only_in_1.to_a.sort.join(', ')}" if only_in_1.any?
  parts << "only in second: #{only_in_2.to_a.sort.join(', ')}" if only_in_2.any?
  parts << "different values: #{different_values.sort.join(', ')}" if different_values.any?

  if parts.empty?
    "#{keys1.size} vs #{keys2.size} attributes (same names)"
  else
    parts.join("; ")
  end
end

.build_path(node) ⇒ String?

Build canonical path for a node

Parameters:

  • node (Object) —

    Node to build path for

Returns:

  • (String, nil) —

    Canonical path with ordinal indices



124
125
126
127
128
 
# File 'lib/canon/comparison/xml_comparator/diff_node_builder.rb', line 124

def self.build_path(node)
  return nil if node.nil?

  Canon::Diff::PathBuilder.build(node, format: :document)
end

.build_reason(node1, node2, diff1, diff2, dimension) ⇒ String

Build a human-readable reason for a difference

Parameters:

  • node1 (Object) —

    First node

  • node2 (Object) —

    Second node

  • diff1 (String) —

    Difference type for node1

  • diff2 (String) —

    Difference type for node2

  • dimension (Symbol) —

    The dimension of the difference

Returns:

  • (String) —

    Human-readable reason



52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
 
# File 'lib/canon/comparison/xml_comparator/diff_node_builder.rb', line 52

def self.build_reason(node1, node2, diff1, diff2, dimension)
  # For deleted/inserted nodes, include namespace information if available
  if dimension == :text_content && (node1.nil? || node2.nil?)
    node = node1 || node2
    if node.is_a?(Canon::Xml::Node) || node.is_a?(Nokogiri::XML::Node)
      ns = node.namespace_uri
      ns_info = if ns.nil? || ns.empty?
                  ""
                else
                  " (namespace: #{ns})"
                end
      label = Canon::Comparison.code_pair_label(diff1, diff2)
      return "element '#{node.name}'#{ns_info}: #{label}"
    end
  end

  # For attribute presence differences, show what attributes differ
  if dimension == :attribute_presence
    attrs1 = extract_attributes(node1)
    attrs2 = extract_attributes(node2)
    return build_attribute_difference_reason(attrs1, attrs2)
  end

  # For text content differences, show the actual text (truncated if needed)
  if dimension == :text_content
    text1 = extract_text_content(node1)
    text2 = extract_text_content(node2)
    return build_text_difference_reason(text1, text2)
  end

  # For attribute order differences, show the actual attribute names
  if dimension == :attribute_order
    attrs1 = extract_attributes(node1)&.keys || []
    attrs2 = extract_attributes(node2)&.keys || []
    return "Attribute order changed: [#{attrs1.join(', ')}] → [#{attrs2.join(', ')}]"
  end

  # Default reason
  if diff1 == Canon::Comparison::MISSING_NODE && diff2 == Canon::Comparison::MISSING_NODE
    "element structure mismatch (children differ)"
  elsif dimension == :element_structure &&
      diff1 == Canon::Comparison::UNEQUAL_ELEMENTS &&
      diff2 == Canon::Comparison::UNEQUAL_ELEMENTS &&
      (node1.is_a?(Canon::Xml::Node) || node1.is_a?(Nokogiri::XML::Node)) &&
      (node2.is_a?(Canon::Xml::Node) || node2.is_a?(Nokogiri::XML::Node)) &&
      node1.name && node2.name && node1.name != node2.name
    "different element name (<#{node1.name}> vs <#{node2.name}>)"
  else
    Canon::Comparison.code_pair_label(diff1, diff2)
  end
end

.build_text_difference_reason(text1, text2) ⇒ String

Build a clear reason message for text content differences Shows the actual text content (truncated if too long)

Parameters:

  • text1 (String, nil) —

    First text content

  • text2 (String, nil) —

    Second text content

Returns:

  • (String) —

    Clear explanation of the text difference



210
211
212
213
214
215
216
217
218
 
# File 'lib/canon/comparison/xml_comparator/diff_node_builder.rb', line 210

def self.build_text_difference_reason(text1, text2)
  # Handle nil cases
  return "missing vs '#{truncate(text2)}'" if text1.nil? && text2
  return "'#{truncate(text1)}' vs missing" if text1 && text2.nil?
  return "both missing" if text1.nil? && text2.nil?

  # Both have content - show truncated versions
  "'#{truncate(text1)}' vs '#{truncate(text2)}'"
end

.enrich_metadata(node1, node2) ⇒ Hash

Enrich DiffNode with canonical path, serialized content, and attributes This extracts presentation-ready metadata from nodes for Stage 4 rendering

Parameters:

  • node1 (Object, nil) —

    First node

  • node2 (Object, nil) —

    Second node

Returns:

  • (Hash) —

    Enriched metadata hash



110
111
112
113
114
115
116
117
118
 
# File 'lib/canon/comparison/xml_comparator/diff_node_builder.rb', line 110

def self.enrich_metadata(node1, node2)
  {
    path: build_path(node1 || node2),
    serialized_before: serialize(node1),
    serialized_after: serialize(node2),
    attributes_before: extract_attributes(node1),
    attributes_after: extract_attributes(node2),
  }
end

.extract_attributes(node) ⇒ Hash?

Extract attributes from a node as a normalized hash

Parameters:

  • node (Object, nil) —

    Node to extract attributes from

Returns:

  • (Hash, nil) —

    Normalized attributes hash



144
145
146
147
148
 
# File 'lib/canon/comparison/xml_comparator/diff_node_builder.rb', line 144

def self.extract_attributes(node)
  return nil if node.nil?

  Canon::Diff::NodeSerializer.extract_attributes(node)
end

.extract_text_content(node) ⇒ String?

Extract text content from a node

Parameters:

  • node (Object, nil) —

    Node to extract text from

Returns:

  • (String, nil) —

    Text content or nil



185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
 
# File 'lib/canon/comparison/xml_comparator/diff_node_builder.rb', line 185

def self.extract_text_content(node)
  return nil if node.nil?

  case node
  when Canon::Xml::Nodes::TextNode
    node.value
  when Canon::Xml::Node
    node.text_content
  when Nokogiri::XML::Node
    node.content.to_s
  when String
    node
  else
    node.to_s
  end
rescue StandardError
  nil
end

.serialize(node) ⇒ String?

Serialize a node to string for display

Parameters:

  • node (Object, nil) —

    Node to serialize

Returns:

  • (String, nil) —

    Serialized content



134
135
136
137
138
 
# File 'lib/canon/comparison/xml_comparator/diff_node_builder.rb', line 134

def self.serialize(node)
  return nil if node.nil?

  Canon::Diff::NodeSerializer.serialize(node)
end

.truncate(text, max_length = 40) ⇒ String

Truncate text for display in reason messages

Parameters:

  • text (String) —

    Text to truncate

  • max_length (Integer) (defaults to: 40) —

    Maximum length

Returns:

  • (String) —

    Truncated text



225
226
227
228
229
230
231
232
 
# File 'lib/canon/comparison/xml_comparator/diff_node_builder.rb', line 225

def self.truncate(text, max_length = 40)
  return "" if text.nil?

  text = text.to_s
  return text if text.length <= max_length

  "#{text[0...max_length]}..."
end