png_conform 0.1.2 → 0.1.3

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
 

data/lib/png_conform/readers/streaming_reader.rb

@@ -27,15 +27,19 @@ module PngConform
         .pack("C*")
         .freeze
 
-      attr_reader :io, :signature
+      attr_reader :io, :signature, :total_bytes_read
 
       # Initialize a new streaming reader
       #
       # @param io [IO] IO object to read from (must be opened in binary mode)
-      def initialize(io)
+      # @param options [Hash] Options for reading behavior
+      # @option options [Boolean] :validate_crc (true) Calculate CRC during reading
+      def initialize(io, options = {})
         @io = io
         @signature = nil
         @chunks_read = 0
+        @total_bytes_read = 0
+        @validate_crc = options.fetch(:validate_crc, true)
       end
 
       # Read and validate the PNG signature
@@ -71,6 +75,15 @@ module PngConform
         return nil if @io.eof?
 
         chunk = BinData::ChunkStructure.read(@io)
+
+        # Track total bytes read (8 byte header + data + 4 byte CRC)
+        @total_bytes_read += (12 + chunk.data_length)
+
+        # Validate CRC during reading if enabled and cache result
+        if @validate_crc
+          chunk.instance_variable_set(:@_crc_valid, chunk.crc_valid?)
+        end
+
         @chunks_read += 1
         chunk
       rescue EOFError
@@ -135,6 +148,18 @@ module PngConform
         @io.rewind
         @signature = nil
         @chunks_read = 0
+        @total_bytes_read = 0
+      end
+
+      # Get file size from total bytes tracked during reading
+      #
+      # Returns the total file size including signature and all chunks.
+      # This is cached during reading to avoid O(n) recalculation.
+      #
+      # @return [Integer] File size in bytes (0 if no chunks read yet)
+      def file_size
+        # 8 bytes signature + total chunk bytes
+        8 + @total_bytes_read
       end
 
       # Get the current position in the file

data/lib/png_conform/reporters/color_reporter.rb

@@ -1,23 +1,13 @@
 # frozen_string_literal: true
 
 require_relative "base_reporter"
+require_relative "../utils/colorizer"
 
 module PngConform
   module Reporters
     # Color reporter - wraps another reporter to add ANSI color support (-c flag)
     # Decorator pattern to add color to any reporter
     class ColorReporter < BaseReporter
-      # ANSI color codes
-      COLORS = {
-        red: "\e[31m",
-        green: "\e[32m",
-        yellow: "\e[33m",
-        blue: "\e[34m",
-        magenta: "\e[35m",
-        cyan: "\e[36m",
-        reset: "\e[0m",
-      }.freeze
-
       attr_reader :wrapped_reporter
 
       # @param wrapped_reporter [BaseReporter] The reporter to wrap with colors
@@ -41,12 +31,25 @@ module PngConform
 
       protected
 
-      # Override colorize to actually apply colors
+      # Override colorize to use Colorizer class
       def colorize(text, color)
         return text unless @colorize_enabled
-        return text unless COLORS.key?(color)
 
-        "#{COLORS[color]}#{text}#{COLORS[:reset]}"
+        case color
+        when :red
+          Utils::Colorizer.error(text, bold: false)
+        when :green
+          Utils::Colorizer.success(text, bold: false)
+        when :yellow
+          Utils::Colorizer.warning(text, bold: false)
+        when :blue
+          Utils::Colorizer.info(text, bold: false)
+        when :cyan, :magenta
+          # Use cyan as a neutral color for other cases
+          Utils::Colorizer.colorize(text, :cyan, bold: false)
+        else
+          text
+        end
       end
 
       # Determine color based on validation status

data/lib/png_conform/reporters/visual_elements.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "../utils/colorizer"
+
 module PngConform
   module Reporters
     # Module providing visual elements (emojis and colors) for CLI output
@@ -20,27 +22,31 @@ module PngConform
         image: "🖼️",
       }.freeze
 
-      # ANSI color codes for terminal output
-      COLORS = {
-        green: "\e[32m",
-        red: "\e[31m",
-        yellow: "\e[33m",
-        blue: "\e[34m",
-        cyan: "\e[36m",
-        gray: "\e[90m",
-        reset: "\e[0m",
-        bold: "\e[1m",
-      }.freeze
-
-      # Colorize text with ANSI color codes
+      # Colorize text with Colorizer class
       # @param text [String] The text to colorize
-      # @param color [Symbol] The color name from COLORS
+      # @param color [Symbol] The color name
       # @return [String] Colorized text or original if colorization disabled
       def colorize(text, color)
         return text unless @colorize
-        return text unless COLORS.key?(color)
 
-        "#{COLORS[color]}#{text}#{COLORS[:reset]}"
+        case color
+        when :green
+          Utils::Colorizer.success(text, bold: false)
+        when :red
+          Utils::Colorizer.error(text, bold: false)
+        when :yellow
+          Utils::Colorizer.warning(text, bold: false)
+        when :blue
+          Utils::Colorizer.info(text, bold: false)
+        when :cyan
+          Utils::Colorizer.colorize(text, :cyan, bold: false)
+        when :gray
+          Utils::Colorizer.colorize(text, :gray, bold: false)
+        when :bold
+          Utils::Colorizer.bold(text)
+        else
+          text
+        end
       end
 
       # Get emoji for a given name

data/lib/png_conform/services/analysis_manager.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require_relative "../configuration"
+
+module PngConform
+  module Services
+    # Manages conditional analysis execution
+    #
+    # The AnalysisManager handles:
+    # - Running resolution analysis (conditional)
+    # - Running optimization analysis (conditional)
+    # - Running metrics analysis (conditional)
+    #
+    # Analyzers are only run when needed based on options to improve performance.
+    # This class extracts analysis logic from ValidationService following
+    # Single Responsibility Principle.
+    #
+    class AnalysisManager
+      # Initialize analysis manager
+      #
+      # @param options [Hash] CLI options for controlling behavior
+      # @param config [Configuration] Configuration instance (optional)
+      def initialize(options = {}, config: Configuration.instance)
+        @options = options
+        @config = config
+      end
+
+      # Enrich FileAnalysis with conditional analyzer results
+      #
+      # Runs analyzers only when needed based on options:
+      # - Resolution analysis: unless quiet mode, or if --resolution or --mobile-ready
+      # - Optimization analysis: unless quiet mode, or if --optimize
+      # - Metrics analysis: if yaml/json format, or if --metrics
+      #
+      # @param file_analysis [FileAnalysis] File analysis to enrich
+      # @return [FileAnalysis] Enriched file analysis
+      def enrich(file_analysis)
+        validation_result = file_analysis.validation_result
+
+        if need_resolution_analysis?
+          file_analysis.resolution_analysis =
+            run_resolution_analysis(validation_result)
+        end
+
+        if need_optimization_analysis?
+          file_analysis.optimization_analysis =
+            run_optimization_analysis(validation_result)
+        end
+
+        if need_metrics_analysis?
+          file_analysis.metrics = run_metrics_analysis(validation_result)
+        end
+
+        file_analysis
+      end
+
+      private
+
+      # Run resolution analyzer
+      #
+      # @param result [ValidationResult] Validation result
+      # @return [Hash] Resolution analysis results
+      def run_resolution_analysis(result)
+        require_relative "../analyzers/resolution_analyzer" unless defined?(Analyzers::ResolutionAnalyzer)
+        Analyzers::ResolutionAnalyzer.new(result, config: @config).analyze
+      rescue StandardError => e
+        { error: "Resolution analysis failed: #{e.message}" }
+      end
+
+      # Run optimization analyzer
+      #
+      # @param result [ValidationResult] Validation result
+      # @return [Hash] Optimization analysis results
+      def run_optimization_analysis(result)
+        require_relative "../analyzers/optimization_analyzer" unless defined?(Analyzers::OptimizationAnalyzer)
+        Analyzers::OptimizationAnalyzer.new(result, config: @config).analyze
+      rescue StandardError => e
+        { error: "Optimization analysis failed: #{e.message}" }
+      end
+
+      # Run metrics analyzer
+      #
+      # @param result [ValidationResult] Validation result
+      # @return [Hash] Metrics analysis results
+      def run_metrics_analysis(result)
+        require_relative "../analyzers/metrics_analyzer" unless defined?(Analyzers::MetricsAnalyzer)
+        Analyzers::MetricsAnalyzer.new(result, config: @config).analyze
+      rescue StandardError => e
+        { error: "Metrics analysis failed: #{e.message}" }
+      end
+
+      # Check if resolution analysis is needed
+      #
+      # @return [Boolean] True if resolution analysis should be run
+      def need_resolution_analysis?
+        return true unless @options[:quiet]
+
+        @options[:resolution] || @options[:mobile_ready]
+      end
+
+      # Check if optimization analysis is needed
+      #
+      # @return [Boolean] True if optimization analysis should be run
+      def need_optimization_analysis?
+        return true unless @options[:quiet]
+
+        @options[:optimize]
+      end
+
+      # Check if metrics analysis is needed
+      #
+      # @return [Boolean] True if metrics analysis should be run
+      def need_metrics_analysis?
+        return true if ["yaml", "json"].include?(@options[:format])
+
+        @options[:metrics]
+      end
+    end
+  end
+end