diff --git a/.github/fork-ci-tests.txt b/.github/fork-ci-tests.txt index 1f985f61b6ede..75f319b1f471a 100644 --- a/.github/fork-ci-tests.txt +++ b/.github/fork-ci-tests.txt @@ -20,6 +20,7 @@ .github/scripts/fork-workflow-triggers.test.cjs fork-ci/actions/docs-scope/docs-scope.test.py fork-ci/actions/gradle-cache/gradle_cache.test.py +fork-ci/actions/head-check/head_check.test.py fork-ci/actions/job-changed/job-changed.test.py fork-ci/actions/pr-queue/lens.test.py fork-ci/actions/pr-queue/pr_queue.test.py diff --git a/fork-ci/actions/head-check/README.md b/fork-ci/actions/head-check/README.md new file mode 100644 index 0000000000000..51ded5238881d --- /dev/null +++ b/fork-ci/actions/head-check/README.md @@ -0,0 +1,188 @@ +# head-check + +A composite action that answers one question for a pull request: **is its head +the change the review read?** It is the required `head_check` of the merge +queue ([pr-queue](../pr-queue/README.md)), with the queue's own rules. + +The queue re-arms auto-merge only for a head that holds exactly the change the +lenses read, but it only touches pull requests that are behind their base. A +plain push to an armed pull request that is already up to date would merge +unread. This check, required by the branch ruleset, fails that head. + +## The rules + +All of them are the queue's, imported from `../pr-queue`, never copied: + +- **The review** (`lens.py`, `Review.reviewed_head` and `Review.lens_reads`): + the one full 40-hex sha every lens's newest comment read, or a newer + override comment's sha. Only comments and reviews by the config's + `lens_author_associations` count, and bots never do. A lens comment edited + after posting or hidden (minimized), a short sha, and a comment that only + looks like a lens report read nothing. The pr-queue README, section "Lens + comments", has the full grammar. +- **One lens name, one read:** each lens name counts once, by its newest + comment, whoever posted it. If two reviewers post under the same name, the + newer one wins: the check can pass on a head only the second one read. Two + independent reviews of one angle need two different names (`correctness` + and `correctness-2`, say), each in `required-lenses`. +- **Bots:** a login in the config's `bot_logins`, a login ending in `[bot]`, + or an author of type Bot. `gh` gives only the login, without `[bot]` + (`coderabbitai`, not `coderabbitai[bot]`), so list every bot that comments + in `bot_logins`. Bots usually have no lens author association either. +- **The same change** (`pr_queue.holds`): the head is the commit read, or the + base merged into it cleanly, byte for byte (a queue update, up to three in a + row). A push after the review, a conflict resolution or an extra change in a + merge is not the same change. +- **The config** is the queue's own JSON file (`config.py`). It is read from + the base commit that the run's merge commit tests, never from the pull + request's copy, so a pull request cannot change whose comments count for its + own check. + +It passes when: + +- every lens read the head, or a newer override vouches for it, and every + required lens (`required-lenses`) is among them; +- the pull request has no lens comments and no lens is required: there is + nothing to compare (the queue then vouches only for the head it found); +- it is a draft and `pass-drafts` is `true`. + +It fails (exit 1), never passes, when anything is unknown: GitHub cannot be +read after three tries, its answer is malformed, the checkout's merge commit +merges another head than the one GitHub reports (a newer push has its own +run), or the read commit is not in the checkout and cannot be fetched (GitHub +no longer has it, or the checkout kept no credentials: see Usage). + +It refuses to start (exit 2, before it reads GitHub, every reason at once) on +a config error (also a base commit without the config), a missing pull +request number (not a `pull_request` event), a lens name in `required-lenses` +that names no lens, a git older than 2.38, a checkout that is not GitHub's +two-parent merge commit, a checkout that is shallow, or a checkout holding a +file that changes what git's objects or merges say (`info/grafts`, `shallow`, +alternates, `info/attributes`). A refusal is a red required check too. git +runs with no hooks, no fsmonitor, no replace refs and no attributes: the pull +request's `.gitattributes` cannot turn a conflict into a clean merge. + +It reads only and posts nothing. The one write is a fetch, into the job's own +checkout, of a read commit the head dropped (a rebase or force-push; GitHub +keeps it, and the queue fetches it the same way). So a re-run on the same head +gives the same answer and adds nothing, and a run stopped half-way leaves +nothing behind. + +## Usage + +Run it in a job of its own, right after the checkout of the merge commit, and +make that job a required check (the config's `head_check`): + +```yaml +on: + pull_request: + # edited: a base change (a stacked pull request retargeted) runs it again + types: [opened, synchronize, reopened, ready_for_review, edited] +permissions: {} +jobs: + review-check: + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: read + steps: + - uses: actions/checkout@ # the default ref: on pull_request GitHub's merge commit + with: { fetch-depth: 0 } # the base's history is needed + - uses: scuttletoby/t3code/fork-ci/actions/head-check@ # ci/vN + with: + config: .github/pr-queue.json + # required-lenses: | # optional: lenses that must read the head + # correctness + # security + # pass-drafts: true # optional: with ready_for_review in the types above +``` + +The check reads the comments when it runs. After a lens or an override is +posted for the head, run it again (re-run the job, or let a tool the project +uses for its ready command do that); a new push runs it anyway. The `edited` +trigger runs it again when the base branch changes: the answer depends on the +base (its config, and which merged-in commits are the base's). A title or body +edit also runs it; it only reads, so that costs one short job. + +**Pin it by the release sha, always.** Use the full sha a `ci/vN` release +names (the release sha of ci/vN), never a branch, a tag alone or a local path +(`uses: ./fork-ci/actions/head-check`), not even inside the repository that +holds the action. With a local path a pull request runs its own copy of +`head_check.py` and `lens.py` and can weaken the rules without touching +`.github/`. (This repository runs no head check of its own; its reusable queue +workflow checks out the queue at its own workflow commit and never runs for a +pull request.) + +**Drafts:** with `pass-drafts: true` a draft's check is green without a read. +When the draft is marked ready, that old green result still counts for a few +seconds, until the `ready_for_review` run starts. Arm auto-merge (or merge) +only after this check's `ready_for_review` run has finished on that head, or +keep `pass-drafts` false. + +**Credentials:** a read commit the head dropped (a rebase or force-push) is +fetched from `origin` with the credentials actions/checkout stored. With +`persist-credentials: false` on a private repository that fetch fails, and so +does the check (it never passes on it). + +No step before it may run the pull request's code: that code could change the +checkout the check reads. + +**What it does not stop.** A pull request can change the workflow file itself +(a `pull_request` run uses the merge commit's workflows). So this check stops +an unread push, not an author who rewrites the check. On a repository owned +by a user account, anyone who can push a branch can rewrite this job, or add +another passing job with the required check's name. GitHub's "require +workflows to pass" ruleset rule would close that, but it is for organizations +on paid plans only, not for user-owned repositories. Until there is a better +way, a person reads every pull request that changes `.github/workflows/` or +this action's files. The real fix is future work: a `pull_request_target` job +that runs code pinned on the base branch, posts its result through a separate +GitHub App (its key in an environment only the base branch can use), and a +required check bound to that App as its only allowed source. Tracked in +[issue 34](https://github.com/scuttletoby/t3code/issues/34). + +### Inputs + +| Input | Default | Meaning | +| ----------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------- | +| `config` | (required) | the queue's JSON config, a path in the repository, read from the base commit | +| `required-lenses` | (empty) | lens names, one per line, that must be among the reads; matched as lens keys (case, `r2`) | +| `pass-drafts` | `false` | `true` passes a draft without reading its review; add `ready_for_review` to the workflow's triggers | +| `path` | `.` | where the merge commit is checked out | +| `pr` | `github.event.pull_request.number` | the pull request | +| `repo` | `github.repository` | owner/name | +| `token` | `github.token` | reads the pull request's comments and reviews (`pull-requests: read`) | + +`required-lenses` takes one lens name per line; blanks around a name and +empty lines are skipped. Never separate names with commas: a lens name may +hold one (`data-integrity (DI-1, DI-2)` is one name). A required lens is +matched by its lens key: the whole name, case and blanks normalised, minus a +trailing round marker (`Correctness r2` is `correctness`, `correctness (DI-1)` +is not). When a required name matches no counted lens comment, the check +fails and its reason, in the log and the summary, lists the lens names it +found, so a typo shows. Which lenses a pull request needs is the +project's to decide; a workflow can compute the list in an earlier step (from +labels or changed paths, say) and pass it in. + +### Outputs + +| Output | Value | +| -------- | ------------------------------------------------------ | +| `result` | `pass` or `fail`; empty when the step refused to start | + +The log and the job summary list each lens with `ok` or `fail` and a short +reason (the sha it read, an override, edited, hidden, a short sha, required +but missing). + +| Exit | Meaning | +| ---- | -------------------------------------------------------------------------------- | +| 0 | Pass. | +| 1 | Fail, also when GitHub or the checkout cannot say. | +| 2 | Refused to start (config, arguments, git or checkout); read nothing from GitHub. | + +## Tests + +`python3 fork-ci/actions/head-check/head_check.test.py`: real commits (a +local bare repository stands in for GitHub, the checkout is a merge commit as +GitHub makes it) and a fake `gh`; it fails the run if anything starts the real +`gh`. diff --git a/fork-ci/actions/head-check/action.yml b/fork-ci/actions/head-check/action.yml new file mode 100644 index 0000000000000..c651e35ca7beb --- /dev/null +++ b/fork-ci/actions/head-check/action.yml @@ -0,0 +1,60 @@ +name: pr-queue head check +description: >- + Fails a pull request head that is not the change its review read: the merge queue's head_check (pr-queue), with the + queue's own lens rules and config. Run it in a job of its own, right after the checkout of GitHub's merge commit + with fetch-depth 0, on pull_request events. Reads only and posts nothing. Needs git 2.38+, gh and python3. +inputs: + config: + description: The merge queue's JSON config (pr-queue README, "Config"), a path in the repository, read from the base commit. + required: true + required-lenses: + description: Lens names, one per line (a name may hold a comma), that must be among the reads (default none). + required: false + default: "" + pass-drafts: + description: true passes a draft without reading its review (run the check again on ready_for_review). + required: false + default: "false" + path: + description: Where the merge commit is checked out (actions/checkout's path). + required: false + default: "." + pr: + description: The pull request number. + required: false + default: ${{ github.event.pull_request.number }} + repo: + description: The repository, owner/name. + required: false + default: ${{ github.repository }} + token: + description: A token that can read the pull request's comments and reviews (pull-requests read). + required: false + default: ${{ github.token }} +outputs: + result: + description: pass or fail (empty when the step refused to start). + value: ${{ steps.check.outputs.result }} +runs: + using: composite + steps: + - id: check + name: The head is the change the review read + shell: bash + env: + GH_TOKEN: ${{ inputs.token }} + REPO: ${{ inputs.repo }} + PR: ${{ inputs.pr }} + CONFIG: ${{ inputs.config }} + CHECKOUT_PATH: ${{ inputs.path }} + REQUIRED_LENSES: ${{ inputs.required-lenses }} + PASS_DRAFTS: ${{ inputs.pass-drafts }} + run: | + args=(--repo "$REPO" --pr "$PR" --config "$CONFIG" --path "$CHECKOUT_PATH" + --required-lenses "$REQUIRED_LENSES") + case "$PASS_DRAFTS" in + true) args+=(--pass-drafts) ;; + false) ;; + *) echo "::error::head check: pass-drafts must be true or false"; exit 2 ;; + esac + exec python3 -I "$GITHUB_ACTION_PATH/head_check.py" "${args[@]}" diff --git a/fork-ci/actions/head-check/head_check.py b/fork-ci/actions/head-check/head_check.py new file mode 100644 index 0000000000000..ab97890cd31c9 --- /dev/null +++ b/fork-ci/actions/head-check/head_check.py @@ -0,0 +1,268 @@ +#!/usr/bin/env python3 +"""Is this pull request's head the change its review read? The pr-queue's `head_check` as a required check (README.md). + +The merge queue (../pr-queue) re-arms auto-merge only for a head that holds exactly the change the lenses read, but it +only touches pull requests that are behind their base. A plain push to an armed pull request that is already up to +date would merge unread; this check, required by the branch ruleset, fails that head. It reads the review with the +queue's own rules, imported, never copied: + - lens.Review.reviewed_head and lens_reads: the one full 40-hex sha every lens's newest read names, or a newer + override comment's. Only comments of the config's lens_author_associations count (bots never); an edited or + hidden lens comment, a short sha and a comment that only looks like a lens report read nothing. + - pr_queue.holds: the head is that commit, or a clean merge of the base into it, byte for byte (a queue update). +The config is the queue's own JSON file (config.py), read from the base commit, so the check and the queue read the +same people and override, and a pull request cannot change them for its own check. +`--required-lenses` (the project's, per pull request if it likes) adds lenses that must be among the reads. + +Pass: every lens read the head (or a newer override vouches for it), and every required lens is there; a pull +request with no lens comments and no required lens (nothing to compare); a draft, with --pass-drafts only. Fail, +never pass, when anything is unknown: GitHub unreadable after ATTEMPTS, a malformed answer, a checkout whose merge +commit merges another head than the one GitHub reports, a read commit that is not in the checkout and cannot be fetched. +Refuse to start (exit 2, before GitHub is read) on a config or argument error, a git older than 2.38, and a checkout +that is not GitHub's two-parent merge commit, is shallow or is tampered with. Reads only (a fetch of a missing read +commit into the job's own checkout aside) and posts nothing: a re-run on the same head gives the same answer, and a +run stopped half-way leaves nothing behind. +Exit codes: 0 pass, 1 fail, 2 refused to start (every reason printed at once). + head_check.py --repo OWNER/NAME --pr N --config FILE [--path DIR] [--required-lenses TEXT] [--pass-drafts] +`--required-lenses` takes one lens name per line (a name may hold a comma: `data-integrity (DI-1, DI-2)`). +""" +import argparse, json, os, re, subprocess, sys, tempfile, time + +sys.dont_write_bytecode = True # no __pycache__ next to the scripts +sys.path.insert(0, os.path.join(os.path.dirname(os.path.abspath(__file__)), '..', 'pr-queue')) +import config # noqa: E402 +import lens # noqa: E402 +import pr_queue # noqa: E402 + +ATTEMPTS, RETRY_SECONDS = 3, 10 +FIELDS = 'isDraft,headRefOid,comments,reviews' +SHA = pr_queue.SHA +REFUSED = pr_queue.REFUSED +# Every git call: the queue's safe flags (no hooks, fsmonitor, commit-graph or replace refs) and no attributes file. git +# runs in an empty folder with --git-dir, so the checkout's own .gitattributes (the pull request's) cannot change how +# merge-tree merges (merge=union would make a conflict "clean"). +GIT_SAFE = (*pr_queue.GIT_SAFE, '-c', 'core.attributesFile=/dev/null') + + +class Checkout: + """The job's checkout of GitHub's merge commit, read with git (`run` replaces git in tests).""" + + def __init__(self, path, run=None): + self.git_dir = os.path.join(os.path.abspath(path), '.git') + self.run = run + + def git(self, *a): + if self.run: + return self.run(*a) + with tempfile.TemporaryDirectory(prefix='head-check-') as empty: + return subprocess.run(['git', *GIT_SAFE, '--git-dir', self.git_dir, *a], cwd=empty, text=True, + capture_output=True, env={**os.environ, 'GIT_TERMINAL_PROMPT': '0', + 'GIT_ATTR_NOSYSTEM': '1'}) + + def problem(self): + """Why the checkout cannot be read as git made it, or None: not a .git folder, shallow (the base's history is + needed), or holding a file that changes what its objects or merges say (pr_queue.UNTRUSTED_FILES).""" + if not os.path.isdir(self.git_dir): + return f'{self.git_dir} is no git folder: check out the pull request first (actions/checkout)' + if os.path.lexists(os.path.join(self.git_dir, 'shallow')): + return 'the checkout is shallow: check it out with fetch-depth: 0' + bad = [f for f in pr_queue.UNTRUSTED_FILES if os.path.lexists(os.path.join(self.git_dir, f))] + return f'the checkout holds {", ".join(bad)}, which a checkout never writes' if bad else None + + def merge_parents(self): + """(base, head) of HEAD when it is a two-parent merge commit, else None.""" + r = self.git('rev-list', '--parents', '-n', '1', 'HEAD') + line = r.stdout.split() if r.returncode == 0 else [] + return (line[1], line[2]) if len(line) == 3 and all(SHA.fullmatch(s) for s in line) else None + + def has(self, sha): + return self.git('cat-file', '-e', sha + '^{commit}').returncode == 0 + + def fetch(self, sha): + """A read commit no ref of the checkout reaches (a force-push dropped it; GitHub keeps it), from origin with the + credentials actions/checkout stored (none with persist-credentials: false: a private repository then fails).""" + return self.git('fetch', '-q', '--no-tags', 'origin', sha).returncode == 0 and self.has(sha) + + +def required_names(text): + """{lens key: name as written} from one lens name per line, blank lines skipped; (keys, problems). Lines only, never + commas: a lens name may hold one (`data-integrity (DI-1, DI-2)`).""" + names, problems = {}, [] + for name in (n.strip() for n in (text or '').splitlines()): + if not name: + continue + if not lens.names_a_lens(name): + problems.append(f'required lens {name!r} names no lens (a placeholder, a round marker or nothing)') + else: + names.setdefault(lens.lens_key(name), name) + return names, problems + + +def well_formed(pr): + return isinstance(pr, dict) and isinstance(pr.get('isDraft'), bool) \ + and all(isinstance(pr.get(k), list) for k in ('comments', 'reviews')) + + +def read_pr(repo, n, gh, sleep): + """(the PR, None) or (None, why it could not be read), after ATTEMPTS tries.""" + why = '' + for attempt in range(ATTEMPTS): + if attempt: + sleep(RETRY_SECONDS) + r = gh('pr', 'view', str(n), '--repo', repo, '--json', FIELDS) + try: + pr = json.loads(r.stdout) if r.returncode == 0 else None + except ValueError: + pr = None + if well_formed(pr): + return pr, None + why = (r.stderr or r.stdout or '').strip()[:300] or 'gh gave no usable answer' + return None, why + + +def same_change(checkout, head, read): + """(True, how) when the checkout's merge commit merges `head` and head holds `read`'s change (pr_queue.holds), + else (False, why). Only the checkout's own commits and GitHub's (a fetch of a missing read) are looked at. cli + refuses a checkout that is no merge commit before this runs (base_config); the check here is for other callers.""" + parents = checkout.merge_parents() + if not parents: + return False, "HEAD is not GitHub's two-parent merge commit, so the pull request head is unknown" + base, merged = parents + if merged != head: + return False, (f'the checkout merges {merged[:12]} but GitHub says the head is {head[:12]}: ' + 'a newer head has its own run') + if head == read: + return True, f'{head[:12]} is the commit read' + if not (checkout.has(read) or checkout.fetch(read)): + return False, (f'the read commit {read[:12]} is not in the checkout and could not be fetched from origin ' + '(GitHub no longer has it, or the checkout kept no credentials: persist-credentials: false)') + if pr_queue.holds(checkout.git, head, read, pr_queue.UPDATES, base): + return True, f'{head[:12]} is {read[:12]} merged with the base, nothing else' + return False, f'{head[:12]} is not the change read at {read[:12]}, nor that change merged with the base' + + +def verdict(pr, review, checkout, required=None, pass_drafts=False): + """(ok, reason, rows): rows is [(lens, ok, short reason)] per lens, required ones first.""" + required = required or {} + head = str(pr.get('headRefOid') or '').lower() + if not SHA.fullmatch(head): + return False, 'GitHub names no head commit for the pull request', [] + if pr['isDraft'] and pass_drafts: + return True, 'a draft: checked again when it is marked ready for review', [] + reads = review.lens_reads(pr) + reviewed, read, why = review.reviewed_head(pr) + missing = [name for key, name in required.items() if key not in reads] + found = ', '.join(sorted(reads)) or 'none' + if not reads and not required: + return True, 'no lens comments and no required lens: nothing to compare', [] + ok, how = same_change(checkout, head, read) if reviewed and read else (False, None) + rows = [(name, False, f'required: no lens comment of a counted author has this name (lenses found: {found})') + for name in missing] + for key, (sha, gap, override) in sorted(reads.items()): + if not sha: + text = f'reads nothing: {gap}' + elif not read: + text = f'read {sha[:12]}; the lenses did not all read one head' + else: + text = f'{"override " if override else "read "}{sha[:12]}: {how}' + rows.append(((f'{key} (required)' if key in required else key), bool(sha and read and ok), text)) + if missing: + return False, (f'required lens without a read: {", ".join(missing)}. No counted lens comment has that name: ' + f'check it in required-lenses (one name per line); lenses found: {found}'), rows + if not read: + return False, why, rows + return ok, how, rows + + +def escape(text): + """One line for a workflow command (::error::) or the log: nothing in a comment can start a command.""" + return str(text).replace('%', '%25').replace('\r', '%0D').replace('\n', '%0A') + + +def cell(text): + return re.sub(r'[|<>`\r\n]', ' ', str(text)) + + +def report(ok, reason, rows, n, env, out=print): + """The log, the step summary (one table, appended) and the `result` output.""" + for name, good, text in rows: + out(f' {"ok " if good else "FAIL"} {escape(name)}: {escape(text)}') + out(f'#{n}: head check {"passed" if ok else "FAILED"}: {escape(reason)}' if ok else f'::error::#{n}: head check ' + f'failed: {escape(reason)}') + summary = env.get('GITHUB_STEP_SUMMARY') + if summary: + lines = [f'### Head check #{n}: {"pass" if ok else "fail"}', '', cell(reason), ''] + if rows: + lines += ['| lens | | reason |', '| --- | --- | --- |'] + lines += [f'| {cell(name)} | {"ok" if good else "fail"} | {cell(text)} |' for name, good, text in rows] + with open(summary, 'a', encoding='utf-8') as f: + f.write('\n'.join(lines) + '\n') + output = env.get('GITHUB_OUTPUT') + if output: + with open(output, 'a', encoding='utf-8') as f: + f.write(f'result={"pass" if ok else "fail"}\n') + + +def gh_run(*a): + return subprocess.run(['gh', *a], text=True, capture_output=True) + + +def cli(argv=None, env=None, gh=gh_run, sleep=time.sleep, git=None, out=print): + env = os.environ if env is None else env + p = argparse.ArgumentParser(prog='head_check.py', description=__doc__.split('\n')[0]) + p.add_argument('--repo', required=True, help='owner/name') + p.add_argument('--pr', required=True, help='the pull request number') + p.add_argument('--config', required=True, help="the merge queue's JSON config (../pr-queue/README.md, Config): a " + 'path in the repository, read from the base commit the merge commit tests') + p.add_argument('--path', default='.', help="the checkout of GitHub's merge commit (fetch-depth: 0)") + p.add_argument('--required-lenses', default='', help='lens names, one per line, that must read the head') + p.add_argument('--pass-drafts', action='store_true', help='pass a draft without reading its review') + a = p.parse_args(argv) + problems = [] + if not pr_queue.REPO_RE.fullmatch(a.repo): + problems.append(f'--repo {a.repo!r} is not owner/name') + if not re.fullmatch(r'[1-9][0-9]{0,9}', a.pr): + problems.append(f'--pr {a.pr!r} is not a pull request number (run it on a pull_request event)') + required, bad = required_names(a.required_lenses) + problems += bad + checkout = Checkout(a.path, git) + if git is None: + problems += filter(None, [pr_queue.git_problem(), checkout.problem()]) + cfg = None + if not problems: + cfg = base_config(checkout, a.config, problems) + if problems: + out('::error::head check refused to start: ' + escape('; '.join(problems))) + return REFUSED + pr, why = read_pr(a.repo, a.pr, gh, sleep) + if pr is None: + report(False, f'could not read the pull request from GitHub after {ATTEMPTS} tries: {why}', [], a.pr, env, out) + return 1 + review = lens.Review(cfg.bot_logins, cfg.override_prefix, cfg.override_association, cfg.lens_author_associations, + log=lambda text: out(escape(text))) + ok, reason, rows = verdict(pr, review, checkout, required, a.pass_drafts) + report(ok, reason, rows, a.pr, env, out) + return 0 if ok else 1 + + +def base_config(checkout, path, problems): + """The queue's config as the base commit holds it (the merge commit's first parent), never the pull request's own + copy: a pull request cannot widen whose comments count for its own check. None with a problem added.""" + parents = checkout.merge_parents() + if not parents: + problems.append("HEAD is not GitHub's two-parent merge commit (check out the pull_request event's default ref)") + return None + rel = path[2:] if path.startswith('./') else path + r = checkout.git('show', f'{parents[0]}:{rel}') + if r.returncode != 0: + problems.append(f'the base commit {parents[0][:12]} has no config {path}') + return None + try: + return config.parse(r.stdout, f'{path} at the base {parents[0][:12]}') + except config.ConfigError as e: + problems.append(str(e)) + return None + + +if __name__ == '__main__': + sys.stdout.reconfigure(line_buffering=True) + sys.exit(cli()) diff --git a/fork-ci/actions/head-check/head_check.test.py b/fork-ci/actions/head-check/head_check.test.py new file mode 100644 index 0000000000000..3b5447c2d98fd --- /dev/null +++ b/fork-ci/actions/head-check/head_check.test.py @@ -0,0 +1,682 @@ +"""Tests of head_check.py (run: python3 fork-ci/actions/head-check/head_check.test.py). + +The check fails a pull request head that is not the change its review read, with the merge queue's own rules +(../pr-queue: lens.py, pr_queue.holds, config.py). For each rule: what passes, what fails, and what a re-run, a stop +half-way or old or empty state does. + +Real commits in a temporary World: a local bare repository stands in for GitHub, the checkout is GitHub's merge commit +of the pull request, `gh` is a fake, and nothing here can reach the network or a real gh login (the guard below fails +the whole run if anything starts the real `gh`). +""" +import atexit, os, shlex, shutil, sys, tempfile + +# --- guard: first, before anything can start gh or git ------------------------------------------------------------ +sys.dont_write_bytecode = True # no __pycache__ next to the scripts +_GUARD = tempfile.mkdtemp(prefix='head-check-guard-') +_GH_RAN = os.path.join(_GUARD, 'gh-ran') +os.makedirs(os.path.join(_GUARD, 'bin')) +os.makedirs(os.path.join(_GUARD, 'gh-config')) +with open(os.path.join(_GUARD, 'bin', 'gh'), 'w') as _f: + _f.write(f'#!/bin/sh\necho "$*" >> {shlex.quote(_GH_RAN)}\n' + 'echo "head_check.test.py: a test started the real gh" >&2\nexit 97\n') +os.chmod(os.path.join(_GUARD, 'bin', 'gh'), 0o755) +os.environ['PATH'] = os.path.join(_GUARD, 'bin') + os.pathsep + os.environ.get('PATH', '') +for _k in ('GH_TOKEN', 'GITHUB_TOKEN', 'GH_ENTERPRISE_TOKEN', 'GITHUB_ENTERPRISE_TOKEN', 'GH_HOST', + 'GITHUB_STEP_SUMMARY', 'GITHUB_OUTPUT'): + os.environ.pop(_k, None) +os.environ.update(GH_CONFIG_DIR=os.path.join(_GUARD, 'gh-config'), GIT_ALLOW_PROTOCOL='file', + GIT_CONFIG_GLOBAL=os.devnull, GIT_CONFIG_NOSYSTEM='1', GIT_TERMINAL_PROMPT='0') + + +def _gh_never_ran(): + ran = None + if os.path.exists(_GH_RAN): + with open(_GH_RAN) as f: + ran = f.read() + shutil.rmtree(_GUARD, ignore_errors=True) + if ran is not None: + print(f'FAILED: a test started the real gh: {ran[:500]}', file=sys.stderr) + sys.stderr.flush() + os._exit(97) # unittest may have said OK: this exit code is the answer + + +atexit.register(_gh_never_ran) + +import json, subprocess, types, unittest, unittest.mock # noqa: E402 + +HERE = os.path.dirname(os.path.abspath(__file__)) +sys.path.insert(0, HERE) +import head_check as H # noqa: E402 +import config # noqa: E402 (../pr-queue, put on the path by head_check) +import lens # noqa: E402 + +REPO = 'owner/proj' +CONFIG_PATH = '.github/pr-queue.json' +CFG_RAW = { + 'required_checks': ['build', 'review-check'], 'merge_method': 'squash', 'delete_branch': True, + 'bot_logins': ['review-bot'], 'lens_author_associations': ['OWNER', 'COLLABORATOR'], + 'override': {'prefix': 'tool ready --head', 'author_association': 'OWNER'}, + 'ready_command': 'tool ready {pr}', 'push_command': 'tool push', 'lens_format_doc': 'docs/review.md', + 'head_check': 'review-check', +} +CFG = config.parse(json.dumps(CFG_RAW)) +LENS = 'lens' # built at run time: no line of this file starts with the lens marker +A, B, C = 'a1' * 20, 'b2' * 20, 'c3' * 20 +GIT_ENV = {'GIT_AUTHOR_NAME': 't', 'GIT_AUTHOR_EMAIL': 't@t', 'GIT_COMMITTER_NAME': 't', 'GIT_COMMITTER_EMAIL': 't@t'} + + +def review(cfg=CFG, log=None): + return lens.Review(cfg.bot_logins, cfg.override_prefix, cfg.override_association, cfg.lens_author_associations, + log=log or (lambda text: None)) + + +class Posts: + """Comments with rising createdAt, as GitHub lists them.""" + def __init__(self): + self.n = 0 + + def post(self, body, assoc='OWNER', login='owner', edited=False, hidden=False): + self.n += 1 + return {'body': body, 'author': {'login': login}, 'authorAssociation': assoc, 'includesCreatedEdit': edited, + 'isMinimized': hidden, 'createdAt': f'2026-11-14T01:{self.n:02d}:00Z', + 'url': f'https://github.com/{REPO}/pull/7#issuecomment-{self.n}'} + + def lens(self, name, sha, **kw): + return self.post(f'{LENS}: {name} · reviewer: x · read at: {sha}\nfindings: none', **kw) + + def override(self, sha, **kw): + return self.post(f'tool ready --head {sha}: read it myself', **kw) + + +def pr(comments=(), head=A, draft=False, reviews=()): + return {'isDraft': draft, 'headRefOid': head, 'comments': list(comments), 'reviews': list(reviews)} + + +class FakeCheckout: + """A checkout whose HEAD merges `head` into `base` and that knows no history: every git call fails, so only a head + that is the read commit itself can pass (pr_queue.holds finds no tree and no parents).""" + def __init__(self, head=A, base=C, parents=None): + self.parents = parents if parents is not None else (base, head) + + def merge_parents(self): + return self.parents + + def git(self, *a): + return types.SimpleNamespace(returncode=1, stdout='', stderr='no history here') + + def has(self, sha): + return True + + fetch = has + + +def lines(n=30, extra=None, at=None): + out = [f'line{i}' for i in range(1, n + 1)] + if extra: + out[at:at] = extra + return '\n'.join(out) + '\n' + + +class World: + """"GitHub" (a bare repository that serves any commit by sha), a work clone that builds commits, and the job's + checkout: GitHub's merge commit of a head into a base, fetched and checked out as actions/checkout does.""" + def __init__(self): + self.dir = tempfile.mkdtemp(prefix='head-check-world-') + self.remote, self.work = os.path.join(self.dir, 'github.git'), os.path.join(self.dir, 'work') + self.co = os.path.join(self.dir, 'checkout') + self.git(self.dir, 'init', '-q', '--bare', '-b', 'main', self.remote) + self.git(self.remote, 'config', 'uploadpack.allowAnySHA1InWant', 'true') + self.git(self.dir, 'init', '-q', '-b', 'main', self.work) + self.git(self.work, 'remote', 'add', 'origin', self.remote) + self.n = 0 + + def close(self): + shutil.rmtree(self.dir, ignore_errors=True) + + @staticmethod + def git(cwd, *a): + r = subprocess.run(['git', *a], cwd=cwd, text=True, capture_output=True, env={**os.environ, **GIT_ENV}) + if r.returncode != 0: + raise RuntimeError(f'git {a}: {r.stderr}') + return r.stdout.strip() + + def commit(self, files, parents=(), msg='c'): + for name in os.listdir(self.work): + if name != '.git': + p = os.path.join(self.work, name) + shutil.rmtree(p) if os.path.isdir(p) else os.remove(p) + for path, text in files.items(): + os.makedirs(os.path.dirname(os.path.join(self.work, path)) or self.work, exist_ok=True) + with open(os.path.join(self.work, path), 'w') as f: + f.write(text) + self.git(self.work, 'add', '-A') + tree = self.git(self.work, 'write-tree') + sha = self.git(self.work, 'commit-tree', tree, *sum((['-p', p] for p in parents), []), '-m', msg) + self.n += 1 + self.git(self.work, 'push', '-q', 'origin', f'{sha}:refs/keep/{self.n}') + return sha + + def merge(self, head, base, files=None): + """What `gh pr update-branch` makes: (parents head, base), git's clean merge, or exactly `files`.""" + if files is not None: + return self.commit(files, [head, base], 'Merge main') + tree = self.git(self.work, 'merge-tree', '--write-tree', head, base).split()[0] + sha = self.git(self.work, 'commit-tree', tree, '-p', head, '-p', base, '-m', 'Merge main') + self.n += 1 + self.git(self.work, 'push', '-q', 'origin', f'{sha}:refs/keep/{self.n}') + return sha + + def checkout(self, base, head): + """The job's checkout: GitHub's merge commit (parents base, head), with base and head's history and nothing + else (no ref reaches a commit the head dropped). Returns the checkout's path.""" + tree = self.git(self.work, 'merge-tree', '--write-tree', '--allow-unrelated-histories', base, head).split()[0] + merge = self.git(self.work, 'commit-tree', tree, '-p', base, '-p', head, '-m', 'GitHub merge') + self.git(self.work, 'push', '-q', '-f', 'origin', f'{merge}:refs/pull/7/merge') + shutil.rmtree(self.co, ignore_errors=True) + self.git(self.dir, 'init', '-q', '-b', 'main', self.co) + self.git(self.co, 'remote', 'add', 'origin', self.remote) + self.git(self.co, 'fetch', '-q', '--no-tags', 'origin', '+refs/pull/7/merge:refs/remotes/pull/7/merge') + self.git(self.co, 'checkout', '-q', '--detach', merge) + return self.co + + +def base_files(cfg_raw=CFG_RAW, **files): + return {CONFIG_PATH: json.dumps(cfg_raw), 'x.py': lines(), **files} + + +def fake_gh(*answers, calls=None): + """gh that answers `pr view` with each answer in turn (the last one repeats): (code, stdout).""" + calls = [] if calls is None else calls + + def gh(*a): + calls.append(a) + if a[:2] != ('pr', 'view'): + raise AssertionError(f'gh must only read: {a}') + code, out = answers[min(len(calls) - 1, len(answers) - 1)] + return types.SimpleNamespace(returncode=code, stdout=out, stderr='boom' if code else '') + return gh + + +def run_cli(path, gh, *extra, env=None, sleeps=None): + out = [] + code = H.cli(['--repo', REPO, '--pr', '7', '--config', CONFIG_PATH, '--path', path, *extra], env=env or {}, gh=gh, + sleep=(sleeps.append if sleeps is not None else lambda s: None), out=out.append) + return code, '\n'.join(out) + + +# --- the review rules, on a checkout whose merge commit merges the head GitHub reports ---------------------------- +class Rules(unittest.TestCase): + def setUp(self): + self.p = Posts() + + def verdict(self, comments, head=A, required='', **kw): + names, problems = H.required_names(required) + self.assertEqual(problems, []) + return H.verdict(pr(comments, head=head, **{k: v for k, v in kw.items() if k == 'draft'}), review(), + kw.get('checkout') or FakeCheckout(head), names, kw.get('pass_drafts', False)) + + def test_every_lens_read_the_head_passes(self): + ok, why, rows = self.verdict([self.p.lens('correctness', A), self.p.lens('design', A)]) + self.assertTrue(ok, why) + self.assertEqual([(name, good) for name, good, _ in rows], [('correctness', True), ('design', True)]) + + def test_no_lens_comments_passes_unless_a_lens_is_required(self): # empty state + ok, why, rows = self.verdict([self.p.post('looks fine, thanks')]) + self.assertTrue(ok, why) + self.assertEqual(rows, []) + ok, why, rows = self.verdict([], required='correctness') + self.assertFalse(ok) + self.assertIn('correctness', why) + self.assertEqual(rows, [('correctness', False, + 'required: no lens comment of a counted author has this name (lenses found: none)')]) + + def test_a_required_lens_must_be_among_the_reads(self): + ok, why, _ = self.verdict([self.p.lens('correctness', A)], required='correctness\nsecurity') + self.assertFalse(ok) + self.assertIn('security', why) + ok, why, rows = self.verdict([self.p.lens('Correctness r2', A), self.p.lens('security', A)], + required='correctness\nsecurity') + self.assertTrue(ok, why) + self.assertIn(('correctness (required)', True), [(n, g) for n, g, _ in rows]) + + def test_a_required_lens_name_may_hold_a_comma(self): # one name per line, trimmed, blank lines skipped + names, problems = H.required_names('\n data-integrity (DI-1, DI-2) \r\n\n security\n') + self.assertEqual((names, problems), ({'data-integrity (di-1, di-2)': 'data-integrity (DI-1, DI-2)', + 'security': 'security'}, [])) + ok, why, _ = self.verdict([self.p.lens('data-integrity (DI-1, DI-2)', A), self.p.lens('security', A)], + required='data-integrity (DI-1, DI-2)\nsecurity') + self.assertTrue(ok, why) + + def test_a_required_name_no_comment_has_is_named_with_the_lenses_found(self): # a typo fails, and says why + ok, why, rows = self.verdict([self.p.lens('correctness', A), self.p.lens('security', A)], + required='correctness\nsecurty') + self.assertFalse(ok) + self.assertIn('required lens without a read: securty', why) + self.assertIn('one name per line', why) + self.assertIn('lenses found: correctness, security', why) + self.assertEqual(rows[0], ('securty', False, 'required: no lens comment of a counted author has this name ' + '(lenses found: correctness, security)')) + + def test_a_required_lens_that_reads_nothing_fails(self): + ok, _, rows = self.verdict([self.p.lens('correctness', A[:12])], required='correctness') + self.assertFalse(ok) + self.assertEqual(rows[0][:2], ('correctness (required)', False)) + + def test_lens_names_that_name_no_lens_are_refused(self): + for text in ('', 'r2', 're-check', '***'): + with self.subTest(text=text): + self.assertTrue(H.required_names(text)[1]) + + def test_a_draft_passes_only_when_drafts_pass(self): + stale = [self.p.lens('correctness', B)] + self.assertTrue(self.verdict(stale, draft=True, pass_drafts=True)[0]) + ok, _, _ = self.verdict(stale, draft=True, checkout=FakeCheckout(A)) + self.assertFalse(ok) + + def test_lenses_on_different_commits_fail(self): + ok, why, rows = self.verdict([self.p.lens('a', A), self.p.lens('b', B)]) + self.assertFalse(ok) + self.assertIn('did not all read one head', why) + self.assertEqual({good for _, good, _ in rows}, {False}) + + def test_a_short_sha_reads_nothing(self): # a later push can share the prefix + ok, _, rows = self.verdict([self.p.lens('correctness', A[:7])]) + self.assertFalse(ok) + self.assertIn(lens.SHORT, rows[0][2]) + + def test_an_edited_lens_reads_nothing_until_it_posts_again(self): + ok, _, rows = self.verdict([self.p.lens('correctness', A, edited=True)]) + self.assertFalse(ok) + self.assertIn(lens.EDITED, rows[0][2]) + self.assertTrue(self.verdict([self.p.lens('correctness', A, edited=True), self.p.lens('correctness', A)])[0]) + + def test_a_missing_edit_field_reads_nothing(self): # fail closed: GitHub did not say "never edited" + post = self.p.lens('correctness', A) + del post['includesCreatedEdit'] + self.assertFalse(self.verdict([post])[0]) + + def test_a_hidden_lens_reads_nothing(self): + ok, _, rows = self.verdict([self.p.lens('correctness', A, hidden=True)]) + self.assertFalse(ok) + self.assertIn(lens.HIDDEN, rows[0][2]) + + def test_a_strangers_lens_neither_reads_nor_blocks(self): # anyone can comment on a public repository + for assoc in ('NONE', 'CONTRIBUTOR', 'FIRST_TIME_CONTRIBUTOR', None): + with self.subTest(assoc=assoc): + stale = self.p.lens('correctness', B, assoc=assoc, login='stranger') + self.assertTrue(self.verdict([self.p.lens('correctness', A), stale])[0]) + ok, why, _ = self.verdict([self.p.lens('correctness', A, assoc=assoc)], required='correctness') + self.assertFalse(ok, f'{assoc} vouched for a head') + + def test_a_bot_counts_for_nothing_even_as_owner(self): + for login in ('review-bot', 'Review-Bot', 'helper[bot]'): + with self.subTest(login=login): + self.assertTrue(self.verdict([self.p.lens('correctness', A), self.p.lens('x', B, login=login)])[0]) + + def test_an_old_format_report_reads_nothing(self): # old state: reports from before the fixed grammar + for body in (f'## Correctness {LENS}\nsafe to merge: yes', f'Review (correctness) read at: {A}', + f'```\n{LENS}: correctness · read at: {A}\n```', 'covered: all\nchecks: ran the tests'): + with self.subTest(body=body): + ok, _, rows = self.verdict([self.p.lens('correctness', A), self.p.post(body)]) + self.assertFalse(ok) + self.assertIn(lens.NO_HEADER, ' '.join(name for name, _, _ in rows)) + + def test_a_deleted_comment_counts_no_more(self): # deleted: GitHub no longer lists it + look_alike = self.p.post('safe to merge') + good = self.p.lens('correctness', A) + self.assertFalse(self.verdict([look_alike, good])[0]) + self.assertTrue(self.verdict([good])[0]) + stale, newer = self.p.lens('correctness', B), self.p.lens('correctness', A) + self.assertTrue(self.verdict([stale, newer])[0]) + self.assertFalse(self.verdict([stale])[0]) # the newer read deleted: the old head's read stands + + def test_a_not_a_lens_note_is_no_lens(self): + self.assertTrue(self.verdict([self.p.lens('correctness', A), self.p.post(f'not a {LENS}: fixed it')])[0]) + + def test_the_owners_newer_override_covers_a_stale_lens(self): + ok, why, rows = self.verdict([self.p.lens('correctness', B), self.p.override(A)]) + self.assertTrue(ok, why) + self.assertIn('override', rows[0][2]) + + def test_an_override_that_is_not_the_owners_shown_unedited_and_newer_counts_for_nothing(self): + cases = {'collaborator': dict(assoc='COLLABORATOR'), 'stranger': dict(assoc='NONE'), + 'edited': dict(edited=True), 'hidden': dict(hidden=True), 'bot': dict(login='helper[bot]')} + for what, kw in cases.items(): + with self.subTest(what=what): + self.assertFalse(self.verdict([self.p.lens('correctness', B), self.p.override(A, **kw)])[0]) + older = self.p.override(A) + self.assertFalse(self.verdict([older, self.p.lens('correctness', B)])[0]) + + def test_github_naming_no_head_fails(self): + for head in (None, '', A[:12], 'z' * 40): + with self.subTest(head=head): + self.assertFalse(H.verdict(pr([self.p.lens('c', A)], head=head), review(), FakeCheckout(), {}, False)[0]) + + def test_a_checkout_of_another_head_fails(self): # a newer push: its own run decides + ok, why, _ = self.verdict([self.p.lens('correctness', A)], checkout=FakeCheckout(B)) + self.assertFalse(ok) + self.assertIn('newer head', why) + + def test_a_checkout_that_is_no_merge_commit_fails(self): + ok, why, _ = self.verdict([self.p.lens('correctness', A)], checkout=FakeCheckout(parents=())) + self.assertFalse(ok) + self.assertIn('merge commit', why) + + def test_the_rules_are_lens_pys_not_a_copy(self): # one source: change lens.py's answer, the check follows + with unittest.mock.patch.object(lens.Review, 'lens_reads', lambda self, p: {'patched': (A, None, None)}), \ + unittest.mock.patch.object(lens.Review, 'reviewed_head', lambda self, p: (True, A, 'every lens read it')): + ok, _, rows = H.verdict(pr([self.p.lens('c', B)]), review(), FakeCheckout(), {}, False) + self.assertTrue(ok) + self.assertEqual([name for name, _, _ in rows], ['patched']) + with unittest.mock.patch.object(lens.Review, 'lens_reads', lambda self, p: {'c': (None, 'x', None)}), \ + unittest.mock.patch.object(lens.Review, 'reviewed_head', lambda self, p: (True, None, 'x')): + self.assertFalse(H.verdict(pr([self.p.lens('c', A)]), review(), FakeCheckout(), {}, False)[0]) + self.assertIs(H.lens, lens) + self.assertEqual(os.path.dirname(os.path.realpath(lens.__file__)), os.path.join(os.path.dirname(HERE), 'pr-queue')) + + +# --- the same change: real commits ------------------------------------------------------------------------------ +class SameChange(unittest.TestCase): + """GitHub's merge commit is the checkout; the read commit, the base and the head are real commits.""" + + def setUp(self): + self.w = World() + self.addCleanup(self.w.close) + self.p = Posts() + self.m0 = self.w.commit(base_files()) + self.read = self.w.commit(base_files(**{'x.py': lines(extra=['fix'], at=20)}), [self.m0]) + self.m1 = self.w.commit(base_files(**{'y.py': 'y\n'}), [self.m0]) + + def check(self, head, read=None, base=None, comments=None, *extra): + path = self.w.checkout(base or self.m1, head) + comments = comments if comments is not None else [self.p.lens('correctness', read or self.read)] + return run_cli(path, fake_gh((0, json.dumps(pr(comments, head=head)))), *extra) + + def test_the_read_commit_itself_passes(self): + code, out = self.check(self.read) + self.assertEqual(code, 0, out) + + def test_a_queue_update_of_the_read_commit_passes(self): + code, out = self.check(self.w.merge(self.read, self.m1)) + self.assertEqual(code, 0, out) + self.assertIn('merged with the base', out) + + def test_a_second_queue_update_passes(self): + first = self.w.merge(self.read, self.m1) + m2 = self.w.commit(base_files(**{'y.py': 'y\n', 'z.py': 'z\n'}), [self.m1]) + code, out = self.check(self.w.merge(first, m2), base=m2) + self.assertEqual(code, 0, out) + + def test_a_commit_on_top_of_the_read_commit_fails(self): # a plain push after the review + head = self.w.commit(base_files(**{'x.py': lines(extra=['fix', 'more'], at=20)}), [self.read]) + code, out = self.check(head) + self.assertEqual(code, 1, out) + self.assertIn('::error::', out) + + def test_a_lens_on_an_old_head_fails(self): # old state: the review read a commit before the last push + old = self.read + head = self.w.commit(base_files(**{'x.py': lines(extra=['fix2'], at=20)}), [old]) + code, out = self.check(head, read=old) + self.assertEqual(code, 1, out) + self.assertIn(f'not the change read at {old[:12]}', out) + + def test_a_merge_with_an_extra_change_in_it_fails(self): + evil = self.w.merge(self.read, self.m1, files=base_files(**{'x.py': lines(extra=['fix', 'sneaked'], at=20), + 'y.py': 'y\n'})) + self.assertEqual(self.check(evil)[0], 1) + + def test_the_read_commit_merged_with_a_branch_that_is_not_the_base_fails(self): + other = self.w.commit(base_files(**{'evil.py': 'evil\n'}), [self.m0]) + self.assertEqual(self.check(self.w.merge(self.read, other))[0], 1) + + def test_a_force_pushed_rewrite_fails(self): + rewritten = self.w.commit(base_files(**{'x.py': lines(extra=['other'], at=20)}), [self.m0]) + self.assertEqual(self.check(rewritten)[0], 1) + + def test_a_read_commit_the_head_dropped_is_fetched_from_github(self): # an amended message: same change + amended = self.w.commit(base_files(**{'x.py': lines(extra=['fix'], at=20)}), [self.m0], msg='amended') + path = self.w.checkout(self.m1, amended) + self.assertNotEqual(subprocess.run(['git', '-C', path, 'cat-file', '-e', self.read + '^{commit}'], + capture_output=True).returncode, 0) + code, out = run_cli(path, fake_gh((0, json.dumps(pr([self.p.lens('c', self.read)], head=amended))))) + self.assertEqual(code, 0, out) + + def test_a_read_commit_github_does_not_have_fails(self): + code, out = self.check(self.w.merge(self.read, self.m1), read='e' * 40) + self.assertEqual(code, 1, out) + self.assertIn('could not be fetched from origin', out) + self.assertIn('persist-credentials: false', out) + + def test_the_pull_requests_gitattributes_cannot_make_a_conflict_clean(self): + # The read change and the base both change line 20; the read commit also asks for merge=union. The queue's + # bare cache reads no attributes, so the conflict stands there: the check must agree, although the checkout's + # work tree holds that .gitattributes. + attrs = {'.gitattributes': 'x.py merge=union\n'} + read = self.w.commit(base_files(**attrs, **{'x.py': lines().replace('line20', 'X')}), [self.m0]) + m1 = self.w.commit(base_files(**{'x.py': lines().replace('line20', 'Y')}), [self.m0]) + union = base_files(**attrs, **{'x.py': lines().replace('line20', 'Y\nX')}) + head = self.w.merge(read, m1, files=union) + code, out = self.check(head, read=read, base=m1) + self.assertEqual(code, 1, out) + + def test_the_config_is_the_bases_not_the_pull_requests(self): + # The head's copy makes the owner a bot, which would hide the owner's stale lens (no lens comments: pass). + head = self.w.commit(base_files(cfg_raw={**CFG_RAW, 'bot_logins': ['owner']}, + **{'x.py': lines(extra=['unread'], at=20)}), [self.read]) + code, out = self.check(head) + self.assertEqual(code, 1, out) + + def test_a_base_without_the_config_is_refused(self): + bare_base = self.w.commit({'other.py': 'o\n'}, []) + path = self.w.checkout(bare_base, self.read) + code, out = run_cli(path, fake_gh((0, json.dumps(pr([]))))) + self.assertEqual(code, H.REFUSED, out) + self.assertIn('has no config', out) + + def test_a_shallow_or_tampered_checkout_is_refused(self): + for name, text, says in (('shallow', self.m1 + '\n', 'fetch-depth: 0'), ('info/grafts', '', 'info/grafts'), + ('objects/info/alternates', '', 'alternates')): + with self.subTest(name=name): + path = self.w.checkout(self.m1, self.read) + target = os.path.join(path, '.git', name) + os.makedirs(os.path.dirname(target), exist_ok=True) + with open(target, 'w') as f: + f.write(text) + calls = [] + code, out = run_cli(path, fake_gh((0, json.dumps(pr([]))), calls=calls)) + self.assertEqual(code, H.REFUSED, out) + self.assertIn(says, out) + self.assertEqual(calls, []) + + def test_a_checkout_that_is_not_a_merge_commit_is_refused(self): # refused (2) before GitHub is read, not failed + path = self.w.checkout(self.m1, self.read) + self.w.git(path, 'checkout', '-q', '--detach', self.read) + calls = [] + code, out = run_cli(path, fake_gh((0, json.dumps(pr([self.p.lens('c', self.read)], head=self.read))), + calls=calls)) + self.assertEqual(code, H.REFUSED, out) + self.assertIn("not GitHub's two-parent merge commit", out) + self.assertEqual(calls, []) + + +# --- reading GitHub, the outputs, re-runs and stops ------------------------------------------------------------- +class Runs(unittest.TestCase): + def setUp(self): + self.w = World() + self.addCleanup(self.w.close) + self.p = Posts() + self.m0 = m0 = self.w.commit(base_files()) + self.read = self.w.commit(base_files(**{'x.py': lines(extra=['fix'], at=20)}), [m0]) + self.path = self.w.checkout(m0, self.read) + self.good = json.dumps(pr([self.p.lens('correctness', self.read)], head=self.read)) + self.stale = json.dumps(pr([self.p.lens('correctness', m0)], head=self.read)) + self.files = tempfile.mkdtemp(prefix='head-check-files-') + self.addCleanup(shutil.rmtree, self.files, True) + self.env = {'GITHUB_STEP_SUMMARY': os.path.join(self.files, 'summary.md'), + 'GITHUB_OUTPUT': os.path.join(self.files, 'output')} + + def read_file(self, name): + path = os.path.join(self.files, name) + if not os.path.exists(path): + return None + with open(path) as f: + return f.read() + + def test_a_gh_error_fails_after_the_retries(self): + calls, sleeps = [], [] + code, out = run_cli(self.path, fake_gh((1, ''), calls=calls), env=self.env, sleeps=sleeps) + self.assertEqual(code, 1) + self.assertEqual(len(calls), H.ATTEMPTS) + self.assertEqual(sleeps, [H.RETRY_SECONDS] * (H.ATTEMPTS - 1)) + self.assertIn('::error::', out) + self.assertEqual(self.read_file('output'), 'result=fail\n') + + def test_one_failed_read_is_retried(self): + self.assertEqual(run_cli(self.path, fake_gh((1, ''), (0, self.good)))[0], 0) + + def test_an_answer_that_is_not_a_pr_fails(self): + for text in ('', 'null', '[]', '{}', '{"isDraft": "no", "comments": [], "reviews": []}', + json.dumps(dict(pr(), comments=None)), json.dumps(dict(pr(), reviews=None))): + with self.subTest(text=text): + self.assertEqual(run_cli(self.path, fake_gh((0, text)))[0], 1) + + def test_pass_and_fail_reach_the_exit_code_summary_and_output(self): + code, out = run_cli(self.path, fake_gh((0, self.good)), env=self.env) + self.assertEqual(code, 0, out) + self.assertEqual(self.read_file('output'), 'result=pass\n') + self.assertIn('| correctness | ok |', self.read_file('summary.md')) + os.remove(self.env['GITHUB_OUTPUT']) + code, out = run_cli(self.path, fake_gh((0, self.stale)), env=self.env) + self.assertEqual(code, 1, out) + self.assertEqual(self.read_file('output'), 'result=fail\n') + self.assertIn('| correctness | fail |', self.read_file('summary.md')) + + def test_a_rerun_on_the_same_head_gives_the_same_answer_and_writes_nothing_else(self): + refs = self.w.git(self.path, 'for-each-ref') + for answer in (self.good, self.stale): + with self.subTest(pass_=answer is self.good): + calls = [] + first = run_cli(self.path, fake_gh((0, answer), calls=calls)) + self.assertEqual(run_cli(self.path, fake_gh((0, answer), calls=calls)), first) + self.assertEqual({c[:2] for c in calls}, {('pr', 'view')}) # reads only: no comment, no edit + self.assertEqual(self.w.git(self.path, 'for-each-ref'), refs) + self.assertEqual(self.w.git(self.path, 'status', '--porcelain'), '') + + def test_a_run_stopped_before_the_answer_leaves_nothing(self): + def dies(*a): + raise KeyboardInterrupt # the job is cancelled while gh runs + with self.assertRaises(KeyboardInterrupt): + run_cli(self.path, dies, env=self.env) + self.assertIsNone(self.read_file('output')) + self.assertIsNone(self.read_file('summary.md')) + + def test_refusals_touch_nothing_and_name_every_reason(self): + calls = [] + out = [] + code = H.cli(['--repo', 'not a repo', '--pr', '', '--config', CONFIG_PATH, '--path', self.path, + '--required-lenses', ''], env=self.env, gh=fake_gh((0, self.good), calls=calls), + out=out.append) + self.assertEqual(code, H.REFUSED) + self.assertEqual(calls, []) + self.assertIsNone(self.read_file('output')) + for part in ('--repo', '--pr', 'names no lens'): + self.assertIn(part, out[0]) + + def test_a_bad_config_on_the_base_is_refused(self): + bad = self.w.commit(base_files(cfg_raw={**CFG_RAW, 'lens_author_associations': ['NONE']}), [self.m0]) + path = self.w.checkout(bad, self.read) + code, out = run_cli(path, fake_gh((0, self.good))) + self.assertEqual(code, H.REFUSED, out) + self.assertIn('lens_author_associations', out) + + def test_no_text_from_a_comment_starts_a_workflow_command(self): + name = 'x%0A::warning::y\r::error::z\n::error::w' + self.assertNotIn('\n', H.escape(name)) + self.assertNotIn('\r', H.escape(name)) + self.assertIn('%250A', H.escape(name)) + answer = json.dumps(pr([self.p.post(f'{LENS}: {name} · read at: {self.read}\n::error::forged')], + head=self.read)) + code, out = run_cli(self.path, fake_gh((0, answer))) + self.assertTrue(all(not line.startswith('::') or line.startswith('::error::#7') for line in out.splitlines()), + out) + + +# --- the action ------------------------------------------------------------------------------------------------- +class Action(unittest.TestCase): + """action.yml's step, run as Actions runs it, with a fake python3 that prints its arguments.""" + + def setUp(self): + import yaml + with open(os.path.join(HERE, 'action.yml')) as f: + self.action = yaml.safe_load(f) + self.bin = tempfile.mkdtemp(prefix='head-check-bin-') + self.addCleanup(shutil.rmtree, self.bin, True) + with open(os.path.join(self.bin, 'python3'), 'w') as f: + f.write('#!/bin/sh\nfor a in "$@"; do printf "%s\\n" "$a"; done\n') + os.chmod(os.path.join(self.bin, 'python3'), 0o755) + + def run_step(self, **env): + step = self.action['runs']['steps'][0] + base = {'REPO': REPO, 'PR': '7', 'CONFIG': CONFIG_PATH, 'CHECKOUT_PATH': '.', 'REQUIRED_LENSES': '', + 'PASS_DRAFTS': 'false', 'GITHUB_ACTION_PATH': HERE} + return subprocess.run(['bash', '--noprofile', '--norc', '-eo', 'pipefail', '-c', step['run']], + env={'PATH': self.bin + os.pathsep + os.environ['PATH'], **base, **env}, + capture_output=True, text=True) + + def test_it_runs_the_check_isolated_with_every_input(self): + r = self.run_step(REQUIRED_LENSES='a\nb', PASS_DRAFTS='true') + self.assertEqual(r.returncode, 0, r.stderr) + self.assertEqual(r.stdout.split('\n')[:2], ['-I', os.path.join(HERE, 'head_check.py')]) + args = r.stdout.split('\n')[2:] + self.assertEqual(args[args.index('--config') + 1], CONFIG_PATH) # a repository path, read from the base + self.assertEqual(args[args.index('--required-lenses') + 1], 'a') + self.assertIn('--pass-drafts', args) + self.assertNotIn('--pass-drafts', self.run_step().stdout.split('\n')) + + def test_a_pass_drafts_that_is_not_true_or_false_is_refused(self): + r = self.run_step(PASS_DRAFTS='yes') + self.assertEqual(r.returncode, 2) + self.assertIn('::error::', r.stdout) + + def test_the_refusal_does_not_echo_the_pass_drafts_value(self): # a newline in it could start a command + r = self.run_step(PASS_DRAFTS='yes\n::warning::forged') + self.assertEqual(r.returncode, 2) + self.assertNotIn('forged', r.stdout + r.stderr) + + def test_the_defaults_are_the_pull_request_events(self): + inputs = self.action['inputs'] + self.assertEqual(inputs['pr']['default'], '${{ github.event.pull_request.number }}') + self.assertEqual(inputs['pass-drafts']['default'], 'false') + self.assertTrue(inputs['config']['required']) + self.assertEqual(self.action['outputs']['result']['value'], '${{ steps.check.outputs.result }}') + + +class ReadmeExample(unittest.TestCase): + """README.md's usage example: the triggers a base change needs, and the action pinned by sha.""" + + def setUp(self): + import re, yaml + with open(os.path.join(HERE, 'README.md')) as f: + text = f.read() + blocks = re.findall(r'```yaml\n(.*?)```', text, re.S) + self.assertEqual(len(blocks), 1) + self.example = yaml.safe_load(blocks[0]) + self.text = blocks[0] + + def test_the_triggers_rerun_it_on_a_base_change_and_on_ready(self): + types = self.example[True]['pull_request']['types'] # yaml reads `on` as True + for kind in ('opened', 'synchronize', 'reopened', 'ready_for_review', 'edited'): + self.assertIn(kind, types) + + def test_the_action_is_pinned_by_a_full_sha_never_by_a_local_path(self): + import re + uses = [s['uses'] for job in self.example['jobs'].values() for s in job['steps'] if 'uses' in s] + mine = [u for u in uses if 'head-check' in u] + self.assertEqual(len(mine), 1, uses) + self.assertRegex(mine[0], r'^[^./][^@]*/fork-ci/actions/head-check@$') + self.assertNotIn('uses: ./', self.text) + self.assertTrue(re.search(r'head-check@ # ci/vN', self.text)) + + +if __name__ == '__main__': + unittest.main() diff --git a/fork-ci/actions/pr-queue/README.md b/fork-ci/actions/pr-queue/README.md index 35b13f9f2eac6..5559b28939a98 100644 --- a/fork-ci/actions/pr-queue/README.md +++ b/fork-ci/actions/pr-queue/README.md @@ -31,7 +31,7 @@ an error: the queue then exits non-zero and touches no pull request. | `required_checks` | yes | Exactly the checks the branch ruleset requires. Not empty. | | `merge_method` | yes | `merge`, `squash` or `rebase`: how auto-merge is turned back on. | | `delete_branch` | yes | Whether auto-merge deletes the branch after merging. | -| `bot_logins` | yes | Logins whose comments never count as a lens. Any login ending in `[bot]` is a bot too. May be empty. | +| `bot_logins` | yes | Logins whose comments never count as a lens. May be empty. A login ending in `[bot]` or an author of type Bot is a bot too, but gh gives only the login, without `[bot]`: list every bot here. | | `lens_author_associations` | yes | Whose comments count as lens comments: GitHub's author association of the comment, from `OWNER`, `MEMBER`, `COLLABORATOR`. Everyone else's comments are ignored (Lens comments). `MEMBER` and `COLLABORATOR` do not mean write access: list only those whose holders may all vouch for a head. | | `override` | yes | The comment that vouches for a head when the lenses read older commits: ` <40-hex sha>: `, posted with this author association (`OWNER`, `MEMBER` or `COLLABORATOR`, with the same caveat) and never edited. | | `ready_command` | yes | The command people run to re-arm a pull request after a lens read; `{pr}` is the number. Only quoted in the queue's comments. | @@ -245,7 +245,9 @@ The queue needs: the plan decides what is re-armed ("The queue"); - a required `head_check` that fails a head no lens read. The queue only touches pull requests that are behind; without that check, a push to an - armed pull request that is already up to date merges unread; + armed pull request that is already up to date merges unread. The + [head-check](../head-check/README.md) action is that check, with the + queue's own rules; - a run after each push to the base branch and on a timer, so a pull request armed while the base is quiet is still picked up; - a token that can update branches, comment and merge (a fine-grained personal diff --git a/fork-ci/actions/pr-queue/config.py b/fork-ci/actions/pr-queue/config.py index 7338d853958e9..3d6e7c66462ec 100644 --- a/fork-ci/actions/pr-queue/config.py +++ b/fork-ci/actions/pr-queue/config.py @@ -71,7 +71,7 @@ def _int(lo, hi): 'merge_method': (True, lambda v: v in MERGE_METHODS, f'one of {", ".join(MERGE_METHODS)}'), 'delete_branch': (True, lambda v: isinstance(v, bool), 'true or false'), 'bot_logins': (True, lambda v: isinstance(v, list) and all(map(_text, v)), - 'a list of logins whose comments never count as a lens (may be empty; `*[bot]` always counts as a bot)'), + 'a list of logins whose comments never count as a lens (may be empty; list every bot: gh drops `[bot]`)'), 'lens_author_associations': (True, _associations, f'a non-empty list of distinct author associations from ' f'{", ".join(ASSOCIATIONS)}: only their comments count as lens comments'), 'override': (True, lambda v: isinstance(v, dict) and set(v) == {'prefix', 'author_association'} diff --git a/fork-ci/actions/pr-queue/lens.py b/fork-ci/actions/pr-queue/lens.py index f30c949d6388c..64bc2ab82b7c5 100644 --- a/fork-ci/actions/pr-queue/lens.py +++ b/fork-ci/actions/pr-queue/lens.py @@ -216,8 +216,13 @@ def __init__(self, bot_logins, override_prefix, override_association, lens_assoc self.log, self.logged = log, set() def is_bot(self, post): - login = ((post.get('author') or {}).get('login') or '').lower() - return login in self.bots or login.endswith('[bot]') + """A configured bot login, a login ending in `[bot]` (GitHub's REST API), or an author whose type is Bot + (`is_bot` true, or GraphQL's `__typename` Bot). `gh pr view --json comments,reviews` gives only the login, and + without the `[bot]` suffix, so through gh only bot_logins (and the author associations) keep bots out.""" + author = post.get('author') or {} + login = (author.get('login') or '').lower() + return login in self.bots or login.endswith('[bot]') or author.get('is_bot') is True \ + or author.get('__typename') == 'Bot' def counts(self, post): """The comment or review takes part in the review at all: GitHub records its author with one of the configured @@ -318,27 +323,37 @@ def lens_entries(self, pr): found[key] = ((when, i), None, why) if why else ((when, i), header[1], None) return found + def lens_reads(self, pr): + """{lens key: (sha, gap, override)}: what each lens of lens_entries counts as reading, the one rule reviewed_head + and the head-check action (../head-check) both use. sha: the full 40-hex sha it read, or the newest override's + sha when that override is newer than the lens's newest read (override is then that sha too); None when it reads + nothing, and gap then says why (edited, hidden, a short sha, no sha). Empty: no lens comments.""" + found = self.lens_entries(pr) + overrides = [((when, i), sha) for when, i, post in self.lens_posts(pr) for sha in [self.override_sha(post)] + if sha] + newest = max(overrides) if overrides else None + reads = {} + for k, (at, sha, why) in found.items(): + if newest and at < newest[0]: + reads[k] = (newest[1], None, newest[1]) + elif FULL_SHA.fullmatch(sha or ''): + reads[k] = (sha, None, None) + else: + reads[k] = (None, why or (f'{sha[:12]}: {SHORT}' if sha else 'no sha: no single commit of this PR'), None) + return reads + def reviewed_head(self, pr): """(reviewed, sha, why). Not reviewed (no lens comments): (False, None, ...). Reviewed: the one full 40-hex sha every lens's newest read names. A shorter read names nothing: the queue can only match a prefix against the commits GitHub lists now, and after a force-push a new commit can be made to share the prefix of the dropped one that was read. A full sha need not be a commit of the PR now (a rebase or force-push drops the read commit; GitHub keeps it, and the queue compares content). An override covers each lens whose newest read is - older than it. Lenses that name different commits, a short sha or none: sha None.""" - found = self.lens_entries(pr) - overrides = [((when, i), sha) for when, i, post in self.lens_posts(pr) for sha in [self.override_sha(post)] - if sha] - if not found: + older than it (lens_reads). Lenses that name different commits, a short sha or none: sha None.""" + reads = self.lens_reads(pr) + if not reads: return False, None, 'no lens comments' - newest = max(overrides) if overrides else None - reads = {k: (newest[1] if newest and at < newest[0] else sha if FULL_SHA.fullmatch(sha or '') else None) - for k, (at, sha, _) in found.items()} - shas = set(reads.values()) + shas = {sha for sha, _, _ in reads.values()} if len(shas) == 1 and None not in shas: return True, shas.pop(), 'every lens read it' - - def gap(k): - _, sha, why = found[k] - return why or (f'{sha[:12]}: {SHORT}' if sha else 'no sha: no single commit of this PR') - listed = ', '.join(f'{k} {v[:12] if v else "(" + gap(k) + ")"}' for k, v in sorted(reads.items())) + listed = ', '.join(f'{k} {sha[:12] if sha else "(" + gap + ")"}' for k, (sha, gap, _) in sorted(reads.items())) return True, None, f'the lenses did not all read one head: {listed}' diff --git a/fork-ci/actions/pr-queue/lens.test.py b/fork-ci/actions/pr-queue/lens.test.py index 6520689975a29..c827b758285e9 100644 --- a/fork-ci/actions/pr-queue/lens.test.py +++ b/fork-ci/actions/pr-queue/lens.test.py @@ -140,6 +140,15 @@ def test_a_configured_bot_and_any_login_ending_in_bot_never_count(self): self.assertEqual(r.reviewed_head(pr(post(body, login=login))), (False, None, 'no lens comments'), login) self.assertEqual(r.reviewed_head(pr(post(body))), (True, SHA_A, 'every lens read it')) + def test_an_author_whose_type_is_bot_never_counts(self): # GraphQL drops the `[bot]` suffix from the login + r = lens.Review((), 'tool ready --head', 'OWNER', ('OWNER',)) + body = f'lens: correctness · reviewer: x · read at: {SHA_A}' + for author in ({'login': 'helper', 'is_bot': True}, {'login': 'helper', '__typename': 'Bot'}): + p = pr(post(body, author=author)) + self.assertEqual(r.reviewed_head(p), (False, None, 'no lens comments'), author) + for author in ({'login': 'helper', 'is_bot': False}, {'login': 'helper', '__typename': 'User'}): + self.assertEqual(r.reviewed_head(pr(post(body, author=author))), (True, SHA_A, 'every lens read it')) + def test_lenses_that_read_different_heads_name_no_head(self): p = pr(post(f'lens: correctness · reviewer: x · read at: {SHA_A}'), post(f'lens: data-integrity · reviewer: y · read at: {SHA_B}'))