canon 0.1.6 → 0.1.7

data/lib/canon/options/registry.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+require_relative "../comparison/match_options"
+
+module Canon
+  module Options
+    # Centralized registry for all Canon options
+    # This is the SINGLE SOURCE OF TRUTH for option definitions
+    # All interfaces (CLI, Ruby API, RSpec) auto-generate from this registry
+    class Registry
+      class << self
+        # Get all option definitions
+        def all_options
+          @all_options ||= [
+            preprocessing_option,
+            diff_algorithm_option,
+            diff_mode_option,
+            *match_dimension_options,
+            match_profile_option,
+            *diff_formatting_options,
+          ].freeze
+        end
+
+        # Get options applicable to a specific format
+        def options_for_format(format)
+          all_options.select do |opt|
+            opt[:applies_to].nil? || opt[:applies_to].include?(format)
+          end
+        end
+
+        # Validate options hash against registry
+        def validate_options!(opts, format)
+          valid_option_names = options_for_format(format).map { |o| o[:name] }
+          invalid = opts.keys - valid_option_names
+          return if invalid.empty?
+
+          raise Canon::Error,
+                "Invalid options for #{format}: #{invalid.join(', ')}"
+        end
+
+        # Get CLI flag name for an option
+        def cli_flag_for(option_name)
+          opt = all_options.find { |o| o[:name] == option_name }
+          opt&.dig(:cli_flag)
+        end
+
+        # Get default value for an option
+        def default_for(option_name, format = nil)
+          opt = all_options.find { |o| o[:name] == option_name }
+          return nil unless opt
+
+          # Check for format-specific default
+          if format && opt[:format_defaults]&.key?(format)
+            opt[:format_defaults][format]
+          else
+            opt[:default]
+          end
+        end
+
+        private
+
+        # Preprocessing option
+        def preprocessing_option
+          {
+            name: :preprocessing,
+            type: :enum,
+            values: %w[none c14n normalize format],
+            default: :none,
+            cli_flag: "--preprocessing",
+            description: "Preprocessing: none, c14n, normalize, or format",
+            applies_to: %i[xml html json yaml],
+          }
+        end
+
+        # Diff algorithm option (NEW)
+        def diff_algorithm_option
+          {
+            name: :diff_algorithm,
+            type: :enum,
+            values: %w[dom semantic],
+            default: :dom,
+            cli_flag: "--diff-algorithm",
+            aliases: ["-a"],
+            description: "Diff algorithm: dom (positional) or semantic (tree-based)",
+            applies_to: %i[xml html json yaml],
+          }
+        end
+
+        # Diff mode option (replaces --by-line flag)
+        def diff_mode_option
+          {
+            name: :diff_mode,
+            type: :enum,
+            values: %w[by_line by_object],
+            default: :by_object,
+            format_defaults: {
+              html: :by_line,
+            },
+            cli_flag: "--diff-mode",
+            description: "Diff output mode: by_line or by_object",
+            applies_to: %i[xml html json yaml],
+          }
+        end
+
+        # Match profile option
+        def match_profile_option
+          {
+            name: :match_profile,
+            type: :enum,
+            values: Canon::Comparison::MatchOptions::MATCH_PROFILES.keys.map(&:to_s),
+            default: nil,
+            cli_flag: "--match-profile",
+            aliases: ["-p"],
+            description: "Match profile: strict, rendered, spec_friendly, or content_only",
+            applies_to: %i[xml html json yaml],
+          }
+        end
+
+        # Match dimension options (generated from MatchOptions)
+        def match_dimension_options
+          Canon::Comparison::MatchOptions::MATCH_DIMENSIONS.map do |dim|
+            {
+              name: dim,
+              type: :enum,
+              values: behaviors_for_dimension(dim),
+              default: nil,
+              format_defaults: format_defaults_for_dimension(dim),
+              cli_flag: "--#{dim.to_s.tr('_', '-')}",
+              description: "#{dimension_description(dim)}: #{behaviors_for_dimension(dim).join(', ')}",
+              applies_to: applicable_formats_for_dimension(dim),
+            }
+          end
+        end
+
+        # Diff formatting options
+        def diff_formatting_options
+          [
+            {
+              name: :color,
+              type: :boolean,
+              default: true,
+              cli_flag: "--color",
+              description: "Colorize diff output",
+              applies_to: %i[xml html json yaml],
+            },
+            {
+              name: :verbose,
+              type: :boolean,
+              default: false,
+              cli_flag: "--verbose",
+              aliases: ["-v"],
+              description: "Show detailed differences",
+              applies_to: %i[xml html json yaml],
+            },
+            {
+              name: :context_lines,
+              type: :numeric,
+              default: 3,
+              cli_flag: "--context-lines",
+              description: "Number of context lines around changes",
+              applies_to: %i[xml html json yaml],
+            },
+            {
+              name: :diff_grouping_lines,
+              type: :numeric,
+              default: nil,
+              cli_flag: "--diff-grouping-lines",
+              description: "Group diffs within N lines into context blocks",
+              applies_to: %i[xml html json yaml],
+            },
+          ]
+        end
+
+        # Get valid behaviors for a dimension
+        def behaviors_for_dimension(dimension)
+          case dimension
+          when :key_order, :attribute_order,
+               :element_structure, :element_position, :element_hierarchy
+            %w[strict ignore]
+          else
+            %w[strict normalize ignore]
+          end
+        end
+
+        # Get format defaults for a dimension from MatchOptions
+        def format_defaults_for_dimension(dimension)
+          Canon::Comparison::MatchOptions::FORMAT_DEFAULTS
+            .transform_values { |v| v[dimension] }
+            .compact
+        end
+
+        # Get applicable formats for a dimension
+        def applicable_formats_for_dimension(dimension)
+          case dimension
+          when :attribute_whitespace, :attribute_order, :attribute_values
+            %i[xml html]
+          when :key_order
+            %i[json yaml]
+          else
+            %i[xml html json yaml]
+          end
+        end
+
+        # Get human-readable description for a dimension
+        def dimension_description(dimension)
+          case dimension
+          when :text_content
+            "Text content matching"
+          when :structural_whitespace
+            "Structural whitespace matching"
+          when :attribute_whitespace
+            "Attribute whitespace matching (XML/HTML only)"
+          when :attribute_order
+            "Attribute ordering (XML/HTML only)"
+          when :attribute_values
+            "Attribute value matching (XML/HTML only)"
+          when :key_order
+            "Key ordering (JSON/YAML only)"
+          when :comments
+            "Comment matching"
+          when :element_structure
+            "Element type/structure matching (semantic diff)"
+          when :element_position
+            "Element position/order matching (semantic diff)"
+          when :element_hierarchy
+            "Element hierarchy/parent-child matching (semantic diff)"
+          else
+            dimension.to_s.tr("_", " ").capitalize
+          end
+        end
+      end
+    end
+  end
+end

data/lib/canon/rspec_matchers.rb

@@ -44,12 +44,23 @@ module Canon
     # This is a THIN WRAPPER around Canon::Comparison API
     class SerializationMatcher
       def initialize(expected, format = nil, match_profile: nil,
-                     match: nil, preprocessing: nil)
+                     match: nil, preprocessing: nil, diff_algorithm: nil,
+                     show_diffs: nil)
         @expected = expected
         @format = format&.to_sym
         @match_profile = match_profile
         @match = match
         @preprocessing = preprocessing
+        @diff_algorithm = diff_algorithm
+        @show_diffs = show_diffs
+      end
+
+      # Chain method for controlling diff display
+      # @param value [Symbol, String] :all, :normative, or :informative
+      # @return [SerializationMatcher] self for chaining
+      def show_diffs(value)
+        @show_diffs = value.to_sym
+        self
       end
 
       def matches?(target)
@@ -134,6 +145,8 @@ module Canon
         opts[:match_profile] = @match_profile if @match_profile
         opts[:match] = @match if @match
         opts[:preprocessing] = @preprocessing if @preprocessing
+        opts[:diff_algorithm] = @diff_algorithm if @diff_algorithm
+        opts[:show_diffs] = @show_diffs if @show_diffs
 
         # Add global configuration from Canon::Config (lower priority)
         if @format
@@ -151,6 +164,8 @@ module Canon
                 format_config.match.options
             end
             opts[:preprocessing] ||= format_config.preprocessing
+            # Add diff algorithm from config if not explicitly set
+            opts[:diff_algorithm] ||= format_config.diff.algorithm if format_config.diff.algorithm
           elsif !%i[xml html html4 html5 json yaml
                     string].include?(@format)
             # Unsupported format - raise error early
@@ -211,27 +226,30 @@ module Canon
     # Matcher methods
     def be_serialization_equivalent_to(expected, format: :xml,
                                       match_profile: nil, match: nil,
-                                      preprocessing: nil)
+                                      preprocessing: nil, diff_algorithm: nil)
       SerializationMatcher.new(expected, format,
                                match_profile: match_profile,
                                match: match,
-                               preprocessing: preprocessing)
+                               preprocessing: preprocessing,
+                               diff_algorithm: diff_algorithm)
     end
 
     def be_analogous_with(expected, match_profile: nil, match: nil,
-                         preprocessing: nil)
+                         preprocessing: nil, diff_algorithm: nil)
       SerializationMatcher.new(expected, :xml,
                                match_profile: match_profile,
                                match: match,
-                               preprocessing: preprocessing)
+                               preprocessing: preprocessing,
+                               diff_algorithm: diff_algorithm)
     end
 
     def be_xml_equivalent_to(expected, match_profile: nil, match: nil,
-                            preprocessing: nil)
+                            preprocessing: nil, diff_algorithm: nil)
       SerializationMatcher.new(expected, :xml,
                                match_profile: match_profile,
                                match: match,
-                               preprocessing: preprocessing)
+                               preprocessing: preprocessing,
+                               diff_algorithm: diff_algorithm)
     end
 
     def be_yaml_equivalent_to(expected)
@@ -243,27 +261,30 @@ module Canon
     end
 
     def be_html_equivalent_to(expected, match_profile: nil, match: nil,
-                             preprocessing: nil)
+                             preprocessing: nil, diff_algorithm: nil)
       SerializationMatcher.new(expected, :html,
                                match_profile: match_profile,
                                match: match,
-                               preprocessing: preprocessing)
+                               preprocessing: preprocessing,
+                               diff_algorithm: diff_algorithm)
     end
 
     def be_html4_equivalent_to(expected, match_profile: nil, match: nil,
-                              preprocessing: nil)
+                              preprocessing: nil, diff_algorithm: nil)
       SerializationMatcher.new(expected, :html4,
                                match_profile: match_profile,
                                match: match,
-                               preprocessing: preprocessing)
+                               preprocessing: preprocessing,
+                               diff_algorithm: diff_algorithm)
     end
 
     def be_html5_equivalent_to(expected, match_profile: nil, match: nil,
-                              preprocessing: nil)
+                              preprocessing: nil, diff_algorithm: nil)
       SerializationMatcher.new(expected, :html5,
                                match_profile: match_profile,
                                match: match,
-                               preprocessing: preprocessing)
+                               preprocessing: preprocessing,
+                               diff_algorithm: diff_algorithm)
     end
 
     def be_equivalent_to(expected)

data/lib/canon/tree_diff/adapters/html_adapter.rb

@@ -0,0 +1,316 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Canon
+  module TreeDiff
+    module Adapters
+      # HTMLAdapter converts Nokogiri HTML documents to TreeNode structures
+      # and back, enabling semantic tree diffing on HTML documents.
+      #
+      # This adapter:
+      # - Converts Nokogiri::HTML::Document to TreeNode tree
+      # - Preserves element names, text content, and attributes
+      # - Handles HTML-specific elements (script, style, etc.)
+      # - Maintains document structure for round-trip conversion
+      #
+      # @example Convert HTML to TreeNode
+      #   html = Nokogiri::HTML("<html><body><p>text</p></body></html>")
+      #   adapter = HTMLAdapter.new
+      #   tree = adapter.to_tree(html)
+      #
+      class HTMLAdapter
+        attr_reader :match_options
+
+        # Initialize adapter with match options
+        #
+        # @param match_options [Hash] Match options for text/attribute normalization
+        def initialize(match_options: {})
+          @match_options = match_options
+        end
+
+        # Convert Nokogiri HTML document/element or Canon::Xml::Node to TreeNode
+        #
+        # @param node [Nokogiri::HTML::Document, Nokogiri::XML::Element, Nokogiri::HTML::DocumentFragment, Canon::Xml::Node] HTML node
+        # @return [Core::TreeNode] Root tree node
+        def to_tree(node)
+          # Handle Canon::Xml::Node types first (same as XML adapter)
+          case node
+          when Canon::Xml::Nodes::RootNode
+            return to_tree_from_canon_root(node)
+          when Canon::Xml::Nodes::ElementNode
+            return to_tree_from_canon_element(node)
+          when Canon::Xml::Nodes::TextNode
+            return to_tree_from_canon_text(node)
+          when Canon::Xml::Nodes::CommentNode
+            return to_tree_from_canon_comment(node)
+          end
+
+          # Fallback to Nokogiri (legacy support)
+          case node
+          when Nokogiri::HTML::Document, Nokogiri::HTML4::Document, Nokogiri::HTML5::Document
+            # Start from html element or root element
+            root = node.at_css("html") || node.root
+            root ? to_tree(root) : nil
+          when Nokogiri::HTML4::DocumentFragment, Nokogiri::HTML5::DocumentFragment, Nokogiri::XML::DocumentFragment
+            # For DocumentFragment, create a wrapper root node and add all fragment children
+            convert_fragment(node)
+          when Nokogiri::XML::Element
+            convert_element(node)
+          else
+            raise ArgumentError, "Unsupported node type: #{node.class}"
+          end
+        end
+
+        # Convert TreeNode back to Nokogiri HTML
+        #
+        # @param tree_node [Core::TreeNode] Root tree node
+        # @param doc [Nokogiri::HTML::Document] Optional document to use
+        # @return [Nokogiri::HTML::Document, Nokogiri::XML::Element]
+        def from_tree(tree_node, doc = nil)
+          doc ||= Nokogiri::HTML::Document.new
+
+          element = build_element(tree_node, doc)
+
+          if doc.root.nil?
+            doc.root = element
+            doc
+          else
+            element
+          end
+        end
+
+        private
+
+        # Convert a DocumentFragment to TreeNode
+        # Creates a synthetic root node containing the fragment's children
+        #
+        # @param fragment [Nokogiri::HTML::DocumentFragment] HTML fragment
+        # @return [Core::TreeNode] Root tree node
+        def convert_fragment(fragment)
+          # Create a synthetic root node for the fragment
+          root = Core::TreeNode.new(
+            label: "fragment",
+            value: nil,
+            attributes: {},
+            source_node: fragment,
+          )
+
+          # Add all fragment children as children of the root
+          fragment.element_children.each do |child|
+            child_node = convert_element(child)
+            root.add_child(child_node)
+          end
+
+          root
+        end
+
+        # Convert a Nokogiri element to TreeNode
+        #
+        # @param element [Nokogiri::XML::Element] HTML element
+        # @return [Core::TreeNode] Tree node
+        def convert_element(element)
+          # Get element name (lowercase for HTML)
+          label = element.name.downcase
+
+          # Collect attributes (preserve original order for tree diff)
+          # The tree diff will detect attribute order differences
+          # and classify them as informative when attribute_order: ignore
+          #
+          # CRITICAL FIX: Filter out xmlns attributes for HTML documents
+          # These are typically added by parsers (e.g., MS Word) and aren't
+          # semantically significant for HTML comparison. Keeping them causes
+          # false mismatches that prevent the entire subtree from matching due
+          # to prefix closure constraints.
+          attributes = {}
+          element.attributes.each do |name, attr|
+            # Skip xmlns namespace declarations for HTML (but keep regular attributes)
+            # This prevents false mismatches caused by parser-added namespace declarations
+            next if name.start_with?("xmlns")
+
+            attributes[name] = attr.value
+          end
+
+          # Get text content (only direct text, not from children)
+          text_value = extract_text_value(element)
+
+          # Create tree node with source_node reference
+          tree_node = Core::TreeNode.new(
+            label: label,
+            value: text_value,
+            attributes: attributes,
+            source_node: element,
+          )
+
+          # Process child elements
+          element.element_children.each do |child|
+            child_node = convert_element(child)
+            tree_node.add_child(child_node)
+          end
+
+          tree_node
+        end
+
+        # Extract direct text content from element
+        #
+        # Preserves original text for proper normalization during comparison.
+        # Normalization happens in OperationDetector based on match_options,
+        # NOT during tree conversion.
+        #
+        # For mixed content (text nodes + child elements), joins text nodes
+        # with a space to prevent text from running together when elements
+        # like <br/> separate the text.
+        #
+        # @param element [Nokogiri::XML::Element] HTML element
+        # @return [String, nil] Text content or nil
+        def extract_text_value(element)
+          # Get only direct text nodes, not from nested elements
+          text_nodes = element.children.select(&:text?)
+
+          # For mixed content (has both text nodes and element children),
+          # join text nodes with space to handle implicit whitespace around
+          # block-level elements like <br/>
+          # Example: "Text<br/>More" should become "Text More" not "TextMore"
+          # EXCEPT for whitespace-sensitive elements (<pre>, <code>, etc.)
+          # where we must preserve exact whitespace
+          separator = if element.element_children.any? && !whitespace_sensitive?(element)
+                        " "
+                      else
+                        ""
+                      end
+          text = text_nodes.map(&:text).join(separator)
+
+          # CRITICAL FIX: Return original text without stripping
+          # Normalization will be applied during comparison based on match_options
+          # Only return nil for truly empty text
+          text.empty? ? nil : text
+        end
+
+        # Check if an element is whitespace-sensitive
+        #
+        # HTML elements where whitespace is significant: <pre>, <code>, <textarea>, <script>, <style>
+        #
+        # @param element [Nokogiri::XML::Element] Element to check
+        # @return [Boolean] True if element is whitespace-sensitive
+        def whitespace_sensitive?(element)
+          return false unless element.respond_to?(:name)
+
+          # List of HTML elements where whitespace is semantically significant
+          whitespace_sensitive_tags = %w[pre code textarea script style]
+          whitespace_sensitive_tags.include?(element.name.downcase)
+        end
+
+        # Build Nokogiri element from TreeNode
+        #
+        # @param tree_node [Core::TreeNode] Tree node
+        # @param doc [Nokogiri::HTML::Document] Document
+        # @return [Nokogiri::XML::Element] HTML element
+        def build_element(tree_node, doc)
+          element = Nokogiri::XML::Element.new(tree_node.label, doc)
+
+          # Add attributes
+          tree_node.attributes.each do |name, value|
+            element[name] = value
+          end
+
+          # Add text content if present
+          if tree_node.value && !tree_node.value.empty?
+            element.content = tree_node.value
+          end
+
+          # Add child elements
+          tree_node.children.each do |child|
+            child_element = build_element(child, doc)
+            element.add_child(child_element)
+          end
+
+          element
+        end
+
+        # Convert Canon::Xml::Nodes::RootNode to TreeNode
+        #
+        # @param root_node [Canon::Xml::Nodes::RootNode] Root node
+        # @return [Core::TreeNode, nil] Tree node for first child (document element)
+        def to_tree_from_canon_root(root_node)
+          # Root node: process first child (document element)
+          return nil if root_node.children.empty?
+
+          to_tree(root_node.children.first)
+        end
+
+        # Convert Canon::Xml::Nodes::ElementNode to TreeNode
+        #
+        # @param element_node [Canon::Xml::Nodes::ElementNode] Element node
+        # @return [Core::TreeNode] Tree node
+        def to_tree_from_canon_element(element_node)
+          # Create TreeNode from Canon::Xml::Nodes::ElementNode
+          tree_node = Core::TreeNode.new(
+            label: element_node.name.downcase, # Lowercase for HTML
+            value: nil, # Elements don't have values
+            attributes: extract_canon_attributes(element_node),
+            children: [],
+            source_node: element_node, # Preserve reference to Canon node
+          )
+
+          # Process children recursively
+          element_node.children.each do |child|
+            child_tree = to_tree(child)
+            tree_node.add_child(child_tree) if child_tree
+          end
+
+          tree_node
+        end
+
+        # Convert Canon::Xml::Nodes::TextNode to TreeNode
+        #
+        # @param text_node [Canon::Xml::Nodes::TextNode] Text node
+        # @return [Core::TreeNode, nil] Tree node or nil for empty text
+        def to_tree_from_canon_text(text_node)
+          # Extract text value
+          text_value = text_node.value.to_s
+
+          # Return nil for empty text (don't strip for HTML)
+          return nil if text_value.empty?
+
+          Core::TreeNode.new(
+            label: "text",
+            value: text_value,
+            attributes: {},
+            children: [],
+            source_node: text_node,
+          )
+        end
+
+        # Convert Canon::Xml::Nodes::CommentNode to TreeNode
+        #
+        # @param comment_node [Canon::Xml::Nodes::CommentNode] Comment node
+        # @return [Core::TreeNode] Tree node
+        def to_tree_from_canon_comment(comment_node)
+          Core::TreeNode.new(
+            label: "comment",
+            value: comment_node.value,
+            attributes: {},
+            children: [],
+            source_node: comment_node,
+          )
+        end
+
+        # Extract attributes from Canon::Xml::Nodes::ElementNode
+        #
+        # @param element_node [Canon::Xml::Nodes::ElementNode] Element node
+        # @return [Hash] Attributes hash (preserves order, filters xmlns)
+        def extract_canon_attributes(element_node)
+          # Canon::Xml::Nodes::ElementNode has attribute_nodes array
+          attrs = {}
+          element_node.attribute_nodes.each do |attr|
+            # Skip xmlns attributes for HTML (like Nokogiri path)
+            next if attr.name.start_with?("xmlns")
+
+            attrs[attr.name] = attr.value
+          end
+          attrs
+        end
+      end
+    end
+  end
+end