Never stop coding. Free MIT AI gateway: one endpoint, 375 providers (150+ free), 1,400+ models Kimi, Claude, GPT, Gemini, GLM, DeepSeek, MiniMax. Works with Claude Code, Codex, Cursor, OpenCode, Cline & Copilot. Quota-aware auto-fallback, RTK+Caveman compression saves 15-95% tokens, MCP/A2A, Desktop/PWA. Built by 900+ contributors
TypeScript a2aai-agentsai-gatewayanthropicclaudeclaude-codeclinecodexcopilotcursordeepseekfree-aigeminikimillm-gatewaymcpopenaiopenai-proxyqwentoken-saver
// scripts/quality/baseline-headroom.mjs
// Baseline headroom monitor (velocity phase, 2026-08-30 → v4.0).
//
// The ratchet gates only speak when a baseline is CROSSED. During the velocity phase the
// baselines were loosened by 20% on purpose, so the interesting question is no longer
// "did we regress?" but "how much of the loosened budget is already consumed, and how
// fast?". This script measures every numeric ratchet the same way its gate does, compares
// it with the frozen baseline and prints the remaining headroom per gate.
//
// headroom = (baseline − live) / baseline for lower-is-better counts
// headroom = (live − baseline) / baseline for higher-is-better percentages
//
// status: ok headroom ≥ --warn (default 10%)
// warn 0 ≤ headroom < --warn → the next few PRs will trip the gate
// critical headroom < 0 → the gate is already red on this tip
//
// Runs nightly (nightly-release-green.yml → baseline-headroom job) and publishes the table
// in the run summary and its retained JSON/Markdown artifact. Locally:
// node scripts/quality/baseline-headroom.mjs # table on stdout
// node scripts/quality/baseline-headroom.mjs --json out.json --md out.md
// node scripts/quality/baseline-headroom.mjs --only deadExports,fileSize
// node scripts/quality/baseline-headroom.mjs --strict # exit 1 on any critical
// Heavy measurements (knip, tsc, eslint) take a few minutes each; --only keeps it cheap.
import { execFileSync } from "node:child_process";
import fs from "node:fs";
import path from "node:path";
import { fileURLToPath, pathToFileURL } from "node:url";
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
const Q = (f) => path.join(ROOT, "config", "quality", f);
const readJson = (f) => JSON.parse(fs.readFileSync(Q(f), "utf8"));
// ── pure helpers (unit-tested) ───────────────────────────────────────────────
/**
* Headroom of one gate as a fraction of its baseline (can be negative = over budget).
* @param {number} live
* @param {number} baseline
* @param {"down"|"up"} direction "down" = lower is better (counts), "up" = higher is better (%)
*/
export function headroomOf(live, baseline, direction) {
if (!Number.isFinite(live) || !Number.isFinite(baseline)) return null;
if (baseline === 0) return direction === "down" ? (live === 0 ? 1 : -1) : live >= 0 ? 0 : -1;
return direction === "down" ? (baseline - live) / baseline : (live - baseline) / baseline;
}
/** @returns {"ok"|"warn"|"critical"|"unknown"} */
export function statusOf(headroom, warnFraction = 0.1) {
if (headroom === null || headroom === undefined) return "unknown";
if (headroom < 0) return "critical";
if (headroom < warnFraction) return "warn";
return "ok";
}
/** Sum of every per-file / per-TS-code count in a typecheck baseline (notes ignored). */
export function sumTypecheckBaseline(json) {
let n = 0;
for (const [file, codes] of Object.entries(json)) {
if (file.startsWith("_") || !codes || typeof codes !== "object") continue;
for (const c of Object.values(codes)) if (typeof c === "number") n += c;
}
return n;
}
// Files whose size is not an editable-code signal: generated modules are frozen at
// their emitter's exact output size (≈0% headroom by construction — growth is policed
// by re-freezing, e.g. openapi.generated.ts in #12212), and vendored code is upstream's.
// The GATE (check:file-size) still enforces both; only the monitor skips them so the
// nightly headroom report reflects files a human can actually slim.
export function isMonitorExemptFile(file) {
return file.includes(".generated.") || /(^|\/)vendor\//.test(file);
}
/**
* Frozen-file headroom: the worst (most consumed) frozen file and how many sit within
* `warnFraction` of their cap. `locOf(file)` returns the live line count or null.
* Generated/vendored files are excluded (see isMonitorExemptFile).
*/
export function fileSizeHeadroom(frozen, locOf, warnFraction = 0.1) {
let worst = null;
let nearCap = 0;
let over = 0;
let measured = 0;
for (const [file, capRaw] of Object.entries(frozen)) {
if (file.startsWith("_") || isMonitorExemptFile(file)) continue;
const cap = Number(capRaw);
const loc = locOf(file);
if (!Number.isFinite(cap) || loc === null || loc === undefined) continue;
measured++;
const h = headroomOf(loc, cap, "down");
if (h < 0) over++;
else if (h < warnFraction) nearCap++;
if (!worst || h < worst.headroom) worst = { file, loc, cap, headroom: h };
}
return { measured, nearCap, over, worst };
}
/** Render the markdown table for the nightly run summary and artifact. */
export function renderMarkdown(rows, { policy, generatedAt = new Date().toISOString() } = {}) {
const icon = { ok: "🟢", warn: "🟡", critical: "🔴", unknown: "⚪" };
const lines = [
`## 📈 Baseline headroom — ${generatedAt.slice(0, 16).replace("T", " ")}Z`,
"",
policy
? `Velocity phase since ${policy.since} (relax ${policy.relaxPct}%, until v${policy.until}). ` +
`Headroom = budget still free before the gate turns red.`
: "No velocity policy in quality-baseline.json (normal ratchet mode).",
"",
"| gate | live | baseline | headroom | status |",
"|---|---:|---:|---:|:--:|",
...rows.map(
(r) =>
`| \`${r.id}\` | ${fmt(r.live)} | ${fmt(r.baseline)} | ${
r.headroom === null ? "—" : `${(r.headroom * 100).toFixed(1)}%`
} | ${icon[r.status]} ${r.status}${r.note ? ` — ${r.note}` : ""} |`
),
"",
];
const bad = rows.filter((r) => r.status === "critical" || r.status === "warn");
lines.push(
bad.length
? `**${bad.length} gate(s) need attention:** ${bad.map((r) => `\`${r.id}\` (${r.status})`).join(", ")}.`
: "**All measured gates have ≥ warn headroom.**"
);
return lines.join("\n") + "\n";
}
function fmt(v) {
if (v === null || v === undefined) return "—";
return Number.isInteger(v) ? String(v) : Number(v).toFixed(2);
}
// ── measurements ─────────────────────────────────────────────────────────────
function runAndMatch(script, regex, { timeoutMs = 20 * 60 * 1000, args = [] } = {}) {
let out = "";
try {
out = execFileSync(process.execPath, [path.join(ROOT, script), ...args], {
cwd: ROOT,
encoding: "utf8",
timeout: timeoutMs,
maxBuffer: 64 * 1024 * 1024,
env: { ...process.env, FORCE_COLOR: "0" },
stdio: ["ignore", "pipe", "pipe"],
});
} catch (err) {
// A red gate exits 1 but still prints its measurement — keep reading.
out = `${err.stdout || ""}\n${err.stderr || ""}`;
}
const m = out.match(regex);
return m ? Number(m[1]) : null;
}
function countLines(file) {
try {
const text = fs.readFileSync(path.join(ROOT, file), "utf8");
return text.split("\n").length - (text.endsWith("\n") ? 1 : 0);
} catch {
return null;
}
}
/** Gate manifest — one entry per numeric ratchet the CI enforces. */
export function buildManifest() {
const qb = readJson("quality-baseline.json");
const m = qb.metrics || {};
const val = (k) => (m[k] && typeof m[k].value === "number" ? m[k].value : null);
return [
{
id: "deadExports",
direction: "down",
baseline: () => val("deadExports"),
measure: () => runAndMatch("scripts/check/check-dead-code.mjs", /DEAD_TOTAL=(\d+)/),
},
{
id: "apiTypecheck",
direction: "down",
baseline: () => sumTypecheckBaseline(readJson("api-typecheck-baseline.json")),
measure: () =>
runAndMatch("scripts/check/check-api-typecheck.mjs", /apiTypecheckErrors=(\d+)/),
},
{
id: "dashboardTypecheck",
direction: "down",
baseline: () => sumTypecheckBaseline(readJson("dashboard-typecheck-baseline.json")),
measure: () =>
runAndMatch(
"scripts/check/check-dashboard-typecheck.mjs",
/dashboardTypecheckErrors=(\d+)/
),
},
{
id: "openSseTypecheck",
direction: "down",
baseline: () => sumTypecheckBaseline(readJson("open-sse-typecheck-baseline.json")),
measure: () =>
runAndMatch("scripts/check/check-open-sse-typecheck.mjs", /openSseTypecheckErrors=(\d+)/),
},
{
id: "cognitiveComplexity",
direction: "down",
baseline: () => val("cognitiveComplexity"),
measure: () =>
runAndMatch("scripts/check/check-cognitive-complexity.mjs", /cognitiveComplexity=(\d+)/),
},
{
id: "complexity",
direction: "down",
baseline: () => readJson("complexity-baseline.json").count,
measure: () => runAndMatch("scripts/check/check-complexity.mjs", /(\d+) violaç/),
},
{
id: "duplicationPct",
direction: "down",
baseline: () => readJson("duplication-baseline.json").percentage,
measure: () => runAndMatch("scripts/check/check-duplication.mjs", /(\d+(?:\.\d+)?)%/),
},
{
id: "rtlPhysicalClasses",
direction: "down",
baseline: () => val("rtlPhysicalClasses"),
measure: () => runAndMatch("scripts/check/check-rtl-ratchet.mjs", /rtlPhysicalClasses=(\d+)/),
},
{
id: "typeCoveragePct",
direction: "up",
baseline: () => val("typeCoveragePct"),
measure: () =>
runAndMatch("scripts/check/check-type-coverage.mjs", /typeCoveragePct=(\d+(?:\.\d+)?)/),
},
{
id: "fileSize",
direction: "down",
// Reported as the WORST frozen file: live = its lines, baseline = its cap.
baseline: () => null,
measure: () => null,
custom: (warnFraction) => {
const fsz = readJson("file-size-baseline.json");
const r = fileSizeHeadroom(fsz.frozen || {}, countLines, warnFraction);
const t = fileSizeHeadroom(fsz.testFrozen || {}, countLines, warnFraction);
const worst = [r.worst, t.worst].filter(Boolean).sort((a, b) => a.headroom - b.headroom)[0];
return {
live: worst ? worst.loc : null,
baseline: worst ? worst.cap : null,
headroom: worst ? worst.headroom : null,
note: worst
? `worst: ${worst.file}; ${r.nearCap + t.nearCap} file(s) within warn, ${r.over + t.over} over (${r.measured + t.measured} frozen)`
: "no frozen files measured",
};
},
},
];
}
export function collect({ only = null, warnFraction = 0.1, manifest = buildManifest() } = {}) {
const rows = [];
for (const gate of manifest) {
if (only && !only.includes(gate.id)) continue;
let live = null;
let baseline = null;
let headroom = null;
let note = "";
try {
if (gate.custom) {
({ live, baseline, headroom, note } = gate.custom(warnFraction));
} else {
baseline = gate.baseline();
live = gate.measure();
headroom = headroomOf(live, baseline, gate.direction);
if (live === null) note = "measurement unavailable";
}
} catch (err) {
note = `error: ${err && err.message ? err.message.split("\n")[0] : err}`;
}
rows.push({
id: gate.id,
direction: gate.direction,
live,
baseline,
headroom,
status: statusOf(headroom, warnFraction),
note,
});
}
return rows;
}
// ── CLI ──────────────────────────────────────────────────────────────────────
function main() {
const argv = process.argv.slice(2);
const getArg = (n, d) => {
const i = argv.indexOf(n);
return i >= 0 && argv[i + 1] !== undefined ? argv[i + 1] : d;
};
const warnFraction = Number(getArg("--warn", "10")) / 100;
const only =
getArg("--only", null)
?.split(",")
.map((s) => s.trim())
.filter(Boolean) ?? null;
const jsonOut = getArg("--json", null);
const mdOut = getArg("--md", null);
const strict = argv.includes("--strict");
const qb = readJson("quality-baseline.json");
const rows = collect({ only, warnFraction });
const md = renderMarkdown(rows, { policy: qb._policy || null });
process.stdout.write(md);
if (jsonOut) {
fs.mkdirSync(path.dirname(jsonOut), { recursive: true });
fs.writeFileSync(
jsonOut,
JSON.stringify(
{ generatedAt: new Date().toISOString(), policy: qb._policy || null, warnFraction, rows },
null,
2
) + "\n"
);
}
if (mdOut) {
fs.mkdirSync(path.dirname(mdOut), { recursive: true });
fs.writeFileSync(mdOut, md);
}
const critical = rows.filter((r) => r.status === "critical").length;
if (strict && critical) process.exit(1);
}
if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
main();
}