png_conform 0.1.0

data/lib/png_conform/bindata/mng_file.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module PngConform
+  module BinData
+    # MNG (Multiple-image Network Graphics) file structure
+    # An MNG file consists of:
+    # - 8-byte signature: 138 77 78 71 13 10 26 10
+    # - MHDR chunk (must be first)
+    # - Series of chunks (can include PNG chunks)
+    # - MEND chunk (must be last)
+    class MngFile < ::BinData::Record
+      # MNG signature (magic number)
+      MNG_SIGNATURE = [138, 77, 78, 71, 13, 10, 26, 10].pack("C*").freeze
+
+      string :signature, length: 8
+      array :chunks, type: :chunk_structure, read_until: :eof
+
+      # Validate MNG signature
+      def valid_signature?
+        signature == MNG_SIGNATURE
+      end
+
+      # Get signature as hex string for display
+      def signature_hex
+        signature.unpack1("H*")
+      end
+
+      # Find chunks by type
+      def chunks_by_type(type)
+        chunks.select { |chunk| chunk.type == type }
+      end
+
+      # Get MHDR chunk (must be first chunk)
+      def mhdr_chunk
+        chunks.first if chunks.first&.type == "MHDR"
+      end
+
+      # Get MEND chunk (must be last chunk)
+      def mend_chunk
+        chunks.last if chunks.last&.type == "MEND"
+      end
+
+      # Get all PNG image chunks (IHDR-IEND sequences)
+      def png_images
+        images = []
+        current_image = []
+
+        chunks.each do |chunk|
+          if chunk.type == "IHDR"
+            current_image = [chunk]
+          elsif !current_image.empty?
+            current_image << chunk
+            if chunk.type == "IEND"
+              images << current_image
+              current_image = []
+            end
+          end
+        end
+
+        images
+      end
+
+      # Get all JNG image chunks (JHDR-IEND sequences)
+      def jng_images
+        images = []
+        current_image = []
+
+        chunks.each do |chunk|
+          if chunk.type == "JHDR"
+            current_image = [chunk]
+          elsif !current_image.empty?
+            current_image << chunk
+            if chunk.type == "IEND"
+              images << current_image
+              current_image = []
+            end
+          end
+        end
+
+        images
+      end
+
+      # Check if file has proper chunk ordering
+      def proper_chunk_order?
+        return false unless mhdr_chunk
+        return false unless mend_chunk
+
+        true
+      end
+
+      # Get total file size
+      def total_size
+        8 + chunks.sum(&:total_size)
+      end
+    end
+  end
+end

data/lib/png_conform/bindata/png_file.rb

@@ -0,0 +1,162 @@
+# frozen_string_literal: true
+
+require "bindata"
+require_relative "chunk_structure"
+
+module PngConform
+  module BinData
+    # Binary structure for PNG files
+    #
+    # PNG file format (from PNG spec):
+    #   Signature: 8 bytes (0x89 0x50 0x4E 0x47 0x0D 0x0A 0x1A 0x0A)
+    #   Chunks:    variable number of chunks until IEND
+    #
+    # The PNG signature is always:
+    #   - 0x89: High bit set to detect transmission as text
+    #   - "PNG": Format identifier
+    #   - 0x0D 0x0A: DOS-style line ending (CRLF)
+    #   - 0x1A: DOS end-of-file character
+    #   - 0x0A: Unix-style line ending (LF)
+    #
+    # @example Reading a PNG file
+    #   File.open("image.png", "rb") do |f|
+    #     png = PngFile.read(f)
+    #     puts "Valid PNG" if png.valid_signature?
+    #     png.chunks.each { |chunk| puts chunk.type }
+    #   end
+    #
+    class PngFile < ::BinData::Record
+      # PNG signature (8 bytes)
+      # Must be: 0x89 0x50 0x4E 0x47 0x0D 0x0A 0x1A 0x0A
+      string :signature, length: 8
+
+      # Array of chunks (read until IEND)
+      array :chunks, type: :chunk_structure, read_until: :eof
+
+      # Expected PNG signature bytes
+      PNG_SIGNATURE = [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]
+        .pack("C*")
+        .freeze
+
+      # Check if the signature is valid
+      #
+      # @return [Boolean] true if signature matches PNG specification
+      def valid_signature?
+        signature == PNG_SIGNATURE
+      end
+
+      # Get signature as hex string for debugging
+      #
+      # @return [String] signature in hex format
+      def signature_hex
+        signature.bytes.map { |b| format("%02x", b) }.join(" ")
+      end
+
+      # Find a specific chunk by type
+      #
+      # @param type [String, Symbol] chunk type (e.g., "IHDR" or :IHDR)
+      # @return [ChunkStructure, nil] the first matching chunk or nil
+      def find_chunk(type)
+        type_str = type.to_s
+        chunks.find { |chunk| chunk.type == type_str }
+      end
+
+      # Find all chunks of a specific type
+      #
+      # @param type [String, Symbol] chunk type
+      # @return [Array<ChunkStructure>] all matching chunks
+      def find_chunks(type)
+        type_str = type.to_s
+        chunks.select { |chunk| chunk.type == type_str }
+      end
+
+      # Get the IHDR chunk (image header)
+      #
+      # @return [ChunkStructure, nil] the IHDR chunk
+      def ihdr
+        find_chunk("IHDR")
+      end
+
+      # Get the IEND chunk (image end)
+      #
+      # @return [ChunkStructure, nil] the IEND chunk
+      def iend
+        find_chunk("IEND")
+      end
+
+      # Get all IDAT chunks (image data)
+      #
+      # @return [Array<ChunkStructure>] all IDAT chunks
+      def idats
+        find_chunks("IDAT")
+      end
+
+      # Get the PLTE chunk (palette)
+      #
+      # @return [ChunkStructure, nil] the PLTE chunk
+      def plte
+        find_chunk("PLTE")
+      end
+
+      # Check if this appears to be a valid PNG structure
+      #
+      # Basic validation:
+      # - Valid signature
+      # - Has IHDR as first chunk
+      # - Has IEND as last chunk
+      #
+      # @return [Boolean] true if basic structure is valid
+      def structurally_valid?
+        return false unless valid_signature?
+        return false if chunks.empty?
+        return false unless chunks.first.type == "IHDR"
+        return false unless chunks.last.type == "IEND"
+
+        true
+      end
+
+      # Get chunk sequence as array of types
+      #
+      # @return [Array<String>] array of chunk type codes
+      def chunk_sequence
+        chunks.map(&:type)
+      end
+
+      # Count chunks by type
+      #
+      # @return [Hash<String, Integer>] chunk types and their counts
+      def chunk_counts
+        chunks.each_with_object(Hash.new(0)) do |chunk, counts|
+          counts[chunk.type] += 1
+        end
+      end
+
+      # Check if all chunks have valid CRCs
+      #
+      # @return [Boolean] true if all CRCs are valid
+      def all_crcs_valid?
+        chunks.all?(&:crc_valid?)
+      end
+
+      # Get chunks with invalid CRCs
+      #
+      # @return [Array<ChunkStructure>] chunks with CRC errors
+      def invalid_crc_chunks
+        chunks.reject(&:crc_valid?)
+      end
+
+      # Get file summary information
+      #
+      # @return [Hash] summary of file structure
+      def summary
+        {
+          signature_valid: valid_signature?,
+          chunk_count: chunks.length,
+          chunk_types: chunk_counts,
+          structurally_valid: structurally_valid?,
+          all_crcs_valid: all_crcs_valid?,
+        }
+      end
+    end
+  end
+end

data/lib/png_conform/cli.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "thor"
+require_relative "commands/check_command"
+require_relative "commands/list_command"
+
+module PngConform
+  # Main CLI application class using Thor framework.
+  #
+  # Provides the command-line interface for PNG validation and analysis.
+  # Delegates to command classes for implementation.
+  class Cli < Thor
+    class_option :verbose,
+                 type: :boolean,
+                 default: false,
+                 desc: "Enable verbose output"
+
+    desc "check FILES", "Validate PNG files"
+    long_desc <<~DESC
+            Validate one or more PNG files and report any errors or warnings.
+
+            Options:
+              -f, --format FORMAT     Output format: text, yaml, json (default: text)
+              -v, --verbose           Print detailed chunk information
+              -vv, --very-verbose     Print very detailed information including \
+      line filters
+              -q, --quiet             Only output errors (suppress success messages)
+              --no-color              Disable colored output (colors enabled by default)
+              -p, --palette           Print palette and histogram chunks
+              -t, --text              Print text chunk contents
+              -7, --seven-bit         Escape characters >= 128 for 7-bit terminals
+              --profile PROFILE       Validate against a specific profile \
+      (minimal, web, print, archive, strict, default)
+              --strict                Enable strict validation mode
+              --optimize              Show optimization suggestions
+              --metrics               Show detailed metrics (JSON/YAML)
+              --resolution            Show resolution and Retina analysis
+              --mobile-ready          Check mobile and Retina readiness
+
+            Examples:
+              png_conform check image.png
+              png_conform check -v image.png
+              png_conform check --optimize image.png
+              png_conform check --resolution icon@2x.png
+              png_conform check --metrics --format json image.png
+              png_conform check --mobile-ready app-icon.png
+              png_conform check --profile web *.png
+    DESC
+    option :format, aliases: :f, type: :string, default: "text",
+                    desc: "Output format (text, yaml, json)"
+    option :very_verbose, aliases: :vv, type: :boolean, default: false,
+                          desc: "Print very detailed information"
+    option :quiet, aliases: :q, type: :boolean, default: false,
+                   desc: "Only output errors"
+    option :no_color, type: :boolean, default: false,
+                      desc: "Disable colored output"
+    option :palette, aliases: :p, type: :boolean, default: false,
+                     desc: "Print palette and histogram chunks"
+    option :text, aliases: :t, type: :boolean, default: false,
+                  desc: "Print text chunk contents"
+    option :seven_bit, aliases: :"7", type: :boolean, default: false,
+                       desc: "Escape chars >= 128"
+    option :profile, type: :string, default: nil,
+                     desc: "Validation profile"
+    option :strict, type: :boolean, default: false,
+                    desc: "Strict validation mode"
+    option :optimize, type: :boolean, default: false,
+                      desc: "Show file size optimization suggestions"
+    option :metrics, type: :boolean, default: false,
+                     desc: "Show comprehensive metrics"
+    option :resolution, type: :boolean, default: false,
+                        desc: "Show resolution and Retina/DPI analysis"
+    option :mobile_ready, type: :boolean, default: false,
+                          desc: "Check mobile and Retina readiness"
+    def check(*files)
+      Commands::CheckCommand.new(files, options).run
+    end
+
+    desc "list", "List available validation profiles"
+    long_desc <<~DESC
+      Display all available validation profiles and their requirements.
+
+      Profiles define different validation rules for different use cases:
+        - minimal: Basic PNG structure validation
+        - web: Browser-optimized validation
+        - print: Print-ready validation with physical dimensions
+        - archive: Long-term preservation with full metadata
+        - strict: Strictest possible validation
+        - default: Balanced validation for general use
+
+      Examples:
+        png_conform list
+    DESC
+    def list
+      Commands::ListCommand.new(options).run
+    end
+
+    desc "version", "Display version information"
+    def version
+      puts "png_conform version #{PngConform::VERSION}"
+      puts "Ruby version #{RUBY_VERSION}"
+    end
+
+    # Override default error handling to provide helpful messages
+    def self.exit_on_failure?
+      true
+    end
+
+    # Provide helpful error message for unknown commands
+    def method_missing(method, *_args)
+      puts "Error: Unknown command '#{method}'"
+      puts "Run 'png_conform help' for usage information"
+      exit(1)
+    end
+  end
+end

data/lib/png_conform/commands/check_command.rb

@@ -0,0 +1,323 @@
+# frozen_string_literal: true
+
+require_relative "../services/validation_service"
+require_relative "../services/profile_manager"
+require_relative "../reporters/reporter_factory"
+require_relative "../readers/streaming_reader"
+
+module PngConform
+  module Commands
+    # Command to validate PNG files and report results.
+    #
+    # Coordinates between readers, validators, and reporters to analyze
+    # PNG files according to specified options and profiles.
+    class CheckCommand
+      attr_reader :files, :options
+
+      # @param files [Array<String>] List of file paths to validate
+      # @param options [Hash] Command-line options
+      def initialize(files, options = {})
+        @files = files
+        @options = options
+        @errors_found = false
+      end
+
+      # Execute the validation command.
+      #
+      # @return [Integer] Exit code (0 for success, 1 for errors)
+      def run
+        validate_inputs
+        validate_files
+        exit_code
+      end
+
+      private
+
+      # Validate command inputs and options.
+      def validate_inputs
+        if files.empty?
+          puts "Error: No files specified"
+          puts "Usage: png_conform check [OPTIONS] FILES"
+          exit(1)
+        end
+
+        # Check if profile exists (if specified)
+        if options[:profile] && !Services::ProfileManager.profile_exists?(options[:profile])
+          puts "Error: Unknown profile '#{options[:profile]}'"
+          puts "Available profiles: #{Services::ProfileManager.available_profiles.join(', ')}"
+          exit(1)
+        end
+
+        # Check for conflicting options
+        if options[:quiet] && options[:verbose]
+          puts "Warning: --quiet and --verbose are mutually exclusive, using --quiet"
+          options[:verbose] = false
+        end
+
+        return unless options[:quiet] && options[:very_verbose]
+
+        puts "Warning: --quiet and --very-verbose are mutually exclusive, using --quiet"
+        options[:very_verbose] = false
+      end
+
+      # Validate all specified files.
+      def validate_files
+        reporter = create_reporter
+
+        files.each do |file_path|
+          validate_single_file(file_path, reporter)
+        end
+      end
+
+      # Validate a single PNG file.
+      #
+      # @param file_path [String] Path to the PNG file
+      # @param reporter [Reporters::BaseReporter] Reporter for output
+      def validate_single_file(file_path, reporter)
+        unless File.exist?(file_path)
+          puts "Error: File not found: #{file_path}"
+          @errors_found = true
+          return
+        end
+
+        unless File.file?(file_path)
+          puts "Error: Not a file: #{file_path}"
+          @errors_found = true
+          return
+        end
+
+        # Read and validate the file using streaming reader
+        Readers::StreamingReader.open(file_path) do |reader|
+          # Perform validation
+          validator = Services::ValidationService.new(reader, file_path)
+          file_analysis = validator.validate
+
+          # Track if any errors were found
+          @errors_found = true unless file_analysis.valid?
+
+          # Use reporter to output result
+          reporter.report(file_analysis)
+
+          # For text output (default), show additional analysis unless quiet
+          if (options[:format].nil? || options[:format] == "text") && !options[:quiet]
+            show_resolution_analysis(file_analysis)
+            show_optimization_suggestions(file_analysis)
+          end
+
+          # Explicit flags always show
+          show_metrics(file_analysis) if options[:metrics]
+          show_mobile_readiness(file_analysis) if options[:mobile_ready]
+        end
+      rescue StandardError => e
+        puts "Error processing #{file_path}: #{e.message}"
+        puts e.backtrace.join("\n") if options[:verbose]
+        @errors_found = true
+      end
+
+      # Create the appropriate reporter based on options.
+      #
+      # @return [Reporters::BaseReporter] Reporter instance
+      def create_reporter
+        Reporters::ReporterFactory.create(
+          format: options[:format] || "text",
+          verbose: options[:verbose] || options[:very_verbose],
+          quiet: options[:quiet],
+          colorize: !options[:no_color],
+          show_palette: options[:palette],
+          show_text: options[:text],
+          seven_bit: options[:seven_bit],
+        )
+      end
+
+      # Show optimization suggestions for the file
+      def show_optimization_suggestions(file_analysis)
+        analysis = file_analysis.optimization_analysis
+        return unless analysis && analysis[:suggestions]
+        return if analysis[:suggestions].empty?
+
+        puts "\n#{colorize('OPTIMIZATION SUGGESTIONS:', :bold)}"
+        analysis[:suggestions].each_with_index do |suggestion, index|
+          priority_color = priority_color(suggestion[:priority])
+          priority_label = suggestion[:priority].to_s.upcase
+
+          puts "  #{index + 1}. [#{colorize(priority_label,
+                                            priority_color)}] #{suggestion[:description]}"
+          if suggestion[:savings_bytes]&.positive?
+            puts "     Savings: #{format_bytes(suggestion[:savings_bytes])}"
+          end
+        end
+
+        total_savings = analysis[:potential_savings_bytes]
+        if total_savings.positive?
+          puts "\n  #{colorize('Total Potential Savings:', :bold)} " \
+               "#{format_bytes(total_savings)} (#{analysis[:potential_savings_percent]}%)"
+        end
+      end
+
+      # Show comprehensive metrics
+      def show_metrics(file_analysis)
+        metrics = file_analysis.metrics
+        return unless metrics
+
+        case options[:format]
+        when "json"
+          require "json"
+          puts JSON.pretty_generate(metrics)
+        when "yaml"
+          require "yaml"
+          puts metrics.to_yaml
+        else
+          # Text format with colored output
+          puts "\n#{colorize('METRICS:', :bold)}"
+          puts "  File: #{metrics[:file][:filename]} (#{metrics[:file][:size_kb]} KB)"
+          puts "  Image: #{metrics[:image][:dimensions]}, #{metrics[:image][:color_type_name]}, " \
+               "#{metrics[:image][:bit_depth]}-bit"
+          puts "  Chunks: #{metrics[:chunks][:total_count]} (#{metrics[:chunks][:types].join(', ')})"
+          puts "  Validation: #{metrics[:validation][:error_count]} errors, " \
+               "#{metrics[:validation][:warning_count]} warnings"
+        end
+      end
+
+      # Show resolution and Retina analysis
+      def show_resolution_analysis(file_analysis)
+        analysis = file_analysis.resolution_analysis
+        return unless analysis
+
+        puts "\n#{colorize('RESOLUTION ANALYSIS:', :bold)}"
+
+        # Basic info
+        res = analysis[:resolution]
+        puts "  Dimensions: #{res[:dimensions]} (#{res[:megapixels]} megapixels)"
+        puts "  DPI: #{res[:dpi] || 'Not specified'}"
+
+        # Retina analysis
+        puts "\n  #{colorize('Retina Analysis:', :bold)}"
+        retina = analysis[:retina]
+        puts "    @1x: #{retina[:at_1x][:dimensions_pt]} (#{retina[:at_1x][:suitable_for].first})"
+        puts "    @2x: #{retina[:at_2x][:dimensions_pt]} (#{retina[:at_2x][:suitable_for].first})"
+        puts "    @3x: #{retina[:at_3x][:dimensions_pt]} (#{retina[:at_3x][:suitable_for].first})"
+        puts "    Recommended: #{retina[:recommended_density]}"
+
+        # iOS suggestions
+        ios = retina[:ios_asset_catalog]
+        if ios && !ios.empty?
+          puts "    iOS: #{ios.join(', ')}"
+        end
+
+        # Android
+        puts "    Android: #{retina[:android_density]}"
+
+        # Print analysis if DPI available
+        if analysis[:print][:capable]
+          print_info = analysis[:print]
+          puts "\n  #{colorize('Print Analysis:', :bold)}"
+          puts "    Quality: #{print_info[:quality]} (#{print_info[:dpi]} DPI)"
+          phys = print_info[:physical_size]
+          puts "    Physical Size: #{phys[:width_inches]}\" x #{phys[:height_inches]}\" " \
+               "(#{phys[:width_cm]} x #{phys[:height_cm]} cm)"
+        end
+
+        # Recommendations
+        recommendations = analysis[:recommendations]
+        if recommendations && !recommendations.empty?
+          puts "\n  #{colorize('Recommendations:', :bold)}"
+          recommendations.each do |rec|
+            priority_color = priority_color(rec[:priority])
+            puts "    [#{colorize(rec[:priority].to_s.upcase,
+                                  priority_color)}] #{rec[:message]}"
+          end
+        end
+      end
+
+      # Show mobile and Retina readiness
+      def show_mobile_readiness(file_analysis)
+        analysis = file_analysis.resolution_analysis
+        return unless analysis
+
+        puts "\n#{colorize('MOBILE & RETINA READINESS:', :bold)}"
+
+        retina = analysis[:retina]
+        web = analysis[:web]
+
+        # Overall readiness
+        is_ready = retina[:is_retina_ready] && web[:mobile_friendly]
+        status = if is_ready
+                   colorize("✓ READY",
+                            :green)
+                 else
+                   colorize("✗ NOT READY", :red)
+                 end
+        puts "  Status: #{status}"
+
+        # Specific checks
+        puts "\n  Checks:"
+        puts "    Retina Ready: #{format_check(retina[:is_retina_ready])}"
+        puts "    Mobile Friendly: #{format_check(web[:mobile_friendly])}"
+        puts "    Web Suitable: #{format_check(web[:suitable_for_web])}"
+
+        # Retina densities
+        puts "\n  Retina Densities:"
+        puts "    @1x: #{retina[:at_1x][:dimensions_pt]}"
+        puts "    @2x: #{retina[:at_2x][:dimensions_pt]}"
+        puts "    @3x: #{retina[:at_3x][:dimensions_pt]}"
+        puts "    Recommended: #{retina[:recommended_density]}"
+
+        # Screen coverage
+        puts "\n  Screen Coverage:"
+        web[:typical_screen_size].each do |screen, coverage|
+          puts "    #{screen}: #{coverage}"
+        end
+
+        # Load time
+        puts "\n  Load Time: #{web[:load_time_estimate]}"
+      end
+
+      # Helper methods for formatting
+
+      def format_check(passed)
+        passed ? colorize("✓", :green) : colorize("✗", :red)
+      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
+
+      def priority_color(priority)
+        case priority
+        when :high then :red
+        when :medium then :yellow
+        when :low then :blue
+        else :default
+        end
+      end
+
+      def colorize(text, color)
+        return text if options[:no_color]
+
+        codes = {
+          red: "\e[31m",
+          green: "\e[32m",
+          yellow: "\e[33m",
+          blue: "\e[34m",
+          bold: "\e[1m",
+          reset: "\e[0m",
+        }
+
+        "#{codes[color]}#{text}#{codes[:reset]}"
+      end
+
+      # Determine the exit code based on whether errors were found.
+      #
+      # @return [Integer] Exit code (0 for success, 1 for errors)
+      def exit_code
+        @errors_found ? 1 : 0
+      end
+    end
+  end
+end