@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/actionlint.ts

@@ -0,0 +1,178 @@
+/**
+ * `repo check`'s workflow lines: actionlint, pinned to one release, run over `.github/workflows` under the release
+ * pack. The binary is fetched once into the state home, checked against its pinned sha256 and cached; a download that
+ * fails or does not match is a problem line, never a cached file.
+ */
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import {
+  ACTIONLINT_FLAGS,
+  ACTIONLINT_VERSION,
+  ARCH_NAMES,
+  BINARY_MODE,
+  CACHE_DIR,
+  DEFAULT_SYSTEM_ROOT,
+  EXIT_PROBLEMS,
+  FETCH_TIMEOUT_MS,
+  HASHES,
+  MAX_OUTPUT_BYTES,
+  OS_NAMES,
+  RELEASE_URL,
+  SHOWN_HASH,
+  WINDOWS_PLATFORM,
+  WINDOWS_TAR,
+  WORKFLOW_EXTENSIONS,
+  WORKFLOWS_DIR,
+} from "./actionlint.constants.ts";
+import { findRoot, loadConfig } from "./config.ts";
+import { childEnv } from "./env.ts";
+import { toolEnv, type Captured } from "./scripts/lint.ts";
+import { stateHome } from "./scripts/setup.ts";
+
+/** What `repo check` prints of actionlint: problem lines that fail it. */
+export type ActionlintCheck = { problems: string[] };
+/** Runs `command` with `args`; the default spawns it and captures its output. */
+export type Spawn = (command: string, args: string[], options: { cwd: string; env: NodeJS.ProcessEnv }) => Captured;
+/** Everything `checkActionlintAt` reaches outside the repo through, each replaceable by a test. */
+export type ActionlintDeps = {
+  fetch?: (url: string) => Promise<Uint8Array>;
+  spawn?: Spawn;
+  cacheDir?: string;
+  platform?: string;
+  arch?: string;
+  hashes?: Record<string, string>;
+};
+/** The deps with every default filled in. */
+type Resolved = ActionlintDeps & Required<Pick<ActionlintDeps, "fetch" | "spawn" | "hashes">>;
+type Binary = { ok: true; path: string } | { ok: false; problem: string };
+type Bytes = { ok: true; bytes: Uint8Array } | { ok: false; problem: string };
+/** What an install needs: the archive's name and key, where the binary goes and the injected edges. */
+type Plan = { name: string; key: string; target: string; platform: string; deps: Resolved };
+
+const NONE: ActionlintCheck = { problems: [] };
+const itemsSchema = () =>
+  z.array(
+    z.object({ message: z.string(), filepath: z.string(), line: z.number(), column: z.number(), kind: z.string() }),
+  );
+
+/** The archive at `url`, or a thrown error for a failed request. */
+export async function fetchArchive(url: string): Promise<Uint8Array> {
+  const response = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
+  if (!response.ok) throw new Error(`${url} answered ${response.status}`);
+  return new Uint8Array(await response.arrayBuffer());
+}
+
+export const spawnCaptured: Spawn = (command, args, { cwd, env }) => {
+  const result = spawnSync(command, args, { cwd, env, encoding: "utf8", maxBuffer: MAX_OUTPUT_BYTES });
+  // A command that cannot start leaves stdout and stderr unset at runtime, whatever the types say.
+  if (result.error !== undefined) return { code: 1, stdout: "", stderr: `${result.error.message}\n` };
+  return { code: result.status ?? 1, stdout: result.stdout, stderr: result.stderr };
+};
+
+/** The workflow files under `root`, relative and sorted; none when the directory is missing. */
+function workflowsOf(root: string): string[] {
+  const dir = path.join(root, WORKFLOWS_DIR);
+  if (!fs.existsSync(dir)) return [];
+  const names = fs.readdirSync(dir).filter((name) => WORKFLOW_EXTENSIONS.includes(path.extname(name)));
+  return names.toSorted().map((name) => `${WORKFLOWS_DIR}/${name}`);
+}
+
+/** The archive's bytes when they hash to the pinned value; otherwise the problem line. */
+async function download(plan: Plan): Promise<Bytes> {
+  const { name, key, deps } = plan;
+  let bytes: Uint8Array;
+  try {
+    bytes = await deps.fetch(`${RELEASE_URL}/${name}`);
+  } catch (error) {
+    const why = error instanceof Error ? error.message : String(error);
+    return { ok: false, problem: `could not fetch ${ACTIONLINT_VERSION} (${why}); connect once so repo can cache it` };
+  }
+  const actual = createHash("sha256").update(bytes).digest("hex");
+  const expected = deps.hashes[key] ?? "";
+  if (actual === expected) return { ok: true, bytes };
+  const [a, e] = [actual, expected].map((hash) => `${hash.slice(0, SHOWN_HASH)}…`);
+  return { ok: false, problem: `${name} has sha256 ${a}, expected ${e}; nothing was cached` };
+}
+
+/** Unpacks `archive` into `into` with tar; on windows the system tar by full path, which reads a zip. */
+function unpack(plan: Plan, archive: string, into: string): Captured {
+  const system = childEnv().SystemRoot ?? DEFAULT_SYSTEM_ROOT;
+  const tar = plan.platform === WINDOWS_PLATFORM ? `${system}${WINDOWS_TAR}` : "tar";
+  const spawn = plan.deps.spawn;
+  return spawn(tar, ["-xf", archive, "-C", into], { cwd: into, env: toolEnv(childEnv()) });
+}
+
+/** Fetches, verifies, unpacks and renames the binary into place; a problem line when any step fails. */
+async function install(plan: Plan): Promise<Binary> {
+  const dir = path.dirname(plan.target);
+  const archive = path.join(dir, `download-${process.pid}-${plan.name}`);
+  const extracted = path.join(dir, `unpack-${process.pid}`);
+  try {
+    const got = await download(plan);
+    if (!got.ok) return got;
+    fs.writeFileSync(archive, got.bytes);
+    fs.mkdirSync(extracted, { recursive: true });
+    const tarred = unpack(plan, archive, extracted);
+    if (tarred.code !== 0) return { ok: false, problem: `could not unpack ${plan.name}: ${tarred.stderr.trim()}` };
+    const unpacked = path.join(extracted, path.basename(plan.target));
+    fs.chmodSync(unpacked, BINARY_MODE);
+    fs.renameSync(unpacked, plan.target);
+    return { ok: true, path: plan.target };
+  } finally {
+    fs.rmSync(archive, { force: true });
+    fs.rmSync(extracted, { recursive: true, force: true });
+  }
+}
+
+/** The cached binary, installing it first when it is missing. */
+async function binaryFor(deps: Resolved): Promise<Binary> {
+  const platform = deps.platform ?? process.platform;
+  const arch = deps.arch ?? process.arch;
+  const [osName, archName] = [OS_NAMES[platform], ARCH_NAMES[arch]];
+  if (osName === undefined || archName === undefined) {
+    const build = `${ACTIONLINT_VERSION} build for ${platform} ${arch}`;
+    return { ok: false, problem: `no ${build}; run repo check on linux, macOS or Windows` };
+  }
+  const cacheDir = deps.cacheDir ?? path.join(stateHome(), CACHE_DIR, ACTIONLINT_VERSION);
+  const target = path.join(cacheDir, platform === WINDOWS_PLATFORM ? "actionlint.exe" : "actionlint");
+  if (fs.existsSync(target)) return { ok: true, path: target };
+  fs.mkdirSync(cacheDir, { recursive: true });
+  const key = `${osName}_${archName}`;
+  const name = `actionlint_${ACTIONLINT_VERSION}_${key}${platform === WINDOWS_PLATFORM ? ".zip" : ".tar.gz"}`;
+  return await install({ name, key, target, platform, deps });
+}
+
+/** One line per item of actionlint's json, or the failure line when the run or its output is not as expected. */
+function linesOf(ran: Captured): string[] {
+  if (ran.code === 0) return [];
+  const failure = `actionlint: exited ${ran.code}: ${ran.stderr.trim()}`;
+  if (ran.code !== EXIT_PROBLEMS) return [failure];
+  try {
+    const items = itemsSchema().parse(JSON.parse(ran.stdout));
+    return items.map((i) => `actionlint: ${i.filepath}:${i.line}:${i.column}: ${i.message} [${i.kind}]`);
+  } catch {
+    return [failure];
+  }
+}
+
+/**
+ * `repo check`'s actionlint lines for the repo at `cwd`: none without a config, without the release pack or without a
+ * workflow file, and then no download either.
+ */
+export async function checkActionlintAt(cwd: string, deps: ActionlintDeps = {}): Promise<ActionlintCheck> {
+  const root = findRoot(cwd);
+  if (root === null) return NONE;
+  const loaded = await loadConfig(root);
+  if (!loaded.ok || !loaded.config.packs.includes("release")) return NONE;
+  const files = workflowsOf(root);
+  if (files.length === 0) return NONE;
+  const io = { fetch: fetchArchive, spawn: spawnCaptured, hashes: HASHES, ...deps };
+  const binary = await binaryFor(io);
+  if (!binary.ok) return { problems: [`actionlint: ${binary.problem}`] };
+  const args = [...ACTIONLINT_FLAGS, ...files];
+  const ran = io.spawn(binary.path, args, { cwd: root, env: toolEnv(childEnv()) });
+  return { problems: linesOf(ran) };
+}

package/cli/bin.test.ts

@@ -0,0 +1,54 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { BIN, type Bin, main } from "./bin.ts";
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+/** A bin whose registry answers `code`, whose `cli/main.ts` runs `start`, and whose exit is recorded. */
+function bin(code: number | null, start: () => Promise<void> = async () => {}) {
+  return {
+    dispatch: vi.fn<Bin["dispatch"]>(() => Promise.resolve(code)),
+    load: vi.fn(() => Promise.resolve({ start })),
+    exit: vi.fn<Bin["exit"]>(),
+  };
+}
+
+describe("main", () => {
+  it("exits with the code of a registry command or hook, never loading cli/main.ts", async () => {
+    const deps = bin(3);
+    await main(["hook", "turn"], deps);
+    expect(deps.dispatch).toHaveBeenCalledWith(["hook", "turn"]);
+    expect([deps.load.mock.calls.length, deps.exit.mock.calls]).toEqual([0, [[3]]]);
+  });
+
+  it("runs cli/main.ts when the registry names nothing, then exits with the code it set", async () => {
+    const start = vi.fn(async () => {});
+    const deps = bin(null, start);
+    await main(["init"], deps);
+    expect([start.mock.calls.length, deps.exit.mock.calls]).toEqual([1, [[undefined]]]);
+  });
+
+  it.each([
+    [new Error("no manifest"), "repo: no manifest\n"],
+    ["a string", "repo: a string\n"],
+  ])("prints a thrown %j as repo: <message> and exits 1", async (thrown, printed) => {
+    const stderr = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    const deps = bin(null, () => Promise.reject(thrown));
+    await main(["init"], deps);
+    expect([stderr.mock.calls, deps.exit.mock.calls]).toEqual([[[printed]], [[1]]]);
+  });
+});
+
+describe("BIN", () => {
+  it("is what main runs by default: the registry's code goes to the process's exit", async () => {
+    const stderr = vi.spyOn(process.stderr, "write").mockImplementation(() => true);
+    const exit = vi.spyOn(process, "exit").mockImplementation(() => undefined /* a spy, so the run goes on */ as never);
+    await main(["hook"]);
+    expect([stderr.mock.calls.length, exit.mock.calls]).toEqual([1, [[1]]]);
+  });
+
+  it("loads cli/main.ts lazily, its start among its exports", async () => {
+    expect(typeof (await BIN.load()).start).toBe("function");
+  });
+});

package/cli/bin.ts

@@ -0,0 +1,40 @@
+import { dispatch } from "./commands.ts";
+
+/** What the bin runs on and how it ends; tests pass stubs. */
+export type Bin = {
+  /** Runs a registry command or hook and returns its exit code, or null when `cli/main.ts` owns argv. */
+  dispatch: (argv: readonly string[]) => Promise<number | null>;
+  /** Loads `cli/main.ts`, only once the registry has named nothing. */
+  load: () => Promise<{ start: () => Promise<void> }>;
+  exit: (code?: number) => void;
+};
+
+/** The registry, a lazy `cli/main.ts`, and the process's own exit. */
+export const BIN: Readonly<Bin> = {
+  dispatch,
+  load: () => import("./main.ts"),
+  exit: (code) => process.exit(code),
+};
+
+/** The exit code of a registry command or hook, or undefined once `cli/main.ts` has run and set its own. */
+async function run(argv: readonly string[], deps: Readonly<Bin>): Promise<number | undefined> {
+  const code = await deps.dispatch(argv);
+  if (code !== null) return code;
+  await (await deps.load()).start();
+  return undefined;
+}
+
+/**
+ * `repo`: registry commands and hooks first, so they never load the init, sync and prompt code in `cli/main.ts`.
+ * Exits once the command settles, as each script did when run directly, so a hook never waits on a stray handle; a
+ * thrown error prints `repo: <message>` and exits 1.
+ */
+export async function main(argv: readonly string[], deps: Readonly<Bin> = BIN): Promise<void> {
+  await run(argv, deps).then(
+    (code) => deps.exit(code),
+    (err: unknown) => {
+      process.stderr.write(`repo: ${err instanceof Error ? err.message : String(err)}\n`);
+      deps.exit(1);
+    },
+  );
+}

package/cli/check-changelog.test.ts

@@ -0,0 +1,40 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { checkChangelog } from "./check-changelog.ts";
+import { removePlanted, tempDir, write } from "./fixtures/planted-repo.ts";
+
+afterEach(removePlanted);
+
+const BAD = "# Changelog\n\n## [Unreleased]\n\n### Improved\n\n- x\n\n## [0.2.0]\n";
+const GOOD = "# Changelog\n\n## [Unreleased]\n\n### Added\n\n- x\n\n## [0.2.0] - 2026-11-01\n";
+
+function root(files: Record<string, unknown>): string {
+  const dir = tempDir();
+  write(dir, files);
+  return dir;
+}
+
+describe("checkChangelog", () => {
+  it("holds a public root's CHANGELOG.md to Keep a Changelog, one line per problem", () => {
+    const lines = checkChangelog(root({ "package.json": { name: "app" }, "CHANGELOG.md": BAD }));
+    expect(lines).toEqual([
+      'CHANGELOG.md:5: "### Improved" is not a section; use Added, Changed, Deprecated, Removed, Fixed or Security',
+      'CHANGELOG.md:9: "## [0.2.0]" needs a date; write ## [0.2.0] - YYYY-MM-DD',
+    ]);
+  });
+
+  it("passes a public root with a good changelog", () => {
+    expect(checkChangelog(root({ "package.json": { name: "app" }, "CHANGELOG.md": GOOD }))).toEqual([]);
+  });
+
+  it("names a missing CHANGELOG.md in a public root", () => {
+    expect(checkChangelog(root({ "package.json": { name: "app" } }))).toEqual([
+      "CHANGELOG.md is missing; add one in the Keep a Changelog format",
+    ]);
+  });
+
+  it("checks nothing in a private root, or one without a readable manifest", () => {
+    expect(checkChangelog(root({ "package.json": { name: "app", private: true }, "CHANGELOG.md": BAD }))).toEqual([]);
+    expect(checkChangelog(root({ "CHANGELOG.md": BAD }))).toEqual([]);
+    expect(checkChangelog(root({ "package.json": "[", "CHANGELOG.md": BAD }))).toEqual([]);
+  });
+});

package/cli/check-changelog.ts

@@ -0,0 +1,12 @@
+import fs from "node:fs";
+import path from "node:path";
+import { changelogFormatProblems } from "./release/changelog.ts";
+import { CHANGELOG_FILE } from "./release/release.constants.ts";
+import { ownerLookup } from "./tdd-scope.ts";
+
+/** The `repo check` lines for the root's CHANGELOG.md; none for a private root or one without a readable manifest. */
+export function checkChangelog(root: string): string[] {
+  if (!ownerLookup(root)("package.json").public) return [];
+  const file = path.join(root, CHANGELOG_FILE);
+  return changelogFormatProblems(fs.existsSync(file) ? fs.readFileSync(file, "utf8") : null);
+}

package/cli/check-comments.test.ts

@@ -0,0 +1,157 @@
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, expect, it, vi } from "vitest";
+import { checkComments, commentProblems, sourceFiles } from "./check-comments.ts";
+import { captureBun } from "./scripts/lint.ts";
+
+const temps: string[] = [];
+afterEach(() => {
+  for (const dir of temps.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+const LINT = (word: string) =>
+  `"${word}" switches a lint rule off; fix the code, or add a lint.skip entry with a reason`;
+const IGNORE = '"@ts-ignore" hides a type error; fix the type, or write @ts-expect-error with a reason';
+const NOCHECK = '"@ts-nocheck" turns type checking off for the file; fix the types instead';
+const EXPECT = '"@ts-expect-error" needs a reason: // @ts-expect-error <why this line must not compile>';
+
+/** A temp dir holding `files`. */
+function plant(files: Record<string, string>): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "workerstack-comments-"));
+  temps.push(root);
+  for (const [rel, text] of Object.entries(files)) {
+    fs.mkdirSync(path.dirname(path.join(root, rel)), { recursive: true });
+    fs.writeFileSync(path.join(root, rel), text);
+  }
+  return root;
+}
+
+const git = (root: string, ...args: string[]) => execFileSync("git", args, { cwd: root, encoding: "utf8" });
+
+/** The problems of one planted file. */
+const problemsOf = (text: string, rel = "a.ts") => commentProblems(plant({ [rel]: text }), [rel]);
+
+it("names each refused comment with its file and line, in the order of the files given", () => {
+  const root = plant({
+    "src/a.ts":
+      "export const a = 1;\n\n// oxlint-disable-next-line repo/no-module-state\nlet b = 2;\n\nb++;\n// @ts-ignore\n",
+    "src/b.ts": "// @ts-nocheck\n".concat("\n".repeat(7), "// @ts-expect-error\nexport const c: number = 'c';\n"),
+  });
+  expect(commentProblems(root, ["src/a.ts", "src/b.ts"])).toEqual([
+    `src/a.ts:3: ${LINT("oxlint-disable-next-line")}`,
+    `src/a.ts:7: ${IGNORE}`,
+    `src/b.ts:1: ${NOCHECK}`,
+    `src/b.ts:9: ${EXPECT}`,
+  ]);
+});
+
+it.each([
+  ["// eslint-disable\n", 1, "eslint-disable"],
+  ["// oxlint-disable no-debugger -- legacy\n", 1, "oxlint-disable"],
+  ["debugger; // eslint-disable-line\n", 1, "eslint-disable-line"],
+  ["//eslint-disable-next-line\n", 1, "eslint-disable-next-line"],
+  ["/* eslint-disable no-debugger */\n", 1, "eslint-disable"],
+  ["/*eslint-disable*/\n", 1, "eslint-disable"],
+  ["/*\n   oxlint-disable */\n", 2, "oxlint-disable"],
+  ["const s = 1;\n\n/* eslint-disable-next-line */\n", 3, "eslint-disable-next-line"],
+])("refuses the lint directive in %j", (text, line, word) => {
+  expect(problemsOf(text)).toEqual([`a.ts:${line}: ${LINT(word)}`]);
+});
+
+it.each([
+  ["/// @ts-ignore\n", 1, IGNORE],
+  ["/* @ts-ignore */ const a = 1;\n", 1, IGNORE],
+  ["// @ts-ignored, as TypeScript reads any word that starts so\n", 1, IGNORE],
+  ["/**\n * Some prose first.\n * @ts-ignore */\n", 3, IGNORE],
+  ["#!/usr/bin/env bun\n// @TS-NOCHECK\n", 2, NOCHECK],
+  ["// leading\n/* also leading */ //@ts-nocheck: why\n", 2, NOCHECK],
+  ["// @ts-expect-error parsed above\n", 1, EXPECT],
+  ["/* @ts-expect-error */\n", 1, EXPECT],
+  ["/**\n * @ts-expect-error */\n", 2, EXPECT],
+])("refuses the TypeScript directive in %j", (text, line, message) => {
+  expect(problemsOf(text)).toEqual([`a.ts:${line}: ${message}`]);
+});
+
+it.each([
+  '// @ts-expect-error "lint" is not a pack\n',
+  "/* @ts-expect-error the schema allows no pack named lint */\n",
+  'export const s = "// oxlint-disable";\n',
+  "/** never write eslint-disable here */\n",
+  "/** eslint-disable */\n",
+  "// eslint-disabled\n",
+  "// eslint-disable-next-line-- no space, so oxlint reads no directive\n",
+  "// ESLINT-DISABLE\n",
+  "// see @ts-ignore in the handbook\n",
+  "/** @ts-ignore\n * on a line before the last, which TypeScript does not read\n */\n",
+  'import "./b.ts";\n// @ts-nocheck\n',
+  "/* @ts-nocheck */\n",
+  "// @ts-nocheckers\n",
+])("passes %j", (text) => {
+  expect(problemsOf(text)).toEqual([]);
+});
+
+it("reads the multi-line block form as real tsc does: honored only on the block's last line", () => {
+  const root = plant({
+    "last.ts": "/**\n * Some prose first.\n * @ts-ignore */\nexport const a: number = 'a';\n",
+    "first.ts": "/** @ts-ignore\n * more prose\n */\nexport const b: number = 'b';\n",
+  });
+  const tsc = path.join(path.dirname(Bun.resolveSync("typescript/package.json", import.meta.dirname)), "bin/tsc");
+  const run = (rel: string) => captureBun([tsc, "--noEmit", "--strict", rel], root).code;
+  expect({ last: run("last.ts"), first: run("first.ts") }).toEqual({ last: 0, first: 2 });
+  expect(commentProblems(root, ["last.ts", "first.ts"])).toEqual([`last.ts:3: ${IGNORE}`]);
+}, 30_000);
+
+it("scans the comments a file with a parse error still returns", () => {
+  expect(problemsOf("// @ts-ignore\nconst = ;\n")).toEqual([`a.ts:1: ${IGNORE}`]);
+});
+
+it("skips a listed file that cannot be read, and files that are not source", () => {
+  const root = plant({ "a.md": "// @ts-ignore\n", "fixtures/a.ts": "// @ts-ignore\n" });
+  expect(commentProblems(root, ["gone.ts", "a.md", "fixtures/a.ts"])).toEqual([]);
+});
+
+/** A git repo with a committed file, an untracked one, and files `sourceFiles` leaves out. */
+function repo(): string {
+  const root = plant({
+    ".gitignore": "dist\n",
+    "src/a.ts": "",
+    "dist/out.js": "",
+    "cli/fixtures/f.ts": "",
+    "README.md": "",
+    "styles.css": "",
+  });
+  git(root, "init", "-q");
+  git(root, "add", "-A");
+  git(root, "-c", "user.email=a@b", "-c", "user.name=a", "commit", "-q", "-m", "init");
+  for (const ext of ["tsx", "mts", "cts", "js", "jsx", "mjs", "cjs"]) fs.writeFileSync(path.join(root, `b.${ext}`), "");
+  return root;
+}
+
+const LISTED = ["b.cjs", "b.cts", "b.js", "b.jsx", "b.mjs", "b.mts", "b.tsx", "src/a.ts"];
+
+it("lists tracked and untracked source files, leaving out ignored, fixtures and other extensions", () => {
+  expect(sourceFiles(repo())).toEqual({ ok: true, files: LISTED });
+});
+
+it("lists the same files under a hook's GIT_INDEX_FILE naming another index", () => {
+  const root = repo();
+  vi.stubEnv("GIT_INDEX_FILE", path.join(plant({}), "index"));
+  expect(sourceFiles(root)).toEqual({ ok: true, files: LISTED });
+});
+
+it("says why when git cannot list the files", () => {
+  const listed = sourceFiles(plant({}));
+  expect(listed.ok).toBe(false);
+  expect(listed.ok ? [] : listed.errors).toEqual([
+    expect.stringMatching(/^git ls-files failed: .*not a git repository/),
+  ]);
+});
+
+it("checkComments scans the listed files, or reports why it could not list them", () => {
+  const root = repo();
+  fs.writeFileSync(path.join(root, "src/a.ts"), "// @ts-ignore\n");
+  expect(checkComments(root)).toEqual([`src/a.ts:1: ${IGNORE}`]);
+  expect(checkComments(plant({}))).toEqual([expect.stringMatching(/^git ls-files failed: /)]);
+});

package/cli/check-comments.ts

@@ -0,0 +1,123 @@
+/**
+ * The comments no rule may hide behind: a lint disable, `@ts-ignore`, `@ts-nocheck`, and an `@ts-expect-error` with no
+ * written reason. A script and not an oxlint rule, since oxlint honors its own disable comments. Each directive is
+ * matched as the tool that obeys it reads it, so a string or prose that mentions one passes.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { parseSync, type Comment } from "oxc-parser";
+import { isReason } from "./lint/is-reason.ts";
+import { runGit } from "./sync/standards.ts";
+
+/** ts tsx mts cts js jsx mjs cjs. */
+const SOURCE = /\.(?:[jt]sx?|[cm][jt]s)$/;
+const LINE_BREAK = /\r\n?|[\n\u2028\u2029]/g;
+const HASHBANG = /^#!.*/;
+/** oxlint's (and eslint's) directive: the word first in the trimmed text, then a space or the end. */
+const DISABLE = /^((?:eslint|oxlint)-disable(?:-next-line|-line)?)(?:\s|$)/;
+/** TypeScript's `commentDirectiveRegExSingleLine`, on the whole `//` comment. */
+const TS_LINE = /^\/\/\/?\s*@(ts-expect-error|ts-ignore)/;
+/** TypeScript's `commentDirectiveRegExMultiLine`, on the trimmed last line of a block comment. */
+const TS_BLOCK = /^(?:\/|\*)*\s*@(ts-expect-error|ts-ignore)/;
+/** TypeScript's `singleLinePragmaRegEx`, read on the `//` comments before the file's first token. */
+const PRAGMA = /^\/\/\/?\s*@([^\s:]+)(?:(?:[^\S\r\n]|:).*)?$/;
+
+const IGNORE = '"@ts-ignore" hides a type error; fix the type, or write @ts-expect-error with a reason';
+const NOCHECK = '"@ts-nocheck" turns type checking off for the file; fix the types instead';
+const EXPECT = '"@ts-expect-error" needs a reason: // @ts-expect-error <why this line must not compile>';
+
+/** A refused comment: where in the file its directive starts, and what to do instead. */
+type Hit = { at: number; message: string };
+/** The source files of a checkout, or why git could not list them. */
+export type Listed = { ok: true; files: string[] } | { ok: false; errors: string[] };
+
+const isSource = (rel: string) => SOURCE.test(rel) && !rel.split("/").includes("fixtures");
+const lineOf = (source: string, at: number) => (source.slice(0, at).match(LINE_BREAK) ?? []).length + 1;
+
+function disableHit(comment: Comment): Hit | null {
+  const trimmed = comment.value.trimStart();
+  const word = DISABLE.exec(trimmed)?.[1];
+  if (word === undefined) return null;
+  const at = comment.end - (comment.type === "Block" ? 2 : 0) - trimmed.length;
+  return { at, message: `"${word}" switches a lint rule off; fix the code, or add a lint.skip entry with a reason` };
+}
+
+/** The text TypeScript reads a directive from, and where it starts: a block comment's last line, from `/*` or after. */
+function directiveLine(comment: Comment): { text: string; at: number } {
+  if (comment.type === "Line") return { text: `//${comment.value}`, at: comment.start };
+  const raw = `/*${comment.value}*/`;
+  const breaks = [...raw.matchAll(LINE_BREAK)];
+  const last = breaks.at(-1);
+  const offset = last === undefined ? 0 : last.index + last[0].length;
+  return { text: raw.slice(offset), at: comment.start + offset };
+}
+
+function tsHit(comment: Comment): Hit | null {
+  const { text, at } = directiveLine(comment);
+  const trimmed = text.trimStart();
+  const match = (comment.type === "Line" ? TS_LINE : TS_BLOCK).exec(trimmed);
+  if (match === null) return null;
+  const start = at + text.length - trimmed.length;
+  if (match[1] === "ts-ignore") return { at: start, message: IGNORE };
+  const rest = trimmed.slice(match[0].length).replace(/\*\/$/, "");
+  return isReason(rest) ? null : { at: start, message: EXPECT };
+}
+
+/** The comments before the first token, past a `#!` line, where TypeScript reads its file pragmas. */
+function leading(source: string, comments: readonly Comment[]): Comment[] {
+  let edge = HASHBANG.exec(source)?.[0].length ?? 0;
+  const found: Comment[] = [];
+  for (const comment of comments) {
+    if (source.slice(edge, comment.start).trim() !== "") break;
+    found.push(comment);
+    edge = comment.end;
+  }
+  return found;
+}
+
+function nocheckHit(comment: Comment): Hit | null {
+  if (comment.type !== "Line") return null;
+  const name = PRAGMA.exec(`//${comment.value}`)?.[1];
+  return name?.toLowerCase() === "ts-nocheck" ? { at: comment.start, message: NOCHECK } : null;
+}
+
+/** Every refused comment of one file, in the order they appear. */
+function hitsOf(rel: string, source: string): Hit[] {
+  const { comments } = parseSync(rel, source);
+  const nochecks = leading(source, comments).map(nocheckHit);
+  const hits = [...comments.flatMap((comment) => [disableHit(comment), tsHit(comment)]), ...nochecks];
+  return hits.filter((hit) => hit !== null).sort((a, b) => a.at - b.at);
+}
+
+function readSource(file: string): string | null {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * One `<file>:<line>: <message>` per refused comment in the source files of `files` (paths relative to `root`); a file
+ * that cannot be read is skipped, and one that does not parse is scanned on the comments the parser still returns.
+ */
+export function commentProblems(root: string, files: readonly string[]): string[] {
+  return files.filter(isSource).flatMap((rel) => {
+    const source = readSource(path.join(root, rel));
+    if (source === null) return [];
+    return hitsOf(rel, source).map((hit) => `${rel}:${lineOf(source, hit.at)}: ${hit.message}`);
+  });
+}
+
+/** The tracked and untracked, not ignored, source files under `root`, outside any `fixtures` dir, sorted. */
+export function sourceFiles(root: string): Listed {
+  const run = runGit(root, ["ls-files", "-z", "--cached", "--others", "--exclude-standard"]);
+  if (run.status !== 0) return { ok: false, errors: [`git ls-files failed: ${run.stderr.trim()}`] };
+  return { ok: true, files: [...new Set(run.stdout.split("\0").filter(isSource))].sort() };
+}
+
+/** `commentProblems` over every source file of the checkout at `root`, as `repo check` runs it. */
+export function checkComments(root: string): string[] {
+  const listed = sourceFiles(root);
+  return listed.ok ? commentProblems(root, listed.files) : listed.errors;
+}