pdfrb 0.3.0 → 0.6.0

data/lib/pdfrb/color/color_space.rb

@@ -0,0 +1,259 @@
+# frozen_string_literal: true
+
+# rubocop:disable Lint/MissingSuper
+module Pdfrb
+  module Color
+    # Color space value objects (ISO 32000-2 §8.6). Each color space
+    # knows how to serialize to its PDF representation (a name for
+    # device spaces, an array for CIE-based and special spaces).
+    #
+    # Hierarchy:
+    #   Base
+    #     Device (DeviceGray, DeviceRGB, DeviceCMYK)
+    #     CIEBased (CalGray, CalRGB, Lab, ICCBased)
+    #     Special (Indexed, Separation, DeviceN, Pattern)
+    #
+    # OCP: new color space = subclass + register_as.
+    class ColorSpace
+      class << self
+        def registry
+          @registry ||= {}
+        end
+
+        def register(name, klass)
+          registry[name.to_sym] = klass
+        end
+
+        def [](name)
+          registry[name.to_sym]
+        end
+
+        def names
+          registry.keys
+        end
+
+        # Subclass hook: the PDF name or array-head symbol.
+        def pdf_name
+          raise NotImplementedError
+        end
+
+        # Register this class under its pdf_name.
+        def register_as(name = pdf_name)
+          ColorSpace.register(name, self)
+          self
+        end
+      end
+    end
+
+    # Device color spaces — simple names, no parameters.
+    class DeviceColorSpace < ColorSpace
+      def to_pdf
+        self.class.pdf_name
+      end
+    end
+
+    class DeviceGray < DeviceColorSpace
+      class << self
+        def pdf_name; :DeviceGray; end
+      end
+      register_as
+    end
+
+    class DeviceRGB < DeviceColorSpace
+      class << self
+        def pdf_name; :DeviceRGB; end
+      end
+      register_as
+    end
+
+    class DeviceCMYK < DeviceColorSpace
+      class << self
+        def pdf_name; :DeviceCMYK; end
+      end
+      register_as
+    end
+
+    # CIE-based color spaces — arrays with calibration parameters.
+    class CIEBasedColorSpace < ColorSpace
+      def to_pdf
+        Pdfrb::Model::PdfArray.new([self.class.pdf_name, parameters_array].compact.flatten)
+      end
+
+      def parameters_array
+        []
+      end
+    end
+
+    class CalGray < CIEBasedColorSpace
+      attr_reader :white_point, :black_point, :gamma
+
+      def initialize(white_point:, black_point: nil, gamma: nil)
+        @white_point = white_point
+        @black_point = black_point
+        @gamma = gamma
+      end
+
+      class << self
+        def pdf_name; :CalGray; end
+      end
+
+      def parameters_array
+        dict = { WhitePoint: Pdfrb::Model::PdfArray.new(@white_point) }
+        dict[:BlackPoint] = Pdfrb::Model::PdfArray.new(@black_point) if @black_point
+        dict[:Gamma] = @gamma if @gamma
+        dict
+      end
+      register_as
+    end
+
+    class CalRGB < CIEBasedColorSpace
+      attr_reader :white_point, :gamma, :matrix, :black_point
+
+      def initialize(white_point:, gamma: nil, matrix: nil, black_point: nil)
+        @white_point = white_point
+        @gamma = gamma
+        @matrix = matrix
+        @black_point = black_point
+      end
+
+      class << self
+        def pdf_name; :CalRGB; end
+      end
+
+      def parameters_array
+        dict = { WhitePoint: Pdfrb::Model::PdfArray.new(@white_point) }
+        dict[:Gamma] = Pdfrb::Model::PdfArray.new(@gamma) if @gamma
+        dict[:Matrix] = Pdfrb::Model::PdfArray.new(@matrix) if @matrix
+        dict[:BlackPoint] = Pdfrb::Model::PdfArray.new(@black_point) if @black_point
+        dict
+      end
+      register_as
+    end
+
+    class Lab < CIEBasedColorSpace
+      attr_reader :white_point, :black_point, :range
+
+      def initialize(white_point:, black_point: nil, range: nil)
+        @white_point = white_point
+        @black_point = black_point
+        @range = range
+      end
+
+      class << self
+        def pdf_name; :Lab; end
+      end
+
+      def parameters_array
+        dict = { WhitePoint: Pdfrb::Model::PdfArray.new(@white_point) }
+        dict[:BlackPoint] = Pdfrb::Model::PdfArray.new(@black_point) if @black_point
+        dict[:Range] = Pdfrb::Model::PdfArray.new(@range) if @range
+        dict
+      end
+      register_as
+    end
+
+    # ICCBased is special — references an ICC profile stream.
+    # Delegates to Pdfrb::Color::ICCProfile for stream creation.
+    class ICCBased < CIEBasedColorSpace
+      attr_reader :icc_stream_ref
+
+      def initialize(icc_stream_ref)
+        @icc_stream_ref = icc_stream_ref
+      end
+
+      class << self
+        def pdf_name; :ICCBased; end
+      end
+
+      def to_pdf
+        Pdfrb::Model::PdfArray.new([:ICCBased, @icc_stream_ref])
+      end
+      register_as
+    end
+
+    # Indexed color space — maps small integer codes to colors in a base space.
+    class Indexed < ColorSpace
+      attr_reader :base, :hival, :lookup
+
+      def initialize(base:, hival:, lookup:)
+        @base = base
+        @hival = hival
+        @lookup = lookup
+      end
+
+      class << self
+        def pdf_name; :Indexed; end
+      end
+
+      def to_pdf
+        Pdfrb::Model::PdfArray.new([:Indexed, @base, @hival, @lookup])
+      end
+      register_as
+    end
+
+    # Separation color space — a single named ink (e.g. "PANTONE 185 C").
+    class Separation < ColorSpace
+      attr_reader :name, :alternate, :tint_transform
+
+      def initialize(name:, alternate:, tint_transform:)
+        @name = name
+        @alternate = alternate
+        @tint_transform = tint_transform
+      end
+
+      class << self
+        def pdf_name; :Separation; end
+      end
+
+      def to_pdf
+        Pdfrb::Model::PdfArray.new([:Separation, @name, @alternate, @tint_transform])
+      end
+      register_as
+    end
+
+    # DeviceN color space — multiple named inks.
+    class DeviceN < ColorSpace
+      attr_reader :names, :alternate, :tint_transform
+
+      def initialize(names:, alternate:, tint_transform:)
+        @names = names
+        @alternate = alternate
+        @tint_transform = tint_transform
+      end
+
+      class << self
+        def pdf_name; :DeviceN; end
+      end
+
+      def to_pdf
+        Pdfrb::Model::PdfArray.new([
+                                     :DeviceN,
+                                     Pdfrb::Model::PdfArray.new(@names),
+                                     @alternate,
+                                     @tint_transform,
+                                   ])
+      end
+      register_as
+    end
+
+    # Pattern color space — for tiling and shading patterns.
+    class Pattern < ColorSpace
+      attr_reader :base
+
+      def initialize(base: nil)
+        @base = base
+      end
+
+      class << self
+        def pdf_name; :Pattern; end
+      end
+
+      def to_pdf
+        @base ? Pdfrb::Model::PdfArray.new([:Pattern, @base]) : :Pattern
+      end
+      register_as
+    end
+  end
+end
+
+# rubocop:enable Lint/MissingSuper

data/lib/pdfrb/color/icc_profile.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Color
+    # ICC profile stream model. An ICCBased color space is a
+    # [/ICCBased <stream-ref>] array where the stream carries the
+    # raw ICC profile bytes and the dictionary declares /N (number
+    # of components), /Alternate (fallback space), and /Range.
+    #
+    # This class parses the ICC header to extract metadata (version,
+    # device class, color space, component count) and builds the
+    # PDF stream dictionary.
+    #
+    # ICC spec: ISO 15076-1 / ICC.1:2010. PDF integration: ISO 32000-2 §8.6.5.5.
+    class ICCProfile
+      HEADER_SIZE = 128
+      SIGNATURE_OFFSET = 36
+
+      attr_reader :raw_data, :version, :device_class, :color_space,
+                  :component_count, :alternate
+
+      def initialize(raw_data, alternate: nil)
+        @raw_data = raw_data.b
+        parse_header
+        @alternate = alternate || derive_alternate
+      end
+
+      def self.read(path)
+        new(File.binread(path))
+      end
+
+      def pdf_color_space_array
+        [:ICCBased, :__icc_stream_ref__]
+      end
+
+      def stream_dictionary_fields
+        {
+          N: @component_count,
+          Alternate: @alternate,
+        }.freeze
+      end
+
+      def valid?
+        @raw_data.bytesize >= HEADER_SIZE && signature_valid?
+      end
+
+      private
+
+      def parse_header
+        return unless @raw_data.bytesize >= HEADER_SIZE
+
+        major = @raw_data.getbyte(8)
+        minor_bugfix = @raw_data.getbyte(9)
+        @version = format("%d.%d.%d", major, (minor_bugfix >> 4) & 0x0F, minor_bugfix & 0x0F)
+        @device_class = read_str(12, 4)
+        @color_space = read_str(16, 4)
+        @component_count = component_count_for(@color_space)
+      end
+
+      def signature_valid?
+        read_str(SIGNATURE_OFFSET, 4) == "acsp"
+      end
+
+      def derive_alternate
+        case @color_space
+        when "CMYK" then :DeviceCMYK
+        when "GRAY" then :DeviceGray
+        when "LAB " then :Lab
+        else :DeviceRGB # RGB and unknown fall back to DeviceRGB
+        end
+      end
+
+      def component_count_for(cs)
+        case cs
+        when "CMYK" then 4
+        when "GRAY" then 1
+        else 3 # RGB, LAB, and unknown all use 3 components
+        end
+      end
+
+      def read_u32(offset)
+        @raw_data.byteslice(offset, 4)&.unpack1("N")
+      end
+
+      def read_str(offset, len)
+        @raw_data.byteslice(offset, len)&.force_encoding(Encoding::US_ASCII) || ""
+      end
+    end
+  end
+end

data/lib/pdfrb/color.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  # Color spaces and color management. Provides domain types for
+  # device color spaces (DeviceGray/RGB/CMYK), CIE-based spaces
+  # (CalGray, CalRGB, Lab, ICCBased), and special spaces (Indexed,
+  # Separation, DeviceN, Pattern).
+  module Color
+    autoload :ICCProfile, "pdfrb/color/icc_profile"
+    autoload :ColorSpace, "pdfrb/color/color_space"
+  end
+end

data/lib/pdfrb/compare/comparator.rb

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Compare
+    # Compares two Pdfrb::Documents at the structural level.
+    # Walks pages, extracts text, inventories fonts/images,
+    # inspects outlines and metadata. Produces a Report.
+    class Comparator
+      def compare(left, right)
+        Report.new(
+          page_count_delta: page_count_delta(left, right),
+          per_page_text_diffs: per_page_text_diffs(left, right),
+          font_diff: font_diff(left, right),
+          image_count_delta: image_count_delta(left, right),
+          outline_diff: outline_diff(left, right),
+          metadata_diff: metadata_diff(left, right),
+          structural_diffs: structural_diffs(left, right)
+        )
+      end
+
+      private
+
+      def page_count_delta(left, right)
+        right.pages.count - left.pages.count
+      end
+
+      def per_page_text_diffs(left, right)
+        left_text = extract_text_per_page(left)
+        right_text = extract_text_per_page(right)
+
+        max = [left_text.length, right_text.length].max
+        (0...max).filter_map do |i|
+          lt = left_text[i] || ""
+          rt = right_text[i] || ""
+          sim = text_similarity(lt, rt)
+          next nil if sim >= 1.0 && lt == rt
+
+          {
+            page: i,
+            similarity: sim,
+            left_length: lt.length,
+            right_length: rt.length,
+            left_missing: chars_only_in(rt, lt),
+            right_missing: chars_only_in(lt, rt),
+          }
+        end
+      end
+
+      def extract_text_per_page(doc)
+        Pdfrb::Task::ExtractText.call(doc)
+      rescue StandardError
+        []
+      end
+
+      def text_similarity(a, b)
+        return 1.0 if a == b
+        return 0.0 if a.empty? || b.empty?
+
+        max_len = [a.length, b.length].max
+        lev = levenshtein(a, b)
+        1.0 - (lev.to_f / max_len)
+      end
+
+      def levenshtein(a, b)
+        m = a.length
+        n = b.length
+        return n if m.zero?
+        return m if n.zero?
+
+        d = Array.new(m + 1) { |i| [i] + Array.new(n, 0) }
+        d[0] = (0..n).to_a
+
+        (1..m).each do |i|
+          (1..n).each do |j|
+            cost = a[i - 1] == b[j - 1] ? 0 : 1
+            d[i][j] = [d[i - 1][j] + 1, d[i][j - 1] + 1, d[i - 1][j - 1] + cost].min
+          end
+        end
+        d[m][n]
+      end
+
+      def chars_only_in(a, b)
+        (a.chars.to_a - b.chars.to_a).uniq.first(20).join
+      end
+
+      def font_diff(left, right)
+        left_fonts = inventory_fonts(left)
+        right_fonts = inventory_fonts(right)
+
+        {
+          added: (right_fonts - left_fonts).sort,
+          removed: (left_fonts - right_fonts).sort,
+          common: (left_fonts & right_fonts).sort,
+        }
+      end
+
+      def inventory_fonts(doc)
+        fonts = Set.new
+        doc.each_indirect_object do |obj|
+          next unless obj.is_a?(Pdfrb::Model::Cos::Dictionary)
+          next unless obj[:Type] == :Font
+
+          name = obj[:BaseFont] || obj[:Name] || "Unknown"
+          subtype = obj[:Subtype] || "Unknown"
+          fonts << "#{subtype}:#{name}"
+        end
+        fonts.to_a
+      rescue StandardError
+        []
+      end
+
+      def image_count_delta(left, right)
+        right_count = count_images(right)
+        left_count = count_images(left)
+        right_count - left_count
+      end
+
+      def count_images(doc)
+        count = 0
+        doc.each_indirect_object do |obj|
+          next unless obj.is_a?(Pdfrb::Model::Cos::Stream)
+          next unless obj[:Subtype] == :Image
+
+          count += 1
+        end
+        count
+      rescue StandardError
+        0
+      end
+
+      def outline_diff(left, right)
+        left_titles = outline_titles(left)
+        right_titles = outline_titles(right)
+
+        {
+          added: (right_titles - left_titles),
+          removed: (left_titles - right_titles),
+          common: (left_titles & right_titles),
+        }
+      end
+
+      def outline_titles(doc)
+        titles = Set.new
+        outlines_ref = doc.catalog&.value&.dig(:Outlines)
+        return titles.to_a unless outlines_ref
+
+        outlines = doc.object(outlines_ref)
+        return titles.to_a unless outlines
+
+        walk_outline(outlines, doc) { |title| titles << title }
+        titles.to_a
+      rescue StandardError
+        []
+      end
+
+      def walk_outline(outlines, doc, &)
+        current = outlines[:First]
+        while current
+          entry = doc.object(current)
+          break unless entry
+
+          title = entry[:Title]
+          yield(title.to_s) if title
+
+          if entry[:First]
+            child = doc.object(entry[:First])
+            walk_outline(child, doc, &) if child
+          end
+
+          current = entry[:Next]
+        end
+      end
+
+      def metadata_diff(left, right)
+        left_info = extract_info(left)
+        right_info = extract_info(right)
+
+        diff = {}
+        (left_info.keys | right_info.keys).each do |key|
+          lv = left_info[key]
+          rv = right_info[key]
+          next if lv == rv
+
+          diff[key] = { left: lv, right: rv }
+        end
+        diff
+      end
+
+      def extract_info(doc)
+        trailer = doc.trailer || {}
+        info_ref = trailer[:Info]
+        return {} unless info_ref
+
+        info = doc.object(info_ref)
+        return {} unless info
+
+        result = {}
+        info.value.each do |k, v|
+          next if k == :Type
+
+          result[k] = v.to_s
+        end
+        result
+      rescue StandardError
+        {}
+      end
+
+      def structural_diffs(left, right)
+        diffs = []
+
+        lc = left.catalog
+        rc = right.catalog
+        if lc && rc
+          left_keys = lc.value.keys.to_set
+          right_keys = rc.value.keys.to_set
+
+          added = right_keys - left_keys
+          removed = left_keys - right_keys
+          unless added.empty? && removed.empty?
+            diffs << {
+              location: "catalog",
+              keys_added: added.to_a.sort,
+              keys_removed: removed.to_a.sort,
+            }
+          end
+        end
+
+        lt = left.trailer || {}
+        rt = right.trailer || {}
+        left_tkeys = lt.keys.to_set - [:Size, :Root, :Prev]
+        right_tkeys = rt.keys.to_set - [:Size, :Root, :Prev]
+        unless (left_tkeys - right_tkeys).empty? && (right_tkeys - left_tkeys).empty?
+          diffs << {
+            location: "trailer",
+            keys_added: (right_tkeys - left_tkeys).to_a.sort,
+            keys_removed: (left_tkeys - right_tkeys).to_a.sort,
+          }
+        end
+
+        diffs
+      end
+    end
+  end
+end

data/lib/pdfrb/compare/report.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  module Compare
+    # Result of comparing two PDFs. Immutable value object.
+    class Report
+      attr_reader :page_count_delta, :per_page_text_diffs,
+                  :font_diff, :image_count_delta,
+                  :outline_diff, :metadata_diff, :structural_diffs
+
+      def initialize(page_count_delta:, per_page_text_diffs:, font_diff:,
+                     image_count_delta:, outline_diff:, metadata_diff:,
+                     structural_diffs:)
+        @page_count_delta = page_count_delta
+        @per_page_text_diffs = per_page_text_diffs.freeze
+        @font_diff = font_diff.freeze
+        @image_count_delta = image_count_delta
+        @outline_diff = outline_diff.freeze
+        @metadata_diff = metadata_diff.freeze
+        @structural_diffs = structural_diffs.freeze
+        freeze
+      end
+
+      def equivalent?
+        return false unless @page_count_delta.zero?
+        return false unless @per_page_text_diffs.empty?
+        return false unless @font_diff[:added].empty? && @font_diff[:removed].empty?
+        return false unless @image_count_delta.zero?
+        return false unless @structural_diffs.empty?
+
+        true
+      end
+
+      def similarity
+        total_checks = 0
+        passing = 0
+
+        total_checks += 1
+        passing += 1 if @page_count_delta.zero?
+
+        total_checks += @per_page_text_diffs.length + 1
+        passing += @per_page_text_diffs.count { |d| d[:similarity] > 0.95 } + 1
+
+        total_checks += 1
+        passing += 1 if @font_diff[:added].empty? && @font_diff[:removed].empty?
+
+        total_checks += 1
+        passing += 1 if @image_count_delta.zero?
+
+        total_checks + 1
+        passing + (@structural_diffs.empty? ? 1 : 0)
+        (passing.to_f / (total_checks + 1)).round(4)
+      end
+
+      def to_h
+        {
+          equivalent: equivalent?,
+          similarity: similarity,
+          page_count_delta: @page_count_delta,
+          per_page_text_diffs: @per_page_text_diffs,
+          font_diff: @font_diff,
+          image_count_delta: @image_count_delta,
+          outline_diff: @outline_diff,
+          metadata_diff: @metadata_diff,
+          structural_diffs: @structural_diffs,
+        }
+      end
+
+      def summary
+        status = equivalent? ? "EQUIVALENT" : "DIFFERENT"
+        sim = (similarity * 100).round(1)
+        "#{status} (#{sim}% similarity, page_delta=#{@page_count_delta}, " \
+          "text_diffs=#{@per_page_text_diffs.length}, " \
+          "font_changes=#{@font_diff[:added].length + @font_diff[:removed].length})"
+      end
+    end
+  end
+end