png_conform 0.1.1 → 0.1.3

data/lib/png_conform/services/result_builder.rb

@@ -0,0 +1,299 @@
+# frozen_string_literal: true
+
+require_relative "../models/validation_result"
+require_relative "../models/file_analysis"
+require_relative "../models/image_info"
+require_relative "../models/compression_info"
+
+module PngConform
+  module Services
+    # Builds validation results and file analysis
+    #
+    # The ResultBuilder handles:
+    # - Building ValidationResult from validation context
+    # - Extracting ImageInfo from IHDR chunk
+    # - Extracting CompressionInfo (lazy calculation)
+    # - Building complete FileAnalysis model
+    #
+    # This class extracts result building logic from ValidationService
+    # following Single Responsibility Principle.
+    #
+    class ResultBuilder
+      # Initialize result builder
+      #
+      # @param reader [Object] File reader (StreamingReader or FullLoadReader)
+      # @param filepath [String] File path for reporting
+      # @param context [ValidationContext] Validation context with results
+      # @param chunks [Array] Array of BinData chunks
+      # @param options [Hash] CLI options for conditional calculations
+      def initialize(reader, filepath, context, chunks, options = {})
+        @reader = reader
+        @filepath = filepath
+        @context = context
+        @chunks = chunks
+        @options = options
+        @idat_data_cache = nil # Cache for streaming IDAT data
+      end
+
+      # Build complete FileAnalysis with all data
+      #
+      # @return [FileAnalysis] Complete analysis model
+      def build
+        # First build the ValidationResult
+        validation_result = build_validation_result
+
+        # Extract image info from IHDR
+        image_info = extract_image_info(validation_result)
+
+        # Build complete FileAnalysis
+        Models::FileAnalysis.new.tap do |analysis|
+          analysis.file_path = @filepath || "unknown"
+          analysis.file_size = validation_result.file_size
+          analysis.file_type = validation_result.file_type
+          analysis.validation_result = validation_result
+          analysis.image_info = image_info
+          analysis.compression_info = extract_compression_info(validation_result)
+        end
+      end
+
+      private
+
+      # Build ValidationResult from validation context and chunks
+      #
+      # @return [ValidationResult] Validation results with chunks and errors
+      def build_validation_result
+        Models::ValidationResult.new.tap do |result|
+          # Set file metadata
+          result.filename = @filepath || "unknown"
+          result.file_type = determine_file_type
+          result.file_size = calculate_file_size
+
+          # Add all chunks with CRC validation
+          add_chunks_with_crc(result)
+
+          # Calculate compression ratio for PNG files (lazy calculation)
+          result.compression_ratio = if result.file_type == "PNG" &&
+              need_compression_ratio?
+                                       calculate_compression_ratio(result.chunks)
+                                     else
+                                       0.0
+                                     end
+
+          # Add all errors, warnings, and info from context
+          add_context_messages(result)
+        end
+      end
+
+      # Add chunks with CRC validation to result
+      #
+      # Caches IDAT data during initial pass for streaming compression calculation.
+      # Uses cached CRC validation from reader if available to avoid recalculation.
+      #
+      # @param result [ValidationResult] Result to add chunks to
+      # @return [void]
+      def add_chunks_with_crc(result)
+        crc_error_count = 0
+
+        @chunks.each do |bindata_chunk|
+          chunk = Models::Chunk.from_bindata(bindata_chunk,
+                                             bindata_chunk.abs_offset)
+
+          # Cache IDAT data for streaming compression calculation
+          if bindata_chunk.chunk_type.to_s == "IDAT"
+            @idat_data_cache ||= ""
+            @idat_data_cache += bindata_chunk.data.to_s
+          end
+
+          # Validate CRC using cached result if available
+          expected_crc = bindata_chunk.crc
+          chunk.crc_expected = format_hex(expected_crc)
+
+          # Check if reader already validated CRC (cached in @_crc_valid)
+          if bindata_chunk.instance_variable_defined?(:@_crc_valid)
+            # Use cached validation result
+            chunk.valid_crc = bindata_chunk.instance_variable_get(:@_crc_valid)
+            # Don't set crc_actual since we didn't recalculate it
+          else
+            # Calculate CRC if not cached
+            actual_crc = calculate_crc(bindata_chunk)
+            chunk.crc_actual = format_hex(actual_crc)
+            chunk.valid_crc = (expected_crc == actual_crc)
+          end
+
+          crc_error_count += 1 unless chunk.valid_crc
+
+          result.add_chunk(chunk)
+        end
+
+        result.crc_errors_count = crc_error_count
+      end
+
+      # Add all messages from validation context to result
+      #
+      # @param result [ValidationResult] Result to add messages to
+      # @return [void]
+      def add_context_messages(result)
+        # Add errors from context
+        @context.all_errors.each do |e|
+          result.error(e[:message])
+        end
+
+        # Add warnings from context
+        @context.all_warnings.each do |w|
+          result.warning(w[:message])
+        end
+
+        # Add info from context
+        @context.all_info.each do |i|
+          result.info(i[:message])
+        end
+      end
+
+      # Calculate file size from reader or chunks
+      #
+      # Performance optimization: Use reader.file_size if available,
+      # otherwise calculate from chunks (O(n) operation).
+      #
+      # @return [Integer] File size in bytes
+      def calculate_file_size
+        if @reader.respond_to?(:file_size)
+          @reader.file_size
+        else
+          # 8 bytes signature + sum of chunk sizes
+          # (8 byte header + data + 4 byte CRC per chunk)
+          8 + @chunks.sum { |c| 12 + c.length }
+        end
+      end
+
+      # Determine file type based on chunks
+      #
+      # @return [String] File type (PNG, MNG, JNG, or UNKNOWN)
+      def determine_file_type
+        return Models::ValidationResult::FILE_TYPE_MNG if @context.seen?("MHDR")
+        return Models::ValidationResult::FILE_TYPE_JNG if @context.seen?("JHDR")
+        return Models::ValidationResult::FILE_TYPE_PNG if @context.seen?("IHDR")
+
+        Models::ValidationResult::FILE_TYPE_UNKNOWN
+      end
+
+      # Calculate CRC32 for a chunk
+      #
+      # @param chunk [Object] BinData chunk
+      # @return [Integer] CRC32 value
+      def calculate_crc(chunk)
+        require "zlib"
+        # CRC is calculated over chunk type + chunk data
+        Zlib.crc32(chunk.chunk_type.to_s + chunk.data.to_s)
+      end
+
+      # Format integer as hex string
+      #
+      # @param value [Integer] Value to format
+      # @return [String] Hex string (e.g., "0x12345678")
+      def format_hex(value)
+        format("0x%08x", value)
+      end
+
+      # Calculate compression ratio for PNG
+      #
+      # Streaming optimization: Uses cached IDAT data from initial chunk read
+      # to avoid re-selecting and concatenating chunks.
+      #
+      # Lazy calculation - only performed when needed.
+      #
+      # @param chunks [Array<Chunk>] All chunks
+      # @return [Float] Compression ratio as percentage, 0.0 if cannot calculate
+      def calculate_compression_ratio(chunks)
+        # Use cached IDAT data from streaming read
+        idat_chunks = chunks.select { |c| c.type == "IDAT" }
+        return 0.0 if idat_chunks.empty?
+
+        compressed_size = idat_chunks.sum(&:length)
+        return 0.0 if compressed_size.zero?
+
+        # Try to decompress to get original size
+        begin
+          require "zlib"
+
+          # Use cached IDAT data from initial read (streaming optimization)
+          compressed_data = @idat_data_cache || ""
+
+          decompressed = Zlib::Inflate.inflate(compressed_data)
+          original_size = decompressed.bytesize
+
+          return 0.0 if original_size.zero?
+
+          # Calculate percentage: (compressed/original - 1) * 100
+          # Negative means compression, positive means expansion
+          ((compressed_size.to_f / original_size - 1) * 100).round(1)
+        rescue StandardError
+          # If decompression fails, we can't calculate ratio
+          0.0
+        end
+      end
+
+      # Extract ImageInfo from IHDR chunk
+      #
+      # @param result [ValidationResult] Validation result with chunks
+      # @return [ImageInfo, nil] Image info or nil if IHDR not found
+      def extract_image_info(result)
+        ihdr = result.ihdr_chunk
+        return nil unless ihdr&.data && ihdr.data.bytesize >= 13
+
+        width = ihdr.data.bytes[0..3].pack("C*").unpack1("N")
+        height = ihdr.data.bytes[4..7].pack("C*").unpack1("N")
+        bit_depth = ihdr.data.bytes[8]
+        color_type = ihdr.data.bytes[9]
+        interlace = ihdr.data.bytes[12]
+
+        Models::ImageInfo.new.tap do |info|
+          info.width = width
+          info.height = height
+          info.bit_depth = bit_depth
+          info.color_type = color_type_name(color_type)
+          info.interlaced = interlace == 1
+          info.animated = false # Could check for APNG chunks
+        end
+      end
+
+      # Extract CompressionInfo
+      #
+      # @param result [ValidationResult] Validation result
+      # @return [CompressionInfo, nil] Compression info or nil
+      def extract_compression_info(result)
+        return nil unless result.compression_ratio
+
+        Models::CompressionInfo.new.tap do |info|
+          info.compression_ratio = result.compression_ratio
+          info.compressed_size = result.chunks.select do |c|
+            c.type == "IDAT"
+          end.sum(&:length)
+        end
+      end
+
+      # Helper to convert color type code to name
+      #
+      # @param code [Integer] Color type code
+      # @return [String] Color type name
+      def color_type_name(code)
+        case code
+        when 0 then "grayscale"
+        when 2 then "truecolor"
+        when 3 then "palette"
+        when 4 then "grayscale+alpha"
+        when 6 then "truecolor+alpha"
+        else "unknown"
+        end
+      end
+
+      # Check if compression ratio calculation is needed
+      #
+      # @return [Boolean] True if compression ratio should be calculated
+      def need_compression_ratio?
+        return true if ["yaml", "json"].include?(@options[:format])
+
+        !@options[:quiet]
+      end
+    end
+  end
+end

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