fontisan 0.4.46 → 0.4.48

data/scripts/corpus/generate_goldens.rb

@@ -0,0 +1,282 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "fontisan"
+require "json"
+require "digest"
+require "fileutils"
+require "tmpdir"
+
+# Read goldens for the reference corpus (fontist/fontisan#156 card 0b).
+#
+# One JSON file per manifest font, written through Fontisan::Reference (the
+# canonical serialisations are in docs/reference-facade.md):
+#
+#   corpus/goldens/read/<id>.json         ci tier, committed
+#   corpus/goldens/read-large/<id>.json   large tier, generated in CI (nightly)
+#
+# A golden holds the `read` result for each loading mode and lazy flag
+# (identical variants collapse to {"same_as" => key}), the `audit` result with
+# and without --validate, and the known_reference_bug tags from
+# corpus/TRIAGE.md. Malformed fonts belong to card 0e and are not covered here.
+module CorpusGoldens
+  ROOT = File.expand_path("../..", __dir__)
+  MANIFEST = File.join(ROOT, "corpus", "manifest.json")
+  GOLDEN_DIRS = { "ci" => "read", "large" => "read-large" }.freeze
+  SWALLOW_DIR = File.join(ROOT, "corpus", "goldens", "read", "_swallow")
+  DIVERGE_DIR = File.join(ROOT, "corpus", "goldens", "read", "_diverge")
+  MALFORMED = /\Amalformed-/
+  VARIANTS = [[:metadata, true], [:metadata, false], [:full, true], [:full, false]].freeze
+  SCHEMA = 1
+
+  # TRIAGE.md ids of Ruby results that are kept as the reference (the golden
+  # keeps Ruby's output and Rust reproduces it). Keyed by manifest id; "*"
+  # applies to every font.
+  KNOWN_REFERENCE_BUGS = {
+    "fonttools-test-t1-pfb" => %w[T1-READ],
+    "fonttools-test-t1-pfa" => %w[T1-READ],
+    "fonttools-test-woff" => %w[WOFF-CHECKS],
+    "fonttools-test-woff2" => %w[WOFF-CHECKS],
+    "source-sans-3-regular-otf-woff" => %w[WOFF-CHECKS],
+    "source-sans-3-regular-otf-woff2" => %w[WOFF-CHECKS],
+    "source-sans-3-regular-ttf-woff" => %w[WOFF-CHECKS],
+    "source-sans-3-regular-ttf-woff2" => %w[WOFF-CHECKS],
+    "noto-sans-vf-wdth-wght" => %w[MVAR-OFFSET],
+    "source-sans-3-vf-italic-ttf" => %w[MVAR-OFFSET],
+    "source-sans-3-vf-upright-cff2" => %w[MVAR-OFFSET CFF2-PARSER],
+    "source-sans-3-vf-upright-ttf" => %w[MVAR-OFFSET],
+    "quirk-name-format-1" => %w[NAME-FORMAT1],
+    "names-mac-roman-only" => %w[NAME-MAC-DECODE],
+  }.freeze
+
+  # NAME-FULL-REGULAR is derived: it applies to every font whose audit carries
+  # the full-name message, so a new font cannot be missed.
+  FULL_NAME_MESSAGE = /Full name .* doesn't match Family \+ Subfamily/
+  FULL_NAME_TAG = "NAME-FULL-REGULAR"
+
+  module_function
+
+  def manifest
+    JSON.parse(File.read(MANIFEST)).fetch("fonts")
+  end
+
+  def entries(tier)
+    manifest.select { |f| f["tier"] == tier && !f["id"].match?(MALFORMED) }
+  end
+
+  def font_path(entry)
+    dir = entry["type"] == "derived" ? "derived" : File.join("fonts", entry["id"])
+    File.join(ROOT, "corpus", dir, entry["file"])
+  end
+
+  def golden_dir(tier)
+    File.join(ROOT, "corpus", "goldens", GOLDEN_DIRS.fetch(tier))
+  end
+
+  def golden_path(tier, id)
+    File.join(golden_dir(tier), "#{id}.json")
+  end
+
+  # Goldens are only meaningful with the loader's env overrides unset.
+  def assert_clean_env!
+    bad = %w[FONTISAN_MODE FONTISAN_LAZY].select { |k| ENV.key?(k) }
+    raise "unset #{bad.join(', ')} before generating goldens" unless bad.empty?
+  end
+
+  # The error as data: class and message with the path reduced to a basename.
+  def outcome(path)
+    { "ok" => yield }
+  rescue StandardError => e
+    msg = e.message.gsub(path, File.basename(path)).gsub("#{File.dirname(path)}/", "")
+    { "error" => { "class" => e.class.name, "message" => msg } }
+  end
+
+  def read_variants(path)
+    seen = {}
+    VARIANTS.each_with_object({}) do |(mode, lazy), out|
+      key = "#{mode}/#{lazy ? 'lazy' : 'eager'}"
+      result = outcome(path) { Fontisan::Reference.read(path, mode: mode, lazy: lazy) }
+      comparable = strip_variant(result)
+      out[key] = seen[comparable] ? { "same_as" => seen[comparable] } : result
+      seen[comparable] ||= key
+    end
+  end
+
+  # The variant itself is the key, so `mode` and `lazy` do not make otherwise
+  # identical results differ.
+  def strip_variant(result)
+    return result unless result["ok"]
+
+    { "ok" => result["ok"].map { |face| face.except("mode", "lazy") } }
+  end
+
+  def audit_variants(path)
+    {
+      "default" => outcome(path) { Fontisan::Reference.audit(path, validate: false) },
+      "validate" => outcome(path) { Fontisan::Reference.audit(path, validate: true) },
+    }
+  end
+
+  def reference_bugs(id, audit)
+    tags = KNOWN_REFERENCE_BUGS.fetch(id, []).dup
+    tags << FULL_NAME_TAG if JSON.generate(audit).match?(FULL_NAME_MESSAGE)
+    tags.sort
+  end
+
+  def golden(entry, tier)
+    path = font_path(entry)
+    doc = {
+      "schema" => SCHEMA,
+      "id" => entry["id"],
+      "file" => File.basename(path),
+      "tier" => tier,
+      "font_sha256" => entry.fetch("sha256"),
+      "comparison_class" => "exact",
+      "generated_in" => tier == "large" ? "ci" : "any",
+      "read" => read_variants(path),
+      "audit" => audit_variants(path),
+    }
+    doc["known_reference_bug"] = reference_bugs(entry["id"], doc["audit"])
+    Fontisan::Reference.canonical_json(doc)
+  end
+
+  # Cases that hit the audit's error-swallowing paths on purpose, so a native
+  # tier reproduces them: GSUB/GPOS scripts and features answer [] when the
+  # table cannot be parsed (`collect_features`), and total_glyphs answers 0
+  # when maxp cannot be read. Each is TestTTF with one table replaced; the
+  # input font is committed next to its golden.
+  SWALLOW_SOURCE = "fonttools-test-ttf"
+  GARBAGE_LAYOUT = ([1, 0, 10, 10, 10].pack("n*") + ("\xFF".b * 6)).freeze
+  SWALLOW_CASES = {
+    "gsub-garbage" => ->(_tables) { { "GSUB" => GARBAGE_LAYOUT } },
+    "gpos-garbage" => ->(_tables) { { "GPOS" => GARBAGE_LAYOUT } },
+    "maxp-truncated" => ->(tables) { { "maxp" => tables.fetch("maxp").byteslice(0, 4) } },
+  }.freeze
+
+  # { path => bytes } for every swallow case: the input font and its golden.
+  def swallow
+    source = Fontisan::FontLoader.load(font_path(manifest.find { |e| e["id"] == SWALLOW_SOURCE }))
+    tables = source.table_data
+    SWALLOW_CASES.each_with_object({}) do |(name, change), out|
+      font = Fontisan::FontWriter.write_font(tables.merge(change.call(tables)))
+      input = File.join(SWALLOW_DIR, "#{name}.ttf")
+      out[input] = font
+      out[File.join(SWALLOW_DIR, "#{name}.json")] = swallow_golden(name, font)
+    end
+  end
+
+  def swallow_golden(name, font)
+    Dir.mktmpdir("swallow") do |dir|
+      path = File.join(dir, "#{name}.ttf")
+      File.binwrite(path, font)
+      Fontisan::Reference.canonical_json(
+        "schema" => SCHEMA, "case" => name, "source" => SWALLOW_SOURCE,
+        "font_sha256" => Digest::SHA256.hexdigest(font), "comparison_class" => "exact",
+        "known_reference_bug" => [],
+        "read" => { "full/eager" => outcome(path) { Fontisan::Reference.read(path, mode: :full, lazy: false) } },
+        "audit" => audit_variants(path)
+      )
+    end
+  end
+
+  # Divergences found after Phase 0 that the dedupe above or the malformed
+  # goldens never exercised (fontisan-rs docs/divergences.md):
+  #
+  # 1. WOFF1 `read` echoes the requested mode in each face's "mode". The read
+  #    goldens collapse variants with `same_as` and strip `mode` first, so it
+  #    was never compared for WOFF1. woff1-mode.json keeps all four variants
+  #    explicit, with no dedupe, for every WOFF1 font in the ci tier.
+  # 2. audit(validate: true) on a bad table checksum yields one fatal
+  #    "Check table_directory failed to execute" (BinData::Uint32be#to_s(16)
+  #    takes no argument). Tagged CHECKSUM-BINDATA: Rust reproduces it.
+  BAD_CHECKSUM = "malformed-bad-checksum"
+  CHECKSUM_TAG = "CHECKSUM-BINDATA"
+
+  def woff1_entries
+    entries("ci").select { |e| e["file"].end_with?(".woff") }
+  end
+
+  def woff1_mode_golden
+    cases = woff1_entries.to_h do |e|
+      path = font_path(e)
+      variants = VARIANTS.to_h do |mode, lazy|
+        key = "#{mode}/#{lazy ? 'lazy' : 'eager'}"
+        [key, outcome(path) { Fontisan::Reference.read(path, mode: mode, lazy: lazy) }]
+      end
+      [e["id"], { "font_sha256" => e.fetch("sha256"), "read" => variants }]
+    end
+    Fontisan::Reference.canonical_json(
+      "schema" => SCHEMA, "case" => "woff1-mode", "comparison_class" => "exact",
+      "known_reference_bug" => [], "cases" => cases
+    )
+  end
+
+  def bad_checksum_golden
+    entry = manifest.find { |e| e["id"] == BAD_CHECKSUM }
+    path = font_path(entry)
+    Fontisan::Reference.canonical_json(
+      "schema" => SCHEMA, "case" => "bad-checksum-validate", "source" => BAD_CHECKSUM,
+      "file" => File.basename(path), "font_sha256" => entry.fetch("sha256"),
+      "comparison_class" => "exact", "known_reference_bug" => [CHECKSUM_TAG],
+      "audit" => audit_variants(path)
+    )
+  end
+
+  def diverge
+    {
+      File.join(DIVERGE_DIR, "woff1-mode.json") => woff1_mode_golden,
+      File.join(DIVERGE_DIR, "bad-checksum-validate.json") => bad_checksum_golden,
+    }
+  end
+
+  # Every golden of a tier as { path => bytes }, generated fresh.
+  def generate(tier)
+    assert_clean_env!
+    out = entries(tier).to_h { |e| [golden_path(tier, e["id"]), golden(e, tier)] }
+    out.merge!(swallow).merge!(diverge) if tier == "ci"
+    out
+  end
+
+  def write(tier)
+    out = generate(tier)
+    FileUtils.mkdir_p(golden_dir(tier))
+    out.each do |path, bytes|
+      FileUtils.mkdir_p(File.dirname(path))
+      File.binwrite(path, bytes)
+    end
+    out.size
+  end
+
+  # Compare fresh output with the committed goldens. Returns problem strings.
+  def verify(tier)
+    problems = []
+    fresh = generate(tier)
+    fresh.each do |path, bytes|
+      rel = path.delete_prefix("#{ROOT}/")
+      next problems << "missing golden #{rel}" unless File.exist?(path)
+
+      committed = File.binread(path).force_encoding(bytes.encoding)
+      problems << "golden differs #{rel}#{first_difference(committed, bytes)}" unless committed == bytes
+    end
+    problems.concat(stale(tier, fresh.keys))
+  end
+
+  def stale(tier, expected)
+    Dir.glob(File.join(golden_dir(tier), "**", "*.{json,ttf}")).reject { |p| expected.include?(p) }
+      .map { |p| "stale golden #{p.delete_prefix("#{ROOT}/")} (no manifest font)" }
+  end
+
+  def first_difference(committed, fresh)
+    return " (binary, #{committed.bytesize} vs #{fresh.bytesize} bytes)" unless fresh.encoding == Encoding::UTF_8
+
+    a = committed.force_encoding("UTF-8").lines
+    b = fresh.lines
+    n = a.zip(b).index { |x, y| x != y }
+    n ? " at line #{n + 1}: committed #{a[n]&.strip.inspect} fresh #{b[n]&.strip.inspect}" : ""
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  tier = ARGV.fetch(0, "ci")
+  puts "wrote #{CorpusGoldens.write(tier)} goldens (tier #{tier})"
+end

data/scripts/corpus/generate_malformed_goldens.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+# Malformed-input goldens (fontist/fontisan#156, card 0e).
+#
+# For each committed malformed font (manifest entries with "malformed_kind")
+# this records what the Ruby reference does on each operation: outcome, error
+# class, normalised message (paths and numbers masked), position/context
+# markers and the point where it fails. Read-type operations go through
+# Fontisan::Reference; the per-step probe (load, name, table reads) uses
+# FontLoader directly because the facade has no per-step operation.
+#
+#   ruby scripts/corpus/generate_malformed_goldens.rb [--check]
+#
+# Writes corpus/goldens/malformed/<id>.json. --check compares instead of writing
+# (used by rake corpus:malformed:verify).
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "fontisan"
+require "digest"
+require "fileutils"
+require "json"
+require "timeout"
+
+module MalformedGoldens
+  ROOT = File.expand_path("../..", __dir__)
+  MANIFEST = File.join(ROOT, "corpus", "manifest.json")
+  DERIVED_DIR = File.join(ROOT, "corpus", "derived")
+  GOLDEN_DIR = File.join(ROOT, "corpus", "goldens", "malformed")
+
+  # The Ruby reference itself never returns on a few fuzz-found inputs (a cmap
+  # format 12 group spanning the u32 range, a CFF2 INDEX of 2^32 entries). An
+  # operation that runs past this many seconds is recorded as outcome "timeout";
+  # the tiers are then only required to finish without crashing (see
+  # {.matches?}). Real fonts take milliseconds.
+  OP_TIMEOUT = 5
+
+  COMBOS = [[:metadata, true], [:metadata, false],
+            [:full, true], [:full, false]].freeze
+
+  # Steps tried in order after a load; the first failing one is the failure
+  # point. table_cmap is full-mode only (metadata gates it out by design).
+  STEPS = %w[load name table_head table_cmap].freeze
+
+  PATH_RE = %r{(?<![\w/])(?:[A-Za-z]:)?(?:\.{0,2}/)(?:[\w.~+-]+/)*[\w.~+-]*|
+               (?:[\w.~+-]+/)*[\w.~+-]+\.(?:ttf|otf|ttc|otc|woff2?|dfont|pf[ab]|json|rb)\b}x
+  HEX_RE = /0x\h+/i
+  NUM_RE = /\d+/
+
+  MARKER_RES = [
+    /end of file reached/i,
+    /\boffset\s*[:=]?\s*\d+/i,
+    /\bposition\s*[:=]?\s*\d+/i,
+    /\bbyte\s+\d+/i,
+    /\bglyph\s+\d+/i,
+    /\bindex\s+\d+/i,
+    /\btable\s+['"][^'"]{1,4}['"]/i,
+  ].freeze
+
+  module_function
+
+  def entries
+    JSON.parse(File.read(MANIFEST)).fetch("fonts")
+      .select { |e| e["malformed_kind"] }.sort_by { |e| e["id"] }
+  end
+
+  # Mask paths first (they contain digits), then hex, then decimal numbers.
+  def normalize_message(message)
+    message.to_s.gsub(PATH_RE, "<PATH>").gsub(HEX_RE, "<HEX>").gsub(NUM_RE, "<N>")
+  end
+
+  def markers(*messages)
+    messages.compact.flat_map do |m|
+      MARKER_RES.flat_map { |re| m.scan(re).map { |s| normalize_message(s.downcase) } }
+    end.uniq.sort
+  end
+
+  def causes(exception)
+    out = []
+    cause = exception.cause
+    while cause && out.size < 5
+      out << { class: cause.class.name, message: normalize_message(cause.message) }
+      cause = cause.cause
+    end
+    out
+  end
+
+  def error_record(exception)
+    {
+      outcome: "error",
+      error_class: exception.class.name,
+      message: normalize_message(exception.message),
+      markers: markers(exception.message, *causes(exception).map { |c| c[:message] }),
+      causes: causes(exception),
+    }
+  end
+
+  def attempt(&)
+    { outcome: "ok" }.merge(Timeout.timeout(OP_TIMEOUT, &) || {})
+  rescue Timeout::Error
+    { outcome: "timeout" }
+  rescue StandardError => e
+    error_record(e)
+  end
+
+  def digest(data)
+    Digest::SHA256.hexdigest(Fontisan::Reference.canonical_json(data))
+  end
+
+  def probe_step(step, path, mode, lazy, font)
+    case step
+    when "load"
+      attempt { { format: Fontisan::FontLoader.detect_format(path).to_s } }
+    when "name"
+      attempt { { family: font.table("name").english_name(1) } }
+    when "table_head"
+      attempt { { units_per_em: font.table("head").units_per_em } }
+    when "table_cmap"
+      attempt { { mappings: font.table("cmap").unicode_mappings.size } }
+    end
+  end
+
+  # load, name, table reads, read: per (mode, lazy).
+  def combo(path, mode, lazy)
+    steps = {}
+    font = nil
+    steps["load"] = attempt do
+      font = Fontisan::FontLoader.load(path, mode: mode, lazy: lazy)
+      { format: font.class.name }
+    end
+    (STEPS - ["load"]).each do |step|
+      next if step == "table_cmap" && mode == :metadata
+
+      steps[step] = if font
+                      probe_step(step, path, mode, lazy, font)
+                    else
+                      { outcome: "skipped", reason: "load failed" }
+                    end
+    end
+    font.close if font.respond_to?(:close)
+    steps["read"] = attempt do
+      faces = Fontisan::Reference.read(path, mode: mode, lazy: lazy)
+      { faces: faces.size, digest: digest(faces) }
+    end
+    failing = STEPS.find { |s| steps[s] && steps[s][:outcome] == "error" }
+    { failure_point: failing, ops: steps }
+  end
+
+  def audit(path)
+    attempt do
+      reports = Fontisan::Reference.audit(path)
+      { faces: reports.size, digest: digest(reports) }
+    end
+  end
+
+  def scan(path)
+    rows = Timeout.timeout(OP_TIMEOUT) { Fontisan::Reference.scan([path]) }
+    rows.each { |r| r["path"] = File.basename(r["path"]) }
+    {
+      outcome: "ok",
+      rows: rows.size,
+      digest: digest(rows),
+      summary: rows.map { |r| scan_summary(r) },
+    }
+  rescue Timeout::Error
+    { outcome: "timeout" }
+  rescue StandardError => e
+    error_record(e)
+  end
+
+  def scan_summary(row)
+    errors = row["errors"].transform_values do |err|
+      next nil unless err
+
+      { class: err["class"], message: normalize_message(err["message"]),
+        markers: markers(err["message"]),
+        cause: err["cause"] && { class: err["cause"]["class"],
+                                 message: normalize_message(err["cause"]["message"]) } }
+    end
+    { format: row["format"], num_faces: row["num_faces"],
+      validation_status: row["validation"] && row["validation"]["status"],
+      errors: errors }
+  end
+
+  def golden(entry, dir: DERIVED_DIR)
+    path = File.join(dir, entry.fetch("file"))
+    {
+      id: entry["id"], kind: entry["malformed_kind"], file: entry["file"],
+      file_sha256: Digest::SHA256.file(path).hexdigest,
+      comparison: "exact",
+      combos: COMBOS.to_h { |m, l| ["#{m}/lazy=#{l}", combo(path, m, l)] },
+      audit: audit(path),
+      scan: scan(path)
+    }
+  end
+
+  def render(entry, dir: DERIVED_DIR)
+    Fontisan::Reference.canonical_json(golden(entry, dir: dir))
+  end
+
+  def golden_path(entry)
+    File.join(GOLDEN_DIR, "#{entry['id']}.json")
+  end
+
+  # Whether +actual+ (parsed render) equals +want+ (parsed golden). A node the
+  # reference timed out on matches whatever the tier returned, because that
+  # operation has no reference result; a crash would have killed the process.
+  def matches?(want, actual)
+    case want
+    when Hash
+      return true if want["outcome"] == "timeout" && actual.is_a?(Hash)
+
+      actual.is_a?(Hash) && want.keys.sort == actual.keys.sort &&
+        want.all? { |k, v| matches?(v, actual[k]) }
+    when Array
+      actual.is_a?(Array) && want.size == actual.size &&
+        want.zip(actual).all? { |w, a| matches?(w, a) }
+    else
+      want == actual
+    end
+  end
+
+  # @return [Array<String>] problems; empty when the committed goldens match
+  def verify(dir: DERIVED_DIR)
+    problems = []
+    entries.each do |e|
+      gp = golden_path(e)
+      unless File.exist?(gp)
+        problems << "#{e['id']}: golden missing"
+        next
+      end
+      actual = render(e, dir: dir)
+      same = File.read(gp) == actual || matches?(JSON.parse(File.read(gp)), JSON.parse(actual))
+      problems << "#{e['id']}: golden differs from current behaviour" unless same
+    end
+    extra = Dir[File.join(GOLDEN_DIR, "*.json")].map { |f| File.basename(f, ".json") } - entries.map { |e| e["id"] }
+    problems.concat(extra.map { |x| "#{x}: golden has no manifest entry" })
+    problems
+  end
+
+  def regenerate
+    FileUtils.mkdir_p(GOLDEN_DIR)
+    entries.each { |e| File.write(golden_path(e), render(e)) }
+    entries.size
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  if ARGV.include?("--check")
+    problems = MalformedGoldens.verify
+    abort problems.join("\n") unless problems.empty?
+    puts "malformed goldens ok (#{MalformedGoldens.entries.size})"
+  else
+    puts "wrote #{MalformedGoldens.regenerate} malformed goldens"
+  end
+end

data/scripts/corpus/generate_scan_goldens.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+$LOAD_PATH.unshift(File.expand_path("../../lib", __dir__))
+require "fontisan"
+require "json"
+require "fileutils"
+
+# Scan goldens for the reference corpus (fontist/fontisan#156 card 0f).
+#
+# One JSON file per manifest row (malformed included: scan never raises),
+# written from Fontisan::Reference.scan with the path reduced to a basename:
+#
+#   corpus/goldens/scan/<id>.json         ci tier, committed
+#   corpus/goldens/scan-large/<id>.json   large tier, generated in CI (nightly)
+module ScanGoldens
+  ROOT = File.expand_path("../..", __dir__)
+  MANIFEST = File.join(ROOT, "corpus", "manifest.json")
+  GOLDEN_DIRS = { "ci" => "scan", "large" => "scan-large" }.freeze
+  SCHEMA = 1
+
+  module_function
+
+  def manifest
+    JSON.parse(File.read(MANIFEST)).fetch("fonts")
+  end
+
+  def entries(tier)
+    manifest.select { |f| f["tier"] == tier }.sort_by { |f| f["id"] }
+  end
+
+  def font_path(entry)
+    dir = entry["type"] == "derived" ? "derived" : File.join("fonts", entry["id"])
+    File.join(ROOT, "corpus", dir, entry["file"])
+  end
+
+  def golden_dir(tier)
+    File.join(ROOT, "corpus", "goldens", GOLDEN_DIRS.fetch(tier))
+  end
+
+  def golden_path(tier, id)
+    File.join(golden_dir(tier), "#{id}.json")
+  end
+
+  # Rows for one font as Reference.scan returns them, paths reduced to basenames.
+  def rows(path)
+    Fontisan::Reference.scan([path]).map { |row| row.merge("path" => File.basename(row["path"])) }
+  end
+
+  def golden(entry)
+    Fontisan::Reference.canonical_json(
+      "schema" => SCHEMA,
+      "id" => entry["id"],
+      "file" => entry["file"],
+      "tier" => entry["tier"],
+      "font_sha256" => entry.fetch("sha256"),
+      "comparison_class" => "exact",
+      "rows" => rows(font_path(entry)),
+    )
+  end
+
+  def generate(tier)
+    bad = %w[FONTISAN_MODE FONTISAN_LAZY].select { |k| ENV.key?(k) }
+    raise "unset #{bad.join(', ')} before generating goldens" unless bad.empty?
+
+    entries(tier).to_h { |e| [golden_path(tier, e["id"]), golden(e)] }
+  end
+
+  def write(tier)
+    out = generate(tier)
+    FileUtils.mkdir_p(golden_dir(tier))
+    out.each { |path, bytes| File.binwrite(path, bytes) }
+    out.size
+  end
+
+  # Compare fresh output with the committed goldens. Returns problem strings.
+  def verify(tier)
+    fresh = generate(tier)
+    problems = fresh.filter_map do |path, bytes|
+      rel = path.delete_prefix("#{ROOT}/")
+      if !File.exist?(path)
+        "missing golden #{rel}"
+      elsif File.binread(path).force_encoding(bytes.encoding) != bytes
+        "golden differs #{rel}"
+      end
+    end
+    problems + stale(tier, fresh.keys)
+  end
+
+  def stale(tier, expected)
+    Dir.glob(File.join(golden_dir(tier), "*.json")).reject { |p| expected.include?(p) }
+      .map { |p| "stale golden #{p.delete_prefix("#{ROOT}/")} (no manifest font)" }
+  end
+end
+
+if $PROGRAM_NAME == __FILE__
+  tier = ARGV.fetch(0, "ci")
+  puts "wrote #{ScanGoldens.write(tier)} scan goldens (tier #{tier})"
+end