svg_conform 0.1.6 → 0.1.8

data/lib/svg_conform/errors/base.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+module SvgConform
+  module Errors
+    # Base class for all SvgConform error types
+    #
+    # Provides common interface for error and notice objects
+    # used during validation.
+    class Base
+      attr_reader :type, :node, :message
+
+      # Initialize a new error/notice
+      #
+      # @param type [Symbol] The type (:error, :warning, :info, etc.)
+      # @param node [Object] The node associated with this error
+      # @param message [String] The error message
+      def initialize(type:, node:, message:)
+        @type = type
+        @node = node
+        @message = message
+      end
+
+      # Get the line number of the error
+      #
+      # @return [Integer, nil] The line number if available
+      def line
+        @node.respond_to?(:line) ? @node.line : nil
+      end
+
+      # Get the column number of the error
+      #
+      # @return [Integer, nil] The column number if available
+      def column
+        @node.respond_to?(:column) ? @node.column : nil
+      end
+
+      # Get the element name of the error
+      #
+      # @return [String, nil] The element name if available
+      def element_name
+        @node.respond_to?(:name) ? @node.name : nil
+      end
+
+      # Convert error to hash representation
+      #
+      # @return [Hash] Hash representation of the error
+      def to_h
+        {
+          type: @type,
+          message: @message,
+          line: line,
+          column: column,
+          element: element_name,
+        }
+      end
+    end
+  end
+end

data/lib/svg_conform/errors/validation_issue.rb

@@ -0,0 +1,245 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module SvgConform
+  module Errors
+    # Validation issue (error, warning, or notice)
+    #
+    # Represents a single validation issue found during SVG validation.
+    # Contains information about the issue including type, rule, node,
+    # message, fix, and remediation information.
+    class ValidationIssue < Base
+      attr_reader :rule, :fix, :data,
+                  :requirement_id_override, :severity, :violation_type
+
+      def initialize(type:, rule:, node:, message:, fix: nil, data: {},
+requirement_id: nil, severity: nil, violation_type: nil)
+        super(type: type, node: node, message: message)
+        @rule = rule
+        @fix = fix
+        @data = data
+        @requirement_id_override = requirement_id
+        @severity = severity
+        @violation_type = violation_type || detect_violation_type
+      end
+
+      def requirement_id
+        return @requirement_id_override.to_s if @requirement_id_override
+
+        if @rule.respond_to?(:id)
+          @rule.id.to_s
+        elsif @rule.respond_to?(:class) && @rule.class.respond_to?(:name)
+          # Extract ID from class name for requirements
+          class_name = @rule.class.name.split("::").last
+          class_name.gsub(/Requirement$/, "").downcase.gsub(/([a-z])([A-Z])/,
+                                                            '\1_\2').downcase
+        else
+          "unknown"
+        end
+      end
+
+      def error?
+        @type == :error
+      end
+
+      def warning?
+        @type == :warning
+      end
+
+      def fixable?
+        !@fix.nil?
+      end
+
+      def line
+        @node.respond_to?(:line) ? @node.line : nil
+      end
+
+      def column
+        @node.respond_to?(:column) ? @node.column : nil
+      end
+
+      def element_name
+        @node.respond_to?(:name) ? @node.name : nil
+      end
+
+      def apply_fix
+        return false unless fixable?
+
+        begin
+          if @fix.respond_to?(:call)
+            @fix.call
+          else
+            @fix.apply
+          end
+          true
+        rescue StandardError
+          false
+        end
+      end
+
+      # Check if this issue is remediable
+      def remediable?
+        case @violation_type
+        when :color_violation, :font_violation, :content_violation, :reference_violation,
+             :namespace_violation, :viewbox_violation, :style_violation
+          true
+        when :structural_violation
+          false
+        else
+          # Default to remediable for backward compatibility
+          true
+        end
+      end
+
+      # Get the type of remediation needed
+      def remediation_type
+        case @violation_type
+        when :color_violation, :font_violation
+          :convert
+        when :content_violation, :reference_violation, :namespace_violation
+          :remove
+        when :viewbox_violation
+          :add
+        when :style_violation
+          :promote
+        else
+          :unknown
+        end
+      end
+
+      # Get the confidence level of automated remediation
+      def remediation_confidence
+        case @violation_type
+        when :color_violation, :font_violation, :style_violation
+          :automatic
+        when :viewbox_violation, :namespace_violation
+          :safe_structural
+        when :content_violation, :reference_violation
+          :safe_removal
+        else
+          :manual_review
+        end
+      end
+
+      # Get the suggested action to fix this issue
+      def suggested_action
+        case @violation_type
+        when :color_violation
+          "Convert color to allowed equivalent using CssColor"
+        when :font_violation
+          "Map font family to generic equivalent"
+        when :content_violation
+          "Remove forbidden element or attribute"
+        when :reference_violation
+          "Remove broken reference or containing element"
+        when :namespace_violation
+          "Fix namespace declarations and remove invalid elements/attributes"
+        when :viewbox_violation
+          "Add missing viewBox attribute"
+        when :style_violation
+          "Promote style properties to attributes"
+        when :structural_violation
+          "Manual fix required - document structure issue"
+        else
+          "Apply available remediation"
+        end
+      end
+
+      # Check if this issue affects document content
+      def affects_content?
+        case @violation_type
+        when :content_violation, :reference_violation
+          true
+        when :color_violation, :font_violation, :style_violation, :viewbox_violation, :namespace_violation
+          false
+        else
+          false
+        end
+      end
+
+      def to_h
+        {
+          type: @type,
+          rule: rule_id,
+          message: @message,
+          line: line,
+          column: column,
+          element: element_name,
+          fixable: fixable?,
+          remediable: remediable?,
+          violation_type: @violation_type,
+          remediation_type: remediation_type,
+          remediation_confidence: remediation_confidence,
+          suggested_action: suggested_action,
+          affects_content: affects_content?,
+        }
+      end
+
+      def to_s
+        location = line ? " at line #{line}" : ""
+        location += ":#{column}" if column
+        rule_info = rule_id ? " (#{rule_id})" : ""
+        remediation_info = remediable? ? " [#{remediation_type}]" : " [NOT REMEDIABLE]"
+        "#{@message}#{location}#{rule_info}#{remediation_info}"
+      end
+
+      private
+
+      def detect_violation_type
+        req_id = requirement_id.downcase
+        msg = @message.downcase
+
+        # First check for structural violations (non-remediable)
+        return :structural_violation if msg.include?("root element must be") ||
+          msg.include?("malformed") ||
+          msg.include?("invalid document") ||
+          msg.include?("required element missing") ||
+          msg.include?("invalid hierarchy")
+
+        # Then check requirement-based violations (remediable)
+        case req_id
+        when /color/
+          :color_violation
+        when /font/
+          :font_violation
+        when /forbidden|content/
+          :content_violation
+        when /reference|id/
+          :reference_violation
+        when /namespace/
+          :namespace_violation
+        when /viewbox/
+          :viewbox_violation
+        when /style/
+          :style_violation
+        else
+          # Check message content for clues
+          return :color_violation if msg.include?("color")
+          return :font_violation if msg.include?("font")
+          return :content_violation if msg.include?("forbidden")
+          return :reference_violation if msg.include?("reference") || msg.include?("href")
+          return :namespace_violation if msg.include?("namespace")
+          return :viewbox_violation if msg.include?("viewbox")
+          return :style_violation if msg.include?("style")
+
+          :unknown_violation
+        end
+      end
+
+      def rule_id
+        return @requirement_id_override if @requirement_id_override
+        return @rule.id if @rule.respond_to?(:id)
+
+        if @rule.respond_to?(:class) && @rule.class.respond_to?(:name)
+          # Extract ID from class name for requirements
+          class_name = @rule.class.name.split("::").last
+          class_name.gsub(/Requirement$/, "").downcase.gsub(/([a-z])([A-Z])/,
+                                                            '\1_\2').downcase
+        else
+          "unknown"
+        end
+      end
+    end
+  end
+end

data/lib/svg_conform/errors/validation_notice.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require_relative "base"
+
+module SvgConform
+  module Errors
+    # Validation notice (informational message, not an error)
+    #
+    # Represents informational notices during validation, such as
+    # external reference notices or other non-error messages.
+    class ValidationNotice < Base
+      attr_reader :data
+
+      def initialize(type:, node:, message:, data: {})
+        super(type: type, node: node, message: message)
+        @data = data
+      end
+
+      def to_h
+        {
+          type: @type,
+          message: @message,
+          line: line,
+          column: column,
+          data: @data,
+        }
+      end
+    end
+  end
+end

data/lib/svg_conform/interfaces/requirement_interface.rb

@@ -0,0 +1,177 @@
+# frozen_string_literal: true
+
+module SvgConform
+  module Interfaces
+    # Defines the contract for validation requirements
+    #
+    # All requirements must implement the methods defined in this interface.
+    # This ensures consistent behavior between DOM and SAX validation modes.
+    #
+    # @example Implementing a requirement
+    #   class MyRequirement < BaseRequirement
+    #     include RequirementInterface
+    #
+    #     def check(node, context)
+    #       # DOM validation logic here
+    #     end
+    #
+    #     def validate_sax_element(element, context)
+    #       # SAX validation logic here
+    #     end
+    #   end
+    module RequirementInterface
+      # Required Methods
+      # These methods must be implemented by all requirement classes
+
+      # Validates a single node during DOM traversal
+      #
+      # This is the main validation method called for each node that passes
+      # the should_check_node? filter during DOM-based validation.
+      #
+      # @param node [Moxml::Node, Nokogiri::XML::Node] The node to validate
+      # @param context [ValidationContext] The validation context for reporting errors
+      # @return [void]
+      # @raise [NotImplementedError] If not implemented by subclass
+      #
+      # @example Basic implementation
+      #   def check(node, context)
+      #     if invalid_condition?(node)
+      #       context.add_error(
+      #         requirement_id: id,
+      #         message: "Node violates requirement",
+      #         node: node,
+      #         severity: :error,
+      #       )
+      #     end
+      #   end
+      def check(node, context)
+        raise NotImplementedError, "#{self.class} must implement #check"
+      end
+
+      # Optional Methods
+      # These methods have default implementations but can be overridden
+
+      # Validates the entire document (called once per requirement)
+      #
+      # Default implementation traverses the document and calls #check
+      # on each node that passes should_check_node?. Override for custom
+      # document-level validation logic.
+      #
+      # @param document [Document] The document to validate
+      # @param context [ValidationContext] The validation context for reporting errors
+      # @return [void]
+      def validate_document(document, context)
+        document.traverse do |node|
+          check(node, context) if should_check_node?(node, context)
+        end
+      end
+
+      # Validates an element during SAX parsing
+      #
+      # Called for each element during streaming SAX validation.
+      # Override this method to implement SAX-compatible validation logic.
+      #
+      # IMPORTANT: In SAX mode, the element is an ElementProxy (not a full DOM node).
+      # It provides: name, attributes, parent, path, position but NOT:
+      # - children (not yet parsed)
+      # - tree traversal (impossible during streaming)
+      # - XPath queries (not available)
+      #
+      # Use ElementProxy methods:
+      # - element.name - element tag name
+      # - element.attributes - hash of attributes
+      # - element.parent - parent ElementProxy
+      # - element.path - array of element names representing path
+      # - element.position - 1-based position in document
+      # - element.path_id - unique node ID for tracking
+      #
+      # @param element [ElementProxy] The element being validated
+      # @param context [ValidationContext] The validation context for reporting errors
+      # @return [void]
+      def validate_sax_element(element, context)
+        # Default: Empty - subclasses must override for SAX support
+      end
+
+      # Collects data during SAX parsing for deferred validation
+      #
+      # Called for each element during SAX parsing to collect data
+      # that will be used later in validate_sax_complete.
+      #
+      # Use this for requirements that need to collect references, IDs,
+      # or other data before validating (e.g., ID/reference validation).
+      #
+      # @param element [ElementProxy] The element being examined
+      # @param context [ValidationContext] The validation context
+      # @return [void]
+      def collect_sax_data(element, context)
+        # Default: no data collection
+      end
+
+      # Performs deferred validation after document is fully parsed
+      #
+      # Called once after SAX parsing completes. Use this to validate
+      # relationships that require forward references (e.g., ID references,
+      # cross-element constraints).
+      #
+      # Override this method and return true from needs_deferred_validation?
+      # to enable deferred validation for this requirement.
+      #
+      # @param context [ValidationContext] The validation context containing
+      #   collected data and for reporting errors
+      # @return [void]
+      def validate_sax_complete(context)
+        # Default: no deferred validation
+      end
+
+      # Indicates if this requirement needs deferred validation
+      #
+      # Return true if this requirement needs to validate after the full
+      # document is parsed (e.g., for ID/reference validation).
+      #
+      # When returning true, also implement validate_sax_complete.
+      #
+      # @return [Boolean] true if deferred validation is needed
+      def needs_deferred_validation?
+        false
+      end
+
+      # Determines if this requirement should check a specific node
+      #
+      # Return false to skip validation for a node. The default implementation
+      # skips nodes that are not elements (text nodes, comments, etc.) and
+      # structurally invalid nodes.
+      #
+      # Override this to add additional filtering logic.
+      #
+      # @param node [Moxml::Node, Nokogiri::XML::Node, ElementProxy] The node to check
+      # @param context [ValidationContext, nil] The validation context (may be nil in some cases)
+      # @return [Boolean] true if the node should be validated
+      def should_check_node?(node, context = nil)
+        return false unless node.respond_to?(:name) && node.respond_to?(:attributes)
+
+        # Skip structurally invalid nodes
+        return false if context&.node_structurally_invalid?(node)
+
+        true
+      end
+
+      # Resets any state between validations (for batch mode)
+      #
+      # Called between validations when validating multiple files.
+      # Override this method if your requirement maintains state that
+      # needs to be reset.
+      #
+      # @return [void]
+      def reset_state
+        # Default: no state to reset
+      end
+
+      # Returns a string representation of the requirement
+      #
+      # @return [String] The requirement ID and description
+      def to_s
+        "#{@id}: #{@description}"
+      end
+    end
+  end
+end

data/lib/svg_conform/node_helpers.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module SvgConform
+  # Shared helper methods for working with XML nodes
+  #
+  # This module provides common utilities used by both requirements
+  # and remediations to avoid code duplication and ensure consistency.
+  module NodeHelpers
+    # Check if a node is an element
+    # @param node [Object] the node to check
+    # @return [Boolean] true if the node is an element
+    def element?(node)
+      node.respond_to?(:name) && !node.name.nil?
+    end
+
+    # Check if a node is text
+    # @param node [Object] the node to check
+    # @return [Boolean] true if the node is text
+    def text?(node)
+      node.respond_to?(:text?) && node.text?
+    end
+
+    # Get attribute value from a node
+    # @param node [Object] the node
+    # @param name [String] attribute name
+    # @return [String, nil] attribute value or nil
+    def get_attribute(node, name)
+      return nil unless node.respond_to?(:[])
+
+      node[name]
+    end
+
+    # Set attribute value on a node
+    # @param node [Object] the node
+    # @param name [String] attribute name
+    # @param value [String] attribute value
+    # @return [Boolean] true if successful
+    def set_attribute(node, name, value)
+      return unless node.respond_to?(:[]=)
+
+      node[name] = value
+      true
+    end
+
+    # Check if node has an attribute
+    # @param node [Object] the node
+    # @param name [String] attribute name
+    # @return [Boolean] true if attribute exists
+    def has_attribute?(node, name)
+      return false unless node.respond_to?(:[])
+
+      !node[name].nil?
+    end
+
+    # Remove attribute from a node
+    # @param node [Object] the node
+    # @param name [String] attribute name
+    # @return [Boolean] true if successful
+    def remove_attribute(node, name)
+      if node.respond_to?(:remove_attribute)
+        node.remove_attribute(name)
+        true
+      elsif node.respond_to?(:[]=) && node.respond_to?(:[])
+        # Fallback for bracket notation
+        node[name] = nil
+        true
+      else
+        false
+      end
+    end
+  end
+end

data/lib/svg_conform/remediations/base_remediation.rb

@@ -2,11 +2,14 @@
 
 require "lutaml/model"
 require_relative "../remediation_result"
+require_relative "../node_helpers"
 
 module SvgConform
   module Remediations
     # Base class for all remediations using lutaml-model serialization
     class BaseRemediation < Lutaml::Model::Serializable
+      include SvgConform::NodeHelpers
+
       attribute :id, :string
       attribute :description, :string
       attribute :targets, :string, collection: true
@@ -72,27 +75,8 @@ module SvgConform
 
       protected
 
-      def element?(node)
-        node.respond_to?(:name) && node.name
-      end
-
-      def get_attribute(node, attr_name)
-        return nil unless node.respond_to?(:[])
-
-        node[attr_name]
-      end
-
-      def set_attribute(node, attr_name, value)
-        return unless node.respond_to?(:[]=)
-
-        node[attr_name] = value
-      end
-
-      def has_attribute?(node, attr_name)
-        return false unless node.respond_to?(:[])
-
-        !node[attr_name].nil?
-      end
+      # Helper methods for node manipulation included via NodeHelpers module:
+      # element?, text?, get_attribute, set_attribute, has_attribute?, remove_attribute
 
       def find_nodes(document, &)
         nodes = []
@@ -100,20 +84,6 @@ module SvgConform
         nodes
       end
 
-      # Helper method to remove attribute
-      def remove_attribute(node, name)
-        if node.respond_to?(:remove_attribute)
-          node.remove_attribute(name)
-          true
-        elsif node.respond_to?(:[]=) && node.respond_to?(:[])
-          # Fallback for different implementations
-          node[name] = nil
-          true
-        else
-          false
-        end
-      end
-
       # Helper method to remove node
       def remove_node(node)
         return false unless node.respond_to?(:remove)