stationery 0.12.0 → 0.12.2

data/lib/stationery/verify/engines/poppler.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Verify
+    module Engines
+      # Poppler, the engine of the Linux desktop viewers (Evince, Okular):
+      # pdfinfo for the pages and the structure tree, pdftotext, pdftoppm
+      # in grey, pdffonts, pdfdetach and pdfsig. What any of them writes on
+      # stderr fails the check. The tools take a password on their command
+      # line only, where other local processes can read it; pdfsig takes
+      # none, so a file opened with one reports no signatures.
+      class Poppler < Engine
+        NAME = "poppler"
+        INSTALL = "brew install poppler, or apt-get install poppler-utils"
+        TOOLS = %w[pdfinfo pdftotext pdftoppm pdffonts pdfdetach pdfsig].freeze
+        UNSIGNED = "does not contain any signatures"
+        NOT_SIGNED = "The signature form field is not signed."
+
+        def available? = TOOLS.all? { |tool| Command.which(tool) }
+        def version = "poppler #{run("pdfinfo", "-v").stderr[/\d+(\.\d+)+/]}"
+
+        def facts(paths, password: nil)
+          paths.map { |path| Dir.mktmpdir("stationery-verify") { |dir| read(path, password, dir) } }
+        end
+
+        private
+
+        def read(path, password, dir)
+          @results = []
+          options = password ? ["-upw", password] : []
+          count = tool("pdfinfo", *options, path).stdout[/^Pages:\s+(\d+)/, 1].to_i
+          { "file" => path, "pages" => pages(path, options, dir, count), "fonts" => fonts(path, options),
+            "attachments" => attachments(path, options), "signatures" => (signatures(path) unless password),
+            "structure" => !tool("pdfinfo", "-struct", *options, path).stdout.strip.empty?,
+            "errors" => @results.reject { |(_, result)| result.success? || unsigned?(result) }
+                                .map { |(name, result)| failure(name, result) },
+            "warnings" => @results.flat_map { |(_, result)| lines(result.stderr) }.uniq }
+        end
+
+        def tool(name, *)
+          run(name, *).tap { |result| @results << [name, result] }
+        end
+
+        def pages(path, options, dir, count)
+          texts = tool("pdftotext", "-enc", "UTF-8", *options, path, "-").stdout.split("\f")
+          tool("pdftoppm", "-gray", "-r", "36", *options, path, File.join(dir, "p"))
+          pictures = Dir[File.join(dir, "p-*.pgm")].sort_by { |file| file[/-(\d+)\.pgm\z/, 1].to_i }
+          (1..count).map do |number|
+            picture = pictures[number - 1]
+            { "number" => number, "text" => texts[number - 1].to_s,
+              "painted" => picture && painted?(File.binread(picture)) }
+          end
+        end
+
+        def fonts(path, options)
+          tool("pdffonts", *options, path).stdout.lines.drop(2).map do |line|
+            columns = line.split
+            { "name" => columns.first, "embedded" => columns[-5] == "yes", "unicode" => columns[-3] == "yes" }
+          end
+        end
+
+        def attachments(path, options)
+          tool("pdfdetach", "-list", *options, path).stdout.lines.filter_map { |line| line[/\A\d+: (.*)$/, 1] }
+        end
+
+        # pdfsig answers "valid" for a signature over the whole file whose
+        # CMS verifies; -nocert leaves the certificate's trust out of it.
+        def signatures(path)
+          result = tool("pdfsig", "-nocert", path)
+          return { "count" => 0, "valid" => nil } if unsigned?(result)
+
+          blocks = result.stdout.split(/^Signature #\d+:$/).drop(1).reject { |block| block.include?(NOT_SIGNED) }
+          { "count" => blocks.size,
+            "valid" => blocks.all? do |block|
+              block.include?("Signature is Valid") && block.include?("Total document signed")
+            end }
+        end
+
+        def unsigned?(result) = result.exitstatus == 2 && result.stdout.include?(UNSIGNED)
+      end
+    end
+  end
+end

data/lib/stationery/verify/engines/qpdf.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Verify
+    module Engines
+      # qpdf: the file's structure (`--check`, whose warnings fail it too)
+      # and its page count. The password goes through a file.
+      class Qpdf < Engine
+        NAME = "qpdf"
+        INSTALL = "brew install qpdf, or apt-get install qpdf"
+
+        def available? = !Command.which("qpdf").nil?
+        def version = run("qpdf", "--version").stdout.lines.first.to_s.strip
+
+        def facts(paths, password: nil)
+          with_password_file(password) do |options|
+            paths.map { |path| read(path, options) }
+          end
+        end
+
+        private
+
+        def read(path, options)
+          check = run("qpdf", *options, "--check", path)
+          count = run("qpdf", *options, "--show-npages", path)
+          errors = check.success? || check.exitstatus == 3 ? [] : [failure("qpdf --check", check)]
+          errors << failure("qpdf --show-npages", count) unless count.success?
+          warnings = check.exitstatus == 3 ? lines(check.stderr) + lines(check.stdout).grep(/WARNING/) : []
+          { "file" => path, "pages" => (1..count.stdout.to_i).map { |number| { "number" => number } },
+            "errors" => errors, "warnings" => warnings.uniq }
+        end
+
+        def with_password_file(password)
+          return yield([]) unless password
+
+          Tempfile.create("stationery-verify") do |file|
+            file.chmod(0o600)
+            file.write(password)
+            file.flush
+            yield(["--password-file=#{file.path}"])
+          end
+        end
+      end
+    end
+  end
+end

data/lib/stationery/verify/expectation.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Verify
+    # What a file holds, read with pdf-reader (Testing::Inspector), for the
+    # engines' facts to be held against: each page's text lines, links and
+    # whether it has content; the outline's titles in order; the fields,
+    # once by name, and whether one of its widgets has an area; the
+    # attachments' names; how many signatures the file carries and whether
+    # they verify; whether it is tagged.
+    Expectation = Data.define(:pages, :outline, :fields, :attachments, :signatures, :valid, :tagged) do
+      # A page's `lines` are its runs of text (Testing::PageReader); it has
+      # `content` when it shows text or an image. Paths are not read, so a
+      # page that draws only paths is held to nothing painted.
+      self::Page = Data.define(:number, :lines, :links, :content)
+
+      def self.read(inspector)
+        layout = inspector.layout
+        signatures = inspector.signatures
+        new(pages: layout[:pages].map { |page| page(page) }, outline: titles(layout[:outline]),
+            fields: fields(layout[:pages]), attachments: layout[:attachments].map { |file| file[:name] },
+            signatures: signatures.size, valid: signatures.all? { |signature| signature[:valid] },
+            tagged: layout[:tagged])
+      end
+
+      def self.page(page)
+        self::Page.new(number: page[:number], lines: page[:text].map { |run| run[:text] },
+                       links: page[:links].map { |link| link.slice(:uri, :page) },
+                       content: page[:text].any? || page[:images].any?)
+      end
+
+      def self.titles(entries) = entries.flat_map { |entry| [entry[:title], *titles(entry[:children])] }
+
+      # A field is `visible` when one of its widgets has an area: a widget
+      # of no size (an invisible signature's) needs no appearance.
+      def self.fields(pages)
+        pages.flat_map { |page| page[:fields] }.group_by { |field| field[:name] }.map do |_, widgets|
+          widgets.first.slice(:name, :type, :value)
+                 .merge(visible: widgets.any? { |widget| widget[:width].positive? && widget[:height].positive? })
+        end
+      end
+    end
+  end
+end

data/lib/stationery/verify/report.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Verify
+    # What Verify.run found: a Result for each file and engine that ran, and
+    # the engines that are not installed. It passes when every engine that
+    # ran finds nothing wrong with any file, and at least one ran.
+    Report = Data.define(:results, :missing) do
+      self::Result = Data.define(:file, :engine, :version, :problems) do
+        def passed? = problems.empty?
+      end
+
+      def passed? = results.any? && results.all?(&:passed?)
+
+      # One line per file and engine, its problems under it, then the
+      # engines not run with the line that installs each.
+      def lines
+        width = results.map { |result| result.engine.size }.max.to_i
+        found = results.group_by(&:file).flat_map do |file, ran|
+          [file, *ran.flat_map { |result| result_lines(result, width) }]
+        end
+        found + (if missing.empty?
+                   []
+                 else
+                   ["not run: #{missing.map do |engine|
+                     "#{engine.name} (#{engine.install})"
+                   end.join(", ")}"]
+                 end)
+      end
+
+      def to_h
+        { passed: passed?, results: results.map(&:to_h),
+          missing: missing.map { |engine| { engine: engine.name, install: engine.install } } }
+      end
+
+      private
+
+      def result_lines(result, width)
+        verdict = result.passed? ? "ok" : "FAILED"
+        ["  #{result.engine.ljust(width)}  #{verdict}  (#{result.version})",
+         *result.problems.map { |problem| "      #{printable(problem)}" }]
+      end
+
+      # A problem quotes what engines read from the file, which may hold
+      # control characters: they print escaped, not to the terminal.
+      def printable(text) = text.scrub.gsub(/[[:cntrl:]]/) { |char| char.dump[1..-2] }
+    end
+  end
+end

data/lib/stationery/verify/scripts/pdfium.py

@@ -0,0 +1,99 @@
+"""Reads PDFs with PDFium (pypdfium2) and prints one JSON object of facts per
+file, one per line, for Stationery::Verify.
+
+    python3 pdfium.py FILE...
+
+STATIONERY_VERIFY_PASSWORD opens an encrypted file.
+"""
+import ctypes
+import json
+import os
+import sys
+
+import pypdfium2 as pdfium
+import pypdfium2.raw as raw
+
+PASSWORD = os.environ.get("STATIONERY_VERIFY_PASSWORD") or None
+SCALE = 0.5  # 36 dpi: enough for a page's text to darken a pixel
+
+
+def utf16(function, *args):
+    size = function(*args, None, 0)
+    if size <= 2:
+        return ""
+    buffer = ctypes.create_string_buffer(size)
+    function(*args, ctypes.cast(buffer, ctypes.POINTER(ctypes.c_ushort)), size)
+    return buffer.raw[: size - 2].decode("utf-16-le")
+
+
+def painted(page):
+    bitmap = page.render(scale=SCALE, grayscale=True, may_draw_forms=True)
+    data = bytes(bitmap.buffer)
+    width, stride = bitmap.width * bitmap.n_channels, bitmap.stride
+    return any(data[row * stride : row * stride + width].count(255) != width for row in range(bitmap.height))
+
+
+def target(document, link):
+    action = raw.FPDFLink_GetAction(link)
+    if action and raw.FPDFAction_GetType(action) == raw.PDFACTION_URI:
+        size = raw.FPDFAction_GetURIPath(document.raw, action, None, 0)
+        buffer = ctypes.create_string_buffer(size)
+        raw.FPDFAction_GetURIPath(document.raw, action, buffer, size)
+        return {"uri": buffer.raw[: size - 1].decode("utf-8", "replace")}
+    dest = raw.FPDFLink_GetDest(document.raw, link)
+    if not dest and action:
+        dest = raw.FPDFAction_GetDest(document.raw, action)
+    return {"page": raw.FPDFDest_GetDestPageIndex(document.raw, dest) + 1} if dest else {}
+
+
+def annotations(document, page):
+    links, fields = [], []
+    form = document.formenv.raw if document.formenv else None
+    for index in range(raw.FPDFPage_GetAnnotCount(page.raw)):
+        annot = raw.FPDFPage_GetAnnot(page.raw, index)
+        subtype = raw.FPDFAnnot_GetSubtype(annot)
+        if subtype == raw.FPDF_ANNOT_LINK:
+            links.append(target(document, raw.FPDFAnnot_GetLink(annot)))
+        elif subtype == raw.FPDF_ANNOT_WIDGET and form:
+            value = utf16(raw.FPDFAnnot_GetFormFieldValue, form, annot)
+            fields.append({"name": utf16(raw.FPDFAnnot_GetFormFieldName, form, annot),
+                           "value": value if raw.FPDFAnnot_GetFormFieldType(form, annot) == raw.FPDF_FORMFIELD_TEXTFIELD else None,
+                           "appearance": bool(raw.FPDFAnnot_HasKey(annot, b"AP"))})
+        raw.FPDFPage_CloseAnnot(annot)
+    return links, fields
+
+
+def signed(document):
+    """The signature fields that hold a signature: PDFium counts empty ones too."""
+    count = raw.FPDF_GetSignatureCount(document.raw)
+    objects = (raw.FPDF_GetSignatureObject(document.raw, index) for index in range(count))
+    return sum(1 for signature in objects if raw.FPDFSignatureObj_GetContents(signature, None, 0) > 0)
+
+
+def facts(path):
+    result = {"file": path, "pages": [], "errors": [], "warnings": []}
+    try:
+        read(path, result)
+    except Exception as error:  # a file PDFium cannot read is that file's error, not the run's
+        result["errors"].append(f"{type(error).__name__}: {error}")
+    return result
+
+
+def read(path, result):
+    document = pdfium.PdfDocument(path, password=PASSWORD)
+    document.init_forms()
+    fields = []
+    for index in range(len(document)):
+        page = document[index]
+        links, widgets = annotations(document, page)
+        fields.extend(widgets)
+        text = page.get_textpage().get_text_range()
+        result["pages"].append({"number": index + 1, "text": text, "painted": painted(page), "links": links})
+    result["outline"] = [item.get_title() for item in document.get_toc()]
+    result["fields"] = fields
+    result["signatures"] = {"count": signed(document), "valid": None}
+    document.close()
+
+
+for path in sys.argv[1:]:
+    print(json.dumps(facts(path)), flush=True)

data/lib/stationery/verify/scripts/pdfjs.mjs

@@ -0,0 +1,108 @@
+// Reads PDFs with pdf.js (pdfjs-dist's legacy build under Node) and prints
+// one JSON object of facts per file, one per line, for Stationery::Verify.
+//
+//   STATIONERY_PDFJS=/path/to/node_modules/pdfjs-dist node pdfjs.mjs FILE…
+//
+// STATIONERY_VERIFY_PASSWORD opens an encrypted file. Node has no canvas, so
+// a page "paints" when its operator list holds a painting operator.
+import { readFile } from "node:fs/promises";
+import { pathToFileURL } from "node:url";
+import path from "node:path";
+
+const root = process.env.STATIONERY_PDFJS;
+const pdfjs = await import(pathToFileURL(path.join(root, "legacy/build/pdf.mjs")).href);
+const { getDocument, VerbosityLevel, OPS, AnnotationType } = pdfjs;
+const password = process.env.STATIONERY_VERIFY_PASSWORD || undefined;
+const write = process.stdout.write.bind(process.stdout);
+const PAINTS = new Set(
+  ["fill", "eoFill", "stroke", "fillStroke", "eoFillStroke", "closeStroke", "closeFillStroke", "closeEOFillStroke",
+   "showText", "showSpacedText", "nextLineShowText", "nextLineSetSpacingShowText", "shadingFill",
+   "paintImageXObject", "paintInlineImageXObject", "paintImageMaskXObject", "paintSolidColorImageMask",
+   "paintImageXObjectRepeat", "paintImageMaskXObjectRepeat", "paintImageMaskXObjectGroup", "constructPath"]
+    .filter((name) => name in OPS).map((name) => OPS[name])
+);
+
+let messages = [];
+for (const level of ["log", "info", "warn", "error"]) {
+  console[level] = (...args) => messages.push(args.map(String).join(" "));
+}
+
+// pdf.js 6 answers Maps where earlier versions answered plain objects.
+const entries = (found) => (found instanceof Map ? [...found] : Object.entries(found || {}));
+
+async function titles(items) {
+  const found = [];
+  for (const item of items || []) found.push(item.title, ...(await titles(item.items)));
+  return found;
+}
+
+async function target(document, annotation) {
+  if (annotation.url) return { uri: annotation.url };
+  let dest = annotation.dest;
+  if (typeof dest === "string") dest = await document.getDestination(dest);
+  if (!Array.isArray(dest)) return {};
+  const ref = dest[0];
+  const index = typeof ref === "number" ? ref : await document.getPageIndex(ref);
+  return { page: index + 1 };
+}
+
+async function page(document, number) {
+  const page = await document.getPage(number);
+  const text = (await page.getTextContent()).items.map((item) => item.str ?? "").join(" ");
+  const operators = await page.getOperatorList();
+  const painted = operators.fnArray.some((fn) => PAINTS.has(fn));
+  const annotations = await page.getAnnotations();
+  const links = [];
+  for (const annotation of annotations) {
+    if (annotation.annotationType === AnnotationType.LINK) links.push(await target(document, annotation));
+  }
+  const widgets = annotations.filter((annotation) => annotation.annotationType === AnnotationType.WIDGET);
+  const structure = await page.getStructTree();
+  return { page: { number, text, painted, links }, widgets, structure: structure !== null };
+}
+
+function fields(objects, widgets) {
+  return entries(objects).map(([name, kids]) => {
+    const values = kids.map((kid) => kid.value).filter((value) => value !== undefined && value !== null);
+    const own = widgets.filter((widget) => widget.fieldName === name);
+    return {
+      name,
+      value: typeof values[0] === "string" ? values[0] : null,
+      appearance: own.length === 0 ? null : own.every((widget) => widget.hasAppearance),
+    };
+  });
+}
+
+async function facts(file) {
+  messages = [];
+  const result = { file, pages: [], errors: [] };
+  try {
+    const data = new Uint8Array(await readFile(file));
+    const task = getDocument({
+      data, password, verbosity: VerbosityLevel.WARNINGS, isEvalSupported: false,
+      standardFontDataUrl: path.join(root, "standard_fonts") + path.sep,
+      cMapUrl: path.join(root, "cmaps") + path.sep, cMapPacked: true,
+      wasmUrl: path.join(root, "wasm") + path.sep,
+    });
+    const document = await task.promise;
+    const widgets = [];
+    let structure = false;
+    for (let number = 1; number <= document.numPages; number++) {
+      const read = await page(document, number);
+      result.pages.push(read.page);
+      widgets.push(...read.widgets);
+      structure ||= read.structure;
+    }
+    result.outline = await titles(await document.getOutline());
+    result.fields = fields(await document.getFieldObjects(), widgets);
+    result.attachments = entries(await document.getAttachments()).map(([, file]) => file.filename);
+    result.structure = structure;
+    await task.destroy();
+  } catch (error) {
+    result.errors.push(String(error?.message || error));
+  }
+  result.warnings = messages;
+  return result;
+}
+
+for (const file of process.argv.slice(2)) write(JSON.stringify(await facts(file)) + "\n");

data/lib/stationery/verify/scripts/pdfkit.swift

@@ -0,0 +1,80 @@
+// Reads PDFs with Apple's PDFKit (what Preview and Safari show) and prints
+// one JSON object of facts per file, one per line, for Stationery::Verify.
+//
+//   swift pdfkit.swift FILE…
+//
+// STATIONERY_VERIFY_PASSWORD opens an encrypted file.
+import CoreGraphics
+import Foundation
+import PDFKit
+
+let password = ProcessInfo.processInfo.environment["STATIONERY_VERIFY_PASSWORD"] ?? ""
+let scale: CGFloat = 0.5 // 36 dpi: enough for a page's text to darken a pixel
+
+func painted(_ page: PDFPage) -> Bool {
+    let box = page.bounds(for: .mediaBox)
+    let width = max(Int(box.width * scale), 1), height = max(Int(box.height * scale), 1)
+    guard let context = CGContext(data: nil, width: width, height: height, bitsPerComponent: 8, bytesPerRow: width,
+                                  space: CGColorSpaceCreateDeviceGray(),
+                                  bitmapInfo: CGImageAlphaInfo.none.rawValue) else { return false }
+    context.setFillColor(gray: 1, alpha: 1)
+    context.fill(CGRect(x: 0, y: 0, width: width, height: height))
+    context.scaleBy(x: scale, y: scale)
+    page.draw(with: .mediaBox, to: context)
+    guard let data = context.data else { return false }
+    let pixels = data.bindMemory(to: UInt8.self, capacity: width * height)
+    return (0 ..< width * height).contains { pixels[$0] != 255 }
+}
+
+func target(_ annotation: PDFAnnotation, in document: PDFDocument) -> [String: Any] {
+    if let url = annotation.url ?? (annotation.action as? PDFActionURL)?.url { return ["uri": url.absoluteString] }
+    let destination = annotation.destination ?? (annotation.action as? PDFActionGoTo)?.destination
+    if let page = destination?.page { return ["page": document.index(for: page) + 1] }
+    return [:]
+}
+
+func titles(_ item: PDFOutline?) -> [String] {
+    guard let item else { return [] }
+    return (0 ..< item.numberOfChildren).flatMap { index -> [String] in
+        let child = item.child(at: index)!
+        return [child.label ?? ""] + titles(child)
+    }
+}
+
+func facts(_ path: String) -> [String: Any] {
+    var result: [String: Any] = ["file": path, "pages": [], "errors": [], "warnings": []]
+    guard let document = PDFDocument(url: URL(fileURLWithPath: path)) else {
+        result["errors"] = ["PDFKit cannot open the file"]
+        return result
+    }
+    if document.isLocked && !document.unlock(withPassword: password) {
+        result["errors"] = ["PDFKit cannot unlock the file"]
+        return result
+    }
+    var pages: [[String: Any]] = [], fields: [[String: Any]] = []
+    for index in 0 ..< document.pageCount {
+        guard let page = document.page(at: index) else {
+            result["errors"] = ["PDFKit cannot read page \(index + 1)"]
+            return result
+        }
+        var links: [[String: Any]] = []
+        for annotation in page.annotations {
+            if annotation.type == "Link" { links.append(target(annotation, in: document)) }
+            if annotation.type == "Widget", let name = annotation.fieldName {
+                let text = annotation.widgetFieldType == .text ? annotation.widgetStringValue : nil
+                // PDFKit keeps a widget's /AP to itself: the appearance is not reported.
+                fields.append(["name": name, "value": text as Any, "appearance": NSNull()])
+            }
+        }
+        pages.append(["number": index + 1, "text": page.string ?? "", "painted": painted(page), "links": links])
+    }
+    result["pages"] = pages
+    result["outline"] = titles(document.outlineRoot)
+    result["fields"] = fields
+    return result
+}
+
+for path in CommandLine.arguments.dropFirst() {
+    let data = try! JSONSerialization.data(withJSONObject: facts(path))
+    FileHandle.standardOutput.write(data + Data("\n".utf8))
+}

data/lib/stationery/verify.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "stationery"
+require "stationery/testing/inspector"
+require_relative "verify/command"
+require_relative "verify/engine"
+require_relative "verify/engines/qpdf"
+require_relative "verify/engines/poppler"
+require_relative "verify/engines/mupdf"
+require_relative "verify/engines/pdfium"
+require_relative "verify/engines/pdfjs"
+require_relative "verify/engines/pdfkit"
+require_relative "verify/allowlist"
+require_relative "verify/expectation"
+require_relative "verify/comparison"
+require_relative "verify/report"
+
+module Stationery
+  # Checks PDFs in the engines viewers are built on: qpdf, Poppler (the
+  # Linux desktop viewers), MuPDF, PDFium (Chrome, Edge), pdf.js (Firefox)
+  # and PDFKit (Preview, Safari). Each engine is an external tool the check
+  # finds when it is installed; the gem depends on none of them. What the
+  # engines read is held against what pdf-reader reads (Expectation), so
+  # `stationery verify` needs pdf-reader, as `inspect` does.
+  #
+  # `require "stationery"` does not load this: `stationery verify` and
+  # `rake verify:readers` do.
+  #
+  # An engine's facts about a file are a Hash, as its script prints them in
+  # JSON: `"file"`, `"errors"`, `"warnings"`, `"pages"` (each `"number"`,
+  # `"text"`, `"painted"`, `"links"`, a link `{"uri"}` or `{"page"}`), and
+  # `"outline"` (titles in order), `"fields"` (`"name"`, `"value"`,
+  # `"appearance"`), `"attachments"` (names), `"signatures"` (`"count"`,
+  # `"valid"`), `"structure"` and `"fonts"` (`"name"`, `"embedded"`,
+  # `"unicode"`). A fact an engine does not report is nil or left out, and
+  # is not checked.
+  module Verify
+    ENGINES = { "qpdf" => Engines::Qpdf, "poppler" => Engines::Poppler, "mupdf" => Engines::Mupdf,
+                "pdfium" => Engines::Pdfium, "pdfjs" => Engines::Pdfjs, "pdfkit" => Engines::Pdfkit }.freeze
+
+    # One adapter for each engine, or for each of `names`; raises
+    # ArgumentError for a name that is not an engine.
+    def self.adapters(names = ENGINES.keys)
+      names.map do |name|
+        ENGINES.fetch(name.to_s) { raise ArgumentError, "no engine #{name} (engines: #{ENGINES.keys.join(", ")})" }.new
+      end
+    end
+
+    # Reads each of `paths` with each of `engines` that is available and
+    # holds what it read against the file: a Report. `password` opens
+    # encrypted files.
+    def self.run(paths, engines: adapters, password: nil)
+      require_reader
+      available, missing = engines.partition(&:available?)
+      expectations = paths.to_h { |path| [path, expectation(path, password)] }
+      # Absolute, so no path reaches a tool as an option ("-o…").
+      absolute = paths.map { |path| File.expand_path(path) }
+      results = available.flat_map do |engine|
+        version = engine.version
+        engine.facts(absolute, password:).zip(paths).map do |facts, path|
+          Report::Result.new(file: path, engine: engine.name, version:,
+                             problems: problems(expectations[path], facts, engine))
+        end
+      end
+      Report.new(results: results.sort_by.with_index { |result, index| [paths.index(result.file), index] }, missing:)
+    end
+
+    def self.require_reader
+      require "pdf/reader"
+    rescue LoadError
+      raise Stationery::Error, Testing::Inspector::NEEDS_READER
+    end
+
+    def self.expectation(path, password)
+      Expectation.read(Testing::Inspector.new(Pathname(path), password:))
+    rescue StandardError => e
+      e # pdf-reader cannot read it: each engine is then held to opening it with no error, and the file fails
+    end
+
+    def self.problems(expectation, facts, engine)
+      return Comparison.new(expectation, facts, engine: engine.name).problems if expectation.is_a?(Expectation)
+
+      ["pdf-reader cannot read the file (#{expectation.class.name.split("::").last}: #{expectation.message}), " \
+       "so there is nothing to hold the engine to",
+       *Comparison.new(Expectation.new(pages: [], outline: [], fields: [], attachments: [], signatures: 0, valid: true,
+                                       tagged: false), facts.slice("errors", "warnings"), engine: engine.name).problems]
+    end
+  end
+end

data/lib/stationery/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Stationery
-  VERSION = "0.12.0"
+  VERSION = "0.12.2"
 end

data/lib/stationery.rb

@@ -11,6 +11,7 @@ require_relative "stationery/pdf/encryption/aes"
 require_relative "stationery/pdf/encryption/revision4"
 require_relative "stationery/pdf/encryption/revision6"
 require_relative "stationery/pdf/encryption/standard_security"
+require_relative "stationery/pdf/object_streams"
 require_relative "stationery/pdf/writer"
 require_relative "stationery/fonts/sfnt_metrics"
 require_relative "stationery/fonts/woff"
@@ -120,6 +121,7 @@ require_relative "stationery/pdf/signature/timestamp"
 require_relative "stationery/forms/metrics"
 require_relative "stationery/forms/typeface"
 require_relative "stationery/forms/field"
+require_relative "stationery/forms/auto_size"
 require_relative "stationery/forms/appearance"
 require_relative "stationery/forms/acro_form"
 require_relative "stationery/pdf/page_sealer"