canon 0.1.3 → 0.1.5

data/docs/SEMANTIC_DIFF_REPORT.adoc

@@ -0,0 +1,528 @@
+---
+layout: default
+title: Semantic Diff Report
+nav_order: 41
+parent: Advanced Topics
+---
+= Canon semantic diff report
+:toc:
+:toclevels: 3
+
+== General
+
+The Semantic Diff Report provides dimension-specific, actionable details for
+each difference found during comparison. Unlike the detailed line-by-line or
+object tree diffs, which show every changed line, the Semantic Diff Report
+focuses on WHAT changed and WHY it matters.
+
+The report is always shown in verbose mode when differences exist, providing
+a high-level summary before the detailed diff output.
+
+Key features:
+
+* XPath locations for XML/HTML elements
+* JSON path locations for JSON/YAML data
+* Dimension-specific formatting optimized for each type of difference
+* Colorized output for easy visual scanning
+* Whitespace preservation detection for `<pre>`, `<code>`, etc.
+* Actionable change summaries (e.g., "Added: +xmlns:v, +xmlns:o")
+
+== Architecture
+
+The Semantic Diff Report is generated by the `DiffDetailFormatter` module
+and integrated into the main diff output flow:
+
+[source]
+----
+╔═════════════════════════════════════════════════════════════════════╗
+║           SEMANTIC DIFF REPORT ARCHITECTURE                         ║
+╚═════════════════════════════════════════════════════════════════════╝
+
+Input: ComparisonResult with differences array
+
+┌─────────────────────────────────────────────────────────────────────┐
+│ DiffDetailFormatter.format_report(differences)                      │
+│                                                                      │
+│  For each difference:                                               │
+│   1. Detect type (DiffNode for XML/HTML, Hash for JSON/YAML)       │
+│   2. Extract location (XPath or JSON path)                          │
+│   3. Dispatch to dimension-specific formatter                       │
+│   4. Format as vertical section with colors                         │
+└─────────────────────────────────────────────────────────────────────┘
+                               │
+                               ▼
+┌─────────────────────────────────────────────────────────────────────┐
+│ Dimension-Specific Formatters                                       │
+│                                                                      │
+│  XML/HTML:                      JSON/YAML:                          │
+│   • attribute_presence          • hash_diff                         │
+│   • attribute_values            (unified handling)                  │
+│   • text_content                                                    │
+│   • structural_whitespace                                           │
+│   • comments                                                        │
+│                                                                      │
+│  Each formatter returns:                                            │
+│   [detail1, detail2, changes_summary]                               │
+└─────────────────────────────────────────────────────────────────────┘
+                               │
+                               ▼
+Output: Formatted semantic diff report with:
+  • Header with difference count
+  • Individual difference sections
+  • Color-coded for easy scanning
+----
+
+=== Integration with DiffFormatter
+
+The Semantic Diff Report is integrated at the `format_comparison_result()`
+level:
+
+[source,ruby]
+----
+# In Canon::DiffFormatter
+def format_comparison_result(comparison_result, expected, actual)
+  output = []
+
+  # 1. CANON VERBOSE tables (optional)
+  output << DebugOutput.verbose_tables_only(...)
+
+  # 2. Semantic Diff Report (always if diffs exist)
+  if comparison_result.differences.any?
+    output << DiffDetailFormatter.format_report(differences)
+  end
+
+  # 3. Detailed diff (always)
+  output << format(...)
+
+  output.compact.join("\n")
+end
+----
+
+This ensures the Semantic Diff Report is part of the main output, not debug
+information.
+
+== Output format
+
+=== General structure
+
+Each difference is displayed as a vertical section with these components:
+
+[example]
+====
+[source]
+----
+🔍 DIFFERENCE #1/3 [STATUS]
+──────────────────────────────────────────────────────────────────────
+Dimension:  dimension_name
+Location:   /xpath/or/json.path
+
+⊖ Expected (File 1):
+   Details...
+
+⊕ Actual (File 2):
+   Details...
+
+✨ Changes:
+   Summary of what changed
+----
+====
+
+Where:
+
+`STATUS`:: Either `[NORMATIVE]` (green) or `[INFORMATIVE]` (yellow)
+`Dimension`:: The match dimension that detected this difference (magenta)
+`Location`:: XPath for XML/HTML, JSON path for JSON/YAML (blue)
+`Expected`:: What was in File 1 (red heading)
+`Actual`:: What was in File 2 (green heading)
+`Changes`:: Actionable summary (yellow)
+
+=== Color scheme
+
+The report uses colors to make scanning easy:
+
+* **Dimension name**: Magenta
+* **XPath/JSON path**: Blue
+* **Expected heading**: Red (bold)
+* **Actual heading**: Green (bold)
+* **Changes heading**: Yellow (bold)
+* **Status [NORMATIVE]**: Green (bold)
+* **Status [INFORMATIVE]**: Yellow (bold)
+* **Added items**: Green (with `+` prefix)
+* **Removed items**: Red (with `-` prefix)
+* **Element names**: Magenta
+* **Attribute names**: Cyan
+
+=== Vertical layout
+
+The vertical layout ensures no width constraints, making it easy to read
+even with long attribute lists or deeply nested paths.
+
+== XML/HTML dimensions
+
+=== General
+
+XML and HTML comparisons use the same set of dimensions, classified based
+on what aspect of the document differs.
+
+=== Attribute presence differences
+
+Reports when attributes are missing or extra.
+
+[example]
+====
+[source]
+----
+🔍 DIFFERENCE #1/1 [NORMATIVE]
+──────────────────────────────────────────────────────────────────────
+Dimension:  attribute_presence
+Location:   /html/body/p
+
+⊖ Expected (File 1):
+   <p> with 2 attributes: id, lang
+
+⊕ Actual (File 2):
+   <p> with 5 attributes: id, lang, xmlns:o, xmlns:v, xmlns:w
+
+✨ Changes:
+   Added: +xmlns:o, +xmlns:v, +xmlns:w
+----
+====
+
+The report shows:
+
+* Element name
+* Total attribute count in each document
+* Complete list of attributes
+* Which were added (green `+` prefix) or removed (red `-` prefix)
+
+This makes it immediately clear what needs to be added or removed to fix
+the test.
+
+=== Attribute value differences
+
+Reports when an attribute value differs.
+
+[example]
+====
+[source]
+----
+🔍 DIFFERENCE #1/1 [NORMATIVE]
+──────────────────────────────────────────────────────────────────────
+Dimension:  attribute_values
+Location:   /html/body/div[@id="main"]
+
+⊖ Expected (File 1):
+   <div> class="  container  fluid  "
+
+⊕ Actual (File 2):
+   <div> class="container fluid"
+
+✨ Changes:
+   Whitespace normalization difference
+----
+====
+
+The report shows:
+
+* Which specific attribute has different value (cyan highlighting)
+* Exact values on both sides (with quotes)
+* Analysis of the difference type:
+** "Whitespace difference only" - Only leading/trailing whitespace differs
+** "Whitespace normalization difference" - Whitespace runs differ
+** "Value changed" - Actual content differs
+
+=== Text content differences
+
+Reports when element text content differs.
+
+[example]
+====
+[source]
+----
+🔍 DIFFERENCE #1/1 [NORMATIVE]
+──────────────────────────────────────────────────────────────────────
+Dimension:  text_content
+Location:   /html/body/div/table/tbody/tr/td/pre/text
+
+⊖ Expected (File 1):
+   <text> "
+                      puts \"Hello, world.\"
+                      "
+
+⊕ Actual (File 2):
+   <text> "puts \"Hello, world.\" "
+
+✨ Changes:
+   ⚠️  Whitespace preserved (inside <pre>, <code>, etc. - whitespace
+   is significant)
+----
+====
+
+The report shows:
+
+* Text preview (truncated at 100 characters if long)
+* Element containing the text
+* Special warning if the text is inside whitespace-preserving elements
+  (`<pre>`, `<code>`, `<textarea>`, `<script>`, `<style>`)
+
+The whitespace warning is important because Canon automatically switches
+from `text_content: normalize` to `:strict` mode inside these elements.
+
+=== Structural whitespace differences
+
+Reports whitespace-only text differences (usually informative).
+
+[example]
+====
+[source]
+----
+🔍 DIFFERENCE #1/1 [INFORMATIVE]
+──────────────────────────────────────────────────────────────────────
+Dimension:  structural_whitespace
+Location:   /root/section/p
+
+⊖ Expected (File 1):
+   <p> "hello␣␣world"
+
+⊕ Actual (File 2):
+   <p> "hello␣world"
+
+✨ Changes:
+   Whitespace-only difference (informative)
+----
+====
+
+The report shows:
+
+* Whitespace visualized using Unicode symbols:
+** `␣` - Space (U+0020)
+** `→` - Tab
+** `↵` - Newline
+* Marked as `[INFORMATIVE]` (yellow) when `structural_whitespace: ignore`
+
+=== Comment differences
+
+Reports when HTML/XML comment content differs.
+
+[example]
+====
+[source]
+----
+🔍 DIFFERENCE #1/1 [INFORMATIVE]
+──────────────────────────────────────────────────────────────────────
+Dimension:  comments
+Location:   /html/head
+
+⊖ Expected (File 1):
+   <!-- Original comment text -->
+
+⊕ Actual (File 2):
+   <!-- Modified comment text -->
+
+✨ Changes:
+   Comment content differs
+----
+====
+
+== JSON/YAML dimensions
+
+=== General
+
+JSON and YAML comparisons use path-based difference reporting with Hash
+objects containing:
+
+* `:path` - The JSON path to the difference (e.g., `user.profile.email`)
+* `:value1` - Expected value
+* `:value2` - Actual value
+* `:diff_code` - Type of difference (MISSING_HASH_KEY,
+  UNEQUAL_PRIMITIVES, etc.)
+
+=== Hash key differences
+
+Reports when a key is missing or has different value.
+
+[example]
+====
+[source]
+----
+🔍 DIFFERENCE #1/1 [NORMATIVE]
+──────────────────────────────────────────────────────────────────────
+Dimension:  2
+Location:   user.email
+
+⊖ Expected (File 1):
+   user.email = "alice@example.com"
+
+⊕ Actual (File 2):
+   user.email = nil
+
+✨ Changes:
+   Key missing
+----
+====
+
+=== Primitive value differences
+
+Reports when primitive values (strings, numbers, booleans) differ.
+
+[example]
+====
+[source]
+----
+🔍 DIFFERENCE #1/1 [NORMATIVE]
+──────────────────────────────────────────────────────────────────────
+Dimension:  15
+Location:   users[0].age
+
+⊖ Expected (File 1):
+   users[0].age = 25
+
+⊕ Actual (File 2):
+   users[0].age = 30
+
+✨ Changes:
+   Value changed
+----
+====
+
+=== Array differences
+
+Reports when arrays have different lengths or elements.
+
+[example]
+====
+[source]
+----
+🔍 DIFFERENCE #1/1 [NORMATIVE]
+──────────────────────────────────────────────────────────────────────
+Dimension:  12
+Location:   items
+
+⊖ Expected (File 1):
+   items = [...] (5 items)
+
+⊕ Actual (File 2):
+   items = [...] (3 items)
+
+✨ Changes:
+   Array length differs
+----
+====
+
+Complex values (hashes, arrays) are shown as `{...} (N keys)` or
+`[...] (N items)` to keep output concise.
+
+== Special features
+
+=== XPath location extraction
+
+For XML/HTML differences, the report extracts XPath with:
+
+* Full path from root: `/html/body/div/section/p`
+* Position predicates when multiple siblings: `/p[2]`, `/div[3]`
+* Safe traversal with depth limits to prevent infinite loops
+* Graceful error handling for circular references
+* Document node detection to stop at appropriate boundaries
+
+=== Whitespace preservation detection
+
+The report detects when text is inside whitespace-preserving HTML elements
+and shows a special warning:
+
+[source]
+----
+✨ Changes: ⚠️  Whitespace preserved (inside <pre>, <code>, etc. -
+            whitespace is significant)
+----
+
+This is important because Canon automatically switches to `:strict` mode
+for text content inside these elements:
+
+* `<pre>` - Preformatted text
+* `<code>` - Code blocks
+* `<textarea>` - Text input areas
+* `<script>` - JavaScript code
+* `<style>` - CSS style sheets
+
+The warning helps developers understand why a seemingly minor whitespace
+difference is causing a test failure.
+
+=== Comprehensive error handling
+
+The formatter includes multiple layers of error handling:
+
+* Top-level rescue in `format_single_diff()` - Catches any formatting
+  errors
+* Safe XPath extraction with depth limits and circular reference detection
+* Safe parent traversal with document node checks
+* Graceful fallbacks when node types are unexpected
+
+This ensures the Semantic Diff Report never crashes, even with unusual DOM
+structures.
+
+== Implementation
+
+=== DiffDetailFormatter class
+
+Module: `Canon::DiffFormatter::DiffDetailFormatter`
+
+Location: `lib/canon/diff_formatter/diff_detail_formatter.rb`
+
+Main entry point:
+
+[source,ruby]
+----
+# Format all differences as semantic diff report
+def self.format_report(differences, use_color: true)
+  # Returns formatted string with all difference sections
+end
+----
+
+=== Dimension dispatch mechanism
+
+The formatter uses dimension-based dispatch:
+
+[source,ruby]
+----
+def format_dimension_details(diff, use_color)
+  # Handle Hash diffs (JSON/YAML)
+  return format_hash_diff_details(diff) if diff.is_a?(Hash)
+
+  # Handle DiffNode (XML/HTML) based on dimension
+  case diff.dimension
+  when :attribute_presence
+    format_attribute_presence_details(diff)
+  when :attribute_values
+    format_attribute_values_details(diff)
+  when :text_content
+    format_text_content_details(diff)
+  # ... other dimensions
+  end
+end
+----
+
+This ensures each difference type is optimally formatted.
+
+=== Helper methods
+
+Key helper methods:
+
+`extract_xpath(node)`:: Extracts XPath from XML/HTML nodes with safety
+limits and error handling
+
+`extract_location(diff)`:: Dispatches to XPath extraction for XML/HTML or
+returns JSON path for JSON/YAML
+
+`inside_preserve_element?(node)`:: Detects if node is inside `<pre>`,
+`<code>`, etc. with safe parent traversal
+
+`get_attribute_names(node)`:: Extracts sorted attribute names from elements
+
+`find_differing_attribute(node1, node2)`:: Finds which attribute has
+different value
+
+`format_json_value(value)`:: Formats JSON values concisely ({...},
+[...], primitives)
+
+All helpers include comprehensive error handling to ensure the report never
+crashes.

data/docs/UNDERSTANDING_CANON.adoc

@@ -0,0 +1,17 @@
+---
+layout: default
+title: Understanding Canon
+nav_order: 3
+has_children: true
+---
+= Understanding Canon
+
+Learn how Canon works internally:
+
+* **link:FORMATS[Format support]** - XML, HTML, JSON, YAML
+canonicalization
+* **link:MODES[Diff modes]** - By-line vs by-object comparison modes
+* **link:MATCH_ARCHITECTURE[Match architecture]** - Three-phase
+comparison flow
+
+These documents explain Canon's core concepts and architecture.