canon 0.1.6 → 0.1.7

data/docs/{RSPEC.adoc → interfaces/rspec/index.adoc}

@@ -1,8 +1,9 @@
 ---
 layout: default
 title: RSpec Matchers
-nav_order: 12
-parent: Basic Usage
+parent: Interfaces
+nav_order: 3
+has_children: true
 ---
 = Canon RSpec matchers
 :toc:
@@ -14,9 +15,9 @@ This document describes how to use Canon's RSpec matchers for testing. Canon
 provides semantic comparison matchers that focus on content rather than
 formatting.
 
-For Ruby API usage, see link:RUBY_API[Ruby API documentation].
+For Ruby API usage, see link:../ruby-api/[Ruby API documentation].
 
-For command-line usage, see link:CLI[CLI documentation].
+For command-line usage, see link:../cli/[CLI documentation].
 
 == General
 
@@ -147,7 +148,7 @@ end
 
 Available profiles: `:strict`, `:rendered`, `:spec_friendly`, `:content_only`
 
-See link:MATCH_OPTIONS[Match options] for profile details.
+See link:../../features/match-options/[Match options] for profile details.
 ====
 
 .Match dimension options
@@ -175,7 +176,7 @@ Canon::RSpecMatchers.configure do |config|
 end
 ----
 
-See link:MATCH_OPTIONS[Match options] for dimension reference.
+See link:../../features/match-options/[Match options] for dimension reference.
 ====
 
 === Diff configuration
@@ -200,7 +201,7 @@ Canon::RSpecMatchers.configure do |config|
 end
 ----
 
-See link:MODES[Diff modes] for mode details.
+See link:../../understanding/diff-modes/[Diff modes] for mode details.
 ====
 
 .Diff formatting
@@ -221,7 +222,7 @@ Canon::RSpecMatchers.configure do |config|
 end
 ----
 
-See link:DIFF_FORMATTING[Diff formatting] for options.
+See link:../../features/diff-formatting/[Diff formatting] for options.
 ====
 
 === Complete configuration example
@@ -339,7 +340,7 @@ end
 ----
 ====
 
-== Verbose output
+=== Verbose output
 
 Use `verbose: true` to show detailed diff output on test failures.
 
@@ -371,14 +372,238 @@ end
 ----
 ====
 
+=== Display filtering
+
+Use `.show_diffs()` to control which differences appear in failure output.
+
+.Display filtering modes
+[example]
+====
+[source,ruby]
+----
+RSpec.describe 'Display filtering' do
+  it 'shows all differences (default)' do
+    expect(actual_xml).to be_xml_equivalent_to(expected_xml)
+      .show_diffs(:all)
+  end
+
+  it 'shows only normative differences' do
+    # Only show differences that affect equivalence
+    expect(actual_xml).to be_xml_equivalent_to(expected_xml)
+      .show_diffs(:normative)
+  end
+
+  it 'shows only informative differences' do
+    # Only show differences that don't affect equivalence
+    expect(actual_xml).to be_xml_equivalent_to(expected_xml,
+      match: { comments: :ignore }
+    ).show_diffs(:informative)
+  end
+end
+----
+====
+
+.Combining with match options
+[example]
+====
+[source,ruby]
+----
+RSpec.describe 'Combined filtering' do
+  it 'ignores comments but shows only normative diffs' do
+    expect(actual_xml).to be_xml_equivalent_to(expected_xml)
+      .with_options(comments: :ignore)
+      .show_diffs(:normative)
+  end
+
+  it 'uses spec_friendly profile with normative filtering' do
+    expect(actual_xml).to be_xml_equivalent_to(expected_xml)
+      .with_profile(:spec_friendly)
+      .show_diffs(:normative)
+  end
+end
+----
+====
+
+IMPORTANT: Display filtering does NOT affect equivalence determination. It
+only controls which differences appear in the failure output. Equivalence is
+always based on normative differences only.
+
+See link:../../features/diff-formatting/display-filtering.adoc[Display
+filtering] for complete details.
+
+== Diff algorithms
+
+Canon supports two diff algorithms that can be selected based on your needs:
+
+* **`:dom`** (default): Positional, DOM-based matching
+* **`:semantic`**: Tree-based matching with operation detection
+
+=== DOM algorithm
+
+The DOM algorithm performs positional matching and is the default behavior:
+
+.DOM algorithm usage
+[example]
+====
+[source,ruby]
+----
+RSpec.describe 'DOM algorithm' do
+  it 'uses positional matching by default' do
+    expect(actual_xml).to be_xml_equivalent_to(expected_xml)
+  end
+
+  it 'explicitly specifies DOM algorithm' do
+    expect(actual_xml).to be_xml_equivalent_to(expected_xml,
+      diff_algorithm: :dom,
+      verbose: true
+    )
+  end
+end
+----
+====
+
+=== Semantic algorithm
+
+The semantic algorithm uses tree-based matching and detects operations like
+insert, delete, update, move, merge, and split:
+
+.Semantic algorithm usage
+[example]
+====
+[source,ruby]
+----
+RSpec.describe 'Semantic algorithm' do
+  it 'detects semantic operations' do
+    xml1 = '<root><a>1</a><b>2</b></root>'
+    xml2 = '<root><b>2</b><a>1</a><c>3</c></root>'
+
+    expect(xml1).to be_xml_equivalent_to(xml2,
+      diff_algorithm: :semantic,
+      verbose: true
+    )
+  end
+
+  it 'identifies element moves' do
+    html1 = '<div><p>First</p><p>Second</p></div>'
+    html2 = '<div><p>Second</p><p>First</p></div>'
+
+    expect(html1).to be_html_equivalent_to(html2,
+      diff_algorithm: :semantic,
+      verbose: true
+    )
+  end
+
+  it 'detects insertions and deletions' do
+    json1 = '{"users": [{"id": 1}, {"id": 2}]}'
+    json2 = '{"users": [{"id": 1}, {"id": 2}, {"id": 3}]}'
+
+    expect(json1).to be_json_equivalent_to(json2,
+      diff_algorithm: :semantic,
+      verbose: true
+    )
+  end
+end
+----
+====
+
+=== Global algorithm configuration
+
+Configure the diff algorithm globally:
+
+.Global diff algorithm configuration
+[example]
+====
+[source,ruby]
+----
+# spec_helper.rb
+Canon::RSpecMatchers.configure do |config|
+  # Use semantic algorithm for XML by default
+  config.xml.diff.algorithm = :semantic
+
+  # Use DOM algorithm for HTML (default)
+  config.html.diff.algorithm = :dom
+
+  # Use semantic algorithm for JSON
+  config.json.diff.algorithm = :semantic
+end
+----
+====
+
+=== Per-test algorithm override
+
+Override the global algorithm configuration for specific tests:
+
+.Per-test algorithm override
+[example]
+====
+[source,ruby]
+----
+RSpec.describe 'Algorithm override' do
+  # Global config uses :semantic
+  # But this test uses :dom
+  it 'uses DOM algorithm for this specific test' do
+    expect(actual_xml).to be_xml_equivalent_to(expected_xml,
+      diff_algorithm: :dom,
+      verbose: true
+    )
+  end
+
+  # Global config uses :dom
+  # But this test uses :semantic
+  it 'uses semantic algorithm to detect operations' do
+    expect(actual_html).to be_html_equivalent_to(expected_html,
+      diff_algorithm: :semantic,
+      verbose: true
+    )
+  end
+end
+----
+====
+
+=== Combining algorithm with other options
+
+The diff algorithm can be combined with match profiles and options:
+
+.Algorithm with profiles and options
+[example]
+----
+RSpec.describe 'Combined configuration' do
+  it 'uses semantic algorithm with spec_friendly profile' do
+    expect(actual_xml).to be_xml_equivalent_to(expected_xml,
+      diff_algorithm: :semantic,
+      verbose: true
+    )
+      .with_profile(:spec_friendly)
+  end
+
+  it 'uses semantic algorithm with custom match options' do
+    expect(actual_xml).to be_xml_equivalent_to(expected_xml,
+      diff_algorithm: :semantic,
+      verbose: true
+    )
+      .with_options(
+        structural_whitespace: :ignore,
+        comments: :ignore
+      )
+  end
+
+  it 'uses DOM algorithm with strict matching' do
+    expect(actual_html).to be_html_equivalent_to(expected_html,
+      diff_algorithm: :dom,
+      verbose: true
+    )
+      .with_profile(:strict)
+  end
+end
+----
+====
+
 == Common patterns
 
 === Testing XML generation
 
 .XML generation tests
 [example]
-====
-[source,ruby]
 ----
 RSpec.describe 'XML generation' do
   let(:expected_xml) do
@@ -414,8 +639,6 @@ end
 
 .HTML output tests
 [example]
-====
-[source,ruby]
 ----
 RSpec.describe 'HTML generation' do
   let(:expected_html) do
@@ -462,8 +685,6 @@ end
 
 .JSON API tests
 [example]
-====
-[source,ruby]
 ----
 RSpec.describe 'API responses' do
   let(:expected_response) do
@@ -498,8 +719,6 @@ end
 
 .Configuration file tests
 [example]
-====
-[source,ruby]
 ----
 RSpec.describe 'Configuration files' do
   it 'generates correct YAML config' do
@@ -538,8 +757,6 @@ detail:
 
 .Debugging example
 [example]
-====
-[source,ruby]
 ----
 it 'shows exactly what differs' do
   expect(actual).to be_xml_equivalent_to(expected, verbose: true)
@@ -553,14 +770,12 @@ The diff output will show:
 * Color-coded changes (red/green)
 * Whitespace visualization
 * Non-ASCII character warnings
-====
+----
 
 === Temporarily disabling global config
 
 .Override global config
 [example]
-====
-[source,ruby]
 ----
 it 'uses different config for this test' do
   # Global config uses spec_friendly, but we want strict here
@@ -572,14 +787,11 @@ it 'uses different config for this test' do
     )
 end
 ----
-====
 
 === Checking what's being compared
 
 .Debug preprocessed content
 [example]
-====
-[source,ruby]
 ----
 # In your test, temporarily add:
 result = Canon::Comparison.equivalent?(actual, expected, verbose: true)
@@ -594,12 +806,11 @@ puts result[:preprocessed][1]
 puts "Differences:"
 pp result[:differences]
 ----
-====
 
 == See also
 
-* link:RUBY_API[Ruby API documentation]
-* link:CLI[Command-line interface]
-* link:MATCH_OPTIONS[Match options reference]
-* link:MODES[Diff modes]
-* link:DIFF_FORMATTING[Diff formatting options]
+* link:../ruby-api/[Ruby API documentation]
+* link:../cli/[Command-line interface]
+* link:../../features/match-options/[Match options reference]
+* link:../../understanding/diff-modes/[Diff modes]
+* link:../../features/diff-formatting/[Diff formatting options]

data/docs/{RUBY_API.adoc → interfaces/ruby-api/index.adoc}

@@ -1,9 +1,9 @@
 ---
 layout: default
 title: Ruby API
-nav_order: 10
-parent: Basic Usage
-grand_parent: Documentation Index
+parent: Interfaces
+nav_order: 1
+has_children: true
 ---
 = Canon Ruby API
 :toc:
@@ -14,9 +14,9 @@ grand_parent: Documentation Index
 This document describes how to use Canon from Ruby code. It covers formatting,
 parsing, and comparison APIs.
 
-For command-line usage, see link:CLI[CLI documentation].
+For command-line usage, see link:../cli/[CLI documentation].
 
-For RSpec testing, see link:RSPEC[RSpec documentation].
+For RSpec testing, see link:../rspec/[RSpec documentation].
 
 == General
 
@@ -188,7 +188,7 @@ The comparison uses depth-first traversal of DOM trees (XML/HTML) or object
 graphs (JSON/YAML), comparing nodes/values based on configurable match
 dimensions.
 
-See link:MATCH_OPTIONS[Match options] for details on match dimensions and
+See link:../../features/match-options/[Match options] for details on match dimensions and
 profiles.
 
 === Basic comparison
@@ -210,7 +210,14 @@ Returns:
 
 * `true` if documents are semantically equivalent
 * `false` if documents differ
-* `Hash` with `:differences` and `:preprocessed` keys if `verbose: true`
+* `ComparisonResult` object if `verbose: true`
+
+Options:
+
+* `diff_algorithm`: `:dom` (default) or `:semantic` - chooses the diff algorithm
+* `verbose`: `true` or `false` - returns detailed results when true
+* `match`: Hash of match dimension options
+* `match_profile`: Symbol specifying a predefined profile
 
 .Basic comparison examples
 [example]
@@ -262,7 +269,7 @@ Canon::Comparison.equivalent?(obj1, obj2,
 )
 ----
 
-See link:MATCH_OPTIONS[Match options] for complete dimension reference.
+See link:../../features/match-options/[Match options] for complete dimension reference.
 
 .Match option examples
 [example]
@@ -398,6 +405,103 @@ result = Canon::Comparison.equivalent?(xml1, xml2,
 ----
 ====
 
+=== Display filtering
+
+Use the `show_diffs` parameter to control which differences appear in formatted
+output.
+
+Syntax:
+
+[source,ruby]
+----
+Canon::Comparison.equivalent?(obj1, obj2,
+  verbose: true,
+  show_diffs: :mode
+)
+----
+
+Where `mode` is one of:
+
+`:all`:: Show all differences (default)
+`:normative`:: Show only differences that affect equivalence
+`:informative`:: Show only differences that don't affect equivalence
+
+.Display filtering examples
+[example]
+====
+[source,ruby]
+----
+# Show all differences (default)
+result = Canon::Comparison.equivalent?(xml1, xml2,
+  verbose: true,
+  show_diffs: :all
+)
+
+# Show only normative differences
+result = Canon::Comparison.equivalent?(xml1, xml2,
+  verbose: true,
+  match: { comments: :ignore },
+  show_diffs: :normative
+)
+
+# Show only informative differences
+result = Canon::Comparison.equivalent?(xml1, xml2,
+  verbose: true,
+  match: { comments: :ignore },
+  show_diffs: :informative
+)
+
+# Use with DiffFormatter directly
+formatter = Canon::DiffFormatter.new(
+  use_color: true,
+  mode: :by_object,
+  show_diffs: :normative
+)
+output = formatter.format(result, :xml)
+----
+====
+
+IMPORTANT: Display filtering does NOT affect equivalence determination. It
+only controls which differences appear in formatted output. Equivalence is
+always based on normative differences only, regardless of the `show_diffs`
+setting.
+
+.Common use case: XML comments
+[example]
+====
+[source,ruby]
+----
+xml1 = <<~XML
+  <root>
+    <!-- Old comment -->
+    <element>value1</element>
+  </root>
+XML
+
+xml2 = <<~XML
+  <root>
+    <!-- New comment -->
+    <element>value2</element>
+  </root>
+XML
+
+# With comments: :ignore and show_diffs: :normative
+result = Canon::Comparison.equivalent?(xml1, xml2,
+  verbose: true,
+  match: { comments: :ignore },
+  show_diffs: :normative
+)
+
+# Result:
+# - equivalent? => false (element value differs)
+# - Diff output shows: only the element value change
+# - Diff output hides: comment differences (informative)
+----
+====
+
+See link:../../features/diff-formatting/display-filtering.adoc[Display
+filtering] for complete details.
+
 === Format-specific comparators
 
 You can use format-specific comparator classes directly.
@@ -414,8 +518,6 @@ Canon::Comparison::YamlComparator.equivalent?(obj1, obj2, options)
 
 .Format-specific comparator examples
 [example]
-====
-[source,ruby]
 ----
 # XML comparison with strict attribute order
 Canon::Comparison::XmlComparator.equivalent?(xml1, xml2,
@@ -467,12 +569,12 @@ end
 ----
 ====
 
-See link:INPUT_VALIDATION[Input validation] for details.
+See link:../../features/input-validation/[Input validation] for details.
 
 == See also
 
-* link:CLI[Command-line interface]
-* link:RSPEC[RSpec matchers]
-* link:MATCH_OPTIONS[Match options reference]
-* link:FORMATS[Format support details]
-* link:INPUT_VALIDATION[Input validation]
+* link:../cli/[Command-line interface]
+* link:../rspec/[RSpec matchers]
+* link:../../features/match-options/[Match options reference]
+* link:../../understanding/formats/[Format support details]
+* link:../../features/input-validation/[Input validation]

data/docs/lychee.toml

@@ -0,0 +1,65 @@
+# Lychee Link Checker Configuration
+# For Canon Documentation
+# https://github.com/lycheeverse/lychee
+
+# Cache results to avoid re-checking same URLs
+cache = true
+max_cache_age = "1d"
+
+# Check both source files and built site
+include_verbatim = true
+
+# Recursively check all files
+recursive = true
+
+# File types to check
+include = [
+  "_site/**/*.html"
+]
+
+# Excluded paths
+exclude = [
+  ".git",
+  ".github",
+  "node_modules",
+  "vendor",
+  ".bundle",
+  ".sass-cache",
+  ".jekyll-cache"
+]
+
+# Link checking behavior
+max_redirects = 10
+max_retries = 3
+timeout = 30
+
+# Accept status codes
+accept = [
+  "100..=103",  # Informational
+  "200..=299",  # Success
+  "429"         # Too Many Requests (retry handled by max_retries)
+]
+
+# User agent to identify ourselves
+user_agent = "lychee/canon-docs-link-checker"
+
+# Check HTTP, HTTPS, and file:// schemes
+scheme = ["https", "http", "file"]
+
+# Include file:// URLs for local link checking
+include_file = true
+
+# Handle different link types
+include_mail = false  # Don't check mailto: links
+
+# Maximum concurrent requests
+max_concurrency = 10
+
+# Verbose output for debugging
+verbose = "info"
+
+# Require HTTPS where possible
+require_https = false  # Don't enforce
+
+# Index files
+index_files = ["index.html"]