png_conform 0.1.0

data/lib/png_conform/validators/apng/fctl_validator.rb

@@ -0,0 +1,155 @@
+# frozen_string_literal: true
+
+module PngConform
+  module Validators
+    module Apng
+      # Validator for fcTL (Frame Control) chunk
+      #
+      # The fcTL chunk specifies the parameters of each frame in an animated PNG.
+      #
+      # Structure (26 bytes):
+      # - sequence_number (4 bytes): Sequence number (starts at 0)
+      # - width (4 bytes): Frame width in pixels
+      # - height (4 bytes): Frame height in pixels
+      # - x_offset (4 bytes): X position at which to render frame
+      # - y_offset (4 bytes): Y position at which to render frame
+      # - delay_num (2 bytes): Frame delay numerator
+      # - delay_den (2 bytes): Frame delay denominator
+      # - dispose_op (1 byte): Disposal operation (0-2)
+      # - blend_op (1 byte): Blend operation (0-1)
+      #
+      # Constraints:
+      # - Must have acTL chunk before any fcTL
+      # - Frame dimensions must be <= IHDR dimensions
+      # - Frame position + size must fit within IHDR dimensions
+      # - Sequence numbers must be consecutive
+      # - dispose_op: 0=NONE, 1=BACKGROUND, 2=PREVIOUS
+      # - blend_op: 0=SOURCE, 1=OVER
+      #
+      class FctlValidator < BaseValidator
+        CHUNK_TYPE = "fcTL"
+        EXPECTED_LENGTH = 26
+
+        DISPOSE_OP_NONE = 0
+        DISPOSE_OP_BACKGROUND = 1
+        DISPOSE_OP_PREVIOUS = 2
+
+        BLEND_OP_SOURCE = 0
+        BLEND_OP_OVER = 1
+
+        def validate
+          return unless check_crc
+          return unless check_length(EXPECTED_LENGTH)
+
+          validate_structure
+          validate_frame_dimensions
+          validate_sequence_number
+        end
+
+        private
+
+        def validate_structure
+          data = chunk.chunk_data
+
+          # Extract all fields
+          sequence_number = data[0..3].unpack1("N")
+          width = data[4..7].unpack1("N")
+          height = data[8..11].unpack1("N")
+          data[12..15].unpack1("N")
+          data[16..19].unpack1("N")
+          delay_num = data[20..21].unpack1("n")
+          delay_den = data[22..23].unpack1("n")
+          dispose_op = data[24].unpack1("C")
+          blend_op = data[25].unpack1("C")
+
+          # Store in context
+          context.store(:last_fctl_sequence, sequence_number)
+          context.store(:fctl_count, (context.retrieve(:fctl_count) || 0) + 1)
+
+          # Validate frame dimensions
+          if width.zero? || height.zero?
+            add_error("fcTL width and height must be > 0")
+            return false
+          end
+
+          # Validate dispose_op
+          unless check_enum(dispose_op, [DISPOSE_OP_NONE, DISPOSE_OP_BACKGROUND,
+                                         DISPOSE_OP_PREVIOUS], "dispose_op")
+            return false
+          end
+
+          # Validate blend_op
+          unless check_enum(blend_op, [BLEND_OP_SOURCE, BLEND_OP_OVER],
+                            "blend_op")
+            return false
+          end
+
+          # Validate delay
+          if delay_den.zero?
+            # delay_den of 0 means denominator is 100
+            context.store(:frame_delay, delay_num / 100.0)
+          else
+            context.store(:frame_delay, delay_num.to_f / delay_den)
+          end
+
+          true
+        end
+
+        def validate_frame_dimensions
+          ihdr_width = context.retrieve(:ihdr_width)
+          ihdr_height = context.retrieve(:ihdr_height)
+
+          return true unless ihdr_width && ihdr_height
+
+          data = chunk.chunk_data
+          width = data[4..7].unpack1("N")
+          height = data[8..11].unpack1("N")
+          x_offset = data[12..15].unpack1("N")
+          y_offset = data[16..19].unpack1("N")
+
+          # Frame must fit within IHDR dimensions
+          if width > ihdr_width || height > ihdr_height
+            add_error("fcTL frame dimensions exceed IHDR dimensions")
+            return false
+          end
+
+          # Frame position + size must fit within IHDR
+          if x_offset + width > ihdr_width
+            add_error("fcTL frame extends beyond IHDR width")
+            return false
+          end
+
+          if y_offset + height > ihdr_height
+            add_error("fcTL frame extends beyond IHDR height")
+            return false
+          end
+
+          true
+        end
+
+        def validate_sequence_number
+          # Check if acTL exists
+          unless context.retrieve(:actl_num_frames)
+            add_error("fcTL requires acTL chunk")
+            return false
+          end
+
+          data = chunk.chunk_data
+          sequence_number = data[0..3].unpack1("N")
+          expected_sequence = context.retrieve(:expected_apng_sequence) || 0
+
+          if sequence_number != expected_sequence
+            add_error("fcTL sequence number mismatch " \
+                      "(expected #{expected_sequence}, got #{sequence_number})")
+            return false
+          end
+
+          # Update expected sequence for next frame chunk
+          context.store(:expected_apng_sequence, expected_sequence + 1)
+
+          true
+        end
+      end
+    end
+  end
+end

data/lib/png_conform/validators/apng/fdat_validator.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+module PngConform
+  module Validators
+    module Apng
+      # Validator for fdAT (Frame Data) chunk
+      #
+      # The fdAT chunk contains the compressed image data for a single frame
+      # in an animated PNG. It is similar to IDAT but includes a sequence number.
+      #
+      # Structure:
+      # - sequence_number (4 bytes): Sequence number
+      # - frame_data (remaining bytes): Compressed image data
+      #
+      # Constraints:
+      # - Must have fcTL chunk before fdAT
+      # - Sequence numbers must be consecutive (continuing from fcTL)
+      # - Must have acTL chunk present
+      # - Frame data must be valid zlib compressed data
+      #
+      class FdatValidator < BaseValidator
+        CHUNK_TYPE = "fdAT"
+        MIN_LENGTH = 5 # At least 4 bytes for sequence + 1 byte data
+
+        def validate
+          return unless check_crc
+          return unless validate_min_length
+
+          validate_structure
+          validate_sequence_number
+          validate_ordering
+        end
+
+        private
+
+        def validate_min_length
+          actual = chunk.chunk_data.length
+          if actual < MIN_LENGTH
+            add_error("fdAT chunk too short (#{actual} bytes, " \
+                      "minimum #{MIN_LENGTH})")
+            return false
+          end
+          true
+        end
+
+        def validate_structure
+          data = chunk.chunk_data
+
+          # Extract sequence number
+          sequence_number = data[0..3].unpack1("N")
+
+          # Store in context
+          context.store(:last_fdat_sequence, sequence_number)
+          context.store(:fdat_count, (context.retrieve(:fdat_count) || 0) + 1)
+
+          # Frame data is the rest (starting at byte 4)
+          frame_data = data[4..]
+
+          if frame_data.nil? || frame_data.empty?
+            add_error("fdAT has no frame data")
+            return false
+          end
+
+          # Store frame data length for statistics
+          context.store(:fdat_data_length,
+                        (context.retrieve(:fdat_data_length) || 0) + frame_data.length)
+
+          true
+        end
+
+        def validate_sequence_number
+          # Check if acTL exists
+          unless context.retrieve(:actl_num_frames)
+            add_error("fdAT requires acTL chunk")
+            return false
+          end
+
+          data = chunk.chunk_data
+          sequence_number = data[0..3].unpack1("N")
+          expected_sequence = context.retrieve(:expected_apng_sequence)
+
+          # First fdAT should follow fcTL sequences
+          if expected_sequence.nil?
+            add_error("fdAT must follow fcTL chunk")
+            return false
+          end
+
+          if sequence_number != expected_sequence
+            add_error("fdAT sequence number mismatch " \
+                      "(expected #{expected_sequence}, got #{sequence_number})")
+            return false
+          end
+
+          # Update expected sequence for next chunk
+          context.store(:expected_apng_sequence, expected_sequence + 1)
+
+          true
+        end
+
+        def validate_ordering
+          # fdAT must have corresponding fcTL
+          fctl_count = context.retrieve(:fctl_count) || 0
+          context.retrieve(:fdat_count) || 0
+
+          # Each frame should have fcTL followed by fdAT(s)
+          # We can have multiple fdAT chunks per frame, but must have at least one fcTL
+          if fctl_count.zero?
+            add_error("fdAT chunk requires fcTL chunk")
+            return false
+          end
+
+          true
+        end
+      end
+    end
+  end
+end

data/lib/png_conform/validators/base_validator.rb

@@ -0,0 +1,241 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module PngConform
+  module Validators
+    # Base class for all chunk validators
+    #
+    # Validators follow a consistent pattern:
+    # 1. Initialize with chunk and context
+    # 2. Validate method returns ValidationResult
+    # 3. Protected helper methods for specific checks
+    #
+    # Validators are MECE - each handles exactly one chunk type
+    # and validates all aspects of that chunk type completely.
+    class BaseValidator
+      attr_reader :chunk, :context
+
+      # Initialize validator with chunk and validation context
+      #
+      # @param chunk [BinData::Record] The chunk to validate
+      # @param context [ValidationContext] The validation context
+      def initialize(chunk, context = nil)
+        @chunk = chunk
+        @context = context || ValidationContext.new
+      end
+
+      # Validate the chunk
+      #
+      # @return [ValidationResult] The validation result
+      def validate
+        raise NotImplementedError, "Subclasses must implement #validate"
+      end
+
+      protected
+
+      # Add an error to the validation result
+      #
+      # @param message [String] The error message
+      # @param severity [Symbol] :error, :warning, or :info
+      def add_error(message, severity: :error)
+        context.add_error(
+          chunk_type: chunk.chunk_type,
+          message: message,
+          severity: severity,
+          offset: chunk.abs_offset,
+        )
+      end
+
+      # Add a warning to the validation result
+      #
+      # @param message [String] The warning message
+      def add_warning(message)
+        add_error(message, severity: :warning)
+      end
+
+      # Add an info message to the validation result
+      #
+      # @param message [String] The info message
+      def add_info(message)
+        add_error(message, severity: :info)
+      end
+
+      # Check if chunk data length matches expected length
+      #
+      # @param expected [Integer] Expected data length
+      # @return [Boolean] True if length matches
+      def check_length(expected)
+        actual = chunk.chunk_data.length
+        return true if actual == expected
+
+        add_error("invalid #{chunk.chunk_type} length (#{actual}, " \
+                  "should be #{expected})")
+        false
+      end
+
+      # Check if value is within valid range
+      #
+      # @param value [Integer] Value to check
+      # @param min [Integer] Minimum valid value
+      # @param max [Integer] Maximum valid value
+      # @param name [String] Name of the value for error message
+      # @return [Boolean] True if value is in range
+      def check_range(value, min, max, name)
+        return true if value >= min && value <= max
+
+        add_error("invalid #{name} (#{value}, must be #{min}-#{max})")
+        false
+      end
+
+      # Check if value is one of valid options
+      #
+      # @param value [Object] Value to check
+      # @param valid [Array] Array of valid values
+      # @param name [String] Name of the value for error message
+      # @return [Boolean] True if value is valid
+      def check_enum(value, valid, name)
+        return true if valid.include?(value)
+
+        add_error("invalid #{name} (#{value}, must be one of " \
+                  "#{valid.join(', ')})")
+        false
+      end
+
+      # Check if chunk CRC is valid
+      #
+      # @return [Boolean] True if CRC is valid
+      def check_crc
+        return true if chunk.crc_valid?
+
+        add_error("CRC error in #{chunk.chunk_type} chunk")
+        false
+      end
+    end
+
+    # Validation context maintains state during validation
+    class ValidationContext
+      attr_reader :errors, :chunks_seen, :file_info
+
+      def initialize
+        @errors = []
+        @chunks_seen = {}
+        @file_info = {}
+      end
+
+      # Add an error/warning/info to the context
+      #
+      # @param chunk_type [String] The chunk type
+      # @param message [String] The error message
+      # @param severity [Symbol] :error, :warning, or :info
+      # @param offset [Integer] File offset of the error
+      def add_error(chunk_type:, message:, severity: :error, offset: nil)
+        @errors << {
+          chunk_type: chunk_type,
+          message: message,
+          severity: severity,
+          offset: offset,
+        }
+      end
+
+      # Record that a chunk type has been seen
+      #
+      # @param chunk_type [String] The chunk type
+      # @param chunk [BinData::Record] The chunk
+      def record_chunk(chunk_type, chunk = nil)
+        @chunks_seen[chunk_type] ||= []
+        @chunks_seen[chunk_type] << chunk if chunk
+      end
+      alias mark_chunk_seen record_chunk
+
+      # Check if a chunk type has been seen
+      #
+      # @param chunk_type [String] The chunk type
+      # @return [Boolean] True if chunk type has been seen
+      def seen?(chunk_type)
+        @chunks_seen.key?(chunk_type)
+      end
+
+      # Get chunks of a specific type
+      #
+      # @param chunk_type [String] The chunk type
+      # @return [Array] Array of chunks of that type
+      def chunks_of_type(chunk_type)
+        @chunks_seen[chunk_type] || []
+      end
+
+      # Store file information
+      #
+      # @param key [Symbol] The key
+      # @param value [Object] The value
+      def store(key, value)
+        @file_info[key] = value
+      end
+
+      # Retrieve file information
+      #
+      # @param key [Symbol] The key
+      # @return [Object] The value
+      def retrieve(key)
+        @file_info[key]
+      end
+
+      # Check if validation has errors
+      #
+      # @return [Boolean] True if there are any errors
+      def has_errors?
+        @errors.any? { |e| e[:severity] == :error }
+      end
+
+      # Check if validation has warnings
+      #
+      # @return [Boolean] True if there are any warnings
+      def has_warnings?
+        @errors.any? { |e| e[:severity] == :warning }
+      end
+
+      # Get all errors
+      #
+      # @return [Array] Array of error hashes
+      def all_errors
+        @errors.select { |e| e[:severity] == :error }
+      end
+
+      # Get all warnings
+      #
+      # @return [Array] Array of warning hashes
+      def all_warnings
+        @errors.select { |e| e[:severity] == :warning }
+      end
+
+      # Get all info messages
+      #
+      # @return [Array] Array of info hashes
+      def all_info
+        @errors.select { |e| e[:severity] == :info }
+      end
+
+      # Provide attribute-style access to file_info
+      #
+      # Allows context.width instead of context.retrieve(:width)
+      # and context.width = 100 instead of context.store(:width, 100)
+      def method_missing(method, *args)
+        method_name = method.to_s
+        if method_name.end_with?("=")
+          # Setter: context.width = 100
+          key = method_name.chomp("=").to_sym
+          store(key, args.first)
+        elsif args.empty?
+          # Getter: context.width
+          retrieve(method.to_sym)
+        else
+          super
+        end
+      end
+
+      def respond_to_missing?(_method, _include_private = false)
+        true
+      end
+    end
+  end
+end