png_conform 0.1.0

data/examples/basic_usage.rb

@@ -0,0 +1,210 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# Basic Usage Examples for PngConform
+#
+# This file demonstrates the most common ways to use PngConform
+# for validating PNG files programmatically.
+#
+
+require "png_conform"
+
+# Example 1: Basic validation
+def basic_validation(file_path)
+  puts "=" * 60
+  puts "Example 1: Basic Validation"
+  puts "=" * 60
+
+  result = PngConform::Services::ValidationService.validate_file(file_path)
+
+  if result.valid?
+    puts "✓ File is valid!"
+    puts "  Dimensions: #{result.image_info.width}x#{result.image_info.height}"
+    puts "  Color type: #{result.image_info.color_type}"
+    puts "  Bit depth: #{result.image_info.bit_depth}"
+    puts "  Chunks: #{result.chunks.count}"
+  else
+    puts "✗ File has errors:"
+    result.errors.each do |error|
+      puts "  #{error.severity.upcase}: #{error.message}"
+    end
+  end
+  puts
+end
+
+# Example 2: Validation with specific profile
+def profile_validation(file_path, profile_name)
+  puts "=" * 60
+  puts "Example 2: Profile-Based Validation (#{profile_name})"
+  puts "=" * 60
+
+  profile = PngConform::Services::ProfileManager.get_profile(profile_name)
+
+  if profile
+    puts "Profile: #{profile[:name]} - #{profile[:description]}"
+    puts "Required chunks: #{profile[:required_chunks].join(', ')}"
+    puts
+
+    result = PngConform::Services::ValidationService.validate_file(file_path)
+    chunk_types = result.chunks.map(&:type)
+
+    # Validate against profile
+    profile_result = PngConform::Services::ProfileManager.validate_file_against_profile(
+      chunk_types, profile_name
+    )
+
+    if profile_result[:valid]
+      puts "✓ File conforms to #{profile_name} profile"
+    else
+      puts "✗ Profile violations:"
+      profile_result[:errors].each do |error|
+        puts "  #{error}"
+      end
+    end
+  else
+    puts "✗ Profile not found: #{profile_name}"
+  end
+  puts
+end
+
+# Example 3: Detailed chunk inspection
+def inspect_chunks(file_path)
+  puts "=" * 60
+  puts "Example 3: Detailed Chunk Inspection"
+  puts "=" * 60
+
+  result = PngConform::Services::ValidationService.validate_file(file_path)
+
+  puts "File: #{file_path}"
+  puts "Chunks found: #{result.chunks.count}"
+  puts
+
+  result.chunks.each do |chunk|
+    puts "Chunk: #{chunk.type}"
+    puts "  Offset: 0x#{chunk.offset.to_s(16).rjust(8, '0')}"
+    puts "  Length: #{chunk.length} bytes"
+    puts "  CRC: #{chunk.crc_expected}"
+    puts "  CRC Valid: #{chunk.valid_crc ? '✓' : '✗'}"
+
+    # Display decoded data for specific chunks
+    if chunk.data
+      case chunk.type
+      when "IHDR"
+        # Extract IHDR data manually
+        width = chunk.data.bytes[0..3].pack("C*").unpack1("N")
+        height = chunk.data.bytes[4..7].pack("C*").unpack1("N")
+        bit_depth = chunk.data.bytes[8]
+        color_type = chunk.data.bytes[9]
+        puts "  Width: #{width}"
+        puts "  Height: #{height}"
+        puts "  Bit Depth: #{bit_depth}"
+        puts "  Color Type: #{color_type}"
+      when "gAMA"
+        gamma_value = chunk.data.bytes[0..3].pack("C*").unpack1("N")
+        puts "  Gamma: #{gamma_value / 100_000.0}"
+      when "tEXt"
+        text = chunk.data.to_s
+        null_pos = text.index("\x00")
+        if null_pos
+          keyword = text[0...null_pos]
+          content = text[(null_pos + 1)..]
+          puts "  Keyword: #{keyword}"
+          puts "  Text: #{content[0..50]}..."
+        end
+      end
+    end
+    puts
+  end
+end
+
+# Example 4: Batch validation
+def batch_validation(directory)
+  puts "=" * 60
+  puts "Example 4: Batch Validation"
+  puts "=" * 60
+
+  results = {
+    valid: [],
+    invalid: [],
+    errors: [],
+  }
+
+  Dir.glob(File.join(directory, "*.png")).each do |file|
+    result = PngConform::Services::ValidationService.validate_file(file)
+    if result.valid?
+      results[:valid] << file
+    else
+      results[:invalid] << { file: file, errors: result.errors }
+    end
+  rescue StandardError => e
+    results[:errors] << { file: file, error: e.message }
+  end
+
+  puts "Processed #{results[:valid].count + results[:invalid].count + results[:errors].count} files"
+  puts "  Valid: #{results[:valid].count}"
+  puts "  Invalid: #{results[:invalid].count}"
+  puts "  Errors: #{results[:errors].count}"
+  puts
+
+  unless results[:invalid].empty?
+    puts "Invalid files:"
+    results[:invalid].each do |item|
+      puts "  #{File.basename(item[:file])}: #{item[:errors].count} errors"
+    end
+  end
+  puts
+end
+
+# Example 5: Export validation results
+def export_results(file_path, format = :yaml)
+  puts "=" * 60
+  puts "Example 5: Export Results (#{format.upcase})"
+  puts "=" * 60
+
+  result = PngConform::Services::ValidationService.validate_file(file_path)
+
+  case format
+  when :yaml
+    require "yaml"
+    puts result.to_yaml
+  when :json
+    require "json"
+    puts JSON.pretty_generate(result.to_h)
+  else
+    puts "Unknown format: #{format}"
+  end
+  puts
+end
+
+# Main execution
+if __FILE__ == $PROGRAM_NAME
+  # Check if a file path was provided
+  if ARGV.empty?
+    puts "Usage: ruby #{$PROGRAM_NAME} PATH_TO_PNG_FILE [DIRECTORY_FOR_BATCH]"
+    puts
+    puts "Examples:"
+    puts "  ruby #{$PROGRAM_NAME} image.png"
+    puts "  ruby #{$PROGRAM_NAME} image.png ./png_directory"
+    exit 1
+  end
+
+  file_path = ARGV[0]
+  directory = ARGV[1]
+
+  unless File.exist?(file_path)
+    puts "Error: File not found: #{file_path}"
+    exit 1
+  end
+
+  # Run examples
+  basic_validation(file_path)
+  profile_validation(file_path, "web")
+  inspect_chunks(file_path)
+  export_results(file_path, :yaml)
+
+  # Run batch validation if directory provided
+  if directory && Dir.exist?(directory)
+    batch_validation(directory)
+  end
+end

data/exe/png_conform

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require_relative "../lib/png_conform"
+
+PngConform::Cli.start(ARGV)

data/lib/png_conform/analyzers/comparison_analyzer.rb

@@ -0,0 +1,230 @@
+# frozen_string_literal: true
+
+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)
+        @result1 = result1
+        @result2 = result2
+      end
+
+      def analyze
+        {
+          files: file_comparison,
+          image: image_comparison,
+          chunks: chunk_comparison,
+          validation: validation_comparison,
+          quality: quality_comparison,
+          summary: generate_summary,
+        }
+      end
+
+      private
+
+      def file_comparison
+        size1 = @result1.file_size
+        size2 = @result2.file_size
+        diff = size2 - size1
+        percent = size1.zero? ? 0 : ((diff.to_f / size1) * 100).round(2)
+
+        {
+          file1: @result1.filename,
+          file2: @result2.filename,
+          size_bytes: {
+            file1: size1,
+            file2: size2,
+            difference: diff,
+            change_percent: percent,
+          },
+          size_change: format_size_change(diff, percent),
+        }
+      end
+
+      def image_comparison
+        ihdr1 = @result1.ihdr_chunk
+        ihdr2 = @result2.ihdr_chunk
+
+        w1 = ihdr1 ? get_width(ihdr1) : 0
+        h1 = ihdr1 ? get_height(ihdr1) : 0
+        w2 = ihdr2 ? get_width(ihdr2) : 0
+        h2 = ihdr2 ? get_height(ihdr2) : 0
+
+        {
+          dimensions: {
+            file1: "#{w1}x#{h1}",
+            file2: "#{w2}x#{h2}",
+            same: w1 == w2 && h1 == h2,
+          },
+        }
+      end
+
+      def chunk_comparison
+        chunks1 = @result1.chunks.map(&:type)
+        chunks2 = @result2.chunks.map(&:type)
+
+        {
+          count: {
+            file1: chunks1.count,
+            file2: chunks2.count,
+            difference: chunks2.count - chunks1.count,
+          },
+          added: chunks2 - chunks1,
+          removed: chunks1 - chunks2,
+          common: chunks1 & chunks2,
+          changed: detect_chunk_changes,
+        }
+      end
+
+      def validation_comparison
+        {
+          validity: {
+            file1: @result1.valid?,
+            file2: @result2.valid?,
+            same: @result1.valid? == @result2.valid?,
+          },
+          errors: {
+            file1: @result1.error_count,
+            file2: @result2.error_count,
+            difference: @result2.error_count - @result1.error_count,
+          },
+          warnings: {
+            file1: @result1.warning_count,
+            file2: @result2.warning_count,
+            difference: @result2.warning_count - @result1.warning_count,
+          },
+          new_errors: new_errors,
+          resolved_errors: resolved_errors,
+        }
+      end
+
+      def quality_comparison
+        {
+          compression_ratio: {
+            file1: @result1.compression_ratio,
+            file2: @result2.compression_ratio,
+            improved: compression_improved?,
+          },
+          has_color_profile: {
+            file1: has_color_profile?(@result1),
+            file2: has_color_profile?(@result2),
+            same: has_color_profile?(@result1) == has_color_profile?(@result2),
+          },
+          metadata_count: {
+            file1: metadata_count(@result1),
+            file2: metadata_count(@result2),
+            difference: metadata_count(@result2) - metadata_count(@result1),
+          },
+        }
+      end
+
+      def detect_chunk_changes
+        common_types = @result1.chunks.map(&:type) & @result2.chunks.map(&:type)
+        changed = []
+
+        common_types.each do |type|
+          chunk1 = @result1.chunks.find { |c| c.type == type }
+          chunk2 = @result2.chunks.find { |c| c.type == type }
+
+          next unless chunk1 && chunk2
+
+          if chunk1.length != chunk2.length || chunk1.crc != chunk2.crc
+            changed << {
+              type: type,
+              size_changed: chunk1.length != chunk2.length,
+              data_changed: chunk1.crc != chunk2.crc,
+            }
+          end
+        end
+
+        changed
+      end
+
+      def new_errors
+        errors1 = @result1.errors.map(&:message).to_set
+        errors2 = @result2.errors.map(&:message).to_set
+        (errors2 - errors1).to_a
+      end
+
+      def resolved_errors
+        errors1 = @result1.errors.map(&:message).to_set
+        errors2 = @result2.errors.map(&:message).to_set
+        (errors1 - errors2).to_a
+      end
+
+      def compression_improved?
+        return nil unless @result1.compression_ratio && @result2.compression_ratio
+
+        @result2.compression_ratio > @result1.compression_ratio
+      end
+
+      def has_color_profile?(result)
+        result.has_chunk?("gAMA") || result.has_chunk?("sRGB") || result.has_chunk?("iCCP")
+      end
+
+      def metadata_count(result)
+        result.chunks.count { |c| METADATA_CHUNKS.include?(c.type) }
+      end
+
+      def format_size_change(diff, percent)
+        if diff.positive?
+          "Larger by #{diff} bytes (+#{percent}%)"
+        elsif diff.negative?
+          "Smaller by #{diff.abs} bytes (#{percent}%)"
+        else
+          "Same size"
+        end
+      end
+
+      def generate_summary
+        summary = []
+
+        size_diff = @result2.file_size - @result1.file_size
+        summary << format_size_summary(size_diff) if size_diff.abs > 1024
+
+        added = chunk_comparison[:added]
+        removed = chunk_comparison[:removed]
+        summary << "Chunks added: #{added.join(', ')}" if added.any?
+        summary << "Chunks removed: #{removed.join(', ')}" if removed.any?
+
+        if @result1.valid? && !@result2.valid?
+          summary << "⚠️ File became invalid"
+        elsif !@result1.valid? && @result2.valid?
+          summary << "✓ File became valid"
+        end
+
+        summary
+      end
+
+      def format_size_summary(diff)
+        diff.positive? ? "File grew by #{format_bytes(diff)}" : "File reduced by #{format_bytes(diff.abs)} ✓"
+      end
+
+      def format_bytes(bytes)
+        if bytes < 1024
+          "#{bytes} bytes"
+        elsif bytes < 1024 * 1024
+          "#{(bytes / 1024.0).round(2)} KB"
+        else
+          "#{(bytes / 1024.0 / 1024.0).round(2)} MB"
+        end
+      end
+
+      # Helper methods to extract IHDR data
+      def get_width(ihdr_chunk)
+        return 0 unless ihdr_chunk.data && ihdr_chunk.data.bytesize >= 4
+
+        ihdr_chunk.data.bytes[0..3].pack("C*").unpack1("N")
+      end
+
+      def get_height(ihdr_chunk)
+        return 0 unless ihdr_chunk.data && ihdr_chunk.data.bytesize >= 8
+
+        ihdr_chunk.data.bytes[4..7].pack("C*").unpack1("N")
+      end
+    end
+  end
+end

data/lib/png_conform/analyzers/metrics_analyzer.rb

@@ -0,0 +1,176 @@
+# frozen_string_literal: true
+
+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)
+        @result = result
+        ihdr = result.ihdr_chunk
+        @width = ihdr ? get_width(ihdr) : 0
+        @height = ihdr ? get_height(ihdr) : 0
+        @bit_depth = ihdr ? get_bit_depth(ihdr) : 0
+        @color_type = ihdr ? get_color_type(ihdr) : 0
+      end
+
+      def analyze
+        {
+          file: file_metrics,
+          image: image_metrics,
+          chunks: chunk_metrics,
+          validation: validation_metrics,
+          compression: compression_metrics,
+          quality: quality_metrics,
+        }
+      end
+
+      def to_json(*_args)
+        require "json"
+        JSON.pretty_generate(analyze)
+      end
+
+      def to_yaml
+        require "yaml"
+        analyze.to_yaml
+      end
+
+      private
+
+      # Extract data from IHDR chunk
+      def get_width(ihdr_chunk)
+        return 0 unless ihdr_chunk.data && ihdr_chunk.data.bytesize >= 4
+
+        ihdr_chunk.data.bytes[0..3].pack("C*").unpack1("N")
+      end
+
+      def get_height(ihdr_chunk)
+        return 0 unless ihdr_chunk.data && ihdr_chunk.data.bytesize >= 8
+
+        ihdr_chunk.data.bytes[4..7].pack("C*").unpack1("N")
+      end
+
+      def get_bit_depth(ihdr_chunk)
+        return 0 unless ihdr_chunk.data && ihdr_chunk.data.bytesize >= 9
+
+        ihdr_chunk.data.bytes[8]
+      end
+
+      def get_color_type(ihdr_chunk)
+        return 0 unless ihdr_chunk.data && ihdr_chunk.data.bytesize >= 10
+
+        ihdr_chunk.data.bytes[9]
+      end
+
+      def color_type_name
+        case @color_type
+        when 0 then "Grayscale"
+        when 2 then "RGB"
+        when 3 then "Indexed"
+        when 4 then "Grayscale+Alpha"
+        when 6 then "RGBA"
+        else "Unknown"
+        end
+      end
+
+      def file_metrics
+        {
+          filename: @result.filename,
+          size_bytes: @result.file_size,
+          size_kb: (@result.file_size / 1024.0).round(2),
+          size_mb: (@result.file_size / 1024.0 / 1024.0).round(4),
+          file_type: @result.file_type,
+        }
+      end
+
+      def image_metrics
+        {
+          width: @width,
+          height: @height,
+          dimensions: "#{@width}x#{@height}",
+          total_pixels: @width * @height,
+          megapixels: (@width * @height / 1_000_000.0).round(2),
+          bit_depth: @bit_depth,
+          color_type: @color_type,
+          color_type_name: color_type_name,
+          has_alpha: [4, 6].include?(@color_type),
+          has_palette: @color_type == 3,
+        }
+      end
+
+      def chunk_metrics
+        {
+          total_count: @result.chunks.count,
+          types: @result.chunks.map(&:type).uniq.sort,
+          type_counts: @result.chunks.group_by(&:type).transform_values(&:count),
+          critical_chunks: @result.chunks.select(&:critical?).map(&:type),
+          ancillary_chunks: @result.chunks.reject(&:critical?).map(&:type),
+          total_chunk_data_bytes: @result.chunks.sum(&:length),
+          total_chunk_overhead_bytes: @result.chunks.count * 12,
+          chunk_data_percentage: calculate_chunk_data_percentage,
+        }
+      end
+
+      def validation_metrics
+        {
+          valid: @result.valid?,
+          error_count: @result.error_count,
+          warning_count: @result.warning_count,
+          info_count: @result.info_count,
+          errors_by_severity: {
+            error: @result.error_count,
+            warning: @result.warning_count,
+            info: @result.info_count,
+          },
+          crc_errors: @result.crc_errors_count,
+          has_errors: @result.error_count.positive?,
+          has_warnings: @result.warning_count.positive?,
+        }
+      end
+
+      def compression_metrics
+        {
+          compression_ratio: @result.compression_ratio,
+        }
+      end
+
+      def quality_metrics
+        {
+          has_color_profile: @result.has_chunk?("gAMA") ||
+            @result.has_chunk?("sRGB") ||
+            @result.has_chunk?("iCCP"),
+          has_gamma: @result.has_chunk?("gAMA"),
+          has_srgb: @result.has_chunk?("sRGB"),
+          has_iccp: @result.has_chunk?("iCCP"),
+          has_transparency: @result.has_chunk?("tRNS"),
+          has_metadata: @result.chunks.any? do |c|
+            TEXT_CHUNKS.include?(c.type)
+          end,
+          metadata_chunks_count: @result.chunks.count do |c|
+            METADATA_CHUNKS.include?(c.type)
+          end,
+          bytes_per_pixel: calculate_bytes_per_pixel,
+        }
+      end
+
+      def calculate_chunk_data_percentage
+        return 0 if @result.file_size.zero?
+
+        total_chunk_bytes = @result.chunks.sum(&:length) + (@result.chunks.count * 12)
+        (total_chunk_bytes.to_f / @result.file_size * 100).round(2)
+      end
+
+      def calculate_bytes_per_pixel
+        total_pixels = @width * @height
+        return 0 if total_pixels.zero?
+
+        (@result.file_size.to_f / total_pixels).round(3)
+      end
+    end
+  end
+end