canon 0.1.6 → 0.1.7

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

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Canon
+  module TreeDiff
+    module Adapters
+      # JSONAdapter converts JSON objects to TreeNode structures and back,
+      # enabling semantic tree diffing on JSON documents.
+      #
+      # This adapter:
+      # - Converts Hash/Array JSON structures to TreeNode tree
+      # - Handles nested objects, arrays, and primitive values
+      # - Preserves type information for round-trip conversion
+      # - Maps JSON structure to tree representation
+      #
+      # JSON to TreeNode mapping:
+      # - Objects (Hash): TreeNode with label "object", children for each key
+      # - Arrays: TreeNode with label "array", indexed children
+      # - Primitives: TreeNode with label "value", value stored directly
+      #
+      # @example Convert JSON to TreeNode
+      #   json = { "name" => "John", "age" => 30 }
+      #   adapter = JSONAdapter.new
+      #   tree = adapter.to_tree(json)
+      #
+      class JSONAdapter
+        attr_reader :match_options
+
+        # Initialize adapter with match options
+        #
+        # @param match_options [Hash] Match options (for future use)
+        def initialize(match_options: {})
+          @match_options = match_options
+        end
+
+        # Convert JSON structure to TreeNode
+        #
+        # @param data [Hash, Array, String, Numeric, Boolean, nil] JSON data
+        # @param key [String, nil] Key name if this is a hash value
+        # @return [Core::TreeNode] Root tree node
+        def to_tree(data, key = nil)
+          case data
+          when Hash
+            convert_object(data, key)
+          when Array
+            convert_array(data, key)
+          else
+            convert_value(data, key)
+          end
+        end
+
+        # Convert TreeNode back to JSON structure
+        #
+        # @param tree_node [Core::TreeNode] Root tree node
+        # @return [Hash, Array, Object] JSON structure
+        def from_tree(tree_node)
+          case tree_node.label
+          when "object"
+            build_object(tree_node)
+          when "array"
+            build_array(tree_node)
+          when "value"
+            parse_value(tree_node)
+          else
+            # Fallback for custom labels
+            tree_node.value
+          end
+        end
+
+        private
+
+        # Convert JSON object (Hash) to TreeNode
+        #
+        # @param hash [Hash] JSON object
+        # @param key [String, nil] Key name if this is nested
+        # @return [Core::TreeNode] Tree node
+        def convert_object(hash, key = nil)
+          attributes = key ? { "key" => key } : {}
+
+          tree_node = Core::TreeNode.new(
+            label: "object",
+            value: nil,
+            attributes: attributes,
+          )
+
+          hash.each do |k, v|
+            child = to_tree(v, k.to_s)
+            tree_node.add_child(child)
+          end
+
+          tree_node
+        end
+
+        # Convert JSON array to TreeNode
+        #
+        # @param array [Array] JSON array
+        # @param key [String, nil] Key name if this is nested
+        # @return [Core::TreeNode] Tree node
+        def convert_array(array, key = nil)
+          attributes = key ? { "key" => key } : {}
+
+          tree_node = Core::TreeNode.new(
+            label: "array",
+            value: nil,
+            attributes: attributes,
+          )
+
+          array.each_with_index do |item, index|
+            child = to_tree(item, index.to_s)
+            tree_node.add_child(child)
+          end
+
+          tree_node
+        end
+
+        # Convert primitive value to TreeNode
+        #
+        # @param value [String, Numeric, Boolean, nil] Primitive value
+        # @param key [String, nil] Key name
+        # @return [Core::TreeNode] Tree node
+        def convert_value(value, key = nil)
+          attributes = {}
+          attributes["key"] = key if key
+          attributes["type"] = value_type(value)
+
+          Core::TreeNode.new(
+            label: "value",
+            value: value.to_s,
+            attributes: attributes,
+          )
+        end
+
+        # Determine value type
+        #
+        # @param value [Object] Value
+        # @return [String] Type name
+        def value_type(value)
+          case value
+          when String then "string"
+          when Integer then "integer"
+          when Float then "float"
+          when TrueClass, FalseClass then "boolean"
+          when NilClass then "null"
+          else "unknown"
+          end
+        end
+
+        # Build Hash from object TreeNode
+        #
+        # @param tree_node [Core::TreeNode] Object tree node
+        # @return [Hash] Reconstructed hash
+        def build_object(tree_node)
+          hash = {}
+
+          tree_node.children.each do |child|
+            key = child.attributes["key"]
+            hash[key] = from_tree(child) if key
+          end
+
+          hash
+        end
+
+        # Build Array from array TreeNode
+        #
+        # @param tree_node [Core::TreeNode] Array tree node
+        # @return [Array] Reconstructed array
+        def build_array(tree_node)
+          array = []
+
+          tree_node.children.each do |child|
+            array << from_tree(child)
+          end
+
+          array
+        end
+
+        # Parse value from value TreeNode
+        #
+        # @param tree_node [Core::TreeNode] Value tree node
+        # @return [Object] Parsed value
+        def parse_value(tree_node)
+          type = tree_node.attributes["type"]
+          value_str = tree_node.value
+
+          case type
+          when "string"
+            value_str
+          when "integer"
+            value_str.to_i
+          when "float"
+            value_str.to_f
+          when "boolean"
+            value_str == "true"
+          when "null"
+            nil
+          else
+            value_str
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,285 @@
+# frozen_string_literal: true
+
+require "nokogiri"
+
+module Canon
+  module TreeDiff
+    module Adapters
+      # XMLAdapter converts Nokogiri XML documents to TreeNode structures
+      # and back, enabling semantic tree diffing on XML documents.
+      #
+      # This adapter:
+      # - Converts Nokogiri::XML::Document to TreeNode tree
+      # - Preserves element names, text content, and attributes
+      # - Handles namespaces appropriately
+      # - Maintains document structure for round-trip conversion
+      #
+      # @example Convert XML to TreeNode
+      #   xml = Nokogiri::XML("<root><child>text</child></root>")
+      #   adapter = XMLAdapter.new
+      #   tree = adapter.to_tree(xml)
+      #
+      class XMLAdapter
+        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 XML document/element or Canon::Xml::Node to TreeNode
+        #
+        # @param node [Nokogiri::XML::Document, Nokogiri::XML::Element, Canon::Xml::Node] XML node
+        # @return [Core::TreeNode] Root tree node
+        def to_tree(node)
+          # Handle nil nodes
+          return nil if node.nil?
+
+          # Handle Canon::Xml::Node types first
+          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::XML::Document
+            # Start from root element
+            root = node.root
+            raise ArgumentError, "Document has no root element" if root.nil?
+
+            to_tree(root)
+          when Nokogiri::XML::Element
+            convert_element(node)
+          else
+            raise ArgumentError, "Unsupported node type: #{node.class}"
+          end
+        end
+
+        # Convert TreeNode back to Nokogiri XML
+        #
+        # @param tree_node [Core::TreeNode] Root tree node
+        # @param doc [Nokogiri::XML::Document] Optional document to use
+        # @return [Nokogiri::XML::Document, Nokogiri::XML::Element]
+        def from_tree(tree_node, doc = nil)
+          doc ||= Nokogiri::XML::Document.new
+
+          element = build_element(tree_node, doc)
+
+          if doc.root.nil?
+            doc.root = element
+            doc
+          else
+            element
+          end
+        end
+
+        private
+
+        # Convert a Nokogiri element to TreeNode
+        #
+        # @param element [Nokogiri::XML::Element] XML element
+        # @return [Core::TreeNode] Tree node
+        def convert_element(element)
+          # Get element name (with namespace prefix if present)
+          element.name
+
+          # Create label that includes namespace URI to ensure elements
+          # with different namespaces are treated as different nodes
+          # Format: {namespace_uri}name or just name if no namespace
+          namespace_uri = element.namespace&.href
+          label = if namespace_uri && !namespace_uri.empty?
+                    "{#{namespace_uri}}#{element.name}"
+                  else
+                    element.name
+                  end
+
+          # Collect attributes and sort them alphabetically
+          # This ensures attribute order doesn't affect hash matching
+          # (matches behavior of attribute_order: :ignore in match options)
+          attributes = {}
+          element.attributes.each do |name, attr|
+            attributes[name] = attr.value
+          end
+          # Sort attributes by key to normalize order
+          attributes = attributes.sort.to_h
+
+          # 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, # Preserve reference to original Nokogiri node
+          )
+
+          # 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] XML 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"
+          separator = element.element_children.any? ? " " : ""
+          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 or whitespace-only text
+          text.strip.empty? ? nil : text
+        end
+
+        # Build Nokogiri element from TreeNode
+        #
+        # @param tree_node [Core::TreeNode] Tree node
+        # @param doc [Nokogiri::XML::Document] Document
+        # @return [Nokogiri::XML::Element] XML 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 label that includes namespace URI to ensure elements
+          # with different namespaces are treated as different nodes
+          # Format: {namespace_uri}name or just name if no namespace
+          namespace_uri = element_node.namespace_uri
+          label = if namespace_uri && !namespace_uri.empty?
+                    "{#{namespace_uri}}#{element_node.name}"
+                  else
+                    element_node.name
+                  end
+
+          # Create TreeNode from Canon::Xml::Nodes::ElementNode
+          tree_node = Core::TreeNode.new(
+            label: label,
+            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 whitespace-only text
+        def to_tree_from_canon_text(text_node)
+          # Extract text value
+          text_value = text_node.value.to_s
+
+          # Return nil for whitespace-only text
+          return nil if text_value.strip.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 sorted by key
+        def extract_canon_attributes(element_node)
+          # Canon::Xml::Nodes::ElementNode has attribute_nodes array
+          attrs = {}
+          element_node.attribute_nodes.each do |attr|
+            attrs[attr.name] = attr.value
+          end
+          # Sort attributes by key to normalize order
+          attrs.sort.to_h
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,213 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Canon
+  module TreeDiff
+    module Adapters
+      # YAMLAdapter converts YAML structures to TreeNode structures and back,
+      # enabling semantic tree diffing on YAML documents.
+      #
+      # This adapter:
+      # - Converts Hash/Array YAML structures to TreeNode tree
+      # - Handles nested objects, arrays, and primitive values
+      # - Preserves type information for round-trip conversion
+      # - Maps YAML structure to tree representation
+      #
+      # YAML to TreeNode mapping (similar to JSON):
+      # - Objects (Hash): TreeNode with label "object", children for each key
+      # - Arrays: TreeNode with label "array", indexed children
+      # - Primitives: TreeNode with label "value", value stored directly
+      #
+      # @example Convert YAML to TreeNode
+      #   yaml = { "name" => "John", "age" => 30 }
+      #   adapter = YAMLAdapter.new
+      #   tree = adapter.to_tree(yaml)
+      #
+      class YAMLAdapter
+        attr_reader :match_options
+
+        # Initialize adapter with match options
+        #
+        # @param match_options [Hash] Match options (for future use)
+        def initialize(match_options: {})
+          @match_options = match_options
+        end
+
+        # Convert YAML structure to TreeNode
+        #
+        # @param data [Hash, Array, String, Numeric, Boolean, nil] YAML data
+        # @param key [String, nil] Key name if this is a hash value
+        # @return [Core::TreeNode] Root tree node
+        def to_tree(data, key = nil)
+          case data
+          when Hash
+            convert_object(data, key)
+          when Array
+            convert_array(data, key)
+          else
+            convert_value(data, key)
+          end
+        end
+
+        # Convert TreeNode back to YAML structure
+        #
+        # @param tree_node [Core::TreeNode] Root tree node
+        # @return [Hash, Array, Object] YAML structure
+        def from_tree(tree_node)
+          case tree_node.label
+          when "object"
+            build_object(tree_node)
+          when "array"
+            build_array(tree_node)
+          when "value"
+            parse_value(tree_node)
+          else
+            # Fallback for custom labels
+            tree_node.value
+          end
+        end
+
+        private
+
+        # Convert YAML object (Hash) to TreeNode
+        #
+        # @param hash [Hash] YAML object
+        # @param key [String, nil] Key name if this is nested
+        # @return [Core::TreeNode] Tree node
+        def convert_object(hash, key = nil)
+          attributes = key ? { "key" => key } : {}
+
+          tree_node = Core::TreeNode.new(
+            label: "object",
+            value: nil,
+            attributes: attributes,
+          )
+
+          hash.each do |k, v|
+            child = to_tree(v, k.to_s)
+            tree_node.add_child(child)
+          end
+
+          tree_node
+        end
+
+        # Convert YAML array to TreeNode
+        #
+        # @param array [Array] YAML array
+        # @param key [String, nil] Key name if this is nested
+        # @return [Core::TreeNode] Tree node
+        def convert_array(array, key = nil)
+          attributes = key ? { "key" => key } : {}
+
+          tree_node = Core::TreeNode.new(
+            label: "array",
+            value: nil,
+            attributes: attributes,
+          )
+
+          array.each_with_index do |item, index|
+            child = to_tree(item, index.to_s)
+            tree_node.add_child(child)
+          end
+
+          tree_node
+        end
+
+        # Convert primitive value to TreeNode
+        #
+        # @param value [String, Numeric, Boolean, nil] Primitive value
+        # @param key [String, nil] Key name
+        # @return [Core::TreeNode] Tree node
+        def convert_value(value, key = nil)
+          attributes = {}
+          attributes["key"] = key if key
+          attributes["type"] = value_type(value)
+
+          Core::TreeNode.new(
+            label: "value",
+            value: value.to_s,
+            attributes: attributes,
+          )
+        end
+
+        # Determine value type
+        #
+        # @param value [Object] Value
+        # @return [String] Type name
+        def value_type(value)
+          case value
+          when String then "string"
+          when Integer then "integer"
+          when Float then "float"
+          when TrueClass, FalseClass then "boolean"
+          when NilClass then "null"
+          when Symbol then "symbol"
+          when Date then "date"
+          when Time, DateTime then "time"
+          else "unknown"
+          end
+        end
+
+        # Build Hash from object TreeNode
+        #
+        # @param tree_node [Core::TreeNode] Object tree node
+        # @return [Hash] Reconstructed hash
+        def build_object(tree_node)
+          hash = {}
+
+          tree_node.children.each do |child|
+            key = child.attributes["key"]
+            hash[key] = from_tree(child) if key
+          end
+
+          hash
+        end
+
+        # Build Array from array TreeNode
+        #
+        # @param tree_node [Core::TreeNode] Array tree node
+        # @return [Array] Reconstructed array
+        def build_array(tree_node)
+          array = []
+
+          tree_node.children.each do |child|
+            array << from_tree(child)
+          end
+
+          array
+        end
+
+        # Parse value from value TreeNode
+        #
+        # @param tree_node [Core::TreeNode] Value tree node
+        # @return [Object] Parsed value
+        def parse_value(tree_node)
+          type = tree_node.attributes["type"]
+          value_str = tree_node.value
+
+          case type
+          when "string"
+            value_str
+          when "integer"
+            value_str.to_i
+          when "float"
+            value_str.to_f
+          when "boolean"
+            value_str == "true"
+          when "null"
+            nil
+          when "symbol"
+            value_str.to_sym
+          when "date"
+            Date.parse(value_str)
+          when "time"
+            Time.parse(value_str)
+          else
+            value_str
+          end
+        end
+      end
+    end
+  end
+end