Enforce Font Glyph Budgets via CI Script

The cleanest regression signal: any change to the font binary moves total_glyphs. Pin the expected number and fail on drift, so a silent foundry update can't slip in unreviewed.

#!/usr/bin/env bash
set -euo pipefail
EXPECTED=512
ACTUAL=$(curl -sS -X POST \
  http://127.0.0.1:9789/v1/tools/glyph-count-analyzer/run \
  -F 'files=@public/fonts/Body.woff2' | jq '.total_glyphs')
if [ "$ACTUAL" -ne "$EXPECTED" ]; then
  echo "Body font glyph count changed: $EXPECTED -> $ACTUAL"
  echo "Review the font update, then bump EXPECTED if intended."
  exit 1
fi

Read the projection for the subset you actually ship and fail if it exceeds the budget. Early warning — projection is an estimate, so keep ~10% headroom.

JSON=$(curl -sS -X POST \
  http://127.0.0.1:9789/v1/tools/glyph-count-analyzer/run \
  -F 'files=@public/fonts/Body.woff2')
KB=$(echo "$JSON" | jq '.projections[]
  | select(.subset|startswith("Latin Basic"))
  | .estimated_woff2_bytes')
BUDGET=24000
if [ "$KB" -gt "$BUDGET" ]; then
  echo "Body Latin subset projects ${KB}B > ${BUDGET}B budget"; exit 1
fi

Drive every shipped font from fonts.budget.json so adding a font means adding a budget entry, not editing the script.

jq -r 'to_entries[] | "\(.key)\t\(.value.maxGlyphs)"' fonts.budget.json |
while IFS=$'\t' read -r path maxg; do
  g=$(curl -sS -X POST \
    http://127.0.0.1:9789/v1/tools/glyph-count-analyzer/run \
    -F "files=@$path" | jq '.total_glyphs')
  if [ "$g" -gt "$maxg" ]; then
    echo "FAIL $path: $g glyphs > $maxg"; FAILED=1
  fi
done
[ "${FAILED:-0}" = 1 ] && exit 1 || echo "All fonts within glyph budget"

The projection is an estimate; for a contractual byte limit, measure the actual WOFF2 you ship. Build the subset, then stat the file. Use the analyser as the early-warning layer above this.

# 1. build the real subset (font-subsetter / pipeline)
# 2. measure the real shipped bytes:
REAL=$(stat -c%s dist/fonts/Body-Latin.woff2)
if [ "$REAL" -gt 24000 ]; then
  echo "Shipped Body-Latin.woff2 is ${REAL}B > 24000B"; exit 1
fi
# analyser projection is the WARNING; this stat is the HARD gate.

The contract is stable because options are empty. Assert that in CI so a future tool change surfaces loudly rather than silently breaking your parsing.

OPTS=$(curl -sS http://127.0.0.1:9789/v1/tools/glyph-count-analyzer \
  | jq -c '.options')
if [ "$OPTS" != '[]' ]; then
  echo "glyph-count-analyzer schema changed: options=$OPTS"
  echo "Re-check the CI assumptions before trusting the gate."
  exit 1
fi

estimated_woff2_bytes is current × proportion × 1.25, floored at 1500 — a model, not a measurement. Treating it as a hard byte contract will occasionally fail or pass wrongly, especially for complex scripts. Use the projection as an early-warning gate with headroom, and for a strict byte limit stat the real built WOFF2. The analyser is for catching drift cheaply; the file system is for the exact number.

If your CI feeds the analyser a TTF/OTF/WOFF, current_woff2_estimate_bytes is sfnt × 0.55 — an assumption, not a measurement, and every projection scales off it. A heavily-hinted font breaks the 0.55× assumption and your size gates inherit the error. Feed the analyser the actual WOFF2 you ship so the baseline is real, or strip hinting first with the hinting stripper.

A total_glyphs equality gate fires on any binary change — including intended ones. That's the point: it forces a human to look. When the change is legitimate, bump the expected number in fonts.budget.json within the same PR, so the growth is acknowledged in the diff. Don't loosen the gate to a range to silence it; the friction is the value.

If the runner isn't up on 127.0.0.1:9789, the curl fails and — without set -e — your script may carry on and effectively skip the gate, giving a false green. Start every script with set -euo pipefail and probe GET /v1/health first, failing the build if the runner is unreachable. A budget gate that silently no-ops is worse than no gate.

A font over the active tier's size limit (free 5 MB / pro 50 MB / developer 1 GB) is rejected before parsing, so the response is an error rather than the JSON you jq on. Your gate must handle a non-zero curl status and a non-JSON body, not assume success. Run CI under a tier whose limit clears your largest font, and check the HTTP status before parsing.

Selecting by startswith("Latin Basic") is robust, but a loose match like contains("Latin") hits both "Latin Basic + Latin-1 Supplement" and "Latin Extended-A + Extended-B", returning two values and breaking the numeric comparison. Match the exact subset label you ship. The six labels are fixed strings, so anchor on them precisely.

If a TrueType Collection (.ttc) sneaks into the fonts directory, the run returns Unsupported font format: ttc rather than JSON, and a naive loop logs a confusing parse error. Filter the directory to .ttf/.otf/.woff/.woff2, or detect and skip collections explicitly. The analyser only handles single faces.

Icon fonts map to the Private Use Area, which none of the six subsets cover, so every projection shows near-100% savings and a near-floor size. A size gate on the projected subset would pass trivially while telling you nothing — subsetting to "latin" would delete every icon. For icon fonts, gate on total_glyphs drift and on the real built file size, not the subset projection.