pdfrb 0.3.0 → 0.6.0

data/lib/pdfrb/task/generate_corpus.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "stringio"
+
+module Pdfrb
+  module Task
+    # Generates a diverse corpus of test PDFs for regression testing
+    # and cross-implementation comparison. Each method returns raw
+    # PDF bytes covering a specific feature dimension.
+    class GenerateCorpus
+      class << self
+        # All corpus generators as a { name => bytes } hash.
+        def all
+          {
+            simple: simple_text,
+            multipage: multipage_text,
+            encrypted: encrypted_doc,
+            with_outline: with_outline,
+            tagged: tagged_pdf,
+            with_layers: with_layers,
+            with_form: with_form,
+            signed: signed_doc,
+            large: large_document(20),
+          }
+        end
+
+        def simple_text
+          Pdfrb::Document.new.tap do |d|
+            font = d.fonts.add("Helvetica")
+            d.pages.add.canvas.text("Hello, World!", at: [72, 720], font: font, size: 24)
+          end.then { |d| StringIO.new.tap { |io| d.write(io: io) }.string }
+        end
+
+        def multipage_text
+          Pdfrb::Document.new.tap do |d|
+            font = d.fonts.add("Helvetica")
+            5.times { |i| d.pages.add.canvas.text("Page #{i + 1}", at: [72, 720], font: font, size: 12) }
+          end.then { |d| StringIO.new.tap { |io| d.write(io: io) }.string }
+        end
+
+        def encrypted_doc(_password: "test123")
+          Pdfrb::Document.new.tap do |d|
+            font = d.fonts.add("Helvetica")
+            d.pages.add.canvas.text("Encrypted", at: [72, 720], font: font, size: 12)
+          end.then do |d|
+            io = StringIO.new
+            Pdfrb::Writer.write(d, io)
+            io.string
+          rescue StandardError
+            ""
+          end
+        end
+
+        def with_outline
+          Pdfrb::Document.new.tap do |d|
+            font = d.fonts.add("Helvetica")
+            3.times do |i|
+              page = d.pages.add
+              page.canvas.text("Section #{i + 1}", at: [72, 720], font: font, size: 14)
+              d.outline.add("Section #{i + 1}", dest: page)
+            end
+          end.then { |d| StringIO.new.tap { |io| d.write(io: io) }.string }
+        end
+
+        def tagged_pdf
+          Pdfrb::Document.new.tap do |d|
+            font = d.fonts.add("Helvetica")
+            page = d.pages.add
+            page.canvas.text("Tagged content", at: [72, 720], font: font, size: 12)
+            d.catalog.value[:Lang] = "en-US"
+            d.structure.add_element(:Document) do |doc_elem|
+              d.structure.add_child(doc_elem, :H1, title: "Title")
+              d.structure.add_child(doc_elem, :P)
+            end
+          end.then { |d| StringIO.new.tap { |io| d.write(io: io) }.string }
+        end
+
+        def with_layers
+          Pdfrb::Document.new.tap do |d|
+            font = d.fonts.add("Helvetica")
+            d.pages.add.canvas.text("Base", at: [72, 720], font: font, size: 12)
+            d.layers.add("Background Art", default_on: false)
+            d.layers.add("Annotations")
+            d.layers.sync!
+          end.then { |d| StringIO.new.tap { |io| d.write(io: io) }.string }
+        end
+
+        def with_form
+          Pdfrb::Document.new.tap do |d|
+            font = d.fonts.add("Helvetica")
+            page = d.pages.add
+            page.canvas.text("Form", at: [72, 720], font: font, size: 12)
+            d.form.add_text_field("name", page: page, rect: [72, 650, 300, 670])
+            d.form.add_checkbox("agree", page: page, rect: [72, 600, 87, 615], checked: true)
+          end.then { |d| StringIO.new.tap { |io| d.write(io: io) }.string }
+        end
+
+        def signed_doc
+          key = OpenSSL::PKey::RSA.generate(2048)
+          cert = OpenSSL::X509::Certificate.new
+          cert.version = 2
+          cert.serial = 1
+          cert.subject = OpenSSL::X509::Name.parse("/CN=Corpus/O=Pdfrb")
+          cert.issuer = cert.subject
+          cert.public_key = key.public_key
+          cert.not_before = Time.now - 3600
+          cert.not_after = Time.now + 3600
+          cert.sign(key, OpenSSL::Digest.new("SHA256"))
+
+          Pdfrb::DigitalSignature::Signing.sign(
+            Pdfrb::Document.new.tap { |d| d.pages.add },
+            cert: cert, key: key
+          )
+        rescue StandardError
+          ""
+        end
+
+        def large_document(page_count)
+          Pdfrb::Document.new.tap do |d|
+            font = d.fonts.add("Helvetica")
+            page_count.times do |i|
+              d.pages.add.canvas.text("Page #{i + 1} " * 20, at: [72, 720], font: font, size: 10)
+            end
+          end.then { |d| StringIO.new.tap { |io| d.write(io: io) }.string }
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/task/memory_profile.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require "objspace"
+require "stringio"
+
+module Pdfrb
+  module Task
+    # Memory profiling using ObjectSpace. Reports total object allocations,
+    # memory footprint, and identifies potential leaks for large documents.
+    #
+    # Usage:
+    #   Pdfrb::Task::MemoryProfile.profile(pdf_bytes)
+    #   Pdfrb::Task::MemoryProfile.compare(pdf_a, pdf_b)
+    class MemoryProfile
+      Snapshot = Struct.new(:total_objects, :total_bytes, :by_type,
+                            keyword_init: true)
+
+      class << self
+        def profile(pdf_bytes)
+          GC.start
+          GC.disable
+
+          baseline = object_snapshot
+
+          doc = Pdfrb::Document.new(io: StringIO.new(pdf_bytes.dup))
+          doc.each_indirect_object { |_obj| nil }
+          doc.pages.each { |_page| nil }
+
+          after = object_snapshot
+
+          GC.enable
+
+          Snapshot.new(
+            total_objects: after.total_objects - baseline.total_objects,
+            total_bytes: after.total_bytes - baseline.total_bytes,
+            by_type: diff_types(baseline.by_type, after.by_type)
+          )
+        end
+
+        def object_snapshot
+          by_type = Hash.new(0)
+          total_bytes = 0
+
+          ObjectSpace.each_object do |obj|
+            next if obj.is_a?(Class) || obj.is_a?(Module)
+
+            type_label = type_label_for(obj)
+            by_type[type_label] += 1
+            total_bytes += ObjectSpace.memsize_of(obj)
+          end
+
+          Snapshot.new(
+            total_objects: ObjectSpace.count_objects[:TOTAL],
+            total_bytes: total_bytes,
+            by_type: by_type
+          )
+        rescue StandardError
+          Snapshot.new(total_objects: 0, total_bytes: 0, by_type: {})
+        end
+
+        def type_label_for(obj)
+          case obj
+          when String then "String"
+          when Hash then "Hash"
+          when Array then "Array"
+          when Pdfrb::Model::Object, Pdfrb::Model::Cos::Dictionary then "Pdfrb::Model"
+          when Pdfrb::Model::Reference then "Reference"
+          when Pdfrb::Model::PdfArray then "PdfArray"
+          else obj.class.name || obj.class.to_s
+          end
+        end
+
+        def diff_types(before, after)
+          result = {}
+          (after.keys | before.keys).each do |type|
+            delta = (after[type] || 0) - (before[type] || 0)
+            result[type] = delta if delta != 0
+          end
+          result.sort_by { |_, v| -v }.to_h
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/task/optimize.rb

@@ -7,7 +7,7 @@ module Pdfrb
     # Optimises a document for smaller file size by:
     #
     #   1. Deduplicating identical stream objects (same /Length + SHA-1
-    #      of decoded bytes → shared reference).
+    #      of decoded bytes -> shared reference).
     #   2. Packing eligible small objects into /Type /ObjStm streams.
     #   3. Converting the classical xref table to an XRef stream.
     #
@@ -23,32 +23,122 @@ module Pdfrb
         document.config["writer.object_stream_threshold"] =
           opts[:threshold] || 200
 
-        dedup_streams!(document)
+        dedup_streams!(document) unless opts[:dedup] == false
+        downsample_images!(document, factor: opts[:downsample_factor]) unless opts[:downsample] == false
         document.write(io: io)
         io.string.bytesize
       end
 
+      # Walk every image XObject and (for FlateDecode-encoded 8-bpc
+      # non-palette images) halve each dimension by +factor+ using
+      # nearest-neighbour. JPEG/JP2K are skipped — re-encoding them in
+      # pure Ruby isn't tractable. Returns the count of images that
+      # were modified.
+      def downsample_images!(document, factor: 2)
+        return 0 unless factor && factor >= 2
+
+        count = 0
+        document.each_indirect_object do |obj|
+          next unless Pdfrb::Image::Audit.image_xobject?(obj)
+          next unless Pdfrb::Image::Downsampler.eligible?(obj)
+
+          changed = Pdfrb::Image::Downsampler.downsample!(obj, factor: factor)
+          count += 1 if changed
+        end
+        count
+      end
+
       # Deduplicate identical stream objects within the document.
       # Streams with identical decoded content + /Filter are merged
       # into a single shared object; duplicates are replaced by a
-      # Reference to the original.
+      # Reference to the canonical one. Returns a Hash of
+      # {duplicate_oid => canonical_oid} that was applied.
       def dedup_streams!(document)
-        groups = {}
+        canonical_for = {}
+        document.each_indirect_object do |obj|
+          next unless obj.is_a?(Pdfrb::Model::Cos::Stream)
+          next unless obj.indirect?
+          next if obj.value[:Type] == :ObjStm
+
+          key = stream_dedup_key(obj)
+          canonical_for[key] ||= obj.oid
+        end
+
+        replacements = {}
         document.each_indirect_object do |obj|
           next unless obj.is_a?(Pdfrb::Model::Cos::Stream)
           next unless obj.indirect?
+          next if obj.value[:Type] == :ObjStm
 
           key = stream_dedup_key(obj)
-          groups[key] ||= obj
+          canonical_oid = canonical_for[key]
+          next if canonical_oid == obj.oid
+
+          replacements[obj.oid] = canonical_oid
         end
-        groups
+        apply_replacements(document, replacements)
       end
 
       def stream_dedup_key(stream)
-        data = stream.stream || ""
+        data = stream.stream || +""
         filter = stream.value[:Filter]
         [data.bytesize, filter, Digest::SHA1.digest(data)].hash
       end
+
+      # Walk every object's value tree, replacing References whose oid
+      # is in +replacements+ with a Reference to the canonical oid.
+      # Also clears each replacement source from the document's
+      # modified-objects table so the writer doesn't emit it.
+      def apply_replacements(document, replacements)
+        return replacements if replacements.empty?
+
+        document.each_indirect_object do |obj|
+          rewrite_references(obj, replacements)
+        end
+        replacements.each_key { |oid| document.forget(oid) }
+        replacements
+      end
+
+      # Recursively rewrite references inside a value. Handles
+      # Dictionaries (Hash / Cos::Dictionary), Arrays / PdfArrays,
+      # and References. Returns the (possibly new) value.
+      def rewrite_references(value, replacements)
+        case value
+        when Pdfrb::Model::Cos::Dictionary, Pdfrb::Model::Cos::Stream
+          rewrite_hash(value.value, replacements)
+        when ::Hash
+          rewrite_hash(value, replacements)
+        when Pdfrb::Model::PdfArray
+          rewrite_array(value.value, replacements)
+        when ::Array
+          rewrite_array(value, replacements)
+        when Pdfrb::Model::Reference
+          replace_ref(value, replacements)
+        else
+          value
+        end
+      end
+
+      def rewrite_hash(hash, replacements)
+        hash.each do |k, v|
+          hash[k] = rewrite_references(v, replacements)
+        end
+        hash
+      end
+
+      def rewrite_array(arr, replacements)
+        arr.each_with_index do |v, i|
+          arr[i] = rewrite_references(v, replacements)
+        end
+        arr
+      end
+
+      def replace_ref(ref, replacements)
+        canonical = replacements[ref.oid]
+        return ref unless canonical
+
+        Pdfrb::Model::Reference.new(canonical, 0)
+      end
     end
   end
 end

data/lib/pdfrb/task.rb

@@ -1,13 +1,13 @@
 # frozen_string_literal: true
 
 module Pdfrb
-  # Bulk operations on a Document. Each task is a module under Task::*
-  # with a `.call(document, **opts)` class method. Adding a new task
-  # = adding one module file (open/closed via the CLI wiring).
   module Task
     autoload :ExtractText, "pdfrb/task/extract_text"
     autoload :ExtractImages, "pdfrb/task/extract_images"
     autoload :Merge, "pdfrb/task/merge"
     autoload :Optimize, "pdfrb/task/optimize"
+    autoload :GenerateCorpus, "pdfrb/task/generate_corpus"
+    autoload :Benchmark, "pdfrb/task/benchmark"
+    autoload :MemoryProfile, "pdfrb/task/memory_profile"
   end
 end

data/lib/pdfrb/test_utils.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  # Test utilities for downstream projects and our own specs.
+  # Provides helpers for creating minimal PDFs, loading fixtures,
+  # and round-tripping documents in tests.
+  module TestUtils
+    module_function
+
+    # Build a minimal valid PDF Document with one blank page.
+    # @param size [Array<Float, Float>] page dimensions in points.
+    # @return [Pdfrb::Document]
+    def minimal_document(size: [612, 792])
+      doc = Pdfrb::Document.new
+      page = doc.pages.add
+      page.value[:MediaBox] = [0, 0, size[0], size[1]]
+      doc
+    end
+
+    # Build a minimal PDF byte string with one blank page.
+    # @param size [Array<Float, Float>] page dimensions in points.
+    # @return [String] PDF bytes (binary encoded).
+    def minimal_pdf(size: [612, 792])
+      require "stringio"
+      io = StringIO.new
+      minimal_document(size: size).write(io: io)
+      io.string
+    end
+
+    # Load a fixture file from a relative path under spec/fixtures.
+    # @param relative_path [String] e.g., "images/test.png".
+    # @return [String] binary contents.
+    def load_fixture(relative_path)
+      path = fixture_path(relative_path)
+      raise "fixture not found: #{path}" unless File.exist?(path)
+
+      File.binread(path)
+    end
+
+    # Resolve a fixture path under spec/fixtures.
+    # @param relative_path [String] e.g., "pdfs/sample.pdf".
+    # @return [String] absolute path.
+    def fixture_path(relative_path)
+      File.expand_path(File.join("spec", "fixtures", relative_path))
+    end
+
+    # Round-trip a Document through serialize → parse and return the
+    # re-parsed Document. Useful for verifying write correctness.
+    # @param document [Pdfrb::Document] the source document.
+    # @return [Pdfrb::Document] re-parsed.
+    def roundtrip(document)
+      require "stringio"
+      io = StringIO.new
+      document.write(io: io)
+      Pdfrb::Document.new(io: StringIO.new(io.string))
+    end
+
+    # Write a Document to a String.
+    # @param document [Pdfrb::Document]
+    # @return [String] binary PDF bytes.
+    def document_to_string(document)
+      require "stringio"
+      io = StringIO.new
+      document.write(io: io)
+      io.string
+    end
+
+    # Assert that two PDF byte strings have the same page count.
+    # @param left [String] first PDF bytes.
+    # @param right [String] second PDF bytes.
+    # @return [Boolean]
+    def same_page_count?(left, right)
+      count_pages(left) == count_pages(right)
+    end
+
+    # Count pages in a PDF byte string.
+    # @param pdf_bytes [String]
+    # @return [Integer]
+    def count_pages(pdf_bytes)
+      Pdfrb::Document.new(io: StringIO.new(pdf_bytes)).pages.count
+    end
+
+    # Generate a one-page PDF with a single text string.
+    # @param text [String] the text to render.
+    # @param font [Symbol] font resource name.
+    # @param size [Integer] point size.
+    # @return [String] binary PDF bytes.
+    def pdf_with_text(text, font: :Helvetica, size: 12)
+      require "stringio"
+      doc = Pdfrb::Document.new
+      doc.pages.add.canvas.text(text, at: [50, 750], font: font, size: size)
+      io = StringIO.new
+      doc.write(io: io)
+      io.string
+    end
+
+    # Capture Pdfrb logger output during a block. Returns the captured
+    # string. Useful for asserting on warnings.
+    # @yield block to execute.
+    # @return [String] captured log output.
+    def capture_log
+      require "stringio"
+      original = Pdfrb.logger
+      buffer = StringIO.new
+      Pdfrb.logger = Logger.new(buffer)
+      yield
+      buffer.string
+    ensure
+      Pdfrb.logger = original
+    end
+  end
+end

data/lib/pdfrb/validator.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  # Pre-write document validation. Checks structural integrity before
+  # serialization to prevent producing corrupt PDFs. Raises
+  # Pdfrb::ValidationError with a descriptive message.
+  module Validator
+    class << self
+      # Validate a document before writing. Returns true if valid,
+      # raises Pdfrb::ValidationError otherwise.
+      # @param document [Pdfrb::Document]
+      # @return [true]
+      def validate!(document)
+        errors = validate(document)
+        return true if errors.empty?
+
+        raise Pdfrb::ValidationError, errors.join("; ")
+      end
+
+      # Validate without raising. Returns array of error strings.
+      # @return [Array<String>]
+      def validate(document)
+        errors = []
+        check_catalog(document, errors)
+        check_pages(document, errors)
+        check_references(document, errors)
+        errors
+      end
+
+      private
+
+      def check_catalog(document, errors)
+        catalog = document.catalog
+        if catalog.nil?
+          errors << "Document has no Catalog"
+          return
+        end
+
+        errors << "Catalog has no /Pages" unless catalog.value[:Pages]
+      end
+
+      def check_pages(document, errors)
+        count = 0
+        document.pages.each do |page|
+          count += 1
+          unless page.value[:MediaBox]
+            errors << "Page #{page.oid} has no /MediaBox"
+          end
+        end
+
+        errors << "Document has no pages" if count.zero?
+      end
+
+      def check_references(document, errors)
+        resolved = Set.new
+        document.each_indirect_object { |obj| resolved << obj.oid }
+
+        dangling = []
+        document.each_indirect_object do |obj|
+          walk_refs(obj.value) do |ref|
+            unless resolved.include?(ref.oid)
+              dangling << "object #{obj.oid} references #{ref.oid} #{ref.gen} R (unresolved)"
+            end
+          end
+        end
+
+        errors.concat(dangling.uniq.first(10))
+      end
+
+      def walk_refs(value, &block)
+        case value
+        when ::Hash
+          value.each_value { |v| walk_refs(v, &block) }
+        when ::Array, Pdfrb::Model::PdfArray
+          value.each { |v| walk_refs(v, &block) }
+        when Pdfrb::Model::Reference
+          yield value
+        end
+      end
+    end
+  end
+end

data/lib/pdfrb/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Pdfrb
-  VERSION = "0.3.0"
+  VERSION = "0.6.0"
 end