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



169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/canon/comparison/xml_comparator/diff_node_builder.rb', line 169

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_attribute_values_reason(node1, node2) ⇒ String

Build a reason message for attribute value differences Shows each changed attribute with its before/after values

Parameters:

  • node1 (Object, nil) —

    First node

  • node2 (Object, nil) —

    Second node

Returns:

  • (String) —

    Clear explanation of the attribute value differences



200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
 
# File 'lib/canon/comparison/xml_comparator/diff_node_builder.rb', line 200

def self.build_attribute_values_reason(node1, node2)
  attrs1 = extract_attributes(node1) || {}
  attrs2 = extract_attributes(node2) || {}

  differing = (attrs1.keys | attrs2.keys).sort.reject do |k|
    attrs1[k.to_s] == attrs2[k.to_s]
  end

  changed_parts = differing.map do |k|
    "Changed: #{k}=\"#{attrs1[k.to_s]}\" → \"#{attrs2[k.to_s]}\""
  end

  if changed_parts.empty?
    "attributes differ"
  else
    "Attributes differ (#{changed_parts.join('; ')})"
  end
end

.build_comment_difference_reason(node1, node2) ⇒ Object

Build a Reason line for a :comments diff. Returns nil when neither side carries a comment (caller falls back to default).



262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
 
# File 'lib/canon/comparison/xml_comparator/diff_node_builder.rb', line 262

def self.build_comment_difference_reason(node1, node2)
  cm1 = node1 && Canon::Comparison::NodeInspector.comment_node?(node1)
  cm2 = node2 && Canon::Comparison::NodeInspector.comment_node?(node2)

  return nil unless cm1 || cm2

  if cm1 && !cm2
    "Comment present on EXPECTED only: " \
      "<!--#{truncate(comment_text(node1))}-->"
  elsif cm2 && !cm1
    "Comment present on ACTUAL only: " \
      "<!--#{truncate(comment_text(node2))}-->"
  else
    t1 = truncate(comment_text(node1))
    t2 = truncate(comment_text(node2))
    "Comment text differs: <!--#{t1}--> vs <!--#{t2}-->"
  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



137
138
139
140
141
 
# File 'lib/canon/comparison/xml_comparator/diff_node_builder.rb', line 137

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
103
104
105
106
107
108
109
110
111
112
113
114
115
 
# 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) || Canon::XmlParsing.xml_node?(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 attribute value differences, show which attributes changed
  if dimension == :attribute_values
    return build_attribute_values_reason(node1, node2)
  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

  # For asymmetric comment nodes (#144), name the side that carries
  # the comment and surface the comment text rather than reusing
  # the generic "element structure mismatch" wording.
  if dimension == :comments
    comment_reason = build_comment_difference_reason(node1, node2)
    return comment_reason if comment_reason
  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) || Canon::XmlParsing.xml_node?(node1)) &&
      (node2.is_a?(Canon::Xml::Node) || Canon::XmlParsing.xml_node?(node2)) &&
      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



250
251
252
253
254
255
256
257
258
 
# File 'lib/canon/comparison/xml_comparator/diff_node_builder.rb', line 250

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

.comment_text(node) ⇒ Object 



281
282
283
 
# File 'lib/canon/comparison/xml_comparator/diff_node_builder.rb', line 281

def self.comment_text(node)
  Canon::Comparison::NodeInspector.text_content(node).to_s
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



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

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



157
158
159
160
161
 
# File 'lib/canon/comparison/xml_comparator/diff_node_builder.rb', line 157

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



223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
 
# File 'lib/canon/comparison/xml_comparator/diff_node_builder.rb', line 223

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
  else
    if Canon::XmlBackend.nokogiri? && node.is_a?(Nokogiri::XML::Node)
      node.content.to_s
    elsif Canon::XmlParsing.xml_node?(node)
      Canon::XmlParsing.text_content(node)
    else
      node.to_s
    end
  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



147
148
149
150
151
 
# File 'lib/canon/comparison/xml_comparator/diff_node_builder.rb', line 147

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



290
291
292
293
294
295
296
297
 
# File 'lib/canon/comparison/xml_comparator/diff_node_builder.rb', line 290

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