png_conform 0.1.0

data/lib/png_conform/validators/chunk_registry.rb

@@ -0,0 +1,219 @@
+# frozen_string_literal: true
+
+require_relative "critical/ihdr_validator"
+require_relative "critical/plte_validator"
+require_relative "critical/idat_validator"
+require_relative "critical/iend_validator"
+require_relative "ancillary/text_validator"
+require_relative "ancillary/ztxt_validator"
+require_relative "ancillary/itxt_validator"
+require_relative "ancillary/gama_validator"
+require_relative "ancillary/chrm_validator"
+require_relative "ancillary/srgb_validator"
+require_relative "ancillary/sbit_validator"
+require_relative "ancillary/bkgd_validator"
+require_relative "ancillary/iccp_validator"
+require_relative "ancillary/hist_validator"
+require_relative "ancillary/splt_validator"
+require_relative "ancillary/trns_validator"
+require_relative "ancillary/phys_validator"
+require_relative "ancillary/time_validator"
+require_relative "ancillary/offs_validator"
+require_relative "ancillary/pcal_validator"
+require_relative "ancillary/scal_validator"
+require_relative "ancillary/ster_validator"
+require_relative "ancillary/cicp_validator"
+require_relative "ancillary/mdcv_validator"
+require_relative "apng/actl_validator"
+require_relative "apng/fctl_validator"
+require_relative "apng/fdat_validator"
+require_relative "mng/mhdr_validator"
+require_relative "mng/mend_validator"
+require_relative "mng/dhdr_validator"
+require_relative "mng/fram_validator"
+require_relative "mng/defi_validator"
+require_relative "mng/back_validator"
+require_relative "mng/loop_validator"
+require_relative "mng/endl_validator"
+require_relative "mng/term_validator"
+require_relative "mng/save_validator"
+require_relative "mng/seek_validator"
+require_relative "mng/move_validator"
+require_relative "mng/clip_validator"
+require_relative "mng/show_validator"
+require_relative "mng/clon_validator"
+require_relative "mng/disc_validator"
+require_relative "jng/jhdr_validator"
+require_relative "jng/jdat_validator"
+require_relative "jng/jsep_validator"
+
+module PngConform
+  module Validators
+    # Registry of chunk types to their corresponding validator classes
+    #
+    # This class maintains a mapping between PNG chunk type codes and
+    # their validator implementations. It follows the Registry pattern
+    # to provide centralized validator discovery and instantiation.
+    #
+    # The registry is organized by chunk categories:
+    # - Critical chunks (IHDR, PLTE, IDAT, IEND)
+    # - Text chunks (tEXt, zTXt, iTXt)
+    # - Color management (gAMA, cHRM, sRGB, sBIT, bKGD, iCCP)
+    # - Palette support (hIST, sPLT, tRNS)
+    # - Metadata (pHYs, tIME, oFFs, pCAL, sCAL, sTER)
+    # - PNG 3rd edition (cICP, mDCv)
+    # - APNG (acTL, fcTL, fdAT)
+    # - MNG (MHDR, MEND, DHDR, FRAM, DEFI, BACK, LOOP, ENDL, etc.)
+    # - JNG (JHDR, JDAT, JSEP)
+    #
+    class ChunkRegistry
+      # Map of chunk type codes to validator classes
+      VALIDATORS = {
+        # Critical chunks
+        "IHDR" => Critical::IhdrValidator,
+        "PLTE" => Critical::PlteValidator,
+        "IDAT" => Critical::IdatValidator,
+        "IEND" => Critical::IendValidator,
+
+        # Text chunks
+        "tEXt" => Ancillary::TextValidator,
+        "zTXt" => Ancillary::ZtxtValidator,
+        "iTXt" => Ancillary::ItxtValidator,
+
+        # Color management
+        "gAMA" => Ancillary::GamaValidator,
+        "cHRM" => Ancillary::ChrmValidator,
+        "sRGB" => Ancillary::SrgbValidator,
+        "sBIT" => Ancillary::SbitValidator,
+        "bKGD" => Ancillary::BkgdValidator,
+        "iCCP" => Ancillary::IccpValidator,
+
+        # Palette support
+        "hIST" => Ancillary::HistValidator,
+        "sPLT" => Ancillary::SpltValidator,
+        "tRNS" => Ancillary::TrnsValidator,
+
+        # Metadata
+        "pHYs" => Ancillary::PhysValidator,
+        "tIME" => Ancillary::TimeValidator,
+        "oFFs" => Ancillary::OffsValidator,
+        "pCAL" => Ancillary::PcalValidator,
+        "sCAL" => Ancillary::ScalValidator,
+        "sTER" => Ancillary::SterValidator,
+
+        # PNG 3rd edition
+        "cICP" => Ancillary::CicpValidator,
+        "mDCv" => Ancillary::MdcvValidator,
+
+        # APNG (Animated PNG)
+        "acTL" => Apng::ActlValidator,
+        "fcTL" => Apng::FctlValidator,
+        "fdAT" => Apng::FdatValidator,
+
+        # MNG (Multiple-image Network Graphics)
+        "MHDR" => Mng::MhdrValidator,
+        "MEND" => Mng::MendValidator,
+        "DHDR" => Mng::DhdrValidator,
+        "FRAM" => Mng::FramValidator,
+        "DEFI" => Mng::DefiValidator,
+        "BACK" => Mng::BackValidator,
+        "LOOP" => Mng::LoopValidator,
+        "ENDL" => Mng::EndlValidator,
+        "TERM" => Mng::TermValidator,
+        "SAVE" => Mng::SaveValidator,
+        "SEEK" => Mng::SeekValidator,
+        "MOVE" => Mng::MoveValidator,
+        "CLIP" => Mng::ClipValidator,
+        "SHOW" => Mng::ShowValidator,
+        "CLON" => Mng::ClonValidator,
+        "DISC" => Mng::DiscValidator,
+
+        # JNG (JPEG Network Graphics)
+        "JHDR" => Jng::JhdrValidator,
+        "JDAT" => Jng::JdatValidator,
+        "JSEP" => Jng::JsepValidator,
+      }.freeze
+
+      class << self
+        # Get validator class for a chunk type
+        #
+        # @param chunk_type [String] Four-character chunk type code
+        # @return [Class, nil] Validator class or nil if not found
+        def validator_for(chunk_type)
+          VALIDATORS[chunk_type]
+        end
+
+        # Check if a validator exists for a chunk type
+        #
+        # @param chunk_type [String] Four-character chunk type code
+        # @return [Boolean] True if validator exists
+        def validator_exists?(chunk_type)
+          VALIDATORS.key?(chunk_type)
+        end
+
+        # Get all registered chunk types
+        #
+        # @return [Array<String>] List of chunk type codes
+        def chunk_types
+          VALIDATORS.keys
+        end
+
+        # Get validators by category
+        #
+        # @param category [Symbol] Category name
+        #   (:critical, :text, :color, :palette, :metadata, :png3)
+        # @return [Hash] Map of chunk types to validators in category
+        def validators_by_category(category)
+          case category
+          when :critical
+            VALIDATORS.select { |k, _| %w[IHDR PLTE IDAT IEND].include?(k) }
+          when :text
+            VALIDATORS.select { |k, _| %w[tEXt zTXt iTXt].include?(k) }
+          when :color
+            VALIDATORS.select do |k, _|
+              %w[gAMA cHRM sRGB sBIT bKGD iCCP].include?(k)
+            end
+          when :palette
+            VALIDATORS.select { |k, _| %w[hIST sPLT tRNS].include?(k) }
+          when :metadata
+            VALIDATORS.select do |k, _|
+              %w[pHYs tIME oFFs pCAL sCAL sTER].include?(k)
+            end
+          when :png3
+            VALIDATORS.select { |k, _| %w[cICP mDCv].include?(k) }
+          when :apng
+            VALIDATORS.select { |k, _| %w[acTL fcTL fdAT].include?(k) }
+          when :mng
+            VALIDATORS.select do |k, _|
+              %w[MHDR MEND DHDR FRAM DEFI BACK LOOP ENDL TERM SAVE SEEK
+                 MOVE CLIP SHOW CLON DISC].include?(k)
+            end
+          when :jng
+            VALIDATORS.select { |k, _| %w[JHDR JDAT JSEP].include?(k) }
+          else
+            {}
+          end
+        end
+
+        # Get count of registered validators
+        #
+        # @return [Integer] Number of registered validators
+        def count
+          VALIDATORS.size
+        end
+
+        # Create validator instance for a chunk
+        #
+        # @param chunk [Object] Chunk object with type and data
+        # @param context [ValidationContext] Validation context
+        # @return [BaseValidator, nil] Validator instance or nil
+        def create_validator(chunk, context)
+          validator_class = validator_for(chunk.type)
+          return nil unless validator_class
+
+          validator_class.new(chunk, context)
+        end
+      end
+    end
+  end
+end

data/lib/png_conform/validators/critical/idat_validator.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "../base_validator"
+
+module PngConform
+  module Validators
+    module Critical
+      # Validator for PNG IDAT (Image Data) chunk
+      #
+      # IDAT contains the compressed image data using zlib compression.
+      # Multiple IDAT chunks may be present and must be consecutive.
+      #
+      # Validation rules from PNG spec:
+      # - At least one IDAT chunk must be present
+      # - All IDAT chunks must be consecutive (no other chunks between them)
+      # - Must appear after IHDR chunk
+      # - Must appear after PLTE chunk (if present for indexed-color)
+      # - CRC must be valid
+      # - Combined data forms valid zlib stream (full validation in Phase 8)
+      #
+      # This validator performs basic structural checks.
+      # Full zlib decompression and filter validation is in Phase 8.
+      class IdatValidator < BaseValidator
+        # Validate IDAT chunk
+        #
+        # @return [Boolean] True if validation passed
+        def validate
+          return false unless check_crc
+          return false unless check_not_empty
+          return false unless check_position
+
+          record_idat_chunk
+          true
+        end
+
+        private
+
+        # Check that IDAT chunk is not empty
+        def check_not_empty
+          return true unless chunk.chunk_data.empty?
+
+          add_error("IDAT chunk is empty")
+          false
+        end
+
+        # Check IDAT position relative to other chunks
+        def check_position
+          valid = true
+
+          # IDAT must appear after IHDR
+          unless context.seen?("IHDR")
+            add_error("IDAT chunk before IHDR")
+            valid = false
+          end
+
+          # For indexed-color, IDAT must appear after PLTE
+          color_type = context.retrieve(:color_type)
+          if color_type == 3 && !context.seen?("PLTE")
+            add_error("IDAT chunk before PLTE for indexed-color image")
+            valid = false
+          end
+
+          valid
+        end
+
+        # Record IDAT chunk for sequence validation
+        def record_idat_chunk
+          context.record_chunk("IDAT", chunk)
+
+          # Track total IDAT size for compression ratio calculation
+          total_size = context.retrieve(:total_idat_size) || 0
+          context.store(:total_idat_size, total_size + chunk.chunk_data.length)
+        end
+      end
+    end
+  end
+end

data/lib/png_conform/validators/critical/iend_validator.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative "../base_validator"
+
+module PngConform
+  module Validators
+    module Critical
+      # Validator for PNG IEND (Image Trailer) chunk
+      #
+      # IEND marks the end of the PNG datastream.
+      #
+      # Validation rules from PNG spec:
+      # - Must be the last chunk in the file
+      # - Must be exactly 0 bytes in length
+      # - CRC must be valid
+      # - Must appear after at least one IDAT chunk
+      class IendValidator < BaseValidator
+        # Validate IEND chunk
+        #
+        # @return [Boolean] True if validation passed
+        def validate
+          return false unless check_crc
+          return false unless check_empty
+          return false unless check_position
+
+          record_iend_chunk
+          true
+        end
+
+        private
+
+        # Check that IEND chunk is empty
+        def check_empty
+          return true if chunk.chunk_data.empty?
+
+          add_error("invalid IEND chunk length " \
+                    "(#{chunk.chunk_data.length}, should be 0)")
+          false
+        end
+
+        # Check IEND position relative to other chunks
+        def check_position
+          valid = true
+
+          # IEND must appear after IHDR
+          unless context.seen?("IHDR")
+            add_error("IEND chunk before IHDR")
+            valid = false
+          end
+
+          # IEND must appear after at least one IDAT
+          unless context.seen?("IDAT")
+            add_error("IEND chunk before IDAT")
+            valid = false
+          end
+
+          valid
+        end
+
+        # Record IEND chunk
+        def record_iend_chunk
+          context.record_chunk("IEND", chunk)
+          context.store(:has_iend, true)
+        end
+      end
+    end
+  end
+end

data/lib/png_conform/validators/critical/ihdr_validator.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require_relative "../base_validator"
+
+module PngConform
+  module Validators
+    module Critical
+      # Validator for PNG IHDR (Image Header) chunk
+      #
+      # IHDR is always the first chunk in a PNG file and defines:
+      # - Image dimensions (width, height)
+      # - Bit depth
+      # - Color type
+      # - Compression method
+      # - Filter method
+      # - Interlace method
+      #
+      # Validation rules from PNG spec:
+      # - Must be exactly 13 bytes
+      # - Width and height must be non-zero
+      # - Bit depth must be valid for color type
+      # - Color type must be 0, 2, 3, 4, or 6
+      # - Compression method must be 0
+      # - Filter method must be 0
+      # - Interlace method must be 0 or 1
+      class IhdrValidator < BaseValidator
+        # Valid color types
+        COLOR_TYPES = {
+          0 => "grayscale",
+          2 => "truecolor",
+          3 => "indexed-color",
+          4 => "grayscale with alpha",
+          6 => "truecolor with alpha",
+        }.freeze
+
+        # Valid bit depths for each color type
+        VALID_BIT_DEPTHS = {
+          0 => [1, 2, 4, 8, 16],       # Grayscale
+          2 => [8, 16],                # Truecolor
+          3 => [1, 2, 4, 8],           # Indexed-color
+          4 => [8, 16],                # Grayscale with alpha
+          6 => [8, 16], # Truecolor with alpha
+        }.freeze
+
+        # Validate IHDR chunk
+        #
+        # @return [Boolean] True if validation passed
+        def validate
+          return false unless check_crc
+          return false unless check_length(13)
+
+          data = chunk.chunk_data
+          width = data[0, 4].unpack1("N")
+          height = data[4, 4].unpack1("N")
+          bit_depth = data[8].unpack1("C")
+          color_type = data[9].unpack1("C")
+          compression = data[10].unpack1("C")
+          filter = data[11].unpack1("C")
+          interlace = data[12].unpack1("C")
+
+          valid = true
+          valid &= check_dimensions(width, height)
+          valid &= check_color_type(color_type)
+          valid &= check_bit_depth(bit_depth, color_type)
+          valid &= check_compression(compression)
+          valid &= check_filter(filter)
+          valid &= check_interlace(interlace)
+
+          if valid
+            store_ihdr_info(width, height, bit_depth, color_type,
+                            interlace)
+          end
+
+          valid
+        end
+
+        private
+
+        # Check image dimensions
+        def check_dimensions(width, height)
+          valid = true
+
+          if width.zero?
+            add_error("invalid image width (0)")
+            valid = false
+          end
+
+          if height.zero?
+            add_error("invalid image height (0)")
+            valid = false
+          end
+
+          if width > 2**31 - 1
+            add_warning("image width (#{width}) exceeds maximum " \
+                        "recommended value")
+          end
+
+          if height > 2**31 - 1
+            add_warning("image height (#{height}) exceeds maximum " \
+                        "recommended value")
+          end
+
+          valid
+        end
+
+        # Check color type is valid
+        def check_color_type(color_type)
+          check_enum(color_type, COLOR_TYPES.keys, "color type")
+        end
+
+        # Check bit depth is valid for color type
+        def check_bit_depth(bit_depth, color_type)
+          return false unless COLOR_TYPES.key?(color_type)
+
+          valid_depths = VALID_BIT_DEPTHS[color_type]
+          return true if valid_depths.include?(bit_depth)
+
+          add_error("invalid bit depth (#{bit_depth}) for " \
+                    "#{COLOR_TYPES[color_type]} (must be one of " \
+                    "#{valid_depths.join(', ')})")
+          false
+        end
+
+        # Check compression method
+        def check_compression(compression)
+          if compression != 0
+            add_error("invalid compression method (#{compression}, " \
+                      "must be 0)")
+            return false
+          end
+          true
+        end
+
+        # Check filter method
+        def check_filter(filter)
+          if filter != 0
+            add_error("invalid filter method (#{filter}, must be 0)")
+            return false
+          end
+          true
+        end
+
+        # Check interlace method
+        def check_interlace(interlace)
+          check_enum(interlace, [0, 1], "interlace method")
+        end
+
+        # Store IHDR information in context for use by other validators
+        def store_ihdr_info(width, height, bit_depth, color_type, interlace)
+          context.store(:width, width)
+          context.store(:height, height)
+          context.store(:bit_depth, bit_depth)
+          context.store(:color_type, color_type)
+          context.store(:interlace, interlace)
+          context.store(:color_type_name, COLOR_TYPES[color_type])
+        end
+      end
+    end
+  end
+end

data/lib/png_conform/validators/critical/plte_validator.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative "../base_validator"
+
+module PngConform
+  module Validators
+    module Critical
+      # Validator for PNG PLTE (Palette) chunk
+      #
+      # PLTE defines the color palette for indexed-color images.
+      # - Required for color type 3 (indexed-color)
+      # - Optional for color types 2 and 6 (truecolor and truecolor+alpha)
+      # - Forbidden for color types 0 and 4 (grayscale and grayscale+alpha)
+      #
+      # Validation rules from PNG spec:
+      # - Length must be divisible by 3 (RGB triplets)
+      # - Must contain 1-256 palette entries
+      # - For indexed-color, number of entries must not exceed 2^bit_depth
+      # - Must appear before first IDAT chunk
+      # - Must appear before bKGD, hIST, tRNS chunks
+      class PlteValidator < BaseValidator
+        # Maximum number of palette entries
+        MAX_ENTRIES = 256
+
+        # Validate PLTE chunk
+        #
+        # @return [Boolean] True if validation passed
+        def validate
+          return false unless check_crc
+          return false unless check_divisible_by_3
+          return false unless check_entry_count
+          return false unless check_color_type_compatibility
+          return false unless check_bit_depth_compatibility
+
+          store_palette_info
+          true
+        end
+
+        private
+
+        # Check that chunk length is divisible by 3
+        def check_divisible_by_3
+          length = chunk.chunk_data.length
+          return true if (length % 3).zero?
+
+          add_error("invalid PLTE length (#{length}, must be divisible by 3)")
+          false
+        end
+
+        # Check number of palette entries
+        def check_entry_count
+          length = chunk.chunk_data.length
+          entries = length / 3
+
+          if entries.zero?
+            add_error("invalid PLTE chunk (no entries)")
+            return false
+          end
+
+          if entries > MAX_ENTRIES
+            add_error("invalid PLTE chunk (#{entries} entries, " \
+                      "maximum is #{MAX_ENTRIES})")
+            return false
+          end
+
+          true
+        end
+
+        # Check PLTE compatibility with color type
+        def check_color_type_compatibility
+          color_type = context.retrieve(:color_type)
+          return true unless color_type # IHDR not validated yet
+
+          case color_type
+          when 0, 4
+            # Grayscale and grayscale+alpha: PLTE forbidden
+            add_error("PLTE chunk not allowed for grayscale images")
+            false
+          when 3
+            # Indexed-color: PLTE required (checked elsewhere)
+            true
+          when 2, 6
+            # Truecolor and truecolor+alpha: PLTE optional (suggested palette)
+            add_info("PLTE chunk present (suggested palette)")
+            true
+          else
+            # Unknown color type
+            add_warning("PLTE chunk present but color type unknown")
+            true
+          end
+        end
+
+        # Check palette size vs bit depth for indexed-color images
+        def check_bit_depth_compatibility
+          color_type = context.retrieve(:color_type)
+          bit_depth = context.retrieve(:bit_depth)
+
+          return true unless color_type == 3 # Only for indexed-color
+          return true unless bit_depth # Bit depth not available
+
+          max_entries = 2**bit_depth
+          entries = chunk.chunk_data.length / 3
+
+          return true if entries <= max_entries
+
+          add_error("PLTE chunk has #{entries} entries but bit depth " \
+                    "#{bit_depth} allows maximum of #{max_entries}")
+          false
+        end
+
+        # Store palette information in context
+        def store_palette_info
+          entries = chunk.chunk_data.length / 3
+          context.store(:palette_entries, entries)
+          context.store(:has_palette, true)
+        end
+      end
+    end
+  end
+end