canon 0.1.3 → 0.1.5

data/docs/MATCH_ARCHITECTURE.adoc

@@ -0,0 +1,463 @@
+---
+layout: default
+title: Match Architecture
+nav_order: 22
+parent: Understanding Canon
+---
+= Match architecture
+:toc:
+:toclevels: 3
+
+== Scope
+
+This document explains Canon's three-phase comparison architecture and how
+documents flow through preprocessing, semantic matching, and diff rendering.
+
+For match dimension details, see link:MATCH_OPTIONS[Match options].
+
+For diff output customization, see link:DIFF_FORMATTING[Diff formatting].
+
+== General
+
+Canon uses a three-phase architecture that separates concerns for clean,
+maintainable comparison logic:
+
+. **Preprocessing**: Optional document normalization
+. **Semantic matching**: Content comparison with configurable dimensions
+. **Diff rendering**: Formatted output with visualization
+
+Each phase is independent and configurable, allowing fine-grained control over
+comparison behavior.
+
+== Architecture diagram
+
+[source]
+----
+┌──────────────────────────────────────────────────────────────────┐
+│                     CANON COMPARISON FLOW                        │
+└──────────────────────────────────────────────────────────────────┘
+
+┌─────────────────────┐
+│   Input Documents   │
+│   (File 1, File 2)  │
+└──────────┬──────────┘
+           │
+           ▼
+╔══════════════════════════════════════════════════════════════════╗
+║                        PHASE 1: PREPROCESSING                     ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Options:                                                         ║
+║  • none       - No preprocessing                                  ║
+║  • c14n       - Canonical form (XML C14N, JSON/YAML sorted)       ║
+║  • normalize  - Normalize whitespace                              ║
+║  • format     - Pretty-print with standard formatting             ║
+╚══════════════════════════════════════════════════════════════════╝
+           │
+           ▼
+┌─────────────────────┐
+│  Preprocessed Docs  │
+└──────────┬──────────┘
+           │
+           ▼
+╔══════════════════════════════════════════════════════════════════╗
+║                      PHASE 2: SEMANTIC MATCHING                   ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Match Dimensions:                                                ║
+║  • text_content          (strict|normalize|ignore)                ║
+║  • structural_whitespace (strict|normalize|ignore)                ║
+║  • attribute_whitespace  (strict|normalize|ignore) [XML/HTML]     ║
+║  • attribute_order       (strict|ignore) [XML/HTML]               ║
+║  • attribute_values      (strict|normalize|ignore) [XML/HTML]     ║
+║  • key_order            (strict|ignore) [JSON/YAML]               ║
+║  • comments             (strict|normalize|ignore)                 ║
+║                                                                    ║
+║  Match Profiles:                                                  ║
+║  • strict         - All dimensions strict (exact matching)        ║
+║  • rendered       - Mimics browser/CSS rendering behavior         ║
+║  • spec_friendly  - Test-friendly (ignores formatting diffs)      ║
+║  • content_only   - Only semantic content matters                 ║
+╚══════════════════════════════════════════════════════════════════╝
+           │
+           ├─ Equivalent? ──► Return true
+           │
+           ├─ Different? ──┐
+           │               │
+           ▼               ▼
+╔══════════════════════════════════════════════════════════════════╗
+║                   PHASE 3: DIFF RENDERING                         ║
+╠══════════════════════════════════════════════════════════════════╣
+║  Diff Options:                                                    ║
+║  • mode            - by_line (XML/HTML) | by_object (JSON/YAML)   ║
+║  • use_color       - Colorized output (terminal colors)           ║
+║  • context_lines   - Lines of context around changes              ║
+║  • grouping_lines  - Group nearby changes into blocks             ║
+╚══════════════════════════════════════════════════════════════════╝
+           │
+           ▼
+┌─────────────────────┐
+│   Formatted Diff    │
+│      Output         │
+└─────────────────────┘
+----
+
+== Phase 1: Preprocessing
+
+=== Purpose
+
+Transform documents into a normalized form before comparison. This eliminates
+format-specific variations that should not affect semantic equivalence.
+
+=== Options
+
+`none` (default):: No preprocessing - compare documents as-is
+
+`c14n`:: Canonical form:
+* XML: W3C Canonical XML 1.1
+* HTML: Normalized HTML structure
+* JSON: Sorted keys, normalized whitespace
+* YAML: Sorted keys, standard format
+
+`normalize`:: Normalize whitespace:
+* Collapse multiple whitespace to single space
+* Trim leading/trailing whitespace
+* Normalize line endings
+
+`format`:: Pretty-print with standard formatting:
+* 2-space indentation
+* One element/property per line
+* Consistent structure
+
+=== Usage
+
+.Ruby API
+[example]
+====
+[source,ruby]
+----
+Canon::Comparison.equivalent?(doc1, doc2,
+  preprocessing: :normalize
+)
+----
+====
+
+.CLI
+[example]
+====
+[source,bash]
+----
+$ canon diff file1.xml file2.xml --preprocessing normalize
+----
+====
+
+See link:PREPROCESSING[Preprocessing documentation] for details.
+
+== Phase 2: Semantic matching
+
+=== Purpose
+
+Compare document content based on configurable match dimensions. Each
+dimension controls how a specific aspect of documents is compared.
+
+=== Match dimensions
+
+Match dimensions are orthogonal aspects of documents that can be compared
+independently:
+
+`text_content`:: Text within elements/values
+`structural_whitespace`:: Whitespace between elements
+`attribute_whitespace`:: Whitespace in attribute values (XML/HTML)
+`attribute_order`:: Order of attributes (XML/HTML)
+`attribute_values`:: Attribute value content (XML/HTML)
+`key_order`:: Order of object keys (JSON/YAML)
+`comments`:: Comment content and placement
+
+Each dimension supports behaviors:
+
+* `:strict` - Must match exactly
+* `:normalize` - Match after normalization
+* `:ignore` - Don't compare
+
+See link:MATCH_OPTIONS[Match options] for complete dimension reference.
+
+=== Match profiles
+
+Profiles are predefined combinations of dimension settings for common
+scenarios:
+
+`:strict`:: Exact matching - all dimensions use `:strict` behavior
+`:rendered`:: Browser rendering - ignores formatting that doesn't affect
+display
+`:spec_friendly`:: Test-friendly - ignores formatting, focuses on content
+`:content_only`:: Maximum tolerance - only semantic content matters
+
+=== Usage
+
+.With dimensions
+[example]
+====
+[source,ruby]
+----
+Canon::Comparison.equivalent?(doc1, doc2,
+  match: {
+    text_content: :normalize,
+    structural_whitespace: :ignore,
+    comments: :ignore
+  }
+)
+----
+====
+
+.With profile
+[example]
+====
+[source,ruby]
+----
+Canon::Comparison.equivalent?(doc1, doc2,
+  match_profile: :spec_friendly
+)
+----
+====
+
+.Profile with dimension overrides
+[example]
+====
+[source,ruby]
+----
+Canon::Comparison.equivalent?(doc1, doc2,
+  match_profile: :spec_friendly,
+  match: {
+    comments: :strict  # Override profile setting
+  }
+)
+----
+====
+
+== Phase 3: Diff rendering
+
+=== Purpose
+
+When documents differ, format the differences for human review with syntax
+highlighting, context lines, and whitespace visualization.
+
+=== Diff modes
+
+`by-line`:: Traditional line-by-line diff
+* Default for HTML
+* Optional for XML
+* Shows changes in document order
+* DOM-guided semantic matching for XML
+
+`by-object`:: Tree-based semantic diff
+* Default for XML, JSON, YAML
+* Shows only what changed in structure
+* Visual tree representation
+
+See link:MODES[Diff modes] for details.
+
+=== Diff options
+
+`use_color`:: Enable/disable ANSI color codes (default: `true`)
+
+`context_lines`:: Number of unchanged lines around changes (default: `3`)
+
+`grouping_lines`:: Group changes within N lines (default: `nil`)
+
+See link:DIFF_FORMATTING[Diff formatting] for details.
+
+=== Usage
+
+.Ruby API
+[example]
+====
+[source,ruby]
+----
+Canon::Comparison.equivalent?(doc1, doc2,
+  verbose: true,
+  diff: {
+    mode: :by_line,
+    use_color: true,
+    context_lines: 5,
+    grouping_lines: 10
+  }
+)
+----
+====
+
+.CLI
+[example]
+====
+[source,bash]
+----
+$ canon diff file1.xml file2.xml \
+  --verbose \
+  --by-line \
+  --context-lines 5 \
+  --diff-grouping-lines 10
+----
+====
+
+== Data flow examples
+
+=== Example 1: Equivalent documents with formatting differences
+
+[source]
+----
+Input:
+  doc1: <root><a>1</a><b>2</b></root>
+  doc2: <root>  <b>2</b>  <a>1</a>  </root>
+
+Phase 1 - Preprocessing (none):
+  No changes
+
+Phase 2 - Semantic Matching (default):
+  • text_content: Both have "1" and "2" ✓
+  • structural_whitespace: Normalized ✓
+  • element order: Doesn't matter for siblings ✓
+  Result: EQUIVALENT
+
+Phase 3 - Diff Rendering:
+  Not needed (documents equivalent)
+
+Return: true
+----
+
+=== Example 2: Different text content
+
+[source]
+----
+Input:
+  doc1: <p>Test 1</p>
+  doc2: <p>Test 2</p>
+
+Phase 1 - Preprocessing (none):
+  No changes
+
+Phase 2 - Semantic Matching (default):
+  • text_content: "Test 1" ≠ "Test 2" ✗
+  Result: DIFFERENT
+
+Phase 3 - Diff Rendering (by-line):
+  Output:
+    1|  - | <p>Test 1</p>
+     | 1+ | <p>Test 2</p>
+
+Return: false (or diff hash if verbose: true)
+----
+
+=== Example 3: Attribute order with normalize
+
+[source]
+----
+Input:
+  doc1: <div class="foo" id="x">Content</div>
+  doc2: <div id="x" class="foo">Content</div>
+
+Phase 1 - Preprocessing (none):
+  No changes
+
+Phase 2 - Semantic Matching (attribute_order: ignore):
+  • attribute_order: Ignored (set to :ignore)
+  • Both have class="foo" and id="x" ✓
+  • Both have same content ✓
+  Result: EQUIVALENT
+
+Phase 3 - Diff Rendering:
+  Not needed (documents equivalent)
+
+Return: true
+----
+
+=== Example 4: With preprocessing
+
+[source]
+----
+Input:
+  doc1: <root>  <a>  1  </a>  </root>
+  doc2: <root><a>1</a></root>
+
+Phase 1 - Preprocessing (normalize):
+  Both become: <root><a>1</a></root>
+
+Phase 2 - Semantic Matching:
+  Preprocessed documents are identical
+  Result: EQUIVALENT
+
+Phase 3 - Diff Rendering:
+  Not needed (documents equivalent)
+
+Return: true
+----
+
+== Configuration precedence
+
+When options are specified in multiple places, Canon resolves them using this
+hierarchy (highest to lowest priority):
+
+[source]
+----
+1. Per-comparison explicit options (highest)
+   ↓
+2. Per-comparison profile
+   ↓
+3. Global configuration explicit options
+   ↓
+4. Global configuration profile
+   ↓
+5. Format defaults (lowest)
+----
+
+.Precedence example
+[example]
+====
+Global configuration:
+
+[source,ruby]
+----
+Canon::RSpecMatchers.configure do |config|
+  config.xml.match.profile = :spec_friendly
+  config.xml.match.options = { comments: :strict }
+end
+----
+
+Per-test usage:
+
+[source,ruby]
+----
+expect(actual).to be_xml_equivalent_to(expected)
+  .with_profile(:rendered)
+  .with_options(structural_whitespace: :ignore)
+----
+
+**Final resolved options**:
+
+* `text_content: :normalize` (from `:rendered` per-test profile)
+* `structural_whitespace: :ignore` (from per-test explicit option)
+* `comments: :strict` (from global explicit option)
+* Other dimensions use `:rendered` profile or format defaults
+====
+
+== Benefits of three-phase architecture
+
+**Separation of concerns**:: Each phase has a single responsibility
+
+**Composability**:: Mix and match preprocessing, matching, and rendering
+options
+
+**Testability**:: Each phase can be tested independently
+
+**Flexibility**:: Fine-grained control over comparison behavior
+
+**Clarity**:: Clear data flow from input to output
+
+**Extensibility**:: Easy to add new preprocessing, dimensions, or rendering
+modes
+
+== See also
+
+* link:PREPROCESSING[Preprocessing options]
+* link:MATCH_OPTIONS[Match dimensions and profiles]
+* link:MODES[Diff modes]
+* link:DIFF_FORMATTING[Diff formatting]
+* link:RUBY_API[Ruby API documentation]
+* link:CLI[Command-line interface]
+* link:RSPEC[RSpec matchers]