@workerstack/repo 0.0.0-stage → 0.1.0

package/cli/commit-msg.ts

@@ -0,0 +1,194 @@
+import fs from "node:fs";
+import path from "node:path";
+import { changelogProblems, type Kind } from "./commit-changelog.ts";
+import { HEADER, isBreaking } from "./conventional.ts";
+import { commitRange } from "./commit-range.ts";
+import { NAME_A_SOURCE, RANGE_ARGS, RANGE_FLAG } from "./commit-range.constants.ts";
+import { DEFAULT_MAX_CHANGED_LINES, findRoot, loadConfig } from "./config.ts";
+import { type NameStatus, parseNameStatus, redProof as realRedProof, type RedProofResult } from "./red-proof.ts";
+import { stagedChange } from "./staged-change.ts";
+import { runGit } from "./sync/standards.ts";
+import { readWorkspace, type Workspace } from "./sync/workspace.ts";
+import { isTestFile } from "./test-files.ts";
+import { type Owner, ownerLookup, proofApplies } from "./tdd-scope.ts";
+
+/** The Conventional Commits types a commit may use. */
+export const TYPES: string[] = ["feat", "fix", "perf", "refactor", "test", "docs", "build", "ci", "chore", "revert"];
+
+/** Scopes every monorepo accepts besides its workspace package names. */
+export const REPO_SCOPES: string[] = ["repo", "deps", "ci"];
+
+const MAX_HEADER = 100;
+const NEEDS_TEST = new Set(["feat", "fix"]);
+/** The line above the diff `git commit --verbose` appends; everything from it down is not the message. */
+const SCISSORS = "# ------------------------ >8 ------------------------";
+
+/** What a message is checked against: the staged paths and changed lines, the limit, and the workspace's scopes. */
+export type CommitFacts = {
+  stagedFiles: string[];
+  changedLines: number;
+  maxChangedLines: number;
+  scopes?: string[] | undefined;
+};
+
+/** What the repo's config and workspace set: the size limit, and the scopes of a monorepo. */
+export type CommitRules = {
+  maxChangedLines: number;
+  scopes?: string[] | undefined;
+  /** Whether a feat or fix is held to red-proof even in private packages. */
+  tdd: boolean;
+  /** The package owning a repo-relative file. */
+  owners: (file: string) => Owner;
+};
+/** Where `repo commit-msg` runs and prints; `redProof` is the red-proof runner, replaceable in tests. */
+export type CommitMsgIo = {
+  cwd: string;
+  stderr: (text: string) => void;
+  redProof?: (root: string, change: NameStatus[]) => RedProofResult;
+};
+
+/** The scope problem, if any: kebab-case always, and one of `scopes` or the repo scopes when `scopes` is given. */
+function scopeProblems(scope: string | undefined, scopes: string[] | undefined): string[] {
+  if (scope === undefined) return [];
+  if (!/^[a-z0-9]+(-[a-z0-9]+)*$/.test(scope)) return [`the scope "${scope}" must be lowercase kebab-case`];
+  if (scopes === undefined || scopes.includes(scope) || REPO_SCOPES.includes(scope)) return [];
+  const known = `one of ${REPO_SCOPES.join(", ")} (${scopes.join(", ")})`;
+  return [`unknown scope "${scope}"; use a workspace package name or ${known}`];
+}
+
+/** The size problem, if any: over the limit, the message needs a body line saying why. */
+function sizeProblems(body: readonly string[], { changedLines, maxChangedLines }: CommitFacts): string[] {
+  if (changedLines <= maxChangedLines || body.some((line) => line.trim() !== "")) return [];
+  return [
+    `the commit changes ${changedLines} lines, over the limit of ${maxChangedLines}; add a body line saying why, or split it`,
+  ];
+}
+
+/** The lines of the message itself: no comment, and nothing from the verbose diff's scissors line down. */
+function messageLines(message: string): string[] {
+  const all = message.split("\n");
+  const scissors = all.indexOf(SCISSORS);
+  return (scissors === -1 ? all : all.slice(0, scissors)).filter((line) => !line.startsWith("#"));
+}
+
+/** What checking a message found: every problem, and the header's type and breaking mark when the header parsed. */
+type Inspected = { problems: string[]; kind?: Kind };
+
+/** Checks one message, keeping the header's type so the caller need not parse it again. */
+function inspect(message: string, facts: CommitFacts): Inspected {
+  const lines = messageLines(message);
+  const at = lines.findIndex((line) => line.trim() !== "");
+  const header = lines[at];
+  if (header === undefined) return { problems: ["the commit message is empty"] };
+  if (header.startsWith("Merge ")) return { problems: [] };
+
+  const match = HEADER.exec(header);
+  if (!match)
+    return {
+      problems: ['the header must be "type(scope)!: subject", e.g. "fix(paths): compare hook paths canonically"'],
+    };
+
+  // the HEADER regex always captures type and subject; scope is optional
+  const { type, scope, subject } = match.groups as { type: string; scope: string | undefined; subject: string };
+  const problems: string[] = [];
+  if (!TYPES.includes(type)) problems.push(`unknown type "${type}"; use one of ${TYPES.join(", ")}`);
+  problems.push(...scopeProblems(scope, facts.scopes));
+  if (/^[A-Z]/.test(subject)) problems.push("the subject must start lowercase");
+  if (subject.endsWith(".")) problems.push("the subject must not end with a period");
+  if (header.length > MAX_HEADER) problems.push(`the header is ${header.length} characters; keep it to ${MAX_HEADER}`);
+  if (NEEDS_TEST.has(type) && !facts.stagedFiles.some(isTestFile)) {
+    problems.push(`a ${type} commit must include a test change (a *.test.* or *.spec.* file, or a file under e2e/)`);
+  }
+  const body = lines.slice(at + 1);
+  return { problems: [...problems, ...sizeProblems(body, facts)], kind: { type, breaking: isBreaking(header, body) } };
+}
+
+/**
+ * Checks one commit message against the Conventional Commits rules and the size limit, and returns every problem it
+ * finds, or an empty list when the message passes. Without `scopes` any kebab-case scope is accepted.
+ */
+export function checkCommitMessage(message: string, facts: CommitFacts): string[] {
+  return inspect(message, facts).problems;
+}
+
+/** The scopes of a monorepo: the last segment of each workspace package name, or its folder; none for one package. */
+function scopesOf(workspace: Workspace): string[] | undefined {
+  if (workspace.packages.length === 0) return undefined;
+  const names = workspace.packages.map(({ dir, manifest }) => (manifest.name ?? dir).split("/").at(-1) as string);
+  return [...new Set(names)].sort();
+}
+
+/** The limit and scopes for the repo at or above `cwd`: the defaults without a config, or the problems loading it. */
+async function commitRules(cwd: string): Promise<CommitRules | string[]> {
+  const root = findRoot(cwd);
+  const owners = ownerLookup(cwd);
+  if (root === null) return { maxChangedLines: DEFAULT_MAX_CHANGED_LINES, tdd: false, owners };
+  const loaded = await loadConfig(root);
+  if (!loaded.ok) return loaded.errors;
+  const workspace = readWorkspace(root);
+  if (!workspace.ok) return workspace.errors;
+  const { tdd, commit } = loaded.config;
+  return { maxChangedLines: commit.maxChangedLines, scopes: scopesOf(workspace.workspace), tdd, owners };
+}
+
+/** The red-proof result for the staged change, or null when it does not apply to it. */
+function proveRed(rules: CommitRules, io: CommitMsgIo): RedProofResult | null {
+  const diff = runGit(io.cwd, ["diff", "--cached", "--name-status", "--no-renames", "-z"]);
+  const change = parseNameStatus(diff.stdout);
+  return proofApplies(change, rules.tdd, rules.owners) ? (io.redProof ?? realRedProof)(io.cwd, change) : null;
+}
+
+/** Every problem with `message` against the staged change, and the red-proof result when it ran. */
+function judge(
+  message: string,
+  rules: CommitRules,
+  io: CommitMsgIo,
+): { problems: string[]; proof: RedProofResult | null } {
+  const staged = stagedChange(io.cwd);
+  const facts = { ...rules, stagedFiles: staged.files, changedLines: staged.changedLines };
+  const { problems, kind } = inspect(message, facts);
+  const proof = kind !== undefined && problems.length === 0 && NEEDS_TEST.has(kind.type) ? proveRed(rules, io) : null;
+  if (kind !== undefined) problems.push(...changelogProblems(kind, staged.files, rules.owners));
+  if (proof?.ok === false) problems.push(proof.problem);
+  return { problems, proof };
+}
+
+/**
+ * The commit-msg check of the message file at `messageFile` (relative to `io.cwd`, the repo top level git runs hooks
+ * in) against the staged change and `rules`: prints each problem and returns 0 to let the commit through, 1 to refuse.
+ * A passing feat or fix is then held to red-proof where it applies, which prints its line or refuses.
+ */
+export function runCommitMsgHook(messageFile: string, rules: CommitRules, io: CommitMsgIo): number {
+  const message = fs.readFileSync(path.resolve(io.cwd, messageFile), "utf8");
+  const { problems, proof } = judge(message, rules, io);
+  if (problems.length > 0) {
+    io.stderr(`commit-msg: the message was refused\n${problems.map((problem) => `  - ${problem}\n`).join("")}`);
+    return 1;
+  }
+  if (proof?.ok) io.stderr(`${proof.line}\n`);
+  return 0;
+}
+
+/**
+ * `repo commit-msg <file>`, the commit-msg git hook, or `--range <base>..<head>` for the commits of a range: `runCommitMsgHook` with the config's size limit and the
+ * workspace's scopes, or exit 1 with the reason when the file is not named or the config is broken.
+ */
+export async function main(
+  argv: string[],
+  io: CommitMsgIo = { cwd: process.cwd(), stderr: (text) => process.stderr.write(text) },
+): Promise<number> {
+  const ranged = argv[0] === RANGE_FLAG && argv.length === RANGE_ARGS;
+  const [file] = argv;
+  if (file === undefined || (file === RANGE_FLAG ? !ranged : argv.length > 1)) {
+    io.stderr(NAME_A_SOURCE);
+    return 1;
+  }
+  const rules = await commitRules(io.cwd);
+  if (Array.isArray(rules)) {
+    for (const error of rules) io.stderr(`repo commit-msg: ${error}\n`);
+    return 1;
+  }
+  return ranged
+    ? commitRange(argv[1] /* the range follows the flag */ as string, { rules, check: checkCommitMessage }, io)
+    : runCommitMsgHook(file, rules, io);
+}

package/cli/commit-range.constants.ts

@@ -0,0 +1,17 @@
+/** What `repo commit-msg --range` reads and prints. */
+
+/** The `--range` flag. */
+export const RANGE_FLAG = "--range";
+/** A base that names no commit, as a push event of a new branch gives. */
+export const ZERO_SHA = "0000000000000000000000000000000000000000";
+/** The length of an abbreviated sha. */
+export const SHORT_SHA = 7;
+/** A full object name. */
+export const FULL_SHA: RegExp = /^[0-9a-f]{40}$/;
+/** How to call `repo commit-msg`, for the refusal when nothing is named. */
+export const NAME_A_SOURCE =
+  "repo commit-msg: name the commit message file as git's commit-msg hook does or pass --range <base>..<head>\n";
+/** The arguments of `--range <base>..<head>`: the flag and the range. */
+export const RANGE_ARGS = 2;
+/** The sides of a range split on `..`. */
+export const RANGE_SIDES = 2;

package/cli/commit-range.ts

@@ -0,0 +1,57 @@
+import type { CommitFacts, CommitMsgIo, CommitRules } from "./commit-msg.ts";
+import { FULL_SHA, RANGE_SIDES, SHORT_SHA, ZERO_SHA } from "./commit-range.constants.ts";
+import { commitChange } from "./staged-change.ts";
+import { runGit } from "./sync/standards.ts";
+
+/** The checker of one message, as `checkCommitMessage`. */
+type Check = (message: string, facts: CommitFacts) => string[];
+
+/** Whether git succeeds at `cwd` with `args`. */
+const works = (cwd: string, ...args: string[]): boolean => runGit(cwd, args).status === 0;
+/** The non-empty lines git prints at `cwd` with `args`; none when it fails. */
+const linesOf = (cwd: string, ...args: string[]): string[] => runGit(cwd, args).stdout.split("\n").filter(Boolean);
+
+/** The commits to check: those in `base..head` oldest first, or `head` alone, never a merge; null for an unknown range. */
+function commitsOf({ base, head }: { base: string; head: string }, io: CommitMsgIo): string[] | null {
+  const tip = head === "" ? "HEAD" : head;
+  if (!works(io.cwd, "rev-parse", "--verify", `${tip}^{commit}`)) return null;
+  const alone = () => linesOf(io.cwd, "rev-list", "--no-merges", "-n1", tip);
+  if (base === "" || base === ZERO_SHA) return alone();
+  const known = works(io.cwd, "rev-parse", "--verify", `${base}^{commit}`);
+  if (!known && !FULL_SHA.test(base)) return null;
+  if (known && works(io.cwd, "merge-base", "--is-ancestor", base, tip)) {
+    return linesOf(io.cwd, "rev-list", "--reverse", "--no-merges", `${base}..${tip}`);
+  }
+  io.stderr(
+    `commit-msg: ${base.slice(0, SHORT_SHA)} is not an ancestor of HEAD (a force push?); checking HEAD alone\n`,
+  );
+  return alone();
+}
+
+/**
+ * `repo commit-msg --range <base>..<head>`: checks each non-merge commit with `how.check` and `how.rules`, as the hook checks a
+ * staged change, and prints `commit-msg: <sha7> <subject>: <problem>` per problem. Returns 1 when any, or the range is
+ * unknown. A base that is zero, empty or not an ancestor of the head checks the head alone.
+ */
+export function commitRange(range: string, how: { rules: CommitRules; check: Check }, io: CommitMsgIo): number {
+  const { rules, check } = how;
+  const sides = range.split("..");
+  // two sides are read only when the range has exactly two
+  const [base, head] = sides /* two sides, or unused */ as [string, string];
+  const shas = sides.length === RANGE_SIDES ? commitsOf({ base, head }, io) : null;
+  if (shas === null) {
+    io.stderr(`repo commit-msg: no commit range "${range}"; use <base>..<head>\n`);
+    return 1;
+  }
+  let failed = false;
+  for (const sha of shas) {
+    const { files, changedLines } = commitChange(io.cwd, sha);
+    const message = runGit(io.cwd, ["log", "-1", "--format=%B", sha]).stdout;
+    const subject = runGit(io.cwd, ["log", "-1", "--format=%s", sha]).stdout.trim();
+    for (const problem of check(message, { ...rules, stagedFiles: files, changedLines })) {
+      io.stderr(`commit-msg: ${sha.slice(0, SHORT_SHA)} ${subject}: ${problem}\n`);
+      failed = true;
+    }
+  }
+  return failed ? 1 : 0;
+}

package/cli/config-knip.test.ts

@@ -0,0 +1,70 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, expect, it } from "vitest";
+import { CONFIG_FILE, loadConfig } from "./config.ts";
+
+const temps: string[] = [];
+
+afterEach(() => {
+  for (const dir of temps.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+/** A temp repo root holding `body` as the default export of workerstack.config.ts. */
+function repo(body: string): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "workerstack-config-knip-"));
+  temps.push(root);
+  fs.writeFileSync(path.join(root, CONFIG_FILE), `export default ${body}\n`);
+  return root;
+}
+
+const refusal = (message: string) => ({ ok: false, errors: [`workerstack.config.ts: ${message}`] });
+
+it("resolves knip.ignore to none when the config omits knip", async () => {
+  expect(await loadConfig(repo("{}"))).toMatchObject({ ok: true, config: { knip: { ignore: [] } } });
+});
+
+it("resolves a file, a dependency and a binary ignore", async () => {
+  const body = `{ knip: { ignore: [
+    { file: "src/old.ts", reason: "loaded by name" },
+    { dependency: "oxlint", reason: "spawned by path" },
+    { binary: "tsc", reason: "run by a hook" },
+  ] } }`;
+  expect(await loadConfig(repo(body))).toMatchObject({
+    ok: true,
+    config: {
+      knip: {
+        ignore: [
+          { file: "src/old.ts", reason: "loaded by name" },
+          { dependency: "oxlint", reason: "spawned by path" },
+          { binary: "tsc", reason: "run by a hook" },
+        ],
+      },
+    },
+  });
+});
+
+it.each(['{ file: "a.ts" }', '{ file: "a.ts", reason: "" }'])(
+  "refuses the ignore %s without a reason",
+  async (entry) => {
+    expect(await loadConfig(repo(`{ knip: { ignore: [${entry}] } }`))).toEqual(
+      refusal("knip.ignore[0].reason: say why knip cannot see the use"),
+    );
+  },
+);
+
+it.each([
+  '{ file: "a.ts", dependency: "x", reason: "why" }',
+  '{ file: "a.ts", binary: "x", dependency: "y", reason: "why" }',
+  '{ reason: "why" }',
+])("refuses the ignore %s naming not exactly one of its keys", async (entry) => {
+  expect(await loadConfig(repo(`{ knip: { ignore: [{ file: "ok.ts", reason: "why" }, ${entry}] } }`))).toEqual(
+    refusal("knip.ignore[1]: name exactly one of file, dependency or binary"),
+  );
+});
+
+it.each(['["docs"]', "[]"])("refuses knip without the standards pack (packs %s)", async (list) => {
+  expect(await loadConfig(repo(`{ packs: ${list}, knip: {} }`))).toEqual(
+    refusal('knip: set only with the standards pack; add "standards" to packs or delete knip'),
+  );
+});

package/cli/config-nightly.test.ts

@@ -0,0 +1,84 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, describe, expect, it } from "vitest";
+import { CONFIG_FILE, loadConfig } from "./config.ts";
+
+const temps: string[] = [];
+
+afterEach(() => {
+  for (const dir of temps.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+/** A temp repo root holding `body` as the default export of workerstack.config.ts. */
+function repo(body: string): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "workerstack-config-nightly-"));
+  temps.push(root);
+  fs.writeFileSync(path.join(root, CONFIG_FILE), `export default ${body}\n`);
+  return root;
+}
+
+const withRelease = (nightly: string) => repo(`{ packs: ["release"], nightly: ${nightly} }`);
+const refusal = (message: string) => ({ ok: false, errors: [`workerstack.config.ts: ${message}`] });
+const SHARDS_ERROR = "nightly.shards: must be a whole number from 1 to 32";
+const SECRET_ERROR = (at: number) =>
+  `nightly.secrets[${at}]: must be a secret name like CLOUDFLARE_API_TOKEN, not starting with GITHUB_`;
+
+describe("nightly", () => {
+  it("defaults to one shard and no secrets", async () => {
+    expect(await loadConfig(repo("{}"))).toMatchObject({ ok: true, config: { nightly: { shards: 1, secrets: [] } } });
+  });
+
+  it("keeps the shards and secrets a release repo sets", async () => {
+    const loaded = await loadConfig(withRelease('{ shards: 8, secrets: ["API_TOKEN", "_X1"] }'));
+    expect(loaded).toMatchObject({ ok: true, config: { nightly: { shards: 8, secrets: ["API_TOKEN", "_X1"] } } });
+  });
+
+  it("fills the shards when only the secrets are set", async () => {
+    const loaded = await loadConfig(withRelease('{ secrets: ["A"] }'));
+    expect(loaded).toMatchObject({ ok: true, config: { nightly: { shards: 1, secrets: ["A"] } } });
+  });
+
+  it.each(["0", "33", "1.5", '"8"'])("refuses shards %s", async (shards) => {
+    expect(await loadConfig(withRelease(`{ shards: ${shards} }`))).toEqual(refusal(SHARDS_ERROR));
+  });
+
+  it.each(["1", "32"])("accepts shards %s", async (shards) => {
+    expect(await loadConfig(withRelease(`{ shards: ${shards} }`))).toMatchObject({ ok: true });
+  });
+
+  it.each(['"api_token"', '"GITHUB_TOKEN"', '"1A"', '""', "7"])("refuses the secret %s", async (secret) => {
+    expect(await loadConfig(withRelease(`{ secrets: [${secret}] }`))).toEqual(refusal(SECRET_ERROR(0)));
+  });
+
+  it("names the index of the bad secret", async () => {
+    expect(await loadConfig(withRelease('{ secrets: ["A", "b"] }'))).toEqual(refusal(SECRET_ERROR(1)));
+  });
+});
+
+describe("nightly secrets", () => {
+  it("refuses a duplicate secret with its count", async () => {
+    expect(await loadConfig(withRelease('{ secrets: ["A", "B", "A"] }'))).toEqual(
+      refusal('nightly.secrets: "A" is listed twice'),
+    );
+    expect(await loadConfig(withRelease('{ secrets: ["A", "A", "A"] }'))).toEqual(
+      refusal('nightly.secrets: "A" is listed 3 times'),
+    );
+  });
+
+  it("refuses secrets that are not a list and keys it does not know", async () => {
+    expect(await loadConfig(withRelease('{ secrets: "A" }'))).toEqual(
+      refusal("nightly.secrets: must be a list of secret names"),
+    );
+    expect(await loadConfig(withRelease("{ cron: 1 }"))).toEqual(refusal('nightly: unknown key "cron"'));
+    expect(await loadConfig(withRelease("3"))).toEqual(
+      refusal("nightly: must be an object like { shards: 8, secrets: [...] }"),
+    );
+  });
+
+  it("refuses nightly without the release pack", async () => {
+    const message = 'nightly: set only with the release pack; add "release" to packs or delete nightly';
+    expect(await loadConfig(repo("{ nightly: { shards: 8 } }"))).toEqual(refusal(message));
+    expect(await loadConfig(repo('{ packs: ["docs"], nightly: {} }'))).toEqual(refusal(message));
+  });
+});

package/cli/config-tdd.test.ts

@@ -0,0 +1,46 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { afterEach, expect, it } from "vitest";
+import { CONFIG_FILE, loadConfig } from "./config.ts";
+
+const temps: string[] = [];
+
+afterEach(() => {
+  for (const dir of temps.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+});
+
+/** A temp repo root holding `body` as the default export of workerstack.config.ts. */
+function repo(body: string): string {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), "workerstack-config-tdd-"));
+  temps.push(root);
+  fs.writeFileSync(path.join(root, CONFIG_FILE), `export default ${body}\n`);
+  return root;
+}
+
+const refusal = (message: string) => ({ ok: false, errors: [`workerstack.config.ts: ${message}`] });
+
+it("resolves tdd: true", async () => {
+  expect(await loadConfig(repo("{ tdd: true }"))).toMatchObject({ ok: true, config: { tdd: true } });
+});
+
+it("resolves tdd to false when the config omits it", async () => {
+  expect(await loadConfig(repo("{}"))).toMatchObject({ ok: true, config: { tdd: false } });
+});
+
+it.each(['"yes"', "1", "null"])("refuses tdd: %s and names tdd", async (value) => {
+  expect(await loadConfig(repo(`{ tdd: ${value} }`))).toEqual(refusal("tdd: must be true or false"));
+});
+
+it.each(['["docs"]', "[]"])("refuses tdd without the standards pack (packs %s)", async (list) => {
+  expect(await loadConfig(repo(`{ packs: ${list}, tdd: true }`))).toEqual(
+    refusal('tdd: set only with the standards pack; add "standards" to packs or delete tdd'),
+  );
+});
+
+it("accepts tdd with the standards pack listed", async () => {
+  expect(await loadConfig(repo('{ packs: ["standards"], tdd: true }'))).toMatchObject({
+    ok: true,
+    config: { tdd: true },
+  });
+});