stationery 0.12.1 → 0.12.3

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.1"
+  VERSION = "0.12.3"
 end

data/lib/stationery.rb

@@ -121,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"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: stationery
 version: !ruby/object:Gem::Version
-  version: 0.12.1
+  version: 0.12.3
 platform: ruby
 authors:
 - Mikael Henriksson
@@ -48,6 +48,7 @@ files:
 - examples/newsletter.rb
 - examples/packing_slip.rb
 - examples/postcard.rb
+- examples/price_card.rb
 - examples/price_list.rb
 - examples/receipt.rb
 - examples/report.rb
@@ -87,6 +88,7 @@ files:
 - lib/stationery/cli/pictures.rb
 - lib/stationery/cli/render.rb
 - lib/stationery/cli/skill.rb
+- lib/stationery/cli/verify.rb
 - lib/stationery/color.rb
 - lib/stationery/component.rb
 - lib/stationery/css.rb
@@ -144,6 +146,7 @@ files:
 - lib/stationery/fonts/woff.rb
 - lib/stationery/forms/acro_form.rb
 - lib/stationery/forms/appearance.rb
+- lib/stationery/forms/auto_size.rb
 - lib/stationery/forms/field.rb
 - lib/stationery/forms/metrics.rb
 - lib/stationery/forms/typeface.rb
@@ -354,6 +357,22 @@ files:
 - lib/stationery/text/wrapper/one_word.rb
 - lib/stationery/text/wrapper/remainder.rb
 - lib/stationery/units.rb
+- lib/stationery/verify.rb
+- lib/stationery/verify/allowlist.rb
+- lib/stationery/verify/command.rb
+- lib/stationery/verify/comparison.rb
+- lib/stationery/verify/engine.rb
+- lib/stationery/verify/engines/mupdf.rb
+- lib/stationery/verify/engines/pdfium.rb
+- lib/stationery/verify/engines/pdfjs.rb
+- lib/stationery/verify/engines/pdfkit.rb
+- lib/stationery/verify/engines/poppler.rb
+- lib/stationery/verify/engines/qpdf.rb
+- lib/stationery/verify/expectation.rb
+- lib/stationery/verify/report.rb
+- lib/stationery/verify/scripts/pdfium.py
+- lib/stationery/verify/scripts/pdfjs.mjs
+- lib/stationery/verify/scripts/pdfkit.swift
 - lib/stationery/version.rb
 - lib/stationery/warnings.rb
 - lib/stationery/zpl.rb