Files
hyperframes/scripts/check-docs-impact.mjs
T
ukimsanovandClaude Opus 5.5 b849f70834 ci(docs): keep the docs checks under the complexity budget and known to the workflow tests
Splits codeSpans, the flag and subcommand walk, the export walker and the
docs-impact entry point into small functions so fallow's audit passes, adds
scripts/cli-command-tree.test.ts (cli.ts's loader block and a citty command
described end to end), and lists docs-impact.yml among the workflows that read
the PR body on an edit.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 02:09:32 -04:00

167 lines
7.1 KiB
JavaScript

// A pull request that changes what users type or import must change the docs with it.
//
// Fails when, between the merge base and HEAD, either surface changed and nothing under docs/ did:
// CLI every command, subcommand and flag the citty definitions declare (scripts/cli-command-tree.ts),
// hidden ones excepted; flag value types and deprecation count as changes.
// exports every public package's exports subpaths, bin names and root-entry exports
// (scripts/public-api-surface.mjs).
// The PR opts out with the `docs-not-needed` label or a `docs-impact: none` line in its body
// (PR_LABELS: JSON array of label names or label objects; PR_BODY: the body).
//
// node scripts/check-docs-impact.mjs [--base <ref>] [--dry-run] [--base-tree <json>] [--head-tree <json>]
//
// The base CLI tree is built from a temporary worktree (bun install + core build), only when the CLI's
// sources changed. --dry-run prints the verdict and exits 0.
import { execFileSync } from "node:child_process";
import { mkdtempSync, readFileSync, realpathSync, rmSync } from "node:fs";
import { tmpdir } from "node:os";
import { join, resolve } from "node:path";
import { pathToFileURL } from "node:url";
import { publicApiSurface } from "./public-api-surface.mjs";
const ROOT = resolve(import.meta.dirname, "..");
export const OPT_OUT_LABEL = "docs-not-needed";
const OPT_OUT_BODY = /^\s*docs-impact:\s*none\b/im;
const CLI_SOURCE =
/^packages\/cli\/src\/(?!.*\.test\.tsx?$)(?!(?:.*\/)?(?:__fixtures__|fixtures)\/)/;
const PACKAGE_SOURCE = /^packages\/[^/]+\/(?:package\.json$|src\/)/;
/** One line per user-visible command, flag and alias, e.g. `hyperframes render --output <string>`. */
export function cliSurface(tree, path = ["hyperframes"]) {
const shown = path.join(" ");
const lines = [path.length > 1 ? `${shown}${tree.deprecated ? " (deprecated)" : ""}` : shown];
for (const [name, flag] of Object.entries(tree.flags)) {
if (flag.hidden) continue;
const value = flag.type === "boolean" ? "" : ` <${flag.type}>`;
lines.push(`${shown} --${name}${value}${flag.deprecated ? " (deprecated)" : ""}`);
for (const alias of flag.aliases) lines.push(`${shown} -${alias} = --${name}`);
}
for (const [name, sub] of Object.entries(tree.subCommands)) {
if (!sub.hidden) lines.push(...cliSurface(sub, [...path, name]));
}
return lines;
}
/** `-` lines the base had and HEAD lost, then `+` lines HEAD added. */
export function surfaceDiff(base, head) {
const before = new Set(base);
const after = new Set(head);
return [
...base.filter((line) => !after.has(line)).map((line) => `- ${line}`),
...head.filter((line) => !before.has(line)).map((line) => `+ ${line}`),
];
}
/** Why the PR may skip docs, or null. */
export function optOutReason({ labels = [], body = "" }) {
const names = labels.map((label) => (typeof label === "string" ? label : label?.name));
if (names.includes(OPT_OUT_LABEL)) return `labelled ${OPT_OUT_LABEL}`;
if (OPT_OUT_BODY.test(body)) return "the body says `docs-impact: none`";
return null;
}
export const touchesDocs = (files) => files.some((file) => file.startsWith("docs/"));
export const touchesCli = (files) => files.some((file) => CLI_SOURCE.test(file));
export const touchesPackages = (files) => files.some((file) => PACKAGE_SOURCE.test(file));
function git(args, cwd = ROOT) {
return execFileSync("git", args, { cwd, encoding: "utf8", maxBuffer: 1 << 26 }).trim();
}
// Output is kept for the error a failed step throws, not printed: installs and builds are noisy.
function run(command, args, cwd) {
return execFileSync(command, args, {
cwd,
encoding: "utf8",
maxBuffer: 1 << 26,
env: { ...process.env, HYPERFRAMES_NO_TELEMETRY: "1", GIT_LFS_SKIP_SMUDGE: "1" },
stdio: ["ignore", "pipe", "pipe"],
});
}
const treeAt = (root) =>
JSON.parse(run("bun", [join(ROOT, "scripts", "cli-command-tree.ts"), "--root", root], root));
// The base revision's command modules need their own dependencies and generated core sources.
function baseTree(sha) {
const dir = mkdtempSync(join(tmpdir(), "hf-docs-impact-"));
try {
run("git", ["worktree", "add", "--detach", dir, sha], ROOT);
run("bun", ["install", "--frozen-lockfile", "--ignore-scripts"], dir);
run("bun", ["run", "--cwd", "packages/core", "build"], dir);
return treeAt(dir);
} finally {
git(["worktree", "remove", "--force", dir]);
rmSync(dir, { recursive: true, force: true });
}
}
function readJson(path) {
return JSON.parse(readFileSync(path, "utf8"));
}
function flag(args, name) {
const at = args.indexOf(name);
return at < 0 ? undefined : args[at + 1];
}
function parseLabels(raw) {
if (!raw) return [];
const labels = JSON.parse(raw);
return Array.isArray(labels) ? labels : [];
}
function report(heading, lines) {
if (lines.length === 0) return;
console.log(heading);
for (const line of lines) console.log(` ${line}`);
}
/** The outcome for a PR: `{ pass, message }`, given how many surface lines changed and any excuse. */
export function verdict({ changed, excuse, dryRun = false }) {
if (changed === 0)
return { pass: true, message: "passes, no CLI command, flag or public export changed." };
if (excuse) return { pass: true, message: `passes, ${excuse}.` };
const optOut = `opt out with the \`${OPT_OUT_LABEL}\` label or a \`docs-impact: none\` line in the PR body (say why)`;
return { pass: dryRun, message: `update docs/ for the changes above, or ${optOut}.` };
}
function cliChanges(args, files, base) {
const baseTreePath = flag(args, "--base-tree");
const headTreePath = flag(args, "--head-tree");
if (!touchesCli(files) && !baseTreePath) return [];
const before = baseTreePath ? readJson(baseTreePath) : baseTree(base);
const after = headTreePath ? readJson(headTreePath) : treeAt(ROOT);
return surfaceDiff(cliSurface(before), cliSurface(after));
}
function exportChanges(files, base) {
if (!touchesPackages(files)) return [];
return surfaceDiff(publicApiSurface(base, ROOT), publicApiSurface("HEAD", ROOT));
}
function main() {
const args = process.argv.slice(2);
const dryRun = args.includes("--dry-run");
const base = git(["merge-base", flag(args, "--base") ?? "origin/main", "HEAD"]);
const files = git(["diff", "--name-only", base, "HEAD"]).split("\n").filter(Boolean);
const pr = { labels: parseLabels(process.env.PR_LABELS), body: process.env.PR_BODY ?? "" };
const excuse = touchesDocs(files) ? "it changes docs/" : optOutReason(pr);
// Past the excuse, the surfaces only matter to a dry run, which shows them anyway.
if (excuse && !dryRun) {
console.log(`Docs impact: passes, ${excuse}.`);
return;
}
const cli = cliChanges(args, files, base);
const exports = exportChanges(files, base);
report("CLI commands and flags changed:", cli);
report("Public package exports changed:", exports);
const result = verdict({ changed: cli.length + exports.length, excuse, dryRun });
console.log(`Docs impact${dryRun ? " (dry run)" : ""}: ${result.message}`);
if (!result.pass) process.exitCode = 1;
}
if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href)
main();