canon 0.1.8 → 0.1.9

data/old-docs/SEMANTIC_DIFF_REPORT.adoc

@@ -1,646 +0,0 @@
----
-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.
-
-.Real-world example: Removed attribute in IsoDoc output
-[example]
-[source]
-----
-🔍 DIFFERENCE #1/1 [NORMATIVE]
-──────────────────────────────────────────────────────────────────────
-Dimension:  attribute_presence
-Location:   /iso-standard/preface/foreword
-
-⊖ Expected (File 1):
-   <foreword> with 3 attributes: displayorder, id, semx-id
-
-⊕ Actual (File 2):
-   <foreword> with 2 attributes: displayorder, id
-
-✨ Changes:
-   Removed: -semx-id
-----
-
-.Another real-world example: Missing class attribute
-[example]
-[source]
-----
-🔍 DIFFERENCE #1/1 [NORMATIVE]
-──────────────────────────────────────────────────────────────────────
-Dimension:  attribute_presence
-Location:   /html/body/div/div
-
-⊖ Expected (File 1):
-   <div> with 2 attributes: class, id
-
-⊕ Actual (File 2):
-   <div> with 1 attribute: id
-
-[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:
-✨ Changes:
-   Removed: -class
-----
-
-The report shows:
-====
-[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.
-
-.Real-world example: Whitespace differences inside `<pre>` element
-[example]
-[source]
-----
-🔍 DIFFERENCE #1/1 [NORMATIVE]
-──────────────────────────────────────────────────────────────────────
-Dimension:  text_content
-Location:   /html/body/div/div/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)
-----
-
-.Another real-world example: Text content change
-[example]
-[source]
-----
-🔍 DIFFERENCE #1/1 [NORMATIVE]
-──────────────────────────────────────────────────────────────────────
-Dimension:  text_content
-Location:   /iso-standard/bibliography/references/bibitem/formattedref
-
-⊖ Expected (File 1):
-   <formattedref> "
-                      R. FIELDING, J. GETTYS, J. MOGUL, H. FRYSTYK, L. MASINTER, P. LEACH and T. BERNER..."
-
-⊕ Actual (File 2):
-   <formattedref> "[1]IETF RFC 2616, "
-
-[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:
-✨ Changes:
-   Text content changed
-----
-
-The report shows:
-====
-[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.