png_conform 0.1.1 → 0.1.3

data/lib/png_conform/container.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative "readers/streaming_reader"
+require_relative "services/profile_manager"
+require_relative "services/analysis_manager"
+
+module PngConform
+  # Dependency Injection Container
+  #
+  # Centralized dependency management for the application.
+  # Provides factory methods for creating readers, validators, reporters,
+  # and other services with proper dependency injection.
+  #
+  # This makes testing easier by allowing mock injection and provides
+  # a single source of truth for object creation.
+  #
+  class Container
+    class << self
+      # Create a reader for the given type and filepath
+      #
+      # @param type [Symbol] Reader type (:streaming or :full_load)
+      # @param filepath [String] Path to PNG file
+      # @param options [Hash] Additional options for the reader
+      # @return [Object] Reader instance
+      def reader(type, filepath, options = {})
+        case type
+        when :streaming
+          io = File.open(filepath, "rb")
+          Readers::StreamingReader.new(io, options)
+        when :full_load
+          Readers::FullLoadReader.new(filepath, options)
+        else
+          raise ArgumentError, "Unknown reader type: #{type}"
+        end
+      end
+
+      # Open a reader with automatic file closing
+      #
+      # @param type [Symbol] Reader type (:streaming or :full_load)
+      # @param filepath [String] Path to PNG file
+      # @param options [Hash] Additional options for the reader
+      # @yield [reader] Reader instance
+      # @return [Object] Result of the block
+      def open_reader(type, filepath, _options = {}, &block)
+        case type
+        when :streaming
+          Readers::StreamingReader.open(filepath, &block)
+        when :full_load
+          Readers::FullLoadReader.open(filepath, &block)
+        else
+          raise ArgumentError, "Unknown reader type: #{type}"
+        end
+      end
+
+      # Create a validator for a chunk
+      #
+      # Delegates to ChunkRegistry for validator creation
+      #
+      # @param chunk [Object] Chunk object
+      # @param context [ValidationContext] Validation context
+      # @return [Object] Validator instance or nil
+      def validator(chunk, context)
+        require_relative "validators/chunk_registry"
+        Validators::ChunkRegistry.create_validator(chunk, context)
+      end
+
+      # Create a reporter based on options
+      #
+      # Delegates to ReporterFactory for reporter creation
+      #
+      # @param options [Hash] Reporter options
+      # @return [Object] Reporter instance
+      def reporter(options)
+        require_relative "reporters/reporter_factory"
+        Reporters::ReporterFactory.create(**options)
+      end
+
+      # Get the profile manager singleton
+      #
+      # @return [ProfileManager] Profile manager instance
+      def profile_manager
+        @profile_manager ||= Services::ProfileManager.new
+      end
+
+      # Create an analysis manager
+      #
+      # @param options [Hash] Analysis options
+      # @return [AnalysisManager] Analysis manager instance
+      def analysis_manager(options = {})
+        Services::AnalysisManager.new(options)
+      end
+
+      # Create a validation orchestrator
+      #
+      # @param reader [Object] File reader
+      # @param filepath [String] File path
+      # @param options [Hash] Validation options
+      # @return [ValidationOrchestrator] Orchestrator instance
+      def validation_orchestrator(reader, filepath = nil, options = {})
+        require_relative "services/validation_orchestrator"
+        Services::ValidationOrchestrator.new(reader, filepath, options)
+      end
+      alias_method :validation_service, :validation_orchestrator
+
+      # Reset container state
+      #
+      # Clears cached instances (useful for testing)
+      def reset!
+        @profile_manager = nil
+      end
+    end
+  end
+end

data/lib/png_conform/models/decoded_chunk_data.rb

@@ -139,5 +139,38 @@ module PngConform
                year, month, day, hour, minute, second)
       end
     end
+
+    # iDOT chunk decoded data
+    class IdotData < DecodedChunkData
+      attribute :display_scale, :integer
+      attribute :pixel_format, :integer
+      attribute :color_space, :integer
+      attribute :backing_scale_factor, :integer
+      attribute :flags, :integer
+      attribute :reserved1, :integer
+      attribute :reserved2, :integer
+
+      def summary
+        parts = []
+        parts << "display scale: #{display_scale}" if display_scale
+        parts << "pixel format: #{pixel_format}" if pixel_format
+        parts << "color space: #{color_space}" if color_space
+        parts << "backing scale: #{backing_scale_factor}" if backing_scale_factor
+        parts.join(", ")
+      end
+
+      # Format all seven values for detailed display
+      def detailed_info
+        [
+          display_scale,
+          pixel_format,
+          color_space,
+          backing_scale_factor,
+          flags,
+          reserved1,
+          reserved2,
+        ].join(", ")
+      end
+    end
   end
 end

data/lib/png_conform/models/validation_result.rb

@@ -13,15 +13,26 @@ module PngConform
       attribute :compression_ratio, :float
       attribute :crc_errors_count, :integer, default: -> { 0 }
 
+      # Non-serialized hash map for fast chunk type lookup
+      attr_reader :chunks_by_type_map
+
       # File types
       FILE_TYPE_PNG = "PNG"
       FILE_TYPE_MNG = "MNG"
       FILE_TYPE_JNG = "JNG"
       FILE_TYPE_UNKNOWN = "UNKNOWN"
 
+      # Initialize with hash map for fast lookups
+      def initialize(*args)
+        super(*args)
+        @chunks_by_type_map = {}
+        rebuild_chunks_map
+      end
+
       # Add a chunk to the result
       def add_chunk(chunk)
         chunks << chunk
+        add_to_chunks_map(chunk)
       end
 
       # Add an error to the result
@@ -90,14 +101,14 @@ module PngConform
         chunks.count
       end
 
-      # Find chunks by type
+      # Find chunks by type (O(1) hash lookup)
       def chunks_by_type(type)
-        chunks.select { |chunk| chunk.type == type }
+        @chunks_by_type_map[type] || []
       end
 
-      # Check if file has specific chunk type
+      # Check if file has specific chunk type (O(1) hash lookup)
       def has_chunk?(type)
-        chunks.any? { |chunk| chunk.type == type }
+        @chunks_by_type_map.key?(type) && !@chunks_by_type_map[type].empty?
       end
 
       # Get IHDR chunk (PNG/JNG)
@@ -132,6 +143,21 @@ module PngConform
         end
         parts.join("\n")
       end
+
+      private
+
+      # Add chunk to hash map for fast lookup
+      def add_to_chunks_map(chunk)
+        chunk_type = chunk.type
+        @chunks_by_type_map[chunk_type] ||= []
+        @chunks_by_type_map[chunk_type] << chunk
+      end
+
+      # Rebuild hash map from chunks (for deserialization or external modification)
+      def rebuild_chunks_map
+        @chunks_by_type_map.clear
+        chunks.each { |chunk| add_to_chunks_map(chunk) }
+      end
     end
   end
 end

data/lib/png_conform/pipelines/pipeline_result.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module PngConform
+  module Pipelines
+    # Result object for pipeline stages
+    #
+    # Carries state through the validation pipeline.
+    #
+    class PipelineResult
+      attr_accessor :ready_for_analysis
+      attr_reader :context, :chunks
+
+      # Initialize pipeline result
+      #
+      # @param context [ValidationContext] Validation context
+      # @param chunks [Array] Array of chunks
+      def initialize(context:, chunks: [])
+        @context = context
+        @chunks = chunks
+        @ready_for_analysis = false
+      end
+
+      # Check if validation has errors
+      #
+      # @return [Boolean] true if there are errors
+      def has_errors?
+        @context.has_errors?
+      end
+
+      # Check if validation should terminate early
+      #
+      # @param fail_fast [Boolean] Whether fail_fast is enabled
+      # @return [Boolean] true if should terminate
+      def should_terminate?(fail_fast: false)
+        fail_fast && has_errors?
+      end
+    end
+  end
+end

data/lib/png_conform/pipelines/stages/analysis_stage.rb

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "base_stage"
+
+module PngConform
+  module Pipelines
+    module Stages
+      # Analysis enrichment stage
+      #
+      # Runs conditional analyzers based on options.
+      #
+      class AnalysisStage < BaseStage
+        # Initialize analysis stage
+        #
+        # @param context [ValidationContext] Validation context
+        # @param options [Hash] Validation options
+        def initialize(context, options)
+          @context = context
+          @options = options
+        end
+
+        # Execute analysis enrichment
+        #
+        # @param result [PipelineResult] Current pipeline result
+        # @return [PipelineResult] Updated pipeline result
+        def execute(result)
+          # Analysis is performed later during FileAnalysis building
+          # This stage just marks the pipeline as ready for analysis
+          result.ready_for_analysis = true
+          result
+        end
+      end
+    end
+  end
+end

data/lib/png_conform/pipelines/stages/base_stage.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module PngConform
+  module Pipelines
+    module Stages
+      # Base class for validation pipeline stages
+      #
+      # All pipeline stages inherit from this class and implement
+      # the execute method. This provides a consistent interface
+      # for pipeline execution.
+      #
+      class BaseStage
+        # Execute the stage
+        #
+        # @param result [PipelineResult] Current pipeline result
+        # @return [PipelineResult] Updated pipeline result
+        def execute(result)
+          raise NotImplementedError, "Subclasses must implement #execute"
+        end
+      end
+    end
+  end
+end

data/lib/png_conform/pipelines/stages/chunk_validation_stage.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "base_stage"
+require_relative "../../services/chunk_processor"
+require_relative "../../models/pipeline_result"
+
+module PngConform
+  module Pipelines
+    module Stages
+      # Chunk validation stage
+      #
+      # Processes all chunks through validation using ChunkProcessor.
+      # Caches CRC calculations during initial read to avoid recomputation.
+      #
+      class ChunkValidationStage < BaseStage
+        # Initialize chunk validation stage
+        #
+        # @param reader [Object] File reader
+        # @param context [ValidationContext] Validation context
+        # @param options [Hash] Validation options
+        def initialize(reader, context, options = {})
+          @reader = reader
+          @context = context
+          @options = options
+          @crc_cache = {} # Cache for CRC calculations
+        end
+
+        # Execute chunk validation
+        #
+        # @param result [PipelineResult] Current pipeline result
+        # @return [PipelineResult] Updated pipeline result
+        def execute(result)
+          processor = Services::ChunkProcessor.new(@reader, @context, @options)
+          processor.process do |chunk|
+            # Cache CRC during initial read to avoid recalculation
+            cache_crc(chunk)
+            result.chunks << chunk
+          end
+
+          result
+        end
+
+        private
+
+        # Cache CRC calculation for a chunk
+        #
+        # Performance optimization: calculates CRC once during initial read
+        # and stores it for later use in result building.
+        #
+        # @param chunk [Object] Chunk to cache CRC for
+        # @return [void]
+        def cache_crc(chunk)
+          return unless chunk.respond_to?(:chunk_type) && chunk.respond_to?(:data)
+
+          key = "#{chunk.chunk_type}_#{chunk.data.hash}"
+          @crc_cache[key] ||= calculate_crc(chunk)
+
+          # Store cached CRC on chunk for later access
+          chunk.instance_variable_set(:@cached_crc, @crc_cache[key])
+        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
+      end
+    end
+  end
+end

data/lib/png_conform/pipelines/stages/sequence_validation_stage.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+require_relative "base_stage"
+
+module PngConform
+  module Pipelines
+    module Stages
+      # Chunk sequence validation stage
+      #
+      # Validates high-level chunk sequence requirements:
+      # - IHDR must be first chunk
+      # - IEND must be last chunk
+      # - At least one IDAT chunk required
+      #
+      class SequenceValidationStage < BaseStage
+        # Initialize sequence validation stage
+        #
+        # @param context [ValidationContext] Validation context
+        def initialize(context)
+          @context = context
+        end
+
+        # Execute sequence validation
+        #
+        # @param result [PipelineResult] Current pipeline result
+        # @return [PipelineResult] Updated pipeline result
+        def execute(result)
+          validate_ihdr_first
+          validate_iend_last
+          validate_idat_present
+          result
+        end
+
+        private
+
+        # 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
+      end
+    end
+  end
+end

data/lib/png_conform/pipelines/stages/signature_validation_stage.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative "base_stage"
+
+module PngConform
+  module Pipelines
+    module Stages
+      # Signature validation stage
+      #
+      # Validates that the PNG file starts with the correct signature.
+      #
+      class SignatureValidationStage < BaseStage
+        # Initialize signature validation stage
+        #
+        # @param reader [Object] File reader
+        def initialize(reader)
+          @reader = reader
+        end
+
+        # Execute signature validation
+        #
+        # @param result [PipelineResult] Current pipeline result
+        # @return [PipelineResult] Updated pipeline result
+        def execute(result)
+          sig = @reader.signature
+          expected = [137, 80, 78, 71, 13, 10, 26, 10].pack("C*")
+
+          if sig != expected
+            result.context.add_error(
+              chunk_type: "SIGNATURE",
+              message: "Invalid PNG signature",
+              severity: :error,
+            )
+          end
+
+          result
+        end
+      end
+    end
+  end
+end

data/lib/png_conform/pipelines/validation_pipeline.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "pipeline_result"
+require_relative "stages/base_stage"
+require_relative "stages/signature_validation_stage"
+require_relative "stages/chunk_validation_stage"
+require_relative "stages/sequence_validation_stage"
+require_relative "stages/analysis_stage"
+require_relative "../services/result_builder"
+require_relative "../services/analysis_manager"
+
+module PngConform
+  module Pipelines
+    # Validation pipeline for PNG files
+    #
+    # Executes validation in a series of stages:
+    # 1. Signature validation
+    # 2. Chunk validation
+    # 3. Sequence validation
+    # 4. Analysis preparation
+    #
+    class ValidationPipeline
+      # Initialize validation pipeline
+      #
+      # @param reader [Object] File reader
+      # @param options [Hash] Validation options
+      def initialize(reader, options = {})
+        @reader = reader
+        @options = options
+        @context = Validators::ValidationContext.new
+        @chunks = []
+        build_stages
+      end
+
+      # Execute the validation pipeline
+      #
+      # Runs all stages in order. Stops early if fail_fast is enabled
+      # and critical errors are encountered.
+      #
+      # @return [FileAnalysis] Complete file analysis
+      def execute
+        result = PipelineResult.new(context: @context, chunks: @chunks)
+
+        @stages.each do |stage|
+          result = stage.execute(result)
+
+          # Early termination for critical errors
+          break if result.should_terminate?(fail_fast: @options[:fail_fast])
+        end
+
+        build_file_analysis(result)
+      end
+
+      private
+
+      # Build the pipeline stages
+      #
+      # @return [void]
+      def build_stages
+        @stages = [
+          Stages::SignatureValidationStage.new(@reader),
+          Stages::ChunkValidationStage.new(@reader, @context, @options),
+          Stages::SequenceValidationStage.new(@context),
+          Stages::AnalysisStage.new(@context, @options),
+        ]
+      end
+
+      # Build complete FileAnalysis from pipeline result
+      #
+      # @param result [PipelineResult] Pipeline result
+      # @return [FileAnalysis] Complete file analysis
+      def build_file_analysis(_result)
+        result_builder = Services::ResultBuilder.new(
+          @reader,
+          @options[:filepath],
+          @context,
+          @chunks,
+          @options,
+        )
+        file_analysis = result_builder.build
+
+        # Run analyzers through AnalysisManager
+        analysis_manager = Services::AnalysisManager.new(@options)
+        analysis_manager.enrich(file_analysis)
+
+        file_analysis
+      end
+    end
+  end
+end

data/lib/png_conform/readers/full_load_reader.rb

@@ -21,12 +21,14 @@ module PngConform
     #   end
     #
     class FullLoadReader
-      attr_reader :io, :png
+      attr_reader :io, :png, :total_bytes_read
 
       # Initialize a new full-load reader
       #
       # @param filepath_or_io [String, IO] File path or IO object to read from
-      def initialize(filepath_or_io)
+      # @param options [Hash] Options for reading behavior
+      # @option options [Boolean] :validate_crc (true) Calculate CRC during reading
+      def initialize(filepath_or_io, options = {})
         if filepath_or_io.is_a?(String)
           # File path provided
           @filepath = filepath_or_io
@@ -38,6 +40,8 @@ module PngConform
           @owns_io = false
         end
         @png = nil
+        @total_bytes_read = 0
+        @validate_crc = options.fetch(:validate_crc, true)
       end
 
       # Read the entire PNG file structure
@@ -48,6 +52,11 @@ module PngConform
 
         @io.rewind
         @png = BinData::PngFile.read(@io)
+
+        # Calculate total bytes from chunks
+        @total_bytes_read = @png.chunks.sum { |c| 12 + c.data_length }
+
+        @png
       end
 
       # Get PNG signature
@@ -75,9 +84,9 @@ module PngConform
         elsif @io.respond_to?(:stat)
           @io.stat.size
         else
-          # Fallback: calculate from PNG structure
+          # Use cached total bytes from chunks
           read unless @png
-          8 + @png.chunks.sum { |c| 12 + c.length }
+          8 + @total_bytes_read
         end
       end