RubyGems - canon - Versions diffs - 0.1.3 → 0.1.5 - Mend

canon 0.1.3 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (102) hide show

checksums.yaml +4 -4
data/.rubocop.yml +9 -1
data/.rubocop_todo.yml +276 -7
data/README.adoc +203 -138
data/_config.yml +116 -0
data/docs/ADVANCED_TOPICS.adoc +20 -0
data/docs/BASIC_USAGE.adoc +16 -0
data/docs/CHARACTER_VISUALIZATION.adoc +567 -0
data/docs/CLI.adoc +493 -0
data/docs/CUSTOMIZING_BEHAVIOR.adoc +19 -0
data/docs/DIFF_ARCHITECTURE.adoc +435 -0
data/docs/DIFF_FORMATTING.adoc +540 -0
data/docs/FORMATS.adoc +447 -0
data/docs/INDEX.adoc +222 -0
data/docs/INPUT_VALIDATION.adoc +477 -0
data/docs/MATCH_ARCHITECTURE.adoc +463 -0
data/docs/MATCH_OPTIONS.adoc +719 -0
data/docs/MODES.adoc +432 -0
data/docs/NORMATIVE_INFORMATIVE_DIFFS.adoc +219 -0
data/docs/OPTIONS.adoc +1387 -0
data/docs/PREPROCESSING.adoc +491 -0
data/docs/RSPEC.adoc +605 -0
data/docs/RUBY_API.adoc +478 -0
data/docs/SEMANTIC_DIFF_REPORT.adoc +528 -0
data/docs/UNDERSTANDING_CANON.adoc +17 -0
data/docs/VERBOSE.adoc +482 -0
data/exe/canon +7 -0
data/lib/canon/cli.rb +179 -0
data/lib/canon/commands/diff_command.rb +195 -0
data/lib/canon/commands/format_command.rb +113 -0
data/lib/canon/comparison/base_comparator.rb +39 -0
data/lib/canon/comparison/comparison_result.rb +79 -0
data/lib/canon/comparison/html_comparator.rb +410 -0
data/lib/canon/comparison/json_comparator.rb +212 -0
data/lib/canon/comparison/match_options.rb +616 -0
data/lib/canon/comparison/xml_comparator.rb +566 -0
data/lib/canon/comparison/yaml_comparator.rb +93 -0
data/lib/canon/comparison.rb +239 -0
data/lib/canon/config.rb +172 -0
data/lib/canon/diff/diff_block.rb +71 -0
data/lib/canon/diff/diff_block_builder.rb +105 -0
data/lib/canon/diff/diff_classifier.rb +46 -0
data/lib/canon/diff/diff_context.rb +85 -0
data/lib/canon/diff/diff_context_builder.rb +107 -0
data/lib/canon/diff/diff_line.rb +77 -0
data/lib/canon/diff/diff_node.rb +56 -0
data/lib/canon/diff/diff_node_mapper.rb +148 -0
data/lib/canon/diff/diff_report.rb +133 -0
data/lib/canon/diff/diff_report_builder.rb +62 -0
data/lib/canon/diff_formatter/by_line/base_formatter.rb +407 -0
data/lib/canon/diff_formatter/by_line/html_formatter.rb +672 -0
data/lib/canon/diff_formatter/by_line/json_formatter.rb +284 -0
data/lib/canon/diff_formatter/by_line/simple_formatter.rb +190 -0
data/lib/canon/diff_formatter/by_line/xml_formatter.rb +860 -0
data/lib/canon/diff_formatter/by_line/yaml_formatter.rb +292 -0
data/lib/canon/diff_formatter/by_object/base_formatter.rb +199 -0
data/lib/canon/diff_formatter/by_object/json_formatter.rb +305 -0
data/lib/canon/diff_formatter/by_object/xml_formatter.rb +248 -0
data/lib/canon/diff_formatter/by_object/yaml_formatter.rb +17 -0
data/lib/canon/diff_formatter/character_map.yml +197 -0
data/lib/canon/diff_formatter/debug_output.rb +431 -0
data/lib/canon/diff_formatter/diff_detail_formatter.rb +551 -0
data/lib/canon/diff_formatter/legend.rb +141 -0
data/lib/canon/diff_formatter.rb +520 -0
data/lib/canon/errors.rb +56 -0
data/lib/canon/formatters/html4_formatter.rb +17 -0
data/lib/canon/formatters/html5_formatter.rb +17 -0
data/lib/canon/formatters/html_formatter.rb +37 -0
data/lib/canon/formatters/html_formatter_base.rb +163 -0
data/lib/canon/formatters/json_formatter.rb +3 -0
data/lib/canon/formatters/xml_formatter.rb +20 -55
data/lib/canon/formatters/yaml_formatter.rb +4 -1
data/lib/canon/pretty_printer/html.rb +57 -0
data/lib/canon/pretty_printer/json.rb +25 -0
data/lib/canon/pretty_printer/xml.rb +29 -0
data/lib/canon/rspec_matchers.rb +222 -80
data/lib/canon/validators/base_validator.rb +49 -0
data/lib/canon/validators/html_validator.rb +138 -0
data/lib/canon/validators/json_validator.rb +89 -0
data/lib/canon/validators/xml_validator.rb +53 -0
data/lib/canon/validators/yaml_validator.rb +73 -0
data/lib/canon/version.rb +1 -1
data/lib/canon/xml/attribute_handler.rb +80 -0
data/lib/canon/xml/c14n.rb +36 -0
data/lib/canon/xml/character_encoder.rb +38 -0
data/lib/canon/xml/data_model.rb +225 -0
data/lib/canon/xml/element_matcher.rb +196 -0
data/lib/canon/xml/line_range_mapper.rb +158 -0
data/lib/canon/xml/namespace_handler.rb +86 -0
data/lib/canon/xml/node.rb +32 -0
data/lib/canon/xml/nodes/attribute_node.rb +54 -0
data/lib/canon/xml/nodes/comment_node.rb +23 -0
data/lib/canon/xml/nodes/element_node.rb +56 -0
data/lib/canon/xml/nodes/namespace_node.rb +38 -0
data/lib/canon/xml/nodes/processing_instruction_node.rb +24 -0
data/lib/canon/xml/nodes/root_node.rb +16 -0
data/lib/canon/xml/nodes/text_node.rb +23 -0
data/lib/canon/xml/processor.rb +151 -0
data/lib/canon/xml/whitespace_normalizer.rb +72 -0
data/lib/canon/xml/xml_base_handler.rb +188 -0
data/lib/canon.rb +14 -3
metadata +116 -21

data/docs/FORMATS.adoc ADDED Viewed

@@ -0,0 +1,447 @@
+---
+layout: default
+title: Format Support
+nav_order: 20
+parent: Understanding Canon
+---
+= Format support
+:toc:
+:toclevels: 3
+== Scope
+This document describes Canon's support for XML, HTML, JSON, and YAML formats,
+including canonicalization rules, format detection, and format-specific
+features.
+For usage examples, see link:RUBY_API[Ruby API], link:CLI[CLI], or
+link:RSPEC[RSpec documentation].
+== General
+Canon provides unified canonicalization and comparison for four serialization
+formats. Each format has specific rules and defaults optimized for its typical
+usage.
+== XML format
+=== Canonicalization
+Canon implements the https://www.w3.org/TR/xml-c14n11/[W3C Canonical XML
+Version 1.1] specification.
+**Key features:**
+* Namespace declaration ordering (lexicographic by prefix)
+* Attribute ordering (lexicographic by namespace URI, then local name)
+* Character encoding normalization to UTF-8
+* Special character encoding in text and attributes
+* Removal of superfluous namespace declarations
+* Support for xml:base, xml:lang, xml:space, and xml:id attributes
+* Processing instruction and comment handling
+* Document subset support with attribute inheritance
+.XML canonicalization example
+[example]
+====
+[source,ruby]
+----
+xml = <<~XML
+  <root xmlns:b="http://b.com" xmlns:a="http://a.com">
+    <item b:attr="2" a:attr="1">
+      Text   content
+    </item>
+  </root>
+XML
+Canon.format(xml, :xml)
+# => Namespace prefixes sorted, attributes sorted, whitespace normalized
+----
+====
+=== Format defaults
+[cols="1,1"]
+|===
+|Dimension |Default Behavior
+|`text_content`
+|`:strict`
+|`structural_whitespace`
+|`:strict`
+|`attribute_whitespace`
+|`:strict`
+|`attribute_order`
+|`:strict`
+|`attribute_values`
+|`:strict`
+|`comments`
+|`:strict`
+|===
+Default diff mode: `:by_object` (tree-based semantic diff)
+=== XML-specific features
+**Comment handling**: XML comments are preserved in canonical form unless
+`--with-comments` is explicitly set.
+**Namespace normalization**: Namespace declarations are sorted and duplicate
+declarations are removed.
+**xml: attributes**: Special attributes like `xml:lang`, `xml:space`, `xml:id`,
+and `xml:base` are properly handled per specification.
+== HTML format
+=== Canonicalization
+Canon supports HTML 4, HTML5, and XHTML with automatic format detection.
+**Key features:**
+* Automatic HTML vs XHTML detection
+* HTML5 parser for modern HTML
+* XML parser for XHTML
+* Consistent attribute ordering
+* Whitespace normalization
+* Comment handling in `<style>` and `<script>` tags
+.HTML canonicalization example
+[example]
+====
+[source,ruby]
+----
+html = <<~HTML
+  <!DOCTYPE html>
+  <html>
+    <body>
+      <div   class="foo"   id="bar">
+        Content
+      </div>
+    </body>
+  </html>
+HTML
+Canon.format(html, :html)
+# => Normalized structure with consistent formatting
+----
+====
+=== Format defaults
+[cols="1,1"]
+|===
+|Dimension |Default Behavior
+|`text_content`
+|`:normalize`
+|`structural_whitespace`
+|`:normalize`
+|`attribute_whitespace`
+|`:normalize`
+|`attribute_order`
+|`:ignore`
+|`attribute_values`
+|`:strict`
+|`comments`
+|`:ignore`
+|===
+Default diff mode: `:by_line` (line-based diff)
+=== HTML-specific features
+**Format detection**: Automatically detects HTML5, HTML4, or XHTML based on
+DOCTYPE and structure.
+**Whitespace handling**: HTML whitespace is collapsed per CSS rendering rules.
+Empty text nodes between elements are removed.
+**Attribute order**: HTML attributes are inherently unordered per the HTML
+specification, so default is `:ignore`.
+**Special tags**: Comments in `<style>` and `<script>` tags are normalized
+specially to handle CSS/JavaScript syntax.
+== JSON format
+=== Canonicalization
+Canon provides JSON canonicalization with sorted keys at all nesting levels.
+**Key features:**
+* Alphabetically sorted object keys
+* Consistent indentation (configurable)
+* Proper escape sequences
+* No trailing commas
+* Unicode normalization
+.JSON canonicalization example
+[example]
+====
+[source,ruby]
+----
+json = '{"z":3,"a":1,"nested":{"y":2,"x":1}}'
+Canon.format(json, :json)
+# => {"a":1,"nested":{"x":1,"y":2},"z":3}
+# Keys sorted at all levels
+----
+====
+=== Format defaults
+[cols="1,1"]
+|===
+|Dimension |Default Behavior
+|`text_content`
+|`:strict`
+|`structural_whitespace`
+|`:strict`
+|`key_order`
+|`:strict`
+|===
+Default diff mode: `:by_object` (tree-based semantic diff)
+=== JSON-specific features
+**Key ordering**: Object keys are sorted alphabetically for consistent
+comparison.
+**Type preservation**: Distinguishes between numbers, strings, booleans, and
+null.
+**Nested structures**: Handles deeply nested objects and arrays.
+**No comments**: Standard JSON does not support comments.
+== YAML format
+=== Canonicalization
+Canon provides YAML canonicalization with sorted keys and standard formatting.
+**Key features:**
+* Alphabetically sorted mapping keys
+* Consistent indentation
+* Standard YAML 1.2 format
+* Comment preservation (optional)
+* Anchor and alias handling
+.YAML canonicalization example
+[example]
+====
+[source,ruby]
+----
+yaml = <<~YAML
+  z: 3
+  a: 1
+  nested:
+    y: 2
+    x: 1
+YAML
+Canon.format(yaml, :yaml)
+# => Keys sorted at all levels
+----
+====
+=== Format defaults
+[cols="1,1"]
+|===
+|Dimension |Default Behavior
+|`text_content`
+|`:strict`
+|`structural_whitespace`
+|`:strict`
+|`key_order`
+|`:strict`
+|`comments`
+|`:strict`
+|===
+Default diff mode: `:by_object` (tree-based semantic diff)
+=== YAML-specific features
+**Comment support**: YAML comments are preserved and can be compared.
+**Key ordering**: Mapping keys are sorted alphabetically for consistent output.
+**Type detection**: YAML's rich type system is preserved (strings, numbers,
+booleans, dates, etc.).
+**Anchors and aliases**: YAML anchors (`&`) and aliases (`*`) are properly
+handled.
+== Format detection
+Canon automatically detects format based on file extensions:
+[cols="1,1"]
+|===
+|Extension |Format
+|`.xml`
+|XML
+|`.html`, `.htm`
+|HTML
+|`.json`
+|JSON
+|`.yaml`, `.yml`
+|YAML
+|===
+You can override auto-detection by explicitly specifying the format:
+.Explicit format specification
+[example]
+====
+[source,ruby]
+----
+# Ruby API
+Canon.format(content, :xml)
+# CLI
+$ canon format file.txt --format xml
+# Comparison
+Canon::Comparison.equivalent?(doc1, doc2, format: :xml)
+----
+====
+== Format comparison matrix
+[cols="1,1,1,1,1"]
+|===
+|Feature |XML |HTML |JSON |YAML
+|Canonicalization standard
+|W3C C14N 1.1
+|Custom
+|Custom
+|YAML 1.2
+|Comment support
+|Yes
+|Yes
+|No
+|Yes
+|Attribute/key ordering
+|Strict default
+|Ignored default
+|Strict default
+|Strict default
+|Default diff mode
+|by-object
+|by-line
+|by-object
+|by-object
+|Whitespace handling
+|Strict default
+|Normalized default
+|Strict default
+|Strict default
+|Namespace support
+|Yes
+|Limited (XHTML)
+|No
+|No
+|===
+== Working with multiple formats
+Canon's unified API works consistently across all formats:
+.Unified API examples
+[example]
+====
+[source,ruby]
+----
+# Format any content
+Canon.format(xml_content, :xml)
+Canon.format(html_content, :html)
+Canon.format(json_content, :json)
+Canon.format(yaml_content, :yaml)
+# Compare any format
+Canon::Comparison.equivalent?(xml1, xml2)
+Canon::Comparison.equivalent?(html1, html2)
+Canon::Comparison.equivalent?(json1, json2)
+Canon::Comparison.equivalent?(yaml1, yaml2)
+# RSpec matchers
+expect(actual_xml).to be_xml_equivalent_to(expected_xml)
+expect(actual_html).to be_html_equivalent_to(expected_html)
+expect(actual_json).to be_json_equivalent_to(expected_json)
+expect(actual_yaml).to be_yaml_equivalent_to(expected_yaml)
+----
+====
+== Format-specific comparators
+You can use format-specific comparator classes directly:
+.Format-specific comparators
+[example]
+====
+[source,ruby]
+----
+# XML comparator
+Canon::Comparison::XmlComparator.equivalent?(xml1, xml2,
+  match: { attribute_order: :ignore }
+)
+# HTML comparator
+Canon::Comparison::HtmlComparator.equivalent?(html1, html2,
+  match_profile: :rendered
+)
+# JSON comparator
+Canon::Comparison::JsonComparator.equivalent?(json1, json2,
+  match: { key_order: :ignore }
+)
+# YAML comparator
+Canon::Comparison::YamlComparator.equivalent?(yaml1, yaml2,
+  match: { comments: :ignore }
+)
+----
+====
+== See also
+* link:RUBY_API[Ruby API documentation]
+* link:CLI[Command-line interface]
+* link:MATCH_OPTIONS[Match options reference]
+* link:MODES[Diff modes]
+* link:PREPROCESSING[Preprocessing options]

data/docs/INDEX.adoc ADDED Viewed

@@ -0,0 +1,222 @@
+---
+layout: default
+title: Documentation Index
+nav_order: 1
+has_children: false
+---
+= Index
+:toc:
+:toclevels: 2
+== Documentation overview
+This index organizes all Canon documentation by complexity, progressing from
+basic usage to advanced technical topics.
+== Level 1: Getting started
+Start here if you're new to Canon:
+* **link:../README[README]** - Project overview, installation, and quick
+start examples
+== Level 2: Basic usage
+Learn how to use Canon through different interfaces (choose based on your
+needs):
+* **link:RUBY_API[Ruby API]** - Using Canon from Ruby code
+* **link:CLI[Command-line interface]** - Terminal commands and options
+* **link:RSPEC[RSpec matchers]** - Testing with Canon in RSpec
+== Level 3: 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
+== Level 4: Customizing behavior
+Configure Canon for your specific needs:
+* **link:MATCH_OPTIONS[Match options]** - Match dimensions and profiles
+* **link:PREPROCESSING[Preprocessing]** - Document normalization options
+* **link:DIFF_FORMATTING[Diff formatting]** - Customizing diff output
+* **link:INPUT_VALIDATION[Input validation]** - Error handling
+* **link:CHARACTER_VISUALIZATION[Character visualization]** - Whitespace
+visibility
+== Level 5: Advanced topics
+For developers and advanced users:
+* **link:VERBOSE[Verbose mode]** - Two-tier diff output architecture
+* **link:SEMANTIC_DIFF_REPORT[Semantic diff report]** - Detailed report
+format
+* **link:NORMATIVE_INFORMATIVE_DIFFS[Normative vs informative diffs]** - Diff
+classification
+* **link:DIFF_ARCHITECTURE[Diff architecture]** - Six-layer technical
+pipeline
+== Documentation by topic
+=== Canonicalization and formatting
+* link:FORMATS[Format support] - Format-specific canonicalization rules
+* link:RUBY_API#formatting[Ruby API: Formatting]
+* link:CLI#format-command[CLI: Format command]
+=== Comparison and matching
+* link:MATCH_ARCHITECTURE[Match architecture] - Three-phase comparison
+* link:MATCH_OPTIONS[Match options] - Dimensions and profiles
+* link:PREPROCESSING[Preprocessing] - Document normalization
+* link:RUBY_API#comparison[Ruby API: Comparison]
+* link:CLI#diff-command[CLI: Diff command]
+=== Diff output
+* link:MODES[Diff modes] - By-line vs by-object
+* link:DIFF_FORMATTING[Diff formatting] - Output customization
+* link:CHARACTER_VISUALIZATION[Character visualization] - Whitespace
+visibility
+* link:VERBOSE[Verbose mode] - Detailed diff output
+* link:SEMANTIC_DIFF_REPORT[Semantic diff report] - Report structure
+=== Testing
+* link:RSPEC[RSpec matchers] - Testing guide
+* link:MATCH_OPTIONS#match-profiles[Match profiles] - Test-friendly
+profiles
+* link:INPUT_VALIDATION[Input validation] - Error handling in tests
+=== Technical architecture
+* link:MATCH_ARCHITECTURE[Match architecture] - Comparison phases
+* link:DIFF_ARCHITECTURE[Diff architecture] - Six-layer pipeline
+* link:NORMATIVE_INFORMATIVE_DIFFS[Normative vs informative diffs] - Classification
+system
+== Quick reference
+=== Common tasks
+**Format a document**::
+* Ruby: link:RUBY_API#formatting[Formatting section]
+* CLI: link:CLI#format-command[Format command]
+**Compare documents**::
+* Ruby: link:RUBY_API#comparison[Comparison section]
+* CLI: link:CLI#diff-command[Diff command]
+* RSpec: link:RSPEC#basic-usage[Basic usage]
+**Configure comparison behavior**::
+* link:MATCH_OPTIONS[Match options] - Dimensions and profiles
+* link:PREPROCESSING[Preprocessing] - Normalization options
+**Customize diff output**::
+* link:DIFF_FORMATTING[Diff formatting] - Colors, context, grouping
+* link:MODES[Diff modes] - By-line or by-object
+**Debug test failures**::
+* link:RSPEC#troubleshooting[RSpec troubleshooting]
+* link:CHARACTER_VISUALIZATION[Character visualization]
+* link:INPUT_VALIDATION[Input validation]
+=== By format
+**XML**::
+* link:FORMATS#xml-format[XML format details]
+* link:RUBY_API[Ruby API] (all examples include XML)
+* link:MODES[Diff modes] (by-object default, by-line optional)
+**HTML**::
+* link:FORMATS#html-format[HTML format details]
+* link:MODES#by-line-mode[By-line mode] (HTML always uses this)
+**JSON**::
+* link:FORMATS#json-format[JSON format details]
+* link:MODES#by-object-mode[By-object mode] (JSON default)
+**YAML**::
+* link:FORMATS#yaml-format[YAML format details]
+* link:MODES#by-object-mode[By-object mode] (YAML default)
+== Contributing to documentation
+=== Documentation style guidelines
+When updating Canon documentation, follow these principles:
+**Heading style**::
+* Use sentence-case for all headings (e.g., "Match architecture", not "Match
+Architecture")
+* Use descriptive, clear headings that indicate content scope
+**Structure**::
+* Begin with a Scope section explaining what the document covers
+* Include a General section for background and key concepts
+* Organize content into logical sections with clear hierarchy
+* Use "See also" section at the end for cross-references
+**MECE principle**::
+* **Mutually Exclusive**: Each document covers a distinct topic without
+overlap
+* **Collectively Exhaustive**: All topics covered without gaps
+* Avoid duplicate information across documents
+**Examples and code**::
+* Wrap examples with `[example]` and `====` delimiters
+* Use `[source,lang]` with `----` delimiters for code blocks
+* Provide clear example titles describing what is shown
+* Include explanation after code examples
+* Use practical, real-world examples when possible
+**Lists**::
+* Separate lists from surrounding content with blank lines before and after
+* Ordered lists: Use `. ` flush with the line beginning
+* Unordered lists: Use `* ` flush with the line beginning
+* Second-level ordered: Use `.. `
+* Second-level unordered: Use `** `
+* Definition lists: Use `term:: description` format
+**Line length and formatting**::
+* Wrap lines at 80 characters
+* Exceptions: Cross-references, formulas, and code blocks
+* No "hanging paragraphs" - if needed, create a "General" subsection
+**Cross-references**::
+* Link to related documents using `link:DOCUMENT[Link text]`
+* Include "See also" section listing related documentation
+* Reference specific sections using anchors where appropriate
+**File organization**::
+* Each file uses `:toc:` and `:toclevels: 3` for navigation
+* Keep files focused on a single topic
+* Aim for 200-500 lines per document (except comprehensive references)
+=== Content guidelines
+**Clarity**::
+* Write in clear, technical prose
+* Define terms when first introduced
+* Use consistent terminology throughout
+**Completeness**::
+* Provide complete syntax definitions
+* Include "Where," legend explaining syntax elements
+* Show both basic and advanced usage
+**Accuracy**::
+* Verify all code examples work correctly
+* Ensure cross-references point to existing documents
+* Keep documentation synchronized with code changes
+**Accessibility**::
+* Write for users with varying expertise levels
+* Progress from simple to complex topics
+* Link to prerequisite knowledge