png_conform 0.1.1 → 0.1.3

data/lib/png_conform/utils/colorizer.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "paint"
+
+module PngConform
+  module Utils
+    # Colorization utility using the Paint gem
+    #
+    # Provides a centralized colorization service for terminal output.
+    # Wraps the Paint gem with semantic method names and caching.
+    #
+    # @example Basic usage
+    #   Colorizer.success("Success message")
+    #   Colorizer.error("Error message")
+    #   Colorizer.warning("Warning message", bold: true)
+    #
+    class Colorizer
+      class << self
+        # Check if colorization is enabled
+        #
+        # @return [Boolean] true if colors are enabled
+        def enabled?
+          Paint.mode != 0
+        end
+
+        # Enable or disable colorization
+        #
+        # @param value [Boolean] true to enable, false to disable
+        def enabled=(value)
+          Paint.mode = value ? Paint.detect_mode : 0
+        end
+
+        # Colorize text as success (green)
+        #
+        # @param text [String] Text to colorize
+        # @param bold [Boolean] Whether to use bold formatting
+        # @return [String] Colorized text
+        def success(text, bold: false)
+          colorize(text, :green, bold: bold)
+        end
+
+        # Colorize text as error (red)
+        #
+        # @param text [String] Text to colorize
+        # @param bold [Boolean] Whether to use bold formatting
+        # @return [String] Colorized text
+        def error(text, bold: false)
+          colorize(text, :red, bold: bold)
+        end
+
+        # Colorize text as warning (yellow)
+        #
+        # @param text [String] Text to colorize
+        # @param bold [Boolean] Whether to use bold formatting
+        # @return [String] Colorized text
+        def warning(text, bold: false)
+          colorize(text, :yellow, bold: bold)
+        end
+
+        # Colorize text as info (blue)
+        #
+        # @param text [String] Text to colorize
+        # @param bold [Boolean] Whether to use bold formatting
+        # @return [String] Colorized text
+        def info(text, bold: false)
+          colorize(text, :blue, bold: bold)
+        end
+
+        # Colorize text with bold formatting
+        #
+        # @param text [String] Text to colorize
+        # @param color [Symbol] Color to use
+        # @return [String] Colorized text
+        def bold(text, color = nil)
+          return Paint[text, :bold] unless color
+
+          Paint[text, color, :bold]
+        end
+
+        # Colorize text with a specific color
+        #
+        # @param text [String] Text to colorize
+        # @param color [Symbol] Color to use
+        # @param bold [Boolean] Whether to use bold formatting
+        # @return [String] Colorized text
+        def colorize(text, color, bold: false)
+          return text.to_s unless enabled?
+
+          if bold
+            Paint[text, color, :bold]
+          else
+            Paint[text, color]
+          end
+        end
+
+        # Colorize text based on priority
+        #
+        # @param text [String] Text to colorize
+        # @param priority [Symbol] Priority (:high, :medium, :low)
+        # @return [String] Colorized text
+        def priority(text, priority:)
+          case priority
+          when :high
+            error(text, bold: true)
+          when :medium
+            warning(text, bold: true)
+          when :low
+            info(text)
+          else
+            text.to_s
+          end
+        end
+
+        # Get a checkmark symbol (with color)
+        #
+        # @param success [Boolean] Whether the check should be green
+        # @return [String] Colored checkmark
+        def checkmark(success: true)
+          if success
+            success("✓")
+          else
+            error("✗")
+          end
+        end
+
+        # Remove all color codes from text
+        #
+        # @param text [String] Text to uncolorize
+        # @return [String] Plain text
+        def uncolorize(text)
+          Paint.unpaint(text)
+        end
+
+        # Apply multiple colorizations to different parts of text
+        #
+        # @param template [String] Template with %{key} placeholders
+        # @param substitutions [Hash] Hash of key => [text, color] pairs
+        # @return [String] Colorized text
+        # @example
+        #   Colorizer.template("%{greeting} %{name}",
+        #     greeting: ["Hello", :green],
+        #     name: ["World", :blue])
+        def template(template, substitutions)
+          Paint[template, substitutions]
+        end
+      end
+    end
+  end
+end

data/lib/png_conform/validators/ancillary/idot_validator.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative "../base_validator"
+
+module PngConform
+  module Validators
+    module Ancillary
+      # Validator for PNG iDOT (Apple Display Optimization) chunk
+      #
+      # iDOT is an Apple-specific chunk found in screenshots and images saved
+      # from macOS/iOS devices. It contains display optimization data for
+      # Retina displays and multi-core decoding performance.
+      #
+      # Structure (28 bytes - seven 32-bit little-endian integers):
+      # - Display scale factor (4 bytes)
+      # - Pixel format information (4 bytes)
+      # - Color space information (4 bytes)
+      # - Backing scale factor (4 bytes)
+      # - Flags (4 bytes)
+      # - Reserved field 1 (4 bytes)
+      # - Reserved field 2 (4 bytes)
+      #
+      # Validation rules:
+      # - Chunk must be exactly 28 bytes
+      # - Only one iDOT chunk allowed
+      # - Must appear before IDAT chunk
+      #
+      # References:
+      # - Apple's proprietary display optimization format
+      # - Used in macOS/iOS screenshot PNG files
+      class IdotValidator < BaseValidator
+        # Expected chunk length (7 x 4-byte integers)
+        EXPECTED_LENGTH = 28
+
+        # Validate iDOT chunk
+        #
+        # @return [Boolean] True if validation passed
+        def validate
+          return false unless check_crc
+          return false unless check_length(EXPECTED_LENGTH)
+          return false unless check_uniqueness
+          return false unless check_position
+
+          decode_and_store_data
+          true
+        end
+
+        private
+
+        # Check that only one iDOT chunk exists
+        def check_uniqueness
+          if context.seen?("iDOT")
+            add_error("duplicate iDOT chunk (only one allowed)")
+            return false
+          end
+
+          true
+        end
+
+        # Check that iDOT appears before IDAT
+        def check_position
+          if context.seen?("IDAT")
+            add_error("iDOT chunk after IDAT (must be before)")
+            return false
+          end
+
+          true
+        end
+
+        # Decode iDOT data and store in context
+        def decode_and_store_data
+          values = chunk.chunk_data.unpack("V7")
+
+          # Create IdotData model
+          idot_data = create_idot_data(values)
+
+          # Store in context for later use
+          context.store(:idot_data, idot_data)
+
+          # Add info message with decoded data
+          add_info("iDOT: Apple display optimization (#{idot_data.detailed_info})")
+        end
+
+        # Create IdotData model from parsed values
+        #
+        # @param values [Array<Integer>] Seven 32-bit integers
+        # @return [Models::IdotData] The decoded data model
+        def create_idot_data(values)
+          Models::IdotData.new(
+            display_scale: values[0],
+            pixel_format: values[1],
+            color_space: values[2],
+            backing_scale_factor: values[3],
+            flags: values[4],
+            reserved1: values[5],
+            reserved2: values[6],
+          )
+        end
+      end
+    end
+  end
+end

data/lib/png_conform/validators/chunk_registry.rb

@@ -1,54 +1,14 @@
 # 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
+    # Define validator category modules upfront for proper namespace resolution
+    module Critical; end
+    module Ancillary; end
+    module Apng; end
+    module Mng; end
+    module Jng; end
+
     # Registry of chunk types to their corresponding validator classes
     #
     # This class maintains a mapping between PNG chunk type codes and
@@ -62,85 +22,100 @@ module PngConform
     # - Palette support (hIST, sPLT, tRNS)
     # - Metadata (pHYs, tIME, oFFs, pCAL, sCAL, sTER)
     # - PNG 3rd edition (cICP, mDCv)
+    # - Apple extensions (iDOT)
     # - APNG (acTL, fcTL, fdAT)
     # - MNG (MHDR, MEND, DHDR, FRAM, DEFI, BACK, LOOP, ENDL, etc.)
     # - JNG (JHDR, JDAT, JSEP)
     #
+    # Validators are loaded lazily on-demand to improve startup performance.
+    #
     class ChunkRegistry
-      # Map of chunk type codes to validator classes
-      VALIDATORS = {
+      # Map of chunk type codes to validator file paths and class names
+      # Format: [file_path, module_path, class_name]
+      VALIDATOR_PATHS = {
         # Critical chunks
-        "IHDR" => Critical::IhdrValidator,
-        "PLTE" => Critical::PlteValidator,
-        "IDAT" => Critical::IdatValidator,
-        "IEND" => Critical::IendValidator,
+        "IHDR" => ["critical/ihdr_validator", "Critical", "IhdrValidator"],
+        "PLTE" => ["critical/plte_validator", "Critical", "PlteValidator"],
+        "IDAT" => ["critical/idat_validator", "Critical", "IdatValidator"],
+        "IEND" => ["critical/iend_validator", "Critical", "IendValidator"],
 
         # Text chunks
-        "tEXt" => Ancillary::TextValidator,
-        "zTXt" => Ancillary::ZtxtValidator,
-        "iTXt" => Ancillary::ItxtValidator,
+        "tEXt" => ["ancillary/text_validator", "Ancillary", "TextValidator"],
+        "zTXt" => ["ancillary/ztxt_validator", "Ancillary", "ZtxtValidator"],
+        "iTXt" => ["ancillary/itxt_validator", "Ancillary", "ItxtValidator"],
 
         # Color management
-        "gAMA" => Ancillary::GamaValidator,
-        "cHRM" => Ancillary::ChrmValidator,
-        "sRGB" => Ancillary::SrgbValidator,
-        "sBIT" => Ancillary::SbitValidator,
-        "bKGD" => Ancillary::BkgdValidator,
-        "iCCP" => Ancillary::IccpValidator,
+        "gAMA" => ["ancillary/gama_validator", "Ancillary", "GamaValidator"],
+        "cHRM" => ["ancillary/chrm_validator", "Ancillary", "ChrmValidator"],
+        "sRGB" => ["ancillary/srgb_validator", "Ancillary", "SrgbValidator"],
+        "sBIT" => ["ancillary/sbit_validator", "Ancillary", "SbitValidator"],
+        "bKGD" => ["ancillary/bkgd_validator", "Ancillary", "BkgdValidator"],
+        "iCCP" => ["ancillary/iccp_validator", "Ancillary", "IccpValidator"],
 
         # Palette support
-        "hIST" => Ancillary::HistValidator,
-        "sPLT" => Ancillary::SpltValidator,
-        "tRNS" => Ancillary::TrnsValidator,
+        "hIST" => ["ancillary/hist_validator", "Ancillary", "HistValidator"],
+        "sPLT" => ["ancillary/splt_validator", "Ancillary", "SpltValidator"],
+        "tRNS" => ["ancillary/trns_validator", "Ancillary", "TrnsValidator"],
 
         # Metadata
-        "pHYs" => Ancillary::PhysValidator,
-        "tIME" => Ancillary::TimeValidator,
-        "oFFs" => Ancillary::OffsValidator,
-        "pCAL" => Ancillary::PcalValidator,
-        "sCAL" => Ancillary::ScalValidator,
-        "sTER" => Ancillary::SterValidator,
+        "pHYs" => ["ancillary/phys_validator", "Ancillary", "PhysValidator"],
+        "tIME" => ["ancillary/time_validator", "Ancillary", "TimeValidator"],
+        "oFFs" => ["ancillary/offs_validator", "Ancillary", "OffsValidator"],
+        "pCAL" => ["ancillary/pcal_validator", "Ancillary", "PcalValidator"],
+        "sCAL" => ["ancillary/scal_validator", "Ancillary", "ScalValidator"],
+        "sTER" => ["ancillary/ster_validator", "Ancillary", "SterValidator"],
 
         # PNG 3rd edition
-        "cICP" => Ancillary::CicpValidator,
-        "mDCv" => Ancillary::MdcvValidator,
+        "cICP" => ["ancillary/cicp_validator", "Ancillary", "CicpValidator"],
+        "mDCv" => ["ancillary/mdcv_validator", "Ancillary", "MdcvValidator"],
+
+        # Apple extensions
+        "iDOT" => ["ancillary/idot_validator", "Ancillary", "IdotValidator"],
 
         # APNG (Animated PNG)
-        "acTL" => Apng::ActlValidator,
-        "fcTL" => Apng::FctlValidator,
-        "fdAT" => Apng::FdatValidator,
+        "acTL" => ["apng/actl_validator", "Apng", "ActlValidator"],
+        "fcTL" => ["apng/fctl_validator", "Apng", "FctlValidator"],
+        "fdAT" => ["apng/fdat_validator", "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,
+        "MHDR" => ["mng/mhdr_validator", "Mng", "MhdrValidator"],
+        "MEND" => ["mng/mend_validator", "Mng", "MendValidator"],
+        "DHDR" => ["mng/dhdr_validator", "Mng", "DhdrValidator"],
+        "FRAM" => ["mng/fram_validator", "Mng", "FramValidator"],
+        "DEFI" => ["mng/defi_validator", "Mng", "DefiValidator"],
+        "BACK" => ["mng/back_validator", "Mng", "BackValidator"],
+        "LOOP" => ["mng/loop_validator", "Mng", "LoopValidator"],
+        "ENDL" => ["mng/endl_validator", "Mng", "EndlValidator"],
+        "TERM" => ["mng/term_validator", "Mng", "TermValidator"],
+        "SAVE" => ["mng/save_validator", "Mng", "SaveValidator"],
+        "SEEK" => ["mng/seek_validator", "Mng", "SeekValidator"],
+        "MOVE" => ["mng/move_validator", "Mng", "MoveValidator"],
+        "CLIP" => ["mng/clip_validator", "Mng", "ClipValidator"],
+        "SHOW" => ["mng/show_validator", "Mng", "ShowValidator"],
+        "CLON" => ["mng/clon_validator", "Mng", "ClonValidator"],
+        "DISC" => ["mng/disc_validator", "Mng", "DiscValidator"],
 
         # JNG (JPEG Network Graphics)
-        "JHDR" => Jng::JhdrValidator,
-        "JDAT" => Jng::JdatValidator,
-        "JSEP" => Jng::JsepValidator,
+        "JHDR" => ["jng/jhdr_validator", "Jng", "JhdrValidator"],
+        "JDAT" => ["jng/jdat_validator", "Jng", "JdatValidator"],
+        "JSEP" => ["jng/jsep_validator", "Jng", "JsepValidator"],
       }.freeze
 
       class << self
-        # Get validator class for a chunk type
+        # Get validator class for a chunk type (with lazy loading)
         #
         # @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]
+          # Return cached validator if already loaded
+          return loaded_validators[chunk_type] if loaded_validators.key?(chunk_type)
+
+          # Check if validator path exists
+          validator_info = VALIDATOR_PATHS[chunk_type]
+          return nil unless validator_info
+
+          # Load validator on-demand
+          load_validator(chunk_type, validator_info)
         end
 
         # Check if a validator exists for a chunk type
@@ -148,14 +123,14 @@ module PngConform
         # @param chunk_type [String] Four-character chunk type code
         # @return [Boolean] True if validator exists
         def validator_exists?(chunk_type)
-          VALIDATORS.key?(chunk_type)
+          VALIDATOR_PATHS.key?(chunk_type)
         end
 
         # Get all registered chunk types
         #
         # @return [Array<String>] List of chunk type codes
         def chunk_types
-          VALIDATORS.keys
+          VALIDATOR_PATHS.keys
         end
 
         # Get validators by category
@@ -164,34 +139,34 @@ module PngConform
         #   (: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
-            {}
+          chunk_types = case category
+                        when :critical
+                          %w[IHDR PLTE IDAT IEND]
+                        when :text
+                          %w[tEXt zTXt iTXt]
+                        when :color
+                          %w[gAMA cHRM sRGB sBIT bKGD iCCP]
+                        when :palette
+                          %w[hIST sPLT tRNS]
+                        when :metadata
+                          %w[pHYs tIME oFFs pCAL sCAL sTER]
+                        when :png3
+                          %w[cICP mDCv]
+                        when :apng
+                          %w[acTL fcTL fdAT]
+                        when :mng
+                          %w[MHDR MEND DHDR FRAM DEFI BACK LOOP ENDL TERM SAVE SEEK
+                             MOVE CLIP SHOW CLON DISC]
+                        when :jng
+                          %w[JHDR JDAT JSEP]
+                        else
+                          []
+                        end
+
+          # Load validators for this category
+          chunk_types.each_with_object({}) do |chunk_type, result|
+            validator = validator_for(chunk_type)
+            result[chunk_type] = validator if validator
           end
         end
 
@@ -199,7 +174,7 @@ module PngConform
         #
         # @return [Integer] Number of registered validators
         def count
-          VALIDATORS.size
+          VALIDATOR_PATHS.size
         end
 
         # Create validator instance for a chunk
@@ -213,6 +188,46 @@ module PngConform
 
           validator_class.new(chunk, context)
         end
+
+        # Preload all validators for performance
+        #
+        # Loads all validator classes into cache at startup to improve
+        # validation performance by avoiding lazy loading overhead.
+        #
+        # @return [void]
+        def preload_validators!
+          VALIDATOR_PATHS.each_key do |chunk_type|
+            validator_for(chunk_type)
+          end
+        end
+
+        private
+
+        # Cache for loaded validator classes
+        def loaded_validators
+          @loaded_validators ||= {}
+        end
+
+        # Load a validator class on-demand
+        #
+        # @param chunk_type [String] Chunk type code
+        # @param validator_info [Array] [file_path, module_name, class_name]
+        # @return [Class, nil] Loaded validator class
+        def load_validator(chunk_type, validator_info)
+          file_path, module_name, class_name = validator_info
+
+          # Require the validator file
+          require_relative file_path
+
+          # Resolve the constant (e.g., Critical::IhdrValidator)
+          validator_class = Validators.const_get(module_name).const_get(class_name)
+
+          # Cache and return
+          loaded_validators[chunk_type] = validator_class
+        rescue NameError, LoadError => e
+          warn "Failed to load validator for #{chunk_type}: #{e.message}"
+          loaded_validators[chunk_type] = nil
+        end
       end
     end
   end