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/INPUT_VALIDATION.adoc ADDED Viewed

@@ -0,0 +1,477 @@
+---
+layout: default
+title: Input Validation
+nav_order: 33
+parent: Customizing Behavior
+---
+= Canon input validation
+:toc:
+:toclevels: 3
+== Scope
+This document describes Canon's input validation system for XML, HTML, JSON,
+and YAML formats. Validation ensures malformed input is detected early with
+clear error messages.
+For format support details, see link:FORMATS[Format support].
+== General
+Canon validates input before processing and raises `Canon::ValidationError`
+for malformed input. Validation provides:
+* **Early error detection**: Problems caught before processing begins
+* **Precise error location**: Line and column numbers pinpoint the problem
+* **Clear error messages**: Descriptive messages explain what's wrong
+* **Test-friendly**: Errors appear in RSpec output, not hidden in log files
+== How validation works
+Canon validates input **before parsing** using format-specific validators:
+* `Canon::Validators::XmlValidator` - Strict XML syntax validation
+* `Canon::Validators::HtmlValidator` - HTML5 and XHTML validation
+* `Canon::Validators::JsonValidator` - JSON syntax validation
+* `Canon::Validators::YamlValidator` - YAML syntax validation
+Validation happens automatically when you use Canon's formatters or
+comparison methods.
+== Validation error format
+When validation fails, Canon raises `Canon::ValidationError` with:
+`format`:: The format being validated (`:xml`, `:html`, `:json`, `:yaml`)
+`line`:: Line number where the error occurred (if available)
+`column`:: Column number where the error occurred (if available)
+`details`:: Additional context about the error
+.Validation error structure
+[example]
+====
+[source,ruby]
+----
+begin
+  Canon.format(malformed_xml, :xml)
+rescue Canon::ValidationError => e
+  puts e.message
+  # => XML Validation Error: Premature end of data in tag unclosed line 1
+  #    Line: 1
+  #    Column: 18
+  puts "Format: #{e.format}"     # => :xml
+  puts "Line: #{e.line}"          # => 1
+  puts "Column: #{e.column}"      # => 18
+end
+----
+====
+== Format-specific validation
+=== XML validation
+Uses Nokogiri's strict XML parsing to detect:
+* Unclosed tags
+* Mismatched tags
+* Invalid XML declaration
+* Malformed attributes
+* Invalid character references
+.XML validation examples
+[example]
+====
+**Unclosed tag**:
+[source,ruby]
+----
+Canon.format('<root><item>', :xml)
+# => Canon::ValidationError: XML Validation Error: Premature end of data in tag item line 1
+#    Line: 1
+----
+**Mismatched tags**:
+[source,ruby]
+----
+Canon.format('<root><item></root>', :xml)
+# => Canon::ValidationError: XML Validation Error: Opening and ending tag mismatch: item line 1 and root
+#    Line: 1
+----
+**Invalid character reference**:
+[source,ruby]
+----
+Canon.format('<root>&#xGGGG;</root>', :xml)
+# => Canon::ValidationError: XML Validation Error: xmlParseCharRef: invalid hexadecimal value
+#    Line: 1
+----
+====
+=== HTML validation
+Automatically detects HTML5 vs XHTML and applies appropriate validation:
+* **HTML5**: Uses Nokogiri::HTML5 parser with error filtering
+* **XHTML**: Uses strict XML parsing
+**Special handling**:
+* Strips XML declarations from HTML (common in legacy HTML files)
+* Filters out non-critical HTML5 parser warnings
+* Only reports significant errors (level 2+)
+.HTML validation examples
+[example]
+====
+**Malformed XHTML**:
+[source,ruby]
+----
+xhtml = '<html xmlns="http://www.w3.org/1999/xhtml"><body><p>Unclosed'
+Canon.format(xhtml, :html)
+# => Canon::ValidationError: HTML Validation Error: Premature end of data in tag p line 1
+#    Line: 1
+----
+**HTML5 with errors**:
+[source,ruby]
+----
+html5 = '<div><span></div>'
+Canon.format(html5, :html)
+# => Canon::ValidationError: HTML Validation Error: Unexpected end tag : span
+#    Line: 1
+----
+**Valid HTML** (no error):
+[source,ruby]
+----
+html = '<!DOCTYPE html><html><body><p>Content</p></body></html>'
+Canon.format(html, :html)
+# => Successfully formatted
+----
+====
+=== JSON validation
+Validates JSON syntax using Ruby's JSON parser:
+* Missing/extra braces or brackets
+* Trailing commas
+* Invalid escape sequences
+* Invalid numbers
+Provides context showing the error location in the JSON structure.
+.JSON validation examples
+[example]
+====
+**Missing closing brace**:
+[source,ruby]
+----
+Canon.format('{"key": "value"', :json)
+# => Canon::ValidationError: JSON Validation Error: unexpected token at '{"key": "value"'
+#    Details: Error at position 16
+----
+**Trailing comma** (invalid in JSON):
+[source,ruby]
+----
+Canon.format('{"a": 1,}', :json)
+# => Canon::ValidationError: JSON Validation Error: unexpected token at '{"a": 1,}'
+#    Details: Error at position 8
+----
+**Invalid number**:
+[source,ruby]
+----
+Canon.format('{"value": 01}', :json)
+# => Canon::ValidationError: JSON Validation Error: unexpected token
+----
+**Valid JSON** (no error):
+[source,ruby]
+----
+Canon.format('{"key": "value"}', :json)
+# => Successfully formatted
+----
+====
+=== YAML validation
+Validates YAML syntax using Psych (Ruby's YAML parser):
+* Invalid indentation
+* Unclosed brackets/braces
+* Invalid anchors/aliases
+* Type mismatches
+Shows error location with line numbers and context.
+.YAML validation examples
+[example]
+====
+**Unclosed bracket**:
+[source,ruby]
+----
+Canon.format("key: {unclosed", :yaml)
+# => Canon::ValidationError: YAML Validation Error: (<unknown>): did not find expected node content...
+#    Line: 1
+#    Details: Shows context around error
+----
+**Invalid indentation**:
+[source,ruby]
+----
+yaml = <<~YAML
+  parent:
+  child: value
+YAML
+Canon.format(yaml, :yaml)
+# => Canon::ValidationError: YAML Validation Error: mapping values are not allowed in this context
+#    Line: 2
+----
+**Valid YAML** (no error):
+[source,ruby]
+----
+yaml = "key: value\nlist:\n  - item1\n  - item2"
+Canon.format(yaml, :yaml)
+# => Successfully formatted
+----
+====
+== Validation in RSpec tests
+Canon's RSpec matchers automatically propagate validation errors to test
+output, making it easy to see what's wrong.
+.RSpec validation error example
+[example]
+====
+[source,ruby]
+----
+require 'canon/rspec_matchers'
+RSpec.describe 'XML validation' do
+  it 'validates input' do
+    malformed_xml = '<root><unclosed>'
+    expected_xml = '<root><item/></root>'
+    # This will fail with a clear validation error message
+    expect(malformed_xml).to be_xml_equivalent_to(expected_xml)
+  end
+end
+# Test output shows:
+# Canon::ValidationError:
+#   XML Validation Error: Premature end of data in tag unclosed line 1
+#     Line: 1
+#     Column: 18
+----
+The error appears directly in the RSpec output, not hidden in separate error
+files or logs.
+====
+== Validation in comparison
+Validation also occurs when using `Canon::Comparison.equivalent?`:
+.Comparison validation example
+[example]
+====
+[source,ruby]
+----
+require 'canon/comparison'
+xml1 = '<root><item/></root>'
+xml2 = '<root><unclosed>'
+Canon::Comparison.equivalent?(xml1, xml2)
+# => Canon::ValidationError: XML Validation Error: Premature end of data in tag unclosed line 1
+#    Line: 1
+#    Column: 18
+----
+====
+== Error handling strategies
+=== Basic error handling
+[source,ruby]
+----
+begin
+  Canon.format(input, :xml)
+rescue Canon::ValidationError => e
+  puts "Validation failed: #{e.message}"
+  puts "Line #{e.line}, Column #{e.column}" if e.line
+end
+----
+=== Format-specific handling
+[source,ruby]
+----
+begin
+  Canon.format(input, format)
+rescue Canon::ValidationError => e
+  case e.format
+  when :xml
+    handle_xml_error(e)
+  when :html
+    handle_html_error(e)
+  when :json
+    handle_json_error(e)
+  when :yaml
+    handle_yaml_error(e)
+  end
+end
+----
+=== Validation before processing
+[source,ruby]
+----
+def process_xml(xml_string)
+  # Validate early
+  begin
+    Canon.format(xml_string, :xml)
+  rescue Canon::ValidationError => e
+    log_validation_error(e)
+    return { error: e.message, line: e.line }
+  end
+  # Proceed with processing
+  process_valid_xml(xml_string)
+end
+----
+== Common validation errors
+=== XML common errors
+[cols="1,2,1"]
+|===
+|Error |Cause |Solution
+|Premature end of data
+|Unclosed tag
+|Close all tags
+|Tag mismatch
+|Opening/closing tags don't match
+|Match tag names exactly
+|Invalid character reference
+|Bad entity or character code
+|Use valid entities
+|Invalid XML declaration
+|Malformed `<?xml...?>` tag
+|Fix or remove declaration
+|===
+=== HTML common errors
+[cols="1,2,1"]
+|===
+|Error |Cause |Solution
+|Unexpected end tag
+|Mismatched or extra closing tag
+|Match opening/closing tags
+|Invalid DOCTYPE
+|Malformed document type declaration
+|Use standard DOCTYPE
+|Unclosed tag
+|Missing closing tag
+|Close all tags properly
+|Invalid attribute
+|Malformed attribute syntax
+|Fix attribute syntax
+|===
+=== JSON common errors
+[cols="1,2,1"]
+|===
+|Error |Cause |Solution
+|Unexpected token
+|Syntax error in JSON
+|Check JSON syntax
+|Trailing comma
+|Comma after last element
+|Remove trailing commas
+|Unclosed bracket/brace
+|Missing `]` or `}`
+|Close all brackets/braces
+|Invalid number
+|Leading zeros or invalid format
+|Use valid number format
+|===
+=== YAML common errors
+[cols="1,2,1"]
+|===
+|Error |Cause |Solution
+|Invalid indentation
+|Inconsistent indentation
+|Use consistent spaces
+|Unclosed bracket
+|Missing closing bracket
+|Close all brackets
+|Invalid anchor
+|Malformed anchor/alias
+|Fix anchor syntax
+|Type mismatch
+|Value doesn't match expected type
+|Fix value or type
+|===
+== Benefits
+**Early error detection**:: Problems caught before processing begins, saving
+time and providing clear feedback
+**Precise error location**:: Line and column numbers pinpoint exactly where
+the problem is, especially useful in large documents
+**Clear error messages**:: Descriptive messages explain what's wrong and
+often suggest how to fix it
+**Test-friendly**:: Errors appear in RSpec output where developers expect
+them, not in separate log files
+**Format-aware**:: Each validator understands format-specific rules and
+provides relevant error details
+== See also
+* link:FORMATS[Format support]
+* link:RUBY_API[Ruby API documentation]
+* link:RSPEC[RSpec matchers]
+* link:CLI[Command-line interface]