svg_conform 0.1.7 → 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/remediations/namespace_remediation.rb

@@ -177,7 +177,8 @@ module SvgConform
         # Store the prefixes to remove on the document for later serialization
         # Try to store on Document wrapper first, fallback to moxml_document
         target = document.respond_to?(:instance_variable_set) ? document : root.document
-        target&.instance_variable_set(:@unused_namespace_prefixes, disallowed_prefixes)
+        target&.instance_variable_set(:@unused_namespace_prefixes,
+                                      disallowed_prefixes)
       end
 
       def find_used_namespace_prefixes(document)

data/lib/svg_conform/requirements/base_requirement.rb

@@ -1,12 +1,14 @@
 # frozen_string_literal: true
 
 require_relative "../node_helpers"
+require_relative "../interfaces/requirement_interface"
 
 module SvgConform
   module Requirements
     # Base class for all validation requirements
     class BaseRequirement < Lutaml::Model::Serializable
       include SvgConform::NodeHelpers
+      include SvgConform::Interfaces::RequirementInterface
 
       attribute :id, :string
       attribute :description, :string
@@ -81,6 +83,20 @@ module SvgConform
         end
       end
 
+      # Shared helper for skipping attribute validation on structurally invalid nodes
+      # Used by both DOM and SAX validation
+      def skip_attribute_validation?(node_or_element, context)
+        # For DOM mode, also check if it's an element
+        return true if element?(node_or_element) && context.node_structurally_invalid?(node_or_element)
+
+        # For SAX mode (ElementProxy always has this method)
+        if node_or_element.respond_to?(:path_id)
+          return context.node_structurally_invalid?(node_or_element)
+        end
+
+        false
+      end
+
       def to_s
         "#{@id}: #{@description}"
       end

data/lib/svg_conform/requirements/color_restrictions_requirement.rb

@@ -26,70 +26,30 @@ module SvgConform
       def check(node, context)
         return unless element?(node)
 
-        # Skip attribute validation for structurally invalid nodes (e.g., wrong parent-child)
-        return if context.node_structurally_invalid?(node)
-
-        # Check color-related attributes
-        color_attributes = %w[fill stroke color stop-color flood-color
-                              lighting-color]
-
-        color_attributes.each do |attr_name|
-          value = get_attribute(node, attr_name)
-          next if value.nil? || value.empty?
-
-          next if valid_color?(value)
-
-          context.add_error(
-            requirement_id: id,
-            message: "Color '#{value}' in attribute '#{attr_name}' is not allowed in this profile",
-            node: node,
-            severity: :error,
-            data: {
-              attribute: attr_name,
-              value: value,
-              element: node.name,
-            },
-          )
-        end
-
-        # Check style attribute for color properties
-        style_value = get_attribute(node, "style")
-        return unless style_value
-
-        styles = parse_style(style_value)
-        color_properties = %w[fill stroke color stop-color flood-color
-                              lighting-color]
-
-        color_properties.each do |prop|
-          value = styles[prop]
-          next if value.nil? || value.empty?
-
-          next if valid_color?(value)
-
-          context.add_error(
-            requirement_id: id,
-            message: "Color '#{value}' in style property '#{prop}' is not allowed in this profile",
-            node: node,
-            severity: :error,
-            data: {
-              attribute: prop,
-              value: value,
-              element: node.name,
-            },
-          )
-        end
+        validate_colors(node, context)
       end
 
       def validate_sax_element(element, context)
+        # ElementProxy always represents an element, so no element? check needed
+        validate_colors(element, context)
+      end
+
+      private
+
+      # Shared validation logic for both DOM and SAX modes
+      def validate_colors(node_or_element, context)
         # Skip attribute validation for structurally invalid nodes
-        return if context.node_structurally_invalid?(element)
+        return if skip_attribute_validation?(node_or_element, context)
+
+        # Get element name
+        element_name = node_or_element.name
 
         # Check color-related attributes
         color_attributes = %w[fill stroke color stop-color flood-color
                               lighting-color]
 
         color_attributes.each do |attr_name|
-          value = element.raw_attributes[attr_name]
+          value = get_attribute(node_or_element, attr_name)
           next if value.nil? || value.empty?
 
           next if valid_color?(value)
@@ -97,18 +57,18 @@ module SvgConform
           context.add_error(
             requirement_id: id,
             message: "Color '#{value}' in attribute '#{attr_name}' is not allowed in this profile",
-            node: element,
+            node: node_or_element,
             severity: :error,
             data: {
               attribute: attr_name,
               value: value,
-              element: element.name,
+              element: element_name,
             },
           )
         end
 
         # Check style attribute for color properties
-        style_value = element.raw_attributes["style"]
+        style_value = get_attribute(node_or_element, "style")
         return unless style_value
 
         styles = parse_style(style_value)
@@ -124,19 +84,17 @@ module SvgConform
           context.add_error(
             requirement_id: id,
             message: "Color '#{value}' in style property '#{prop}' is not allowed in this profile",
-            node: element,
+            node: node_or_element,
             severity: :error,
             data: {
               attribute: prop,
               value: value,
-              element: element.name,
+              element: element_name,
             },
           )
         end
       end
 
-      private
-
       def valid_color?(color)
         # First check if threshold-based validation is enabled
         if black_and_white_threshold