canon 0.1.6 → 0.1.7

data/docs/understanding/architecture.adoc

@@ -0,0 +1,447 @@
+---
+title: Architecture
+parent: Understanding
+nav_order: 1
+---
+= Architecture
+:toc:
+:toclevels: 3
+
+== Purpose
+
+This document explains Canon's 4-layer comparison architecture and how documents flow through preprocessing, algorithm selection, semantic matching, and diff rendering.
+
+For a guided walkthrough of choosing configurations, see link:../guides/choosing-configuration.adoc[Choosing Configuration].
+
+For detailed 4-layer pipeline documentation, see link:comparison-pipeline.adoc[Comparison Pipeline].
+
+== Overview
+
+Canon uses a 4-layer architecture that separates concerns for clean, maintainable comparison logic:
+
+. **Layer 1 - Preprocessing**: Optional document normalization
+. **Layer 2 - Algorithm Selection**: Choose comparison strategy (DOM vs Semantic)
+. **Layer 3 - Match Options**: Content comparison with configurable dimensions (algorithm-specific)
+. **Layer 4 - Diff Formatting**: Formatted output with visualization (algorithm-specific)
+
+Each layer is independent and configurable, allowing fine-grained control over comparison behavior.
+
+**Key Insight**: Layers 3 and 4 are **algorithm-specific** - they behave differently depending on which algorithm (DOM or Semantic) is chosen in Layer 2.
+
+== System architecture diagram
+
+[mermaid]
+----
+graph TD
+    A[Input Documents] --> B[Layer 1: Preprocessing]
+    B --> C[Layer 2: Algorithm Selection]
+    C --> D[Layer 3: Match Options]
+    D --> E[Layer 4: Diff Formatting]
+    E --> F[Output]
+
+    C -->|DOM Algorithm| D1[Positional Matching]
+    C -->|Semantic Algorithm| D2[Signature Matching]
+
+    D1 --> E1[Line-based Diff]
+    D2 --> E2[Operation-based Diff]
+
+    style B fill:#e1f5ff
+    style C fill:#fff4e1
+    style D fill:#ffe1f5
+    style E fill:#e1ffe1
+----
+
+== Layer 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:../features/preprocessing/[Preprocessing documentation] for details.
+
+== Layer 2: Algorithm selection
+
+=== Purpose
+
+Choose the comparison strategy. This is a **critical decision** because it determines how Layers 3 and 4 behave.
+
+=== Options
+
+`dom` (default):: DOM-based positional comparison
+* Fast, stable, well-tested
+* Position-based element matching
+* No move detection
+* Best for similar documents
+
+`semantic` (experimental):: Tree-based semantic diff
+* Slower but more intelligent
+* Signature-based matching
+* Detects moves, merges, splits
+* Best for restructured documents
+
+=== Algorithm characteristics
+
+[cols="2,3,3"]
+|===
+|Feature |DOM |Semantic
+
+|**Stability**
+|Stable (production-ready)
+|Experimental
+
+|**Performance**
+|Fast (linear)
+|Slower (quadratic worst case)
+
+|**Move Detection**
+|No
+|Yes
+
+|**Match Strategy**
+|Positional
+|Signature-based
+
+|**Layer 3 Behavior**
+|Element-by-element comparison
+|Signature calculation
+
+|**Layer 4 Behavior**
+|Line-based differences
+|Operation-based (INSERT, DELETE, UPDATE, MOVE)
+
+|**Best For**
+|Similar documents
+|Restructured documents
+|===
+
+=== Usage
+
+.Ruby API
+[example]
+====
+[source,ruby]
+----
+# DOM algorithm (default)
+Canon::Comparison.equivalent?(doc1, doc2,
+  diff_algorithm: :dom
+)
+
+# Semantic algorithm
+Canon::Comparison.equivalent?(doc1, doc2,
+  diff_algorithm: :semantic
+)
+----
+====
+
+.CLI
+[example]
+====
+[source,bash]
+----
+# DOM algorithm
+$ canon diff file1.xml file2.xml --diff-algorithm dom
+
+# Semantic algorithm
+$ canon diff file1.xml file2.xml --diff-algorithm semantic
+----
+====
+
+See link:algorithms/[Algorithm documentation] for details.
+
+== Layer 3: Match options
+
+=== Purpose
+
+Configure what to compare and how strictly. **This layer is algorithm-specific** - each algorithm interprets match options differently.
+
+=== 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
+
+=== 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
+
+=== Algorithm-specific behavior
+
+**Critical**: The same match options behave differently with each algorithm!
+
+* **DOM algorithm**: Uses options for positional element comparison
+* **Semantic algorithm**: Uses options during signature calculation
+
+See link:../features/match-options/algorithm-specific-behavior.adoc[Algorithm-Specific Behavior] for detailed comparison.
+
+=== 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
+  }
+)
+----
+====
+
+See link:../features/match-options/[Match Options] for complete reference.
+
+== Layer 4: Diff formatting
+
+=== Purpose
+
+Control how differences are displayed. **This layer is algorithm-specific** - each algorithm generates different output types.
+
+=== Diff modes
+
+`by_line`:: Traditional line-by-line diff
+* Natural fit for DOM algorithm
+* Shows positional changes
+* Traditional diff format
+
+`by_object`:: Tree-based semantic diff
+* Natural fit for Semantic algorithm
+* Shows structural operations
+* Visual tree representation
+
+=== Algorithm-specific output
+
+**Critical**: Each algorithm produces fundamentally different output!
+
+* **DOM algorithm**: Generates line-based differences
+* **Semantic algorithm**: Generates operation-based differences (INSERT, DELETE, UPDATE, MOVE)
+
+See link:../features/diff-formatting/algorithm-specific-output.adoc[Algorithm-Specific Output] for detailed comparison.
+
+=== Diff options
+
+`use_color`:: Enable/disable ANSI color codes (default: `true`)
+
+`context_lines`:: Number of unchanged lines around changes (default: `3`)
+
+`diff_grouping_lines`:: Group changes within N lines (default: `nil`)
+
+See link:../features/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,
+  diff_grouping_lines: 10
+)
+----
+====
+
+.CLI
+[example]
+====
+[source,bash]
+----
+$ canon diff file1.xml file2.xml \
+  --verbose \
+  --diff-mode by-line \
+  --context-lines 5 \
+  --diff-grouping-lines 10
+----
+====
+
+== Complete example: All 4 layers
+
+Here's a full configuration showing all 4 layers working together:
+
+[source,ruby]
+----
+result = Canon::Comparison.equivalent?(doc1, doc2,
+  # Layer 1: Preprocessing
+  preprocessing: :normalize,
+
+  # Layer 2: Algorithm
+  diff_algorithm: :semantic,
+
+  # Layer 3: Match Options
+  match_profile: :spec_friendly,
+
+  # Layer 4: Diff Formatting
+  verbose: true,
+  diff_mode: :by_object,
+  use_color: true,
+  context_lines: 3
+)
+----
+
+See link:comparison-pipeline.adoc[Comparison Pipeline] for layer-by-layer examples.
+
+== 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 4-layer architecture
+
+**Separation of concerns**:: Each layer has a single responsibility
+
+**Composability**:: Mix and match preprocessing, algorithm, matching, and rendering options
+
+**Algorithm flexibility**:: Choose between speed (DOM) and intelligence (Semantic)
+
+**Testability**:: Each layer 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, algorithms, dimensions, or rendering modes
+
+== See also
+
+* link:comparison-pipeline.adoc[Comparison Pipeline] - Complete 4-layer walkthrough
+* link:algorithms/[Algorithms] - DOM and Semantic algorithm details
+* link:../features/preprocessing/[Preprocessing options]
+* link:../features/match-options/[Match dimensions and profiles]
+* link:../features/match-options/algorithm-specific-behavior.adoc[Algorithm-Specific Behavior]
+* link:../features/diff-formatting/[Diff formatting]
+* link:../features/diff-formatting/algorithm-specific-output.adoc[Algorithm-Specific Output]
+* link:../guides/choosing-configuration.adoc[Choosing Configuration]
+* link:../interfaces/ruby-api/[Ruby API documentation]
+* link:../interfaces/cli/[Command-line interface]
+* link:../interfaces/rspec/[RSpec matchers]