png_conform 0.1.1 → 0.1.3

data/docs/CHUNK_TYPES.adoc

@@ -240,6 +240,48 @@ Complete reference of all PNG, MNG, JNG, and APNG chunk types validated by PngCo
 **Size**: 1 byte
 **Values**: 0=cross-fuse, 1=diverging-fuse
 
+== Apple Extensions
+
+=== iDOT (Apple Display Optimization)
+
+**Purpose**: Apple-specific display optimization data for Retina displays
+**Size**: 28 bytes
+**Optional**: Only present in screenshots and images saved from macOS/iOS devices
+
+**Contents**:
+
+* Display scale factor (4 bytes, little-endian)
+* Pixel format information (4 bytes, little-endian)
+* Color space information (4 bytes, little-endian)
+* Backing scale factor (4 bytes, little-endian)
+* Flags (4 bytes, little-endian)
+* Reserved field 1 (4 bytes, little-endian)
+* Reserved field 2 (4 bytes, little-endian)
+
+**Validation**:
+
+* Chunk must be exactly 28 bytes
+* Only one iDOT chunk allowed per file
+* Must appear before IDAT chunk
+* CRC must be valid
+
+**Usage**:
+
+The iDOT chunk is automatically added by macOS and iOS when saving screenshots or images through system APIs. It contains display optimization data for:
+
+* Retina display rendering
+* Multi-core decoding performance
+* Display color space information
+* Backing store scale factors
+
+This chunk is safe to ignore for standard PNG decoders, as it follows the ancillary chunk naming convention (lowercase first letter).
+
+**References**:
+
+* Apple proprietary format
+* Found in PNG files generated by macOS 10.7+ and iOS 5+
+* Commonly seen in screenshot files
+
 == APNG (Animated PNG) Chunks
 
 === acTL (Animation Control)

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/analyzers/comparison_analyzer.rb

@@ -1,18 +1,51 @@
 # frozen_string_literal: true
 
+require_relative "../configuration"
+require_relative "../services/file_signature"
+
 module PngConform
   module Analyzers
     # Compares two PNG files and reports differences
     class ComparisonAnalyzer
-      # Metadata chunk types
-      METADATA_CHUNKS = %w[tEXt zTXt iTXt tIME].freeze
-
-      def initialize(result1, result2)
+      def initialize(result1, result2, config: Configuration.instance)
         @result1 = result1
         @result2 = result2
+        @config = config
+
+        # Fast path: compute signatures for quick equality check
+        @sig1 = Services::FileSignature.from_result(result1).compute_signature
+        @sig2 = Services::FileSignature.from_result(result2).compute_signature
       end
 
       def analyze
+        # Fast return if signatures are identical
+        return identical_result if @sig1 == @sig2
+
+        # Full comparison for different files
+        full_comparison
+      end
+
+      private
+
+      # Return result for identical files
+      #
+      # @return [Hash] Analysis result for identical files
+      def identical_result
+        {
+          files: {
+            file1: @result1.filename,
+            file2: @result2.filename,
+            identical: true,
+            signature: @sig1.short_signature,
+          },
+          summary: ["Files are binary identical"],
+        }
+      end
+
+      # Full comparison for different files
+      #
+      # @return [Hash] Complete comparison analysis
+      def full_comparison
         {
           files: file_comparison,
           image: image_comparison,
@@ -23,8 +56,6 @@ module PngConform
         }
       end
 
-      private
-
       def file_comparison
         size1 = @result1.file_size
         size2 = @result2.file_size
@@ -166,7 +197,10 @@ module PngConform
       end
 
       def metadata_count(result)
-        result.chunks.count { |c| METADATA_CHUNKS.include?(c.type) }
+        # Use only text and time chunks from metadata (excluding pHYs which is physical)
+        result.chunks.count do |c|
+          @config.text_chunks.include?(c.type) || c.type == "tIME"
+        end
       end
 
       def format_size_change(diff, percent)

data/lib/png_conform/analyzers/metrics_analyzer.rb

@@ -1,17 +1,14 @@
 # frozen_string_literal: true
 
+require_relative "../configuration"
+
 module PngConform
   module Analyzers
     # Generates comprehensive metrics for CI/CD and automation
     class MetricsAnalyzer
-      # Text chunk types
-      TEXT_CHUNKS = %w[tEXt zTXt iTXt].freeze
-
-      # Metadata chunk types including time
-      METADATA_CHUNKS = %w[tEXt zTXt iTXt tIME].freeze
-
-      def initialize(result)
+      def initialize(result, config: Configuration.instance)
         @result = result
+        @config = config
         ihdr = result.ihdr_chunk
         @width = ihdr ? get_width(ihdr) : 0
         @height = ihdr ? get_height(ihdr) : 0
@@ -149,10 +146,10 @@ module PngConform
           has_iccp: @result.has_chunk?("iCCP"),
           has_transparency: @result.has_chunk?("tRNS"),
           has_metadata: @result.chunks.any? do |c|
-            TEXT_CHUNKS.include?(c.type)
+            @config.text_chunks.include?(c.type)
           end,
           metadata_chunks_count: @result.chunks.count do |c|
-            METADATA_CHUNKS.include?(c.type)
+            @config.metadata_chunks.include?(c.type)
           end,
           bytes_per_pixel: calculate_bytes_per_pixel,
         }

data/lib/png_conform/analyzers/optimization_analyzer.rb

@@ -1,20 +1,14 @@
 # frozen_string_literal: true
 
+require_relative "../configuration"
+
 module PngConform
   module Analyzers
     # Analyzes PNG files for optimization opportunities
     class OptimizationAnalyzer
-      # Chunks that are often unnecessary for web/mobile use
-      UNNECESSARY_FOR_WEB = %w[tIME pHYs oFFs pCAL sCAL sTER].freeze
-
-      # Text chunk types
-      TEXT_CHUNKS = %w[tEXt zTXt iTXt].freeze
-
-      # Metadata chunk types
-      METADATA_CHUNKS = %w[tEXt zTXt iTXt tIME pHYs].freeze
-
-      def initialize(result)
+      def initialize(result, config: Configuration.instance)
         @result = result
+        @config = config
         @suggestions = []
       end
 
@@ -37,7 +31,7 @@ module PngConform
 
       def check_unnecessary_chunks
         unnecessary = @result.chunks.select do |c|
-          UNNECESSARY_FOR_WEB.include?(c.type)
+          @config.unnecessary_web_chunks.include?(c.type)
         end
         return if unnecessary.empty?
 
@@ -61,14 +55,17 @@ module PngConform
         # Estimate if 8-bit would be sufficient
         if could_use_8_bit?
           current_size = @result.file_size
-          estimated_savings = (current_size * 0.45).to_i # ~45% reduction
+          estimated_savings = (
+            current_size *
+            @config.optimization_percentages[:bit_depth_reduction] / 100.0
+          ).to_i
 
           @suggestions << {
             type: :reduce_bit_depth,
             priority: :high,
             savings_bytes: estimated_savings,
             description: "Convert from 16-bit to 8-bit depth " \
-                        "(estimated ~45% file size reduction)",
+                        "(estimated ~#{@config.optimization_percentages[:bit_depth_reduction]}% file size reduction)",
             current: "16-bit",
             recommended: "8-bit",
           }
@@ -79,15 +76,18 @@ module PngConform
         # Get color type from IHDR
         ihdr = @result.ihdr_chunk
         return unless ihdr && get_color_type(ihdr) == 2 # RGB
-        return if @result.file_size < 10_000 # Skip small files
+        return if @result.file_size < @config.size_thresholds[:palette_opportunity]
 
         # If it's RGB but could be palette
         @suggestions << {
           type: :convert_to_palette,
           priority: :medium,
-          savings_bytes: (@result.file_size * 0.30).to_i,
+          savings_bytes: (
+            @result.file_size *
+            @config.optimization_percentages[:palette_conversion] / 100.0
+          ).to_i,
           description: "Consider converting to palette mode if using limited colors " \
-                      "(potential ~30% reduction)",
+                      "(potential ~#{@config.optimization_percentages[:palette_conversion]}% reduction)",
           current: "RGB (Truecolor)",
           recommended: "Indexed (Palette)",
         }
@@ -99,25 +99,30 @@ module PngConform
         return unless ihdr && get_interlace_method(ihdr) == 1
 
         # Interlaced PNGs are larger
-        savings = (@result.file_size * 0.15).to_i
+        savings = (
+          @result.file_size *
+          @config.optimization_percentages[:interlace_removal] / 100.0
+        ).to_i
 
         @suggestions << {
           type: :remove_interlacing,
           priority: :low,
           savings_bytes: savings,
           description: "Remove interlacing for smaller file size " \
-                      "(~15% reduction, but slower initial display)",
+                      "(~#{@config.optimization_percentages[:interlace_removal]}% reduction, but slower initial display)",
           current: "Adam7 interlaced",
           recommended: "Non-interlaced",
         }
       end
 
       def check_text_chunks
-        text_chunks = @result.chunks.select { |c| TEXT_CHUNKS.include?(c.type) }
+        text_chunks = @result.chunks.select do |c|
+          @config.text_chunks.include?(c.type)
+        end
         return if text_chunks.empty?
 
         total_text_size = text_chunks.sum { |c| c.length + 12 }
-        return if total_text_size < 500 # Ignore small metadata
+        return if total_text_size < @config.size_thresholds[:text_metadata]
 
         @suggestions << {
           type: :reduce_metadata,
@@ -131,14 +136,15 @@ module PngConform
 
       def check_metadata_size
         metadata_chunks = @result.chunks.select do |c|
-          METADATA_CHUNKS.include?(c.type)
+          @config.metadata_chunks.include?(c.type)
         end
 
         total_metadata = metadata_chunks.sum { |c| c.length + 12 }
         file_size = @result.file_size
 
-        # If metadata is more than 10% of file size
-        return unless total_metadata > file_size * 0.1
+        # If metadata is more than threshold percent of file size
+        threshold = @config.optimization_percentages[:metadata_threshold]
+        return unless total_metadata > file_size * threshold / 100.0
 
         @suggestions << {
           type: :excessive_metadata,
@@ -173,7 +179,7 @@ module PngConform
       def could_use_8_bit?
         # Conservative heuristic: suggest 8-bit for smaller files
         # Without pixel analysis, we're conservative
-        @result.file_size < 100_000
+        @result.file_size < @config.size_thresholds[:small_file]
       end
 
       def calculate_total_savings