png_conform 0.1.1 → 0.1.3

data/lib/png_conform/services/file_signature.rb

@@ -0,0 +1,226 @@
+# frozen_string_literal: true
+
+require "digest"
+
+module PngConform
+  module Services
+    # File signature service for fast comparison
+    #
+    # Creates cryptographic signatures of PNG files to enable fast
+    # equality checking without full validation. This is particularly
+    # useful for comparison operations and caching.
+    #
+    # The signature is based on key file characteristics that are
+    # quick to compute but provide strong uniqueness guarantees.
+    #
+    class FileSignature
+      attr_reader :result, :signature, :metadata
+
+      class << self
+        # Create signature from ValidationResult
+        #
+        # @param result [ValidationResult] Validation result to signature
+        # @return [FileSignature] FileSignature instance
+        def from_result(result)
+          new(result).compute_signature
+        end
+
+        # Create signature directly from file metadata
+        #
+        # @param file_path [String] Path to PNG file
+        # @param options [Hash] Options for signature creation
+        # @return [FileSignature] FileSignature instance
+        def from_file(file_path, _options = {})
+          unless File.exist?(file_path)
+            raise ArgumentError, "File not found: #{file_path}"
+          end
+
+          # Quick signature from file metadata without full validation
+          metadata = extract_quick_metadata(file_path)
+          new(nil, metadata).compute_signature
+        end
+      end
+
+      # Initialize with validation result or metadata hash
+      #
+      # @param result [ValidationResult, nil] Validation result
+      # @param metadata [Hash, nil] File metadata hash
+      def initialize(result, metadata = nil)
+        @result = result
+        @metadata = metadata || extract_metadata_from_result
+        @signature = nil
+      end
+
+      # Compute the signature
+      #
+      # @return [FileSignature] Self for chaining
+      def compute_signature
+        @signature = generate_signature
+        self
+      end
+
+      # Check if two signatures are equal
+      #
+      # @param other [FileSignature, String] Another signature or signature string
+      # @return [Boolean] True if signatures match
+      def ==(other)
+        return false unless other.is_a?(self.class)
+
+        @signature == other.signature
+      end
+
+      # Get signature as hex string
+      #
+      # @return [String] Hex signature
+      def to_hex
+        @signature
+      end
+
+      # Get signature as bytes
+      #
+      # @return [String] Signature bytes
+      def to_bytes
+        [@signature].pack("H*")
+      end
+
+      # Get short signature (first 8 bytes of hex)
+      #
+      # @return [String] Short signature for quick comparison
+      def short_signature
+        @signature[0..15]
+      end
+
+      private
+
+      # Extract metadata from validation result
+      #
+      # @return [Hash] Metadata hash
+      def extract_metadata_from_result
+        return {} unless @result
+
+        {
+          file_size: @result.file_size,
+          chunk_count: @result.chunks.count,
+          chunk_types: @result.chunks.map(&:type).sort,
+          chunk_sizes: @result.chunks.map(&:length).sort,
+          crcs: @result.chunks.map do |c|
+            c.crc_actual || c.crc_expected
+          end.compact,
+        }
+      end
+
+      # Generate signature from metadata
+      #
+      # Uses SHA-256 on concatenated metadata for cryptographic strength.
+      #
+      # @return [String] Hex signature
+      def generate_signature
+        signature_data = signature_string
+        Digest::SHA256.hexdigest(signature_data)
+      end
+
+      # Build signature string from metadata
+      #
+      # Creates a deterministic string representation of key file attributes.
+      #
+      # @return [String] Signature string
+      def signature_string
+        StringIO.new.tap do |io|
+          # File size (8 bytes)
+          io << [@metadata[:file_size]].pack("N")
+
+          # Chunk count (4 bytes)
+          io << [@metadata[:chunk_count]].pack("N")
+
+          # Chunk types (sorted for consistency)
+          @metadata[:chunk_types].each do |type|
+            io << type.ljust(4, "\0")[0..3] # Fixed 4-char chunk types
+          end
+
+          # Chunk sizes (sorted for consistency)
+          @metadata[:chunk_sizes].each do |size|
+            io << [size].pack("N")
+          end
+
+          # CRC checksums (for integrity verification)
+          @metadata[:crcs].each do |crc|
+            io << [crc].pack("N")
+          end
+        end.string
+      end
+
+      # Extract quick metadata from file without full validation
+      #
+      # Reads just the PNG signature and chunk headers to create
+      # a signature without loading entire file into memory.
+      #
+      # @param file_path [String] Path to PNG file
+      # @return [Hash] Quick metadata hash
+      def extract_quick_metadata(file_path)
+        File.open(file_path, "rb") do |file|
+          # Verify PNG signature first
+          sig = file.read(8)
+          expected_sig = [137, 80, 78, 71, 13, 10, 26, 10].pack("C*")
+          unless sig == expected_sig
+            raise ArgumentError, "Not a valid PNG file: #{file_path}"
+          end
+
+          # Quick scan to count chunks and collect metadata
+          chunk_count = 0
+          chunk_types = []
+          chunk_sizes = []
+          total_data_size = 0
+
+          # Read entire file - no arbitrary limits for complete signatures
+          while file.pos < File.size(file_path)
+            # Read chunk length (4 bytes)
+            length_bytes = file.read(4)
+            break if length_bytes.nil? || length_bytes.length < 4
+
+            chunk_length = length_bytes.unpack1("N")
+            break if chunk_length > 10 * 1024 * 1024 # Sanity check
+
+            # Read chunk type (4 bytes)
+            type_bytes = file.read(4)
+            break if type_bytes.nil? || type_bytes.length < 4
+
+            chunk_type = type_bytes
+
+            # Skip data
+            file.seek(chunk_length, IO::SEEK_CUR)
+
+            # Read CRC (4 bytes)
+            crc_bytes = file.read(4)
+            break if crc_bytes.nil? || crc_bytes.length < 4
+
+            # Record metadata
+            chunk_count += 1
+            chunk_types << chunk_type
+            chunk_sizes << chunk_length
+            total_data_size += chunk_length
+
+            # Stop if we found IEND
+            break if chunk_type == "IEND"
+          end
+
+          {
+            file_size: File.size(file_path),
+            chunk_count: chunk_count,
+            chunk_types: chunk_types.sort,
+            chunk_sizes: chunk_sizes.sort,
+            crcs: [], # Not easily available without validation
+          }
+        end
+      rescue StandardError
+        # Fallback to basic metadata
+        {
+          file_size: File.size(file_path),
+          chunk_count: 0,
+          chunk_types: [],
+          chunk_sizes: [],
+          crcs: [],
+        }
+      end
+    end
+  end
+end

data/lib/png_conform/services/file_strategy.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module PngConform
+  module Services
+    # File strategy service for reader selection
+    #
+    # Determines the optimal reader type based on file characteristics
+    # and validation options. This enables automatic reader selection for
+    # better performance and memory efficiency.
+    #
+    class FileStrategy
+      # Large file threshold (10MB) - files larger than this use streaming
+      LARGE_FILE_THRESHOLD = 10 * 1024 * 1024
+
+      class << self
+        # Determine the appropriate reader type for a file
+        #
+        # @param file_path [String] Path to the PNG file
+        # @param options [Hash] Validation options
+        # @return [Symbol] Reader type (:streaming or :full_load)
+        def reader_type_for(file_path, options = {})
+          file_size = File.size(file_path)
+
+          # Use streaming for large files unless explicitly forced
+          if file_size > LARGE_FILE_THRESHOLD && !options[:force_full]
+            :streaming
+          else
+            :full_load
+          end
+        end
+
+        # Check if a file is considered large
+        #
+        # @param file_path [String] Path to the PNG file
+        # @return [Boolean] True if file is large
+        def large_file?(file_path)
+          File.size(file_path) > LARGE_FILE_THRESHOLD
+        end
+
+        # Get the threshold for large file detection
+        #
+        # @return [Integer] Threshold in bytes
+        def large_file_threshold
+          LARGE_FILE_THRESHOLD
+        end
+
+        # Calculate recommended chunk size for processing
+        #
+        # For large files, smaller chunks are better for memory management
+        #
+        # @param file_path [String] Path to the PNG file
+        # @return [Integer] Recommended chunk size in bytes
+        def recommended_chunk_size(file_path)
+          file_size = File.size(file_path)
+
+          if file_size > 100 * 1024 * 1024 # > 100MB
+            8192 # 8KB chunks for very large files
+          elsif file_size > 10 * 1024 * 1024 # > 10MB
+            16384 # 16KB chunks for large files
+          else
+            65536 # 64KB chunks for normal files
+          end
+        end
+
+        # Estimate memory usage for full-load reader
+        #
+        # @param file_path [String] Path to the PNG file
+        # @return [Integer] Estimated memory in bytes
+        def estimate_memory_usage(file_path)
+          file_size = File.size(file_path)
+          # Estimate: file_size + overhead for chunks (rough estimate)
+          # Each chunk adds overhead for BinData structures
+          file_size * 1.2
+        end
+      end
+    end
+  end
+end

data/lib/png_conform/services/lru_cache.rb

@@ -0,0 +1,170 @@
+# frozen_string_literal: true
+
+module PngConform
+  module Services
+    # LRU (Least Recently Used) Cache implementation
+    #
+    # Provides efficient caching with automatic eviction of least recently
+    # used items when capacity is reached. Thread-safe for basic operations.
+    #
+    class LRUCache
+      attr_reader :max_size, :current_size
+
+      # Initialize LRU cache
+      #
+      # @param max_size [Integer] Maximum number of items to store
+      # @param options [Hash] Additional options
+      def initialize(max_size, options = {})
+        @max_size = max_size
+        @cache = {}
+        @order = [] # Tracks access order (most recent at end)
+        @current_size = 0
+        @thread_safe = options[:thread_safe] || false
+        @mutex = @thread_safe ? Mutex.new : nil
+      end
+
+      # Get value for key
+      #
+      # @param key [Object] Cache key
+      # @return [Object, nil] Cached value or nil if not found
+      def [](key)
+        return @cache[key] if @thread_safe && !@mutex.synchronize do
+          @cache.key?(key)
+        end
+
+        with_synchronization do
+          return nil unless @cache.key?(key)
+
+          # Move to end (most recently used)
+          @order.delete(key)
+          @order.push(key)
+
+          @cache[key]
+        end
+      end
+
+      # Set value for key
+      #
+      # @param key [Object] Cache key
+      # @param value [Object] Value to cache
+      # @return [Object] The cached value
+      def []=(key, value)
+        with_synchronization do
+          # Remove existing key if updating (to re-insert at end)
+          @order.delete(key) if @cache.key?(key)
+
+          @cache[key] = value
+          @order.push(key)
+
+          # Evict oldest if over capacity
+          if @order.size > @max_size
+            oldest = @order.shift
+            @cache.delete(oldest)
+          end
+
+          @current_size = @cache.size
+        end
+
+        value
+      end
+
+      # Check if key exists
+      #
+      # @param key [Object] Cache key
+      # @return [Boolean] True if key exists in cache
+      def key?(key)
+        @cache.key?(key)
+      end
+
+      # Check if cache is empty
+      #
+      # @return [Boolean] True if cache has no items
+      def empty?
+        @cache.empty?
+      end
+
+      # Clear all cached items
+      #
+      # @return [void]
+      def clear
+        with_synchronization do
+          @cache.clear
+          @order.clear
+          @current_size = 0
+        end
+      end
+
+      # Get all keys
+      #
+      # @return [Array<Object>] All cached keys (in LRU order)
+      def keys
+        @order.dup # Return copy to avoid external modification
+      end
+
+      # Get cache statistics
+      #
+      # @return [Hash] Cache statistics
+      def stats
+        {
+          size: @cache.size,
+          max_size: @max_size,
+          usage_percent: ((@cache.size.to_f / @max_size) * 100).round(1),
+        }
+      end
+
+      # Delete a specific key
+      #
+      # @param key [Object] Cache key to delete
+      # @return [Object, nil] Deleted value or nil if not found
+      def delete(key)
+        with_synchronization do
+          @order.delete(key)
+          @cache.delete(key)
+          @current_size = @cache.size
+        end
+      end
+
+      # Peek at value without affecting LRU order
+      #
+      # @param key [Object] Cache key
+      # @return [Object, nil] Cached value or nil if not found
+      def peek(key)
+        @cache[key]
+      end
+
+      # Get most recently used item
+      #
+      # @return [Array] [key, value] or nil if empty
+      def mru
+        return nil if @order.empty?
+
+        key = @order.last
+        [key, @cache[key]]
+      end
+
+      # Get least recently used item
+      #
+      # @return [Array] [key, value] or nil if empty
+      def lru
+        return nil if @order.empty?
+
+        key = @order.first
+        [key, @cache[key]]
+      end
+
+      private
+
+      # Execute block with optional synchronization
+      #
+      # @yield Block to execute
+      # @return [Object] Block result
+      def with_synchronization(&block)
+        if @thread_safe && @mutex
+          @mutex.synchronize(&block)
+        else
+          yield
+        end
+      end
+    end
+  end
+end

data/lib/png_conform/services/parallel_validator.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require_relative "../container"
+require_relative "validation_orchestrator"
+require "etc"
+
+module PngConform
+  module Services
+    # Parallel validator for processing multiple files simultaneously
+    #
+    # Uses multi-threading to validate multiple PNG files in parallel,
+    # significantly reducing total validation time on multi-core systems.
+    #
+    # This service is MECE with ValidationOrchestrator - it handles
+    # the coordination of multiple file validations, while
+    # ValidationOrchestrator handles single file validation.
+    #
+    class ParallelValidator
+      # Default number of threads based on CPU count
+      DEFAULT_THREADS = [Etc.nprocessors, 4].max
+
+      attr_reader :files, :options, :threads
+
+      # Initialize parallel validator
+      #
+      # @param files [Array<String>] List of file paths to validate
+      # @param options [Hash] CLI options for validation behavior
+      def initialize(files, options = {})
+        @files = files
+        @options = options
+        @threads = options.fetch(:threads, DEFAULT_THREADS)
+      end
+
+      # Validate all files in parallel
+      #
+      # Uses Ruby's Parallel gem to distribute work across threads.
+      # Each file is validated independently using ValidationOrchestrator.
+      #
+      # @return [Array<FileAnalysis>] Array of validation results
+      def validate_all
+        require "parallel"
+
+        Parallel.map(@files, in_threads: @threads) do |file_path|
+          validate_single_file(file_path)
+        end
+      end
+
+      # Validate all files with progress callback
+      #
+      # @param progress_callback [Proc] Callback for progress updates
+      # @return [Array<FileAnalysis>] Array of validation results
+      def validate_all_with_progress(progress_callback = nil)
+        require "parallel"
+
+        completed = 0
+        total = @files.size
+
+        Parallel.map(@files, in_threads: @threads) do |file_path|
+          result = validate_single_file(file_path)
+
+          # Report progress if callback provided
+          if progress_callback
+            completed += 1
+            progress_callback.call(completed, total, file_path)
+          end
+
+          result
+        end
+      end
+
+      private
+
+      # Validate a single file
+      #
+      # Uses StreamingReader and ValidationOrchestrator for validation.
+      # Returns error hash if validation fails.
+      #
+      # @param file_path [String] Path to PNG file
+      # @return [FileAnalysis, Hash] Validation result or error hash
+      def validate_single_file(file_path)
+        # Check file existence first (avoid thread overhead for missing files)
+        unless File.exist?(file_path)
+          return {
+            error: "File not found: #{file_path}",
+            file: file_path,
+            valid: false,
+          }
+        end
+
+        unless File.file?(file_path)
+          return {
+            error: "Not a file: #{file_path}",
+            file: file_path,
+            valid: false,
+          }
+        end
+
+        # Use container to create reader and orchestrator
+        Container.open_reader(:streaming, file_path) do |reader|
+          orchestrator = Container.validation_orchestrator(
+            reader,
+            file_path,
+            @options.merge(filepath: file_path),
+          )
+          orchestrator.validate
+        end
+      rescue StandardError => e
+        # Return error hash instead of raising (keeps parallel processing going)
+        {
+          error: e.message,
+          file: file_path,
+          valid: false,
+          backtrace: @options[:verbose] ? e.backtrace.first(10) : nil,
+        }
+      end
+    end
+  end
+end

data/lib/png_conform/services/profile_manager.rb

@@ -1,5 +1,8 @@
 # frozen_string_literal: true
 
+require "yaml"
+require_relative "../configuration"
+
 module PngConform
   module Services
     # Profile manager for PNG validation profiles
@@ -7,16 +10,11 @@ module PngConform
     # Manages validation profiles that define which chunks are required,
     # optional, or prohibited for different PNG use cases.
     #
-    # Profiles can be used to validate PNG files against specific standards:
-    # - Web: Optimized for web browsers
-    # - Print: High quality for printing
-    # - Archive: Long-term preservation
-    # - Minimal: Minimal valid PNG
-    # - Strict: Full PNG specification compliance
+    # Profiles can be loaded from YAML configuration files or use built-in defaults.
     #
     class ProfileManager
-      # Built-in validation profiles
-      PROFILES = {
+      # Built-in validation profiles (fallback if YAML not available)
+      BUILTIN_PROFILES = {
         # Minimal valid PNG - only critical chunks
         minimal: {
           name: "Minimal",
@@ -99,10 +97,12 @@ module PngConform
       class << self
         # Get profile by name
         #
+        # Loads from YAML if available, otherwise uses built-in profiles
+        #
         # @param name [Symbol, String] Profile name
         # @return [Hash, nil] Profile configuration or nil if not found
         def get_profile(name)
-          PROFILES[name.to_sym]
+          profiles_from_yaml[name.to_sym] || BUILTIN_PROFILES[name.to_sym]
         end
 
         # Check if a profile exists
@@ -110,14 +110,15 @@ module PngConform
         # @param name [Symbol, String] Profile name
         # @return [Boolean] True if profile exists
         def profile_exists?(name)
-          PROFILES.key?(name.to_sym)
+          sym_name = name.to_sym
+          profiles_from_yaml.key?(sym_name) || BUILTIN_PROFILES.key?(sym_name)
         end
 
         # Get all available profile names
         #
         # @return [Array<Symbol>] List of profile names
         def available_profiles
-          PROFILES.keys
+          (profiles_from_yaml.keys | BUILTIN_PROFILES.keys).uniq.sort
         end
 
         # Get profile information
@@ -149,7 +150,7 @@ module PngConform
             )
           elsif profile[:required_chunks].include?(chunk_type)
             success_result("#{chunk_type} chunk required and present")
-          elsif profile[:optional_chunks].include?(chunk_type)
+          elsif profile[:optional_chunks].include?(chunk_type) || profile[:optional_chunks] == ["*"]
             success_result("#{chunk_type} chunk optional and present")
           else
             warning_result(
@@ -211,8 +212,36 @@ module PngConform
           results
         end
 
+        # Reload profiles from YAML
+        #
+        # @return [void]
+        def reload_yaml_profiles!
+          @profiles_from_yaml = nil
+        end
+
         private
 
+        # Load profiles from YAML configuration file
+        #
+        # @return [Hash] Profiles loaded from YAML
+        def profiles_from_yaml
+          @profiles_from_yaml ||= load_yaml_profiles
+        end
+
+        # Load profiles from YAML file
+        #
+        # @return [Hash] Loaded profiles or empty hash if file not found
+        def load_yaml_profiles
+          config_path = File.join(File.dirname(__FILE__),
+                                  "../../config/validation_profiles.yml")
+          return {} unless File.exist?(config_path)
+
+          YAML.load_file(config_path).transform_keys(&:to_sym)
+        rescue StandardError => e
+          warn "Failed to load profiles from YAML: #{e.message}"
+          {}
+        end
+
         # Create success result
         #
         # @param message [String] Success message