canon 0.1.7 → 0.1.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 74adcfa8d9b6ab7cc95fba2557dcfecbfa0dbd134e90497a30195fb476de6b42
-  data.tar.gz: dab1ef7a6c5fe852b6935561ddb85e2ffdde6edf4463b36cbe2f9deb5251b4f2
+  metadata.gz: 1d94be550a90d23eb695f46579b13fa327434993b89a995b3c95ba658a143fb9
+  data.tar.gz: 2ac083712aa9d0153aa2e0898186a7cbf669e775368378c9de8de6c42c52a257
 SHA512:
-  metadata.gz: 98b8e102b110e5a85363a3ccceb28ffb87082f9695ad0c39b182a1f9f3bca7fc652c471a2134cc621b84d9acfaa858f10aea5c9ddb6a90f5e098ed5b3cd795c5
-  data.tar.gz: 1db527549bde5c60b0f45a8d34a59c877ed9b880a9ea80f076b2501319886e1300d036fd5502820d361d06d9a4957a9b648d479aaf98dcf0bc55bb26f9673066
+  metadata.gz: 45b4502c83bfd367c5933e66f610de529b87f27d5cfef18c0fe808bcbc91e20c1c3c0e32ba36ed6163a70de37c5ae3a1023c67fed586491e7eea5f7c621e2769
+  data.tar.gz: 3713856d8dfdfb4164cfd9e8bdcd4dcbdce7b303619d703b7defe58d09c5468eb3acc5f32435f3184d35f20b3a6f7470c2960d8e5cef21ba720ebd7dc44ccfbf

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2025-12-22 03:34:50 UTC using RuboCop version 1.81.7.
+# on 2026-01-17 14:46:16 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
@@ -18,96 +18,27 @@ Gemspec/RequiredRubyVersion:
 # SupportedStyles: with_first_argument, with_fixed_indentation
 Layout/ArgumentAlignment:
   Exclude:
-    - 'spec/canon/comparison/multiple_differences_spec.rb'
-
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyleAlignWith.
-# SupportedStylesAlignWith: either, start_of_block, start_of_line
-Layout/BlockAlignment:
-  Exclude:
-    - 'lib/canon/diff_formatter/by_line/html_formatter.rb'
-    - 'spec/canon/diff/diff_node_mapper_granularity_spec.rb'
+    - 'lib/canon/comparison.rb'
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-Layout/BlockEndNewline:
-  Exclude:
-    - 'spec/canon/diff/diff_node_mapper_granularity_spec.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-Layout/ElseAlignment:
-  Exclude:
-    - 'lib/canon/diff_formatter/by_object/base_formatter.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/diff_formatter/by_object/base_formatter.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowForAlignment, AllowBeforeTrailingComments, ForceEqualSignAlignment.
-Layout/ExtraSpacing:
-  Exclude:
-    - 'lib/canon/commands/diff_command.rb'
-
-# Offense count: 3
-# 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:
-    - 'spec/canon/comparison/multiple_differences_spec.rb'
-
-# Offense count: 4
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: Width, AllowedPatterns.
-Layout/IndentationWidth:
-  Exclude:
-    - 'lib/canon/diff_formatter/by_object/base_formatter.rb'
-    - 'spec/canon/diff/diff_node_mapper_granularity_spec.rb'
-
-# Offense count: 654
+# Offense count: 697
 # 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: 3
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle.
-# SupportedStyles: final_newline, final_blank_line
-Layout/TrailingEmptyLines:
-  Exclude:
-    - 'spec/canon/commands/diff_command_spec.rb'
-    - 'spec/canon/comparison/multiple_differences_spec.rb'
-    - 'spec/canon/diff/diff_classifier_spec.rb'
-
-# Offense count: 10
+# Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowInHeredoc.
 Layout/TrailingWhitespace:
   Exclude:
-    - 'spec/canon/comparison/multiple_differences_spec.rb'
+    - 'lib/canon/comparison.rb'
 
-# Offense count: 46
+# Offense count: 48
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
   Enabled: false
 
-# Offense count: 2
-Lint/DuplicateMethods:
-  Exclude:
-    - 'lib/canon/diff_formatter/by_line/html_formatter.rb'
-
 # Offense count: 2
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowComments.
@@ -132,18 +63,18 @@ Lint/UnreachableCode:
   Exclude:
     - 'lib/canon/diff_formatter/debug_output.rb'
 
-# Offense count: 7
+# Offense count: 6
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowUnusedKeywordArguments, IgnoreEmptyMethods, IgnoreNotImplementedMethods, NotImplementedExceptions.
 # NotImplementedExceptions: NotImplementedError
 Lint/UnusedMethodArgument:
   Exclude:
-    - 'lib/canon/comparison/match_options.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: 219
+# Offense count: 225
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
@@ -154,27 +85,22 @@ Metrics/AbcSize:
 Metrics/BlockLength:
   Max: 84
 
-# Offense count: 2
-# Configuration parameters: CountBlocks, CountModifierForms.
-Metrics/BlockNesting:
-  Max: 4
-
-# Offense count: 180
+# Offense count: 178
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 347
+# Offense count: 376
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
-  Max: 107
+  Max: 110
 
-# Offense count: 23
+# Offense count: 39
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Max: 9
 
-# Offense count: 142
+# Offense count: 143
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
@@ -185,10 +111,11 @@ Metrics/PerceivedComplexity:
 Naming/MethodParameterName:
   Exclude:
     - '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: 2
+# Offense count: 1
 # Configuration parameters: NamePrefix, ForbiddenPrefixes, AllowedMethods, MethodDefinitionMacros, UseSorbetSigs.
 # NamePrefix: is_, has_, have_, does_
 # ForbiddenPrefixes: is_, has_, have_, does_
@@ -197,7 +124,6 @@ Naming/MethodParameterName:
 Naming/PredicatePrefix:
   Exclude:
     - 'lib/canon/comparison/html_comparator.rb'
-    - 'lib/canon/comparison/xml_comparator.rb'
 
 # Offense count: 2
 # Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers, AllowedPatterns.
@@ -207,21 +133,20 @@ Naming/VariableNumber:
   Exclude:
     - 'lib/canon/comparison/json_comparator.rb'
 
-# Offense count: 4
+# Offense count: 2
 # Configuration parameters: MinSize.
 Performance/CollectionLiteralInLoop:
   Exclude:
     - 'lib/canon/comparison/html_comparator.rb'
-    - 'lib/canon/diff_formatter/diff_detail_formatter.rb'
     - 'lib/canon/xml/xml_base_handler.rb'
 
-# Offense count: 58
+# Offense count: 62
 # Configuration parameters: Prefixes, AllowedPatterns.
 # Prefixes: when, with, without
 RSpec/ContextWording:
   Enabled: false
 
-# Offense count: 24
+# Offense count: 25
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
@@ -232,7 +157,7 @@ RSpec/DescribeMethod:
     - 'spec/canon/comparison/multiple_differences_spec.rb'
     - 'spec/canon/diff_formatter/character_map_customization_spec.rb'
 
-# Offense count: 592
+# Offense count: 624
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 67
@@ -269,12 +194,11 @@ RSpec/InstanceVariable:
   Exclude:
     - 'spec/canon/rspec_matchers_spec.rb'
 
-# Offense count: 16
+# Offense count: 15
 # Configuration parameters: EnforcedStyle.
 # SupportedStyles: have_received, receive
 RSpec/MessageSpies:
   Exclude:
-    - 'spec/canon/comparison/yaml_comparator_spec.rb'
     - 'spec/canon/diff/diff_classifier_spec.rb'
     - 'spec/canon_spec.rb'
     - 'spec/xml_c14n_spec.rb'
@@ -284,7 +208,7 @@ RSpec/MultipleDescribes:
   Exclude:
     - 'spec/canon/comparison/match_options_spec.rb'
 
-# Offense count: 489
+# Offense count: 515
 RSpec/MultipleExpectations:
   Max: 15
 
@@ -302,7 +226,7 @@ RSpec/NamedSubject:
     - 'spec/canon/pretty_printer/json_spec.rb'
     - 'spec/canon/pretty_printer/xml_spec.rb'
 
-# Offense count: 29
+# Offense count: 30
 # Configuration parameters: AllowedGroups.
 RSpec/NestedGroups:
   Max: 4
@@ -330,32 +254,14 @@ RSpec/SpecFilePathFormat:
     - 'spec/canon/yaml/formatter_spec.rb'
     - 'spec/xml_c14n_spec.rb'
 
-# Offense count: 68
+# Offense count: 94
 # Configuration parameters: IgnoreNameless, IgnoreSymbolicNames.
 RSpec/VerifiedDoubles:
   Exclude:
     - 'spec/canon/diff/diff_classifier_spec.rb'
+    - 'spec/canon/diff/path_builder_spec.rb'
     - 'spec/canon/tree_diff/operation_converter_spec.rb'
 
-# Offense count: 1
-# 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/diff/diff_node_mapper_granularity_spec.rb'
-
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, AllowComments.
-# SupportedStyles: empty, nil, both
-Style/EmptyElse:
-  Exclude:
-    - 'lib/canon/diff_formatter/diff_detail_formatter.rb'
-
 # Offense count: 3
 # Configuration parameters: MinBranchesCount.
 Style/HashLikeCase:
@@ -376,19 +282,3 @@ Style/IdenticalConditionalBranches:
 Style/OptionalBooleanParameter:
   Exclude:
     - 'lib/canon/diff_formatter/debug_output.rb'
-
-# Offense count: 1
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: Mode.
-Style/StringConcatenation:
-  Exclude:
-    - 'lib/canon/diff_formatter/diff_detail_formatter.rb'
-
-# Offense count: 6
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyleForMultiline.
-# SupportedStylesForMultiline: comma, consistent_comma, diff_comma, no_comma
-Style/TrailingCommaInArguments:
-  Exclude:
-    - 'lib/canon/commands/diff_command.rb'
-    - 'spec/canon/commands/diff_command_spec.rb'

data/README.adoc

@@ -69,7 +69,7 @@ Canon::PrettyPrinter::Xml.new(indent: 2).format(xml_input)
 require 'canon/comparison'
 
 xml1 = '<root><a>1</a><b>2</b></root>'
-xml2 = '<root>  <b>2</b>  <a>1</a>  </root>'
+xml2 = '<root>  <a>1</a>  <b>2</b>    </root>'
 
 Canon::Comparison.equivalent?(xml1, xml2)
 # => true (semantically equivalent despite formatting differences)
@@ -534,14 +534,14 @@ Each dimension can have one of three behaviors:
 ====
 ----
 # Default (strict mode): whitespace differences are normative
-xml1 = '<root><p>Hello world</p></root>'
-xml2 = '<root><p>Hello\nworld</p></root>'
+xml1 = "<root><p>Hello world</p></root>"
+xml2 = "<root><p>Hello   \nworld</p></root>"
 Canon::Comparison.equivalent?(xml1, xml2)  # => false
 
 # Normalize mode: whitespace-only differences are formatting-only
 Canon::Comparison.equivalent?(xml1, xml2,
-  match: { text_content: :normalize, structural_whitespace: :normalize }
-)  # => true
+  match: { text_content: :normalize }
+) # => true
 ----
 ====
 
@@ -620,11 +620,11 @@ html1 = '<div><!-- comment --><p>Text</p></div>'
 html2 = '<div><p>Text</p></div>'
 
 # HTML defaults: comments are ignored (presentational)
-result = Canon::Comparison.equivalent?(html1, html2)
+result = Canon::Comparison.equivalent?(html1, html2, format: :html)
 # => true (comments don't affect HTML equivalence by default)
 
 # Explicit strict matching
-result = Canon::Comparison.equivalent?(html1, html2,
+result = Canon::Comparison.equivalent?(html1, html2, format: :html,
   match: { comments: :strict }
 )
 # => false (comments now affect equivalence)
@@ -638,17 +638,17 @@ don't affect the semantic meaning unless explicitly configured to `:strict`.
 ====
 [source,ruby]
 ----
-html1 = '<pre>Line 1\n  Line 2</pre>'
-html2 = '<pre>Line 1\nLine 2</pre>'
+html1 = "<pre>Line 1\n  Line 2</pre>"
+html2 = "<pre>Line 1\nLine 2</pre>"
 
 # Whitespace is preserved in <pre> elements
-result = Canon::Comparison.equivalent?(html1, html2)
+result = Canon::Comparison::HtmlComparator.equivalent?(html1, html2)
 # => false (whitespace differs in pre element)
 
 # But normalized in other elements
-html3 = '<div>Text    with    spaces</div>'
-html4 = '<div>Text with spaces</div>'
-result = Canon::Comparison.equivalent?(html3, html4)
+html3 = "<div>Text    with\n    spaces</div>"
+html4 = "<div>Text with\n spaces</div>"
+result = Canon::Comparison::HtmlComparator.equivalent?(html3, html4)
 # => true (whitespace normalized in regular elements)
 ----
 

data/docs/.lycheeignore

@@ -0,0 +1,69 @@
+# Lychee ignore patterns
+# These link types are valid but lychee can't verify them
+
+# Ignore all .adoc files (source files that don't exist in built site)
+\.adoc$
+
+# Ignore all .html files with inconsistent paths
+\.html$
+
+# Ignore all file:// URLs (link checker has inconsistent base URL handling for local files)
+file://
+
+# Ignore assets directory (CSS/JS files)
+file://.*/assets/.*
+
+# Ignore directory links with trailing slashes (web servers handle these with index.html)
+file://.*/canon/$
+file://.*/canon/.*/$
+file://.*/docs/$
+file://.*/docs/.*/$
+
+# Ignore all /canon/* and /docs/* paths (may have inconsistent base URLs during link checking)
+file://.*/canon/.*
+file://.*/docs/.*
+
+# Ignore asciidoc-style directory links without .html extension
+file://.*/extending-canon$
+file://.*/verbose-mode-architecture$
+file://.*/cli/diff-command$
+file://.*/cli/format-command$
+file://.*/rspec/matchers$
+file://.*/ruby-api/comparison$
+file://.*/ruby-api/formatting$
+file://.*/core-concepts$
+file://.*/installation$
+file://.*/quick-start$
+file://.*/profiles$
+file://.*/comparison-pipeline$
+file://.*/migrating-from-xmldiff$
+file://.*/performance-optimization$
+file://.*/testing-xml-generation$
+file://.*/debugging-test-failures$
+file://.*/choosing-configuration$
+file://.*/guides/choosing-configuration$
+file://.*/environment-configuration/size-limits$
+file://.*/environment-configuration/override-system$
+file://.*/environment-configuration/input-validation$
+file://.*/architecture$
+
+# Ignore example domain links (these don't exist)
+http://a\.com/.*
+http://b\.com/.*
+http://c\.com/.*
+http://example\.com/.*
+http://ns\.com/.*
+http://shop\.com/.*
+http://z\.com/.*
+
+# Ignore GitHub-specific links
+https://github\.com/[^/]+/[^/]+/edit/.*
+https://github\.com/[^/]+/[^/]+/blob/.*
+
+# Ignore mailto links
+mailto:.*
+
+# Ignore localhost links for development
+http://localhost:.*
+http://127\.0\.0\.1:.*
+http://0\.0\.0\.0:.*

data/docs/advanced/extending-canon.adoc

@@ -0,0 +1,193 @@
+---
+title: Extending Canon
+parent: Advanced
+nav_order: 8
+---
+= Extending Canon
+
+== Purpose
+
+This document explains how to extend Canon with custom functionality, including creating custom comparators, formatters, and adapters for different document formats.
+
+== Overview
+
+Canon is designed to be extensible at multiple layers:
+
+* **Layer 1**: Custom preprocessing/normalization
+* **Layer 2**: Custom comparison algorithms
+* **Layer 3**: Custom match options and dimensions
+* **Layer 4**: Custom diff formatters and renderers
+
+== Adapter Pattern
+
+Canon uses an adapter pattern to work with different parsing libraries (Nokogiri, Moxml, etc.).
+
+=== Adapter Structure
+
+[source,ruby]
+----
+module Canon
+  module Adapters
+    class NokogiriAdapter
+      def parse(input)
+        # Parse with Nokogiri
+        Nokogiri::XML(input)
+      end
+
+      def serialize(node)
+        # Serialize with Nokogiri
+        node.to_xml
+      end
+    end
+  end
+end
+----
+
+=== Creating a Custom Adapter
+
+To add support for a new parsing library:
+
+1. Create an adapter class that implements `parse` and `serialize` methods
+2. Register the adapter with the format system
+3. Add tests for the new adapter
+
+== Custom Comparators
+
+=== Creating a Custom Comparison Algorithm
+
+[source,ruby]
+----
+module Canon
+  module Comparison
+    class CustomComparator < BaseComparator
+      def compare(node1, node2, opts)
+        # Your comparison logic here
+        differences = []
+
+        # Your algorithm implementation
+
+        differences
+      end
+    end
+  end
+end
+----
+
+=== Registering Your Algorithm
+
+[source,ruby]
+----
+Canon::Comparison.register_algorithm(:custom, CustomComparator)
+----
+
+Then use it:
+
+[source,ruby]
+----
+Canon::Comparison.equivalent?(doc1, doc2, diff_algorithm: :custom)
+----
+
+== Custom Formatters
+
+=== Creating a Custom Diff Formatter
+
+[source,ruby]
+----
+module Canon
+  class DiffFormatter
+    class CustomFormatter
+      def format(differences, opts)
+        # Your formatting logic here
+        formatted_output = ""
+
+        differences.each do |diff|
+          formatted_output += format_difference(diff, opts)
+        end
+
+        formatted_output
+      end
+    end
+  end
+end
+----
+
+=== Using Your Formatter
+
+[source,ruby]
+----
+result = Canon::Comparison.equivalent?(doc1, doc2, verbose: true)
+
+formatter = Canon::DiffFormatter::CustomFormatter.new
+output = formatter.format(result.differences, use_color: true)
+puts output
+----
+
+== Custom Match Options
+
+=== Defining Custom Dimensions
+
+[source,ruby]
+----
+module Canon
+  module Comparison
+    class CustomDimension
+      def self.key
+        :custom_dimension
+      end
+
+      def self.compare(node1, node2, behavior, opts)
+        # Your comparison logic for this dimension
+        case behavior
+        when :strict
+          node1 == node2
+        when :normalize
+          normalize(node1) == normalize(node2)
+        when :ignore
+          true
+        end
+      end
+    end
+  end
+end
+----
+
+Register your dimension:
+
+[source,ruby]
+----
+Canon::Comparison.register_dimension(CustomDimension)
+----
+
+== Best Practices
+
+=== Testing Your Extensions
+
+1. Write comprehensive tests for your extensions
+2. Use the existing test helpers and fixtures
+3. Test edge cases and error conditions
+
+=== Performance Considerations
+
+1. Cache expensive computations
+2. Use lazy evaluation where appropriate
+3. Avoid unnecessary node cloning
+
+=== Error Handling
+
+1. Provide clear error messages
+2. Use Canon's error classes consistently
+3. Document error conditions
+
+== Examples
+
+See the source code for examples of:
+
+* link:xml-comparator[DOM Comparator implementation]
+* link:semantic-tree-diff-internals[Semantic Diff implementation]
+* link:diff-formatting/[Diff Formatter implementations]
+
+== See Also
+
+* link:../understanding/architecture.adoc[Architecture] - 4-layer architecture overview
+* link:../features/diff-formatting/[Diff Formatting] - Layer 4 rendering options
+* link:diff-pipeline[Comparison Pipeline] - Technical pipeline details