png_conform 0.1.2 → 0.1.3

data/lib/png_conform/services/validation_cache.rb

@@ -0,0 +1,210 @@
+# frozen_string_literal: true
+
+require_relative "lru_cache"
+require "digest"
+
+module PngConform
+  module Services
+    # Validation cache for storing and reusing validation results
+    #
+    # Provides multi-level caching for validation operations to avoid
+    # redundant I/O and computation. Supports LRU eviction for memory efficiency.
+    #
+    class ValidationCache
+      attr_reader :file_cache, :max_files, :enabled
+
+      # Default configuration
+      DEFAULT_MAX_FILES = 100
+      DEFAULT_ENABLED = true
+
+      class << self
+        # Get global singleton instance
+        #
+        # @return [ValidationCache] Global cache instance
+        def instance
+          @instance ||= new
+        end
+
+        # Reset global cache
+        #
+        # @return [void]
+        def reset!
+          @instance = new
+        end
+      end
+
+      # Initialize validation cache
+      #
+      # @param options [Hash] Cache configuration options
+      def initialize(options = {})
+        @max_files = options.fetch(:max_files, DEFAULT_MAX_FILES)
+        @file_cache = LRUCache.new(@max_files)
+        @enabled = options.fetch(:enabled, DEFAULT_ENABLED)
+        @stats = {
+          hits: 0,
+          misses: 0,
+          evictions: 0,
+        }
+      end
+
+      # Fetch cached validation result for a file
+      #
+      # @param file_path [String] Path to PNG file
+      # @param options [Hash] Validation options (affects cache key)
+      # @return [FileAnalysis, nil] Cached result or nil if not cached
+      def fetch(file_path, options = {})
+        return nil unless @enabled
+
+        cache_key = generate_cache_key(file_path, options)
+        entry = @file_cache[cache_key]
+
+        if entry
+          @stats[:hits] += 1
+          # Return shallow copy - FileAnalysis objects are read-only after creation
+          # This is significantly faster than Marshal deep copy
+          shallow_copy(entry[:result])
+        else
+          @stats[:misses] += 1
+          nil
+        end
+      end
+
+      # Store validation result in cache
+      #
+      # @param file_path [String] Path to PNG file
+      # @param options [Hash] Validation options (affects cache key)
+      # @param result [FileAnalysis] Validation result to cache
+      # @return [void]
+      def store(file_path, options, result)
+        return unless @enabled
+
+        cache_key = generate_cache_key(file_path, options)
+        entry = {
+          result: result, # Store reference - objects are read-only
+          timestamp: Time.now,
+          file_size: result.file_size,
+          validation_time: result.validation_result&.validation_time,
+        }
+
+        @file_cache[cache_key] = entry
+      end
+
+      # Check if file validation is cached
+      #
+      # @param file_path [String] Path to PNG file
+      # @param options [Hash] Validation options
+      # @return [Boolean] True if result is cached
+      def cached?(file_path, options = {})
+        return false unless @enabled
+
+        cache_key = generate_cache_key(file_path, options)
+        @file_cache.key?(cache_key)
+      end
+
+      # Invalidate cache entry for a file
+      #
+      # @param file_path [String] Path to PNG file
+      # @param options [Hash] Validation options (optional)
+      # @return [Boolean] True if entry was found and removed
+      def invalidate(file_path, options = {})
+        return false unless @enabled
+
+        cache_key = generate_cache_key(file_path, options)
+        deleted = @file_cache.delete(cache_key)
+
+        if deleted
+          @stats[:evictions] += 1
+        end
+
+        !!deleted
+      end
+
+      # Clear all cached entries
+      #
+      # @return [void]
+      def clear
+        @file_cache.clear
+        reset_stats
+      end
+
+      # Get cache statistics
+      #
+      # @return [Hash] Cache performance statistics
+      def stats
+        total_requests = @stats[:hits] + @stats[:misses]
+        hit_rate = if total_requests.positive?
+                     (@stats[:hits].to_f / total_requests * 100).round(1)
+                   else
+                     0.0
+                   end
+
+        {
+          enabled: @enabled,
+          max_files: @max_files,
+          current_files: @file_cache.current_size,
+          hits: @stats[:hits],
+          misses: @stats[:misses],
+          evictions: @stats[:evictions],
+          hit_rate: hit_rate,
+          cache_stats: @file_cache.stats,
+        }
+      end
+
+      # Reset statistics counters
+      #
+      # @return [void]
+      def reset_stats
+        @stats = {
+          hits: 0,
+          misses: 0,
+          evictions: 0,
+        }
+      end
+
+      # Get cache key for file validation
+      #
+      # The cache key includes file path, mtime, and relevant options
+      # to ensure cache validity when files change or options differ.
+      #
+      # @param file_path [String] Path to PNG file
+      # @param options [Hash] Validation options
+      # @return [String] Cache key
+      def generate_cache_key(file_path, options = {})
+        # Include relevant options in cache key
+        relevant_opts = options.slice(:profile, :batch_enabled, :fail_fast)
+
+        # Get file modification time for cache invalidation
+        mtime = begin
+          File.mtime(file_path).to_i
+        rescue StandardError
+          0
+        end
+
+        # Create deterministic cache key
+        key_parts = [
+          file_path,
+          mtime,
+          relevant_opts.sort.to_h,
+        ]
+
+        Digest::SHA256.hexdigest(key_parts.flatten.join(":"))
+      end
+
+      private
+
+      # Create shallow copy of result object
+      #
+      # Uses .dup for fast shallow copying. FileAnalysis objects are
+      # effectively read-only after creation, so deep copying is unnecessary.
+      #
+      # @param obj [Object] Object to copy
+      # @return [Object] Shallow copy of object
+      def shallow_copy(obj)
+        obj.dup
+      rescue TypeError
+        # For objects that can't be dup'd, return as-is
+        obj
+      end
+    end
+  end
+end

data/lib/png_conform/services/validation_orchestrator.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require_relative "chunk_processor"
+require_relative "result_builder"
+require_relative "analysis_manager"
+
+module PngConform
+  module Services
+    # Main validation orchestration service
+    #
+    # This service coordinates the validation of PNG files by:
+    # 1. Validating the PNG signature
+    # 2. Processing chunks through ChunkProcessor
+    # 3. Validating chunk sequence requirements
+    # 4. Building the complete FileAnalysis result
+    #
+    # The orchestrator follows a pipeline architecture:
+    # File → Signature → Chunks → Sequence → Analysis → Result
+    #
+    class ValidationOrchestrator
+      attr_reader :reader, :filepath, :options, :context, :chunks
+
+      # Convenience method to validate a file by path
+      #
+      # @param filepath [String] Path to PNG file
+      # @param options [Hash] Optional CLI options
+      # @return [FileAnalysis] Complete file analysis
+      def self.validate_file(filepath, options = {})
+        require_relative "../readers/full_load_reader"
+        reader = Readers::FullLoadReader.new(filepath)
+        new(reader, filepath, options).validate
+      end
+
+      # Initialize validation orchestrator
+      #
+      # @param reader [Object] File reader (StreamingReader or FullLoadReader)
+      # @param filepath [String, nil] Optional file path (for reporting)
+      # @param options [Hash] CLI options for controlling behavior
+      def initialize(reader, filepath = nil, options = {})
+        @reader = reader
+        @filepath = filepath
+        @options = options
+        @context = Validators::ValidationContext.new
+        @chunks = []
+      end
+
+      # Validate the PNG file
+      #
+      # This is the main entry point for validation. It orchestrates
+      # all validation stages in the correct order.
+      #
+      # @return [FileAnalysis] Complete file analysis with all data
+      def validate
+        validate_signature
+        process_chunks
+        validate_sequence
+        build_result
+      end
+
+      # Get all errors from the validation context
+      #
+      # @return [Array<Hash>] Array of error hashes
+      def errors
+        @context.all_errors
+      end
+
+      # Get all warnings from the validation context
+      #
+      # @return [Array<Hash>] Array of warning hashes
+      def warnings
+        @context.all_warnings
+      end
+
+      # Get all info messages from the validation context
+      #
+      # @return [Array<Hash>] Array of info hashes
+      def info_messages
+        @context.all_info
+      end
+
+      private
+
+      # Validate PNG signature
+      #
+      # Checks that the file starts with the PNG signature:
+      # 137 80 78 71 13 10 26 10
+      #
+      # @return [void]
+      def validate_signature
+        sig = reader.signature
+        expected = [137, 80, 78, 71, 13, 10, 26, 10].pack("C*")
+
+        return if sig == expected
+
+        @context.add_error(
+          chunk_type: "SIGNATURE",
+          message: "Invalid PNG signature",
+          severity: :error,
+        )
+      end
+
+      # Process all chunks using ChunkProcessor
+      #
+      # Delegates chunk validation to the ChunkProcessor which handles:
+      # - Iterating through chunks
+      # - Creating validators via ChunkRegistry
+      # - Collecting validation results
+      #
+      # @return [void]
+      def process_chunks
+        processor = ChunkProcessor.new(@reader, @context, @options)
+        processor.process do |chunk|
+          @chunks << chunk
+        end
+      end
+
+      # Validate chunk sequence requirements
+      #
+      # Checks high-level sequencing rules:
+      # - IHDR must be first chunk
+      # - IEND must be last chunk
+      # - At least one IDAT chunk required
+      #
+      # @return [void]
+      def validate_sequence
+        validate_ihdr_first
+        validate_iend_last
+        validate_idat_present
+      end
+
+      # Check that IHDR is the first chunk
+      #
+      # @return [void]
+      def validate_ihdr_first
+        return if @context.seen?("IHDR")
+
+        @context.add_error(
+          chunk_type: "IHDR",
+          message: "Missing IHDR chunk (must be first)",
+          severity: :error,
+        )
+      end
+
+      # Check that IEND is the last chunk
+      #
+      # @return [void]
+      def validate_iend_last
+        return if @context.seen?("IEND")
+
+        @context.add_error(
+          chunk_type: "IEND",
+          message: "Missing IEND chunk (must be last)",
+          severity: :error,
+        )
+      end
+
+      # Check that at least one IDAT chunk exists
+      #
+      # @return [void]
+      def validate_idat_present
+        return if @context.seen?("IDAT")
+
+        @context.add_error(
+          chunk_type: "IDAT",
+          message: "Missing IDAT chunk (at least one required)",
+          severity: :error,
+        )
+      end
+
+      # Build complete FileAnalysis with validation results and analyzer data
+      #
+      # Coordinates ResultBuilder and AnalysisManager to produce the final result
+      #
+      # @return [FileAnalysis] Complete analysis model
+      def build_result
+        result_builder = ResultBuilder.new(@reader, @filepath, @context,
+                                           @chunks, @options)
+        file_analysis = result_builder.build
+
+        # Run analyzers through AnalysisManager
+        analysis_manager = AnalysisManager.new(@options)
+        analysis_manager.enrich(file_analysis)
+
+        file_analysis
+      end
+    end
+  end
+end