canon 0.1.8 → 0.1.10

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d94be550a90d23eb695f46579b13fa327434993b89a995b3c95ba658a143fb9
-  data.tar.gz: 2ac083712aa9d0153aa2e0898186a7cbf669e775368378c9de8de6c42c52a257
+  metadata.gz: 4f9d0e9c0c1bc9f213d837f480d3d9a26ce11505691ff48b63907e7a4abd530e
+  data.tar.gz: aa591a7682cede5f23a8dcb8b8eb8f7616d849bc5f9cad1aa2038463ee9c52b0
 SHA512:
-  metadata.gz: 45b4502c83bfd367c5933e66f610de529b87f27d5cfef18c0fe808bcbc91e20c1c3c0e32ba36ed6163a70de37c5ae3a1023c67fed586491e7eea5f7c621e2769
-  data.tar.gz: 3713856d8dfdfb4164cfd9e8bdcd4dcbdce7b303619d703b7defe58d09c5468eb3acc5f32435f3184d35f20b3a6f7470c2960d8e5cef21ba720ebd7dc44ccfbf
+  metadata.gz: 6c0af5461fff1d1cd1347ba57681bc671cda71d55d62efd328ac9424ef10b8329ec877ccf43f9ff78e83a54ca03df1026e160b259396caac7bd2704227ef01b1
+  data.tar.gz: 8803713442225ae16c0c6c9c03c9cff55dd27dc6b96f5254ee5f814a29b7ad7b5ef6eafd0cd6a58d17f070a2609154476215147d595a01a69586ca7de8608a7f

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-01-17 14:46:16 UTC using RuboCop version 1.81.7.
+# on 2026-01-21 01:26:28 UTC using RuboCop version 1.81.7.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
@@ -12,27 +12,51 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'canon.gemspec'
 
-# Offense count: 1
+# Offense count: 16
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, IndentationWidth.
 # SupportedStyles: with_first_argument, with_fixed_indentation
 Layout/ArgumentAlignment:
   Exclude:
-    - 'lib/canon/comparison.rb'
+    - 'lib/canon/comparison/xml_comparator.rb'
+    - 'lib/canon/diff/xml_serialization_formatter.rb'
+    - 'spec/canon/diff/xml_serialization_formatter_spec.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
+# SupportedHashRocketStyles: key, separator, table
+# SupportedColonStyles: key, separator, table
+# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
+Layout/HashAlignment:
+  Exclude:
+    - 'test_verify_equivalent.rb'
 
-# Offense count: 697
+# Offense count: 709
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, IgnoreCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
-# Offense count: 1
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: aligned, indented
+Layout/MultilineOperationIndentation:
+  Exclude:
+    - 'lib/canon/diff/diff_classifier.rb'
+    - 'lib/canon/diff/xml_serialization_formatter.rb'
+
+# Offense count: 17
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowInHeredoc.
 Layout/TrailingWhitespace:
   Exclude:
-    - 'lib/canon/comparison.rb'
+    - 'lib/canon/comparison/xml_comparator.rb'
+    - 'lib/canon/diff/xml_serialization_formatter.rb'
+    - 'spec/canon/diff/xml_serialization_formatter_spec.rb'
+    - 'test_verify_equivalent.rb'
 
 # Offense count: 48
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
@@ -74,38 +98,38 @@ Lint/UnusedMethodArgument:
     - 'lib/canon/diff_formatter/by_line/xml_formatter.rb'
     - 'lib/canon/diff_formatter/by_object/base_formatter.rb'
 
-# Offense count: 225
+# Offense count: 207
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
 
-# Offense count: 27
+# Offense count: 20
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
   Max: 84
 
-# Offense count: 178
+# Offense count: 176
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 376
+# Offense count: 360
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 110
 
-# Offense count: 39
+# Offense count: 45
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Max: 9
 
-# Offense count: 143
+# Offense count: 142
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
 
-# Offense count: 29
+# Offense count: 28
 # Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
 # AllowedNames: as, at, by, cc, db, id, if, in, io, ip, of, on, os, pp, to
 Naming/MethodParameterName:
@@ -113,7 +137,6 @@ Naming/MethodParameterName:
     - 'lib/canon/comparison/xml_comparator.rb'
     - 'lib/canon/comparison/xml_comparator/attribute_comparator.rb'
     - 'lib/canon/xml/namespace_handler.rb'
-    - 'scripts/investigate_all_false_positives.rb'
 
 # Offense count: 1
 # Configuration parameters: NamePrefix, ForbiddenPrefixes, AllowedMethods, MethodDefinitionMacros, UseSorbetSigs.
@@ -125,13 +148,15 @@ Naming/PredicatePrefix:
   Exclude:
     - 'lib/canon/comparison/html_comparator.rb'
 
-# Offense count: 2
+# Offense count: 6
 # Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers, AllowedPatterns.
 # SupportedStyles: snake_case, normalcase, non_integer
 # AllowedIdentifiers: TLS1_1, TLS1_2, capture3, iso8601, rfc1123_date, rfc822, rfc2822, rfc3339, x86_64
 Naming/VariableNumber:
   Exclude:
     - 'lib/canon/comparison/json_comparator.rb'
+    - 'lib/canon/comparison/markup_comparator.rb'
+    - 'lib/canon/comparison/xml_comparator/diff_node_builder.rb'
 
 # Offense count: 2
 # Configuration parameters: MinSize.
@@ -140,7 +165,7 @@ Performance/CollectionLiteralInLoop:
     - 'lib/canon/comparison/html_comparator.rb'
     - 'lib/canon/xml/xml_base_handler.rb'
 
-# Offense count: 62
+# Offense count: 64
 # Configuration parameters: Prefixes, AllowedPatterns.
 # Prefixes: when, with, without
 RSpec/ContextWording:
@@ -157,7 +182,7 @@ RSpec/DescribeMethod:
     - 'spec/canon/comparison/multiple_differences_spec.rb'
     - 'spec/canon/diff_formatter/character_map_customization_spec.rb'
 
-# Offense count: 624
+# Offense count: 675
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 67
@@ -171,7 +196,7 @@ RSpec/ExpectActual:
     - 'spec/canon/rspec_matchers_spec.rb'
     - 'spec/canon/string_matcher_spec.rb'
 
-# Offense count: 171
+# Offense count: 175
 # Configuration parameters: Max, AllowedIdentifiers, AllowedPatterns.
 RSpec/IndexedLet:
   Exclude:
@@ -208,11 +233,11 @@ RSpec/MultipleDescribes:
   Exclude:
     - 'spec/canon/comparison/match_options_spec.rb'
 
-# Offense count: 515
+# Offense count: 518
 RSpec/MultipleExpectations:
   Max: 15
 
-# Offense count: 66
+# Offense count: 69
 # Configuration parameters: AllowSubject.
 RSpec/MultipleMemoizedHelpers:
   Max: 13
@@ -226,7 +251,7 @@ RSpec/NamedSubject:
     - 'spec/canon/pretty_printer/json_spec.rb'
     - 'spec/canon/pretty_printer/xml_spec.rb'
 
-# Offense count: 30
+# Offense count: 37
 # Configuration parameters: AllowedGroups.
 RSpec/NestedGroups:
   Max: 4
@@ -254,14 +279,24 @@ RSpec/SpecFilePathFormat:
     - 'spec/canon/yaml/formatter_spec.rb'
     - 'spec/xml_c14n_spec.rb'
 
-# Offense count: 94
+# Offense count: 120
 # Configuration parameters: IgnoreNameless, IgnoreSymbolicNames.
 RSpec/VerifiedDoubles:
   Exclude:
+    - 'spec/canon/comparison/whitespace_sensitivity_spec.rb'
     - 'spec/canon/diff/diff_classifier_spec.rb'
     - 'spec/canon/diff/path_builder_spec.rb'
+    - 'spec/canon/diff/xml_serialization_formatter_spec.rb'
     - 'spec/canon/tree_diff/operation_converter_spec.rb'
 
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, AllowComments.
+# SupportedStyles: empty, nil, both
+Style/EmptyElse:
+  Exclude:
+    - 'lib/canon/comparison/xml_comparator.rb'
+
 # Offense count: 3
 # Configuration parameters: MinBranchesCount.
 Style/HashLikeCase:
@@ -276,9 +311,35 @@ Style/IdenticalConditionalBranches:
     - 'lib/canon/diff_formatter/by_object/base_formatter.rb'
     - 'lib/canon/diff_formatter/legend.rb'
 
+# Offense count: 2
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: InverseMethods, InverseBlocks.
+Style/InverseMethods:
+  Exclude:
+    - 'lib/canon/comparison/markup_comparator.rb'
+    - 'lib/canon/comparison/xml_comparator/diff_node_builder.rb'
+
 # Offense count: 1
 # Configuration parameters: AllowedMethods.
 # AllowedMethods: respond_to_missing?
 Style/OptionalBooleanParameter:
   Exclude:
     - 'lib/canon/diff_formatter/debug_output.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
+# SupportedStyles: single_quotes, double_quotes
+Style/StringLiterals:
+  Exclude:
+    - 'lib/canon/comparison/markup_comparator.rb'
+    - 'lib/canon/comparison/xml_comparator/diff_node_builder.rb'
+    - 'test_verify_equivalent.rb'
+
+# Offense count: 12
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleForMultiline.
+# SupportedStylesForMultiline: comma, consistent_comma, diff_comma, no_comma
+Style/TrailingCommaInArguments:
+  Exclude:
+    - 'spec/canon/diff/xml_serialization_formatter_spec.rb'

data/docs/Gemfile

@@ -6,4 +6,5 @@ gem "just-the-docs"
 
 group :jekyll_plugins do
   gem "jekyll-seo-tag"
+  gem "jekyll-sitemap"
 end

data/docs/_config.yml

@@ -12,8 +12,13 @@ repository: lutaml/canon
 
 # Theme
 theme: just-the-docs
+remote_theme: just-the-docs/just-the-docs@v0.7.0
 color_scheme: light
 
+# Logo (uncomment if you have a logo)
+# logo: "/assets/images/logo.svg"
+# favicon_ico: "/assets/images/favicon.ico"
+
 # AsciiDoc support
 asciidoc: {}
 asciidoctor:
@@ -63,10 +68,36 @@ heading_anchors: true
 # Footer
 footer_content: 'Copyright &copy; 2025 Ribose. Distributed under the <a href="https://github.com/lutaml/canon/blob/main/LICENSE.txt">BSD 2-Clause License</a>.'
 
+# Footer last edit timestamp
+last_edit_timestamp: true
+last_edit_time_format: "%b %e %Y at %I:%M %p"
+
+# Enable code copy button
+enable_copy_code_button: true
+
+# Callouts
+callouts_level: quiet
+callouts:
+  highlight:
+    color: yellow
+  important:
+    title: Important
+    color: blue
+  new:
+    title: New
+    color: green
+  note:
+    title: Note
+    color: purple
+  warning:
+    title: Warning
+    color: red
+
 # Plugins
 plugins:
   - jekyll-asciidoc
   - jekyll-seo-tag
+  - jekyll-sitemap
 
 # Markdown settings (for any markdown files)
 markdown: kramdown
@@ -75,6 +106,60 @@ kramdown:
   hard_wrap: false
   syntax_highlighter: rouge
 
+# Collections for organizing content
+collections:
+  # Core documentation pages (getting-started, interfaces, etc.)
+  pages:
+    permalink: "/:path/"
+    output: true
+
+  # Feature documentation
+  features:
+    permalink: "/:collection/:path/"
+    output: true
+
+  # Understanding/internal documentation
+  understanding:
+    permalink: "/:collection/:path/"
+    output: true
+
+  # Advanced topics
+  advanced:
+    permalink: "/:collection/:path/"
+    output: true
+
+  # Guides (task-oriented tutorials)
+  guides:
+    permalink: "/:collection/:path/"
+    output: true
+
+  # Reference documentation
+  reference:
+    permalink: "/:collection/:path/"
+    output: true
+
+# Just the Docs collection configuration
+just_the_docs:
+  collections:
+    pages:
+      name: Pages
+      nav_fold: false
+    features:
+      name: Features
+      nav_fold: true
+    understanding:
+      name: Understanding
+      nav_fold: true
+    advanced:
+      name: Advanced
+      nav_fold: true
+    guides:
+      name: Guides
+      nav_fold: true
+    reference:
+      name: Reference
+      nav_fold: true
+
 # Defaults
 defaults:
   - scope:
@@ -83,6 +168,10 @@ defaults:
     values:
       layout: default
 
+# Include additional files
+include:
+  - "*.adoc"
+
 # Exclude from processing
 exclude:
   - Gemfile
@@ -97,4 +186,4 @@ exclude:
   - .git
   - .gitignore
 
-permalink: pretty
+permalink: pretty

data/docs/advanced/diff-classification.adoc

@@ -80,14 +80,20 @@ Classification depends on `attribute_order` setting:
 │                                                                   │
 │ DiffClassifier examines each DiffNode:                           │
 │                                                                   │
-│ For each dimension:                                               │
-│   behavior = match_options.behavior_for(dimension)                │
+│ 1. Serialization-level formatting (XmlSerializationFormatter)    │
+│    → XML syntax differences: <tag/> vs <tag></tag>               │
+│    → ALWAYS formatting-only (non-normative)                      │
 │                                                                   │
-│   if behavior == :ignore                                          │
-│     → INFORMATIVE (difference doesn't matter)                     │
-│   else  # :strict or :normalize                                   │
-│     → NORMATIVE (difference matters)                              │
+│ 2. Content-level formatting (text_content: :normalize)           │
+│    → Whitespace differences in content                           │
+│    → Formatting-only when normalized content matches             │
 │                                                                   │
+│ 3. CompareProfile policy (normative vs informative)              │
+│    → behavior == :ignore → INFORMATIVE                           │
+│    → behavior == :strict → NORMATIVE                             │
+│    → behavior == :normalize → Check content normalization        │
+│                                                                   │
+│ Sets diff_node.formatting = true/false                           │
 │ Sets diff_node.normative = true/false                            │
 └───────────────────────────────────┬───────────────────────────────┘
                                     ↓
@@ -102,6 +108,27 @@ Classification depends on `attribute_order` setting:
 └──────────────────────────────────────────────────────────────────┘
 ----
 
+=== Three-Level Classification System
+
+Canon distinguishes between **three distinct kinds of differences**:
+
+| Kind | `formatting:` | `normative:` | Meaning | Examples |
+|------|---------------|--------------|---------|----------|
+| **Serialization formatting** | `true` | `false` | XML syntax differences | `<tag/>` vs `<tag></tag>` |
+| **Content formatting** | `true` | `false` | Whitespace in content | `Hello  world` vs `Hello world` |
+| **Informative** | `false` | `false` | Tracked but doesn't affect equivalence | Attribute order (when `:ignore`) |
+| **Normative** | `false` | `true` | Affects equivalence | Different words, missing elements |
+
+**Key distinction**:
+
+* **Serialization-level formatting**: XML syntax differences that are ALWAYS non-normative regardless of match options, because they represent different valid serializations of the same semantic content. Detected by `XmlSerializationFormatter`.
+
+* **Content-level formatting**: Whitespace differences in document content. These are formatting-only (non-normative) when normalized content matches (using `text_content: :normalize`).
+
+* **Informative**: Differences tracked for reference but don't affect equivalence (when behavior is `:ignore`).
+
+* **Normative**: Semantic content differences that affect equivalence (when behavior is `:strict` or when normalized content differs).
+
 == CompareProfile-Based Classification
 
 === Overview
@@ -120,22 +147,42 @@ DiffNode → DiffClassifier → CompareProfile → normative?
 
 === Classification Hierarchy
 
-Canon uses a three-level hierarchy for classifying differences:
+Canon uses a **multi-level hierarchy** for classifying differences:
+
+[source]
+----
+DiffNode → DiffClassifier → XmlSerializationFormatter → serialization formatting?
+                                       ↓
+                                  CompareProfile → normative dimension?
+                                       ↓
+                                  FormattingDetector → formatting-only?
+                                       ↓
+                                  Final classification
+----
+
+**Classification priority (from highest to lowest specificity)**:
+
+1. **Serialization-level formatting** (highest priority)
+   - XML syntax differences: `<tag/>` vs `<tag></tag>`
+   - Detected by `XmlSerializationFormatter`
+   - **ALWAYS** `formatting: true, normative: false`
+   - Bypasses all other classification logic
 
-1. **Formatting-only** (lowest priority)
-   - Pure whitespace/formatting differences
-   - Normalized content is identical
-   - Markers: `[` and `]` in diff output
+2. **Content-level formatting**
+   - Whitespace differences in document content
+   - Detected by `FormattingDetector` when `text_content: :normalize`
+   - `formatting: true, normative: false` when normalized content matches
+   - Respects element-level whitespace sensitivity
 
-2. **Informative** (medium priority)
+3. **Informative** (based on `:ignore` behavior)
    - Tracked but doesn't affect equivalence
-   - Based on behavior `:ignore`
-   - Markers: `<` and `>` in diff output
+   - `formatting: false, normative: false`
+   - Example: Attribute order when `attribute_order: :ignore`
 
-3. **Normative** (highest priority)
+4. **Normative** (based on `:strict` behavior or content mismatch)
    - Affects equivalence
-   - Based on behavior `:strict`
-   - Markers: `-` and `+` in diff output
+   - `formatting: false, normative: true`
+   - Example: Different words, missing elements
 
 === Format-Specific Policies
 
@@ -229,6 +276,97 @@ result = Canon::Comparison.equivalent?(
 ----
 ====
 
+==== Text Content
+
+* **`:strict` behavior** → Normative
+  - Text must match exactly, including all whitespace
+  - Any text difference causes non-equivalence
+
+* **`:normalize` behavior** → Normative (after normalization) or Informative (if formatting-only)
+  - Whitespace is normalized (collapsed/trimmed) before comparison
+  - If normalized texts match but originals differ, classified as formatting-only (informative)
+  - This ensures that whitespace-only differences don't affect equivalence
+  - Element-level sensitivity is respected (e.g., `<pre>`, `<code>` preserve whitespace)
+
+* **`:ignore` behavior** → Informative
+  - Text content differences tracked but don't affect equivalence
+
+.Example: Text content with normalize behavior
+====
+[source,ruby]
+----
+# Formatting-only difference - normalized texts match
+xml1 = '<p>Hello  world</p>'
+xml2 = '<p>Hello world</p>'
+
+result = Canon::Comparison.equivalent?(
+  xml1, xml2,
+  match: { text_content: :normalize }
+)
+# => true (extra space is formatting-only, classified as informative)
+
+# Shows as informative in verbose output
+result.differences.first.normative?
+# => false
+result.differences.first.formatting?
+# => true
+----
+
+.Using text_content: :normalize with element-level sensitivity
+====
+[source,ruby]
+----
+# HTML defaults: <code> is whitespace-sensitive
+html1 = '<code>  indented  </code><p>  text  </p>'
+html2 = '<code>indented</code><p>text</p>'
+
+# With <code> blacklisted from sensitive elements
+Canon::Comparison.equivalent?(html1, html2,
+  format: :html,
+  match: {
+    whitespace_insensitive_elements: [:code],
+  }
+)
+# => true
+# - <code> whitespace: formatting-only (informative)
+# - <p> whitespace: formatting-only (informative)
+
+# Without blacklisting (default HTML behavior)
+Canon::Comparison.equivalent?(html1, html2, format: :html)
+# => false
+# - <code> whitespace: normative (sensitive element)
+# - <p> whitespace: formatting-only (informative)
+----
+====
+
+.Self-closing vs explicit closing tags
+====
+Per XML standards, `<tag/>` and `<tag></tag>` are semantically equivalent (both represent empty elements). Canon classifies differences in serialisation format as **formatting-only** (non-normative):
+
+[source,ruby]
+----
+# Self-closing vs explicit closing - always equivalent
+xml1 = '<svg><rect x="10" y="10"/></svg>'
+xml2 = '<svg><rect x="10" y="10"></rect></svg>'
+
+Canon::Comparison.equivalent?(xml1, xml2, format: :xml)
+# => true
+
+# Empty/whitespace-only text nodes from serialisation are formatting-only
+result = Canon::Comparison.equivalent?(xml1, xml2, format: :xml, verbose: true)
+result.differences.each do |diff|
+  if diff.dimension == :text_content
+    puts "Normative: #{diff.normative?}"  # => false
+    puts "Formatting: #{diff.formatting?}"  # => true
+  end
+end
+----
+
+This applies regardless of `text_content` behavior setting, as these differences are purely serialisation format variations (similar to attribute order).
+
+The key insight: empty or whitespace-only text nodes created by different serialisation styles (`<tag/>` vs `<tag></tag>`) are always classified as **formatting-only**, not normative.
+====
+
 === FormattingDetector Integration
 
 For dimensions that support it (`:text_content`, `:structural_whitespace`),
@@ -256,21 +394,48 @@ With `:normalize` mode:
 
 === Implementation Details
 
-The [`CompareProfile`](../../lib/canon/comparison/compare_profile.rb) class provides:
+The classification system uses three main classes:
 
-* `normative_dimension?(dimension)` - Is this dimension normative?
-* `affects_equivalence?(dimension)` - Does this dimension affect equivalence?
-* `supports_formatting_detection?(dimension)` - Can this dimension have formatting-only diffs?
+* **`XmlSerializationFormatter`** - Detects XML serialization-level formatting differences
+  - Self-closing vs explicit closing tags: `<tag/>` vs `<tag></tag>`
+  - Always returns `formatting: true, normative: false`
+  - These differences are ALWAYS non-normative regardless of match options
 
-The [`DiffClassifier`](../../lib/canon/diff/diff_classifier.rb) uses CompareProfile to classify:
+* **`CompareProfile`** - Determines dimension behavior and policy
+  - `normative_dimension?(dimension)` - Is this dimension normative?
+  - `affects_equivalence?(dimension)` - Does this dimension affect equivalence?
+  - `supports_formatting_detection?(dimension)` - Can this dimension have formatting-only diffs?
+
+* **`DiffClassifier`** - Orchestrates classification using the above
+  - First checks `XmlSerializationFormatter` for serialization formatting
+  - Then handles content-level formatting (text_content: :normalize)
+  - Finally applies `CompareProfile` policy for normative vs informative
 
 [source,ruby]
 ----
 def classify(diff_node)
-  # Check normative status based on policy
+  # FIRST: Check for XML serialization-level formatting differences
+  # These are ALWAYS non-normative (formatting-only) regardless of match options
+  if XmlSerializationFormatter.serialization_formatting?(diff_node)
+    diff_node.formatting = true
+    diff_node.normative = false
+    return diff_node
+  end
+
+  # SECOND: Handle content-level formatting for text_content with :normalize
+  if diff_node.dimension == :text_content &&
+      profile.send(:behavior_for, :text_content) == :normalize &&
+      !inside_whitespace_sensitive_element?(diff_node) &&
+      formatting_only_diff?(diff_node)
+    diff_node.formatting = true
+    diff_node.normative = false
+    return diff_node
+  end
+
+  # THIRD: Apply CompareProfile policy
   is_normative = profile.normative_dimension?(diff_node.dimension)
 
-  # Only check formatting for non-normative dimensions
+  # FOURTH: Check FormattingDetector for non-normative dimensions
   if !is_normative && profile.supports_formatting_detection?(diff_node.dimension)
     if formatting_only_diff?(diff_node)
       diff_node.formatting = true
@@ -279,11 +444,18 @@ def classify(diff_node)
     end
   end
 
+  # FIFTH: Apply normative determination
   diff_node.normative = is_normative
   diff_node
 end
 ----
 
+The key distinction for `text_content: :normalize`:
+
+* **Formatting-only detection**: Uses `normalized_equivalent?` method to compare normalized texts
+* **Element sensitivity**: Respects element-level whitespace sensitivity (`<pre>`, `<code>`, etc.)
+* **Result**: Whitespace-only differences are classified as *informative* (non-normative) when using `:normalize`
+
 == Visual Indicators
 
 === Normative Diffs