Generate Coverage Reports for Every Font in Your Design System

The core: parse, collect codepoints, bucket into blocks. Assumes a vendored BLOCKS array of { name, start, end } sorted by start.

import opentype from 'opentype.js';
import { BLOCKS } from './unicode-blocks.js';

function blockFor(cp) {
  let lo = 0, hi = BLOCKS.length - 1;
  while (lo <= hi) {
    const m = (lo + hi) >> 1, b = BLOCKS[m];
    if (cp < b.start) hi = m - 1;
    else if (cp > b.end) lo = m + 1;
    else return b;
  }
  return null;
}

export function coverage(path) {
  const font = opentype.loadSync(path);   // .ttf/.otf
  const cps = new Set();
  for (let i = 0; i < font.glyphs.length; i++) {
    const g = font.glyphs.get(i);
    if (g.unicode != null) cps.add(g.unicode);
    if (g.unicodes) for (const u of g.unicodes) cps.add(u);
  }
  const counts = {};
  for (const cp of cps) {
    const b = blockFor(cp);
    if (b) counts[b.name] = (counts[b.name] || 0) + 1;
  }
  return { totalGlyphs: font.glyphs.length, totalCodepoints: cps.size, blocks: counts };
}

Walk the fonts dir and write one JSON per file. Commit dist/audit as the baseline at adoption time.

import fs from 'node:fs';
import { coverage } from './coverage.js';

fs.mkdirSync('dist/audit', { recursive: true });
for (const f of fs.readdirSync('src/fonts').filter(n => /\.(ttf|otf)$/.test(n))) {
  const cov = coverage(`src/fonts/${f}`);
  fs.writeFileSync(`dist/audit/${f}.coverage.json`, JSON.stringify(cov, null, 2));
  console.log(`${f}: ${Object.keys(cov.blocks).length} blocks, ${cov.totalCodepoints} cps`);
}

Compare current coverage to the committed baseline; exit non-zero if a block in CRITICAL drops.

const CRITICAL = new Set(['Basic Latin','Latin-1 Supplement','Latin Extended-A','Cyrillic']);
let failed = false;

for (const f of fonts) {
  const base = readJSON(`baseline/${f}.coverage.json`).blocks;
  const now  = coverage(`src/fonts/${f}`).blocks;
  for (const name of Object.keys(base)) {
    const before = base[name], after = now[name] || 0;
    if (after < before) {
      const tag = CRITICAL.has(name) ? 'BLOCKING' : 'warn';
      console.log(`${f}  ${name}: ${before} -> ${after} (${tag})`);
      if (CRITICAL.has(name)) failed = true;
    }
  }
}
process.exit(failed ? 1 : 0);

opentype.js reads sfnt (TTF/OTF). Decompress WOFF2/WOFF to sfnt first so web-delivery fonts can be audited too.

import { decompress } from 'wawoff2';   // WOFF2 -> sfnt
import zlib from 'node:zlib';           // WOFF tables are zlib

async function loadAny(path, bytes) {
  if (path.endsWith('.woff2')) return opentype.parse(toAB(await decompress(bytes)));
  if (path.endsWith('.woff'))  return opentype.parse(woffToSfnt(bytes, zlib));
  return opentype.parse(toAB(bytes));   // ttf/otf
}

// Audit the same bytes you actually ship (the .woff2) so coverage
// reflects the delivered file, not just the source TTF.

Run the audit on every PR; the non-zero exit blocks the merge when a critical block regresses.

- name: Font coverage audit
  run: |
    node scripts/coverage-baseline.mjs   # writes dist/audit/*.json
    node scripts/coverage-diff.mjs       # exits 1 on critical regression

# Baseline lives in baseline/*.coverage.json, committed and reviewed.
# Intentional coverage changes require an explicit baseline update PR.

The whole point of the gate. A new Bold that lost Latin Extended-A coverage diffs against the baseline as Latin Extended-A: 128 -> 96 (BLOCKING) and exits non-zero. Without the gate this ships and surfaces as tofu in production weeks later.

A foundry can add or remove unencoded alternates without changing the encoded character set. totalGlyphs moves; totalCodepoints and the per-block counts don't. Diff on block counts, not glyph totals, so cosmetic glyph-set churn doesn't trip the gate.

Coverage should be identical between a TTF and its WOFF2 (compression doesn't change the cmap), but a broken build step that subsets during WOFF2 conversion can diverge them. Audit the file you actually ship — decompress the WOFF2 and read its cmap — so the report reflects delivered bytes.

If a new font uses a block added in a Unicode version newer than your vendored table, those codepoints fall outside every known block and blockFor returns null — they're dropped from the per-block tally though they still count in totalCodepoints. Keep the block table current (Unicode 17.0.0 has 346 blocks) and refresh it when Unicode publishes a new version.

The hosted tool omits zero-coverage blocks. If your script keeps them at 0% and your baseline doesn't (or vice-versa), every diff is noisy. Pick one convention — omit blocks with zero hits — and apply it to both the baseline and the current run.

If your design system ships a single variable font, it has one glyph set and one cmap — audit it once, not per named instance. Static-instance exports each need their own audit because subsetting/instancing can change the encoded set.

opentype.js may throw on malformed or unusual tables. Wrap each font's parse in try/catch, log the filename, and decide policy: a parse failure on a shipping font should fail CI (you can't verify its coverage), not be silently skipped.

A glyph mapped to a codepoint outside every named block (an unassigned gap) is skipped by blockFor — counted in totalCodepoints but in no per-block bucket. Rare in well-built fonts; if it spikes, the cmap is likely malformed and worth flagging.

Driving character-coverage-map through the @jadapps/runner returns the same HTML report the browser produces. That's fine for archiving, but a CI diff needs structured data — which is why the Node reimplementation (identical coverage maths, JSON output) is the right tool for the gate.