Inspect OpenType Features Programmatically in CI

The core of the browser tool, in plain Node: union the GSUB and GPOS feature tags. TTF/OTF only here — decompress WOFF/WOFF2 first.

import opentype from "opentype.js";
import fs from "node:fs";

function featureTags(path) {
  const font = opentype.parse(fs.readFileSync(path).buffer);
  const tags = new Set();
  for (const tbl of [font.tables.gsub, font.tables.gpos]) {
    for (const f of tbl?.features ?? []) if (f?.tag) tags.add(f.tag);
  }
  return [...tags].sort();
}

console.log(featureTags("./fonts/Brand-Regular.ttf"));
// → ['calt','kern','liga','smcp','ss01','tnum']  (same as the tool)

One entry per font, the tags that must be present. Captured from the Inspector's features[].tag arrays and committed to the repo.

// font-features.required.json
{
  "Brand-Regular.ttf": ["kern", "liga", "calt", "tnum", "smcp"],
  "Brand-Bold.ttf":    ["kern", "liga", "calt", "tnum"],
  "Brand-Mono.ttf":    ["kern", "zero"]
}

Walk the directory, diff each font against its required set, collect all violations, exit non-zero if any. Extra features are allowed; missing required ones fail.

import fs from "node:fs";
import path from "node:path";

const required = JSON.parse(fs.readFileSync("font-features.required.json"));
let failed = false;

for (const file of fs.readdirSync("./fonts")) {
  if (!/\.(ttf|otf)$/i.test(file)) continue;        // WOFF2: pre-convert
  const need = required[file];
  if (!need) continue;
  const have = new Set(featureTags(path.join("./fonts", file)));
  const missing = need.filter((t) => !have.has(t));
  if (missing.length) {
    failed = true;
    console.error(`✗ ${file} missing: ${missing.join(", ")}`);
  } else {
    console.log(`✓ ${file}`);
  }
}
process.exit(failed ? 1 : 0);

Rarely a font version moves a tag from one table to the other. Track in_gsub/in_gpos per tag to catch shaping-relevant moves, not just presence.

function featureMap(path) {
  const font = opentype.parse(fs.readFileSync(path).buffer);
  const map = {};
  for (const f of font.tables.gsub?.features ?? []) (map[f.tag] ??= {}).gsub = true;
  for (const f of font.tables.gpos?.features ?? []) (map[f.tag] ??= {}).gpos = true;
  return map;
}
// Diff featureMap(old) vs featureMap(new):
//   kern: was {gpos:true}, now {gsub:true,gpos:true}  → review

JAD's hosted API never accepts uploads. To run the inspector through your paired @jadapps/runner, fetch the schema, then POST to the local runner endpoint — the font is processed on your machine.

# 1. Inspect the schema (no upload):
curl -H "Authorization: Bearer $JAD_API_KEY" \
  https://<host>/api/v1/tools/opentype-features-inspector

# 2. Execute locally through the paired runner:
curl -X POST \
  -F file=@./fonts/Brand-Regular.ttf \
  http://127.0.0.1:9789/v1/tools/opentype-features-inspector/run
# → same JSON: { total_features, gsub_count, gpos_count, features }

Across opentype.js versions the GSUB/GPOS shape varies — most expose a flat features array on the table, which is what both the browser tool and these scripts read. If a version groups features under scripts[].script.langSysRecords, the flat features list is still the authoritative deduplicated set the tool uses. Pin your opentype.js version in CI so the parse shape can't shift under you between builds.

opentype.js parses sfnt (TTF/OTF). A WOFF2 file is Brotli-compressed and won't parse directly — you'll get a parse error. The browser tool decompresses WOFF2 with a wawoff2 WASM build first. In Node, either run a WOFF2 decoder before opentype.parse, or pre-convert fonts to TTF in the pipeline. Filtering the CI loop to .ttf/.otf (as the example does) sidesteps this for source fonts.

The feature tag being present in GSUB does not prove the substitution glyphs still exist or that coverage is unchanged. A font could keep the smcp tag while dropping half its small-cap glyphs. This gate catches a removed *feature*, not degraded *coverage*. For coverage regressions, add a glyph-count or character-coverage check alongside it (glyph count analyzer, character coverage map).

If your required set includes cv11 or a private tag, the script must keep unknown tags verbatim — exactly as the browser tool labels them (custom feature) but still emits them. Don't filter to a known-tag allowlist; that would drop legitimate cvNN and foundry-private features from both capture and check.

The baseline is keyed by filename. If a font update renames Brand-Regular.ttf to Brand-Text.ttf, the script finds no required entry for the new name and skips it (no failure) while the old key never matches. Normalise on family/subfamily from the name table instead of filename if your foundry renames files, or update the baseline keys in the version-bump PR.

A new font version that *adds* features (more stylistic sets, a new zero) passes the gate unchanged — the check is required − present, so extras are fine. File size grows slightly. If you want to be notified of additions too (to consider exposing them), diff total_features against the previous run and log increases as informational, not failures.

Feature tables live in GSUB/GPOS, independent of fvar, so a variable font reports the same feature set whether you check the variable file or a static instance produced by the variable font freezer. The exception is rvrn (Required variation alternates), which only matters for variable files — keep it in the baseline for the .var font, not its frozen instances.

A truncated download or a stray .DS_Store renamed to .ttf makes opentype.parse throw. Wrap the per-font parse in try/catch and treat a parse failure as a hard CI failure (a font you can't read is a font you can't ship), logging the filename so the bad artifact is obvious. The browser tool surfaces the same condition as an explicit error rather than an empty list.