feat: add --rev, and stop the CLI hanging or passing in silence - #544

Three CLI behaviours that bit this project's own CI while #541 was being built, fixed as three commits. Together they make commit-check behave predictably when a script, a workflow, or an agent drives it rather than a human at a terminal.

1. commit-check --author-name could hang forever

stdin was read whenever it was not a tty — for every check type. On a pipe that is open but that nothing will ever write to or close (what stdin looks like under some CI runners and process managers), read() blocks indefinitely. In a workflow that is a stuck step, not a failed one, which is the worst way to fail.

The read is now gated with select(): genuinely piped input is already in the pipe buffer when the process starts (and EOF counts as readable), while an idle pipe is not readable and never will be. Piping still works — printf '%s' "$msg" | commit-check --message is unchanged — and Windows keeps the historic path, since select() only handles sockets there.

Regression tests use real pipes rather than mocks: idle-open pipe returns promptly, piped content still arrives, /dev/null reads as nothing.

2. There was no way to say which commit to check

Message checks read HEAD; author checks read the local git config before falling back to HEAD's author. Two consequences:

• CI could not iterate a pull request's commits without checking each one out.
• A malformed author on any commit passed, as long as whoever ran the check had a valid identity configured. Verified on a repo whose commit author is a with a clean config: exit 0.

New --rev REVISION names the commit under test. Message checks read that commit's message; author checks read that commit's author, never the config — an existing commit's identity is a fact about the commit, not about the operator. A revision that doesn't resolve is a clear one-line error up front. --rev plus a message file is rejected, and stdin is not consulted, since each would name a second subject for the same checks.

This is the revision input that came up in #541's review as an engine gap the workflow couldn't paper over. With it, iterating a PR becomes:

for sha in $(git rev-list HEAD^1..HEAD^2); do
  commit-check --message --author-name --author-email --rev "$sha"
done

3. Skipped checks were silent, which reads as passed

On a pull_request checkout HEAD is the synthetic merge commit. The subject rules bypass merge subjects — so a bare commit-check --message exited 0 having judged nothing it was asked about. That silence is what #541 had to engineer around in shell.

The merge/fixup bypasses now return SKIP (the status #537 introduced) instead of PASS, and text mode prints one stderr line naming every skipped check:

⊘ skipped (not validated): subject-max-length, subject-min-length

Exit codes are unchanged — a skip is still not a failure — and stdout is untouched, so nothing parsing it notices. ignore_authors keeps its PASS on an absent message: it judges the author and had already done so; a SKIP there would wrongly read as the author having been bypassed.

Verification

• 580 passed; the one failure is the pre-existing config_test.py::test_load_config_file_permission_error, which fails on a clean main in this environment because the suite runs as root.
• ruff clean, formatted, codespell clean.
• Live checks besides the tests: the exact hang reproduced then eliminated; --rev HEAD^1 passes with a deliberately broken local config, proving the config is no longer consulted; the merge-HEAD false-green scenario now prints the skip notice.
• All commit subjects pass this branch's own commit-check --message.

Follow-ups (not in this PR)

• docs: --rev and the skip notice want entries on commit-check.com's configuration and rules pages, plus a changelog entry when this ships (v2.15.0 — the --rev addition makes it a minor).
• commit-check-action can drop its checkout gymnastics once it can rely on --rev.

Summary by CodeRabbit

• New Features

  • Added --rev to validate a specific Git commit revision.
  • Revision-based validation now uses that commit's message and author details.
  • Added clear handling for invalid revisions and conflicting command-line options.

• Bug Fixes

  • Prevented validation from hanging on idle piped input.
  • Machine-generated, absent, or empty commit messages are now correctly marked as skipped.
  • Skipped checks are reported clearly in command-line output.