imbik-rectifier 0.2.0__py3-none-any.whl

imbik_rectifier-0.2.0.dist-info/METADATA

@@ -0,0 +1,56 @@
+Metadata-Version: 2.5
+Name: imbik-rectifier
+Version: 0.2.0
+Summary: Review the changes in a git checkout with rectifier, imbik's code reviewer
+Project-URL: Homepage, https://rectifier.imbik.ai
+Author: imbik
+Classifier: Environment :: Console
+Classifier: License :: Other/Proprietary License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# rectifier review
+
+Review the changes in a git checkout with [rectifier](https://rectifier.imbik.ai), imbik's code reviewer. The review
+runs on rectifier's service; this command sends the change, waits, and prints the review.
+
+The [docs](https://rectifier.imbik.ai/docs/) have the rest: how to set it up, every option, and how to use it with
+Claude Code.
+
+## Install
+
+```bash
+uv tool install imbik-rectifier     # or: pipx install imbik-rectifier
+```
+
+It needs Python 3.10 or later and git, and nothing else.
+
+## Use
+
+Make a token on the dashboard's CLI tokens page, then, in a checkout of a repository your account has connected:
+
+```bash
+export RECTIFIER_CLI_TOKEN=rct_...
+rectifier review                   # the branch, against where it left the default branch
+rectifier review --last 3          # the last 3 commits
+rectifier review abc123            # one commit
+rectifier review --uncommitted     # the uncommitted changes
+rectifier review --post            # and post it on the branch's open pull or merge request
+```
+
+The report goes to stdout, and a copy to `.rectifier/reviews/`. The exit code is 0 when nothing is blocking, 1 when
+something is, 2 when the review did not run, and 3 when `--uncommitted` stopped for you to agree to the files it sends.
+`rectifier review --help` and the [command's docs](https://rectifier.imbik.ai/docs/?page=cli) have the rest.
+
+Commits your forge does not have yet are uploaded for the review. Before `--uncommitted` sends anything, it lists the
+files it would send, tracked and untracked, and asks. Run without a terminal, as by Claude Code, it sends nothing and
+prints a code instead: `rectifier review --uncommitted --confirm <code>`, run once you agree, sends exactly those files.
+The service deletes them after the review ends.
+
+## Upgrade
+
+```bash
+uv tool upgrade imbik-rectifier     # or: pipx upgrade imbik-rectifier
+```

imbik_rectifier-0.2.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+rectifier_client/__init__.py,sha256=72QeCnSADGJqOgAXARMMcZQ_vMKYt4wr7gZ--aMiKl4,332
+rectifier_client/change.py,sha256=lNIqBPlDdASCWFpQG81BLzyfSxcXfIXohZw-WBbjOZA,16758
+rectifier_client/cli.py,sha256=nc2CvxcCNQ4L6O9rgu05eXcfPDyJYb6T6huZQfeOTvI,882
+rectifier_client/report.py,sha256=tycOngcGW-fU9EhM0Q6UIUvIExQOra9jNkDsSW3xWXw,8967
+rectifier_client/review.py,sha256=rvmLeokiaUrbDTdRfPVoMrhT6WcFyDLm16VM1254Pq0,27094
+imbik_rectifier-0.2.0.dist-info/METADATA,sha256=mqyINLSOkkdYxKp9eB5kfIrF2Yswayl4M_rFEHf-Ky8,2342
+imbik_rectifier-0.2.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+imbik_rectifier-0.2.0.dist-info/entry_points.txt,sha256=M6JK8vP5oevy0pO8b_DG6CK5JOT8gi_0rPm0t3wkTYQ,56
+imbik_rectifier-0.2.0.dist-info/RECORD,,

imbik_rectifier-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

imbik_rectifier-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+rectifier = rectifier_client.cli:main

rectifier_client/__init__.py

@@ -0,0 +1,7 @@
+"""`rectifier review`: the command that sends changes in a local checkout to rectifier's review service and prints the
+review. It uses the standard library only.
+"""
+
+__version__ = "0.2.0"
+"""The version sent with every request (`cli_version`). The service refuses a version too old to read its answers, and
+says how to upgrade."""

rectifier_client/change.py

@@ -0,0 +1,335 @@
+#!/usr/bin/env python3
+"""What `rectifier review` reviews: the commits one call names, read from the local checkout, and the repository and
+forge they belong to.
+
+  (no input)               the branch, against where it left the default branch
+  abc123                   one commit, against its first parent
+  --last 3                 the last 3 commits, as one change
+  main..feature            a range, as one change
+  --uncommitted            the uncommitted changes, against HEAD
+  --uncommitted --base X   the uncommitted changes and the commits since X, against X
+
+Uncommitted changes are reviewed only with `--uncommitted`, as a temporary commit made on the side (`snapshot`).
+"""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import subprocess
+import tempfile
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Callable
+from urllib.parse import urlparse
+
+SCOPES = ("branch", "commit", "last", "range", "uncommitted")
+
+SNAPSHOT_IDENTITY = {
+    "GIT_AUTHOR_NAME": "rectifier", "GIT_AUTHOR_EMAIL": "rectifier@imbik.ai",
+    "GIT_COMMITTER_NAME": "rectifier", "GIT_COMMITTER_EMAIL": "rectifier@imbik.ai",
+}
+"""The author and committer of the temporary commit that `--uncommitted` makes from the user's uncommitted changes.
+Rectifier makes that commit, not the user, and it works whether or not the user's git has a name and email set."""
+
+Git = Callable[..., str]
+
+
+class LocalError(Exception):
+    """Something about the checkout or the request that stops a review before it starts. The message says what."""
+
+
+def _git(repo: Path, *args: str, env: dict[str, str] | None = None, errors: str = "strict") -> str:
+    # Bytes, decoded here: text mode reads a carriage return, which git keeps in an author's email, as a newline.
+    out = subprocess.run(["git", "-C", str(repo), *args], capture_output=True, timeout=600, env=env)
+    if out.returncode != 0:
+        raise LocalError(f"git {' '.join(args)} failed: {out.stderr.decode(errors='replace').strip()[:200]}")
+    # `errors="replace"` is for output only shown or recorded; a name passed back to git keeps the strict default.
+    return out.stdout.decode(errors=errors)
+
+
+@dataclass(frozen=True)
+class Selection:
+    """The commits one call reviews, as a base and a head."""
+
+    base: str
+    head: str
+    scope: str
+    """What kind of input it was: `branch`, `commit`, `last`, `range` or `uncommitted` (`SCOPES`)."""
+    notes: tuple[str, ...] = ()
+    """What the reader should know about how the input was read, such as a `--last N` that ran past the first
+    commit, or the untracked files a review of uncommitted changes takes in."""
+    untracked: tuple[str, ...] = ()
+    """For uncommitted changes, the untracked files the temporary commit takes in."""
+    on: str = ""
+    """For uncommitted changes, the real commit the temporary one sits on, HEAD. The report names this one, since
+    `head` is a commit nobody else has."""
+    branch: str = ""
+    """The checkout's branch; empty when HEAD is detached."""
+    against: str = ""
+    """For the whole branch, the name of what it is compared against, such as `origin/main`."""
+
+    @property
+    def sliced(self) -> bool:
+        """A part of the branch rather than the whole of it, which gets a lite review by default."""
+        return self.scope != "branch"
+
+
+def select(repo: Path, target: str | None = None, last: int | None = None, base: str | None = None,
+           uncommitted: bool = False, git: Git = _git) -> Selection:
+    """The base and head one call reviews. Every name is turned into a full sha here, so the report records the exact
+    commits.
+
+    No input is the whole branch, against where it left `base` or the remote's default branch. `target` is a commit,
+    reviewed against its first parent, or a range `A..B`, reviewed from where B left A. `last` is the last N commits on
+    this branch's own line, first parents only, so commits a merge brought in do not count. `uncommitted` is the
+    working tree against HEAD, or with `base` against where HEAD left it, as a temporary commit (`snapshot`).
+    """
+    if target and last is not None:
+        raise LocalError("give a commit or a range, or --last, not both")
+    if uncommitted and (target or last is not None):
+        raise LocalError("--uncommitted goes with no commit, range or --last; --base is the one input it takes")
+    if base and (target or last is not None):
+        raise LocalError("--base goes with no input or --uncommitted: it changes what the branch is compared against")
+
+    def sha(rev: str) -> str:
+        try:
+            return git(repo, "rev-parse", "--verify", "--quiet", f"{rev}^{{commit}}").strip()
+        except LocalError:
+            raise LocalError(f"{rev!r} is not a commit in this checkout") from None
+
+    def count(a: str, b: str) -> int:
+        return int(git(repo, "rev-list", "--count", f"{a}..{b}").strip() or 0)
+
+    def merge_base(a: str, b: str) -> str:
+        try:
+            return git(repo, "merge-base", a, b).strip()
+        except LocalError:
+            raise LocalError(f"{a[:7]} and {b[:7]} have no commit in common") from None
+
+    branch = git(repo, "rev-parse", "--abbrev-ref", "HEAD").strip()
+    branch = "" if branch == "HEAD" else branch
+
+    if uncommitted:
+        on = sha("HEAD")
+        start = merge_base(sha(base), on) if base else on
+        snap, untracked = snapshot(repo)
+        if snap == "":
+            raise LocalError("there are no uncommitted changes to review")
+        return Selection(start, snap, "uncommitted", untracked=untracked, on=on, branch=branch)
+
+    if last is not None:
+        if last < 1:
+            raise LocalError("--last takes a number of commits, 1 or more")
+        head = sha("HEAD")
+        line = git(repo, "rev-list", "--first-parent", f"--max-count={last + 1}", head).split()
+        if len(line) < 2:
+            raise LocalError("HEAD is the repository's first commit, so it has no parent to compare with")
+        notes: tuple[str, ...] = ()
+        if len(line) <= last:
+            notes = (f"--last {last} goes past the first commit, so this reviews the {len(line) - 1} commits after "
+                     f"it",)
+        start = line[min(last, len(line) - 1)]
+        return Selection(start, head, "last", notes, branch=branch)
+
+    if target and ".." in target:
+        left, _, right = target.partition("...") if "..." in target else target.partition("..")
+        b = sha(right or "HEAD")
+        start = merge_base(sha(left or "HEAD"), b)
+        if not count(start, b):
+            raise LocalError(f"{target} has no commits to review")
+        return Selection(start, b, "range", branch=branch)
+
+    if target:
+        head = sha(target)
+        parents = git(repo, "rev-list", "--parents", "--max-count=1", head).split()[1:]
+        if not parents:
+            raise LocalError(f"{target} is the repository's first commit, so it has no parent to compare with")
+        return Selection(parents[0], head, "commit", branch=branch)
+
+    against = base or default_branch(repo, git)
+    head = sha("HEAD")
+    start = merge_base(sha(against), head)
+    if not count(start, head):
+        raise LocalError(f"HEAD has no commits that {against} does not have, so there is nothing to review. "
+                         f"Name a commit, a range or --last N")
+    return Selection(start, head, "branch", branch=branch, against=against)
+
+
+def snapshot(repo: Path) -> tuple[str, tuple[str, ...]]:
+    """The working tree as a commit on top of HEAD, and the untracked files it takes in. Empty when nothing differs.
+
+    Made with a copy of the index, so the user's index, branch and files are left as they were: `git add -A` into the
+    copy takes in staged and unstaged changes and the untracked files git does not ignore, then `write-tree` and
+    `commit-tree` make a commit no ref points to, by rectifier (`SNAPSHOT_IDENTITY`) at the current time.
+    """
+    untracked = tuple(p for p in _git(repo, "ls-files", "--others", "--exclude-standard", "-z",
+                                           errors="replace").split("\0") if p)
+    index = Path(_git(repo, "rev-parse", "--path-format=absolute", "--git-path", "index").strip())
+    with tempfile.TemporaryDirectory(prefix="rectifier-index-") as scratch:
+        copy = Path(scratch) / "index"
+        if index.exists():
+            # `copy2`, which keeps the index's own modification time: git trusts a file whose size and time match
+            # what the index recorded unless the index is no older than the file, and a copy made now would be newer
+            # than an edit that kept the size, so that edit would be missed.
+            shutil.copy2(index, copy)
+        env = {**os.environ, "GIT_INDEX_FILE": str(copy), **SNAPSHOT_IDENTITY}
+
+        def run(*args: str) -> str:
+            return _git(repo, *args, env=env).strip()
+
+        run("add", "-A")
+        tree = run("write-tree")
+        if tree == run("rev-parse", "HEAD^{tree}"):
+            return "", ()
+        return run("commit-tree", tree, "-p", "HEAD", "-m", "rectifier: uncommitted changes"), untracked
+
+
+STATUS = {"A": "added", "M": "modified", "D": "deleted", "T": "changed"}
+"""How the list of uncommitted changes names each kind of change to a tracked file (`git diff --name-status`)."""
+
+
+@dataclass(frozen=True)
+class Sending:
+    """The files `--uncommitted` would send, for the user to see and agree to before anything is sent."""
+
+    tracked: tuple[tuple[str, str], ...]
+    """Each tracked file with a change, as its kind of change (`STATUS`) and its path."""
+    untracked: tuple[str, ...]
+    code: str
+    """Six characters of the temporary commit's tree, which is the files' contents: the same files give the same code,
+    and any change to one, or a file more, gives another (`--confirm`)."""
+
+
+def sending_of(repo: Path, selection: Selection, git: Git = _git) -> Sending:
+    """What a review of uncommitted changes sends: the files that differ from HEAD, tracked and untracked."""
+    rows = git(repo, "diff", "--name-status", "--no-renames", "-z", selection.on, selection.head,
+               errors="replace").split("\0")
+    untracked = set(selection.untracked)
+    tracked = tuple((STATUS.get(kind[:1], "changed"), path) for kind, path in zip(rows[::2], rows[1::2])
+                    if path and path not in untracked)
+    code = git(repo, "rev-parse", f"{selection.head}^{{tree}}").strip()[:6]
+    return Sending(tracked, tuple(sorted(untracked)), code)
+
+
+def uncommitted_left_out(repo: Path, git: Git = _git) -> bool:
+    """Whether the working tree has changes a review without `--uncommitted` leaves out, for the command to say so."""
+    return bool(git(repo, "status", "--porcelain", "--untracked-files=no").strip())
+
+
+def default_branch(repo: Path, git: Git = _git) -> str:
+    """The remote's default branch, such as `origin/main` or `origin/dev`, as git recorded it at clone time."""
+    try:
+        return git(repo, "symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD").strip()
+    except LocalError:
+        raise LocalError("cannot tell this repository's default branch. Run `git remote set-head origin --auto`, "
+                         "or pass --base <branch>") from None
+
+
+HOST = re.compile(r"[A-Za-z0-9][A-Za-z0-9.-]*")
+"""A host name, as an `origin` URL may name one: letters, digits, dots and dashes, starting with a letter or digit."""
+
+
+def origin(repo: Path, git: Git = _git) -> tuple[str, str]:
+    """The `origin` remote's host and repository path, such as `github.com` and `owner/name`. Both are empty when
+    there is no `origin` or its URL is not one of a forge."""
+    try:
+        url = git(repo, "remote", "get-url", "origin").strip()
+    except LocalError:
+        return "", ""
+    if "://" in url:
+        host, path = urlparse(url).hostname or "", urlparse(url).path
+    elif re.match(r"^[\w.-]+@[\w.-]+:", url):  # git@host:owner/name.git
+        host, path = url.split("@", 1)[1].split(":", 1)
+    else:
+        return "", ""
+    if not HOST.fullmatch(host):  # one that starts with `-` would reach `ssh -G` as an option (`ssh_hostname`)
+        return "", ""
+    return host, re.sub(r"\.git$", "", path.strip("/"))
+
+
+FORGES = {"github.com": "github", "ssh.github.com": "github", "gitlab.com": "gitlab", "altssh.gitlab.com": "gitlab"}
+"""The hosts an `origin` the service can review is on, by forge: github.com and gitlab.com, each with the host it also
+takes SSH on, over port 443."""
+
+
+def ssh_hostname(host: str) -> str:
+    """The host SSH connects to for `host`, from the user's SSH configuration: an alias such as `github-work` stands for
+    `github.com`. `host` itself when it is no alias, or when `ssh` cannot say."""
+    try:
+        said = subprocess.run(["ssh", "-G", "--", host], capture_output=True, text=True, timeout=10).stdout
+    except (OSError, subprocess.SubprocessError):
+        return host
+    return next((line.split(None, 1)[1].strip() for line in said.splitlines()
+                 if line.startswith("hostname ") and len(line.split(None, 1)) == 2), host)
+
+
+def forge_of(repo: Path, git: Git = _git, resolve: Callable[[str], str] = ssh_hostname) -> str:
+    """The forge `origin` is on, `github` or `gitlab` (`FORGES`), with an SSH alias read as the host it stands for.
+    Raises for any other host, before anything is sent: the service would refuse it, and say so less plainly."""
+    named, _ = origin(repo, git)
+    if not named:
+        try:
+            url = git(repo, "remote", "get-url", "origin").strip()
+        except LocalError:
+            raise LocalError("this checkout has no `origin` remote, so its repository is unknown") from None
+        raise LocalError(f"origin is {url}, which is neither GitHub (github.com) nor GitLab (gitlab.com); rectifier "
+                         f"reviews repositories on those two")
+    host = named.lower() if named.lower() in FORGES else resolve(named).lower()
+    if host not in FORGES:
+        where = f"{named}," if host == named.lower() else f"{named}, which your SSH configuration points at {host},"
+        raise LocalError(f"origin is on {where} which is neither GitHub (github.com) nor GitLab (gitlab.com); "
+                         f"rectifier reviews repositories on those two")
+    return FORGES[host]
+
+
+def repo_name(repo: Path, git: Git = _git) -> str:
+    """The repository's `owner/name`, or `group/sub/name` on GitLab, read from the `origin` URL. A checkout with no
+    usable remote is `local/<directory>`."""
+    _, path = origin(repo, git)
+    if "/" in path:
+        return path
+    top = Path(git(repo, "rev-parse", "--show-toplevel").strip())
+    return f"local/{top.name}"
+
+
+def under_review(scope: str, commits: int, base: str, head: str, branch: str = "", against: str = "") -> str:
+    """What is under review, in the report's words: "commit 3f9c2a1", "3 commits, 3f9c2a1..8d41e07", "branch feature, 3
+    commits against origin/main" or "uncommitted changes against 8d41e07 on branch feature". `commits` counts the
+    commits under review, which for uncommitted changes stop at HEAD."""
+    n, base, head = commits, base[:7], head[:7]
+    counted = f"{n} commit{'' if n == 1 else 's'}"
+    if scope == "branch":
+        return f"{'branch ' + branch if branch else 'HEAD'}, {counted} against {against}"
+    if scope == "uncommitted":
+        on = f" on branch {branch}" if branch else ""
+        return f"uncommitted changes and {counted} since {base}{on}" if n else f"uncommitted changes against {base}{on}"
+    if scope == "commit" or n == 1:
+        return f"commit {head}"
+    return f"{counted}, {base}..{head}"
+
+
+@dataclass(frozen=True)
+class Size:
+    """What the report says of the change before any finding: what it is, and how many files and lines it touches."""
+
+    under_review: str
+    files_changed: int
+    added: int
+    deleted: int
+
+
+def size_of(repo: Path, selection: Selection, git: Git = _git) -> Size:
+    """The selection's size, as `git diff --numstat` counts it, and what it is (`under_review`)."""
+    files = added = deleted = 0
+    for row in git(repo, "diff", "--numstat", selection.base, selection.head, errors="replace").splitlines():
+        plus, minus, _ = (row.split("\t", 2) + ["", "", ""])[:3]
+        files += 1
+        added += int(plus) if plus.isdigit() else 0
+        deleted += int(minus) if minus.isdigit() else 0
+    # The commits under review stop at HEAD for uncommitted changes: the temporary commit on top is not one of them.
+    last = selection.on or selection.head
+    commits = int(git(repo, "rev-list", "--count", f"{selection.base}..{last}").strip() or 0)
+    said = under_review(selection.scope, commits, selection.base, selection.head, selection.branch, selection.against)
+    return Size(said, files, added, deleted)

rectifier_client/cli.py

@@ -0,0 +1,32 @@
+#!/usr/bin/env python3
+"""`rectifier`, as the `imbik-rectifier` package installs it.
+
+  rectifier review --last 3     send changes in this checkout to be reviewed (`rectifier review --help`)
+  rectifier --version
+
+Docs: https://rectifier.imbik.ai/docs/
+"""
+
+from __future__ import annotations
+
+import sys
+
+from rectifier_client import __version__
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = sys.argv[1:] if argv is None else argv
+    if argv[:1] == ["review"]:
+        from rectifier_client import review
+
+        return review.main(argv[1:])
+    if argv[:1] in (["--version"], ["-V"]):
+        print(f"rectifier {__version__} (imbik-rectifier)")
+        return 0
+    asked = argv[:1] in (["-h"], ["--help"])
+    print(__doc__.strip(), file=sys.stdout if asked else sys.stderr)
+    return 0 if asked else 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

rectifier_client/report.py

@@ -0,0 +1,180 @@
+#!/usr/bin/env python3
+"""The review as `rectifier review` prints it and keeps it: the verdict, the counts, and each finding with its message
+for a coding agent, in markdown; a copy under `.rectifier/reviews/`; and the exit code.
+
+The service sends each finding ready to print: its text already rendered as a pull request comment shows it, whether it
+blocks by the account's blocking severity, the severity to show it at, why it is unconfirmed when no check confirmed
+it, and its message for an agent. It sends the verdict, and any note on how the review went, as sentences. This lays
+them out and decides none of it.
+"""
+
+from __future__ import annotations
+
+import itertools
+import json
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import Any, Mapping
+
+SAVED = Path(".rectifier") / "reviews"
+"""Where each review's markdown and JSON are kept, under the checkout's top level."""
+
+IGNORE = "*\n"
+"""What `.rectifier/.gitignore` holds: everything in the folder, the file itself included, so nothing there is ever
+committed and the repository's own `.gitignore` is left alone."""
+
+DEPTHS = {"light": "Lite", "deep": "Deep"}
+
+LIKELIHOODS = {"normal_use": "Normal use", "edge_case": "Edge case", "edge_case_rare": "Edge case"}
+"""How a finding's `likelihood` reads in the report."""
+
+RARE = "edge_case_rare"
+"""Rendered as an edge case with `rare` in front of its reason: `Edge case (rare: reason)`."""
+
+BACKTICKS = re.compile(r"`+")
+
+CONTROL = re.compile(r"[\x00-\x08\x0b-\x1f\x7f-\x9f]")
+"""Characters a terminal can take as commands rather than text, such as the escape that opens a sequence to write the
+clipboard or clear the screen. Newline and tab are not among them."""
+
+
+def visible(text: str) -> str:
+    """`text` as the report prints and keeps it: each control character (`CONTROL`) written out, as `\\x1b`, so a
+    terminal shows it rather than acting on it. A finding can quote a line of the repository's own files, which can hold
+    any byte. A Windows line ending is one newline."""
+    return CONTROL.sub(lambda c: f"\\x{ord(c.group(0)):02x}", text.replace("\r\n", "\n"))
+
+
+def why_not_a_review(produced: Mapping[str, Any]) -> str:
+    """Why the service says this run is not a review, or empty when it is one. A run that did not complete can still
+    have returned no findings, so the count alone never says the change is clean."""
+    return str((produced.get("meta") or {}).get("error") or "")
+
+
+def report(produced: dict[str, Any]) -> str:
+    """The review as markdown: the verdict, the counts, and each finding with its message for a coding agent."""
+    findings = produced.get("findings") or []
+    about = produced.get("review") or {}
+    depth = DEPTHS.get(about.get("depth") or "", "Configured")
+    first = (f"{_capital(about.get('under_review') or 'the change')}. {_count(about.get('files_changed', 0), 'file')}, "
+             f"+{about.get('added', 0)}/-{about.get('deleted', 0)}. {depth} review.")
+    meta = produced.get("meta") or {}
+    why = why_not_a_review(produced)
+    if why:
+        return visible("\n".join(["## Rectifier review: did not complete", "", f"{first} {why}"]))
+    counts = (f"{_count(len(findings), 'finding')}, {sum(bool(f.get('blocking')) for f in findings)} blocking."
+              if findings else "Nothing found.")
+    verdict = produced.get("verdict") or "Accept"
+    if partial := meta.get("partial"):
+        # The service's sentence on the part of the review that did not finish. The exit code stays the verdict's.
+        verdict += " (partial)"
+        counts += f"\n{partial}"
+    if said := about.get("environment_line"):
+        counts += f"\n{said}"
+    out = [f"## Rectifier review: {verdict}", "", f"{first} {counts}"]
+    for finding in findings:
+        out += ["", *_finding(finding, about)]
+    return visible("\n".join(out))
+
+
+def _finding(finding: dict[str, Any], about: dict[str, Any]) -> list[str]:
+    path, line = finding.get("file") or "", finding.get("line")
+    severity = finding.get("severity") or "Finding"
+    # No check confirmed it, so it blocks nothing: its heading says so, with what its reviewer rated it when the service
+    # shows it lower, as the post does, and why it is unconfirmed follows on a line of its own.
+    unconfirmed = finding.get("unconfirmed") or ""
+    if unconfirmed:
+        was = f"was {finding['lowered_from']}, " if finding.get("lowered_from") else ""
+        severity = f"{severity} ({was}not blocking)"
+    lines = [f"### {severity}: {finding.get('title') or ''}"]
+    if path:
+        lines.append(f"`{path}:{line}`" if line else f"`{path}`")
+    if unconfirmed:
+        lines += ["", f"{_capital(unconfirmed)}."]
+    lines += ["", (finding.get("body") or "").strip()]
+    if (finding.get("impact") or "").strip():
+        lines += ["", f"**Impact:** {finding['impact'].strip()}"]
+    likelihood = LIKELIHOODS.get(finding.get("likelihood") or "", finding.get("likelihood") or "")
+    if likelihood:
+        reason = (finding.get("likelihood_reason") or "").strip()
+        aside = ": ".join(filter(None, ["rare" if finding.get("likelihood") == RARE else "", reason]))
+        lines += ["", f"**Likelihood:** {likelihood}" + (f" ({aside})" if aside else "")]
+    if finding.get("agent_message"):
+        message = _agent_message(finding["agent_message"], about)
+        fence = "`" * max(3, 1 + max((len(run) for run in BACKTICKS.findall(message)), default=0))
+        lines += ["", "Message to fix with an agent:", "", f"{fence}text", message, fence]
+    return lines
+
+
+def _agent_message(message: str, about: dict[str, Any]) -> str:
+    """The service's message for a coding agent, with a line naming the repository and the commits in place of the
+    pull request line a posted comment has."""
+    task, _, rest = message.partition("\n\n")
+    at = "on top of commit" if about.get("uncommitted") else "reviewed at commit"
+    where = f"Repository: {about.get('repo')}, {about.get('under_review')}, {at} {about.get('head')}"
+    return f"{task}\n\n{where}\n{rest}"
+
+
+def kept(top: Path, text: str, produced: dict[str, Any]) -> Path | None:
+    """The report of this same review saved by an earlier run, or None. Run again, as with `--post` within the hour,
+    the command is handed the review it already has, and one review is kept once.
+
+    The same review is the same job with the same report. The service runs a new review under the same job when the
+    earlier one failed, or once its result is no longer kept, and that new report is saved on its own."""
+    about = produced.get("review") or {}
+    job, head = about.get("job") or "", (about.get("head") or produced.get("head_sha") or "")[:7]
+    if not job or not (top / SAVED).is_dir():
+        return None
+    for path in sorted((top / SAVED).glob(f"*-{head}*.json")):
+        try:
+            if ((json.loads(path.read_text()).get("review") or {}).get("job") == job
+                    and path.with_suffix(".md").read_text() == text + "\n"):
+                return path.with_suffix(".md")
+        except (OSError, ValueError):
+            continue
+    return None
+
+
+def save(top: Path, text: str, produced: dict[str, Any], now: datetime | None = None) -> Path:
+    """Keep the report and the JSON under `.rectifier/reviews/`, and return the report's path. The first save in a
+    checkout also writes `.rectifier/.gitignore`, so git never sees the folder."""
+    folder = top / SAVED.parent
+    folder.mkdir(exist_ok=True)
+    ignore = folder / ".gitignore"
+    if not ignore.exists():
+        ignore.write_text(IGNORE)
+    reviews = top / SAVED
+    reviews.mkdir(exist_ok=True)
+    about = produced.get("review") or {}
+    head = about.get("head") or produced.get("head_sha") or ""
+    name = (f"{(now or datetime.now()).strftime('%Y-%m-%d-%H%M%S')}-{head[:7]}"
+            + ("-uncommitted" if about.get("uncommitted") else ""))
+    # Two reviews of the same head can end in the same second, from two terminals: the markdown file is created only
+    # if its name is free, and a taken name gets -2, -3 and so on, so one review never overwrites another.
+    for n in itertools.count(1):
+        stem = reviews / (name if n == 1 else f"{name}-{n}")
+        try:
+            with stem.with_suffix(".md").open("x") as kept:
+                kept.write(text + "\n")
+            break
+        except FileExistsError:
+            continue
+    stem.with_suffix(".json").write_text(json.dumps(produced, indent=1) + "\n")
+    return stem.with_suffix(".md")
+
+
+def exit_code(produced: dict[str, Any]) -> int:
+    """0 when nothing found is blocking, 1 when something is, 2 when the review did not complete. Which findings
+    block is the service's to say."""
+    if why_not_a_review(produced):
+        return 2
+    return 1 if any(f.get("blocking") for f in produced.get("findings") or []) else 0
+
+
+def _count(n: int, noun: str) -> str:
+    return f"{n} {noun}{'' if n == 1 else 's'}"
+
+
+def _capital(text: str) -> str:
+    return text[:1].upper() + text[1:]

rectifier_client/review.py

@@ -0,0 +1,517 @@
+#!/usr/bin/env python3
+"""`rectifier review`: send changes in a local checkout to the reviewer service, and print what it found. `HELP` is
+what `rectifier review --help` prints.
+
+The review runs on the reviewer service, never here. The command sends the commits the forge does not have yet as a
+git bundle, so nothing needs pushing, waits for the review, and prints it as markdown that Claude Code can act on and
+a person can read. A review takes minutes, so Claude Code runs it in the background. Stopped, the review goes on, and
+the same command picks it up again, except with `--uncommitted`: its temporary commit is new on every run.
+
+A commit, the last N commits, a range and uncommitted changes get a lite review, and the whole branch the depth your
+account's rules give its pull requests; `--deep` and `--lite` change that. `--post` posts the review on the branch's
+open pull request, or merge request on GitLab, as a comment asking for a review would, when it has the reviewed
+commits.
+
+`--uncommitted` lists the files it would send, tracked and untracked, and asks before sending them. With no terminal to
+ask in, as when Claude Code runs it, it sends nothing and gives a code: the same command with `--confirm <code>`, run
+once the user agrees, sends exactly those files, and stops again if any of them changed.
+
+`RECTIFIER_URL` points the command at another reviewer service, such as a local one for testing.
+"""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import os
+import secrets
+import shlex
+import subprocess
+import sys
+import tempfile
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+from typing import Any, Callable
+from urllib.parse import urlparse
+
+from rectifier_client import __version__, change, report
+from rectifier_client.change import LocalError
+
+HELP = """\
+Send changes in this checkout to rectifier, and print the review.
+
+  rectifier review                         the branch, against where it left the default branch
+  rectifier review abc123                  one commit, against its first parent
+  rectifier review --last 3                the last 3 commits, as one change
+  rectifier review main..feature           a range, as one change
+  rectifier review --uncommitted           the uncommitted changes, against HEAD
+  rectifier review --uncommitted --base X  the uncommitted changes and the commits since X
+
+Each run reviews what you name again: plain `rectifier review` reads the whole
+branch every time. Use --last or a range to review only new commits.
+
+A review runs on rectifier's service and takes a few minutes. Ctrl-C stops the
+wait, not the review; run the same command to pick it up (with --uncommitted,
+it starts a new review). The review prints to stdout, and a copy goes to
+.rectifier/reviews/.
+
+Exit codes: 0 nothing blocks, 1 a finding blocks, 2 the review did not run or
+did not finish, 3 --uncommitted is waiting for you to agree to its files,
+130 stopped with Ctrl-C.
+
+Set RECTIFIER_CLI_TOKEN to a token from the dashboard's CLI tokens page.
+Docs: https://rectifier.imbik.ai/docs/?page=cli
+"""
+
+DEFAULT_URL = "https://rectifier-api.imbik.ai"
+PATH = "/api/cli/reviews"
+POLL = 10.0
+"""Seconds between asks while the review waits or runs."""
+
+WAIT_FOR = 2 * 3600.0
+"""Seconds the command waits for a review before it stops waiting, well past the longest review. The review goes on, and
+the same command picks it up."""
+
+RETRY_FOR = 120.0
+"""Seconds the wait keeps asking a service it cannot reach, a laptop waking or the service restarting, before it gives
+up. The review goes on either way."""
+
+REFS = "refs/rectifier/review-"
+"""Where each run makes the ref its bundle carries the head under, `<REFS><pid>-<random>`, deleted after the bundle. One
+per run, so two runs at once in one repository, or in its worktrees, which share these refs, never bundle or delete
+each other's."""
+
+
+def bundle_of(top: Path, head: str, git: change.Git = change._git) -> bytes:
+    """The commits up to `head` that no `origin/*` branch has, as a git bundle; empty when there are none.
+
+    Only `origin`'s: the review reads the forge `origin` is on, so a commit only another remote has (a colleague's
+    fork) must be uploaded. `git bundle` takes refs, not shas, so the head goes under a ref of this run's own."""
+    # With none of origin's branches, nothing would be left out, and a one-commit review would upload the whole history.
+    if not git(top, "for-each-ref", "--count=1", "refs/remotes/origin").strip():
+        raise LocalError("this checkout has none of origin's branches, so the whole history would be uploaded. Run "
+                         "`git fetch origin`, then run `rectifier review` again")
+    if git(top, "rev-list", "--count", head, "--not", "--remotes=origin").strip() == "0":
+        return b""  # the forge already has every commit
+    ref = f"{REFS}{os.getpid()}-{secrets.token_hex(4)}"
+    git(top, "update-ref", ref, head)
+    try:
+        with tempfile.TemporaryDirectory(prefix="rectifier-bundle-") as scratch:
+            path = Path(scratch) / "review.bundle"
+            made = subprocess.run(["git", "-C", str(top), "bundle", "create", "-q", str(path), ref, "--not",
+                                   "--remotes=origin"], capture_output=True, text=True, timeout=600)
+            if made.returncode != 0:
+                raise LocalError(f"git bundle failed: {made.stderr.strip()[:200]}")
+            return path.read_bytes()
+    finally:
+        git(top, "update-ref", "-d", ref)
+
+
+def request_of(top: Path, selection: change.Selection, depth: str, post: bool,
+               git: change.Git = change._git, command: str = "") -> dict[str, Any]:
+    """What the service is asked: which commits, from where, and the commits it may not have."""
+    try:
+        upstream = git(top, "rev-parse", "--abbrev-ref", "--symbolic-full-name", "@{upstream}").strip()
+    except LocalError:
+        upstream = ""
+    # Where origin is first: a missing or non-forge origin is refused for that, before any advice about its branches.
+    forge, repo = change.forge_of(top, git), change.repo_name(top, git)
+    bundle = bundle_of(top, selection.head, git)
+    return {"forge": forge, "repo": repo, "scope": selection.scope,
+            "base": selection.base, "head": selection.head, "on": selection.on, "branch": selection.branch,
+            "against": selection.against, "upstream": upstream, "depth": depth, "post": post,
+            "cli_version": __version__, "command": command, "bundle": base64.b64encode(bundle).decode()}
+
+
+def agreed(sending: change.Sending, a: argparse.Namespace, url: str, on: str,
+           ask: Callable[[str], str | None]) -> bool:
+    """Whether the user agreed to send these files: by a `--confirm` code that still names them, or by answering yes in
+    the terminal. Says on stderr what it lists, and what to do when it stops."""
+    if a.confirm and a.confirm == sending.code:
+        return True
+    print(files_sent(sending, url, on), file=sys.stderr)
+    if a.confirm:
+        print(f"\nThese files changed since code {a.confirm} was given.", file=sys.stderr)
+    elif (answer := ask("\nSend these files for review? [y/N] ")) is not None:
+        if answer.lower() in ("y", "yes"):
+            return True
+        print("Nothing was sent.", file=sys.stderr)
+        return False
+    # With the checkout it was run on: pasted where it was printed, it reviews the same one.
+    where = ["-C", a.repo] if a.repo != "." else []
+    again = shlex.join([*shlex.split(command_of(a)), *where, "--confirm", sending.code])
+    print(f"\nNothing was sent. To send exactly these files, run: {again}", file=sys.stderr)
+    return False
+
+
+def command_of(a: argparse.Namespace) -> str:
+    """The command as a posted review names it, in its "Requested with" line: what it was asked to review and how,
+    without `-C` and `--json`, which only change what happens on this machine."""
+    words = ["rectifier", "review", *([a.target] if a.target else []), *(["--last", str(a.last)] if a.last else []),
+             *(["--uncommitted"] if a.uncommitted else []), *(["--base", a.base] if a.base else []),
+             *({"deep": ["--deep"], "light": ["--lite"]}.get(a.depth or "", [])), *(["--post"] if a.post else [])]
+    return shlex.join(words)
+
+
+class Unreachable(LocalError):
+    """The service did not answer: no connection, a timeout, or a proxy in front of it answering for it. Asking again
+    later can work."""
+
+
+class Gone(LocalError):
+    """The service knows no such review (404)."""
+
+
+class TooLarge(LocalError):
+    """A proxy in front of the service refused the request's size (413)."""
+
+
+AGAIN = (502, 503, 504)
+"""What a proxy in front of the service answers while the service restarts or is down: worth asking again."""
+
+
+LOCAL = ("localhost", "127.0.0.1", "::1")
+"""The hosts `RECTIFIER_URL` may name over plain http: this machine, which the token never leaves."""
+
+
+def checked_url(url: str) -> str:
+    """`RECTIFIER_URL`, refused unless it is https, or plain http to this machine (`LOCAL`), since every request carries
+    the token. A name that only starts like a local one, such as `localhost.example.com`, is not local."""
+    parsed = urlparse(url)
+    if parsed.scheme == "https" and parsed.hostname:
+        return url
+    if parsed.scheme == "http" and parsed.hostname in LOCAL:
+        return url
+    raise LocalError(f"RECTIFIER_URL is {url}, which is not https: the token would go unencrypted. Use an https "
+                     f"address, or http only for a service on this machine (localhost or 127.0.0.1)")
+
+
+class Reply:
+    """An HTTP answer, as `Service` reads one: its status, its body, and where a redirect pointed."""
+
+    def __init__(self, status_code: int, content: bytes, location: str = ""):
+        self.status_code, self.content, self.location = status_code, content, location
+
+    def json(self) -> Any:
+        return json.loads(self.content)
+
+
+def _encoded(said: Any) -> bytes:
+    return json.dumps(said).encode()
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """Follows no redirect. `urllib` would send the request's headers, the token among them, to whatever host a redirect
+    names; the service never redirects, so a redirect is answered as it came (`Service._call`)."""
+
+    def redirect_request(self, *args: Any, **kw: Any) -> None:
+        return None
+
+
+_OPENER = urllib.request.build_opener(_NoRedirect)
+
+_LOCAL_OPENER = urllib.request.build_opener(_NoRedirect, urllib.request.ProxyHandler({}))
+"""For a service on this machine (`LOCAL`), no proxy either: plain http is allowed there only because the request does
+not leave the machine, and a proxy that `http_proxy` names would take it, token and upload, elsewhere unencrypted."""
+
+
+class Http:
+    """HTTP from the standard library, so the command installs with nothing beside it. An answer that is not 2xx is a
+    `Reply` like any other: what it says is the service's reason, or a proxy's page. A redirect is not followed."""
+
+    def request(self, method: str, url: str, headers: dict[str, str] | None = None, timeout: float = 300,
+                json: Any = None) -> Reply:
+        body = None if json is None else _encoded(json)
+        sent = urllib.request.Request(url, data=body, method=method,
+                                      headers={**(headers or {}), "user-agent": f"imbik-rectifier/{__version__}",
+                                               **({"content-type": "application/json"} if body is not None else {})})
+        try:
+            opener = _LOCAL_OPENER if urlparse(url).hostname in LOCAL else _OPENER
+            with opener.open(sent, timeout=timeout) as answer:
+                return Reply(answer.status, answer.read())
+        except urllib.error.HTTPError as answer:
+            return Reply(answer.code, answer.read(), answer.headers.get("location") or "")
+
+
+class Service:
+    """The reviewer service's CLI endpoints, with the user's token."""
+
+    def __init__(self, url: str, token: str, http: Any = None):
+        self.url, self.token, self.http = url.rstrip("/"), token, http or Http()
+
+    def _call(self, method: str, path: str, **kw: Any) -> dict[str, Any]:
+        try:
+            reply = self.http.request(method, self.url + path, headers={"authorization": f"Bearer {self.token}"},
+                                      timeout=300, **kw)
+        except Exception as trouble:  # noqa: BLE001  the network, said in the command's words
+            raise Unreachable(f"cannot reach the reviewer service at {self.url}: {trouble}") from trouble
+        try:
+            said = reply.json() if reply.content else {}
+        except ValueError:
+            # Not the service's own answer: a proxy in front of it refused the request (a bundle too large, say)
+            # or found the service down, and answered with a page of its own.
+            said = {}
+        if reply.status_code == 401:
+            raise LocalError(f"RECTIFIER_CLI_TOKEN was refused ({said.get('error')}). Make a new token on the dashboard's "
+                             f"CLI tokens page")
+        if reply.status_code == 404:
+            raise Gone(said.get("error") or "the reviewer service knows no such review")
+        if reply.status_code == 413:
+            raise TooLarge("the request is larger than the reviewer service takes")
+        if 300 <= reply.status_code < 400:
+            to = getattr(reply, "location", "") or "another address"
+            raise LocalError(f"the reviewer service at {self.url} answered {reply.status_code}, a redirect to {to}. "
+                             f"rectifier review does not follow redirects, so the token was not sent there. Check "
+                             f"RECTIFIER_URL")
+        if reply.status_code in AGAIN or (reply.status_code != 200 and not said):
+            why = f": {said['error']}" if said.get("error") else ""
+            raise Unreachable(f"the reviewer service at {self.url} answered {reply.status_code}{why}")
+        if reply.status_code != 200:
+            raise LocalError(said.get("error") or f"the reviewer service answered {reply.status_code}")
+        if not said:
+            raise LocalError("the reviewer service's answer was not one it gives")
+        return said
+
+    def submit(self, request: dict[str, Any]) -> dict[str, Any]:
+        """Never asked twice: with `--uncommitted`, a second ask is a second review."""
+        try:
+            return self._call("POST", PATH, json=request)
+        except TooLarge:
+            size = len(request.get("bundle") or "") * 3 / 4 / 1e6  # base64 is 4 characters for every 3 bytes
+            raise LocalError(f"the upload ({size:.0f} MB of commits the forge does not have) is larger than the "
+                             f"reviewer service takes. Push the commits, then run the command again: commits the "
+                             f"forge has are not uploaded") from None
+
+    def status(self, job: str) -> dict[str, Any]:
+        return self._call("GET", f"{PATH}/{job}")
+
+
+class LostContact(LocalError):
+    """The wait stopped: it could not reach the service for `RETRY_FOR` seconds, or the review had not ended after
+    `WAIT_FOR`. The review goes on."""
+
+
+def wait(service: Service, job: str, sleep: Callable[[float], None] = time.sleep) -> dict[str, Any]:
+    """Ask until the review has ended, saying on stderr where it is when that changes. Returns its result.
+
+    A service it cannot reach is asked again, at growing gaps, for up to `RETRY_FOR` seconds: a laptop that wakes
+    takes a moment to reconnect, and a deploy restarts the service. Asking again cannot change a refused token, so that
+    ends the wait at once. A review the service no longer knows ended more than an hour ago, while this command was
+    stopped or asleep, and its result is gone."""
+    said_last, lost, waited = "", 0.0, 0.0
+    while True:
+        if waited >= WAIT_FOR:
+            raise LostContact(f"review {job} has not ended after {WAIT_FOR / 3600:.0f} hours")
+        try:
+            said = service.status(job)
+        except Unreachable as trouble:
+            if lost >= RETRY_FOR:
+                raise LostContact(str(trouble)) from trouble
+            if not lost:
+                print(f"lost contact with the reviewer service; trying again for up to {RETRY_FOR / 60:.0f} minutes "
+                      f"(review {job} goes on)", file=sys.stderr, flush=True)
+            gap = min(max(POLL, lost), RETRY_FOR - lost)
+            sleep(gap)
+            lost, waited = lost + gap, waited + gap
+            continue
+        except Gone:
+            raise LocalError(f"review {job} ended more than an hour ago, and its result is deleted; run the command "
+                             f"again for a new review") from None
+        if lost:
+            print("reached the reviewer service again", file=sys.stderr, flush=True)
+            lost = 0.0
+        if said["state"] in ("done", "failed"):
+            return said["result"]
+        where = (f"waiting, {said.get('position', 0)} ahead" if said["state"] == "pending" and said.get("position")
+                 else "waiting" if said["state"] == "pending" else "running")
+        if where != said_last:
+            print(f"review {job}: {where}", file=sys.stderr, flush=True)
+            said_last = where
+        sleep(POLL)
+        waited += POLL
+
+
+NEEDS_OK = 3
+"""The exit code when `--uncommitted` stopped for the user to agree to the files it sends."""
+
+
+def ask_in_terminal(question: str) -> str | None:
+    """The user's answer, read where they typed the command; None when it was not typed in a terminal."""
+    if not sys.stdin.isatty():
+        return None
+    print(question, end="", file=sys.stderr, flush=True)
+    return sys.stdin.readline().strip()
+
+
+def files_sent(sending: change.Sending, url: str, on: str) -> str:
+    """The files `--uncommitted` sends, and where, as the user sees them before agreeing."""
+    out = [f"rectifier review --uncommitted sends these files to rectifier's review service at {url},",
+           f"on top of commit {on[:7]}, to be reviewed. The service deletes them after the review ends."]
+    if sending.tracked:
+        out += ["", f"Tracked files with changes ({len(sending.tracked)}):",
+                *(f"  {kind:<9} {path}" for kind, path in sending.tracked)]
+    if sending.untracked:
+        out += ["", f"Untracked files ({len(sending.untracked)}):", *(f"  {path}" for path in sending.untracked)]
+    return report.visible("\n".join(out))
+
+
+class PipeSafe:
+    """A stream that takes no more writes once its reader has gone, as with `| head` or `2>&1 | head`, so a closed pipe
+    never ends the command: the report is saved and the exit code is the review's all the same."""
+
+    def __init__(self, stream: Any):
+        self.stream, self.gone = stream, False
+
+    def write(self, text: str) -> int:
+        if not self.gone:
+            try:
+                return self.stream.write(text)
+            except BrokenPipeError:
+                self._gone()
+        return len(text)
+
+    def flush(self) -> None:
+        if not self.gone:
+            try:
+                self.stream.flush()
+            except BrokenPipeError:
+                self._gone()
+
+    def _gone(self) -> None:
+        """Point the stream's descriptor at nowhere, so what is left in its buffer, flushed when Python exits, fails
+        neither."""
+        self.gone = True
+        try:
+            nowhere = os.open(os.devnull, os.O_WRONLY)
+        except OSError:
+            return
+        try:
+            os.dup2(nowhere, self.stream.fileno())
+        except (OSError, ValueError, AttributeError):
+            pass
+        finally:
+            os.close(nowhere)
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(self.stream, name)
+
+
+def main(argv: list[str] | None = None, http: Any = None, sleep: Callable[[float], None] = time.sleep,
+         git: change.Git = change._git, ask: Callable[[str], str | None] = ask_in_terminal) -> int:
+    out, err = sys.stdout, sys.stderr
+    sys.stdout, sys.stderr = PipeSafe(out), PipeSafe(err)
+    try:
+        return _main(argv, http, sleep, git, ask)
+    except Exception as error:  # noqa: BLE001  exit 1 means a blocking finding, so nothing else may end in it
+        print(f"rectifier review: {type(error).__name__}: {error}", file=sys.stderr)
+        return 2
+    finally:
+        sys.stdout, sys.stderr = out, err
+
+
+def _main(argv: list[str] | None, http: Any, sleep: Callable[[float], None], git: change.Git,
+          ask: Callable[[str], str | None]) -> int:
+    ap = argparse.ArgumentParser(prog="rectifier review", description=HELP,
+                                 formatter_class=argparse.RawDescriptionHelpFormatter)
+    # One of the first group picks what is reviewed, and `change.select` refuses two; the second group goes with any.
+    pick = ap.add_argument_group("what to review (pick one; with none, the whole branch)")
+    pick.add_argument("target", nargs="?", metavar="COMMITS", help="one commit (abc123) or a range (main..feature)")
+    pick.add_argument("--last", type=int, metavar="N", help="the last N commits on this branch, as one change")
+    pick.add_argument("--uncommitted", action="store_true", help="the uncommitted changes, untracked files included")
+    pick.add_argument("--base", metavar="REF", help="with no choice or --uncommitted: compare against REF instead of "
+                                                    "the default branch")
+    how = ap.add_argument_group("how to review")
+    depth = how.add_mutually_exclusive_group()
+    depth.add_argument("--deep", dest="depth", action="store_const", const="deep", help="a deep review")
+    depth.add_argument("--lite", dest="depth", action="store_const", const="light", help="a lite review")
+    how.add_argument("--post", action="store_true", help="post the review on the branch's open pull or merge request")
+    how.add_argument("--json", action="store_true", help="print the JSON instead of the markdown")
+    how.add_argument("-C", dest="repo", default=".", help="the checkout to review; default is this directory")
+    how.add_argument("--confirm", metavar="CODE", help="with --uncommitted, send the files an earlier run listed under "
+                                                      "this code, without asking")
+    a = ap.parse_args(argv)
+    token = os.environ.get("RECTIFIER_CLI_TOKEN", "")
+    if not token:
+        print("rectifier review: set RECTIFIER_CLI_TOKEN to a token from the dashboard's CLI tokens page", file=sys.stderr)
+        return 2
+    if a.post and a.uncommitted:
+        print("rectifier review: uncommitted changes are never posted; commit them, or leave out --post",
+              file=sys.stderr)
+        return 2
+    if a.confirm and not a.uncommitted:
+        print("rectifier review: --confirm goes with --uncommitted: it sends the uncommitted changes an earlier run "
+              "listed", file=sys.stderr)
+        return 2
+    try:
+        url = checked_url(os.environ.get("RECTIFIER_URL") or DEFAULT_URL)
+    except LocalError as error:
+        print(f"rectifier review: {error}", file=sys.stderr)
+        return 2
+    service = Service(url, token, http)
+    job = ""
+    again = "running the command again starts a new review" if a.uncommitted else "the same command picks it up"
+    try:
+        top = Path(git(Path(a.repo), "rev-parse", "--show-toplevel").strip())
+        selection = change.select(top, a.target, a.last, a.base, a.uncommitted, git)
+        if not a.uncommitted and change.uncommitted_left_out(top, git):
+            print("note: uncommitted changes are not reviewed; --uncommitted reviews them", file=sys.stderr)
+        for note in selection.notes:
+            print(f"note: {note}", file=sys.stderr)
+        if a.uncommitted and not agreed(change.sending_of(top, selection, git), a, service.url, selection.on, ask):
+            return NEEDS_OK
+        request = request_of(top, selection, a.depth or "", a.post, git, command_of(a))
+        size = change.size_of(top, selection, git)
+        print(f"sending {size.under_review} to {service.url}", file=sys.stderr, flush=True)
+        job = service.submit(request)["job"]
+        result = wait(service, job, sleep)
+    except LostContact as error:
+        print(f"rectifier review: {error}. Stopped waiting: review {job} goes on, and {again}", file=sys.stderr)
+        return 2
+    except LocalError as error:
+        print(f"rectifier review: {error}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        if job:
+            print(f"\nstopped waiting; review {job} goes on, and {again}", file=sys.stderr)
+        return 130
+    # Whether it was posted, said after the report, as the last thing the user reads. A review asked to be posted
+    # that was not is a warning.
+    told = []
+    if result.get("note"):
+        told.append(f"WARNING: review {result['note']}" if a.post else f"note: {result['note']}")
+    n = result.get("number")
+    named = f"merge request !{n}" if request["forge"] == "gitlab" else f"pull request #{n}"
+    if result.get("posted"):
+        told.append(f"posted on {named}")
+    elif a.post and not result.get("note") and result.get("state") == "done":
+        # Asked as it was ending, after the service had decided not to post: asked again, it posts this review.
+        told.append(f"WARNING: review not posted: --post came as the review was ending. To post it, run "
+                    f"`{command_of(a)}` again")
+    elif n and not a.post and not selection.on and result.get("state") == "done":
+        # Asked again with --post, the service posts this review rather than running another.
+        told.append(f"note: not posted: to post this review on {named}, run the same command with --post within an "
+                    f"hour")
+    produced = result.get("produced") or {"findings": [], "meta": {}}
+    if result.get("state") == "failed":
+        # Whatever the review made, it did not end as one (a post that failed, say): the report and the exit code say so.
+        produced.setdefault("meta", {})["error"] = result.get("error") or "the review did not complete"
+    produced["review"] = {"under_review": size.under_review, "base": selection.base,
+                          "head": selection.on or selection.head, "uncommitted": bool(selection.on),
+                          "repo": request["repo"], "job": job, "depth": produced.get("depth") or "",
+                          "number": result.get("number"), "files_changed": size.files_changed, "added": size.added,
+                          "deleted": size.deleted, "environment_line": result.get("environment_line") or ""}
+    text = report.report(produced)
+    before = report.kept(top, text, produced)
+    saved = before or report.save(top, text, produced)
+    print(json.dumps(produced, indent=1) if a.json else text, flush=True)
+    print(f"{'already saved' if before else 'saved'}: {saved.relative_to(top)} and .json", file=sys.stderr)
+    for line in told:
+        print(line, file=sys.stderr)
+    return report.exit_code(produced)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())