stationery 0.12.1 → 0.12.2

data/lib/stationery/forms/auto_size.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Forms
+    # The size `font_size: :auto` draws a field's value at: the largest that
+    # fits the field's box less its padding, no larger than `max_font_size:`
+    # and no smaller than `min_font_size:` (4 points by default, the smallest
+    # Chrome's PDFium auto-sizes to). Sizes are whole tenths of a point,
+    # rounded down.
+    #
+    # A typeface's widths and heights are linear in the size, so one line and
+    # a comb field's cells are arithmetic; wrapped lines are not, and their
+    # size is found by bisection. Only the typeface's measures are asked:
+    # nothing is drawn or named here.
+    class AutoSize
+      MIN = 4
+      # Measures are taken at this size and scaled: less rounding than at 1.
+      UNIT = 100.0
+
+      # The value broken into lines no wider than `width` at `size`, keeping
+      # its own line breaks; a word wider than a line stands alone.
+      def self.wrap(type, text, width, size)
+        text.split("\n", -1).flat_map do |paragraph|
+          paragraph.split.each_with_object([+""]) do |word, lines|
+            candidate = lines.last.empty? ? word : "#{lines.last} #{word}"
+            if lines.last.empty? || type.width(candidate, size) <= width
+              lines[-1] = candidate
+            else
+              lines << word
+            end
+          end
+        end
+      end
+
+      # `type` is the typeface the appearance draws with; `width` and
+      # `height` the widget's.
+      def initialize(field, type, width, height)
+        @field = field
+        @type = type
+        @inner_width = width - (2 * Appearance::PADDING)
+        @inner_height = height - (2 * Appearance::PADDING)
+        @cell = field.options[:comb] && width.fdiv(field.max_length)
+      end
+
+      def size
+        min = @field.min_font_size || [MIN, @field.max_font_size].compact.min
+        max = [tenth([@field.max_font_size, height_fit].compact.min), min].max
+        fit = @field.options[:multiline] && !@cell ? lines_fit(min, max) : [max, width_fit].compact.min
+        [tenth(fit), min].max
+      end
+
+      private
+
+      def value = @field.value.to_s
+      def tenth(size) = (size * 10).floor / 10.0
+      def per_point(measure) = measure / UNIT
+      def glyph_box = per_point(@type.ascent(UNIT) + @type.descent(UNIT))
+      def height_fit = @inner_height / glyph_box
+
+      # What the width allows one line, or the widest character a cell; nil
+      # when the value has no width.
+      def width_fit
+        return cell_fit if @cell
+
+        width = per_point(@type.width(value, UNIT))
+        @inner_width / width if width.positive?
+      end
+
+      def cell_fit
+        widest = value[0, @field.max_length].chars.map { |char| per_point(@type.width(char, UNIT)) }.max
+        @cell / widest if widest&.positive?
+      end
+
+      # The largest tenth in min..max at which the wrapped value fits.
+      def lines_fit(min, max)
+        low = (min * 10).ceil
+        high = (max * 10).floor
+        return min unless high >= low && fits?(low / 10.0)
+
+        while low < high
+          middle = (low + high + 1) / 2
+          fits?(middle / 10.0) ? low = middle : high = middle - 1
+        end
+        low / 10.0
+      end
+
+      def fits?(size)
+        lines = AutoSize.wrap(@type, value, @inner_width, size)
+        height = @type.ascent(size) + ((lines.size - 1) * size * Appearance::LEADING) + @type.descent(size)
+        height <= @inner_height && lines.all? { |line| @type.width(line, size) <= @inner_width }
+      end
+    end
+  end
+end

data/lib/stationery/forms/field.rb

@@ -16,13 +16,20 @@ module Stationery
                comb: 25 }.freeze
       DEFAULTS = { font_size: 10, read_only: false, required: false, border: "#9CA3AF", background: "#FFFFFF",
                    radius: 2, tooltip: nil }.freeze
+      # What a text field and a select take beyond the defaults: where the
+      # value sits, its colour, and the bounds of `font_size: :auto`.
+      BOUNDS = %i[min_font_size max_font_size].freeze
+      STYLE = [:align, :color, *BOUNDS].freeze
       OPTIONS = {
-        text: %i[multiline max_length comb], checkbox: [], radio: %i[checked], select: %i[options editable],
-        signature: %i[label]
+        text: [:multiline, :max_length, :comb, *STYLE], checkbox: [], radio: %i[checked],
+        select: [:options, :editable, *STYLE], signature: %i[label]
       }.freeze
       VARIABLE_TEXT = %i[text select].freeze
+      # The /Q (quadding) of each `align:` (PDF 32000-1, 12.7.3.3).
+      ALIGNMENTS = { left: 0, center: 1, right: 2 }.freeze
+      BLACK = Color.parse("#000000")
 
-      attr_reader :kind, :name, :value, :options, :typeface
+      attr_reader :kind, :name, :value, :options, :typeface, :color
 
       def initialize(kind, name, value: nil, typeface: Standard.new, **options)
         @kind = kind
@@ -33,12 +40,24 @@ module Stationery
         raise ArgumentError, "unknown #{kind} field option: #{unknown.join(", ")}" if unknown.any?
 
         @options = DEFAULTS.merge(options)
+        @color = Color.parse(@options.fetch(:color, BLACK))
         validate_comb
+        validate_style
+      end
+
+      # A copy with `changes` to its options.
+      def with(**changes)
+        self.class.new(@kind, @name, value: @value, typeface: @typeface, **@options, **changes)
       end
 
       def segments = @name.split(".")
       def type = TYPES.fetch(@kind)
       def font_size = @options[:font_size]
+      # Whether the value is drawn at the largest size that fits (`font_size: :auto`).
+      def auto_size? = font_size == :auto
+      def min_font_size = @options[:min_font_size]
+      def max_font_size = @options[:max_font_size]
+      def align = @options.fetch(:align, :left)
       # Whether a viewer redraws its text when the value changes.
       def variable_text? = VARIABLE_TEXT.include?(@kind)
       # The accessible name: `tooltip:`, a signature's label, else the name.
@@ -62,6 +81,7 @@ module Stationery
       def field_entries(value = field_value, default_appearance: nil)
         entries = { FT: type, TU: PDF::TextString.new(tooltip) }
         entries[:DA] = default_appearance if default_appearance
+        entries[:Q] = ALIGNMENTS.fetch(align) unless align == :left
         entries[:Ff] = flags if flags.positive?
         entries[:V] = value unless value.nil?
         entries[:MaxLen] = max_length if max_length
@@ -126,6 +146,28 @@ module Stationery
 
         raise ArgumentError, "a comb field needs max_length: (or comb: <cells>)"
       end
+
+      def validate_style
+        raise ArgumentError, "align: is :left, :center or :right, not #{align.inspect}" unless ALIGNMENTS.key?(align)
+
+        points(:font_size, " or :auto") unless auto_size?
+        BOUNDS.each do |key|
+          next unless @options.key?(key)
+          raise ArgumentError, "#{key}: needs font_size: :auto" unless auto_size?
+
+          points(key)
+        end
+        return unless min_font_size && max_font_size && min_font_size > max_font_size
+
+        raise ArgumentError, "min_font_size: #{min_font_size} is above max_font_size: #{max_font_size}"
+      end
+
+      def points(key, alternative = "")
+        value = @options[key]
+        return if value.is_a?(Numeric) && value.positive?
+
+        raise ArgumentError, "#{key}: is a number of points#{alternative}, not #{value.inspect}"
+      end
     end
   end
 end

data/lib/stationery/monochrome/painting.rb

@@ -47,6 +47,16 @@ module Stationery
         super
       end
 
+      # A field's value is text: its colour is reported, or snapped in /DA
+      # and the appearance alike. Its frame is drawn as it is.
+      def widget(field, x, y, w, h, tag: nil)
+        if field.variable_text?
+          color, = @monochrome.paint(field.color, :text, @page)
+          field = field.with(color:) unless color.equal?(field.color)
+        end
+        super
+      end
+
       # A gradient is reported by its stops; snapped, it is a black fill or nothing.
       def shade_path(path, shading, matrix:, even_odd: false, opacity: nil)
         return super unless shading.respond_to?(:stops)

data/lib/stationery/pdf/conformance.rb

@@ -27,6 +27,8 @@ module Stationery
       OUTPUT_CONDITION = "sRGB IEC61966-2.1"
       PRINT = 4
       CMYK_OPERATOR = /^(?:-?[\d.]+ ){4}[kK]$/
+      # The colour a field's /DA sets, after its font and size.
+      CMYK_DEFAULT_APPEARANCE = /Tf (?:-?[\d.]+ ){4}k\z/
       # What a character no font has does: :raise, or :replace to draw the
       # font's stand-in for it (see Fonts::Font#stand_in).
       MISSING_GLYPHS = %i[raise replace].freeze
@@ -174,7 +176,18 @@ module Stationery
         pages.each_with_index do |page, index|
           subjects << "CMYK colour on page #{index + 1}" if page.content.match?(CMYK_OPERATOR)
         end
-        subjects
+        subjects + cmyk_fields(pages)
+      end
+
+      # A field's appearance and /DA are not page content: each is read on its own.
+      def cmyk_fields(pages)
+        widgets = pages.flat_map(&:annotations).select { |annotation| annotation[:widget] && annotation[:appearance] }
+        widgets.select { |annotation| cmyk_paint?(annotation[:appearance].paints) }
+               .map { |annotation| %(CMYK colour in form field "#{annotation[:widget].name}") }.uniq
+      end
+
+      def cmyk_paint?(paints)
+        paints.any? { |paint| paint.match?(CMYK_OPERATOR) || paint.match?(CMYK_DEFAULT_APPEARANCE) }
       end
     end
   end

data/lib/stationery/skill/recipes/form.md.erb

@@ -23,17 +23,17 @@ class ApplicationFormPdf < Stationery::Document
     text "Membership application", size: 20, weight: :bold, heading: 1
     spacer 16
     row(gap: 12) do
-      labelled("Full name") { text_field "applicant.name", value: @name, required: true }
-      labelled("Email") { text_field "applicant.email" }
+      labelled("Full name") { text_field "applicant.name", value: @name, required: true, tooltip: "Full name" }
+      labelled("Email") { text_field "applicant.email", tooltip: "Email" }
     end
     spacer 10
     row(gap: 12) do
-      column(width: 90) { labelled_field("Postcode") { text_field "applicant.postcode", comb: 5 } }
-      labelled("Country") { select "applicant.country", options: %w[Sweden Norway Denmark], value: "Sweden" }
+      column(width: 90) { labelled_field("Postcode") { text_field "applicant.postcode", comb: 5, tooltip: "Postcode" } }
+      labelled("Country") { select "applicant.country", options: %w[Sweden Norway Denmark], value: "Sweden", tooltip: "Country" }
     end
     spacer 10
     labelled_field("Plan") do
-      radio "plan", "basic", label: "Basic"
+      radio "plan", "basic", label: "Basic", tooltip: "Plan"         # a radio group is named by its first choice
       radio "plan", "pro", label: "Pro", checked: true
     end
     spacer 10
@@ -72,7 +72,10 @@ end
   which paints the appearances the gem writes: `mutool draw -r 96 -o form-%d.png form.pdf`
   (`pdftoppm` draws the values but not the borders). `stationery inspect form.pdf` lists each
   field with its rectangle and value.
-- Fields keep PDF/A and PDF/UA (every field has an accessible name from `tooltip:` or its label).
+- Fields keep PDF/A and PDF/UA. Every field has an accessible name: its `tooltip:`, else a check
+  box's or signature field's `label:`, else its field name (`applicant.name`), which is what a
+  screen reader then says. So a text field, a select and a radio group get a `tooltip:`, as above:
+  the text printed beside a field is not its name.
 - Signing the file: `sign certificate:, key:, field: "signature"` fills the signature field with
   a digital signature (see [../reference/conformance.md](../reference/conformance.md)).
 - Every option of every field: [../reference/forms.md](../reference/forms.md) and <%= docs("forms") %>.

data/lib/stationery/skill/recipes/invoice.md.erb

@@ -93,9 +93,9 @@ class InvoicePdf < Stationery::Document
 
   def subtotal = @lines.sum { |line| line.quantity * line.unit_cents }
 
-  def vat_by_rate
-    @lines.group_by(&:vat_rate).transform_values do |lines|
-      (lines.sum { |line| line.quantity * line.unit_cents } * lines.first.vat_rate / 100.0).round
+  def vat_by_rate                                      # exact: Rational, rounded once per rate
+    @lines.group_by(&:vat_rate).to_h do |rate, lines|
+      [rate, (lines.sum { |line| line.quantity * line.unit_cents } * Rational(rate, 100)).round]
     end
   end
 
@@ -108,9 +108,12 @@ end
 
 ## What matters here
 
-- **Money is computed by the application**, in integer cents or `BigDecimal`, never in Floats;
-  the document only formats it. Totals are ordinary table rows: a cell `{ content:, colspan: }`
-  spans columns, `t.rows(-3..)` selects the last three rows.
+- **Money is integer cents** (or `BigDecimal`), never a Float. This document derives the line
+  amounts and VAT from its lines, exactly (`Rational(rate, 100)`, rounded once per rate); an
+  application whose invoice already holds its totals, as its books have them, passes those in
+  and the document only formats them, so the PDF cannot disagree with the ledger by a cent.
+  Totals are ordinary table rows: a cell `{ content:, colspan: }` spans columns, `t.rows(-3..)`
+  selects the last three rows.
 - **A table has black 0.5 pt borders on every cell by default.** `cell: { borders: [] }` takes
   them away; `borders: [:top]` on a selection draws one rule. `header: true` repeats the first row
   on every page the table continues onto; `t.zebra(from:, to:, color:)` stripes rows.
@@ -118,9 +121,10 @@ end
   as wide as the page.
 - **PDF/A-3b** (`conformance :pdf_a3b`) embeds the sRGB output intent and XMP identification, and
   raises `Stationery::ConformanceError` instead of writing a file that breaks the claim: a CMYK
-  colour, `encrypt`, or a character no font has (unless `missing_glyphs: :replace`, as above). Set
-  `metadata title:`. Transparency (a PNG logo with alpha) is allowed. Validate the file with
-  veraPDF: `verapdf --format text -v --flavour 3b invoice_pdf.pdf` prints `PASS` (`brew install
+  colour, or a character no font has (unless `missing_glyphs: :replace`, as above). `encrypt` with
+  a conformance level raises `ArgumentError` before anything renders: the two contradict each
+  other. Set `metadata title:`. Transparency (a PNG logo with alpha) is allowed. Validate the
+  file with veraPDF: `verapdf --format text -v --flavour 3b invoice_pdf.pdf` prints `PASS` (`brew install
   verapdf`; with Docker, see [../reference/conformance.md](../reference/conformance.md)).
 - An application that would rather send a plain PDF than none rescues the claim:
 

data/lib/stationery/skill/recipes/label.md.erb

@@ -73,7 +73,8 @@ every change:
    `CODE-128:SX0042771903` and `QR-Code:https://…`. A code it cannot read will not scan either.
 4. **Check the native commands** are in the ZPL: `grep -o '\^B[CQEX][^^]*' label.zpl` shows `^BC`
    (Code 128), `^BQ` (QR), `^BE` (EAN-13), `^BX` (Data Matrix). A barcode that is missing there
-   stayed in the picture (see below), which prints too, but not on the printer's own dot grid.
+   stayed in the picture (see below): it prints, on the dot grid as part of the `^GFA` graphic,
+   but drawn by stationery, not by the printer's own barcode encoder.
 5. **Warnings**: `label.warnings` after `to_zpl` (or `to_png`) lists what a one-bit printer
    cannot print as it is.
 
@@ -100,7 +101,8 @@ possibly another QR mask. (Online, labelary.com renders a `.zpl` file.)
   dot grid. A barcode the printer could not draw as it is stays in the picture without a word: one
   rotated or clipped, paler than half grey, a module wider than 10 dots (a QR code sized with a
   large `width:` at 300 dpi), or a QR code of text outside ASCII. Size a native QR code by
-  `module_size:` (1 to 2 pt) and check the ZPL has its `^BQ` line.
+  `module_size:`, at most 720 / dpi points so a module is 10 dots or fewer (3.5 pt at 203 dpi,
+  2.4 pt at 300, 1.2 pt at 600), and check the ZPL has its `^BQ` line.
   Send it to port 9100: `TCPSocket.open(host, 9100) { |s| label.to_zpl(s) }`.
   From the shell: `stationery render label_pdf.rb --zpl --dpi 300`.
 - **Black and white only.** A thermal printer prints black or nothing. `monochrome dpi: 203` reports

data/lib/stationery/skill/recipes/report.md.erb

@@ -6,6 +6,8 @@ the footer, a table that continues across pages and a chart. The examples in the
 `stationery examples accessible_report --source` (PDF/UA-1, a chart as a figure).
 
 ```ruby
+require "erb"                                          # ERB::Util.html_escape, for data written into SVG
+
 class ReportPdf < Stationery::Document
   ACCENT = "#0F766E"
   MUTED = "#6B7280"
@@ -63,14 +65,15 @@ class ReportPdf < Stationery::Document
     spacer 8
   end
 
-  # A bar chart as SVG, drawn from the data: there is no chart element.
+  # A bar chart as SVG, drawn from the data: there is no chart element. Text
+  # from the data is escaped, as "&" or "<" in it would break the XML.
   def chart
     top = @quarters.map(&:last).max
     bars = @quarters.each_with_index.map do |(label, value), i|
       height = (value / top * 150).round(1)
       x = 30 + (i * 110)
       %(<rect x="#{x}" y="#{170 - height}" width="70" height="#{height}" fill="currentColor"/>) +
-        %(<text x="#{x + 35}" y="190" font-size="12" text-anchor="middle">#{label}</text>) +
+        %(<text x="#{x + 35}" y="190" font-size="12" text-anchor="middle">#{ERB::Util.html_escape(label)}</text>) +
         %(<text x="#{x + 35}" y="#{164 - height}" font-size="11" text-anchor="middle">#{value}</text>)
     end
     %(<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 460 200">#{bars.join}</svg>)
@@ -91,13 +94,15 @@ end
   same page. `heading: 1..6` makes a heading in a tagged PDF; do not skip a level (1, then 3).
 - **Long tables** continue on the next page with `header: true` rows repeated; a row never splits
   unless it is taller than a page (or `split_rows: true`). Rows given as an Enumerator
-  (`Order.find_each.lazy.map { |o| [o.number, o.total] }`) to a table with a width for every
+  (`Order.preload(:customer).find_each.lazy.map { |o| [o.number, o.customer.name, o.total] }`,
+  preloading what each row reads) to a table with a width for every
   column (`widths: [80, 0.5, 90]`) are read as pages reach them, so the rows of about a page are
   held at a time, however many there are; such a table selects rows from its start only (`t.row(0)`, `t.rows(1..)`,
   `zebra`), and none of its cells may span rows. With a column without a width the rows are read
   when the table is built.
 - **Charts are SVG or `canvas`.** Build the SVG from the data as above (`currentColor` takes
-  `color:`, `<text>` is set in the document's fonts). An `svg` is drawn at its viewBox size in
+  `color:`, `<text>` is set in the document's fonts), and escape every string from the data with
+  `ERB::Util.html_escape`: an "&" or "<" in a label breaks the SVG or adds elements to it. An `svg` is drawn at its viewBox size in
   points, shrunk to the width there is; `width:` is points (`width: 1.0` is one point, not the
   whole width). Or draw the shapes on a canvas (its `text` takes a font object, so label a canvas
   chart with SVG or with `text` elements around it):

data/lib/stationery/testing/inspector.rb

@@ -10,8 +10,9 @@ require_relative "layout"
 module Stationery
   module Testing
     # Reads a rendered PDF back for assertions. The subject is a
-    # Stationery::Document, PDF bytes, a path (String or Pathname) or an IO.
-    # Needs the pdf-reader gem, loaded on first use.
+    # Stationery::Document, PDF bytes, a path (String or Pathname) or an IO;
+    # `password:` opens an encrypted one. Needs the pdf-reader gem, loaded on
+    # first use.
     class Inspector
       UTF16_BOM = "\xFE\xFF".b
       # id-aa-signatureTimeStampToken: a signature's RFC 3161 timestamp.
@@ -23,9 +24,11 @@ module Stationery
       COLOR_OPERATORS = { "g" => 1, "G" => 1, "rg" => 3, "RG" => 3, "k" => 4, "K" => 4 }.freeze
       NUMBER = /\A[-+]?(?:\d+\.?\d*|\.\d+)\z/
       LITERAL_STRING = /\((?:\\.|[^\\()])*\)/m
+      NEEDS_READER = 'Stationery::Testing needs pdf-reader: add gem "pdf-reader" to your test group'
 
-      def initialize(subject)
+      def initialize(subject, password: nil)
         @subject = subject
+        @password = password
       end
 
       def pdf
@@ -40,9 +43,9 @@ module Stationery
       def reader
         @reader ||= begin
           require "pdf/reader"
-          ::PDF::Reader.new(StringIO.new(pdf))
+          ::PDF::Reader.new(StringIO.new(pdf), **{ password: @password }.compact)
         rescue LoadError
-          raise Stationery::Error, 'Stationery::Testing needs pdf-reader: add gem "pdf-reader" to your test group'
+          raise Stationery::Error, NEEDS_READER
         end
       end
 

data/lib/stationery/testing/layout.rb

@@ -18,6 +18,9 @@ module Stationery
       # The Radio and Pushbutton flags of a button field's /Ff.
       RADIO = 1 << 15
       PUSHBUTTON = 1 << 16
+      ALIGNMENTS = %i[left center right].freeze
+      # The font size and colour operator of a /DA: "/F1 10 Tf 0.5 g".
+      DEFAULT_APPEARANCE = /([\d.]+) Tf\s+((?:-?[\d.]+\s+)+)(g|rg|k)\s*\z/
 
       def initialize(inspector)
         @inspector = inspector
@@ -98,10 +101,24 @@ module Stationery
           name = chain.filter_map { |field| field[:T] && decode(field[:T]) }.reverse.join(".")
           type = inherit(chain, :FT)
           { name:, type: field_type(type, inherit(chain, :Ff).to_i), value: value(inherit(chain, :V)),
-            **rect(widget, left, top), state: state(widget) }.compact
+            **rect(widget, left, top), state: state(widget), **style(chain) }.compact
         end
       end
 
+      # The alignment, size (:auto for 0) and colour a field's value is
+      # drawn in; nothing for a field without variable text.
+      def style(chain)
+        match = DEFAULT_APPEARANCE.match(inherit(chain, :DA).to_s) or return {}
+
+        size, values, operator = match.captures
+        values = values.split.map(&:to_f)
+        values *= 3 if operator == "g"
+        { align: ALIGNMENTS.fetch(inherit(chain, :Q).to_i, :left), font_size: size.to_f.zero? ? :auto : number(size),
+          color: Monochrome.hex(Color.new(operator == "k" ? :cmyk : :rgb, values)) }
+      end
+
+      def number(text) = text.include?(".") ? text.to_f : text.to_i
+
       def parents(widget)
         chain = [widget]
         chain << @objects.deref_hash(chain.last[:Parent]) while chain.last[:Parent] && chain.size < 32

data/lib/stationery/verify/allowlist.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Verify
+    # The engine messages that are the check's environment and not the PDF:
+    # each names the engine, a pattern and why. Everything else an engine
+    # says fails the check. An entry is added only once the cause is found
+    # in the engine's source and the file; a file that lacks what a viewer
+    # needs is a bug in the gem, not an entry here.
+    module Allowlist
+      ENTRIES = [
+        { engine: "pdfjs", pattern: /\AWarning: _getAppearance: OffscreenCanvas is not supported/,
+          why: "Node has no OffscreenCanvas. pdf.js builds a text field's appearance again when the form sets " \
+               "/NeedAppearances, which Forms::AcroForm does for a form that is neither signed nor PDF/A or " \
+               "PDF/UA, and warns whenever it builds one without OffscreenCanvas. Every widget carries its /AP." },
+        { engine: "poppler", pattern: /\ANSS_Init failed: security library: bad database\.\z/,
+          why: "pdfsig opens an NSS certificate database to judge trust, and says so when the machine has none " \
+               "(~/.pki/nssdb). Whether the signature verifies does not need it." },
+        { engine: "mupdf", pattern: /\Awarning: ICC support is not available\z/,
+          why: "Debian's mutool (mupdf-tools, in the verify image) is built without colour management and says so " \
+               "before it opens any file, even one that is not a PDF." }
+      ].freeze
+
+      def self.allows?(entries, engine, message)
+        entries.any? { |entry| entry[:engine] == engine && entry[:pattern].match?(message) }
+      end
+    end
+  end
+end

data/lib/stationery/verify/command.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "tempfile"
+require "tmpdir"
+
+module Stationery
+  module Verify
+    # Runs an engine's tool: an argument array, never through a shell, its
+    # output written to files as it runs (so a large one cannot block it),
+    # in `chdir` (the temporary directory unless asked: a tool that loads
+    # modules from where it runs must not load a checked file's neighbours),
+    # and its process group killed when it takes longer than `timeout`
+    # seconds (swift runs the compiled script as a child of its own).
+    module Command
+      POLL = 0.01 # seconds between looks at a running child
+
+      # `timeout` is the seconds the tool was given.
+      Result = Data.define(:stdout, :stderr, :status, :timed_out, :timeout) do
+        def success? = !timed_out && status&.success? == true
+        def exitstatus = status&.exitstatus
+      end
+
+      def self.run(*argv, env: {}, timeout: 60, chdir: Dir.tmpdir)
+        Tempfile.create("stationery-verify-out") do |out|
+          Tempfile.create("stationery-verify-err") do |err|
+            status, timed_out = spawn(argv, env:, timeout:, chdir:, out:, err:)
+            Result.new(stdout: read(out), stderr: read(err), status:, timed_out:, timeout:)
+          rescue SystemCallError => e # the program could not start: that tool's failure, not the run's
+            Result.new(stdout: "", stderr: "#{e.message}\n", status: nil, timed_out: false, timeout:)
+          end
+        end
+      end
+
+      def self.spawn(argv, env:, timeout:, chdir:, out:, err:)
+        # [program, argv0] never goes through a shell, whatever argv holds.
+        pid = Process.spawn(env, [argv.first, argv.first], *argv.drop(1), in: File::NULL, out:, err:, chdir:,
+                                                                          pgroup: true)
+        waited = wait(pid, timeout)
+      ensure
+        kill(pid) if pid && !waited
+      end
+
+      # What a tool wrote, as UTF-8 with anything that is not replaced.
+      def self.read(file) = File.read(file.path, encoding: Encoding::UTF_8).scrub
+
+      # The executable `name` on the PATH (or at `name`, a path from the
+      # working directory, answered absolute), or nil.
+      def self.which(name)
+        if name.include?(File::SEPARATOR)
+          path = File.expand_path(name)
+          return (path if File.file?(path) && File.executable?(path))
+        end
+
+        ENV.fetch("PATH", "").split(File::PATH_SEPARATOR).map { |dir| File.join(dir, name) }
+           .find { |path| File.file?(path) && File.executable?(path) }
+      end
+
+      def self.wait(pid, timeout)
+        deadline = Process.clock_gettime(Process::CLOCK_MONOTONIC) + timeout
+        loop do
+          _, status = Process.waitpid2(pid, Process::WNOHANG)
+          return [status, false] if status
+
+          break if Process.clock_gettime(Process::CLOCK_MONOTONIC) > deadline
+
+          sleep POLL
+        end
+        [kill(pid), true]
+      end
+
+      # Kills the child's process group and answers the child's status.
+      def self.kill(pid)
+        Process.kill(:KILL, -pid)
+        Process.waitpid2(pid).last
+      rescue Errno::ESRCH, Errno::ECHILD
+        nil # it was gone already
+      end
+    end
+  end
+end