png_conform 0.1.0

data/lib/png_conform/models/image_info.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+require "lutaml/model"
+
+module PngConform
+  module Models
+    # Domain model representing PNG image metadata
+    class ImageInfo < Lutaml::Model::Serializable
+      attribute :width, :integer
+      attribute :height, :integer
+      attribute :bit_depth, :integer
+      attribute :color_type, :string
+      attribute :interlaced, :boolean
+      attribute :animated, :boolean
+
+      # Color type constants for validation
+      COLOR_TYPES = {
+        0 => "grayscale",
+        2 => "truecolor",
+        3 => "palette",
+        4 => "grayscale+alpha",
+        6 => "truecolor+alpha",
+      }.freeze
+
+      # Convert color type code to human-readable string
+      def self.color_type_name(code)
+        COLOR_TYPES[code] || "unknown"
+      end
+
+      # Format as pngcheck summary (e.g., "32x32, 1-bit grayscale")
+      def summary
+        parts = []
+        parts << "#{width}x#{height}"
+        parts << "#{bit_depth}-bit #{color_type}"
+        parts << (interlaced ? "interlaced" : "non-interlaced")
+        parts << (animated ? "animated" : "static")
+        parts.join(", ")
+      end
+
+      # Convert to hash for serialization
+      def to_h
+        {
+          "width" => width,
+          "height" => height,
+          "bit_depth" => bit_depth,
+          "color_type" => color_type,
+          "interlaced" => interlaced,
+        }.compact
+      end
+    end
+  end
+end

data/lib/png_conform/models/validation_error.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module PngConform
+  module Models
+    # Domain model representing a validation error or warning
+    class ValidationError < Lutaml::Model::Serializable
+      attribute :severity, :string
+      attribute :message, :string
+      attribute :chunk_type, :string
+      attribute :chunk_offset, :integer
+      attribute :error_type, :string
+      attribute :expected, :string
+      attribute :actual, :string
+
+      # Severity levels
+      SEVERITY_ERROR = "error"
+      SEVERITY_WARNING = "warning"
+      SEVERITY_INFO = "info"
+
+      # Error types
+      ERROR_TYPE_SIGNATURE = "signature"
+      ERROR_TYPE_CRC = "crc"
+      ERROR_TYPE_CHUNK_ORDER = "chunk_order"
+      ERROR_TYPE_CHUNK_DATA = "chunk_data"
+      ERROR_TYPE_ZLIB = "zlib"
+      ERROR_TYPE_MISSING_CHUNK = "missing_chunk"
+      ERROR_TYPE_INVALID_VALUE = "invalid_value"
+      ERROR_TYPE_PROFILE = "profile"
+
+      # Create error-level validation error
+      def self.error(message, options = {})
+        new(
+          severity: SEVERITY_ERROR,
+          message: message,
+          chunk_type: options[:chunk_type],
+          chunk_offset: options[:chunk_offset],
+          error_type: options[:error_type],
+        )
+      end
+
+      # Create warning-level validation error
+      def self.warning(message, options = {})
+        new(
+          severity: SEVERITY_WARNING,
+          message: message,
+          chunk_type: options[:chunk_type],
+          chunk_offset: options[:chunk_offset],
+          error_type: options[:error_type],
+        )
+      end
+
+      # Create info-level validation error
+      def self.info(message, options = {})
+        new(
+          severity: SEVERITY_INFO,
+          message: message,
+          chunk_type: options[:chunk_type],
+          chunk_offset: options[:chunk_offset],
+          error_type: options[:error_type],
+        )
+      end
+
+      # Check if this is an error
+      def error?
+        severity == SEVERITY_ERROR
+      end
+
+      # Check if this is a warning
+      def warning?
+        severity == SEVERITY_WARNING
+      end
+
+      # Check if this is info
+      def info?
+        severity == SEVERITY_INFO
+      end
+
+      # Format for display
+      def to_s
+        parts = []
+        parts << "[#{severity.upcase}]"
+        parts << chunk_type if chunk_type
+        parts << format("at 0x%05x", chunk_offset) if chunk_offset
+        parts << message
+        parts.join(" ")
+      end
+    end
+  end
+end

data/lib/png_conform/models/validation_result.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+module PngConform
+  module Models
+    # Domain model representing validation results for a file
+    class ValidationResult < Lutaml::Model::Serializable
+      attribute :filename, :string
+      attribute :file_type, :string
+      attribute :file_size, :integer
+      attribute :valid, :boolean, default: -> { true }
+      attribute :chunks, Chunk, collection: true, default: -> { [] }
+      attribute :errors, ValidationError, collection: true, default: -> { [] }
+      attribute :compression_ratio, :float
+      attribute :crc_errors_count, :integer, default: -> { 0 }
+
+      # File types
+      FILE_TYPE_PNG = "PNG"
+      FILE_TYPE_MNG = "MNG"
+      FILE_TYPE_JNG = "JNG"
+      FILE_TYPE_UNKNOWN = "UNKNOWN"
+
+      # Add a chunk to the result
+      def add_chunk(chunk)
+        chunks << chunk
+      end
+
+      # Add an error to the result
+      def add_error(error)
+        errors << error
+        self.valid = false if error.error?
+      end
+
+      # Create error and add to result
+      def error(message, options = {})
+        add_error(ValidationError.error(message, options))
+      end
+
+      # Create warning and add to result
+      def warning(message, options = {})
+        add_error(ValidationError.warning(message, options))
+      end
+
+      # Create info and add to result
+      def info(message, options = {})
+        add_error(ValidationError.info(message, options))
+      end
+
+      # Check if validation passed
+      def valid?
+        valid
+      end
+
+      # Alias for filename (compatibility with reporters)
+      def file_path
+        filename
+      end
+
+      # Get only errors (not warnings or info)
+      def error_messages
+        errors.select(&:error?)
+      end
+
+      # Get only warnings
+      def warning_messages
+        errors.select(&:warning?)
+      end
+
+      # Get only info messages
+      def info_messages
+        errors.select(&:info?)
+      end
+
+      # Get error count
+      def error_count
+        error_messages.count
+      end
+
+      # Get warning count
+      def warning_count
+        warning_messages.count
+      end
+
+      # Get info count
+      def info_count
+        info_messages.count
+      end
+
+      # Get chunk count
+      def chunk_count
+        chunks.count
+      end
+
+      # Find chunks by type
+      def chunks_by_type(type)
+        chunks.select { |chunk| chunk.type == type }
+      end
+
+      # Check if file has specific chunk type
+      def has_chunk?(type)
+        chunks.any? { |chunk| chunk.type == type }
+      end
+
+      # Get IHDR chunk (PNG/JNG)
+      def ihdr_chunk
+        chunks_by_type("IHDR").first
+      end
+
+      # Get MHDR chunk (MNG)
+      def mhdr_chunk
+        chunks_by_type("MHDR").first
+      end
+
+      # Get JHDR chunk (JNG)
+      def jhdr_chunk
+        chunks_by_type("JHDR").first
+      end
+
+      # Summary for display
+      def summary
+        status = valid? ? "OK" : "ERRORS"
+        "#{status}: #{filename} (#{file_type}, #{file_size} bytes, " \
+          "#{chunk_count} chunks, #{error_count} errors, " \
+          "#{warning_count} warnings)"
+      end
+
+      # Error summary for output (pngcheck format)
+      def error_summary
+        parts = []
+        parts << "ERROR: #{filename}"
+        errors.each do |error|
+          parts << "  #{error.message}"
+        end
+        parts.join("\n")
+      end
+    end
+  end
+end

data/lib/png_conform/readers/full_load_reader.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+require_relative "../bindata/png_file"
+
+module PngConform
+  module Readers
+    # Full-file PNG reader
+    #
+    # This reader loads the entire PNG file into memory at once, providing
+    # fast random access to chunks but using more memory. Suitable for
+    # small to medium files or when you need to access chunks non-sequentially.
+    #
+    # @example Reading an entire PNG file
+    #   File.open("image.png", "rb") do |f|
+    #     reader = FullLoadReader.new(f)
+    #     png = reader.read
+    #
+    #     puts "Signature valid: #{png.valid_signature?}"
+    #     puts "Chunks: #{png.chunk_sequence.join(', ')}"
+    #     puts "Structurally valid: #{png.structurally_valid?}"
+    #   end
+    #
+    class FullLoadReader
+      attr_reader :io, :png
+
+      # 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)
+        if filepath_or_io.is_a?(String)
+          # File path provided
+          @filepath = filepath_or_io
+          @io = File.open(filepath_or_io, "rb")
+          @owns_io = true
+        else
+          # IO object provided
+          @io = filepath_or_io
+          @owns_io = false
+        end
+        @png = nil
+      end
+
+      # Read the entire PNG file structure
+      #
+      # @return [BinData::PngFile] the complete PNG file structure
+      def read
+        return @png if @png
+
+        @io.rewind
+        @png = BinData::PngFile.read(@io)
+      end
+
+      # Get PNG signature
+      #
+      # @return [String] 8-byte PNG signature
+      def signature
+        read unless @png
+        @png.signature.to_s
+      end
+
+      # Iterate over each chunk
+      #
+      # @yield [chunk] Each chunk in the file
+      def each_chunk(&block)
+        read unless @png
+        @png.chunks.each(&block)
+      end
+
+      # Get file size
+      #
+      # @return [Integer] File size in bytes
+      def file_size
+        if @filepath
+          File.size(@filepath)
+        elsif @io.respond_to?(:stat)
+          @io.stat.size
+        else
+          # Fallback: calculate from PNG structure
+          read unless @png
+          8 + @png.chunks.sum { |c| 12 + c.length }
+        end
+      end
+
+      # Close the IO if we own it
+      def close
+        @io.close if @owns_io && @io && !@io.closed?
+      end
+
+      # Read file from path and return PNG structure
+      #
+      # @param path [String] path to PNG file
+      # @return [BinData::PngFile] the PNG file structure
+      def self.read_file(path)
+        File.open(path, "rb") do |f|
+          new(f).read
+        end
+      end
+
+      # Read file from path and yield PNG structure to block
+      #
+      # @param path [String] path to PNG file
+      # @yield [png] The PNG file structure
+      # @yieldparam png [BinData::PngFile] the PNG structure
+      # @return [Object] result of the block
+      def self.open(path)
+        File.open(path, "rb") do |f|
+          png = new(f).read
+          yield png
+        end
+      end
+    end
+  end
+end

data/lib/png_conform/readers/streaming_reader.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+require_relative "../bindata/chunk_structure"
+
+module PngConform
+  module Readers
+    # Memory-efficient chunk-by-chunk PNG reader
+    #
+    # This reader processes PNG files one chunk at a time, making it suitable
+    # for large files where loading the entire file into memory would be
+    # impractical.
+    #
+    # @example Reading chunks one at a time
+    #   File.open("large.png", "rb") do |f|
+    #     reader = StreamingReader.new(f)
+    #
+    #     if reader.valid_signature?
+    #       reader.each_chunk do |chunk|
+    #         puts "#{chunk.type}: #{chunk.length} bytes"
+    #       end
+    #     end
+    #   end
+    #
+    class StreamingReader
+      # PNG signature (8 bytes)
+      PNG_SIGNATURE = [0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A]
+        .pack("C*")
+        .freeze
+
+      attr_reader :io, :signature
+
+      # Initialize a new streaming reader
+      #
+      # @param io [IO] IO object to read from (must be opened in binary mode)
+      def initialize(io)
+        @io = io
+        @signature = nil
+        @chunks_read = 0
+      end
+
+      # Read and validate the PNG signature
+      #
+      # This must be called before reading chunks.
+      #
+      # @return [Boolean] true if signature is valid
+      def read_signature
+        @signature = @io.read(8)
+        valid_signature?
+      end
+
+      # 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, nil] signature in hex format, or nil if not read
+      def signature_hex
+        return nil unless @signature
+
+        @signature.bytes.map { |b| format("%02x", b) }.join(" ")
+      end
+
+      # Read the next chunk from the stream
+      #
+      # @return [BinData::ChunkStructure, nil] the next chunk, or nil if EOF
+      def read_chunk
+        return nil if @io.eof?
+
+        chunk = BinData::ChunkStructure.read(@io)
+        @chunks_read += 1
+        chunk
+      rescue EOFError
+        nil
+      end
+
+      # Iterate over all chunks in the file
+      #
+      # @yield [chunk] Each chunk in the file
+      # @yieldparam chunk [BinData::ChunkStructure] the current chunk
+      # @return [Integer] number of chunks read
+      def each_chunk
+        return enum_for(:each_chunk) unless block_given?
+
+        while (chunk = read_chunk)
+          yield chunk
+          break if chunk.type == "IEND"
+        end
+
+        @chunks_read
+      end
+
+      # Read all chunks into an array
+      #
+      # Note: This defeats the purpose of streaming for large files.
+      # Use only when you need random access to chunks.
+      #
+      # @return [Array<BinData::ChunkStructure>] all chunks
+      def read_all_chunks
+        chunks = []
+        each_chunk { |chunk| chunks << chunk }
+        chunks
+      end
+
+      # Find the first chunk of a specific type
+      #
+      # @param type [String] chunk type to find
+      # @return [BinData::ChunkStructure, nil] the first matching chunk
+      def find_chunk(type)
+        each_chunk do |chunk|
+          return chunk if chunk.type == type
+        end
+        nil
+      end
+
+      # Collect all chunks of a specific type
+      #
+      # @param type [String] chunk type to find
+      # @return [Array<BinData::ChunkStructure>] all matching chunks
+      def find_chunks(type)
+        chunks = []
+        each_chunk do |chunk|
+          chunks << chunk if chunk.type == type
+        end
+        chunks
+      end
+
+      # Reset the reader to the beginning of the file
+      #
+      # @return [void]
+      def rewind
+        @io.rewind
+        @signature = nil
+        @chunks_read = 0
+      end
+
+      # Get the current position in the file
+      #
+      # @return [Integer] current byte position
+      def position
+        @io.pos
+      end
+
+      # Check if we've reached end of file
+      #
+      # @return [Boolean] true if at EOF
+      def eof?
+        @io.eof?
+      end
+
+      # Get statistics about the reading process
+      #
+      # @return [Hash] reading statistics
+      def stats
+        {
+          chunks_read: @chunks_read,
+          current_position: position,
+          eof: eof?,
+        }
+      end
+
+      # Read file from path using streaming reader
+      #
+      # @param path [String] path to PNG file
+      # @yield [reader] The streaming reader
+      # @yieldparam reader [StreamingReader] the reader instance
+      # @return [Object] result of the block
+      def self.open(path)
+        File.open(path, "rb") do |f|
+          reader = new(f)
+          reader.read_signature
+          yield reader
+        end
+      end
+    end
+  end
+end

data/lib/png_conform/reporters/base_reporter.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module PngConform
+  module Reporters
+    # Base class for all reporters
+    # Reporters consume FileAnalysis models and produce formatted output
+    class BaseReporter
+      attr_reader :output
+
+      def initialize(output = $stdout, colorize: true)
+        @output = output
+        @colorize = colorize
+      end
+
+      # Report a single file analysis
+      # Must be implemented by subclasses
+      def report(file_analysis)
+        raise NotImplementedError, "Subclasses must implement #report"
+      end
+
+      # Report multiple file analyses
+      def report_all(file_analyses)
+        file_analyses.each do |analysis|
+          report(analysis)
+        end
+      end
+
+      protected
+
+      # Write a line to output
+      def write_line(text = "")
+        output.puts(text)
+      end
+
+      # Write text without newline
+      def write(text)
+        output.print(text)
+      end
+
+      # Format with color (if supported)
+      def colorize(text, _color)
+        # Base implementation only colorizes if @colorize is true
+        # Override in ColorReporter for actual color support
+        text
+      end
+
+      # Check if colorization is enabled
+      def colorize?
+        @colorize
+      end
+    end
+  end
+end

data/lib/png_conform/reporters/color_reporter.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+require_relative "base_reporter"
+
+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
+      def initialize(wrapped_reporter)
+        super(wrapped_reporter.output, colorize: true)
+        @wrapped_reporter = wrapped_reporter
+      end
+
+      def report(file_analysis)
+        # Temporarily enable colorization
+        @colorize_enabled = true
+        wrapped_reporter.report(file_analysis)
+        @colorize_enabled = false
+      end
+
+      def report_all(file_analyses)
+        @colorize_enabled = true
+        wrapped_reporter.report_all(file_analyses)
+        @colorize_enabled = false
+      end
+
+      protected
+
+      # Override colorize to actually apply colors
+      def colorize(text, color)
+        return text unless @colorize_enabled
+        return text unless COLORS.key?(color)
+
+        "#{COLORS[color]}#{text}#{COLORS[:reset]}"
+      end
+
+      # Determine color based on validation status
+      def status_color(file_analysis)
+        file_analysis.valid? ? :green : :red
+      end
+
+      # Determine color based on chunk type
+      def chunk_color(chunk_type)
+        # Critical chunks in one color, ancillary in another
+        critical_chunks = %w[IHDR PLTE IDAT IEND]
+        critical_chunks.include?(chunk_type) ? :cyan : :blue
+      end
+    end
+  end
+end

data/lib/png_conform/reporters/json_reporter.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+require_relative "base_reporter"
+require "json"
+
+module PngConform
+  module Reporters
+    # JSON reporter - outputs complete file analysis in JSON format
+    # Proper Model → Formatter pattern
+    # Receives FileAnalysis model and formats it (no analysis done here)
+    class JsonReporter < BaseReporter
+      def report(file_analysis)
+        # Simple formatting - model knows how to serialize itself
+        write_line(JSON.pretty_generate(file_analysis.to_h))
+      end
+    end
+  end
+end