png_conform 0.1.1 → 0.1.2

data/examples/README.md

@@ -0,0 +1,282 @@
+# PngConform Examples
+
+This directory contains example scripts demonstrating how to use PngConform in various scenarios.
+
+## Quick Start
+
+All examples are executable Ruby scripts. Make sure you have PngConform installed:
+
+```bash
+gem install png_conform
+# or
+bundle install
+```
+
+## Available Examples
+
+### Basic Usage ([`basic_usage.rb`](basic_usage.rb))
+
+Demonstrates fundamental PngConform operations:
+
+- Basic file validation
+- Profile-based validation
+- Detailed chunk inspection
+- Batch validation of multiple files
+- Exporting results to YAML/JSON
+
+**Run it:**
+```bash
+ruby examples/basic_usage.rb path/to/image.png
+ruby examples/basic_usage.rb path/to/image.png path/to/png_directory
+```
+
+**What you'll learn:**
+- How to validate a single PNG file
+- How to use different validation profiles
+- How to inspect chunk data
+- How to process multiple files efficiently
+- How to export validation results
+
+### Advanced Usage ([`advanced_usage.rb`](advanced_usage.rb))
+
+Demonstrates advanced integration patterns:
+
+- Creating custom reporters
+- Working with validators directly
+- Comparing streaming vs full-load modes
+- Profile comparison across all profiles
+- Error handling best practices
+- Extracting metadata from chunks
+- Performance monitoring
+
+**Run it:**
+```bash
+ruby examples/advanced_usage.rb path/to/image.png
+ruby examples/advanced_usage.rb file1.png file2.png file3.png
+```
+
+**What you'll learn:**
+- How to create custom output formats
+- How to handle errors properly
+- How to optimize for large files
+- How to extract chunk metadata
+- How to monitor performance
+
+## Common Use Cases
+
+### Validate a Single File
+
+```ruby
+require "png_conform"
+
+service = PngConform::Services::ValidationService.new
+result = service.validate_file("image.png")
+
+puts result.valid? ? "Valid PNG" : "Invalid PNG"
+```
+
+### Batch Validation
+
+```ruby
+Dir.glob("images/*.png").each do |file|
+  result = service.validate_file(file)
+  puts "#{file}: #{result.valid? ? '✓' : '✗'}"
+end
+```
+
+### Profile Validation
+
+```ruby
+profile_manager = PngConform::Services::ProfileManager.new
+profile = profile_manager.load_profile("web")
+
+result = service.validate_file("image.png", profile: profile)
+```
+
+### Extract Metadata
+
+```ruby
+result = service.validate_file("image.png")
+
+# Get image dimensions
+puts "#{result.image_info.width}x#{result.image_info.height}"
+
+# Get chunk information
+result.chunks.each do |chunk|
+  puts "#{chunk.type}: #{chunk.length} bytes"
+end
+```
+
+### Handle Errors
+
+```ruby
+begin
+  result = service.validate_file("image.png")
+rescue PngConform::ParseError => e
+  puts "File is corrupted: #{e.message}"
+rescue PngConform::Error => e
+  puts "Validation error: #{e.message}"
+end
+```
+
+## Testing the Examples
+
+You can test the examples with files from the PngSuite test fixture:
+
+```bash
+# Using a test fixture
+ruby examples/basic_usage.rb spec/fixtures/pngsuite/background/bgwn6a08.png
+
+# Using multiple test files
+ruby examples/advanced_usage.rb spec/fixtures/pngsuite/background/*.png
+```
+
+## Integration Patterns
+
+### Web Application
+
+```ruby
+# In a Rails/Sinatra controller
+def validate_upload
+  uploaded_file = params[:file]
+
+  # Save to temporary location
+  temp_path = "/tmp/#{SecureRandom.hex}.png"
+  File.write(temp_path, uploaded_file.read)
+
+  # Validate
+  service = PngConform::Services::ValidationService.new
+  result = service.validate_file(temp_path)
+
+  # Clean up
+  File.delete(temp_path)
+
+  # Return result
+  render json: {
+    valid: result.valid?,
+    errors: result.errors.map(&:message)
+  }
+end
+```
+
+### Background Job
+
+```ruby
+# In a Sidekiq/ActiveJob worker
+class PngValidationJob < ApplicationJob
+  def perform(file_path)
+    service = PngConform::Services::ValidationService.new
+    result = service.validate_file(file_path, streaming: true)
+
+    if result.valid?
+      # Process valid file
+      ProcessImageJob.perform_later(file_path)
+    else
+      # Handle invalid file
+      NotifyUserJob.perform_later(user_id, result.errors)
+    end
+  end
+end
+```
+
+### Command Line Tool
+
+```ruby
+#!/usr/bin/env ruby
+# Custom validation script
+
+require "png_conform"
+
+ARGV.each do |file|
+  service = PngConform::Services::ValidationService.new
+  result = service.validate_file(file)
+
+  status = result.valid? ? "PASS" : "FAIL"
+  puts "#{status}: #{file}"
+
+  unless result.valid?
+    result.errors.each do |error|
+      puts "  #{error.severity}: #{error.message}"
+    end
+  end
+end
+```
+
+## Performance Tips
+
+### Large Files
+
+For files larger than 50MB, use streaming mode:
+
+```ruby
+result = service.validate_file("large.png", streaming: true)
+```
+
+### Batch Processing
+
+Process files in parallel using threads:
+
+```ruby
+require "concurrent"
+
+files = Dir.glob("images/*.png")
+pool = Concurrent::FixedThreadPool.new(4)
+
+files.each do |file|
+  pool.post do
+    result = service.validate_file(file)
+    # Process result...
+  end
+end
+
+pool.shutdown
+pool.wait_for_termination
+```
+
+### Memory Management
+
+For production systems, set resource limits:
+
+```ruby
+MAX_FILE_SIZE = 100 * 1024 * 1024  # 100 MB
+MAX_PROCESSING_TIME = 30  # seconds
+
+if File.size(file_path) > MAX_FILE_SIZE
+  raise "File too large"
+end
+
+Timeout.timeout(MAX_PROCESSING_TIME) do
+  result = service.validate_file(file_path)
+end
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**"File not found" error:**
+- Check file path is correct
+- Use absolute paths if relative paths don't work
+- Ensure file has read permissions
+
+**Memory issues with large files:**
+- Use streaming mode: `streaming: true`
+- Process files one at a time
+- Set memory limits in your environment
+
+**Slow validation:**
+- Use streaming mode for large files
+- Consider caching results
+- Run validation in background jobs
+
+## Additional Resources
+
+- [API Documentation](../README.adoc)
+- [Architecture Guide](../ARCHITECTURE.md)
+- [Contributing Guide](../CONTRIBUTING.md)
+- [Security Policy](../SECURITY.md)
+
+## Questions?
+
+- Open an issue: https://github.com/claricle/png_conform/issues
+- Read the documentation: https://github.com/claricle/png_conform

data/lib/png_conform/commands/check_command.rb

@@ -88,8 +88,9 @@ module PngConform
 
         # Read and validate the file using streaming reader
         Readers::StreamingReader.open(file_path) do |reader|
-          # Perform validation
-          validator = Services::ValidationService.new(reader, file_path)
+          # Perform validation - pass options for conditional analyzers (Phase 1.1 + 1.2)
+          validator = Services::ValidationService.new(reader, file_path,
+                                                      options)
           file_analysis = validator.validate
 
           # Track if any errors were found

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/reporters/reporter_factory.rb

@@ -1,21 +1,12 @@
 # frozen_string_literal: true
 
-require_relative "summary_reporter"
-require_relative "verbose_reporter"
-require_relative "very_verbose_reporter"
-require_relative "quiet_reporter"
-require_relative "palette_reporter"
-require_relative "text_reporter"
-require_relative "color_reporter"
-require_relative "yaml_reporter"
-require_relative "json_reporter"
-
 module PngConform
   module Reporters
     # Factory for creating reporter instances based on options.
     #
     # Implements the Factory pattern to provide a clean interface for
     # creating reporters with various combinations of options.
+    # Uses lazy loading to only require reporters when actually needed.
     class ReporterFactory
       # Create a reporter based on the specified options.
       #
@@ -34,30 +25,43 @@ module PngConform
         # Format takes priority over verbosity
         case format
         when "yaml"
+          require_relative "yaml_reporter" unless defined?(YamlReporter)
           return YamlReporter.new
         when "json"
+          require_relative "json_reporter" unless defined?(JsonReporter)
           return JsonReporter.new
         end
 
-        # Text reporters with verbosity levels
+        # Text reporters with verbosity levels - lazy load base and visual elements
+        require_relative "visual_elements" unless defined?(VisualElements)
+        require_relative "base_reporter" unless defined?(BaseReporter)
+
         reporter = if verbosity
                      case verbosity
                      when :quiet
+                       require_relative "quiet_reporter" unless defined?(QuietReporter)
                        QuietReporter.new($stdout, colorize: colorize)
                      when :verbose
+                       require_relative "verbose_reporter" unless defined?(VerboseReporter)
                        VerboseReporter.new($stdout, colorize: colorize)
                      when :very_verbose
+                       require_relative "very_verbose_reporter" unless defined?(VeryVerboseReporter)
                        VeryVerboseReporter.new($stdout, colorize: colorize)
                      when :summary
+                       require_relative "summary_reporter" unless defined?(SummaryReporter)
                        SummaryReporter.new($stdout, colorize: colorize)
                      else
+                       require_relative "summary_reporter" unless defined?(SummaryReporter)
                        SummaryReporter.new($stdout, colorize: colorize)
                      end
                    elsif quiet
+                     require_relative "quiet_reporter" unless defined?(QuietReporter)
                      QuietReporter.new($stdout, colorize: colorize)
                    elsif verbose
+                     require_relative "verbose_reporter" unless defined?(VerboseReporter)
                      VerboseReporter.new($stdout, colorize: colorize)
                    else
+                     require_relative "summary_reporter" unless defined?(SummaryReporter)
                      SummaryReporter.new($stdout, colorize: colorize)
                    end
 
@@ -76,6 +80,7 @@ module PngConform
       # @param reporter [BaseReporter] Reporter to wrap
       # @return [PaletteReporter] Wrapped reporter
       def self.wrap_with_palette(reporter)
+        require_relative "palette_reporter" unless defined?(PaletteReporter)
         PaletteReporter.new(reporter)
       end
 
@@ -86,6 +91,7 @@ module PngConform
       # @param escape_mode [Symbol] Explicit escape mode setting
       # @return [TextReporter] Wrapped reporter
       def self.wrap_with_text(reporter, seven_bit, escape_mode)
+        require_relative "text_reporter" unless defined?(TextReporter)
         mode = if escape_mode == :none
                  (seven_bit ? :seven_bit : :none)
                else
@@ -99,6 +105,7 @@ module PngConform
       # @param reporter [BaseReporter] Reporter to wrap
       # @return [ColorReporter] Wrapped reporter
       def self.wrap_with_color(reporter)
+        require_relative "color_reporter" unless defined?(ColorReporter)
         ColorReporter.new(reporter)
       end
 

data/lib/png_conform/services/validation_service.rb

@@ -5,9 +5,10 @@ require_relative "../models/validation_result"
 require_relative "../models/file_analysis"
 require_relative "../models/image_info"
 require_relative "../models/compression_info"
-require_relative "../analyzers/resolution_analyzer"
-require_relative "../analyzers/optimization_analyzer"
-require_relative "../analyzers/metrics_analyzer"
+# Lazy load analyzers - only require when needed (Phase 2: Lazy Loading)
+# require_relative "../analyzers/resolution_analyzer"
+# require_relative "../analyzers/optimization_analyzer"
+# require_relative "../analyzers/metrics_analyzer"
 
 module PngConform
   module Services
@@ -28,11 +29,12 @@ module PngConform
       # Convenience method to validate a file by path
       #
       # @param filepath [String] Path to PNG file
+      # @param options [Hash] Optional CLI options
       # @return [ValidationResult] Validation results
-      def self.validate_file(filepath)
+      def self.validate_file(filepath, options = {})
         require_relative "../readers/full_load_reader"
         reader = Readers::FullLoadReader.new(filepath)
-        service = new(reader, filepath)
+        service = new(reader, filepath, options)
         service.validate
       end
 
@@ -40,9 +42,11 @@ module PngConform
       #
       # @param reader [Object] File reader (StreamingReader or FullLoadReader)
       # @param filepath [String, nil] Optional file path (for reporting)
-      def initialize(reader, filepath = nil)
+      # @param options [Hash] CLI options for controlling behavior
+      def initialize(reader, filepath = nil, options = {})
         @reader = reader
         @filepath = filepath
+        @options = options
         @context = Validators::ValidationContext.new
         @results = []
         @chunks = [] # Store chunks as we read them
@@ -184,7 +188,7 @@ module PngConform
       # Proper Model → Formatter pattern
       # - Builds ValidationResult (legacy)
       # - Extracts ImageInfo and CompressionInfo
-      # - Runs all analyzers HERE (not in reporters)
+      # - Runs analyzers conditionally (Phase 1.1 optimization)
       # - Returns complete FileAnalysis model
       #
       # @return [FileAnalysis] Complete analysis model
@@ -205,10 +209,18 @@ module PngConform
           analysis.image_info = image_info
           analysis.compression_info = extract_compression_info(validation_result)
 
-          # Run analyzers HERE (proper Model → Formatter pattern)
-          analysis.resolution_analysis = run_resolution_analysis(validation_result)
-          analysis.optimization_analysis = run_optimization_analysis(validation_result)
-          analysis.metrics = run_metrics_analysis(validation_result)
+          # Run analyzers conditionally (Phase 1.1: saves ~80ms)
+          if need_resolution_analysis?
+            analysis.resolution_analysis = run_resolution_analysis(validation_result)
+          end
+
+          if need_optimization_analysis?
+            analysis.optimization_analysis = run_optimization_analysis(validation_result)
+          end
+
+          if need_metrics_analysis?
+            analysis.metrics = run_metrics_analysis(validation_result)
+          end
         end
       end
 
@@ -248,10 +260,12 @@ module PngConform
 
           result.crc_errors_count = crc_error_count
 
-          # Calculate compression ratio for PNG files
-          if result.file_type == "PNG"
-            result.compression_ratio = calculate_compression_ratio(result.chunks)
-          end
+          # Calculate compression ratio for PNG files (Phase 1.2: lazy calculation)
+          result.compression_ratio = if result.file_type == "PNG" && need_compression_ratio?
+                                       calculate_compression_ratio(result.chunks)
+                                     else
+                                       0.0
+                                     end
 
           # Add errors from service (@results)
           @results.select { |r| r[:type] == :error }.each do |r|
@@ -422,6 +436,7 @@ module PngConform
 
       # Run resolution analyzer
       def run_resolution_analysis(result)
+        require_relative "../analyzers/resolution_analyzer" unless defined?(Analyzers::ResolutionAnalyzer)
         Analyzers::ResolutionAnalyzer.new(result).analyze
       rescue StandardError => e
         { error: "Resolution analysis failed: #{e.message}" }
@@ -429,6 +444,7 @@ module PngConform
 
       # Run optimization analyzer
       def run_optimization_analysis(result)
+        require_relative "../analyzers/optimization_analyzer" unless defined?(Analyzers::OptimizationAnalyzer)
         Analyzers::OptimizationAnalyzer.new(result).analyze
       rescue StandardError => e
         { error: "Optimization analysis failed: #{e.message}" }
@@ -436,6 +452,7 @@ module PngConform
 
       # Run metrics analyzer
       def run_metrics_analysis(result)
+        require_relative "../analyzers/metrics_analyzer" unless defined?(Analyzers::MetricsAnalyzer)
         Analyzers::MetricsAnalyzer.new(result).analyze
       rescue StandardError => e
         { error: "Metrics analysis failed: #{e.message}" }
@@ -452,6 +469,34 @@ module PngConform
         else "unknown"
         end
       end
+
+      # Check if resolution analysis is needed (Phase 1.1)
+      def need_resolution_analysis?
+        return true unless @options[:quiet]
+
+        @options[:resolution] || @options[:mobile_ready]
+      end
+
+      # Check if optimization analysis is needed (Phase 1.1)
+      def need_optimization_analysis?
+        return true unless @options[:quiet]
+
+        @options[:optimize]
+      end
+
+      # Check if metrics analysis is needed (Phase 1.1)
+      def need_metrics_analysis?
+        return true if ["yaml", "json"].include?(@options[:format])
+
+        @options[:metrics]
+      end
+
+      # Check if compression ratio calculation is needed (Phase 1.2)
+      def need_compression_ratio?
+        return true if ["yaml", "json"].include?(@options[:format])
+
+        !@options[:quiet]
+      end
     end
   end
 end

data/lib/png_conform/validators/ancillary/idot_validator.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+require_relative "../base_validator"
+
+module PngConform
+  module Validators
+    module Ancillary
+      # Validator for PNG iDOT (Apple Display Optimization) chunk
+      #
+      # iDOT is an Apple-specific chunk found in screenshots and images saved
+      # from macOS/iOS devices. It contains display optimization data for
+      # Retina displays and multi-core decoding performance.
+      #
+      # Structure (28 bytes - seven 32-bit little-endian integers):
+      # - Display scale factor (4 bytes)
+      # - Pixel format information (4 bytes)
+      # - Color space information (4 bytes)
+      # - Backing scale factor (4 bytes)
+      # - Flags (4 bytes)
+      # - Reserved field 1 (4 bytes)
+      # - Reserved field 2 (4 bytes)
+      #
+      # Validation rules:
+      # - Chunk must be exactly 28 bytes
+      # - Only one iDOT chunk allowed
+      # - Must appear before IDAT chunk
+      #
+      # References:
+      # - Apple's proprietary display optimization format
+      # - Used in macOS/iOS screenshot PNG files
+      class IdotValidator < BaseValidator
+        # Expected chunk length (7 x 4-byte integers)
+        EXPECTED_LENGTH = 28
+
+        # Validate iDOT chunk
+        #
+        # @return [Boolean] True if validation passed
+        def validate
+          return false unless check_crc
+          return false unless check_length(EXPECTED_LENGTH)
+          return false unless check_uniqueness
+          return false unless check_position
+
+          decode_and_store_data
+          true
+        end
+
+        private
+
+        # Check that only one iDOT chunk exists
+        def check_uniqueness
+          if context.seen?("iDOT")
+            add_error("duplicate iDOT chunk (only one allowed)")
+            return false
+          end
+
+          true
+        end
+
+        # Check that iDOT appears before IDAT
+        def check_position
+          if context.seen?("IDAT")
+            add_error("iDOT chunk after IDAT (must be before)")
+            return false
+          end
+
+          true
+        end
+
+        # Decode iDOT data and store in context
+        def decode_and_store_data
+          values = chunk.chunk_data.unpack("V7")
+
+          # Create IdotData model
+          idot_data = create_idot_data(values)
+
+          # Store in context for later use
+          context.store(:idot_data, idot_data)
+
+          # Add info message with decoded data
+          add_info("iDOT: Apple display optimization (#{idot_data.detailed_info})")
+        end
+
+        # Create IdotData model from parsed values
+        #
+        # @param values [Array<Integer>] Seven 32-bit integers
+        # @return [Models::IdotData] The decoded data model
+        def create_idot_data(values)
+          Models::IdotData.new(
+            display_scale: values[0],
+            pixel_format: values[1],
+            color_space: values[2],
+            backing_scale_factor: values[3],
+            flags: values[4],
+            reserved1: values[5],
+            reserved2: values[6],
+          )
+        end
+      end
+    end
+  end
+end