mirror of
https://github.com/diegosouzapw/OmniRoute.git
synced 2026-11-16 17:09:09 +00:00
A push to omni-queue/** has no github.event.pull_request, so the gates that are base-relative (or advisory) on a pull request ran a candidate in their absolute / strict mode. A base that drifted mid-cycle would red every candidate and the queue would blame innocent pull requests. Measured on the release tip: the strict i18n drift check exits 1 (33 sources, 66 mirrors). On a candidate these now compare with needs.changes.outputs.candidateBase: - ci.yml lint: boundary ratchet (--base-ref). - quality.yml fast-gates: file-size, complexity-ratchets, dead-code, boundary and the TS7 diagnostics ratchet (which was skipped without a base). - ci.yml docs-sync-strict: the i18n docs drift takes the pull-request path (base checkout of the candidate base + advisory comparison); the strict step no longer runs on a candidate. Pushes to main, merge_group and workflow_dispatch evaluate to the same values as before; pull requests keep github.event.pull_request.base.sha. newCodeMode.resolveMergeBase: on a merge-commit HEAD it compares with HEAD^1 (the live base tip of refs/pull/N/merge). A batch candidate is the base plus one merge commit per pull request, so that rule judged only the last pull request of the batch. The two new-code gates now pass the pushed ref, and a refs/heads/omni-queue/** ref compares with the given base. Every other ref keeps the first-parent rule. GITHUB_REF joins the runner-owned variables of check-env-doc-sync (the gates read it; it is not OmniRoute configuration). Existing assertions changed on purpose (same strictness, new expression): - tests/unit/build/check-boundary-ratchet.test.ts: the two exact matches of the PR_BASE_SHA binding (ci.yml lint, quality.yml fast-gates) now expect "github.event.pull_request.base.sha || needs.changes.outputs.candidateBase". - tests/unit/quality-rail-gate-membership.test.ts: the PR_BASE_SHA regex of the TS7 ratchet expects the same expression.
449 lines
16 KiB
JavaScript
449 lines
16 KiB
JavaScript
#!/usr/bin/env node
|
|
// scripts/check/check-dead-code.mjs
|
|
// Gate de dead-code via knip — unused exports, unused files.
|
|
// Fase 7 INT: promovido de ADVISORY para RATCHET bloqueante.
|
|
// Lê o baseline de quality-baseline.json (metrics.deadExports), compara e
|
|
// falha com exit 1 se a contagem SUBIR. Suporta --update para ratchetar o baseline.
|
|
//
|
|
// Saída (stdout):
|
|
// DEAD_EXPORTS=<n> — exports/re-exports/tipos não utilizados
|
|
// DEAD_FILES=<n> — arquivos sem nenhum consumidor
|
|
// DEAD_TOTAL=<n> — soma de ambos (métrica primária para o ratchet)
|
|
//
|
|
// Use --json para imprimir o relatório completo do knip em JSON.
|
|
// Use --quiet para suprimir logs de diagnóstico.
|
|
// Use --update para ratchetar o baseline quando a contagem cair legitimamente.
|
|
|
|
import { execFileSync } from "node:child_process";
|
|
import fs from "node:fs";
|
|
import path from "node:path";
|
|
import { pathToFileURL } from "node:url";
|
|
import {
|
|
baseRefArg,
|
|
listChangedFiles,
|
|
newDeadSymbols,
|
|
resolveMergeBase,
|
|
withBaseWorktree,
|
|
} from "./newCodeMode.mjs";
|
|
|
|
const ROOT = process.cwd();
|
|
const QUIET = process.argv.includes("--quiet");
|
|
const BASE_REF = baseRefArg();
|
|
const PRINT_JSON = process.argv.includes("--json");
|
|
const UPDATE = process.argv.includes("--update");
|
|
|
|
const BASELINE_PATH = path.resolve(
|
|
process.argv.includes("--baseline")
|
|
? process.argv[process.argv.indexOf("--baseline") + 1]
|
|
: path.join(ROOT, "config/quality/quality-baseline.json")
|
|
);
|
|
|
|
/**
|
|
* Conta dead exports e dead files a partir do output JSON do knip.
|
|
*
|
|
* O reporter JSON do knip emite:
|
|
* { issues: Array<{ file, exports?, files?, types?, nsExports?, nsTypes?, ... }> }
|
|
*
|
|
* Cada entrada em `exports`, `types`, `nsExports`, `nsTypes` é um símbolo morto naquele
|
|
* arquivo. A presença do arquivo em si na lista (campo `files: []` não-vazio ou arquivo
|
|
* sem outros campos relevantes com `files: true` no include) indica arquivo morto.
|
|
*
|
|
* @param {object} knipJson - Objeto JSON parseado do output do knip
|
|
* @returns {{ deadExports: number, deadFiles: number, deadTotal: number }}
|
|
*/
|
|
export function parseKnipMetrics(knipJson) {
|
|
if (!knipJson || !Array.isArray(knipJson.issues)) {
|
|
return { deadExports: 0, deadFiles: 0, deadTotal: 0 };
|
|
}
|
|
|
|
let deadExports = 0;
|
|
let deadFiles = 0;
|
|
|
|
for (const fileEntry of knipJson.issues) {
|
|
// Dead file: o arquivo aparece na lista com campo `files` populado
|
|
// (knip emite um entry com files:[] indicando "este arquivo é morto")
|
|
if (Array.isArray(fileEntry.files) && fileEntry.files.length > 0) {
|
|
deadFiles += fileEntry.files.length;
|
|
}
|
|
// Alguns reporters indicam arquivo morto sem campo files — o entry existe
|
|
// sem exports/types = o arquivo inteiro não tem consumidor
|
|
// (conservador: só contar quando files[] está presente e populado)
|
|
|
|
// Dead exports: somar todos os símbolos mortos por tipo de export
|
|
const exportFields = [
|
|
"exports",
|
|
"types",
|
|
"nsExports",
|
|
"nsTypes",
|
|
"enumMembers",
|
|
"namespaceMembers",
|
|
"duplicates",
|
|
];
|
|
for (const field of exportFields) {
|
|
if (Array.isArray(fileEntry[field])) {
|
|
deadExports += fileEntry[field].length;
|
|
}
|
|
}
|
|
}
|
|
|
|
return {
|
|
deadExports,
|
|
deadFiles,
|
|
deadTotal: deadExports + deadFiles,
|
|
};
|
|
}
|
|
|
|
/**
|
|
* Exit taxonomy of this gate (G-07, #15159).
|
|
*
|
|
* Before this was documented, every failure path collapsed to exit 2, so a
|
|
* missing knip binary and a genuine knip failure were indistinguishable — an
|
|
* infra-down run presented exactly like a repo with dead code, and a reviewer
|
|
* chasing exit 2 found nothing wrong with their code.
|
|
*
|
|
* 0 OK no regression
|
|
* 1 POLICY dead-code regression — a REAL repo defect
|
|
* 2 CONFIG baseline missing / metric key absent / unparseable knip
|
|
* output — an operator-config or tool-contract fault
|
|
* 3 INFRASTRUCTURE knip missing or unrunnable — the TOOLCHAIN, not the repo
|
|
*
|
|
* Exit 3 is the load-bearing one: it is what lets CI and a reviewer tell "knip
|
|
* isn't installed" from "your code has dead exports".
|
|
*/
|
|
export const DEAD_CODE_EXIT = {
|
|
OK: 0,
|
|
POLICY: 1,
|
|
CONFIG: 2,
|
|
INFRASTRUCTURE: 3,
|
|
};
|
|
|
|
/** Node/child_process error codes that mean "the tool never ran". */
|
|
const INFRASTRUCTURE_ERROR_CODES = new Set([
|
|
"ENOENT", // executable not found — knip not installed
|
|
"EACCES", // not executable
|
|
"EPERM",
|
|
"ETIMEDOUT", // knip exceeded the 300s timeout
|
|
"ESIGTERM", // killed by the OS / runner shutdown
|
|
"ENOMEM",
|
|
"EAGAIN",
|
|
// Windows: a `.cmd` shim cannot be spawned by execFileSync without
|
|
// `shell: true`, so it fails EINVAL. Found by running the gate end-to-end with
|
|
// the Node entrypoint removed — this was classified as a CONFIG fault, which
|
|
// is exactly the misattribution G-07 exists to eliminate: EINVAL here means
|
|
// "this spawn cannot work", never "knip produced garbage".
|
|
"EINVAL",
|
|
]);
|
|
|
|
/**
|
|
* Resolve a runnable knip entrypoint (G-07 follow-up, found while verifying it).
|
|
*
|
|
* `node_modules/.bin/knip` is a `#!/bin/sh` wrapper. `execFileSync` cannot run a
|
|
* POSIX shell script on Windows, so on that platform the gate failed with ENOENT
|
|
* on EVERY run — the "infra-down presents as repo-broken" symptom with a
|
|
* permanently-down cause, i.e. the ratchet was inert on Windows rather than
|
|
* merely noisy.
|
|
*
|
|
* So on Windows prefer the package's own Node entrypoint
|
|
* (`node_modules/knip/bin/knip.js`), which is a plain JS file any Node can run.
|
|
* POSIX keeps the conventional `.bin` shim. Returns null when knip is genuinely
|
|
* absent so the caller can report exit 3 instead of throwing ENOENT.
|
|
*
|
|
* Exported for unit testing.
|
|
*
|
|
* @param {{platform?: string, existsSync?: (p: string) => boolean}} [opts]
|
|
* @returns {string | null} path to exec, or null when knip is not installed
|
|
*/
|
|
export function resolveKnipBin(opts = {}) {
|
|
const platform = opts.platform ?? process.platform;
|
|
const exists = opts.existsSync ?? ((p) => fs.existsSync(p));
|
|
|
|
const candidates =
|
|
platform === "win32"
|
|
? [
|
|
// Authoritative, cross-platform entrypoint: a plain JS file any Node
|
|
// can run. Preferred on Windows for exactly that reason.
|
|
path.join("node_modules", "knip", "bin", "knip.js"),
|
|
// `.cmd` is deliberately NOT a fallback: execFileSync cannot spawn one
|
|
// without `shell: true` (it fails EINVAL), so listing it would resolve
|
|
// to a path that is guaranteed to fail. Prefer reporting the real
|
|
// "knip is not usable here" over picking an unrunnable candidate.
|
|
path.join("node_modules", ".bin", "knip"),
|
|
]
|
|
: [path.join("node_modules", ".bin", "knip")];
|
|
|
|
for (const candidate of candidates) {
|
|
if (exists(candidate)) return candidate;
|
|
}
|
|
return null;
|
|
}
|
|
|
|
/**
|
|
* Parse knip's `--reporter json` stdout.
|
|
*
|
|
* knip >= 6.44 loads `next.config.*`, and ours calls fumadocs-mdx `createMDX()`,
|
|
* which prints "[MDX] generated files in …ms" to stdout before the report. The
|
|
* report is still intact, so read it from the first line that opens a JSON object.
|
|
* Output with no JSON report still throws a SyntaxError.
|
|
*
|
|
* Exported for unit testing.
|
|
*
|
|
* @param {string} stdout
|
|
* @returns {unknown} the parsed report
|
|
*/
|
|
export function parseKnipStdout(stdout) {
|
|
const text = String(stdout ?? "").trim();
|
|
try {
|
|
return JSON.parse(text);
|
|
} catch (err) {
|
|
const lines = text.split(/\r?\n/);
|
|
const start = lines.findIndex((line) => line.trimStart().startsWith("{"));
|
|
if (start <= 0) throw err;
|
|
return JSON.parse(lines.slice(start).join("\n"));
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Classify a knip invocation outcome.
|
|
*
|
|
* The subtlety this exists for: knip LEGITIMATELY exits non-zero when it finds
|
|
* issues — that is the entire purpose of this gate — and still prints a full
|
|
* JSON report on stdout. So "threw" is not the same as "failed". A non-zero exit
|
|
* WITH parseable JSON is a successful measurement (kind "ok"); only a run that
|
|
* produced nothing usable is a failure.
|
|
*
|
|
* Exported for unit testing.
|
|
*
|
|
* @param {{code?: string, message?: string} | null} execError - the thrown error, or null on success
|
|
* @param {string} stdout - whatever knip wrote to stdout
|
|
* @returns {{kind: "ok"|"infra"|"unparseable", exitCode: number, reason: string}}
|
|
*/
|
|
export function classifyKnipFailure(execError, stdout) {
|
|
const text = typeof stdout === "string" ? stdout.trim() : "";
|
|
|
|
// No error at all: knip ran and succeeded.
|
|
if (!execError) {
|
|
return { kind: "ok", exitCode: DEAD_CODE_EXIT.OK, reason: "knip completed" };
|
|
}
|
|
|
|
// An error, but it still produced parseable JSON — a legitimate non-zero exit
|
|
// reporting findings. This is a successful measurement, not a failure.
|
|
if (text) {
|
|
try {
|
|
parseKnipStdout(text);
|
|
return {
|
|
kind: "ok",
|
|
exitCode: DEAD_CODE_EXIT.OK,
|
|
reason: `knip reported findings (exit ${execError.status ?? "non-zero"})`,
|
|
};
|
|
} catch {
|
|
// fall through to the unparseable classification below
|
|
}
|
|
}
|
|
|
|
// No usable output. Distinguish "the tool never ran" from "the tool ran but
|
|
// its output is not the JSON contract we expect".
|
|
const code = execError.code;
|
|
if (code && INFRASTRUCTURE_ERROR_CODES.has(code)) {
|
|
return {
|
|
kind: "infra",
|
|
exitCode: DEAD_CODE_EXIT.INFRASTRUCTURE,
|
|
reason:
|
|
`knip is unavailable (${code}) — this is a TOOLCHAIN problem, not a repo ` +
|
|
`defect. Install dev dependencies (npm ci) and re-run; do not treat this as ` +
|
|
`a dead-code finding. Original error: ${execError.message ?? "unknown"}`,
|
|
};
|
|
}
|
|
|
|
return {
|
|
kind: "unparseable",
|
|
exitCode: DEAD_CODE_EXIT.CONFIG,
|
|
reason:
|
|
`knip produced no parseable JSON report — the tool exited abnormally ` +
|
|
`(${execError.message ?? "unknown"}).`,
|
|
};
|
|
}
|
|
|
|
/**
|
|
* Avalia a contagem atual de dead-code total contra o baseline.
|
|
* Direction: down (contagem só pode CAIR).
|
|
*
|
|
* Exported for unit testing.
|
|
*
|
|
* @param {number} current
|
|
* @param {number} baseline
|
|
* @returns {{ regressed: boolean, improved: boolean }}
|
|
*/
|
|
export function evaluateDeadCode(current, baseline) {
|
|
return {
|
|
regressed: current > baseline,
|
|
improved: current < baseline,
|
|
};
|
|
}
|
|
|
|
function runKnip(cwd = ROOT) {
|
|
const knipBin = resolveKnipBin();
|
|
if (!knipBin) {
|
|
// Genuinely not installed — report it as infrastructure (exit 3), never as a
|
|
// dead-code finding, so CI and a reviewer can tell the two apart.
|
|
process.stderr.write(
|
|
"[dead-code] knip is not installed (no runnable entrypoint found under " +
|
|
"node_modules/). This is a TOOLCHAIN problem, not a repo defect: run " +
|
|
"'npm ci' and re-run. Do not treat this as a dead-code finding.\n"
|
|
);
|
|
process.exit(DEAD_CODE_EXIT.INFRASTRUCTURE);
|
|
}
|
|
|
|
const knipArgs = [
|
|
"--reporter",
|
|
"json",
|
|
"--no-progress",
|
|
"--no-exit-code", // não falha por contagem — só coletamos métricas
|
|
];
|
|
// A `.js` entrypoint must be run through node; a `.bin`/`.cmd` shim is directly
|
|
// executable on its own platform.
|
|
const isNodeScript = knipBin.endsWith(".js");
|
|
const command = isNodeScript ? process.execPath : knipBin;
|
|
const args = isNodeScript ? [knipBin, ...knipArgs] : knipArgs;
|
|
|
|
if (!QUIET) {
|
|
process.stderr.write(`[dead-code] Rodando knip --reporter json (${knipBin}) ...\n`);
|
|
}
|
|
|
|
let stdout;
|
|
let execError = null;
|
|
try {
|
|
stdout = execFileSync(command, args, {
|
|
cwd,
|
|
encoding: "utf8",
|
|
maxBuffer: 128 * 1024 * 1024,
|
|
timeout: 300_000, // 5 min (knip pode ser lento em monorepos grandes)
|
|
});
|
|
} catch (err) {
|
|
// knip sai com código != 0 quando encontra issues; o JSON ainda vai no stdout.
|
|
// Não tratar "lançou" como "falhou": ver classifyKnipFailure.
|
|
execError = err;
|
|
stdout = err.stdout ? String(err.stdout) : "";
|
|
}
|
|
|
|
// G-07: a falha de infra (knip ausente/inexecutável) NÃO pode sair com o mesmo
|
|
// código de uma falha de config — senão "infra caiu" e "repo tem código morto"
|
|
// são indistinguíveis para o CI e para quem lê o log.
|
|
const outcome = classifyKnipFailure(execError, stdout);
|
|
if (outcome.kind !== "ok") {
|
|
process.stderr.write(`[dead-code] ${outcome.reason}\n`);
|
|
if (outcome.kind === "unparseable") {
|
|
process.stderr.write(
|
|
`[dead-code] stdout (primeiros 500 chars): ${String(stdout).slice(0, 500)}\n`
|
|
);
|
|
}
|
|
process.exit(outcome.exitCode);
|
|
}
|
|
|
|
let knipJson;
|
|
try {
|
|
knipJson = parseKnipStdout(stdout);
|
|
} catch (parseErr) {
|
|
// Unreachable via classifyKnipFailure (it already JSON-parsed), kept as a
|
|
// defensive guard so a future change cannot turn this into exit 2.
|
|
process.stderr.write(`[dead-code] ERRO ao parsear JSON do knip: ${parseErr.message}\n`);
|
|
process.exit(DEAD_CODE_EXIT.CONFIG);
|
|
}
|
|
|
|
return knipJson;
|
|
}
|
|
|
|
/**
|
|
* New-code mode (PR events, `--base-ref <sha>`): knip on HEAD and on the merge-base; blocking
|
|
* only on dead symbols the PR introduced in files it touched. The global count is printed as
|
|
* an advisory (the release reconciliation re-freezes it). See newCodeMode.mjs.
|
|
*/
|
|
function mainNewCode(baselineValue) {
|
|
const mergeBase = resolveMergeBase(BASE_REF, { ref: process.env.GITHUB_REF });
|
|
const changed = listChangedFiles(mergeBase, {
|
|
dirs: ["src", "open-sse", "electron", "bin", "scripts"],
|
|
exts: [".ts", ".tsx", ".js", ".mjs"],
|
|
// Knip still reports vendor symbols in the global advisory total. Exclude them only from
|
|
// the PR authorship comparison so vendored public APIs remain faithful to upstream.
|
|
excludePrefixes: ["open-sse/vendor/"],
|
|
});
|
|
const headKnip = runKnip();
|
|
const { deadTotal } = parseKnipMetrics(headKnip);
|
|
console.log(`DEAD_TOTAL=${deadTotal}`);
|
|
const over = deadTotal > baselineValue ? " — OVER, re-freeze at release" : "";
|
|
console.log(
|
|
`[dead-code] new-code mode: merge-base ${mergeBase.slice(0, 12)}, ${changed.length} changed file(s); global ${deadTotal} vs baseline ${baselineValue} (advisory${over})`
|
|
);
|
|
if (changed.length === 0) {
|
|
console.log("[dead-code] OK — no source files changed; nothing to compare.");
|
|
return;
|
|
}
|
|
const baseKnip = withBaseWorktree(mergeBase, (dir) => runKnip(dir));
|
|
const added = newDeadSymbols(headKnip, baseKnip, changed);
|
|
console.log(`deadExportsNewCode=${added.length}`);
|
|
if (added.length) {
|
|
process.stderr.write(
|
|
`[dead-code] REGRESSÃO (código novo) — ${added.length} símbolo(s) morto(s) introduzido(s) nos arquivos tocados:\n` +
|
|
added.map((k) => ` ✗ ${k}`).join("\n") +
|
|
"\n → remova o export (ou use-o). O total global do repo não conta aqui.\n"
|
|
);
|
|
process.exit(DEAD_CODE_EXIT.POLICY);
|
|
}
|
|
console.log(
|
|
`[dead-code] OK (código novo) — nenhum símbolo morto novo nos ${changed.length} arquivo(s) tocado(s)`
|
|
);
|
|
}
|
|
|
|
function main() {
|
|
if (!fs.existsSync(BASELINE_PATH)) {
|
|
process.stderr.write(`[dead-code] FAIL — ${path.basename(BASELINE_PATH)} ausente.\n`);
|
|
process.exit(DEAD_CODE_EXIT.CONFIG);
|
|
}
|
|
|
|
const baselineJson = JSON.parse(fs.readFileSync(BASELINE_PATH, "utf8"));
|
|
const baselineMetric = baselineJson.metrics && baselineJson.metrics.deadExports;
|
|
if (!baselineMetric || typeof baselineMetric.value !== "number") {
|
|
process.stderr.write(
|
|
"[dead-code] FAIL — metrics.deadExports ausente em quality-baseline.json.\n"
|
|
);
|
|
process.exit(DEAD_CODE_EXIT.CONFIG);
|
|
}
|
|
const baselineValue = baselineMetric.value;
|
|
if (BASE_REF && !PRINT_JSON && !UPDATE) return mainNewCode(baselineValue);
|
|
|
|
const knipJson = runKnip();
|
|
|
|
if (PRINT_JSON) {
|
|
process.stdout.write(JSON.stringify(knipJson, null, 2) + "\n");
|
|
return;
|
|
}
|
|
|
|
const { deadExports, deadFiles, deadTotal } = parseKnipMetrics(knipJson);
|
|
|
|
// Emitir em formato KEY=VALUE para o coletor de métricas (collect-metrics.mjs)
|
|
console.log(`DEAD_EXPORTS=${deadExports}`);
|
|
console.log(`DEAD_FILES=${deadFiles}`);
|
|
console.log(`DEAD_TOTAL=${deadTotal}`);
|
|
|
|
const { regressed, improved } = evaluateDeadCode(deadTotal, baselineValue);
|
|
|
|
if (UPDATE && improved) {
|
|
baselineJson.metrics.deadExports.value = deadTotal;
|
|
fs.writeFileSync(BASELINE_PATH, JSON.stringify(baselineJson, null, 2) + "\n");
|
|
console.log(`[dead-code] baseline ratcheado: ${deadTotal} (era ${baselineValue})`);
|
|
}
|
|
|
|
if (regressed) {
|
|
process.stderr.write(
|
|
`[dead-code] REGRESSÃO — ${deadTotal} símbolos mortos > baseline ${baselineValue}\n` +
|
|
` → Remova exports/arquivos não utilizados ou rode\n` +
|
|
` 'node scripts/check/check-dead-code.mjs --update' se a contagem caiu legitimamente.\n`
|
|
);
|
|
process.exit(DEAD_CODE_EXIT.POLICY);
|
|
}
|
|
|
|
console.log(`[dead-code] OK — ${deadTotal} símbolos mortos (baseline ${baselineValue})`);
|
|
process.exitCode = DEAD_CODE_EXIT.OK;
|
|
}
|
|
|
|
if (import.meta.url === pathToFileURL(process.argv[1] || "").href) main();
|