canon 0.2.11 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8fcacddf719d0cb69472bc55b2a23d724c938fdf76f995eb77be962aeda42182
-  data.tar.gz: 3a1d14c811209e8353c7539d12c2f7a4d23d44c1e6742b6f48a8d94f65282bd5
+  metadata.gz: 0d1f4de27225e068e0bc1a00b2b7b2d980847bf9027a21f042de148aae65926e
+  data.tar.gz: 4561eaa1efb9abcd541ec8da05f2e33df11859c35d6e5fe3f5fee9fa9d22af3d
 SHA512:
-  metadata.gz: f4685b05d13d6cedad780751a8011a722511a9a5623a3a3fa14ce548b95d036c8fd36cabb10d8793ede0a97cf5a1e72d8f53729022c90c8b316c510dc133983e
-  data.tar.gz: 5201625d93a1ed9c2efb929905c1d14f4a292e914604149f8e5902a61d1ea6059b987c8875b073ec71340adb1833a33bbce450f58006f29736a37d810f326d6d
+  metadata.gz: ee29ec80689f0c53771017dca13d48ba4c3162db98f0e3605c3198148035cd564d818b8e4c08728608ef3abd055231d82850f79f933d2206ec4a36d488c6faa6
+  data.tar.gz: 37ae2bd7e928265b8c54e4025ae73d7e8761ce6e28ee2933e005129bd218d7003a5d547103bba140e11e829ef4d45aa7ef41768766b302f6608814f08fb74983

data/.rubocop_todo.yml

@@ -1,6 +1,6 @@
 # This configuration was generated by
-# `rubocop --auto-gen-config --no-auto-gen-timestamp`
-# using RuboCop version 1.86.0.
+# `rubocop --auto-gen-config`
+# on 2026-08-27 03:37:16 UTC using RuboCop version 1.90.0.
 # 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
@@ -11,14 +11,44 @@ Gemspec/RequiredRubyVersion:
   Exclude:
     - 'canon.gemspec'
 
-# Offense count: 1357
+# Offense count: 6
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowForAlignment, AllowBeforeTrailingComments, ForceEqualSignAlignment.
+Layout/ExtraSpacing:
+  Exclude:
+    - 'lib/canon/diff_formatter/theme.rb'
+    - 'lib/tasks/performance_report.rb'
+
+# Offense count: 4
+# 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:
+    - 'lib/tasks/performance_report.rb'
+
+# Offense count: 1267
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
-# Offense count: 58
+# Offense count: 4
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowInHeredoc.
+Layout/TrailingWhitespace:
+  Exclude:
+    - 'lib/tasks/performance_report.rb'
+
+# Offense count: 1
+Lint/CopDirectiveSyntax:
+  Exclude:
+    - 'lib/canon/comparison/comparison_result.rb'
+
+# Offense count: 57
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
   Enabled: false
@@ -32,7 +62,7 @@ Lint/EmptyConditionalBody:
     - 'spec/canon/comparison_spec.rb'
 
 # Offense count: 5
-# Configuration parameters: MaximumRangeSize.
+# Configuration parameters: MaxRangeSize.
 Lint/MissingCopEnableDirective:
   Exclude:
     - 'lib/canon/commands/format_command.rb'
@@ -62,12 +92,12 @@ Lint/UselessConstantScoping:
   Exclude:
     - 'lib/canon/diff_formatter/theme.rb'
 
-# Offense count: 316
+# Offense count: 296
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
 
-# Offense count: 29
+# Offense count: 28
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
@@ -78,12 +108,12 @@ Metrics/BlockLength:
 Metrics/BlockNesting:
   Max: 4
 
-# Offense count: 276
+# Offense count: 262
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 527
+# Offense count: 501
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 146
@@ -93,12 +123,12 @@ Metrics/MethodLength:
 Metrics/ParameterLists:
   Max: 10
 
-# Offense count: 214
+# Offense count: 207
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
 
-# Offense count: 30
+# 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:
@@ -115,16 +145,6 @@ Naming/PredicateMethod:
   Exclude:
     - 'spec/canon/comparison/xml_attribute_diff_spec.rb'
 
-# 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: 4
 # Configuration parameters: MinSize.
 Performance/CollectionLiteralInLoop:
@@ -134,7 +154,7 @@ Performance/CollectionLiteralInLoop:
     - 'lib/canon/xml/xml_base_handler.rb'
     - 'spec/canon/diff/diff_node_mapper_comments_spec.rb'
 
-# Offense count: 107
+# Offense count: 111
 # Configuration parameters: Prefixes, AllowedPatterns.
 # Prefixes: when, with, without
 RSpec/ContextWording:
@@ -151,7 +171,7 @@ RSpec/DescribeMethod:
     - 'spec/canon/comparison/multiple_differences_spec.rb'
     - 'spec/canon/diff_formatter/character_map_customization_spec.rb'
 
-# Offense count: 893
+# Offense count: 916
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 44
@@ -203,11 +223,11 @@ RSpec/MultipleDescribes:
   Exclude:
     - 'spec/canon/comparison/match_options_spec.rb'
 
-# Offense count: 749
+# Offense count: 783
 RSpec/MultipleExpectations:
   Max: 15
 
-# Offense count: 93
+# Offense count: 92
 # Configuration parameters: AllowSubject.
 RSpec/MultipleMemoizedHelpers:
   Max: 16
@@ -267,6 +287,23 @@ RSpec/VerifiedDoubles:
     - 'spec/canon/diff_formatter/diff_detail_formatter_spec.rb'
     - 'spec/canon/tree_diff/operation_converter_spec.rb'
 
+# Offense count: 13
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Style/DirectiveScope:
+  Exclude:
+    - 'lib/canon.rb'
+    - 'lib/canon/commands/diff_command.rb'
+    - 'lib/canon/comparison/comparison_result.rb'
+    - 'lib/canon/diff_formatter.rb'
+    - 'lib/canon/diff_formatter/by_line/base_formatter.rb'
+    - 'lib/canon/diff_formatter/by_line/html_formatter.rb'
+    - 'lib/canon/diff_formatter/by_line_formatter.rb'
+    - 'spec/canon/comparison/xml_comparator_spec.rb'
+    - 'spec/canon/comparison_spec.rb'
+    - 'spec/canon/diff_formatter/formatting_diff_visualization_spec.rb'
+    - 'spec/canon/fixtures_integrity_spec.rb'
+    - 'spec/canon/string_matcher_spec.rb'
+
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, AllowComments.

data/CLAUDE.md

@@ -0,0 +1,197 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Overview
+
+Canon is a canonicalization, formatting, and comparison library for serialization formats (XML, HTML, JSON, YAML). It produces standardized forms suitable for comparison, testing, digital signatures, and human-readable output.
+
+## Common Commands
+
+```bash
+# Install dependencies
+bundle install
+
+# Run all tests
+bundle exec rake spec        # or: bundle exec rspec
+
+# Run a single test file
+bundle exec rspec spec/canon/comparison/xml_comparator_spec.rb
+
+# Run tests with specific pattern
+bundle exec rspec spec/canon/comparison --tag focus
+
+# Lint (rubocop)
+bundle exec rake rubocop
+
+# Default task (runs tests + lint)
+bundle exec rake
+
+# Performance benchmarks (takes ~5 minutes)
+bundle exec rake performance:run
+
+# Quick benchmark (~30 seconds)
+bundle exec rake performance:quick
+```
+
+### Size Limits
+
+Canon protects against pathologically large files with configurable limits:
+- **File size**: Default 5MB (`CANON_MAX_FILE_SIZE`)
+- **Node count**: Default 10,000 (`CANON_MAX_NODE_COUNT`)
+- **Diff output**: Default 10,000 lines (`CANON_MAX_DIFF_LINES`)
+
+```bash
+export CANON_MAX_FILE_SIZE=10485760  # 10MB
+export CANON_MAX_NODE_COUNT=50000
+bundle exec rspec
+```
+
+## Architecture
+
+### Core Entry Points
+
+- `lib/canon.rb` — Main module entry point. Provides `Canon.format`, `Canon.parse`, and shorthand methods like `Canon.format_xml`, `Canon.parse_json`. Defines `SUPPORTED_FORMATS = [:xml, :yaml, :json, :html, :html4, :html5, :string]`.
+- `lib/canon/cli.rb` — Thor-based CLI. Two commands: `canon format` (canonicalize/pretty-print) and `canon diff` (semantic comparison). See CLI long descriptions for full option documentation.
+- `exe/canon` — CLI entry point (runs the Thor CLI).
+
+### Two Comparison Algorithms — Distinct by Design
+
+Canon provides two **fundamentally different** comparison algorithms. They are NOT alternative implementations of the same approach. They use different methods, accept different options, produce different intermediate representations, and solve different problems. The pipelines must never be merged or "unified."
+
+#### DOM Algorithm (`diff_algorithm: :dom`, default)
+
+Position-based recursive tree walk. Compares children by position, attributes by name, namespace by URI.
+
+- **Method**: Positional recursive descent through the DOM tree
+- **Code path**: `dom_diff` → format comparators (`XmlComparator`, `HtmlComparator`, `JsonComparator`, `YamlComparator`)
+- **Algorithm-specific options**: Filtering (`ignore_children`, `ignore_text_nodes`, `ignore_attrs`, `ignore_nodes`, `ignore_attr_content`, `diff_children`)
+- **Intermediate representation**: Integer comparison-result codes (EQUIVALENT, MISSING_NODE, UNEQUAL_TEXT_CONTENTS, etc.)
+- **Output**: DiffNodes with diff codes
+- **Strength**: Deterministic positional comparison with fine-grained filtering; O(n) performance
+- **Location**: `lib/canon/comparison/`
+
+#### Semantic Tree Algorithm (`diff_algorithm: :semantic`)
+
+Signature-based tree matching. Computes node signatures, uses hash matching + similarity matching + structural propagation to find node correspondences even when nodes have moved. Produces insert/update/delete/move operations.
+
+- **Method**: Signature computation → three-phase matching (hash, similarity, structural propagation) → operation detection
+- **Code path**: `semantic_diff` → `TreeDiffIntegrator` → format adapters → `OperationConverter` → DiffNodes
+- **Algorithm-specific options**: Matching strategy (`similarity_threshold`, `hash_matching`, `similarity_matching`, `propagation`)
+- **Intermediate representation**: Operations (INSERT, DELETE, UPDATE, MOVE)
+- **Output**: Operations → converted to DiffNodes
+- **Strength**: Detects moved/renamed nodes and structural reorganization
+- **Location**: `lib/canon/tree_diff/`
+
+#### Shared Infrastructure (safe to consolidate)
+
+Both algorithms share these pipeline steps — this is the ONLY layer where consolidation makes sense:
+- Format detection (`FormatDetector`)
+- Config resolution (`Canon::Config`)
+- Match option resolution (`MatchOptions` resolvers, profiles, dimensions)
+- Preprocessing (`:none`, `:c14n`, `:normalize`, `:format`)
+- Parsing (format-specific `.parse` methods)
+- DiffNode output format — both produce DiffNodes
+- Diff formatting (`by_line` / `by_object`) — both feed into the same formatters
+
+#### NOT Shared (do NOT merge)
+
+- The comparison engines are entirely separate codepaths with no shared comparison logic
+- DOM-specific filtering options (`ignore_*`) have no meaning in semantic matching
+- Semantic-specific matching options (`similarity_threshold`, `hash_matching`) have no meaning in DOM comparison
+- Intermediate representations differ: diff codes vs tree-matching operations
+
+#### Two Activation Paths
+
+Semantic diff can be activated two ways:
+1. `diff_algorithm: :semantic` — caught by `Comparison.equivalent?`, routes to `Comparison.semantic_diff` (owns full pipeline end-to-end)
+2. `match: { semantic_diff: true }` — passes through `dom_diff` to the format comparator, which detects the flag and calls its own `perform_semantic_tree_diff`
+
+Path 1 is the primary API. Path 2 exists for direct comparator calls and is tested in `spec/canon/tree_diff/canon_integration_spec.rb`.
+
+### Four-Layer Architecture
+
+The comparison pipeline flows through four independent layers:
+
+1. **Preprocessing** — Optional normalization (`:none`, `:c14n`, `:normalize`, `:format`)
+2. **Algorithm Selection** — `:dom` (position-based, stable) or `:semantic` (signature-based, experimental)
+3. **Match Options** — Dimension behaviors per format (`:text_content`, `:structural_whitespace`, `:attribute_values`, etc.) controlled via profiles (`:strict`, `:spec_friendly`, `:rendered`, `:content_only`)
+4. **Diff Formatting** — `by_line` or `by_object` output mode
+
+**Critical distinction**: Do NOT use `Canon.format_xml` output for string comparison in tests. The formatting process changes line counts and causes false failures. Use `Canon::Comparison.equivalent?` or RSpec matchers instead.
+
+### Key Modules
+
+- `lib/canon/comparison/` — DOM-based comparison logic. `comparison.rb` is the main facade; comparators live in submodules. `MatchOptions::Xml` defines profiles (`:strict`, `:spec_friendly`, `:rendered`, `:content_only`) and per-dimension behaviors.
+- `lib/canon/tree_diff/` — Semantic tree diff engine. Separate from the DOM comparators. Integrates back into the main pipeline via `OperationConverter`.
+- `lib/canon/diff_formatter/` — Output formatters for diff results. Two modes: `by_line` (line-by-line, used for HTML and strings) and `by_object` (semantic/object-level, used for XML/JSON/YAML). Contains format-specific formatters for XML, HTML, JSON, YAML output.
+- `lib/canon/formatters/` — Pretty-printers for canonicalization/formatting (distinct from diff formatters). `XmlFormatter` supports Canonical XML (C14N).
+- `lib/canon/config.rb` — Global configuration with per-format settings (profiles, preprocessing, diff options). Read at runtime via `Canon::Config.instance`.
+- `lib/canon/rspec_matchers.rb` — RSpec matchers (`be_xml_equivalent_to`, `be_json_equivalent_to`, etc.). These delegate to `Canon::Comparison.equivalent?` with the global config. Automatically included in RSpec.
+- `lib/canon/xml/sax_builder.rb` — SAX-based canon-tree builder (~6x faster than DOM parsing for large documents). Engine-neutral; `lib/canon/xml/sax.rb` selects the driver (`NokogiriDriver` on CRuby, `MoxmlDriver` under Opal).
+
+### XML Engines
+
+Canon is engine-agnostic across three seams (MECE — one concern per module):
+
+- `Canon::XmlBackend` — XML engine selection. The default follows moxml's resolved adapter: **leptris whenever it is installed** (parse ~1.6x, serialize ~3.8x vs Nokogiri), raw Nokogiri otherwise (wrapping Nokogiri in moxml buys nothing — the wrapper adds 2-3x overhead). `:moxml` under Opal. `CANON_XML_BACKEND=nokogiri|moxml` forces either engine.
+- `Canon::XmlParsing` — the only place that talks to engines for XML parse/serialize (moxml parses pass `readonly: true` — canon never mutates engine documents); node type queries answer for ANY recognized node (Nokogiri or moxml) by type, never by active backend — user-supplied Nokogiri nodes keep working under the moxml engine.
+- `Canon::Html::NokogiriSupport` — HTML is always Nokogiri on CRuby (moxml has no HTML adapter, leptris no HTML parser); independent of the XML engine.
+- `Canon::Xml::Sax` — SAX driver selection: `NokogiriDriver` on CRuby (per-event C callbacks beat FFI SAX today), `MoxmlDriver` under Opal. The builder (`SaxBuilder`) is engine-neutral.
+
+Engine parity is complete through libleptris 1.9.8 / leptris-ruby 1.9.33 / moxml 0.5.12: attribute-value normalization, prolog/epilog PIs and comments, DTD ATTLIST defaults off by default (opt-in via `ParseOptions::DTDATTR`), PI-data whitespace matching libxml2, materialize with namespace declarations and a root-subtree-only record contract (moxml#140), readonly parse, deterministic `Document#free` (wired into `from_moxml_xml` — moxml#134). Canon's moxml conversion is record-based (`build_from_moxml` consumes `materialize` records — no per-node wrapper allocation; ~0.55x the Nokogiri conversion). `spec/canon/xml/engine_parity_spec.rb` is fully green. Remaining product gaps: moxml#129 (serializer byte parity — last blocker for pretty-printing on leptris) and leptris#594 (SAX at parity, not faster — the SAX driver stays Nokogiri). Pretty-printers (`PrettyPrinter::Xml`, `XmlNormalized`) deliberately stay on the Nokogiri pipeline — pretty-printed bytes are canon's product.
+
+Engine A/B testing: `CANON_XML_BACKEND=nokogiri bundle exec rspec` (or `=moxml` to force leptris when it isn't the resolved default). The default suite must stay green under BOTH values; the only expected pendings are the upstream-tracked ones. The benchmark header (`rake performance:quick`) reports the active engine.
+
+### Format Detection
+
+`Canon::Comparison::FormatDetector` auto-detects format from string content or object type (Moxml::Node → XML, Nokogiri::HTML → HTML, Hash → JSON, etc.). HTML4 vs HTML5 is determined by DOCTYPE.
+
+### Difference Result Format
+
+When `verbose: true`, comparison returns `Canon::Comparison::ComparisonResult` (or legacy Hash/Array). The result exposes:
+- `differences` — array of `DiffNode` objects
+- `equivalent?` — boolean
+- `preprocessed_strings` / `original_strings` — for diff display
+- `tree_diff_operations` / `tree_diff_statistics` / `tree_diff_matching` — only when using semantic algorithm
+
+### Difference Classification
+
+Differences are classified into three tiers:
+- **Normative** — Affects equivalence (documents not equivalent if different)
+- **Informative** — Tracked but doesn't affect equivalence
+- **Formatting-only** — Pure whitespace/formatting differences when normalized content matches
+
+Use `show_diffs: :normative` to display only equivalence-affecting differences.
+
+### Testing Notes
+
+- Tests use a shared fixture system (`spec/canon/fixtures/`). `spec/canon/fixtures_integrity_spec.rb` validates fixture references.
+- `spec/spec_helper.rb` disables monkey-patching and uses `expect` syntax.
+- Specs named `*_spec.rb` under `spec/canon/` map to `lib/canon/`.
+
+## Architectural Rules
+
+These rules are non-negotiable. Violations must be fixed before merge.
+
+### No `respond_to?` — use proper types
+
+`respond_to?` is a type-system bypass. It means the code does not know what it is working with, which is a failure of the model. Every object flowing through the comparison pipeline is one of a known set of types (`Canon::Xml::Node` and subclasses, `Nokogiri::XML::Node` and subclasses, `ComparisonResult`, `DiffNode`, `Hash`, `String`). Use `is_a?` for type dispatch, or better yet, design the classes so that polymorphism handles dispatch automatically (e.g., a shared base class or module providing the same interface).
+
+If you find yourself writing `respond_to?`, stop and introduce a proper type check or a shared protocol instead.
+
+### No `send` to bypass visibility — make the method public
+
+Using `send` to call a private method from another module or class is an encapsulation violation. If another object needs to call a method, that method must be public. Private means "internal implementation detail of this class" — if it is needed externally, it is not private. Either make it public or rethink the boundary.
+
+### No duplicated type-checking logic
+
+Backend-agnostic node queries (text node?, text content, whitespace check) must live in one place. The `Canon::Comparison::NodeInspector` module provides a single source of truth for cross-backend node type operations. All code that needs to query node properties must use it — never re-implement type dispatch inline.
+
+### Single module for cross-cutting utilities
+
+When multiple modules need the same capability (e.g., checking if a node is a whitespace-only text node), extract a single utility module. Do not duplicate the logic in each consumer.
+
+### Two algorithm pipelines must remain separate
+
+DOM and Semantic comparison are fundamentally different algorithms with different option sets, different intermediate representations, and different codepaths. Proposals to "unify" or "merge" the algorithm pipelines are always wrong. The correct approach is to extract shared infrastructure (format detection, config, parsing, output formatting) into reusable methods while keeping the algorithm cores independent. See "Two Comparison Algorithms — Distinct by Design" above.

data/Rakefile

@@ -24,7 +24,9 @@ begin
     end
 
     # REXML: bundled gem since Ruby 3.4
-    rexml_lib = $LOAD_PATH.find { |p| File.exist?(File.join(p, "rexml", "document.rb")) }
+    rexml_lib = $LOAD_PATH.find do |p|
+      File.exist?(File.join(p, "rexml", "document.rb"))
+    end
     Opal.append_path rexml_lib if rexml_lib
   end
 rescue LoadError
@@ -42,7 +44,8 @@ namespace :spec do
     desc "Run Opal (JavaScript) tests"
     Opal::RSpec::RakeTask.new(:opal) do |_server, runner|
       runner.default_path = "spec"
-      runner.requires = %w[rexml_compat rexml/document rexml/xpath moxml/adapter/rexml spec_helper]
+      runner.requires = %w[rexml_compat rexml/document rexml/xpath
+                           moxml moxml/adapter/rexml spec_helper]
       runner.pattern = "spec/canon/opal_xml_smoke_spec.rb"
     end
   end

data/lib/canon/cache.rb

@@ -101,7 +101,9 @@ module Canon
           Digest::SHA256.hexdigest(content)[0..16]
         else
           # Opal fallback: simple string hash
-          h = content.each_char.reduce(0) { |acc, c| ((acc * 31) + c.ord) & 0xFFFFFFFF }
+          h = content.each_char.reduce(0) do |acc, c|
+            ((acc * 31) + c.ord) & 0xFFFFFFFF
+          end
           h.to_s(16).rjust(8, "0")
         end
       end

data/lib/canon/cli.rb

@@ -1,9 +1,6 @@
 # frozen_string_literal: true
 
 require "thor" unless RUBY_ENGINE == "opal"
-require_relative "commands/format_command"
-require_relative "commands/diff_command"
-require_relative "options/registry"
 
 module Canon
   # Command-line interface for Canon

data/lib/canon/commands/diff_command.rb

@@ -1,8 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "../comparison"
-require_relative "../diff_formatter"
-require_relative "../color_detector"
 require "json"
 require "yaml"
 
@@ -15,7 +12,7 @@ module Canon
       end
 
       # rubocop:disable Metrics/MethodLength
-      # rubocop:disable Metrics/AbcSize
+      # rubocop:disable-next Metrics/AbcSize
       def run(file1, file2)
         # Detect formats
         format1 = @options[:format1] || @options[:format] || detect_format(file1)
@@ -66,7 +63,6 @@ module Canon
 
         # Show configuration in verbose mode using shared DebugOutput
         if @options[:verbose]
-          require_relative "../diff_formatter/debug_output"
           config_output = Canon::DiffFormatter::DebugOutput.verbose_tables_only(
             result,
             {
@@ -102,7 +98,6 @@ module Canon
       rescue StandardError => e
         abort "Error processing files: #{e.message}"
       end
-      # rubocop:enable Metrics/AbcSize
       # rubocop:enable Metrics/MethodLength
 
       private
@@ -219,12 +214,10 @@ module Canon
 
         case format
         when :xml
-          require_relative "../pretty_printer/xml"
           formatted1 = Canon::PrettyPrinter::Xml.new(indent: 2).format(content1)
           formatted2 = Canon::PrettyPrinter::Xml.new(indent: 2).format(content2)
           [formatted1, formatted2]
         when :html
-          require_relative "../pretty_printer/html"
           formatted1 = Canon::PrettyPrinter::Html.new(indent: 2).format(content1)
           formatted2 = Canon::PrettyPrinter::Html.new(indent: 2).format(content2)
           [formatted1, formatted2]

data/lib/canon/commands/format_command.rb

@@ -1,9 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "../pretty_printer/xml"
-require_relative "../pretty_printer/json"
-require_relative "../pretty_printer/html"
-
 module Canon
   module Commands
     # Command for canonicalizing files

data/lib/canon/commands.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Canon
+  # Thor command implementations invoked by {CLI}. Children are autoloaded.
+  module Commands
+    autoload :DiffCommand, "canon/commands/diff_command"
+    autoload :FormatCommand, "canon/commands/format_command"
+  end
+end

data/lib/canon/comparison/child_realignment.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require_relative "node_inspector"
-
 module Canon
   module Comparison
     # Shared two-cursor walk over child arrays with noise-aware realignment.

data/lib/canon/comparison/compare_profile.rb

@@ -3,7 +3,7 @@
 module Canon
   module Comparison
     # CompareProfile encapsulates the policy decisions about how differences
-    # in various dimensions should be handled during comparison
+    # in various dimensions should be handled during comparison.
     #
     # This class provides separation of concerns:
     # - CompareProfile: Policy decisions (what to track, what affects equivalence)
@@ -17,69 +17,46 @@ module Canon
         @match_options = match_options
       end
 
-      # Should DiffNodes be created for differences in this dimension?
-      #
-      # In verbose mode, we want to track ALL differences for reporting.
-      # In non-verbose mode, we only need to track normative differences.
-      #
-      # @param dimension [Symbol] The match dimension to check
-      # @return [Boolean] true if differences should be tracked
       def track_dimension?(_dimension)
-        # Always track dimensions that affect equivalence
-        # In verbose mode, also track informative dimensions
         true
       end
 
       # Should differences in this dimension affect equivalence?
       #
-      # This determines the return value of the comparison:
-      # - true: differences make documents non-equivalent
-      # - false: differences are informative only
-      #
       # @param dimension [Symbol] The match dimension to check
       # @return [Boolean] true if differences affect equivalence
       def affects_equivalence?(dimension)
         behavior = behavior_for(dimension)
-
-        # :strict → affects equivalence
-        # :normalize → might affect (if normalization fails)
-        # :ignore → does NOT affect equivalence
         behavior != :ignore
       end
 
       # Is a difference in this dimension normative (affects equivalence)?
       #
-      # This is used by DiffClassifier to determine the normative flag.
-      #
-      # Normative rules by dimension:
-      # - structural_whitespace: only :strict is normative (:normalize and :ignore are informative)
-      # - all other dimensions: normative unless behavior is :ignore
+      # Delegates to the Dimension object's normative? rule.  Falls back to
+      # the default rule (normative unless :ignore) for dimensions not in the
+      # format's dimension set (e.g., derived dimensions like :element_structure).
       #
       # @param dimension [Symbol] The match dimension to check
       # @return [Boolean] true if normative, false if informative
       def normative_dimension?(dimension)
-        # Structural whitespace with :normalize or :ignore behavior is INFORMATIVE
-        # Only :strict mode makes whitespace normative
-        if dimension == :structural_whitespace
-          behavior = behavior_for(dimension)
-          return behavior == :strict
+        dim = dimension_for(dimension)
+        if dim
+          dim.normative?(behavior_for(dimension))
+        else
+          behavior_for(dimension) != :ignore
         end
-
-        # For all other dimensions, normative if behavior affects equivalence
-        affects_equivalence?(dimension)
       end
 
       # Can a difference in this dimension be formatting-only?
       #
-      # This determines whether FormattingDetector should be applied.
-      # Only text/content dimensions can have formatting-only differences.
+      # Delegates to the Dimension object's supports_formatting_detection?
+      # flag.  Falls back to false for unknown dimensions.
       #
       # @param dimension [Symbol] The match dimension to check
       # @return [Boolean] true if formatting detection should apply
       def supports_formatting_detection?(dimension)
-        # Only text_content and structural_whitespace can have formatting-only diffs
-        # Comments are policy-based (strict/ignore), not formatting-based
-        %i[text_content structural_whitespace].include?(dimension)
+        dim = dimension_for(dimension)
+        dim ? dim.supports_formatting_detection? : false
       end
 
       # Get the behavior setting for a dimension
@@ -94,6 +71,23 @@ module Canon
           :strict
         end
       end
+
+      private
+
+      def dimension_for(name)
+        set = Dimensions::Registry.for(extract_format)
+        set[name]
+      end
+
+      def extract_format
+        if match_options.is_a?(ResolvedMatchOptions)
+          match_options.format
+        elsif match_options.is_a?(Hash)
+          match_options[:format]
+        else
+          :xml
+        end
+      end
     end
   end
 end

data/lib/canon/comparison/comparison_result.rb

@@ -133,8 +133,6 @@ parse_errors_expected: nil, parse_errors_received: nil)
       # @return [String] Formatted diff output
       def diff(use_color: true, context_lines: 3, diff_grouping_lines: nil,
 show_diffs: :all, diff_mode: :separate, legacy_terminal: false)
-        require_relative "../diff_formatter"
-
         formatter = Canon::DiffFormatter.new(
           use_color: use_color,
           mode: :by_line,
@@ -164,13 +162,12 @@ show_diffs: :all, diff_mode: :separate, legacy_terminal: false)
       def summarize_diff_node(diff)
         parts = ["Not equivalent:"]
 
-        # rubocop:disable Layout/SpaceBeforeInterpolation,Style/ConditionalAssignment
+        # rubocop:disable-next Layout/SpaceBeforeInterpolation,Style/ConditionalAssignment
         if diff.path
           parts << "#{diff.reason} at #{diff.path}"
         else
           parts << diff.reason.to_s
         end
-        # rubocop:enable Layout/SpaceBeforeInterpolation,Style/ConditionalAssignment
 
         if diff.serialized_before && diff.serialized_after
           before_preview = truncate_preview(diff.serialized_before)