canon 0.1.8 → 0.1.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1d94be550a90d23eb695f46579b13fa327434993b89a995b3c95ba658a143fb9
-  data.tar.gz: 2ac083712aa9d0153aa2e0898186a7cbf669e775368378c9de8de6c42c52a257
+  metadata.gz: 24f79ae4b9b6817104e388a5bef96d24677f797db5d13bd6f009a26a04170137
+  data.tar.gz: 3b8260af8e2157f2f449421b3d40649521ba64495a15f7667e64c3e343b6d3b7
 SHA512:
-  metadata.gz: 45b4502c83bfd367c5933e66f610de529b87f27d5cfef18c0fe808bcbc91e20c1c3c0e32ba36ed6163a70de37c5ae3a1023c67fed586491e7eea5f7c621e2769
-  data.tar.gz: 3713856d8dfdfb4164cfd9e8bdcd4dcbdce7b303619d703b7defe58d09c5468eb3acc5f32435f3184d35f20b3a6f7470c2960d8e5cef21ba720ebd7dc44ccfbf
+  metadata.gz: 971daa53fd96c5c46b5c37c2175f12875e7e36f658cc4186848f1df90ab3db9ceff06af69320e5004d1da1d6b2dc4b35d800c5aca1b1522ac05cf14c73025c21
+  data.tar.gz: 02f5160a42bf651db2a252909966cbc7dea43239cbbae2a53d155c55c4e09709eddc34e599496bfc5cda14705931f24efbebd267b9acc8700b834fb859d8096f

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-20 02:18:38 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,70 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'canon.gemspec'
 
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleAlignWith.
+# SupportedStylesAlignWith: either, start_of_block, start_of_line
+Layout/BlockAlignment:
+  Exclude:
+    - 'spec/canon/rspec_matchers_spec.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+Layout/BlockEndNewline:
+  Exclude:
+    - 'spec/canon/rspec_matchers_spec.rb'
+
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowForAlignment.
+Layout/CommentIndentation:
+  Exclude:
+    - 'lib/canon/comparison/xml_comparator.rb'
+
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: with_first_argument, with_fixed_indentation
-Layout/ArgumentAlignment:
+Layout/ElseAlignment:
   Exclude:
-    - 'lib/canon/comparison.rb'
+    - 'lib/canon/comparison/xml_comparator.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleAlignWith, Severity.
+# SupportedStylesAlignWith: keyword, variable, start_of_line
+Layout/EndAlignment:
+  Exclude:
+    - 'lib/canon/comparison/xml_comparator.rb'
+
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle.
+# SupportedStyles: normal, indented_internal_methods
+Layout/IndentationConsistency:
+  Exclude:
+    - 'lib/canon/comparison/xml_comparator.rb'
 
-# Offense count: 697
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Width, AllowedPatterns.
+Layout/IndentationWidth:
+  Exclude:
+    - 'spec/canon/rspec_matchers_spec.rb'
+
+# Offense count: 655
 # 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: 3
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowInHeredoc.
-Layout/TrailingWhitespace:
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: aligned, indented
+Layout/MultilineOperationIndentation:
   Exclude:
-    - 'lib/canon/comparison.rb'
+    - 'lib/canon/diff/diff_classifier.rb'
 
 # Offense count: 48
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
@@ -74,38 +117,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: 194
 # 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: 164
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 376
+# Offense count: 346
 # 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: 131
 # 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 +156,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.
@@ -140,7 +182,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 +199,7 @@ RSpec/DescribeMethod:
     - 'spec/canon/comparison/multiple_differences_spec.rb'
     - 'spec/canon/diff_formatter/character_map_customization_spec.rb'
 
-# Offense count: 624
+# Offense count: 663
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 67
@@ -171,7 +213,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:
@@ -212,7 +254,7 @@ RSpec/MultipleDescribes:
 RSpec/MultipleExpectations:
   Max: 15
 
-# Offense count: 66
+# Offense count: 69
 # Configuration parameters: AllowSubject.
 RSpec/MultipleMemoizedHelpers:
   Max: 13
@@ -226,7 +268,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 +296,34 @@ RSpec/SpecFilePathFormat:
     - 'spec/canon/yaml/formatter_spec.rb'
     - 'spec/xml_c14n_spec.rb'
 
-# Offense count: 94
+# Offense count: 95
 # 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/tree_diff/operation_converter_spec.rb'
 
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, AllowedMethods, AllowedPatterns, AllowBracesOnProceduralOneLiners, BracesRequiredMethods.
+# SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
+# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
+# FunctionalMethods: let, let!, subject, watch
+# AllowedMethods: lambda, proc, it
+Style/BlockDelimiters:
+  Exclude:
+    - 'spec/canon/rspec_matchers_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:
@@ -269,10 +331,11 @@ Style/HashLikeCase:
     - 'lib/canon/diff/diff_block_builder.rb'
     - 'lib/canon/xml/character_encoder.rb'
 
-# Offense count: 4
+# Offense count: 6
 # This cop supports unsafe autocorrection (--autocorrect-all).
 Style/IdenticalConditionalBranches:
   Exclude:
+    - 'lib/canon/comparison/xml_comparator.rb'
     - 'lib/canon/diff_formatter/by_object/base_formatter.rb'
     - 'lib/canon/diff_formatter/legend.rb'
 
@@ -282,3 +345,27 @@ Style/IdenticalConditionalBranches:
 Style/OptionalBooleanParameter:
   Exclude:
     - 'lib/canon/diff_formatter/debug_output.rb'
+
+# Offense count: 6
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
+# SupportedStyles: single_quotes, double_quotes
+Style/StringLiterals:
+  Exclude:
+    - 'spec/canon/rspec_matchers_spec.rb'
+
+# Offense count: 5
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleForMultiline.
+# SupportedStylesForMultiline: comma, consistent_comma, diff_comma, no_comma
+Style/TrailingCommaInArguments:
+  Exclude:
+    - 'spec/canon/rspec_matchers_spec.rb'
+
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleForMultiline.
+# SupportedStylesForMultiline: comma, consistent_comma, diff_comma, no_comma
+Style/TrailingCommaInHashLiteral:
+  Exclude:
+    - 'spec/canon/rspec_matchers_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

@@ -229,6 +229,69 @@ 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)
+----
+====
+
 === FormattingDetector Integration
 
 For dimensions that support it (`:text_content`, `:structural_whitespace`),
@@ -262,12 +325,23 @@ The [`CompareProfile`](../../lib/canon/comparison/compare_profile.rb) class prov
 * `affects_equivalence?(dimension)` - Does this dimension affect equivalence?
 * `supports_formatting_detection?(dimension)` - Can this dimension have formatting-only diffs?
 
-The [`DiffClassifier`](../../lib/canon/diff/diff_classifier.rb) uses CompareProfile to classify:
+The [`DiffClassifier`](../../lib/canon/diff/diff_classifier.rb) uses CompareProfile to classify differences, with special handling for `text_content: :normalize`:
 
 [source,ruby]
 ----
 def classify(diff_node)
-  # Check normative status based on policy
+  # SPECIAL CASE: text_content with :normalize behavior
+  # Formatting-only differences (whitespace-only) are marked as non-normative
+  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
+
+  # Standard classification flow
   is_normative = profile.normative_dimension?(diff_node.dimension)
 
   # Only check formatting for non-normative dimensions
@@ -284,6 +358,12 @@ def classify(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