@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/scripts/lint-baseline.ts

@@ -0,0 +1,233 @@
+/**
+ * `.repo/lint-baseline.json`: per file, per rule, how many lint problems the repo still carries. Only ever lowered
+ * to the real counts (by `repo turn` for the files it lints, by `repo lint --baseline` for all); `--baseline` also
+ * seeds a rule a file has no entry for. `repo check` fails on a count above its entry, an entry above its count and
+ * an entry for a gone file. Worktrees each hold a copy; a merge conflict resolves either way, then `--baseline`
+ * lowers it to the truth.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { z } from "zod";
+import { findRoot, loadConfig } from "../config.ts";
+import { OXLINT_CONFIG_PATH } from "../sync/oxlint-config.ts";
+import { captureTool } from "./lint.ts";
+import { REPORT_START } from "./lint.constants.ts";
+
+export const BASELINE_PATH = ".repo/lint-baseline.json";
+/** File → rule → problem count; a file or rule left out counts 0. */
+export type Counts = Record<string, Record<string, number>>;
+/** One rule of one file over its baseline entry. */
+export type Excess = { file: string; rule: string; has: number; allows: number };
+/** One entry `repo turn` lowered; `to` 0 drops it. */
+export type Lowered = { file: string; rule: string; from: number; to: number };
+export type Diagnostic = { file: string; rule: string; line: string };
+export type Result<T> = { ok: true; value: T } | { ok: false; errors: string[] };
+
+const LOWER = "run `bun repo lint --baseline`";
+const PARSE_ERROR = "parse-error";
+const count = z.number().int().positive({ error: "must be a whole number above 0" });
+const baselineSchema = z.record(z.string(), z.record(z.string(), count, { error: "must be an object" }), {
+  error: "must be an object",
+});
+const reportSchema = z.object({
+  diagnostics: z.array(
+    z.object({
+      message: z.string(),
+      code: z.string().optional(),
+      severity: z.string(),
+      filename: z.string(),
+      labels: z.array(z.object({ span: z.object({ line: z.number(), column: z.number() }) })).optional(),
+    }),
+  ),
+});
+
+const byKey = (a: string, b: string) => Number(a > b) - Number(a < b);
+const plural = (n: number, noun: string) => `${n} ${noun}${n === 1 ? "" : "s"}`;
+const countOf = (counts: Counts, file: string, rule: string) => counts[file]?.[rule] ?? 0;
+
+export const excessText = ({ file, rule, has, allows }: Excess): string =>
+  `${file} has ${has} ${rule}, the baseline allows ${allows}`;
+
+/** Every rule of `files` whose count in `actual` is above `baseline`, in file then rule order. */
+function overOf(baseline: Counts, actual: Counts, files: readonly string[]): Excess[] {
+  return [...files].sort(byKey).flatMap((file) =>
+    Object.keys(actual[file] ?? {}).flatMap((rule) => {
+      const has = countOf(actual, file, rule);
+      const allows = countOf(baseline, file, rule);
+      return has > allows ? [{ file, rule, has, allows }] : [];
+    }),
+  );
+}
+
+/** `counts` with empty files and zero rules dropped and keys sorted, as the file holds them. */
+function normalized(counts: Counts): Counts {
+  const entries = Object.entries(counts).map(([file, rules]) => {
+    const kept = Object.entries(rules).filter(([, value]) => value > 0);
+    return [file, Object.fromEntries(kept.sort(([a], [b]) => byKey(a, b)))] as const;
+  });
+  const sorted = entries.sort(([a], [b]) => byKey(a, b));
+  return Object.fromEntries(sorted.filter(([, rules]) => Object.keys(rules).length > 0));
+}
+
+/**
+ * The baseline gate over `files` (linted or deleted): what is over, the baseline with each of their entries lowered
+ * to the real count, and what was lowered. Other files' entries stay as they are.
+ */
+export function gate(
+  baseline: Counts,
+  actual: Counts,
+  files: readonly string[],
+): {
+  over: Excess[];
+  next: Counts;
+  lowered: Lowered[];
+} {
+  const next: Counts = { ...baseline };
+  const lowered: Lowered[] = [];
+  for (const file of [...files].sort(byKey)) {
+    const entry = baseline[file];
+    if (entry === undefined) continue;
+    const rules = Object.keys(entry).sort(byKey);
+    next[file] = Object.fromEntries(
+      Object.entries(entry).map(([rule, allows]) => [rule, Math.min(allows, countOf(actual, file, rule))]),
+    );
+    for (const rule of rules) {
+      const [from, to] = [countOf(baseline, file, rule), countOf(next, file, rule)];
+      if (to < from) lowered.push({ file, rule, from, to });
+    }
+  }
+  return { over: overOf(baseline, actual, files), next: normalized(next), lowered };
+}
+
+/** `repo lint --baseline`: every entry lowered to its real count, a gone file dropped, a rule a file lacks seeded. */
+function reseeded(baseline: Counts, actual: Counts): Counts {
+  const next: Counts = gate(baseline, actual, Object.keys(baseline)).next;
+  for (const [file, rules] of Object.entries(actual)) {
+    for (const [rule, value] of Object.entries(rules)) {
+      if (baseline[file]?.[rule] === undefined) next[file] = { ...next[file], [rule]: value };
+    }
+  }
+  return normalized(next);
+}
+
+/** What `repo check` reports: a count over its entry, an entry over its count, an entry for a file that is gone. */
+function drift(baseline: Counts, actual: Counts, exists: (file: string) => boolean): string[] {
+  const files = [...new Set([...Object.keys(baseline), ...Object.keys(actual)])].sort(byKey);
+  return files.flatMap((file) => {
+    if (!exists(file)) return [`${file} is gone; ${LOWER}`];
+    const over = overOf(baseline, actual, [file]).map(excessText);
+    const high = Object.keys(baseline[file] ?? {})
+      .filter((rule) => countOf(actual, file, rule) < countOf(baseline, file, rule))
+      .map((rule) => {
+        const allows = countOf(baseline, file, rule);
+        return `${excessText({ file, rule, has: countOf(actual, file, rule), allows })}; ${LOWER} to lower it`;
+      });
+    return [...over, ...high];
+  });
+}
+
+/** The baseline under `root`, empty when the file is absent. */
+export function readBaseline(root: string): Result<Counts> {
+  const file = path.join(root, BASELINE_PATH);
+  if (!fs.existsSync(file)) return { ok: true, value: {} };
+  const fail = (lines: string[]): Result<Counts> => ({ ok: false, errors: lines.map((l) => `${BASELINE_PATH}: ${l}`) });
+  let raw: unknown;
+  try {
+    raw = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch (error) {
+    return fail([`not valid JSON: ${(error as Error).message}; fix it, or delete it and ${LOWER}`]);
+  }
+  const parsed = baselineSchema.safeParse(raw);
+  if (parsed.success) return { ok: true, value: parsed.data };
+  return fail(
+    parsed.error.issues.map(
+      (issue) => `${[...issue.path, ""].join(": ")}${issue.message}; fix it, or delete it and ${LOWER}`,
+    ),
+  );
+}
+
+/** Writes `counts` sorted, as `JSON.stringify` indents it, which oxfmt leaves alone; through a rename, so no reader sees half. */
+export function writeBaseline(root: string, counts: Counts): void {
+  const file = path.join(root, BASELINE_PATH);
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}.tmp`;
+  fs.writeFileSync(temp, `${JSON.stringify(normalized(counts), null, 2)}\n`);
+  fs.renameSync(temp, file);
+}
+
+/**
+ * oxlint's json report on `args` in `root` (no paths: the whole tree), one diagnostic per problem; `run` runs oxlint,
+ * `captureTool` unless a caller injects another.
+ */
+export function lintReport(
+  root: string,
+  args: readonly string[],
+  run: typeof captureTool = captureTool,
+): Result<Diagnostic[]> {
+  const ran = run("oxlint", ["-f", "json", ...args], root);
+  let raw: unknown;
+  try {
+    raw = JSON.parse(ran.stdout.slice(Math.max(ran.stdout.search(REPORT_START), 0)));
+  } catch {
+    return { ok: false, errors: [`oxlint exited ${ran.code}: ${`${ran.stdout}${ran.stderr}`.trim()}`] };
+  }
+  const report = reportSchema.parse(raw);
+  const diagnostics = report.diagnostics.map((d) => {
+    const rule = d.code ?? PARSE_ERROR;
+    const span = d.labels?.[0]?.span;
+    // A diagnostic without a label is placed at its file alone.
+    const at = [d.filename, span?.line, span?.column].filter((part) => part !== undefined).join(":");
+    return { file: d.filename, rule, line: `${at}: ${d.severity} ${rule}: ${d.message}` };
+  });
+  return { ok: true, value: diagnostics };
+}
+
+export function countsOf(diagnostics: readonly Diagnostic[]): Counts {
+  const counts: Counts = {};
+  for (const { file, rule } of diagnostics) counts[file] = { ...counts[file], [rule]: countOf(counts, file, rule) + 1 };
+  return counts;
+}
+
+/** The whole tree's counts, oxlint's and the `scripts` hits no skip turns off, and the baseline under `root`. */
+function measure(root: string, scripts: readonly Diagnostic[]): Result<{ baseline: Counts; actual: Counts }> {
+  const baseline = readBaseline(root);
+  if (!baseline.ok) return baseline;
+  const report = lintReport(root, []);
+  if (!report.ok) return report;
+  return { ok: true, value: { baseline: baseline.value, actual: countsOf([...report.value, ...scripts]) } };
+}
+
+/**
+ * `repo lint --baseline` in `root`: every entry lowered to the real count, oxlint's and the `scripts` hits no skip turns
+ * off, a gone file dropped and a rule a file lacks seeded; the exit code.
+ */
+export function seedBaseline(root: string, scripts: readonly Diagnostic[]): number {
+  const measured = measure(root, scripts);
+  if (!measured.ok) {
+    for (const line of measured.errors) process.stderr.write(`repo lint: ${line}\n`);
+    return 1;
+  }
+  const next = reseeded(measured.value.baseline, measured.value.actual);
+  writeBaseline(root, next);
+  const problems = Object.values(next).reduce((sum, rules) => sum + Object.values(rules).reduce((a, b) => a + b, 0), 0);
+  const counted = `${plural(Object.keys(next).length, "file")}, ${plural(problems, "problem")}`;
+  process.stdout.write(`repo lint: baseline written: ${counted}\n`);
+  return 0;
+}
+
+/**
+ * `repo check`'s lint lines over oxlint's and the `scripts` hits no skip turns off, each prefixed with the baseline
+ * path: none when the repo has no config, the standards pack is off or sync has not written the oxlint config (sync
+ * --check reports that).
+ */
+export async function checkLintBaseline(cwd: string, scripts: readonly Diagnostic[]): Promise<string[]> {
+  const root = findRoot(cwd);
+  if (root === null) return [];
+  const loaded = await loadConfig(root);
+  if (!loaded.ok || !loaded.config.packs.includes("standards")) return [];
+  if (!fs.existsSync(path.join(root, OXLINT_CONFIG_PATH))) return [];
+  const measured = measure(root, scripts);
+  if (!measured.ok) return measured.errors;
+  const exists = (file: string) => fs.existsSync(path.join(root, file));
+  return drift(measured.value.baseline, measured.value.actual, exists).map((line) => `${BASELINE_PATH}: ${line}`);
+}

package/cli/scripts/lint-main.ts

@@ -0,0 +1,24 @@
+/**
+ * `repo lint`: oxlint with the arguments given, or with `--baseline` alone, the baseline lowered and seeded from
+ * oxlint's and the script checks' hits. The baseline and the script checks load only for `--baseline`, so a lint of
+ * paths never loads typescript.
+ */
+import { lint, runTool } from "./lint.ts";
+
+export async function lintMain(argv: string[]): Promise<number> {
+  if (!argv.includes("--baseline")) return lint(argv);
+  if (argv.length > 1) {
+    process.stderr.write("repo lint: --baseline takes no other arguments; it lints the whole repo\n");
+    return 1;
+  }
+  const [{ seedBaseline }, { checkScriptsAt }] = await Promise.all([
+    import("./lint-baseline.ts"),
+    import("../script-diagnostics.ts"),
+  ]);
+  const scripts = await checkScriptsAt(process.cwd());
+  if (scripts.problems.length > 0) {
+    for (const line of scripts.problems) process.stderr.write(`repo lint: ${line}\n`);
+    return 1;
+  }
+  return runTool("oxlint", [], { run: (_tool, _args, root) => seedBaseline(root, scripts.kept) });
+}

package/cli/scripts/lint-skips.ts

@@ -0,0 +1,139 @@
+/**
+ * `repo check`'s view of `lint.skip`: every skip with its rule, path, hits and reason, a count per rule, and the
+ * entries gone stale. The hits come from one more lint of the skipped files under the generated config without its
+ * skips, written beside `.oxlintrc.json` for the run (oxlint reads override globs against the config's own dir) and
+ * named for the process, so two checks never remove each other's copy.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { findRoot, loadConfig, type LintSkip } from "../config.ts";
+import { sourceFiles } from "../check-comments.ts";
+import { oxlintConfig, unskippedConfigPath } from "../sync/oxlint-config.ts";
+import { readWorkspace, type Workspace } from "../sync/workspace.ts";
+import { type Diagnostic, lintReport } from "./lint-baseline.ts";
+import { captureTool } from "./lint.ts";
+
+/** What `repo check` prints of the skips: report lines that pass, problem lines that fail it. */
+export type SkipCheck = { report: string[]; problems: string[] };
+/** The script checks' hits, no skip applied, and the oxlint runner (`captureTool` unless a test injects another). */
+export type SkipDeps = { scripts: readonly Diagnostic[]; run?: typeof captureTool };
+/** One `lint.skip` entry with the source files its globs match. */
+type Matched = { skip: LintSkip; index: number; files: Set<string> };
+
+const NONE: SkipCheck = { report: [], problems: [] };
+const byKey = (a: string, b: string) => Number(a > b) - Number(a < b);
+const hits = (n: number) => `${n} hit${n === 1 ? "" : "s"}`;
+/** `repo/no-module-state` is reported as `repo(no-module-state)`. */
+export const codeOf = (rule: string): string => rule.replace("/", "(").concat(")");
+
+/**
+ * oxlint's override match: a glob with no slash matches a file's name in any dir, a leading `./` anchors it at the
+ * root, and any other glob matches the root-relative path.
+ */
+function matcherOf(glob: string): Bun.Glob {
+  if (glob.startsWith("./")) return new Bun.Glob(glob.slice(2));
+  return new Bun.Glob(glob.includes("/") ? glob : `**/${glob}`);
+}
+
+/** The `files` (root-relative POSIX paths) any of `globs` matches, as oxlint's overrides match them, in their order. */
+export function skipFiles(globs: readonly string[], files: readonly string[]): string[] {
+  const matchers = globs.map(matcherOf);
+  return files.filter((file) => matchers.some((matcher) => matcher.match(file)));
+}
+
+const noFile = (index: number, glob: string) =>
+  `lint.skip[${index}]: ${JSON.stringify(glob)} matches no file; fix the path or delete the entry`;
+const noHit = ({ skip, index }: Matched, rule: string) =>
+  `lint.skip[${index}]: ${rule} has no hit in ${skip.files.map((glob) => JSON.stringify(glob)).join(", ")}; delete it from the entry`;
+
+/** The diagnostics of `rule` in `files`. */
+const hitsOf = (diagnostics: readonly Diagnostic[], rule: string, files: ReadonlySet<string>) =>
+  diagnostics.filter((d) => d.rule === codeOf(rule) && files.has(d.file));
+
+/** Each entry's report lines, one per rule and glob with hits, and a problem per rule with none. */
+function entryLines(entry: Matched, diagnostics: readonly Diagnostic[], sources: readonly string[]): SkipCheck {
+  const { skip } = entry;
+  const report: string[] = [];
+  const problems: string[] = [];
+  for (const rule of skip.rules) {
+    if (hitsOf(diagnostics, rule, entry.files).length === 0) problems.push(noHit(entry, rule));
+    for (const glob of skip.files) {
+      const count = hitsOf(diagnostics, rule, new Set(skipFiles([glob], sources))).length;
+      if (count > 0) report.push(`skip ${rule} in ${glob}: ${hits(count)} (${skip.reason})`);
+    }
+  }
+  return { report, problems };
+}
+
+/** `skips: <rule> <n>, …`: per rule, the hits any entry turns off, each counted once; null when none. */
+function countLine(entries: readonly Matched[], diagnostics: readonly Diagnostic[]): string | null {
+  const counted = new Map<string, Set<Diagnostic>>();
+  for (const entry of entries) {
+    for (const rule of entry.skip.rules) {
+      const found = counted.get(rule) ?? new Set();
+      for (const hit of hitsOf(diagnostics, rule, entry.files)) found.add(hit);
+      if (found.size > 0) counted.set(rule, found);
+    }
+  }
+  const rules = [...counted.keys()].sort(byKey);
+  return rules.length === 0 ? null : `skips: ${rules.map((rule) => `${rule} ${counted.get(rule)?.size}`).join(", ")}`;
+}
+
+/** The diagnostics of `files` under the generated config without skips, written to the root for the run only. */
+function unskippedReport(workspace: Workspace, files: readonly string[], run: typeof captureTool) {
+  // Only an unknown skip rule fails the build, and this one has no skips.
+  const built = oxlintConfig(workspace, []) /* no skips, so the build cannot fail */ as { ok: true; value: string };
+  const rel = unskippedConfigPath(process.pid);
+  const file = path.join(workspace.root, rel);
+  fs.writeFileSync(file, built.value);
+  try {
+    return lintReport(workspace.root, ["-c", rel, ...files], run);
+  } finally {
+    fs.rmSync(file, { force: true });
+  }
+}
+
+/**
+ * Every `lint.skip` entry checked against the repo: a report line per rule and glob with its hits and reason, a count
+ * per rule, and a problem for a glob that matches no source file and for a rule with no hit in its entry's files. The
+ * hits are oxlint's without skips and the script checks' ones `deps` hands over.
+ */
+export function checkLintSkips(workspace: Workspace, skips: readonly LintSkip[], deps: SkipDeps): SkipCheck {
+  const { scripts, run = captureTool } = deps;
+  if (skips.length === 0) return NONE;
+  const listed = sourceFiles(workspace.root);
+  if (!listed.ok) return { report: [], problems: listed.errors };
+  const entries = skips.map((skip, index) => ({ skip, index, files: new Set(skipFiles(skip.files, listed.files)) }));
+  const files = [...new Set(entries.flatMap((entry) => [...entry.files]))].sort(byKey);
+  const linted = files.length === 0 ? { ok: true as const, value: [] } : unskippedReport(workspace, files, run);
+  if (!linted.ok) return { report: [], problems: linted.errors };
+  const diagnostics = [...linted.value, ...scripts];
+  const lines = entries.map((entry) => {
+    const missing = entry.skip.files.filter((glob) => skipFiles([glob], listed.files).length === 0);
+    // An entry that matches nothing is stale on its paths alone; its rules cannot hit.
+    const checked = entry.files.size === 0 ? NONE : entryLines(entry, diagnostics, listed.files);
+    return {
+      report: checked.report,
+      problems: [...missing.map((glob) => noFile(entry.index, glob)), ...checked.problems],
+    };
+  });
+  const count = countLine(entries, diagnostics);
+  return {
+    report: [...lines.flatMap((line) => line.report), ...(count === null ? [] : [count])],
+    problems: lines.flatMap((line) => line.problems),
+  };
+}
+
+/**
+ * `repo check`'s skip lines for the repo at `cwd`, given its script checks' hits with no skip applied: none without a config,
+ * the standards pack or a readable workspace.
+ */
+export async function checkLintSkipsAt(cwd: string, scripts: readonly Diagnostic[]): Promise<SkipCheck> {
+  const root = findRoot(cwd);
+  if (root === null) return NONE;
+  const loaded = await loadConfig(root);
+  if (!loaded.ok || !loaded.config.packs.includes("standards")) return NONE;
+  // An unreadable manifest is already reported by sync --check.
+  const read = readWorkspace(root);
+  return read.ok ? checkLintSkips(read.workspace, loaded.config.lint.skip, { scripts }) : NONE;
+}

package/cli/scripts/lint.constants.ts

@@ -0,0 +1,6 @@
+/** The prefix of the variables git hands a hook (GIT_DIR, GIT_INDEX_FILE, ...). */
+export const GIT_ENV_PREFIX = "GIT_";
+/** Env-config variables: they set config, not the repo, so a tool keeps them. */
+export const GIT_CONFIG_ENV: RegExp = /^GIT_CONFIG_(COUNT|KEY_\d+|VALUE_\d+)$/;
+/** Where oxlint's json report starts when a note ("No files found to lint.") precedes it: a line opening with `{`. */
+export const REPORT_START: RegExp = /^\{/m;

package/cli/scripts/lint.ts

@@ -0,0 +1,142 @@
+import { spawnSync } from "node:child_process";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { CONFIG_FILE, findRoot, loadConfig } from "../config.ts";
+import { OXLINT_CONFIG_PATH } from "../sync/oxlint-config.ts";
+import { OXFMT_CONFIG_PATH } from "../sync/standards.ts";
+import { WINDOWS_PLATFORM } from "../actionlint.constants.ts";
+import { childEnv, readEnv } from "../env.ts";
+import { GIT_CONFIG_ENV, GIT_ENV_PREFIX } from "./lint.constants.ts";
+
+/** The pinned tools the standards pack runs. */
+export type Tool = "oxlint" | "oxfmt";
+/** Runs `tool` with `args` in `root` and returns its exit code. */
+export type RunTool = (tool: Tool, args: string[], root: string) => number;
+export type ToolDeps = { cwd?: string; stderr?: (s: string) => void; run?: RunTool };
+
+const COMMAND: Record<Tool, string> = { oxlint: "lint", oxfmt: "fmt" };
+const CONFIG: Record<Tool, string> = { oxlint: OXLINT_CONFIG_PATH, oxfmt: OXFMT_CONFIG_PATH };
+
+/**
+ * `repo lint` and `repo fmt`: the pinned tool, run in the repo root with the arguments given, once the config
+ * loads with the standards pack on and sync has written the tool's config. Its exit code is returned as is.
+ */
+export async function runTool(tool: Tool, args: string[], deps: ToolDeps = {}): Promise<number> {
+  const { cwd = process.cwd(), stderr = (s: string) => process.stderr.write(s), run = spawnTool } = deps;
+  const fail = (lines: string[]): number => {
+    for (const line of lines) stderr(`repo ${COMMAND[tool]}: ${line}\n`);
+    return 1;
+  };
+  const root = findRoot(cwd);
+  if (root === null) return fail([`no ${CONFIG_FILE} in ${cwd} or any parent; run \`bun repo init\``]);
+  const loaded = await loadConfig(root);
+  if (!loaded.ok) return fail(loaded.errors);
+  if (!loaded.config.packs.includes("standards"))
+    return fail([`the standards pack is off; add "standards" to packs in ${CONFIG_FILE}`]);
+  if (!fs.existsSync(path.join(root, CONFIG[tool])))
+    return fail([`no ${CONFIG[tool]}; run \`bun repo sync\` to write it`]);
+  return run(tool, args, root);
+}
+
+export const lint = (argv: string[]): Promise<number> => runTool("oxlint", argv);
+export const fmt = (argv: string[]): Promise<number> => runTool("oxfmt", argv);
+
+/** The file a package export resolves to, from this package's install. */
+function resolved(specifier: string): string {
+  // Bun.resolveSync, not import.meta.resolve: vitest's transform drops the latter, and tests run this in-process.
+  return Bun.resolveSync(specifier, import.meta.dirname);
+}
+
+/** The tool's bin script, read from its package.json; it is a node shim, so bun runs it. */
+function binOf(tool: Tool): string {
+  const manifest = resolved(`${tool}/package.json`);
+  const { bin } = JSON.parse(fs.readFileSync(manifest, "utf8")) as { bin: Record<string, string> };
+  return path.join(path.dirname(manifest), bin[tool] as string);
+}
+
+/** What a captured run printed and its exit code. */
+export type Captured = { code: number; stdout: string; stderr: string };
+
+/**
+ * The node_modules dir holding `@workerstack/repo` for this package at `packageRoot`: the one its scope dir sits in
+ * when installed (bunx, a consumer), else the root's own, which a dev checkout fills with a self-link.
+ */
+export function pluginModules(packageRoot: string): string {
+  const modules = path.dirname(path.dirname(packageRoot));
+  return path.basename(modules) === "node_modules" ? modules : path.join(packageRoot, "node_modules");
+}
+
+/** The package export of the native tsgolint binary for a platform and arch; Windows' ends in `.exe`. */
+export function tsgolintSpecifier(platform: NodeJS.Platform, arch: string): string {
+  return `@oxlint-tsgolint/${platform}-${arch}/tsgolint${platform === WINDOWS_PLATFORM ? ".exe" : ""}`;
+}
+
+/**
+ * What oxlint needs beyond the inherited environment: the native tsgolint binary, which its own lookup would reach
+ * through a node shim, and a NODE_PATH led by the node_modules holding this package, so the config's
+ * `@workerstack/repo/lint` plugin loads in a repo with no install of its own.
+ */
+function oxlintEnv(): NodeJS.ProcessEnv {
+  const modules = pluginModules(path.resolve(import.meta.dirname, "..", ".."));
+  const inherited = readEnv().NODE_PATH;
+  return {
+    OXLINT_TSGOLINT_PATH: resolved(tsgolintSpecifier(process.platform, process.arch)),
+    NODE_PATH: inherited ? `${modules}${path.delimiter}${inherited}` : modules,
+  };
+}
+
+/** The bun command line and environment that run `tool`. */
+function commandOf(tool: Tool): { args: string[]; env: NodeJS.ProcessEnv } {
+  return { args: [binOf(tool)], env: childEnv(tool === "oxlint" ? oxlintEnv() : {}) };
+}
+
+/** Spawns bun on the tool's bin, output straight to the terminal. */
+function spawnTool(tool: Tool, args: string[], root: string): number {
+  const command = commandOf(tool);
+  const result = spawnSync(process.execPath, [...command.args, ...args], {
+    cwd: root,
+    stdio: "inherit",
+    env: toolEnv(command.env),
+  });
+  return result.status ?? 1;
+}
+
+/**
+ * `env` without any `GIT_*` variable. Git hands a hook GIT_DIR, GIT_INDEX_FILE and more; a tool run from one that
+ * kept them would aim every git call it makes, a test's `git init` in its own temp dir included, at the repo being
+ * committed. `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_<n>` and `GIT_CONFIG_VALUE_<n>` stay: they set config, not the repo
+ * (the test setup uses them to switch off background git), and git does not hand them to hooks.
+ */
+export function toolEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  return Object.fromEntries(
+    Object.entries(env).filter(([name]) => !name.startsWith(GIT_ENV_PREFIX) || GIT_CONFIG_ENV.test(name)),
+  );
+}
+
+/**
+ * Runs bun with `args` in `cwd`, its output captured instead of printed, with no `GIT_*` variable (`toolEnv`). The
+ * output goes to files, not pipes: a node script that exits right after writing (oxlint's json report) loses what a
+ * pipe had not yet taken.
+ */
+export function captureBun(args: string[], cwd: string, env: NodeJS.ProcessEnv = childEnv()): Captured {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "workerstack-capture-"));
+  const files = { stdout: path.join(dir, "stdout"), stderr: path.join(dir, "stderr") };
+  const out = fs.openSync(files.stdout, "w");
+  const err = fs.openSync(files.stderr, "w");
+  try {
+    const result = spawnSync(process.execPath, args, { cwd, env: toolEnv(env), stdio: ["ignore", out, err] });
+    const read = (file: string) => fs.readFileSync(file, "utf8");
+    return { code: result.status ?? 1, stdout: read(files.stdout), stderr: read(files.stderr) };
+  } finally {
+    fs.closeSync(out);
+    fs.closeSync(err);
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/** The tool run as `repo lint` or `repo fmt` runs it, in `root`, its output captured instead of printed. */
+export function captureTool(tool: Tool, args: string[], root: string): Captured {
+  const command = commandOf(tool);
+  return captureBun([...command.args, ...args], root, command.env);
+}