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
#!/usr/bin/env node
/**
* measure-boundary.mjs — reproducible measurement of the src ⇄ open-sse coupling.
*
* Rail 3.8.55 (Task 13). v4 splits the engine (`open-sse/`) from the app modules
* (`src/lib/*`). This script gives the LTS a repeatable number for that coupling
* instead of hand-built tables:
*
* - scans `src/**\/*.ts(x)` and `open-sse/**\/*.ts(x)` (skips node_modules, .next,
* tests/, __tests__/, *.test.*, *.spec.*);
* - extracts static imports/re-exports (`import … from`, `export … from`,
* `import "x"`), dynamic `import("x")` and `require("x")` — comments, string
* contents, template literals and regex literals are lexed out first so a
* specifier mentioned in a comment does not count;
* - resolves `@/…`, `@omniroute/open-sse[/…]` and relative specifiers to a
* repo-relative file (ts/tsx/js/mjs/json/index fallbacks; unresolved paths keep
* their normalized spelling);
* - counts cross-boundary edges as unique (importing file, imported file) pairs in
* both directions and aggregates them per subsystem of origin
* (`src/lib/<name>`, `src/app/api/<route>`, `src/<dir>`, `open-sse/<dir>`).
*
* `open-sse → src` should trend to zero: the engine must not depend on the app. The
* full list of those edges is emitted (`openSseToSrcEdges`) as the v4 remediation list.
*
* Ratchet: `open-sse → src` went 745 → 768 edges between 2026-10-10 and 2026-10-16 while
* this script only measured it, so the count now has a frozen ceiling in
* `config/quality/quality-baseline.json` → `metrics.boundaryOpenSseToSrc` (`direction:
* down`, `dedicatedGate: true`, same shape as `metrics.cycles`):
* - `--ratchet` blocks (exit 1) when `edges.openSseToSrc` exceeds that ceiling; with no
* ceiling in the baseline it is advisory (exit 0 + warning);
* - `--update` writes the measured count as the new ceiling, but only when it is not
* higher than the current one — the ceiling only goes down. Raising it is a manual,
* justified edit of the baseline, never a way to make the gate green.
* Without either flag the Markdown/JSON report is unchanged.
*
* PR base-relative mode (`--ratchet --base-ref <sha>`, same idea as check:file-size #8522):
* the base receives ~10 merges/hour, and twice on 2026-10-16 merges landed between the seed
* and the merge of the ceiling (771 → 773 → 774, #16904) — every innocent PR went red in that
* window. With `--base-ref` the base commit is exported with `git archive` (src/ + open-sse/,
* the only trees the resolver reads; tsconfig is not consulted) into a temporary directory and
* measured with the same `measureBoundary`; the effective ceiling is
* `max(baseline ceiling, edges on the base)`, so the PR fails only when it ADDS edges. Base
* drift above the ceiling is reported, never blocking. If the base cannot be exported (unknown
* SHA, shallow checkout) the gate warns and falls back to the absolute ceiling — never a
* silent green. CI passes `--base-ref` on pull_request events only; push / workflow_dispatch
* keep the absolute ceiling.
*
* Usage:
* node scripts/quality/measure-boundary.mjs --json [--root <dir>]
* node scripts/quality/measure-boundary.mjs --md [--root <dir>]
* node scripts/quality/measure-boundary.mjs --ratchet [--root <dir>] [--baseline <file>]
* node scripts/quality/measure-boundary.mjs --ratchet --base-ref <sha> [--root <dir>] [--baseline <file>]
* node scripts/quality/measure-boundary.mjs --update [--root <dir>] [--baseline <file>]
*
* Only `node:fs` / `node:path` / `node:url` / `node:os`; the only child processes are `git`
* and `tar` for `--base-ref`, via `execFileSync` with argv arrays (no shell, Hard Rule #13).
*/
import { execFileSync } from "node:child_process";
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { fileURLToPath } from "node:url";
const SOURCE_EXT_RE = /\.(?:ts|tsx)$/;
const TEST_FILE_RE = /\.(?:test|spec)\.(?:ts|tsx)$/;
const SKIPPED_DIRS = new Set(["node_modules", ".next", "tests", "__tests__"]);
const SCANNED_ROOTS = ["src", "open-sse"];
const RESOLVE_SUFFIXES = [
"",
".ts",
".tsx",
".js",
".mjs",
".cjs",
".json",
"/index.ts",
"/index.tsx",
"/index.js",
];
const TOP_TARGETS = 5;
const STR = "\u0001";
// Characters / keywords after which a `/` starts a regex literal instead of a division.
const REGEX_PREFIX_CHARS = new Set("(,=:[!&|?{};+-*%<>~^".split(""));
const REGEX_PREFIX_WORDS = new Set([
"return",
"typeof",
"case",
"do",
"else",
"in",
"of",
"void",
"yield",
"await",
"delete",
"throw",
"instanceof",
"new",
]);
/**
* Lex `source` into code with comments removed and every quoted string literal replaced
* by an indexed placeholder. Template literal text is dropped (its `${…}` code is kept).
* Returns `{ code, strings }`.
*/
function maskSource(source) {
const strings = [];
let code = "";
let i = 0;
const n = source.length;
// Each entry is the brace depth inside a template `${ … }` substitution.
const templateStack = [];
let lastToken = "";
const readTemplate = () => {
// Called with i positioned just after a "`" or a closing "}" of a substitution.
while (i < n) {
const c = source[i];
if (c === "\\") {
i += 2;
continue;
}
if (c === "`") {
i++;
code += " ";
lastToken = "a";
return;
}
if (c === "$" && source[i + 1] === "{") {
i += 2;
templateStack.push(0);
code += " ";
lastToken = "{";
return;
}
i++;
}
};
while (i < n) {
const c = source[i];
const d = source[i + 1];
if (c === "/" && d === "/") {
while (i < n && source[i] !== "\n") i++;
code += " ";
continue;
}
if (c === "/" && d === "*") {
const end = source.indexOf("*/", i + 2);
i = end === -1 ? n : end + 2;
code += " ";
continue;
}
if (c === '"' || c === "'") {
let j = i + 1;
let value = "";
while (j < n && source[j] !== c && source[j] !== "\n") {
if (source[j] === "\\") {
value += source[j + 1] ?? "";
j += 2;
continue;
}
value += source[j];
j++;
}
i = j + 1;
code += `${STR}${strings.length}${STR}`;
strings.push(value);
lastToken = "a";
continue;
}
if (c === "`") {
i++;
readTemplate();
continue;
}
if (c === "{" && templateStack.length > 0) {
templateStack[templateStack.length - 1]++;
}
if (c === "}" && templateStack.length > 0) {
if (templateStack[templateStack.length - 1] === 0) {
templateStack.pop();
i++;
readTemplate();
continue;
}
templateStack[templateStack.length - 1]--;
}
if (c === "/") {
const startsRegex =
lastToken === "" || REGEX_PREFIX_CHARS.has(lastToken) || REGEX_PREFIX_WORDS.has(lastToken);
if (startsRegex) {
let j = i + 1;
let inClass = false;
while (j < n && source[j] !== "\n") {
const r = source[j];
if (r === "\\") {
j += 2;
continue;
}
if (r === "[") inClass = true;
else if (r === "]") inClass = false;
else if (r === "/" && !inClass) break;
j++;
}
j++;
while (j < n && /[a-z]/i.test(source[j])) j++;
i = j;
code += " ";
lastToken = "a";
continue;
}
}
code += c;
if (/[\w$]/.test(c)) {
// Track the whole word so keyword prefixes (return, typeof, …) are recognised.
let j = i + 1;
while (j < n && /[\w$]/.test(source[j])) j++;
const word = source.slice(i, j);
code += word.slice(1);
lastToken = word;
i = j;
continue;
}
if (!/\s/.test(c)) lastToken = c;
i++;
}
return { code, strings };
}
const S = `${STR}(\\d+)${STR}`;
const NOT_MEMBER = "(?:^|[^.\\w$])";
const IMPORT_PATTERNS = [
// import x from "a" / import type { B } from "b" / import * as ns from "c"
new RegExp(`${NOT_MEMBER}import\\s*[\\w$*{},\\s]+?\\s*from\\s*${S}`, "g"),
// export * from "e" / export { f } from "f" / export type { G } from "g"
new RegExp(
`${NOT_MEMBER}export\\s*(?:type\\s+)?(?:\\*(?:\\s*as\\s+[\\w$]+)?|\\{[^}]*\\})\\s*from\\s*${S}`,
"g"
),
// import "side-effect"
new RegExp(`${NOT_MEMBER}import\\s*${S}`, "g"),
// import("dynamic")
new RegExp(`${NOT_MEMBER}import\\s*\\(\\s*${S}\\s*[,)]`, "g"),
// require("cjs")
new RegExp(`${NOT_MEMBER}require\\s*\\(\\s*${S}\\s*\\)`, "g"),
];
/** Return the module specifiers imported by `source` (deduplicated, in first-seen order). */
export function extractImportSpecifiers(source) {
const { code, strings } = maskSource(source);
const seen = new Set();
for (const pattern of IMPORT_PATTERNS) {
pattern.lastIndex = 0;
for (const match of code.matchAll(pattern)) {
seen.add(strings[Number(match[1])]);
}
}
return [...seen];
}
function stripExt(name) {
return name.replace(/\.(?:ts|tsx|js|mjs|cjs|json)$/, "");
}
/** Subsystem of a repo-relative path (posix separators). */
export function subsystemOf(relPath) {
const parts = relPath.split("/");
if (parts[0] === "open-sse") {
return parts.length > 2 ? `open-sse/${parts[1]}` : "open-sse/(root)";
}
if (parts[0] === "src") {
if (parts[1] === "lib" && parts.length > 2) {
return `src/lib/${parts.length > 3 ? parts[2] : stripExt(parts[2])}`;
}
if (parts[1] === "app" && parts[2] === "api" && parts.length > 3) {
return `src/app/api/${parts.length > 4 ? parts[3] : stripExt(parts[3])}`;
}
return parts.length > 2 ? `src/${parts[1]}` : "src/(root)";
}
return parts[0];
}
function listSourceFiles(root, top) {
const out = [];
const walk = (relDir) => {
let entries;
try {
entries = fs.readdirSync(path.join(root, relDir), { withFileTypes: true });
} catch {
return;
}
entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
for (const entry of entries) {
const rel = `${relDir}/${entry.name}`;
if (entry.isDirectory()) {
if (!SKIPPED_DIRS.has(entry.name)) walk(rel);
} else if (
entry.isFile() &&
SOURCE_EXT_RE.test(entry.name) &&
!TEST_FILE_RE.test(entry.name)
) {
out.push(rel);
}
}
};
walk(top);
return out;
}
function createResolver(root) {
const cache = new Map();
const isFile = (rel) => {
try {
return fs.statSync(path.join(root, rel)).isFile();
} catch {
return false;
}
};
return (target) => {
if (cache.has(target)) return cache.get(target);
let resolved = null;
for (const suffix of RESOLVE_SUFFIXES) {
if (isFile(`${target}${suffix}`)) {
resolved = `${target}${suffix}`;
break;
}
}
// TS-style `./x.js` that points at `./x.ts`.
if (!resolved && /\.(?:m?js)$/.test(target)) {
const base = target.replace(/\.(?:m?js)$/, "");
for (const ext of [".ts", ".tsx"]) {
if (isFile(`${base}${ext}`)) {
resolved = `${base}${ext}`;
break;
}
}
}
const result = resolved ?? target;
cache.set(target, result);
return result;
};
}
/** Map a specifier imported from `fromRel` to a repo-relative path, or null if external. */
function specifierTarget(spec, fromRel) {
let target;
if (spec.startsWith("@/")) target = `src/${spec.slice(2)}`;
else if (spec === "@omniroute/open-sse") target = "open-sse";
else if (spec.startsWith("@omniroute/open-sse/")) {
target = `open-sse/${spec.slice("@omniroute/open-sse/".length)}`;
} else if (spec === "." || spec === ".." || spec.startsWith("./") || spec.startsWith("../")) {
target = path.posix.join(path.posix.dirname(fromRel), spec);
} else return null;
target = path.posix.normalize(target).replace(/\/$/, "");
if (target.startsWith("../") || target === "..") return null;
return target;
}
function compareStrings(a, b) {
return a < b ? -1 : a > b ? 1 : 0;
}
/**
* Measure the boundary under `root`. Returns
* `{ generatedAt, files, edges, openSseToSrcEdges, bySubsystem }`.
*/
export function measureBoundary({ root, now = new Date() } = {}) {
const absRoot = path.resolve(root ?? process.cwd());
const resolve = createResolver(absRoot);
const files = {};
for (const top of SCANNED_ROOTS) files[top] = listSourceFiles(absRoot, top);
const subsystems = new Map();
const getSub = (name) => {
let entry = subsystems.get(name);
if (!entry) {
entry = {
name,
files: 0,
importsOpenSse: 0,
importedByOpenSse: 0,
importsSrc: 0,
importedBySrc: 0,
targets: new Map(),
};
subsystems.set(name, entry);
}
return entry;
};
const edges = { srcToOpenSse: 0, openSseToSrc: 0 };
const openSseToSrcEdges = [];
for (const top of SCANNED_ROOTS) {
for (const rel of files[top]) {
const fromSub = getSub(subsystemOf(rel));
fromSub.files++;
const source = fs.readFileSync(path.join(absRoot, rel), "utf8");
const seenTargets = new Set();
for (const spec of extractImportSpecifiers(source)) {
const raw = specifierTarget(spec, rel);
if (!raw) continue;
const to = resolve(raw);
const toTop = to.split("/")[0];
if (toTop === top || !SCANNED_ROOTS.includes(toTop)) continue;
if (seenTargets.has(to)) continue;
seenTargets.add(to);
const toSub = getSub(subsystemOf(to));
fromSub.targets.set(to, (fromSub.targets.get(to) ?? 0) + 1);
if (top === "src") {
edges.srcToOpenSse++;
fromSub.importsOpenSse++;
toSub.importedBySrc++;
} else {
edges.openSseToSrc++;
fromSub.importsSrc++;
toSub.importedByOpenSse++;
openSseToSrcEdges.push({ from: rel, to });
}
}
}
}
openSseToSrcEdges.sort((a, b) => compareStrings(a.from, b.from) || compareStrings(a.to, b.to));
const weight = (s) => s.importsOpenSse + s.importedByOpenSse + s.importsSrc + s.importedBySrc;
const bySubsystem = [...subsystems.values()]
.map((s) => ({
name: s.name,
files: s.files,
importsOpenSse: s.importsOpenSse,
importedByOpenSse: s.importedByOpenSse,
importsSrc: s.importsSrc,
importedBySrc: s.importedBySrc,
topTargets: [...s.targets.entries()]
.map(([target, count]) => ({ target, count }))
.sort((a, b) => b.count - a.count || compareStrings(a.target, b.target))
.slice(0, TOP_TARGETS),
}))
.sort((a, b) => weight(b) - weight(a) || compareStrings(a.name, b.name));
return {
generatedAt: now.toISOString(),
files: { src: files.src.length, openSse: files["open-sse"].length },
edges,
openSseToSrcEdges,
bySubsystem,
};
}
/** Render a measurement as Markdown (only subsystems with cross-boundary edges). */
export function renderMarkdown(result) {
const lines = [
`# src ⇄ open-sse boundary — ${result.generatedAt}`,
"",
"Generated by `scripts/quality/measure-boundary.mjs` (edges = unique importing-file → imported-file pairs).",
"",
"| Metric | Value |",
"| --- | ---: |",
`| src files scanned | ${result.files.src} |`,
`| open-sse files scanned | ${result.files.openSse} |`,
`| src → open-sse edges | ${result.edges.srcToOpenSse} |`,
`| open-sse → src edges | ${result.edges.openSseToSrc} |`,
"",
"## By subsystem",
"",
"| Subsystem | Files | Imports open-sse | Imported by open-sse | Imports src | Imported by src | Top targets |",
"| --- | ---: | ---: | ---: | ---: | ---: | --- |",
];
for (const s of result.bySubsystem) {
if (s.importsOpenSse + s.importedByOpenSse + s.importsSrc + s.importedBySrc === 0) continue;
const targets = s.topTargets.map((t) => `\`${t.target}\` (${t.count})`).join(", ") || "—";
lines.push(
`| \`${s.name}\` | ${s.files} | ${s.importsOpenSse} | ${s.importedByOpenSse} | ${s.importsSrc} | ${s.importedBySrc} | ${targets} |`
);
}
lines.push("", "## open-sse → src edges (v4 remediation list)", "");
if (result.openSseToSrcEdges.length === 0) lines.push("_none_");
for (const edge of result.openSseToSrcEdges) {
lines.push(`- \`${edge.from}\` → \`${edge.to}\``);
}
lines.push("");
return lines.join("\n");
}
// ---------------------------------------------------------------------------
// Ratchet (quality-baseline.json → metrics.boundaryOpenSseToSrc)
// ---------------------------------------------------------------------------
/** Key of the `open-sse → src` ceiling inside `quality-baseline.json` → `metrics`. */
export const BOUNDARY_METRIC_KEY = "boundaryOpenSseToSrc";
/** Default location of the baseline, resolved from this script's own path. */
export function defaultBaselinePath() {
return fileURLToPath(new URL("../../config/quality/quality-baseline.json", import.meta.url));
}
/**
* Read the frozen `open-sse → src` ceiling. Missing file, missing metric or a non-numeric
* value ⇒ `null` (advisory: no ceiling to enforce).
*
* @param {string} [baselinePath]
* @returns {number | null}
*/
export function readBaselineBoundaryValue(baselinePath = defaultBaselinePath()) {
try {
const parsed = JSON.parse(fs.readFileSync(baselinePath, "utf8"));
const value = parsed?.metrics?.[BOUNDARY_METRIC_KEY]?.value;
return typeof value === "number" && Number.isFinite(value) ? value : null;
} catch {
return null;
}
}
/**
* Compare the measured `open-sse → src` edge count with the ceiling.
*
* @param {number} measured
* @param {number | null} ceiling
* @returns {{ status: "ok" | "fail" | "advisory", exitCode: 0 | 1, message: string }}
*/
export function evaluateBoundaryRatchet(measured, ceiling) {
if (ceiling === null || ceiling === undefined) {
return {
status: "advisory",
exitCode: 0,
message: `[boundary] RATCHET ADVISORY - no metrics.${BOUNDARY_METRIC_KEY} ceiling in quality-baseline.json; not enforced (${measured} edges, no ceiling).`,
};
}
if (measured > ceiling) {
return {
status: "fail",
exitCode: 1,
message: `[boundary] RATCHET FAIL - open-sse → src edges exceed the quality-baseline.json ceiling (${measured} edges, ceiling ${ceiling}). The engine must not gain new imports from src/: move the code into open-sse/ or inject it. Run \`npm run quality:boundary\` for the full edge list. Do not raise the ceiling to make this gate green.`,
};
}
return {
status: "ok",
exitCode: 0,
message: `[boundary] RATCHET OK - open-sse → src edges within the quality-baseline.json ceiling (${measured} edges, ceiling ${ceiling}).`,
};
}
/**
* PR base-relative verdict (`--base-ref`): the effective ceiling is
* `max(ceiling, baseMeasured)`, so drift the PR inherited from its base never blocks it,
* while any edge the PR adds on top of the base still does. `warning` is set when the base
* itself is above the baseline ceiling (inherited drift — reported, not blocking).
*
* @param {number} measured edges on the PR head
* @param {number} baseMeasured edges on the PR base
* @param {number | null} ceiling baseline ceiling
* @returns {{ status: "ok" | "fail" | "advisory", exitCode: 0 | 1, message: string, warning?: string }}
*/
export function evaluateBoundaryRatchetRelative(measured, baseMeasured, ceiling) {
const numbers = `head ${measured}, base ${baseMeasured}, baseline ceiling ${ceiling ?? "(none)"}`;
if (ceiling === null || ceiling === undefined) {
return {
status: "advisory",
exitCode: 0,
message: `[boundary] RATCHET ADVISORY - no metrics.${BOUNDARY_METRIC_KEY} ceiling in quality-baseline.json; not enforced (${numbers}).`,
};
}
const effective = Math.max(ceiling, baseMeasured);
const drift = baseMeasured - ceiling;
const warning =
drift > 0
? `[boundary] WARNING base drift herdado: ${drift} acima do teto — não é desta PR (the PR base already has ${baseMeasured} edges vs the baseline ceiling ${ceiling}; inherited, not blocking).`
: undefined;
if (measured > effective) {
return {
status: "fail",
exitCode: 1,
message: `[boundary] RATCHET FAIL - this PR adds open-sse → src edges (${numbers}; effective ceiling max(ceiling, base) = ${effective}). The engine must not gain new imports from src/: move the code into open-sse/ or inject it. Run \`npm run quality:boundary\` for the full edge list. Do not raise the ceiling to make this gate green.`,
...(warning ? { warning } : {}),
};
}
return {
status: "ok",
exitCode: 0,
message: `[boundary] RATCHET OK - open-sse → src edges within max(baseline ceiling, PR base) (${numbers}; effective ceiling ${effective}).`,
...(warning ? { warning } : {}),
};
}
/**
* Measure `openSseToSrc` at git ref `ref` of the repository at `root`, without touching its
* working tree or index: `git archive` exports src/ + open-sse/ of that commit into a
* temporary directory, which is measured with `measureBoundary` and removed afterwards.
* Throws when the ref cannot be resolved or exported (caller falls back to absolute mode).
*
* @param {string} root repository root (the measured tree)
* @param {string} ref commit-ish of the PR base
* @returns {{ sha: string, edges: number }}
*/
export function measureBoundaryAtRef(root, ref) {
if (typeof ref !== "string" || !/^[\w./^~@{}-]+$/.test(ref) || ref.startsWith("-")) {
throw new Error(`refusing suspicious ref ${JSON.stringify(ref)}`);
}
const git = (args) =>
execFileSync("git", args, {
cwd: root,
encoding: "utf8",
stdio: ["ignore", "pipe", "pipe"],
maxBuffer: 64 * 1024 * 1024,
}).trim();
const sha = git(["rev-parse", "--verify", "--quiet", "--end-of-options", `${ref}^{commit}`]);
if (!/^[0-9a-f]{40,64}$/.test(sha)) throw new Error(`cannot resolve ${ref} to a commit`);
const present = git(["ls-tree", "--name-only", sha, "--", ...SCANNED_ROOTS])
.split("\n")
.filter((name) => SCANNED_ROOTS.includes(name));
const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "measure-boundary-base-"));
try {
if (present.length > 0) {
const tarPath = path.join(tmp, "base.tar");
const tree = path.join(tmp, "tree");
fs.mkdirSync(tree);
git(["archive", "--format=tar", `--output=${tarPath}`, sha, "--", ...present]);
execFileSync("tar", ["-xf", tarPath, "-C", tree], { stdio: ["ignore", "pipe", "pipe"] });
return { sha, edges: measureBoundary({ root: tree }).edges.openSseToSrc };
}
return { sha, edges: 0 };
} finally {
fs.rmSync(tmp, { recursive: true, force: true });
}
}
/**
* Write `measured` as the new ceiling. Refuses to raise an existing ceiling (the ratchet
* only goes down); a missing metric is seeded as a dedicated down-only gate. Every other
* key of the baseline — including the metric's `_note` — is preserved.
*
* @param {string} baselinePath
* @param {number} measured
* @returns {{ written: boolean, previous: number | null, value: number }}
*/
export function updateBaselineBoundaryValue(baselinePath, measured) {
const baseline = JSON.parse(fs.readFileSync(baselinePath, "utf8"));
baseline.metrics ??= {};
const spec = baseline.metrics[BOUNDARY_METRIC_KEY];
const previous = typeof spec?.value === "number" ? spec.value : null;
if (previous !== null && measured > previous) {
return { written: false, previous, value: measured };
}
baseline.metrics[BOUNDARY_METRIC_KEY] = spec
? { ...spec, value: measured }
: { value: measured, direction: "down", dedicatedGate: true };
fs.writeFileSync(baselinePath, `${JSON.stringify(baseline, null, 2)}\n`);
return { written: true, previous, value: measured };
}
// ---------------------------------------------------------------------------
// CLI
// ---------------------------------------------------------------------------
function parseArgs(argv) {
const args = {
format: "md",
root: process.cwd(),
baseline: null,
ratchet: false,
update: false,
baseRef: null,
};
for (let i = 0; i < argv.length; i++) {
const arg = argv[i];
if (arg === "--json") args.format = "json";
else if (arg === "--md") args.format = "md";
else if (arg === "--ratchet") args.ratchet = true;
else if (arg === "--update") args.update = true;
else if (arg === "--root") args.root = argv[++i];
else if (arg.startsWith("--root=")) args.root = arg.slice("--root=".length);
else if (arg === "--baseline") args.baseline = argv[++i];
else if (arg.startsWith("--baseline=")) args.baseline = arg.slice("--baseline=".length);
else if (arg === "--base-ref" || arg.startsWith("--base-ref=")) {
const value = arg === "--base-ref" ? argv[++i] : arg.slice("--base-ref=".length);
if (value === undefined || value === "") throw new Error("--base-ref needs a value");
args.baseRef = value;
} else if (arg === "--help" || arg === "-h") args.help = true;
else throw new Error(`Unknown argument: ${arg}`);
}
if (args.ratchet && args.update) throw new Error("--ratchet and --update are exclusive");
if (args.baseRef !== null && !args.ratchet) throw new Error("--base-ref requires --ratchet");
return args;
}
function runUpdate(baselinePath, measured) {
let outcome;
try {
outcome = updateBaselineBoundaryValue(baselinePath, measured);
} catch (error) {
console.error(`[boundary] cannot update ${baselinePath}: ${error.message}`);
return 2;
}
if (!outcome.written) {
console.error(
`[boundary] UPDATE refused - measured ${measured} edges is above the ceiling of ${outcome.previous}; the ceiling only goes down. Remove the new open-sse → src imports instead.`
);
return 1;
}
console.log(
`[boundary] UPDATE - metrics.${BOUNDARY_METRIC_KEY}.value ${outcome.previous ?? "(unset)"} → ${measured}.`
);
return 0;
}
function main() {
let args;
try {
args = parseArgs(process.argv.slice(2));
} catch (error) {
console.error(`[measure-boundary] ${error.message}`);
process.exit(2);
}
if (args.help) {
console.log(
"Usage: node scripts/quality/measure-boundary.mjs [--json|--md] [--ratchet [--base-ref <sha>]|--update] [--root <dir>] [--baseline <file>]"
);
return;
}
const result = measureBoundary({ root: args.root });
const baselinePath = path.resolve(args.baseline ?? defaultBaselinePath());
if (args.update) process.exit(runUpdate(baselinePath, result.edges.openSseToSrc));
if (args.ratchet) {
const ceiling = readBaselineBoundaryValue(baselinePath);
let verdict = null;
if (args.baseRef !== null) {
try {
const base = measureBoundaryAtRef(path.resolve(args.root), args.baseRef);
console.log(
`[boundary] PR mode (--base-ref ${base.sha.slice(0, 12)}): ${base.edges} open-sse → src edges on the base.`
);
verdict = evaluateBoundaryRatchetRelative(result.edges.openSseToSrc, base.edges, ceiling);
} catch (error) {
const reason = String(error?.stderr || error?.message || error)
.trim()
.split("\n")[0];
console.error(
`[boundary] WARNING --base-ref ${args.baseRef} could not be measured (${reason}); falling back to the absolute ceiling.`
);
}
}
verdict ??= evaluateBoundaryRatchet(result.edges.openSseToSrc, ceiling);
if (verdict.warning) console.error(verdict.warning);
(verdict.status === "ok" ? console.log : console.error)(verdict.message);
process.exit(verdict.exitCode);
}
process.stdout.write(
args.format === "json" ? `${JSON.stringify(result, null, 2)}\n` : renderMarkdown(result)
);
}
const isDirectRun =
process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url);
if (isDirectRun) main();