normalize-metrics 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Oles Gergun
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# normalize-metrics
+
+Rewrite font vertical metrics so a word sits in the box.
+
+The text within a button is not always centered. That is the font’s fault, not yours. You can already trim the line box in CSS with `text-box: trim-both cap alphabetic`. The default is still the untrimmed box, and most type ramps and component kits were written for that default.
+
+This CLI rewrites the font for that default case. It only changes how the word sits in the box — not the letters, the look of the font, or anything else.
+
+```
+npm i -g normalize-metrics
+normalize-metrics Inter-Regular.otf
+normalize-metrics ./fonts
+```
+
+Or once, without installing:
+
+```
+npx normalize-metrics ./fonts
+```
+
+A folder means every `.otf`, `.ttf`, `.woff`, and `.woff2` inside it. It writes a normalized copy next to the original. Fonts that already have good metrics are left alone. Variable fonts and TTC collections are skipped in v1.
+
+Rewriting a licensed font and redistributing the result may violate the EULA. This tool does not legalize the file.
+
+## Requirements
+
+- Node.js 20 or newer
+- Python 3 with [fontTools](https://github.com/fonttools/fonttools) (`pip install fonttools`) — an implementation detail, not a pip product install
+
+## Usage
+
+```
+normalize-metrics <file|folder> [options]
+```
+
+| Option | What it does |
+| --- | --- |
+| `--check` | Report fonts that are still off; write nothing; exit 1 if any are off |
+| `--dry-run` | Same report; write nothing |
+| `--in-place` | Overwrite the original (opt-in) |
+| `--out-dir <dir>` | Write copies into this directory |
+| `--suffix <text>` | Filename suffix for copies (default: `-normalized`) |
+| `--config <file>` | `normalize-metrics.config.json` (or a `package.json` key) |
+
+Never overwrites unless you pass `--in-place`.
+
+In a repo, add it as a dev dependency and list the folders in the config. `--check` reports fonts that are still off and exits without writing — useful in CI.
+
+```
+npm i -D normalize-metrics
+```
+
+## Config
+
+`normalize-metrics.config.json`, or a `"normalize-metrics"` key in `package.json`:
+
+```json
+{
+  "include": ["fonts/**/*.{otf,ttf,woff,woff2}"],
+  "exclude": ["**/*-normalized.*"],
+  "outDir": null,
+  "suffix": "-normalized"
+}
+```
+
+## License
+
+MIT

package/bin/normalize-metrics.js

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+"use strict";
+
+const { spawnSync } = require("node:child_process");
+const { join } = require("node:path");
+
+const entry = join(__dirname, "..", "dist", "index.js");
+const result = spawnSync(process.execPath, [entry, ...process.argv.slice(2)], {
+  stdio: "inherit",
+});
+
+if (result.error) {
+  console.error(result.error.message);
+  process.exit(1);
+}
+
+process.exit(result.status ?? 1);

package/dist/args.js

@@ -0,0 +1,97 @@
+export const HELP = `normalize-metrics — rewrite vertical metrics so a word sits in the box
+
+Usage:
+  normalize-metrics <file|folder> [options]
+  normalize-metrics [options]
+
+A folder means every .otf, .ttf, .woff, and .woff2 inside it.
+Writes a normalized copy next to the original. Never overwrites unless --in-place.
+Fonts that already have good metrics are left alone.
+
+Options:
+  --check           report fonts that are still off; write nothing; exit 1 if any are off
+  --dry-run         same report; write nothing
+  --in-place        overwrite the original (opt-in)
+  --out-dir <dir>   write copies into this directory
+  --suffix <text>   filename suffix for copies (default: -normalized)
+  --config <file>   normalize-metrics.config.json (or a package.json key)
+  -h, --help        show this help
+  -v, --version     print the package version
+
+Config (normalize-metrics.config.json or "normalize-metrics" in package.json):
+  include, exclude, outDir, suffix
+
+Examples:
+  normalize-metrics Inter-Regular.otf
+  normalize-metrics ./fonts
+  npx normalize-metrics ./fonts --check
+`;
+const FLAGS_WITH_VALUE = new Set(["--out-dir", "--suffix", "--config"]);
+export function parseArgs(argv) {
+    const args = {
+        path: null,
+        check: false,
+        dryRun: false,
+        inPlace: false,
+        outDir: null,
+        suffix: null,
+        configPath: null,
+        help: false,
+        version: false,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const token = argv[i];
+        if (token === "-h" || token === "--help") {
+            args.help = true;
+            continue;
+        }
+        if (token === "-v" || token === "--version") {
+            args.version = true;
+            continue;
+        }
+        if (token === "--check") {
+            args.check = true;
+            continue;
+        }
+        if (token === "--dry-run") {
+            args.dryRun = true;
+            continue;
+        }
+        if (token === "--in-place") {
+            args.inPlace = true;
+            continue;
+        }
+        if (FLAGS_WITH_VALUE.has(token)) {
+            const value = argv[i + 1];
+            if (!value || value.startsWith("-")) {
+                throw new Error(`${token} needs a value.`);
+            }
+            i += 1;
+            if (token === "--out-dir")
+                args.outDir = value;
+            if (token === "--suffix")
+                args.suffix = value;
+            if (token === "--config")
+                args.configPath = value;
+            continue;
+        }
+        if (token.startsWith("-")) {
+            throw new Error(`Unknown flag: ${token}`);
+        }
+        if (args.path) {
+            throw new Error("Pass one file or one folder.");
+        }
+        args.path = token;
+    }
+    if (args.inPlace && args.outDir) {
+        throw new Error("Use either --in-place or --out-dir, not both.");
+    }
+    return args;
+}
+export function modeOf(args) {
+    if (args.check)
+        return "check";
+    if (args.dryRun)
+        return "dry-run";
+    return "write";
+}

package/dist/config.js

@@ -0,0 +1,99 @@
+import { readFile } from "node:fs/promises";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { pathExists } from "./fs-exists.js";
+export const DEFAULT_SUFFIX = "-normalized";
+const DEFAULT_EXCLUDE = [
+    "**/node_modules/**",
+    "**/.git/**",
+    "**/.next/**",
+    "**/dist/**",
+    "**/__pycache__/**",
+];
+export function emptyConfig() {
+    return {
+        include: [],
+        exclude: [...DEFAULT_EXCLUDE],
+        outDir: null,
+        suffix: DEFAULT_SUFFIX,
+    };
+}
+function asStringList(value, key) {
+    if (value == null)
+        return [];
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+        throw new Error(`Config "${key}" must be an array of strings.`);
+    }
+    return value;
+}
+function asOptionalString(value, key) {
+    if (value == null || value === "")
+        return null;
+    if (typeof value !== "string") {
+        throw new Error(`Config "${key}" must be a string.`);
+    }
+    return value;
+}
+function parseRaw(raw, baseDir) {
+    const outDir = asOptionalString(raw.outDir, "outDir");
+    return {
+        include: asStringList(raw.include, "include"),
+        exclude: [...DEFAULT_EXCLUDE, ...asStringList(raw.exclude, "exclude")],
+        outDir: outDir ? (isAbsolute(outDir) ? outDir : resolve(baseDir, outDir)) : null,
+        suffix: asOptionalString(raw.suffix, "suffix") ?? DEFAULT_SUFFIX,
+    };
+}
+async function readJson(file) {
+    return JSON.parse(await readFile(file, "utf8"));
+}
+export async function loadConfigFile(file) {
+    const raw = (await readJson(file));
+    return parseRaw(raw ?? {}, dirname(file));
+}
+export async function loadPackageConfig(file) {
+    const pkg = (await readJson(file));
+    if (!pkg["normalize-metrics"])
+        return null;
+    return parseRaw(pkg["normalize-metrics"], dirname(file));
+}
+export async function findConfig(startDir, explicit) {
+    if (explicit) {
+        const file = resolve(startDir, explicit);
+        if (!(await pathExists(file))) {
+            throw new Error(`Config not found: ${file}`);
+        }
+        if (file.endsWith("package.json")) {
+            return (await loadPackageConfig(file)) ?? emptyConfig();
+        }
+        return loadConfigFile(file);
+    }
+    let dir = resolve(startDir);
+    while (true) {
+        const jsonFile = join(dir, "normalize-metrics.config.json");
+        if (await pathExists(jsonFile)) {
+            return loadConfigFile(jsonFile);
+        }
+        const pkgFile = join(dir, "package.json");
+        if (await pathExists(pkgFile)) {
+            const fromPkg = await loadPackageConfig(pkgFile);
+            if (fromPkg)
+                return fromPkg;
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    return emptyConfig();
+}
+export function mergeConfig(config, flags, cwd) {
+    return {
+        include: config.include,
+        exclude: config.exclude,
+        outDir: flags.outDir
+            ? isAbsolute(flags.outDir)
+                ? flags.outDir
+                : resolve(cwd, flags.outDir)
+            : config.outDir,
+        suffix: flags.suffix ?? config.suffix,
+    };
+}

package/dist/discover.js

@@ -0,0 +1,70 @@
+import { readdir, stat } from "node:fs/promises";
+import { basename, join, relative, resolve, sep } from "node:path";
+import { matchesAny } from "./glob.js";
+const FONT_EXT = new Set([".otf", ".ttf", ".woff", ".woff2", ".ttc"]);
+function extensionOf(name) {
+    const match = name.toLowerCase().match(/(\.woff2|\.woff|\.ttf|\.otf|\.ttc)$/);
+    return match ? match[1] : "";
+}
+function toPosix(rel) {
+    return rel.split(sep).join("/");
+}
+export function isFontName(name) {
+    return FONT_EXT.has(extensionOf(name));
+}
+export function kindOf(name) {
+    return extensionOf(name) === ".ttc" ? "ttc" : "font";
+}
+function ignoredDir(name) {
+    return name === "node_modules" || name === ".git" || name === ".next" || name === "__pycache__";
+}
+async function walk(dir, root, found) {
+    const entries = await readdir(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const abs = join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (!ignoredDir(entry.name))
+                await walk(abs, root, found);
+            continue;
+        }
+        if (!entry.isFile() || !isFontName(entry.name))
+            continue;
+        const rel = toPosix(relative(root, abs)) || entry.name;
+        found.push({ abs, rel, name: entry.name, kind: kindOf(entry.name) });
+    }
+}
+export async function discover(target, config) {
+    const abs = resolve(target);
+    const info = await stat(abs);
+    if (info.isFile()) {
+        if (!isFontName(basename(abs))) {
+            throw new Error(`Not a font file: ${basename(abs)}`);
+        }
+        return [{ abs, rel: basename(abs), name: basename(abs), kind: kindOf(abs) }];
+    }
+    if (!info.isDirectory()) {
+        throw new Error(`Not a file or folder: ${target}`);
+    }
+    const found = [];
+    await walk(abs, abs, found);
+    found.sort((a, b) => a.rel.localeCompare(b.rel));
+    return found.filter((file) => {
+        if (config.exclude.length && matchesAny(file.rel, config.exclude))
+            return false;
+        if (config.include.length && !matchesAny(file.rel, config.include))
+            return false;
+        return true;
+    });
+}
+export async function discoverFromInclude(cwd, config) {
+    if (!config.include.length)
+        return [];
+    const found = [];
+    await walk(cwd, cwd, found);
+    found.sort((a, b) => a.rel.localeCompare(b.rel));
+    return found.filter((file) => {
+        if (config.exclude.length && matchesAny(file.rel, config.exclude))
+            return false;
+        return matchesAny(file.rel, config.include);
+    });
+}

package/dist/engine.js

@@ -0,0 +1,65 @@
+import { spawn } from "node:child_process";
+import { enginePath } from "./runtime.js";
+function lastJson(text) {
+    const line = text
+        .trim()
+        .split("\n")
+        .filter((entry) => entry.trim().startsWith("{"))
+        .at(-1);
+    if (!line)
+        return null;
+    return JSON.parse(line);
+}
+export function runEngine(options) {
+    const args = [enginePath(), "--progress"];
+    if (options.inspect)
+        args.push("--inspect");
+    if (options.skipIfGood)
+        args.push("--skip-if-good");
+    args.push(options.input);
+    if (options.output && !options.inspect)
+        args.push(options.output);
+    return new Promise((resolve, reject) => {
+        const child = spawn(options.python, args, { stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        const takeProgress = (chunk) => {
+            for (const line of chunk.split("\n")) {
+                const trimmed = line.trim();
+                if (!trimmed.startsWith("{"))
+                    continue;
+                try {
+                    const parsed = JSON.parse(trimmed);
+                    if (parsed.event === "progress" && typeof parsed.percent === "number") {
+                        options.onProgress?.({ percent: parsed.percent, phase: parsed.phase ?? "analyzing" });
+                    }
+                }
+                catch {
+                    // fontTools may write non-JSON lines
+                }
+            }
+        };
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr.on("data", (chunk) => {
+            const text = chunk.toString();
+            stderr += text;
+            takeProgress(text);
+        });
+        child.on("error", reject);
+        child.on("close", (code) => {
+            try {
+                const parsed = lastJson(stdout);
+                if (code === 0 && parsed) {
+                    resolve(parsed);
+                    return;
+                }
+                reject(new Error(stderr.trim() || `normalize failed (${code ?? "unknown"})`));
+            }
+            catch (error) {
+                reject(error instanceof Error ? error : new Error(stderr.trim() || "Could not read that font."));
+            }
+        });
+    });
+}

package/dist/fs-exists.js

@@ -0,0 +1,10 @@
+import { access } from "node:fs/promises";
+export async function pathExists(path) {
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/glob.js

@@ -0,0 +1,59 @@
+/** Minimal glob matcher for include/exclude. Supports *, **, ?, and {a,b}. */
+function escapeRegExp(value) {
+    return value.replace(/[|\\{}()[\]^$+?.]/g, "\\$&").replace(/\*/g, "\\*");
+}
+function expandBraces(pattern) {
+    const match = pattern.match(/\{([^{}]+)\}/);
+    if (!match || match.index == null)
+        return [pattern];
+    const start = match.index;
+    const [token, inner] = match;
+    return inner.split(",").flatMap((choice) => expandBraces(pattern.slice(0, start) + choice + pattern.slice(start + token.length)));
+}
+function globToRegExp(pattern) {
+    const normalized = pattern.replaceAll("\\", "/");
+    let source = "^";
+    let i = 0;
+    while (i < normalized.length) {
+        if (normalized.startsWith("**/", i)) {
+            source += "(?:.*/)?";
+            i += 3;
+            continue;
+        }
+        if (normalized.startsWith("**", i)) {
+            source += ".*";
+            i += 2;
+            continue;
+        }
+        const ch = normalized[i];
+        if (ch === "*") {
+            source += "[^/]*";
+        }
+        else if (ch === "?") {
+            source += "[^/]";
+        }
+        else {
+            source += escapeRegExp(ch);
+        }
+        i += 1;
+    }
+    source += "$";
+    return new RegExp(source);
+}
+export function matchesGlob(relPath, pattern) {
+    const path = relPath.replaceAll("\\", "/");
+    const patterns = expandBraces(pattern);
+    return patterns.some((entry) => {
+        const trimmed = entry.replaceAll("\\", "/");
+        const direct = globToRegExp(trimmed);
+        if (direct.test(path))
+            return true;
+        if (!trimmed.includes("/")) {
+            return globToRegExp(`**/${trimmed}`).test(path);
+        }
+        return false;
+    });
+}
+export function matchesAny(relPath, patterns) {
+    return patterns.some((pattern) => matchesGlob(relPath, pattern));
+}