pdfrb 0.2.1 → 0.6.0

data/lib/pdfrb/compare.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  # Semantic PDF comparison. Compares two PDFs at the structural level:
+  # page count, per-page extracted text, font inventory, image count,
+  # outline structure, and metadata. Returns a structured report.
+  #
+  # Designed for regression testing: "did our render change from
+  # yesterday's reference?" Not a pixel diff — that's a separate
+  # concern (rasterize + image compare).
+  module Compare
+    autoload :Report, "pdfrb/compare/report"
+    autoload :Comparator, "pdfrb/compare/comparator"
+
+    module_function
+
+    # Compare two PDFs. Accepts bytes, IO, or Document objects.
+    #
+    # @param left [String, IO, Pdfrb::Document]
+    # @param right [String, IO, Pdfrb::Document]
+    # @return [Pdfrb::Compare::Report]
+    def compare(left, right)
+      left_doc = to_document(left)
+      right_doc = to_document(right)
+      Comparator.new.compare(left_doc, right_doc)
+    end
+
+    # Convenience: returns true if the two PDFs are equivalent.
+    def equivalent?(left, right)
+      compare(left, right).equivalent?
+    end
+
+    def to_document(input)
+      case input
+      when Pdfrb::Document then input
+      when ::String then Pdfrb::Document.new(io: StringIO.new(input))
+      when IO, StringIO then Pdfrb::Document.new(io: input)
+      else raise ArgumentError, "expected String, IO, or Document"
+      end
+    end
+  end
+end

data/lib/pdfrb/composer.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+module Pdfrb
+  # High-level document composition API. Wraps a +Document+ and a
+  # +Layout::BoxFitter+, exposing a DSL for adding text, images, and
+  # boxes with automatic page flow.
+  #
+  # Usage:
+  #   Pdfrb::Composer.new("out.pdf") do |c|
+  #     c.style(:heading, font_size: 24)
+  #     c.text("Hello world", style: :heading)
+  #     c.image("/path/to/logo.png", width: 200)
+  #     c.text("Body text flows naturally.")
+  #   end
+  class Composer
+    DEFAULT_PAGE_STYLE = :default
+
+    attr_reader :document, :page_styles, :current_page, :current_style_name
+
+    def initialize(output = nil, page_size: :A4, page_orientation: :portrait,
+                   margin: 36, skip_page_creation: false)
+      @document = Pdfrb::Document.new
+      @page_styles = {}
+      @output_target = output
+      @pending_boxes = []
+
+      page_style(DEFAULT_PAGE_STYLE, page_size: page_size,
+                                     orientation: page_orientation,
+                                     margin: margin)
+      @current_style_name = DEFAULT_PAGE_STYLE
+      new_page unless skip_page_creation
+    end
+
+    # Class-level shortcut: create a document, yield to block, write.
+    def self.create(output, **)
+      composer = new(output, **)
+      yield composer
+      composer.write
+    end
+
+    # Define a named text style.
+    def style(name, base: :base, **properties)
+      @styles ||= {}
+      @styles[name.to_sym] = Layout::Style.new(base, **properties)
+    end
+
+    def style?(name)
+      @styles&.key?(name.to_sym)
+    end
+
+    # Define a named page style.
+    def page_style(name, **attrs, &)
+      @page_styles[name.to_sym] = Layout::PageStyle.new(name: name, **attrs, &)
+    end
+
+    # Create a new page using the named (or current) page style.
+    def new_page(style_name = nil)
+      @current_style_name = style_name || next_style_name
+      style_obj = @page_styles[@current_style_name]
+      page = @document.pages.add
+      page.value[:MediaBox] = [0, 0, style_obj.width, style_obj.height]
+      @current_page = page
+      @pending_boxes = []
+      page
+    end
+
+    def x
+      @cursor_x || 50
+    end
+
+    def y
+      @cursor_y || (@current_page ? 750 : 0)
+    end
+
+    # Add text using a style.
+    def text(str, width: 0, height: 0, style: nil, **style_properties)
+      resolved_style = resolve_style(style, style_properties)
+      box = Layout::TextBox.new(text: str, width: width, height: height,
+                                style: resolved_style)
+      draw_box_on_current_page(box)
+    end
+
+    # Add formatted text (array of {text:, style:} runs).
+    def formatted_text(data, **opts)
+      data.each { |run| text(run[:text], **opts, **run.fetch(:style, {})) }
+    end
+
+    # Add an image from a file path.
+    def image(path, width: 0, height: 0, **opts)
+      box = Layout::ImageBox.new(path: path, document: @document,
+                                 width: width, height: height)
+      draw_box_on_current_page(box)
+    end
+
+    # Add an arbitrary box.
+    def box(box_class, **, &)
+      box = box_class.new(**, &)
+      draw_box_on_current_page(box)
+    end
+
+    # Write the document.
+    def write(output = @output_target, optimize: false, **opts)
+      flush_pending_boxes
+      target = output
+      if target.is_a?(String)
+        @document.write(target)
+      else
+        @document.write(io: target)
+      end
+    end
+
+    def write_to_string(optimize: false, **)
+      require "stringio"
+      io = StringIO.new
+      write(io, optimize: optimize, **)
+      io.string
+    end
+
+    private
+
+    def next_style_name
+      current = @page_styles[@current_style_name]
+      current&.next_style || @current_style_name
+    end
+
+    def resolve_style(name, properties)
+      if name.is_a?(Layout::Style)
+        properties.empty? ? name : name.update(**properties)
+      elsif @styles && @styles[name.to_sym]
+        base = @styles[name.to_sym]
+        properties.empty? ? base : base.update(**properties)
+      else
+        Layout::Style.new(properties.empty? ? :base : properties)
+      end
+    end
+
+    def draw_box_on_current_page(box)
+      @pending_boxes << box
+    end
+
+    def flush_pending_boxes
+      return if @pending_boxes.empty?
+
+      style_obj = @page_styles[@current_style_name]
+      frame = style_obj.frame
+      cursor_y = frame.top
+
+      @pending_boxes.each do |box|
+        unless box.fit?(frame.width, cursor_y - frame.bottom)
+          new_page
+          cursor_y = @page_styles[@current_style_name].frame.top
+          box.fit?(frame.width, cursor_y - frame.bottom)
+        end
+        canvas = @current_page.canvas
+        box.draw(canvas, frame.left, cursor_y)
+        cursor_y -= box.height
+      end
+      @pending_boxes = []
+    end
+  end
+end

data/lib/pdfrb/conformance/pdf_a.rb

@@ -1,74 +1,335 @@
 # frozen_string_literal: true
 
+# rubocop:disable Metrics/BlockLength
 module Pdfrb
   module Conformance
-    # PDF/A-1/2/3 validation (ISO 19005). Checks a document against
-    # the subset constraints. Returns a +Result+ with per-rule verdicts.
     module PdfA
-      Result = Struct.new(:level, :passed, :violations, keyword_init: true)
-      Violation = Struct.new(:rule, :message, :object, keyword_init: true)
-
       module_function
 
-      def validate(document, level: :a2b)
-        violations = []
-        check_no_encryption(document, violations)
-        check_has_metadata(document, violations)
-        check_embedded_fonts(document, violations)
-        Result.new(
-          level: level,
-          passed: violations.empty?,
-          violations: violations
-        )
+      SHARED = RuleSet.new("PDF/A-shared").tap do |rs|
+        rs.register(Rule.new(
+                      id: "6.1-1", description: "Encryption prohibited",
+                      severity: :error, spec_clause: "ISO 19005-1 6.1",
+                      check: ->(doc) {
+                        next nil unless doc.trailer && doc.trailer[:Encrypt]
+
+                        Violation.new(rule_id: "6.1-1", message: "PDF/A prohibits encryption",
+                                      object: "trailer", severity: :error, spec_clause: "ISO 19005-1 6.1")
+                      }
+                    ))
+        rs.register(Rule.new(
+                      id: "6.1-2", description: "XMP Metadata required",
+                      severity: :error, spec_clause: "ISO 19005-1 6.1",
+                      check: ->(doc) {
+                        next nil if doc.catalog[:Metadata]
+
+                        Violation.new(rule_id: "6.1-2", message: "PDF/A requires /Catalog/Metadata XMP stream",
+                                      object: "Catalog", severity: :error, spec_clause: "ISO 19005-1 6.1")
+                      }
+                    ))
+        rs.register(Rule.new(
+                      id: "6.1-4", description: "JavaScript prohibited",
+                      severity: :error, spec_clause: "ISO 19005-1 6.1",
+                      check: ->(doc) {
+                        doc.each_indirect_object do |obj|
+                          next unless obj.is_a?(Pdfrb::Model::Cos::Dictionary)
+                          if obj.value[:S] == :JavaScript
+                            return Violation.new(rule_id: "6.1-4", message: "PDF/A prohibits JavaScript actions",
+                                                 object: "JavaScript action", severity: :error,
+                                                 spec_clause: "ISO 19005-1 6.1")
+                          end
+                        end
+                        nil
+                      }
+                    ))
+        rs.register(Rule.new(
+                      id: "6.1-7", description: "Language recommended",
+                      severity: :warning, spec_clause: "ISO 19005-1 6.1",
+                      check: ->(doc) {
+                        next nil if doc.catalog[:Lang]
+
+                        Violation.new(rule_id: "6.1-7", message: "PDF/A recommends /Catalog/Lang",
+                                      object: "Catalog", severity: :warning, spec_clause: "ISO 19005-1 6.1")
+                      }
+                    ))
+        rs.register(Rule.new(
+                      id: "embedded-fonts", description: "All fonts must be embedded",
+                      severity: :error, spec_clause: "ISO 19005-1 6.2",
+                      check: ->(doc) {
+                        vs = []
+                        doc.pages.each do |page|
+                          res = page.value[:Resources]
+                          next unless res
+
+                          fonts = res.is_a?(Pdfrb::Model::Cos::Dictionary) ? res.value[:Font] : res[:Font]
+                          next unless fonts
+
+                          fonts.each_value do |ref|
+                            f = ref.is_a?(Pdfrb::Model::Reference) ? doc.object(ref) : ref
+                            next unless f
+                            next if f[:FontDescriptor]
+
+                            vs << Violation.new(rule_id: "embedded-fonts",
+                                                message: "Font /#{f[:BaseFont]} missing FontDescriptor",
+                                                object: f[:BaseFont]&.to_s, severity: :error,
+                                                spec_clause: "ISO 19005-1 6.2")
+                          end
+                        end
+                        vs.empty? ? nil : vs
+                      }
+                    ))
+      end
+
+      A1_SPECIFIC = RuleSet.new("PDF/A-1-specific").tap do |rs|
+        rs.register(Rule.new(
+                      id: "a1-1", description: "JPEG2000 not allowed in A-1",
+                      severity: :error, spec_clause: "ISO 19005-1 6.2.4",
+                      check: ->(doc) {
+                        doc.each_indirect_object do |obj|
+                          next unless obj.is_a?(Pdfrb::Model::Cos::Stream)
+                          next unless obj[:Filter] == :JPXDecode
+
+                          return Violation.new(rule_id: "a1-1",
+                                               message: "JPEG2000 not allowed in PDF/A-1",
+                                               object: "XObject", severity: :error,
+                                               spec_clause: "ISO 19005-1 6.2.4")
+                        end
+                        nil
+                      }
+                    ))
+        rs.register(Rule.new(
+                      id: "a1-2", description: "Object streams not allowed in A-1",
+                      severity: :error, spec_clause: "ISO 19005-1 6.2.4",
+                      check: ->(doc) {
+                        doc.each_indirect_object do |obj|
+                          next unless obj.is_a?(Pdfrb::Model::Cos::Dictionary)
+                          next unless obj.value[:Type] == :ObjStm
+
+                          return Violation.new(rule_id: "a1-2",
+                                               message: "Object streams not allowed in PDF/A-1",
+                                               object: "ObjStm", severity: :error,
+                                               spec_clause: "ISO 19005-1 6.2.4")
+                        end
+                        nil
+                      }
+                    ))
+        rs.register(Rule.new(
+                      id: "a1-3", description: "PDF version must not exceed 1.4",
+                      severity: :error, spec_clause: "ISO 19005-1 6.1",
+                      check: ->(doc) {
+                        parts = doc.version.to_s.split(".")
+                        major = parts[0].to_i
+                        minor = (parts[1] || "0").to_i
+                        next nil if major < 1 || (major == 1 && minor <= 4)
+
+                        Violation.new(rule_id: "a1-3",
+                                      message: "PDF/A-1 requires version <= 1.4, got #{doc.version}",
+                                      object: "header", severity: :error, spec_clause: "ISO 19005-1 6.1")
+                      }
+                    ))
+        rs.register(Rule.new(
+                      id: "a1-4", description: "LZWDecode not allowed in A-1",
+                      severity: :error, spec_clause: "ISO 19005-1 6.2.4",
+                      check: ->(doc) {
+                        doc.each_indirect_object do |obj|
+                          next unless obj.is_a?(Pdfrb::Model::Cos::Stream)
+
+                          f = obj[:Filter]
+                          fs = f.is_a?(::Array) ? f : [f]
+                          next unless fs.include?(:LZWDecode)
+
+                          return Violation.new(rule_id: "a1-4",
+                                               message: "LZWDecode not allowed in PDF/A-1",
+                                               object: "Stream", severity: :error,
+                                               spec_clause: "ISO 19005-1 6.2.4")
+                        end
+                        nil
+                      }
+                    ))
+      end
+
+      A2_SPECIFIC = RuleSet.new("PDF/A-2-specific").tap do |rs|
+        rs.register(Rule.new(
+                      id: "a2-1", description: "PostScript XObjects prohibited",
+                      severity: :warning, spec_clause: "ISO 19005-2 6.2.4",
+                      check: ->(doc) {
+                        doc.each_indirect_object do |obj|
+                          next unless obj.is_a?(Pdfrb::Model::Cos::Stream)
+                          next unless [:PS, :PSXObject].include?(obj[:Subtype])
+
+                          return Violation.new(rule_id: "a2-1",
+                                               message: "PostScript XObjects not allowed in PDF/A-2",
+                                               object: "XObject", severity: :warning,
+                                               spec_clause: "ISO 19005-2 6.2.4")
+                        end
+                        nil
+                      }
+                    ))
+        rs.register(Rule.new(
+                      id: "a2-2", description: "Embedded files not allowed in A-2",
+                      severity: :error, spec_clause: "ISO 19005-2 6.2",
+                      check: ->(doc) {
+                        doc.each_indirect_object do |obj|
+                          next unless obj.is_a?(Pdfrb::Model::Cos::Dictionary)
+                          next unless obj.value[:Type] == :EmbeddedFile
+
+                          return Violation.new(rule_id: "a2-2",
+                                               message: "Embedded files not allowed in PDF/A-2 (use PDF/A-3)",
+                                               object: "EmbeddedFile", severity: :error,
+                                               spec_clause: "ISO 19005-2 6.2")
+                        end
+                        nil
+                      }
+                    ))
+        rs.register(Rule.new(
+                      id: "a2-3", description: "PDF 2.0 not allowed",
+                      severity: :error, spec_clause: "ISO 19005-2 6.1",
+                      check: ->(doc) {
+                        next nil unless doc.version.to_s.start_with?("2.")
+
+                        Violation.new(rule_id: "a2-3",
+                                      message: "PDF/A-2 does not allow PDF 2.0, got #{doc.version}",
+                                      object: "header", severity: :error, spec_clause: "ISO 19005-2 6.1")
+                      }
+                    ))
       end
 
-      def check_no_encryption(document, violations)
-        return unless document.trailer && document.trailer[:Encrypt]
+      A3_SPECIFIC = RuleSet.new("PDF/A-3-specific").tap do |rs|
+        rs.register(Rule.new(
+                      id: "a3-1", description: "Filespecs must have AFRelationship",
+                      severity: :error, spec_clause: "ISO 19005-3 6.2",
+                      check: ->(doc) {
+                        vs = []
+                        doc.each_indirect_object do |obj|
+                          next unless obj.is_a?(Pdfrb::Model::Cos::Dictionary)
+                          next unless obj.value[:Type] == :Filespec
+                          next if obj.value[:AFRelationship]
 
-        violations << Violation.new(
-          rule: "no-encryption",
-          message: "PDF/A prohibits encryption",
-          object: "trailer"
-        )
+                          vs << Violation.new(rule_id: "a3-1",
+                                              message: "Filespec missing /AFRelationship",
+                                              object: "Filespec", severity: :error,
+                                              spec_clause: "ISO 19005-3 6.2")
+                        end
+                        vs.empty? ? nil : vs
+                      }
+                    ))
       end
-      private_class_method :check_no_encryption
 
-      def check_has_metadata(document, violations)
-        return if document.catalog[:Metadata]
+      A4_SPECIFIC = RuleSet.new("PDF/A-4-specific").tap do |rs|
+        rs.register(Rule.new(
+                      id: "a4-1", description: "PDF 2.0 required",
+                      severity: :error, spec_clause: "ISO 19005-4 6.1",
+                      check: ->(doc) {
+                        next nil if doc.version.to_s.start_with?("2.0")
 
-        violations << Violation.new(
-          rule: "metadata-required",
-          message: "PDF/A requires /Catalog/Metadata XMP stream",
-          object: "Catalog"
-        )
+                        Violation.new(rule_id: "a4-1",
+                                      message: "PDF/A-4 requires PDF 2.0, got #{doc.version}",
+                                      object: "header", severity: :error, spec_clause: "ISO 19005-4 6.1")
+                      }
+                    ))
+        rs.register(Rule.new(
+                      id: "a4-2", description: "Filespecs must have AFRelationship",
+                      severity: :error, spec_clause: "ISO 19005-4 6.2",
+                      check: ->(doc) {
+                        vs = []
+                        doc.each_indirect_object do |obj|
+                          next unless obj.is_a?(Pdfrb::Model::Cos::Dictionary)
+                          next unless obj.value[:Type] == :Filespec
+                          next if obj.value[:AFRelationship]
+
+                          vs << Violation.new(rule_id: "a4-2",
+                                              message: "Filespec missing /AFRelationship",
+                                              object: "Filespec", severity: :error,
+                                              spec_clause: "ISO 19005-4 6.2")
+                        end
+                        vs.empty? ? nil : vs
+                      }
+                    ))
+        rs.register(Rule.new(
+                      id: "a4-3", description: "Annotations need appearance streams",
+                      severity: :error, spec_clause: "ISO 19005-4 6.2.3",
+                      check: ->(doc) {
+                        vs = []
+                        doc.each_indirect_object do |annot|
+                          next unless annot.is_a?(Pdfrb::Model::Cos::Dictionary)
+                          next unless annot.value[:Type] == :Annot
+
+                          st = annot.value[:Subtype]
+                          next if st == :Link
+
+                          r = annot.value[:Rect]
+                          next if r.is_a?(::Array) && r.length == 4 && r[0] == r[2] && r[1] == r[3]
+                          next if annot.value[:AP]
+
+                          vs << Violation.new(rule_id: "a4-3",
+                                              message: "Annotation /#{st} missing /AP",
+                                              object: "Annot", severity: :error,
+                                              spec_clause: "ISO 19005-4 6.2.3")
+                        end
+                        vs.empty? ? nil : vs
+                      }
+                    ))
+        rs.register(Rule.new(
+                      id: "a4-4", description: "Trailer /ID recommended",
+                      severity: :warning, spec_clause: "ISO 19005-4 6.1",
+                      check: ->(doc) {
+                        next nil if doc.trailer && doc.trailer[:ID]
+
+                        Violation.new(rule_id: "a4-4", message: "PDF/A-4 recommends /ID in trailer",
+                                      object: "trailer", severity: :warning, spec_clause: "ISO 19005-4 6.1")
+                      }
+                    ))
+        rs.register(Rule.new(
+                      id: "a4-5", description: "Metadata XMP recommended",
+                      severity: :warning, spec_clause: "ISO 19005-4 6.1",
+                      check: ->(doc) {
+                        next nil if doc.catalog[:Metadata]
+
+                        Violation.new(rule_id: "a4-5",
+                                      message: "PDF/A-4 recommends /Catalog/Metadata XMP stream",
+                                      object: "Catalog", severity: :warning, spec_clause: "ISO 19005-4 6.1")
+                      }
+                    ))
+      end
+
+      A1 = RuleSet.new("PDF/A-1").tap do |rs|
+        SHARED.rules.each { |r| rs.register(r) }
+        A1_SPECIFIC.rules.each { |r| rs.register(r) }
+      end
+
+      A2 = RuleSet.new("PDF/A-2").tap do |rs|
+        SHARED.rules.each { |r| rs.register(r) }
+        A2_SPECIFIC.rules.each { |r| rs.register(r) }
       end
-      private_class_method :check_has_metadata
-
-      def check_embedded_fonts(document, violations)
-        document.pages.each do |page|
-          resources = page.value[:Resources]
-          next unless resources
-
-          fonts = resources.is_a?(Pdfrb::Model::Cos::Dictionary) ?
-                    resources.value[:Font] : resources[:Font]
-          next unless fonts
-
-          fonts.each_value do |ref|
-            font = ref.is_a?(Pdfrb::Model::Reference) ?
-                     document.object(ref) : ref
-            next unless font
-
-            unless font[:FontDescriptor]
-              violations << Violation.new(
-                rule: "embedded-fonts",
-                message: "Font /#{font[:BaseFont]} missing FontDescriptor",
-                object: font[:BaseFont]
-              )
-            end
-          end
-        end
+
+      A3 = RuleSet.new("PDF/A-3").tap do |rs|
+        SHARED.rules.each { |r| rs.register(r) }
+        A3_SPECIFIC.rules.each { |r| rs.register(r) }
+      end
+
+      A4 = RuleSet.new("PDF/A-4").tap do |rs|
+        SHARED.rules.each { |r| rs.register(r) }
+        A4_SPECIFIC.rules.each { |r| rs.register(r) }
+      end
+
+      LEVEL_RULESETS = {
+        a1b: A1, a1a: A1,
+        a2b: A2, a2a: A2,
+        a3b: A3, a3a: A3,
+        a4: A4
+      }.freeze
+
+      def profiles
+        { a1b: A1, a1a: A1, a2b: A2, a2a: A2,
+          a3b: A3, a3a: A3, a4: A4 }
+      end
+
+      def validate(document, level: :a2b)
+        rs = LEVEL_RULESETS[level] || SHARED
+        rs.validate(document)
       end
-      private_class_method :check_embedded_fonts
     end
   end
 end
+
+# rubocop:enable Metrics/BlockLength