bin/no-bloat.mjs

Functions

Imports

It imports no other module of this repo. No module of this repo imports it.

Source

1#!/usr/bin/env node
2// The no-bloat ratchet. Knip for unused files, exports and dependencies, jscpd for duplicated blocks, each count compared
3// with the repository's own baseline. A count above its baseline fails the run (exit 1, an ::error:: line per count); a count
4// at or below it passes, and one that went down is named so the baseline can be lowered to lock the gain in. A tool that
5// cannot run fails the run too (an ::error:: naming its error): a count nobody measured is not a pass. The table goes to the
6// job summary.
7//
8//   npx devkit-no-bloat                      report against .no-bloat.json (no file: one knip run, jscpd on its own config)
9//   npx devkit-no-bloat --config <file>      another config
10//   npx devkit-no-bloat --write-baseline     measure and record the counts as the config's baseline
11//   npx devkit-no-bloat --warn-only          the same report, every error a warning, exit 0: a report, never a gate
12//
13// The config, every field optional:
14//
15//   {
16//     "knip": [{ "label": "knip (Worker)" }, { "label": "knip (dashboard)", "args": ["--directory", "dashboard"] }],
17//     "jscpd": { "args": ["app", "workers", "--min-lines", "8"] },
18//     "tools": { "knip": "knip@6", "jscpd": "jscpd@4" },
19//     "baseline": { "measured_at": "036d615", "knip (Worker)": { "Unused exports": 12 }, "jscpd": { "clones": 23, "percentage": 0.59 } }
20//   }
21//
22// A tool the repository installs is run from node_modules/.bin; otherwise through npx at the spec in `tools`.
23
24import { execFileSync, spawnSync } from "node:child_process";
25import { appendFileSync, existsSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
26import { tmpdir } from "node:os";
27import { join, resolve } from "node:path";
28import { pathToFileURL } from "node:url";
29
30export const DEFAULT_TOOLS = { knip: "knip@6", jscpd: "jscpd@4" };
31
32/**
33 * @typedef {{ label: string, args?: string[] }} KnipRun
34 * @typedef {{ knip?: KnipRun[], jscpd?: { args?: string[] } | false, tools?: { knip?: string, jscpd?: string },
35 *   baseline?: Record<string, unknown> & { measured_at?: string } }} Config
36 * @typedef {(name: "knip" | "jscpd", args: string[]) => string} Runner
37 * @typedef {Record<string, Record<string, number>>} Counts
38 */
39
40/** Knip's compact report as counts per heading, e.g. { "Unused exports": 12 }. */
41export function knipCounts(/** @type {string} */ text) {
42  /** @type {Record<string, number>} */
43  const counts = {};
44  for (const m of text.matchAll(/^([A-Z][A-Za-z ]+) \((\d+)\)$/gm)) counts[m[1]] = Number(m[2]);
45  return counts;
46}
47
48/**
49 * Runs every tool the config names and returns the counts, keyed as the baseline is, and a warning for each tool that could
50 * not run.
51 * @param {Config} config
52 * @param {Runner} run
53 * @param {boolean} [jscpdConfigured] whether the repository has its own .jscpd.json, which then names the paths
54 * @returns {{ counts: Counts, warnings: string[] }}
55 */
56export function measure(config, run, jscpdConfigured = true) {
57  /** @type {Counts} */
58  const counts = {};
59  const warnings = [];
60
61  for (const { label, args = [] } of config.knip ?? [{ label: "knip" }]) {
62    try {
63      counts[label] = knipCounts(run("knip", [...args, "--no-exit-code", "--no-progress", "--reporter", "compact"]));
64    } catch (error) {
65      warnings.push(`${label} could not run: ${messageOf(error)}`);
66    }
67  }
68
69  if (config.jscpd !== false) {
70    const own = config.jscpd?.args ?? [];
71    // jscpd with no path and no config of its own scans nothing; the repository root is the honest default.
72    const paths = own.length === 0 && !jscpdConfigured ? ["."] : [];
73    const out = mkdtempSync(join(tmpdir(), "jscpd-"));
74    try {
75      run("jscpd", [...own, ...paths, "--reporters", "json", "--output", out, "--silent"]);
76      const total = JSON.parse(readFileSync(join(out, "jscpd-report.json"), "utf8")).statistics.total;
77      counts.jscpd = { clones: total.clones, percentage: Number(Number(total.percentage).toFixed(2)) };
78    } catch (error) {
79      warnings.push(`jscpd could not run: ${messageOf(error)}`);
80    } finally {
81      rmSync(out, { recursive: true, force: true });
82    }
83  }
84
85  return { counts, warnings };
86}
87
88/**
89 * One row per finding the baseline or the measurement names, an error for each that grew, and a note for each that went
90 * down. A finding with no baseline is a row and never an error: there is nothing to have grown from.
91 * @param {Record<string, unknown>} baseline
92 * @param {Counts} counts
93 * @param {KnipRun[]} [knipRuns]
94 */
95export function compare(baseline, counts, knipRuns = [{ label: "knip" }]) {
96  /** @type {Array<[string, string, number | null, number]>} */
97  const rows = [];
98  const errors = [];
99  const lowered = [];
100  const before = (/** @type {string} */ tool) => /** @type {Record<string, number> | null} */ (tool in baseline ? baseline[tool] : null);
101
102  for (const [tool, now] of Object.entries(counts)) {
103    if (tool === "jscpd") continue;
104    const was = before(tool);
105    const keys = [...new Set([...Object.keys(was ?? {}), ...Object.keys(now)])];
106    // A clean run is a row too, so the table shows the tool ran.
107    if (keys.length === 0) rows.push([tool, "findings", was ? 0 : null, 0]);
108    for (const key of keys) {
109      const a = was ? (was[key] ?? 0) : null;
110      const b = now[key] ?? 0;
111      rows.push([tool, key, a, b]);
112      if (a !== null && b > a) {
113        const args = knipRuns.find((r) => r.label === tool)?.args ?? [];
114        errors.push(`${tool}: ${key} went from ${a} to ${b}. Run \`npx knip${args.length ? ` ${args.join(" ")}` : ""}\` to see which.`);
115      }
116      if (a !== null && b < a) lowered.push(`${tool}: ${key} ${a} to ${b}`);
117    }
118  }
119
120  if (counts.jscpd) {
121    const was = before("jscpd");
122    const now = counts.jscpd;
123    rows.push(["jscpd", "clones", was ? (was.clones ?? 0) : null, now.clones]);
124    rows.push(["jscpd", "duplicated lines %", was ? (was.percentage ?? 0) : null, now.percentage]);
125    if (was && now.clones < (was.clones ?? 0)) lowered.push(`jscpd: clones ${was.clones} to ${now.clones}`);
126    if (was && now.clones > (was.clones ?? 0)) {
127      errors.push(`jscpd: clones went from ${was.clones ?? 0} to ${now.clones} (${now.percentage}% of lines, baseline ${was.percentage ?? 0}%). Run \`npx jscpd\` to see them.`);
128    }
129  }
130  return { rows, errors, lowered };
131}
132
133/**
134 * The job summary table.
135 * @param {Array<[string, string, number | null, number]>} rows
136 * @param {string[]} problems the errors, then the warnings
137 * @param {string | undefined} measuredAt
138 * @param {boolean} [warnOnly]
139 */
140export function render(rows, problems, measuredAt, warnOnly = false) {
141  const show = (/** @type {number | null} */ n) => (n === null ? "none" : String(n));
142  return [
143    `### No-bloat ${warnOnly ? "report (warn-only, never blocks a merge)" : "ratchet"} (${measuredAt ? `baseline ${measuredAt}` : "no baseline yet: run `npx devkit-no-bloat --write-baseline`"})`,
144    "",
145    "| Tool | Finding | Baseline | Now |",
146    "|---|---|---|---|",
147    ...rows.map(([tool, key, a, b]) => `| ${tool} | ${key} | ${show(a)} | ${b}${a !== null && b > a ? " (up)" : ""} |`),
148    "",
149    problems.length ? problems.map((w) => `- ${w}`).join("\n") : "Nothing grew past the baseline.",
150  ].join("\n");
151}
152
153/**
154 * The npx arguments for a tool that is not installed. The package is named with --package, never as the command: run
155 * under `npx --package <devkit>`, this bin inherits npm_config_package, and a bare `npx knip@6` would then look for a
156 * command called "knip@6" in devkit.
157 */
158export function npxArgs(/** @type {string} */ name, /** @type {string} */ spec, /** @type {string[]} */ args) {
159  return ["--yes", "--package", spec, "--", name, ...args];
160}
161
162/** Runs a tool from the repository's node_modules/.bin when it is installed there, through npx at `spec` otherwise. */
163export function runnerIn(/** @type {string} */ root, /** @type {{ knip: string, jscpd: string }} */ tools) {
164  /** @type {Runner} */
165  return (name, args) => {
166    const local = join(root, "node_modules", ".bin", process.platform === "win32" ? `${name}.cmd` : name);
167    const [file, argv] = existsSync(local) ? [local, args] : ["npx", npxArgs(name, tools[name], args)];
168    // A .cmd shim (and npx itself) on Windows needs cmd.exe; elsewhere the bin runs directly.
169    const [cmd, all] = process.platform === "win32" ? ["cmd.exe", ["/c", file, ...argv]] : [file, argv];
170    const r = spawnSync(cmd, all, { cwd: root, encoding: "utf8", maxBuffer: 64 * 1024 * 1024 });
171    if (r.error) throw r.error;
172    if (r.status !== 0) throw new Error(`${name} exited ${r.status}: ${(r.stderr || r.stdout).trim().slice(0, 400)}`);
173    return r.stdout;
174  };
175}
176
177function messageOf(/** @type {unknown} */ error) {
178  return error instanceof Error ? error.message : String(error);
179}
180
181function shortHead(/** @type {string} */ root) {
182  try {
183    return execFileSync("git", ["rev-parse", "--short", "HEAD"], { cwd: root, encoding: "utf8" }).trim();
184  } catch {
185    return new Date().toISOString().slice(0, 10);
186  }
187}
188
189function main() {
190  const argv = process.argv.slice(2);
191  const at = argv.indexOf("--config");
192  const root = process.cwd();
193  const file = resolve(root, at >= 0 && argv[at + 1] ? argv[at + 1] : ".no-bloat.json");
194  const write = argv.includes("--write-baseline");
195  const warnOnly = argv.includes("--warn-only");
196
197  /** @type {Config} */
198  let config = {};
199  if (existsSync(file)) {
200    try {
201      config = JSON.parse(readFileSync(file, "utf8"));
202    } catch (error) {
203      // A broken config would otherwise be no baseline, and so a ratchet that passes everything.
204      console.error(`devkit-no-bloat: ${file} is not JSON: ${messageOf(error)}`);
205      process.exit(1);
206    }
207  }
208
209  const measured = measure(config, runnerIn(root, { ...DEFAULT_TOOLS, ...config.tools }), existsSync(join(root, ".jscpd.json")));
210
211  if (write) {
212    if (measured.warnings.length) {
213      for (const w of measured.warnings) console.error(`devkit-no-bloat: ${w}`);
214      console.error("devkit-no-bloat: the baseline was not written, because a tool could not run.");
215      process.exit(1);
216    }
217    config.baseline = { measured_at: shortHead(root), ...measured.counts };
218    writeFileSync(file, `${JSON.stringify(config, null, 2)}\n`);
219    console.log(`devkit-no-bloat: wrote the baseline to ${file}`);
220    return;
221  }
222
223  const { rows, errors, lowered } = compare(config.baseline ?? {}, measured.counts, config.knip);
224  /** @type {string[]} */
225  const warnings = [];
226  if (errors.length) {
227    errors.push("Remove what was added. If it is deliberate, run `npx devkit-no-bloat --write-baseline` and commit the config, so the raise is reviewed.");
228  }
229  errors.unshift(...measured.warnings);
230  if (lowered.length) {
231    warnings.push(`Lower the baseline to lock this in (${lowered.join(", ")}): run \`npx devkit-no-bloat --write-baseline\` and commit the config.`);
232  }
233  const table = render(rows, [...errors, ...warnings], config.baseline?.measured_at, warnOnly);
234  console.log(table);
235  for (const e of errors) console.log(`::${warnOnly ? "warning" : "error"}::${e}`);
236  for (const w of warnings) console.log(`::warning::${w}`);
237  if (process.env.GITHUB_STEP_SUMMARY) appendFileSync(process.env.GITHUB_STEP_SUMMARY, `${table}\n`);
238  if (errors.length && !warnOnly) process.exit(1);
239}
240
241// Run through node_modules/.bin, argv[1] is the link and import.meta.url the file it points to.
242if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) main();