canon 0.1.13 → 0.1.15

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 60a7f65c6d95c4c10672244fe19a027022aadb8de563d9f3ac58da151085e883
-  data.tar.gz: 47f17024dd3d1a7055cef281439038d42bfb92527765f92d68392fbb14390d39
+  metadata.gz: '04860609f8d3300ccebf84a0f2208510600dcfaac4b3f54f698eb2de7eed0493'
+  data.tar.gz: fc50abe2a915d7d7ff1cd630c0a5a50849b6fd5780664cb6bb419300b2388743
 SHA512:
-  metadata.gz: 526cfa7a890447be2abc8bc358ac96a67a58ed6cb8016beebb65d087e44de48ef742c90be9ab50960c2b3d543bc7e3a7118af88a4f02af0a3e85eeea83161f14
-  data.tar.gz: 95e16e97ee9b71a1f4d220bc3c4f004f3f39f76d1b2631c68e3a5805b9f9aea4390bab9f9537dc0be254c690e6fcfa4146497ce8867bb15a28fec85387d1a0d1
+  metadata.gz: d1bcc3ad7439fdd7f65627c53cd0dc4b92d781bdbdaf330d2bb8ecc89b3319a4fc02e78de8e961cdb69854661881db39bf59c664210c7a59b7a011355b1db71b
+  data.tar.gz: cca1b3f2eee48054b5431118350e64acb46f485096cd8c88798e0935210985d63eb93de4727a42d17cfaad8ef03c55e7d1745922500f3a3495a791d86fd60676

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-01-21 09:17:44 UTC using RuboCop version 1.81.7.
+# on 2026-02-17 14:18:53 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,13 +12,52 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'canon.gemspec'
 
-# Offense count: 700
+# Offense count: 1
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: with_first_argument, with_fixed_indentation
+Layout/ArgumentAlignment:
+  Exclude:
+    - 'lib/canon/xml/element_matcher.rb'
+
+# Offense count: 23
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: EnforcedStyleAlignWith.
+# SupportedStylesAlignWith: either, start_of_block, start_of_line
+Layout/BlockAlignment:
+  Exclude:
+    - 'spec/canon/fixtures/isodoc_spec.rb'
+    - 'spec/canon/table_class_attribute_bug_spec.rb'
+
+# Offense count: 23
+# This cop supports safe autocorrection (--autocorrect).
+Layout/BlockEndNewline:
+  Exclude:
+    - 'spec/canon/fixtures/isodoc_spec.rb'
+    - 'spec/canon/table_class_attribute_bug_spec.rb'
+
+# Offense count: 46
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: Width, AllowedPatterns.
+Layout/IndentationWidth:
+  Exclude:
+    - 'spec/canon/fixtures/isodoc_spec.rb'
+    - 'spec/canon/table_class_attribute_bug_spec.rb'
+
+# Offense count: 780
 # 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
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowInHeredoc.
+Layout/TrailingWhitespace:
+  Exclude:
+    - 'lib/canon/xml/element_matcher.rb'
+
 # Offense count: 48
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
@@ -48,44 +87,45 @@ Lint/UnreachableCode:
   Exclude:
     - 'lib/canon/diff_formatter/debug_output.rb'
 
-# Offense count: 6
+# Offense count: 7
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
 # NotImplementedExceptions: NotImplementedError
 Lint/UnusedMethodArgument:
   Exclude:
+    - 'lib/canon/comparison.rb'
     - 'lib/canon/diff/path_builder.rb'
     - 'lib/canon/diff_formatter/by_line/base_formatter.rb'
     - 'lib/canon/diff_formatter/by_line/xml_formatter.rb'
     - 'lib/canon/diff_formatter/by_object/base_formatter.rb'
 
-# Offense count: 209
+# Offense count: 215
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
 
-# Offense count: 20
+# Offense count: 21
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
   Max: 84
 
-# Offense count: 177
+# Offense count: 183
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 363
+# Offense count: 369
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 110
+  Max: 115
 
 # Offense count: 44
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Max: 9
 
-# Offense count: 143
+# Offense count: 149
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
@@ -119,12 +159,13 @@ Naming/VariableNumber:
     - 'lib/canon/comparison/markup_comparator.rb'
     - 'lib/canon/comparison/xml_comparator/diff_node_builder.rb'
 
-# Offense count: 2
+# Offense count: 13
 # Configuration parameters: MinSize.
 Performance/CollectionLiteralInLoop:
   Exclude:
     - 'lib/canon/comparison/html_comparator.rb'
     - 'lib/canon/xml/xml_base_handler.rb'
+    - 'spec/canon/table_class_attribute_bug_spec.rb'
 
 # Offense count: 68
 # Configuration parameters: Prefixes, AllowedPatterns.
@@ -132,7 +173,7 @@ Performance/CollectionLiteralInLoop:
 RSpec/ContextWording:
   Enabled: false
 
-# Offense count: 25
+# Offense count: 27
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
@@ -143,13 +184,7 @@ RSpec/DescribeMethod:
     - 'spec/canon/comparison/multiple_differences_spec.rb'
     - 'spec/canon/diff_formatter/character_map_customization_spec.rb'
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-RSpec/EmptyHook:
-  Exclude:
-    - 'spec/canon/color_detector_spec.rb'
-
-# Offense count: 679
+# Offense count: 696
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 67
@@ -201,11 +236,11 @@ RSpec/MultipleDescribes:
   Exclude:
     - 'spec/canon/comparison/match_options_spec.rb'
 
-# Offense count: 522
+# Offense count: 536
 RSpec/MultipleExpectations:
   Max: 15
 
-# Offense count: 69
+# Offense count: 70
 # Configuration parameters: AllowSubject.
 RSpec/MultipleMemoizedHelpers:
   Max: 13
@@ -224,12 +259,13 @@ RSpec/NamedSubject:
 RSpec/NestedGroups:
   Max: 4
 
-# Offense count: 10
+# Offense count: 11
 # Configuration parameters: AllowedPatterns.
 # AllowedPatterns: ^expect_, ^assert_
 RSpec/NoExpectationExample:
   Exclude:
     - 'spec/canon/context_grouping_spec.rb'
+    - 'spec/canon/fixtures/isodoc_spec.rb'
     - 'spec/canon/informative_diffs_debug_spec.rb'
     - 'spec/canon/isodoc_blockquotes_spec.rb'
     - 'spec/canon/match_scenarios_spec.rb'
@@ -257,6 +293,18 @@ RSpec/VerifiedDoubles:
     - 'spec/canon/diff/xml_serialization_formatter_spec.rb'
     - 'spec/canon/tree_diff/operation_converter_spec.rb'
 
+# Offense count: 44
+# 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/fixtures/isodoc_spec.rb'
+    - 'spec/canon/table_class_attribute_bug_spec.rb'
+
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, AllowComments.

data/README.adoc

@@ -16,6 +16,47 @@ Key features:
 * **Multiple interfaces**: Ruby API, CLI, RSpec matchers
 * **Smart diff output**: By-line or by-object modes with syntax highlighting
 
+== When to use formatting vs comparison
+
+Canon provides two main APIs with different purposes:
+
+*Use `Canon.format` for formatting/canonicalization:*
+
+* Pretty-printing XML/JSON/YAML for display
+* Canonicalizing documents for storage
+* Normalizing formatting
+
+*Use `Canon::Comparison.equivalent?` for semantic comparison:*
+
+* Test assertions
+* Document equivalence checking
+* Diff generation
+
+[IMPORTANT]
+====
+Do NOT use `Canon.format_xml` output for string comparison in tests.
+The formatting process changes line counts and formatting, which causes
+false test failures.
+
+Use `Canon::Comparison.equivalent?` instead, which performs semantic
+comparison and properly handles XML declarations.
+====
+
+[example]
+====
+[source,ruby]
+----
+# WRONG - formatting changes line counts
+expect(Canon.format_xml(actual)).to eq(expected_formatted)
+
+# RIGHT - semantic comparison ignores formatting differences
+expect(Canon::Comparison.equivalent?(actual, expected, format: :xml)).to be true
+
+# BEST - use RSpec matchers
+expect(actual).to be_xml_equivalent_to(expected)
+----
+====
+
 == Installation
 
 Add to your application's Gemfile:

data/docs/interfaces/ruby-api/index.adoc

@@ -18,6 +18,32 @@ For command-line usage, see link:../cli/[CLI documentation].
 
 For RSpec testing, see link:../rspec/[RSpec documentation].
 
+== Choosing the right API
+
+Canon provides two main categories of APIs with different purposes.
+
+=== Formatting APIs
+
+Use `Canon.format` or `Canon.format_xml` when you need to:
+
+* Pretty-print documents for display
+* Canonicalize documents for storage
+* Normalize document formatting
+
+NOTE: XML declarations are preserved in pretty-print mode and removed in
+canonicalization mode.
+
+=== Comparison APIs
+
+Use `Canon::Comparison.equivalent?` when you need to:
+
+* Compare documents semantically
+* Generate diffs
+* Make test assertions
+
+NOTE: XML declarations are stripped during preprocessing for semantic comparison.
+Documents with and without XML declarations are considered equivalent.
+
 == General
 
 Canon provides a unified Ruby API for working with XML, HTML, JSON, and YAML

data/docs/understanding/formats/xml.adoc

@@ -183,6 +183,31 @@ configures preprocessing, match options, diff algorithm, and formatting.
 
 == XML-specific features
 
+=== XML declaration handling
+
+The XML declaration (`<?xml version="1.0" encoding="UTF-8"?>`) is handled
+differently depending on the operation:
+
+[cols="2,3"]
+|===
+| Operation | XML Declaration
+
+| `Canon.format_xml` (pretty)
+| Preserved
+
+| `Canon.format_xml` (c14n)
+| Removed (per W3C C14N spec)
+
+| `Canon::Comparison.equivalent?`
+| Stripped during preprocessing
+
+| RSpec matchers
+| Stripped during preprocessing
+|===
+
+This means documents with and without XML declarations are considered
+equivalent when using the comparison API.
+
 === Comment handling
 
 XML comments are preserved in canonical form unless `--with-comments` is explicitly set.

data/lib/canon/color_detector.rb

@@ -81,24 +81,27 @@ module Canon
       #
       # @return [Boolean] true if colors appear to be supported
       def detect_from_env
-        # Check for known color-capable terminals
-        colorterm = ENV["COLORTERM"]
-        return true if COLOR_TERM_VALUES.include?(colorterm)
-
         # Check TERM variable
-        term = ENV["TERM"]
-        if term
+        term = ENV.fetch("TERM", nil)
+        if term && NO_COLOR_TERMS.any? { |t| term.include?(t) }
           # Known no-color terminals
-          return false if NO_COLOR_TERMS.any? { |t| term.include?(t) }
+          return false
+        end
+
+        # Check CI environments
+        # Some CI systems support colors, others don't
+        return detect_ci_colors if ci_environment?
+
+        if term
           # Known color-capable terminals
           return true if COLOR_TERM_SUFFIXES.any? { |s| term.end_with?(s) }
           # Most modern terminals support basic ANSI colors
           return true unless term.empty? || term == "unknown"
         end
 
-        # Check CI environments
-        # Some CI systems support colors, others don't
-        return detect_ci_colors if ci_environment?
+        # Check for known color-capable terminals
+        colorterm = ENV.fetch("COLORTERM", nil)
+        return true if COLOR_TERM_VALUES.include?(colorterm)
 
         # Default: assume colors are supported on modern terminals
         # This is a safe default for most use cases
@@ -122,17 +125,17 @@ module Canon
       # - Generic CI: check for specific TeamCity/Terminal variables
       #
       # @return [Boolean] true if CI environment likely supports colors
-      def detect_ci_colors
+      def detect_ci_colors # rubocop:disable Naming/PredicateMethod
+        # Most modern CI systems support ANSI colors
+        # Only disable for explicitly known non-color CI
+        return false if ENV["TERM"] == "dumb"
+
         # GitHub Actions explicitly supports colors
         return true if ENV["GITHUB_ACTIONS"]
 
         # TeamCity supports colors with specific env var
         return true if ENV["TEAMCITY_VERSION"]
 
-        # Most modern CI systems support ANSI colors
-        # Only disable for explicitly known non-color CI
-        return false if ENV["TERM"] == "dumb"
-
         # Default to supporting colors in CI
         true
       end

data/lib/canon/comparison/comparison_result.rb

@@ -44,10 +44,8 @@ html_version: nil, match_options: nil, algorithm: :dom, original_strings: nil)
           if diff.is_a?(Canon::Diff::DiffNode)
             diff.normative?
           # Legacy Hash format - always considered normative (structural differences)
-          elsif diff.is_a?(Hash)
-            true
           else
-            false
+            diff.is_a?(Hash)
           end
         end
       end

data/lib/canon/comparison/dimensions/attribute_order_dimension.rb

@@ -37,7 +37,7 @@ module Canon
         # @param order1 [Array<Symbol>] First attribute order
         # @param order2 [Array<Symbol>] Second attribute order
         # @return [Boolean] true if attribute order is exactly the same
-        def compare_strict(order1, order2)
+        def compare_strict(order1, order2) # rubocop:disable Naming/PredicateMethod
           order1 == order2
         end
 

data/lib/canon/comparison/dimensions/attribute_presence_dimension.rb

@@ -37,7 +37,7 @@ module Canon
         # @param names1 [Array<Symbol>] First attribute names
         # @param names2 [Array<Symbol>] Second attribute names
         # @return [Boolean] true if attribute names are exactly equal
-        def compare_strict(names1, names2)
+        def compare_strict(names1, names2) # rubocop:disable Naming/PredicateMethod
           names1.sort == names2.sort
         end
 

data/lib/canon/comparison/dimensions/comments_dimension.rb

@@ -37,7 +37,7 @@ module Canon
         # @param comments1 [Array<String>] First comments array
         # @param comments2 [Array<String>] Second comments array
         # @return [Boolean] true if comments are exactly equal
-        def compare_strict(comments1, comments2)
+        def compare_strict(comments1, comments2) # rubocop:disable Naming/PredicateMethod
           comments1 == comments2
         end
 
@@ -48,7 +48,7 @@ module Canon
         # @param comments1 [Array<String>] First comments array
         # @param comments2 [Array<String>] Second comments array
         # @return [Boolean] true if normalized comments are equal
-        def compare_normalize(comments1, comments2)
+        def compare_normalize(comments1, comments2) # rubocop:disable Naming/PredicateMethod
           normalize_comments(comments1) == normalize_comments(comments2)
         end
 

data/lib/canon/comparison/dimensions/element_position_dimension.rb

@@ -39,7 +39,7 @@ module Canon
         # @param pos1 [Integer] First position
         # @param pos2 [Integer] Second position
         # @return [Boolean] true if positions are equal
-        def compare_strict(pos1, pos2)
+        def compare_strict(pos1, pos2) # rubocop:disable Naming/PredicateMethod
           pos1 == pos2
         end
 

data/lib/canon/comparison/dimensions/registry.rb

@@ -67,7 +67,7 @@ module Canon
         # @param node2 [Object] Second node
         # @param behavior [Symbol] Comparison behavior
         # @return [Boolean] true if nodes match for this dimension
-        def self.compare(dimension_name, node1, node2, behavior)
+        def self.compare(dimension_name, node1, node2, behavior) # rubocop:disable Naming/PredicateMethod
           dimension = get(dimension_name)
           dimension.equivalent?(node1, node2, behavior)
         end

data/lib/canon/comparison/dimensions/structural_whitespace_dimension.rb

@@ -41,7 +41,7 @@ module Canon
         # @param ws1 [Array<String>] First whitespace array
         # @param ws2 [Array<String>] Second whitespace array
         # @return [Boolean] true if structural whitespace is exactly equal
-        def compare_strict(ws1, ws2)
+        def compare_strict(ws1, ws2) # rubocop:disable Naming/PredicateMethod
           ws1 == ws2
         end
 
@@ -52,7 +52,7 @@ module Canon
         # @param ws1 [Array<String>] First whitespace array
         # @param ws2 [Array<String>] Second whitespace array
         # @return [Boolean] true if normalized structural whitespace is equal
-        def compare_normalize(ws1, ws2)
+        def compare_normalize(ws1, ws2) # rubocop:disable Naming/PredicateMethod
           normalize_whitespace(ws1) == normalize_whitespace(ws2)
         end
 

data/lib/canon/comparison/dimensions/text_content_dimension.rb

@@ -37,19 +37,27 @@ module Canon
         # @param text1 [String, nil] First text
         # @param text2 [String, nil] Second text
         # @return [Boolean] true if texts are exactly equal
-        def compare_strict(text1, text2)
+        def compare_strict(text1, text2) # rubocop:disable Naming/PredicateMethod
           text1.to_s == text2.to_s
         end
 
         # Normalized text comparison
         #
         # Collapses whitespace and compares.
+        # Two whitespace-only strings that both normalize to empty are equivalent.
         #
         # @param text1 [String, nil] First text
         # @param text2 [String, nil] Second text
         # @return [Boolean] true if normalized texts are equal
-        def compare_normalize(text1, text2)
-          normalize_text(text1) == normalize_text(text2)
+        def compare_normalize(text1, text2) # rubocop:disable Naming/PredicateMethod
+          normalized1 = normalize_text(text1)
+          normalized2 = normalize_text(text2)
+
+          # Both empty after normalization = equivalent
+          # This handles whitespace-only text nodes that normalize to empty
+          return true if normalized1.empty? && normalized2.empty?
+
+          normalized1 == normalized2
         end
 
         private

data/lib/canon/comparison/format_detector.rb

@@ -52,7 +52,7 @@ module Canon
         # @return [Symbol] Format type
         def detect_string(str)
           # Use cache for format detection
-          Cache.fetch(:format_detect, Cache.key_for_format_detection(str)) do
+          Cache.fetch(:format_detect, Cache.key_for_format_detection(str)) do # rubocop:disable Lint/UselessDefaultValueArgument
             detect_string_uncached(str)
           end
         end