@zgeoff/chex 0.0.0 → 0.0.2

package/src/read-branch-files.ts

@@ -0,0 +1,59 @@
+import { readBranchBase } from './read-branch-base.ts';
+import type { RunProgram } from './run-program.ts';
+import { runProgram } from './run-program.ts';
+
+interface ReadBranchFilesOptions {
+  readonly cwd: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly runProgram: RunProgram;
+
+  // Lists the paths the branch deletes too, which a check that compares the disk with HEAD needs.
+  readonly withDeleted?: boolean;
+}
+
+// lefthook's {push_files} lists all of history for a branch with no upstream, so the pre-push
+// baseline reads its file list from here.
+export function readBranchFiles(options: Readonly<ReadBranchFilesOptions>): string[] {
+  const base = readBranchBase(options);
+
+  const diff = options.runProgram(
+    [
+      'git',
+      'diff',
+      '--name-only',
+      '-z',
+      '--no-renames',
+      ...(options.withDeleted === true ? [] : ['--diff-filter=d']),
+      base,
+      'HEAD',
+    ],
+    { cwd: options.cwd, env: options.env },
+  );
+
+  if (diff.exitCode !== 0) {
+    throw new Error(`git diff failed: ${diff.stderr.trim()}`);
+  }
+
+  // -z prints each path as it is, where a newline list would quote a path with a byte past ASCII.
+  return diff.stdout.split('\0').filter((path) => path !== '');
+}
+
+function runCLI(): void {
+  try {
+    const files = readBranchFiles({ cwd: process.cwd(), env: process.env, runProgram });
+
+    if (files.length > 0) {
+      process.stdout.write(`${files.join('\n')}\n`);
+    }
+  } catch (error) {
+    process.stderr.write(
+      `read-branch-files: ${error instanceof Error ? error.message : String(error)}\n`,
+    );
+
+    process.exit(1);
+  }
+}
+
+if (import.meta.main) {
+  runCLI();
+}

package/src/read-pushed-ranges.ts

@@ -0,0 +1,47 @@
+import { parsePushedRefs } from './parse-pushed-refs.ts';
+import type { ReadBranchBaseOptions } from './read-branch-base.ts';
+import { readBranchBase, readDefaultBranch } from './read-branch-base.ts';
+import type { CommitRange } from './read-range-commits.ts';
+
+export interface PushedRangesOptions extends ReadBranchBaseOptions {
+  // The lines git hands a pre-push hook on stdin, or null outside a push.
+  readonly pushedRefs: string | null;
+}
+
+export function readPushedRanges(options: Readonly<PushedRangesOptions>): CommitRange[] {
+  if (options.pushedRefs === null) {
+    const base = readBranchBase(options);
+
+    return [[`${base}..HEAD`]];
+  }
+
+  const refs = parsePushedRefs(options.pushedRefs);
+
+  if (refs.length === 0) {
+    return [];
+  }
+
+  const defaultBranch = readDefaultBranch(options);
+
+  if (!probeCommitPresent(options, defaultBranch)) {
+    throw new Error(
+      `cannot find origin's default branch: ${defaultBranch} is not a commit (is the remote fetched?)`,
+    );
+  }
+
+  return refs.map((ref) =>
+    ref.remoteSha !== null && probeCommitPresent(options, ref.remoteSha)
+      ? [ref.localSha, `^${defaultBranch}`, `^${ref.remoteSha}`]
+      : [ref.localSha, `^${defaultBranch}`],
+  );
+}
+
+// A remote ref that another clone moved points at a commit this clone may lack.
+function probeCommitPresent(options: Readonly<ReadBranchBaseOptions>, revision: string): boolean {
+  const result = options.runProgram(['git', 'cat-file', '-e', `${revision}^{commit}`], {
+    cwd: options.cwd,
+    env: options.env,
+  });
+
+  return result.exitCode === 0;
+}

package/src/read-pushed-refs-input.ts

@@ -0,0 +1,18 @@
+import { parseArgs } from 'node:util';
+
+export type ReadStdin = () => Promise<string>;
+
+// Only a hook that passes `--pushed-refs` hands over stdin; a manual run leaves stdin a terminal,
+// where a read waits for input.
+export function readPushedRefsInput(
+  args: readonly string[],
+  readStdin: ReadStdin,
+): Promise<string | null> {
+  const parsed = parseArgs({
+    args: [...args],
+    options: { 'pushed-refs': { type: 'boolean' } },
+    strict: true,
+  });
+
+  return parsed.values['pushed-refs'] === true ? readStdin() : Promise.resolve(null);
+}

package/src/read-range-commits.ts

@@ -0,0 +1,30 @@
+import type { RunProgram } from './run-program.ts';
+
+// The revisions of one `git rev-list` call, such as `['<local sha>', '^origin/main']`.
+export type CommitRange = readonly string[];
+
+export interface ReadRangeCommitsOptions {
+  readonly cwd: string;
+  readonly env: Readonly<Record<string, string | undefined>>;
+  readonly runProgram: RunProgram;
+}
+
+// Two ranges can share a commit, such as two branches that start from the same one, and git log
+// cannot read a union of ranges, so each range is listed apart and each commit kept once.
+export function readRangeCommits(
+  options: Readonly<ReadRangeCommitsOptions>,
+  ranges: readonly CommitRange[],
+): string[] {
+  const commits = ranges.flatMap((range) => {
+    const argv = ['git', 'rev-list', ...range];
+    const result = options.runProgram(argv, { cwd: options.cwd, env: options.env });
+
+    if (result.exitCode !== 0) {
+      throw new Error(`${argv.join(' ')} failed: ${result.stderr.trim()}`);
+    }
+
+    return result.stdout.split('\n').filter((line) => line !== '');
+  });
+
+  return [...new Set(commits)];
+}

package/src/run-chex.ts

@@ -0,0 +1,62 @@
+import { match } from 'ts-pattern';
+import type { CheckName } from './check-names.ts';
+import { chexUsage, parseChexArgs } from './parse-chex-args.ts';
+
+export interface ChexDeps {
+  readonly runCheck: (name: CheckName, args: readonly string[]) => Promise<number>;
+  readonly runInit: () => Promise<number>;
+  readonly writeOutput: (text: string) => void;
+  readonly writeError: (text: string) => void;
+}
+
+// Runs every named check, even after one bounces, so the output names each check that fails.
+// Returns the highest exit code of the checks, and 2 for a refused request.
+export function runChex(argv: readonly string[], deps: ChexDeps): Promise<number> {
+  return match(parseChexArgs(argv))
+    .with({ kind: 'refused' }, (refusal) => {
+      deps.writeError(`chex: ${refusal.message}\n${chexUsage}\n`);
+
+      return Promise.resolve(2);
+    })
+    .with({ kind: 'init' }, () => deps.runInit())
+    .with({ kind: 'checks' }, (request) => runChecks(request.names, request.args, deps))
+    .exhaustive();
+}
+
+async function runChecks(
+  names: readonly CheckName[],
+  args: readonly string[],
+  deps: ChexDeps,
+): Promise<number> {
+  let exitCode = 0;
+
+  for (const name of names) {
+    const checkExitCode = await runOneCheck(name, args, deps);
+
+    deps.writeOutput(`${checkExitCode === 0 ? 'cleared' : 'bounced'}: ${name}\n`);
+
+    exitCode = Math.max(exitCode, checkExitCode);
+  }
+
+  return exitCode;
+}
+
+// A check that throws, such as a shell script on a host without bash, cannot run, and so does a
+// script that exits with a shell's own code, such as 127 for a missing perl: each counts as exit 2.
+async function runOneCheck(
+  name: CheckName,
+  args: readonly string[],
+  deps: ChexDeps,
+): Promise<number> {
+  try {
+    const exitCode = await deps.runCheck(name, args);
+
+    return exitCode === 0 || exitCode === 1 ? exitCode : 2;
+  } catch (error) {
+    deps.writeError(
+      `chex: ${name} cannot run: ${error instanceof Error ? error.message : String(error)}\n`,
+    );
+
+    return 2;
+  }
+}

package/src/run-commits-check.ts

@@ -0,0 +1,178 @@
+import { dirname, join } from 'node:path';
+import { formatCommitLines } from './format-commit-lines.ts';
+import { readPushedRanges } from './read-pushed-ranges.ts';
+import { readPushedRefsInput } from './read-pushed-refs-input.ts';
+import type { CommitRange } from './read-range-commits.ts';
+import { readRangeCommits } from './read-range-commits.ts';
+import type { ProgramResult, RunProgram } from './run-program.ts';
+import { runProgram } from './run-program.ts';
+
+export interface CommitsCheckOptions {
+  readonly cwd: string;
+
+  readonly ranges: readonly CommitRange[];
+
+  readonly env: Readonly<Record<string, string | undefined>>;
+
+  readonly commitlint: string;
+  readonly config: string;
+
+  readonly runProgram: RunProgram;
+}
+
+// --config replaces any commitlint config the repo keeps, so every repo that runs the check lints
+// with the same rules.
+export function runCommitsCheck(options: Readonly<CommitsCheckOptions>): string[] {
+  return readBranchCommits(options).flatMap((commit) => {
+    const result = options.runProgram(
+      [options.commitlint, '--config', options.config, '--color=false'],
+      { cwd: options.cwd, env: options.env, stdin: commit.message },
+    );
+
+    return parseCommitlintOutput(commit.hash, result);
+  });
+}
+
+interface Commit {
+  readonly hash: string;
+  readonly message: string;
+}
+
+// A merge commit carries the message git wrote, so the check leaves it out.
+function readBranchCommits(options: Readonly<CommitsCheckOptions>): Commit[] {
+  const commits = readRangeCommits(options, options.ranges);
+
+  // git log reads HEAD when stdin names no commit.
+  if (commits.length === 0) {
+    return [];
+  }
+
+  const result = options.runProgram(
+    ['git', 'log', '--no-merges', '-z', '--format=%h%n%B', '--no-walk=unsorted', '--stdin'],
+    { cwd: options.cwd, env: options.env, stdin: formatCommitLines(commits) },
+  );
+
+  if (result.exitCode !== 0) {
+    throw new Error(`git log failed: ${result.stderr.trim()}`);
+  }
+
+  return result.stdout
+    .split('\0')
+    .filter((entry) => entry !== '')
+    .map((entry) => {
+      const newline = entry.indexOf('\n');
+
+      return { hash: entry.slice(0, newline), message: entry.slice(newline + 1) };
+    });
+}
+
+function parseCommitlintOutput(hash: string, result: ProgramResult): string[] {
+  // The default formatter: `✖   subject may not be empty [subject-empty]`. The summary line,
+  // `✖   found 1 problems, 0 warnings`, ends with no rule name.
+  const problemLine = /^✖\s+(?<message>.+ \[[\w-]+\])$/u;
+
+  // commitlint exits 1 when it reports a problem, and with other codes when it cannot run, such as
+  // 9 for a config with no rules.
+  if (result.exitCode > 1) {
+    throw new Error(`commitlint failed: ${result.stderr.trim() || result.stdout.trim()}`);
+  }
+
+  const problems = result.stdout.split('\n').flatMap((line) => {
+    const message = problemLine.exec(line)?.groups?.['message'];
+
+    return message === undefined ? [] : [`commit ${hash}: ${message}`];
+  });
+
+  // An exit of 1 with no problem it could read is a crash, such as a config it cannot load.
+  if (result.exitCode === 1 && problems.length === 0) {
+    throw new Error(`commitlint failed: ${result.stderr.trim()}`);
+  }
+
+  return problems;
+}
+
+// Returns the exit code: 0 when clean or skipped, 1 with a problem, and 2 when the check cannot run.
+export async function runCommitsCommand(args: readonly string[]): Promise<number> {
+  const cwd = process.cwd();
+
+  const commitlint = Bun.which('commitlint', {
+    PATH: `${join(cwd, 'node_modules/.bin')}:${process.env['PATH'] ?? ''}`,
+  });
+
+  if (commitlint === null) {
+    writeSkipNotice(
+      'the repo does not install commitlint; add @commitlint/cli and @zgeoff/commitlint-config as devDependencies to run it',
+    );
+
+    return 0;
+  }
+
+  if (!(await probeConfigInstalled(cwd))) {
+    writeSkipNotice(
+      'the repo does not install @zgeoff/commitlint-config; add it as a devDependency to run it',
+    );
+
+    return 0;
+  }
+
+  try {
+    // An installed package that still fails to resolve, such as one whose export names a missing
+    // file, is broken, so it throws here rather than skip.
+    const config = Bun.resolveSync('@zgeoff/commitlint-config', cwd);
+
+    const ranges = readPushedRanges({
+      cwd,
+      env: process.env,
+      pushedRefs: await readPushedRefsInput(args, () => Bun.stdin.text()),
+      runProgram,
+    });
+
+    const problems = runCommitsCheck({
+      cwd,
+      ranges,
+      env: process.env,
+      commitlint,
+      config,
+      runProgram,
+    });
+
+    for (const problem of problems) {
+      process.stdout.write(`${problem}\n`);
+    }
+
+    return problems.length === 0 ? 0 : 1;
+  } catch (error) {
+    process.stderr.write(`commits: ${error instanceof Error ? error.message : String(error)}\n`);
+
+    return 2;
+  }
+}
+
+// Bun's resolver throws the same error for a package that is absent and for one it cannot read, so
+// the check looks for the package's package.json in each node_modules that resolution walks.
+async function probeConfigInstalled(cwd: string): Promise<boolean> {
+  const found = await Promise.all(
+    collectAncestorFolders(cwd).map((folder) =>
+      Bun.file(join(folder, 'node_modules/@zgeoff/commitlint-config/package.json')).exists(),
+    ),
+  );
+
+  return found.includes(true);
+}
+
+function collectAncestorFolders(folder: string): string[] {
+  const parent = dirname(folder);
+
+  return parent === folder ? [folder] : [folder, ...collectAncestorFolders(parent)];
+}
+
+function writeSkipNotice(reason: string): void {
+  // GitHub Actions shows a line that starts with ::notice:: on the run's summary.
+  const prefix = process.env['GITHUB_ACTIONS'] === 'true' ? '::notice::' : '';
+
+  process.stdout.write(`${prefix}commits: skipped, because ${reason}\n`);
+}
+
+if (import.meta.main) {
+  process.exitCode = await runCommitsCommand(process.argv.slice(2));
+}

package/src/run-init.ts

@@ -0,0 +1,129 @@
+import { join } from 'node:path';
+import { match } from 'ts-pattern';
+import type { InitWrite } from './build-init-plan.ts';
+import { buildInitPlan } from './build-init-plan.ts';
+
+export interface InitDeps {
+  readonly repoRoot: string;
+
+  // Returns undefined for a file that does not exist.
+  readonly readText: (path: string) => Promise<string | undefined>;
+
+  readonly writeText: (path: string, text: string) => Promise<void>;
+
+  readonly renameFile: (from: string, to: string) => Promise<void>;
+
+  // A missing file is no error.
+  readonly removeFile: (path: string) => Promise<void>;
+
+  readonly writeOutput: (text: string) => void;
+
+  readonly writeError: (text: string) => void;
+}
+
+export async function runInit(deps: InitDeps): Promise<number> {
+  const packageText = await deps.readText(join(deps.repoRoot, 'package.json'));
+  const lefthookText = await deps.readText(join(deps.repoRoot, 'lefthook.yml'));
+
+  const plan = buildInitPlan(packageText, lefthookText);
+
+  return match(plan)
+    .with({ kind: 'refused' }, (refusal) => {
+      deps.writeError(refusal.reasons.map((reason) => `chex init: ${reason}\n`).join(''));
+
+      return Promise.resolve(1);
+    })
+    .with({ kind: 'apply' }, async (apply) => {
+      const originals = { 'package.json': packageText, 'lefthook.yml': lefthookText };
+
+      const failure = await writeInitFiles(apply.writes, originals, deps);
+
+      if (failure !== null) {
+        deps.writeError(`chex init: ${failure}, so both files stay as they were\n`);
+
+        return 1;
+      }
+
+      deps.writeOutput(apply.notes.map((note) => `chex init: ${note}\n`).join(''));
+
+      return 0;
+    })
+    .exhaustive();
+}
+
+type InitOriginals = Readonly<Record<InitWrite['file'], string | undefined>>;
+
+// Writes each file in full beside its target before any target changes, then renames each into
+// place, so a failed write never touches a target. Returns the failure, after it puts back each
+// target already replaced; null when every file is in place.
+async function writeInitFiles(
+  writes: readonly InitWrite[],
+  originals: InitOriginals,
+  deps: InitDeps,
+): Promise<string | null> {
+  const staged: InitWrite[] = [];
+
+  for (const write of writes) {
+    const failure = await settleEffect(deps.writeText(toStagedPath(deps, write.file), write.text));
+
+    if (failure !== null) {
+      await removeStagedFiles([...staged, write], deps);
+
+      return `could not write ${write.file}: ${failure}`;
+    }
+
+    staged.push(write);
+  }
+
+  const replaced: InitWrite[] = [];
+
+  for (const write of staged) {
+    const failure = await settleEffect(
+      deps.renameFile(toStagedPath(deps, write.file), join(deps.repoRoot, write.file)),
+    );
+
+    if (failure !== null) {
+      await removeStagedFiles(staged.slice(replaced.length), deps);
+      await restoreFiles(replaced, originals, deps);
+
+      return `could not replace ${write.file}: ${failure}`;
+    }
+
+    replaced.push(write);
+  }
+
+  return null;
+}
+
+// Returns the effect's failure as its message, or null when it succeeds.
+async function settleEffect(effect: Promise<void>): Promise<string | null> {
+  try {
+    await effect;
+
+    return null;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
+
+function toStagedPath(deps: InitDeps, file: InitWrite['file']): string {
+  return join(deps.repoRoot, `${file}.chex-init`);
+}
+
+// A staged file that cannot go stays behind; the targets are what init keeps whole.
+async function removeStagedFiles(writes: readonly InitWrite[], deps: InitDeps): Promise<void> {
+  await Promise.allSettled(writes.map((write) => deps.removeFile(toStagedPath(deps, write.file))));
+}
+
+async function restoreFiles(
+  replaced: readonly InitWrite[],
+  originals: InitOriginals,
+  deps: InitDeps,
+): Promise<void> {
+  for (const write of replaced) {
+    const path = join(deps.repoRoot, write.file);
+    const original = originals[write.file];
+
+    await (original === undefined ? deps.removeFile(path) : deps.writeText(path, original));
+  }
+}