stationery 0.12.1 → 0.12.3

data/lib/stationery/verify/comparison.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Verify
+    # Holds one engine's facts about a file (see Verify) against the
+    # Expectation and answers the problems, as lines a person reads. A fact
+    # the engine does not report (nil) is not held to anything; one it does
+    # report is held to the expectation.
+    #
+    # Text is "found", not "equal": both sides are normalized the same way
+    # (NFKC, no whitespace, no soft hyphens), then each of the expectation's
+    # lines for a page must appear in the engine's text for that page. Every
+    # error and warning is a problem unless the allowlist names it.
+    class Comparison
+      IGNORED = /[[:space:]\u00AD]/
+      # A list's marker: 1. 10) a. iv) or a bullet.
+      MARKER = /\A(?:\d{1,3}|[a-z]|[ivxlcdm]{1,6})[.)]\z|\A[\u2022\u25E6\u25AA\u2023\u2013\u2014*-]\z/i
+      MARKER_PREFIX = /\A(?:(?:\d{1,3}|[a-z]|[ivxlcdm]{1,6})[.)]|[\u2022\u25E6\u25AA\u2023\u2013\u2014*-])/i
+      SHOWN = 5 # text lines not found named on a page; the rest are counted
+      BARE_ORIGIN = %r{\A(https?://[^/?#]+)\z}i
+
+      def initialize(expectation, facts, engine:, allowlist: Allowlist::ENTRIES)
+        @expectation = expectation
+        @facts = facts
+        @engine = engine.to_s
+        @allowlist = allowlist
+      end
+
+      def problems
+        [*messages("errors", "error"), *messages("warnings", "warning"), *page_count, *pages, *fonts, *fields,
+         *listed("outline", @expectation.outline, ordered: true),
+         *listed("attachments", @expectation.attachments, ordered: false),
+         *signatures, *structure]
+      end
+
+      private
+
+      def messages(key, label)
+        Array(@facts[key]).uniq.reject { |message| Allowlist.allows?(@allowlist, @engine, message) }
+                          .map { |message| "#{label}: #{message}" }
+      end
+
+      def read_pages = Array(@facts["pages"])
+
+      def page_count
+        count = read_pages.size
+        expected = @expectation.pages.size
+        count == expected ? [] : ["#{count} pages, expected #{expected}"]
+      end
+
+      def pages
+        @expectation.pages.zip(read_pages).flat_map do |expected, read|
+          next [] unless read
+
+          [*text(expected, read["text"]), *painted(expected, read["painted"]), *links(expected, read["links"])]
+            .map { |problem| "page #{expected.number}: #{problem}" }
+        end
+      end
+
+      def text(expected, text)
+        return [] if text.nil?
+
+        found = normalize(text)
+        items = expected.lines.filter_map { |line| split_marker(line)[1] }
+        missing = expected.lines.reject { |line| found?(found, line, items) }
+        more = missing.size > SHOWN ? ["text not found: #{missing.size - SHOWN} more lines"] : []
+        missing.first(SHOWN).map { |line| "text not found: #{line.inspect}" } + more
+      end
+
+      # A line is found whole, or, when it starts with a list's marker, as
+      # the rest found whole with the marker right after it, or before it
+      # with nothing between them but other markers and other items of the
+      # page. The page draws a marker apart from its item (its own Lbl, its
+      # own colour) and an engine may read the markers as a column of their
+      # own (PDFKit on macOS 26: "1. 2. 3. First… Second… Third…").
+      def found?(found, line, items = [])
+        return true if whole?(found, normalize(line))
+
+        marker, rest = split_marker(line)
+        rest ? marked?(found, marker, rest, items) : false
+      end
+
+      # [marker, rest], normalized, for a line that starts with a marker.
+      def split_marker(line)
+        marker, rest = line.strip.split(/[[:space:]]+/, 2)
+        rest && marker.match?(MARKER) ? [normalize(marker), normalize(rest)] : []
+      end
+
+      def marked?(found, marker, rest, items)
+        offsets(found, rest).any? do |start|
+          found[start + rest.size, marker.size] == marker ||
+            offsets(found[0...start], marker).any? { |at| list?(found[(at + marker.size)...start], items) }
+        end
+      end
+
+      # Whether `gap` is made of markers and the items of the page's lists,
+      # every way of reading it tried (an item may start with something
+      # shaped like a marker: "3.5 mm screws"), each offset once.
+      def list?(gap, items, from = 0, seen = {})
+        return true if from == gap.size
+        return false if seen[from]
+
+        seen[from] = true
+        rest = gap[from..]
+        steps = [rest[MARKER_PREFIX], *items.select { |item| !item.empty? && rest.start_with?(item) }].compact
+        steps.any? { |step| list?(gap, items, from + step.size, seen) }
+      end
+
+      def offsets(text, part) = text.enum_for(:scan, part).map { Regexp.last_match.begin(0) }
+
+      # A line that ends in a hyphen is found without it too: an engine may
+      # join a word broken across lines (pdftotext does).
+      def whole?(found, line) = found.include?(line) || (line.end_with?("-") && found.include?(line.chomp("-")))
+
+      def normalize(text) = text.unicode_normalize(:nfkc).gsub(IGNORED, "")
+
+      def painted(expected, painted)
+        painted == false && expected.content ? ["painted blank, but it has content"] : []
+      end
+
+      def links(expected, links)
+        return [] if links.nil?
+
+        read = links.map { |link| target(link.transform_keys(&:to_sym)) }
+        count = read.size == expected.links.size ? [] : ["#{read.size} links, expected #{expected.links.size}"]
+        missing = expected.links.reject(&:empty?).reject do |link|
+          index = read.index(target(link))
+          read.delete_at(index) if index
+        end
+        count + missing.map { |link| "link not found: #{link.inspect}" }
+      end
+
+      # A web address with no path is the same with the "/" pdf.js adds.
+      def target(link) = link[:uri] ? { uri: link[:uri].sub(BARE_ORIGIN, '\\1/') } : link
+
+      def fonts
+        Array(@facts["fonts"]).flat_map do |font|
+          [("font #{font["name"]} is not embedded" if font["embedded"] == false),
+           ("font #{font["name"]} has no ToUnicode" if font["unicode"] == false)].compact
+        end
+      end
+
+      def fields
+        read = @facts["fields"]
+        return [] if read.nil?
+
+        @expectation.fields.flat_map do |field|
+          widgets = read.select { |widget| widget["name"] == field[:name] }
+          next ["field #{field[:name]} not found"] if widgets.empty?
+
+          [*value(field, widgets), *appearance(field, widgets)]
+        end
+      end
+
+      def appearance(field, widgets)
+        return [] unless field[:visible] && widgets.any? { |widget| widget["appearance"] == false }
+
+        ["field #{field[:name]} has no appearance"]
+      end
+
+      def value(field, widgets)
+        return [] unless field[:type] == :text && field[:value].is_a?(String)
+
+        values = widgets.filter_map { |widget| widget["value"] }
+        values.reject { it == field[:value] }.first(1).map do |value|
+          "field #{field[:name]} holds #{value.inspect}, expected #{field[:value].inspect}"
+        end
+      end
+
+      def listed(key, expected, ordered:)
+        read = @facts[key]
+        return [] if read.nil? || (ordered ? read == expected : read.sort == expected.sort)
+
+        ["#{key} #{read.inspect}, expected #{expected.inspect}"]
+      end
+
+      def signatures
+        read = @facts["signatures"]
+        return [] if read.nil?
+
+        expected = @expectation.signatures
+        count = read["count"] == expected ? [] : ["#{read["count"]} signatures, expected #{expected}"]
+        count + (read["valid"] == false ? ["a signature does not verify"] : [])
+      end
+
+      def structure
+        @facts["structure"] == false && @expectation.tagged ? ["no structure tree, but the file is tagged"] : []
+      end
+    end
+  end
+end

data/lib/stationery/verify/engine.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+require "json"
+require "tempfile"
+require "tmpdir"
+
+module Stationery
+  module Verify
+    # What every engine adapter answers: its `name`, the line that
+    # installs it, whether it is `available?`, its `version`, and
+    # `facts(paths, password:)`, one Hash of facts per path (see Verify).
+    class Engine
+      TIMEOUT = 60 # seconds for each file
+
+      def name = self.class::NAME
+      def install = self.class::INSTALL
+
+      private
+
+      def run(*argv, env: {}, timeout: TIMEOUT, **) = Command.run(*argv, env:, timeout:, **)
+
+      def failed(path, message) = { "file" => path, "pages" => [], "errors" => [message], "warnings" => [] }
+
+      # Why a tool failed, from its result: timed out, or its exit status
+      # and the last lines it wrote to stderr.
+      def failure(tool, result)
+        return "#{tool} timed out after #{result.timeout} s" if result.timed_out
+
+        ended = result.exitstatus ? "exited #{result.exitstatus}" : "did not finish"
+        ["#{tool} #{ended}", *result.stderr.lines.last(3).map(&:strip)].join(": ")
+      end
+
+      def lines(text) = text.to_s.lines.map(&:strip).reject(&:empty?)
+
+      # Whether a binary PGM (P5, 8-bit) has a pixel that is not white.
+      def painted?(pgm)
+        header = pgm.match(/\AP5\s+(\d+)\s+(\d+)\s+(\d+)\s/n) or return false
+        width = header[1].to_i
+        height = header[2].to_i
+        pixels = pgm.byteslice(header[0].bytesize, width * height).to_s
+        pixels.count("\xFF".b) != pixels.bytesize
+      end
+
+      # Runs a script that prints one JSON line of facts per path; a path
+      # the script did not answer for fails with why the script stopped.
+      def scripted(argv, paths, env:)
+        result = run(*argv, *paths, env:, timeout: (TIMEOUT * paths.size) + TIMEOUT)
+        answers = lines(result.stdout).select { |line| line.start_with?("{") }.filter_map { |line| parse(line) }
+        read = answers.to_h { |facts| [facts["file"], facts] }
+        paths.map { |path| read.fetch(path) { failed(path, failure(argv.first, result)) } }
+      end
+
+      # A line that is not JSON answers for no file, which then fails.
+      def parse(line)
+        JSON.parse(line)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def password_env(password) = password ? { "STATIONERY_VERIFY_PASSWORD" => password } : {}
+    end
+  end
+end

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

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Verify
+    module Engines
+      # MuPDF (`mutool draw`): each page drawn in grey and as text. What it
+      # writes on stderr fails the check. mutool takes a password on its
+      # command line only, where other local processes can read it.
+      class Mupdf < Engine
+        NAME = "mupdf"
+        INSTALL = "brew install mupdf, or apt-get install mupdf-tools"
+
+        def available? = !Command.which("mutool").nil?
+        def version = "mutool #{run("mutool", "-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)
+          options = password ? ["-p", password] : []
+          draws = %w[pgm txt].map do |format|
+            run("mutool", "draw", "-q", *options, "-r", "36", "-F", format, "-o", File.join(dir, "p%d.#{format}"), path)
+          end
+          errors = draws.reject(&:success?).map { |draw| failure("mutool draw", draw) }
+          { "file" => path, "pages" => pages(dir), "errors" => errors,
+            "warnings" => draws.flat_map { |draw| lines(draw.stderr) }.uniq }
+        end
+
+        # The pages MuPDF drew, in order, each with its picture and its text.
+        def pages(dir)
+          pictures = Dir[File.join(dir, "p*.pgm")].sort_by { |file| file[/(\d+)\.pgm\z/, 1].to_i }
+          pictures.map.with_index(1) do |picture, number|
+            text = File.join(dir, "p#{number}.txt")
+            { "number" => number, "painted" => painted?(File.binread(picture)),
+              "text" => File.exist?(text) ? File.read(text, encoding: Encoding::UTF_8) : nil }
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Verify
+    module Engines
+      # PDFium, the engine of Chrome and Edge, through pypdfium2 and
+      # scripts/pdfium.py. STATIONERY_PYTHON names the Python that has it.
+      class Pdfium < Engine
+        NAME = "pdfium"
+        INSTALL = "pip install pypdfium2 (STATIONERY_PYTHON names the Python that has it)"
+        SCRIPT = File.expand_path("../scripts/pdfium.py", __dir__)
+        VERSION = "import pypdfium2.version as v; print(v.PYPDFIUM_INFO, v.PDFIUM_INFO)"
+
+        # -P everywhere: Python loads no module from beside the script or from
+        # the working directory, and still finds a pip install --user.
+        def available? = !Command.which(python).nil? && run(python, "-P", "-c", "import pypdfium2").success?
+
+        def version
+          versions = run(python, "-P", "-c", VERSION).stdout.split
+          "pypdfium2 #{versions[0]}, PDFium #{versions[1]}"
+        end
+
+        def facts(paths, password: nil) = scripted([python, "-P", SCRIPT], paths, env: password_env(password))
+
+        private
+
+        # Absolute: the tools run in the temporary directory.
+        def python
+          name = ENV.fetch("STATIONERY_PYTHON", "python3")
+          name.include?(File::SEPARATOR) ? File.expand_path(name) : name
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Verify
+    module Engines
+      # pdf.js, the engine of Firefox, through Node, pdfjs-dist and
+      # scripts/pdfjs.mjs. STATIONERY_PDFJS names pdfjs-dist's directory;
+      # without it, the one Node resolves from the working directory, whose
+      # code then runs: set STATIONERY_PDFJS where that directory is not yours.
+      class Pdfjs < Engine
+        NAME = "pdfjs"
+        INSTALL = "npm i pdfjs-dist (STATIONERY_PDFJS names its directory)"
+        SCRIPT = File.expand_path("../scripts/pdfjs.mjs", __dir__)
+        RESOLVE = "console.log(require('path').dirname(require.resolve('pdfjs-dist/package.json')))"
+
+        def available? = !directory.nil?
+        def version = "pdfjs-dist #{JSON.parse(File.read(File.join(directory, "package.json")))["version"]}"
+
+        def facts(paths, password: nil)
+          scripted(["node", SCRIPT], paths, env: { "STATIONERY_PDFJS" => directory, **password_env(password) })
+        end
+
+        private
+
+        def directory
+          return @directory if defined?(@directory)
+
+          found = ENV["STATIONERY_PDFJS"] ? File.expand_path(ENV["STATIONERY_PDFJS"]) : resolved
+          @directory = found if found && File.file?(File.join(found, "legacy/build/pdf.mjs"))
+        end
+
+        def resolved
+          return unless Command.which("node")
+
+          result = run("node", "-e", RESOLVE, chdir: Dir.pwd)
+          result.stdout.strip if result.success?
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module Stationery
+  module Verify
+    module Engines
+      # PDFKit, the engine of Preview and Safari, through scripts/pdfkit.swift.
+      # macOS only; Swift comes with Xcode or its command line tools.
+      class Pdfkit < Engine
+        NAME = "pdfkit"
+        INSTALL = "macOS only: xcode-select --install"
+        SCRIPT = File.expand_path("../scripts/pdfkit.swift", __dir__)
+
+        def available? = RUBY_PLATFORM.include?("darwin") && !Command.which("swift").nil?
+        def version = "macOS #{run("sw_vers", "-productVersion").stdout.strip}"
+
+        def facts(paths, password: nil) = scripted(["swift", SCRIPT], paths, env: password_env(password))
+      end
+    end
+  end
+end

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