canon 0.1.9 → 0.1.11

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 24f79ae4b9b6817104e388a5bef96d24677f797db5d13bd6f009a26a04170137
-  data.tar.gz: 3b8260af8e2157f2f449421b3d40649521ba64495a15f7667e64c3e343b6d3b7
+  metadata.gz: e123b3a909e4ca7309ed6815282fd03c86e4514fa325d82f1e8973f1428ce83a
+  data.tar.gz: '09e45b9a9f5e8721f4df5b41465b199d0a34824640745321f35cd7edd6d65a91'
 SHA512:
-  metadata.gz: 971daa53fd96c5c46b5c37c2175f12875e7e36f658cc4186848f1df90ab3db9ceff06af69320e5004d1da1d6b2dc4b35d800c5aca1b1522ac05cf14c73025c21
-  data.tar.gz: 02f5160a42bf651db2a252909966cbc7dea43239cbbae2a53d155c55c4e09709eddc34e599496bfc5cda14705931f24efbebd267b9acc8700b834fb859d8096f
+  metadata.gz: c027b7abd237f7b0f3dc679c3b919c11dea6d02f8636aaca9ac95ba56c2d9e321ed3dc23691c33274fa1403f7147b0547011adebb4cb70f1073875cac557a394
+  data.tar.gz: 75aea03c181390b0f927c5d7ba979a8ed6a5ab807e9ab40fa281257e3d165fa001e62fa7ad9bfff3c1d007e1d8157aa49c7218cb2a99bb07919efb1b7da6b120

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-01-20 02:18:38 UTC using RuboCop version 1.81.7.
+# on 2026-01-21 06:10:55 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,70 +12,29 @@ 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).
-Layout/ElseAlignment:
-  Exclude:
-    - '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: 4
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: Width, AllowedPatterns.
-Layout/IndentationWidth:
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: with_first_argument, with_fixed_indentation
+Layout/ArgumentAlignment:
   Exclude:
-    - 'spec/canon/rspec_matchers_spec.rb'
+    - 'lib/canon/diff_formatter.rb'
+    - 'spec/canon/diff_formatter_spec.rb'
 
-# Offense count: 655
+# Offense count: 705
 # 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
+# Offense count: 5
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: aligned, indented
-Layout/MultilineOperationIndentation:
+# Configuration parameters: AllowInHeredoc.
+Layout/TrailingWhitespace:
   Exclude:
-    - 'lib/canon/diff/diff_classifier.rb'
+    - 'lib/canon/diff_formatter.rb'
+    - 'spec/canon/diff_formatter_spec.rb'
 
 # Offense count: 48
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
@@ -117,7 +76,7 @@ Lint/UnusedMethodArgument:
     - 'lib/canon/diff_formatter/by_line/xml_formatter.rb'
     - 'lib/canon/diff_formatter/by_object/base_formatter.rb'
 
-# Offense count: 194
+# Offense count: 209
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
@@ -128,22 +87,22 @@ Metrics/AbcSize:
 Metrics/BlockLength:
   Max: 84
 
-# Offense count: 164
+# Offense count: 176
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 346
+# Offense count: 362
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 110
 
-# Offense count: 45
+# Offense count: 44
 # Configuration parameters: CountKeywordArgs, MaxOptionalParameters.
 Metrics/ParameterLists:
   Max: 9
 
-# Offense count: 131
+# Offense count: 142
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
@@ -167,13 +126,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.
@@ -199,7 +160,7 @@ RSpec/DescribeMethod:
     - 'spec/canon/comparison/multiple_differences_spec.rb'
     - 'spec/canon/diff_formatter/character_map_customization_spec.rb'
 
-# Offense count: 663
+# Offense count: 679
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 67
@@ -250,7 +211,7 @@ RSpec/MultipleDescribes:
   Exclude:
     - 'spec/canon/comparison/match_options_spec.rb'
 
-# Offense count: 515
+# Offense count: 522
 RSpec/MultipleExpectations:
   Max: 15
 
@@ -296,26 +257,16 @@ RSpec/SpecFilePathFormat:
     - 'spec/canon/yaml/formatter_spec.rb'
     - 'spec/xml_c14n_spec.rb'
 
-# Offense count: 95
+# 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: 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.
@@ -331,11 +282,10 @@ Style/HashLikeCase:
     - 'lib/canon/diff/diff_block_builder.rb'
     - 'lib/canon/xml/character_encoder.rb'
 
-# Offense count: 6
+# Offense count: 4
 # 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'
 
@@ -345,27 +295,3 @@ 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/README.adoc

@@ -224,68 +224,262 @@ expect(actual).to be_xml_equivalent_to(expected)
   .show_diffs(:normative)
 ----
 
-=== Original input string display
+=== Input display options
 
-When debugging test failures, it's often helpful to see the exact strings that
-were passed to the comparison before any preprocessing or normalization. The
-`verbose_diff` option displays the original input strings in an RSpec-style
-format with line numbers.
+When debugging test failures, it's often helpful to see the exact inputs that were
+passed to the comparison. Canon provides four input display options:
 
+`show_raw_inputs`:: Show raw/original file contents (before preprocessing)
+
+`show_preprocessed_inputs`:: Show what was actually compared (after preprocessing)
+
+`show_line_numbered_inputs`:: Show raw inputs with line numbers (for reference)
+
+`verbose_diff`:: Convenience flag that enables all three options above
+
+You can enable any combination of them independently.
+
+==== Show raw inputs
+
+Display the raw file contents before any preprocessing. This shows exactly what's
+in your files, useful for copying to specs.
+
+**Ruby API:**
 [source,ruby]
 ----
-# Enable original string display in configuration
+# Enable raw input display in configuration
 Canon::Config.configure do |config|
-  config.xml.diff.verbose_diff = true
+  config.xml.diff.show_raw_inputs = true
 end
 
 # Or programmatically for a specific comparison
 result = Canon::Comparison.equivalent?(xml1, xml2,
   verbose: true,
-  verbose_diff: true
+  show_raw_inputs: true
 )
 ----
 
+**CLI usage:**
+[source,bash]
+----
+# Show raw file contents (for copying to specs)
+$ canon diff file1.xml file2.xml --show-raw-inputs
+
+# Show both raw and preprocessed (full trace)
+$ canon diff file1.xml file2.xml --show-raw-inputs --show-preprocessed-inputs
+----
+
+**Environment variables:**
+[source,bash]
+----
+# Global (all formats)
+export CANON_SHOW_RAW_INPUTS=true
+
+# Format-specific
+export CANON_XML_SHOW_RAW_INPUTS=true
+export CANON_HTML_SHOW_RAW_INPUTS=true
+export CANON_JSON_SHOW_RAW_INPUTS=true
+export CANON_YAML_SHOW_RAW_INPUTS=true
+----
+
 **Output format:**
 ----
-==================================================================
-  ORIGINAL INPUT STRINGS
-==================================================================
+=== ORIGINAL INPUTS (Raw) ===
 
-Expected (as string):
-     1 | <root>
-     2 |   <element>value1</element>
-     3 | </root>
+EXPECTED:
+----------------------------------------------------------------------
+<root>  hello
+  world</root>
+
+RECEIVED:
+----------------------------------------------------------------------
+<root>hello world</root>
+
+----
+
+==== Show preprocessed inputs
+
+Display the content after preprocessing (c14n, normalize, format, etc.).
+This shows what the comparison actually compared, useful for understanding
+how preprocessing affects your content.
+
+**Ruby API:**
+[source,ruby]
+----
+# Enable preprocessed input display in configuration
+Canon::Config.configure do |config|
+  config.xml.diff.show_preprocessed_inputs = true
+end
+
+# Or programmatically for a specific comparison
+result = Canon::Comparison.equivalent?(xml1, xml2,
+  verbose: true,
+  show_preprocessed_inputs: true
+)
+----
+
+**CLI usage:**
+[source,bash]
+----
+# Show what was actually compared
+$ canon diff file1.xml file2.xml --show-preprocessed-inputs
+
+# Preprocess with normalization and show what was compared
+$ canon diff file1.xml file2.xml --preprocessing normalize --show-preprocessed-inputs
+----
+
+**Environment variables:**
+[source,bash]
+----
+# Global (all formats)
+export CANON_SHOW_PROCESSED_INPUTS=true
+
+# Format-specific
+export CANON_XML_SHOW_PROCESSED_INPUTS=true
+export CANON_HTML_SHOW_PROCESSED_INPUTS=true
+export CANON_JSON_SHOW_PROCESSED_INPUTS=true
+export CANON_YAML_SHOW_PROCESSED_INPUTS=true
+----
+
+**Output format:**
+----
+=== PREPROCESSED INPUTS (Compared) ===
+Preprocessing: normalize
+
+EXPECTED:
+----------------------------------------------------------------------
+<root> hello world </root>
+
+RECEIVED:
+----------------------------------------------------------------------
+<root>hello world</root>
 
-Actual (as string):
+----
+
+==== Show line-numbered inputs
+
+Display raw inputs with line numbers (RSpec-style format). Useful for
+pinpointing specific lines when debugging.
+
+**Ruby API:**
+[source,ruby]
+----
+# Enable line-numbered input display in configuration
+Canon::Config.configure do |config|
+  config.xml.diff.show_line_numbered_inputs = true
+end
+
+# Or programmatically for a specific comparison
+result = Canon::Comparison.equivalent?(xml1, xml2,
+  verbose: true,
+  show_line_numbered_inputs: true
+)
+----
+
+**CLI usage:**
+[source,bash]
+----
+# Show raw inputs with line numbers (RSpec-style)
+$ canon diff file1.xml file2.xml --show-line-numbered-inputs
+----
+
+**Environment variables:**
+[source,bash]
+----
+# Global (all formats)
+export CANON_SHOW_LINE_NUMBERED_INPUTS=true
+
+# Format-specific
+export CANON_XML_SHOW_LINE_NUMBERED_INPUTS=true
+export CANON_HTML_SHOW_LINE_NUMBERED_INPUTS=true
+export CANON_JSON_SHOW_LINE_NUMBERED_INPUTS=true
+export CANON_YAML_SHOW_LINE_NUMBERED_INPUTS=true
+----
+
+**Output format:**
+----
+======================================================================
+  ORIGINAL INPUTS (with line numbers)
+======================================================================
+
+Expected:
      1 | <root>
-     2 |   <element>value2</element>
+     2 |   hello
      3 | </root>
 
-==================================================================
+Received:
+     1 | <root>hello world</root>
+
+======================================================================
 ----
 
-**When to use this feature:**
+==== Verbose diff (all input displays)
 
-* Debugging why two documents are considered different
-* Understanding preprocessing effects (c14n, normalization, etc.)
-* Verifying the exact input received by the comparison
-* Comparing raw vs processed content
+The `verbose_diff` option is a convenience flag that enables all three input
+display options at once. This is useful for maximum debugging output.
+
+**Ruby API:**
+[source,ruby]
+----
+# Enable all input displays in configuration
+Canon::Config.configure do |config|
+  config.xml.diff.verbose_diff = true
+end
 
-**Environment variable:**
+# Or programmatically for a specific comparison
+result = Canon::Comparison.equivalent?(xml1, xml2,
+  verbose: true,
+  verbose_diff: true
+)
+----
+
+**CLI usage:**
+[source,bash]
+----
+# Show all three input displays
+$ canon diff file1.xml file2.xml --verbose
+----
+
+**Environment variables:**
 [source,bash]
 ----
+# Format-specific
 export CANON_XML_DIFF_VERBOSE_DIFF=true
 export CANON_HTML_DIFF_VERBOSE_DIFF=true
 export CANON_JSON_DIFF_VERBOSE_DIFF=true
 export CANON_YAML_DIFF_VERBOSE_DIFF=true
 ----
 
+==== When to use each option
+
+`show_raw_inputs`::
+** You want to copy the expected output to paste into your test specs
+** You need to see the exact formatting/structure of your input files
+** You're debugging file reading/parsing issues
+
+`show_preprocessed_inputs`::
+** You want to understand what the comparison actually compared
+** You're debugging why two documents are considered equivalent (or not)
+** You need to trace the effect of preprocessing (c14n, normalize, format)
+
+`show_line_numbered_inputs`::
+** You need line numbers for pinpointing specific lines
+** You prefer the RSpec-style format
+** You're collaborating on debugging with others
+
+`verbose_diff`::
+** You want maximum debugging output (all three displays at once)
+** You're doing initial investigation of a complex comparison issue
+
 === Algorithm choice
 
 Canon provides two diff algorithms:
 
-* **DOM diff** (default): Stable, position-based comparison for traditional line-by-line output
-* **Semantic tree diff** (experimental): Advanced operation detection (INSERT, DELETE, UPDATE, MOVE, MERGE, SPLIT, UPGRADE, DOWNGRADE)
+DOM diff (default):: Stable, position-based comparison for traditional
+line-by-line output
+
+Semantic tree diff (experimental):: Advanced operation detection (INSERT,
+DELETE, UPDATE, MOVE, MERGE, SPLIT, UPGRADE, DOWNGRADE)
 
 [source,ruby]
 ----