basou: Observe a check run by its name on a board, and let every observation carry notes

[takashi-matsuyama]

The second of the changes that move basou board (experimental) to a new shape of its declaration and its records. Like the first, it lands on the integration branch board/shape-v3, not on main; all of them go to main and out in one release.

What changes

• The observation kind github_check (from board_version: 3): a GitHub repository, the name of a check run (check) and a branch (main when it names none), for a check run a GitHub App reports (a deploy, for one) as well as a job of a workflow. Its value is the conclusion of the newest check run of that name on the head commit of the branch, or its status while it has not finished. github_ci, which takes the file name of a workflow and looks at the latest run of the workflow on the branch, stays as it is.

  • A check name may hold spaces and :. One that is empty, longer than 255 characters (counted as characters, not UTF-16 code units), holds a control character or a ', or starts with - is refused. The repository and the branch are held to github_ci's shapes.

• A branch a github_ci or github_check observation names may not have a part that starts with ., in a board of any version. git takes no such branch, and GitHub reads a/./b in the path of a request as a/b: commits/heads/board/./observe-http/check-runs answers with the check runs of board/observe-http.

• notes on every observation (from board_version: 3): what to mind when making it, in the shape of a stage's or a lane's notes. A record keeps them with the declaration it holds.

• basou board guide gives the command for a github_check; basou still sends nothing:

  gh api -X GET 'repos/<owner>/<name>/commits/heads/<branch>/check-runs' -f check_name='<check>' -f per_page=100 -q '(.check_runs | max_by(.id) | if .status == "completed" then .conclusion else .status end), (if .total_count > 100 then "more than 100 runs: \(.total_count)" else empty end)'

  • -X GET, so the fields are the query. The source the guide gives for the record says gh api -X GET ... too: without it, gh sends -f fields as a POST.
  • heads/<branch>: as the API documents a branch. Without it, a branch named like a commit is read as one (commits/5fbd37a/... lists that commit's runs; commits/heads/5fbd37a/... is a 422 when no such branch exists). A branch with / works either way.
  • max_by(.id): the API lists one run for each check suite that ran the check, the default filter=latest included (a commit whose release workflow ran twice lists two runs of each of its jobs), and does not document the order. per_page=100, so the newest is on the page read; when the name has more runs than that, a second line says more than 100 runs: <n>, and the guide says to keep the first line as the value and say in a footnote that it may not be the newest. The 100 of the page and of the line are one constant.
  • No run of that name on the head commit prints an empty line: a null, with the error saying so. The guide says that a head commit that never started the check (a path filter, [skip ci] in its commit message, or the app's own rules) gives this too, even when what the check looks after is fine, and that a job a workflow skipped with if: is a check run, concluded skipped. A branch that does not exist exits 1 (HTTP 422).
  • The check name, the branch and the repository are Markdown code in the guide's prose, so a name with a backquote stays code and one with _ is not read as emphasis.

  Each observation's notes are printed under its commands as - mind: ..., escaped as the stages' and the lanes' are.

• A board of version 1 or 2 with a github_check or an observation's notes is told that version 3 reads it (observe[0].kind: 'github_check' is read from board_version 3 on; this file is board_version 2, observe[1]: 'notes' is read from board_version 3 on; ...).

• basou board init's comment on observe names github_check and notes.

Tests

• Declaration: what github_check takes and refuses (the name's characters and length, at 255 and 256, in characters; the repo, the branch, workflow), a branch with a part that starts with . refused for github_ci and github_check alike (a/./b, release/.x) while a.b/c.d is taken, notes on every kind and what they refuse, the kinds a version 3 board names, and which version a problem of a version 1 or 2 board is put down to.
• Guide: the command as printed for the default branch and for a branch with /, the value (the first line, the second line and its footnote, the empty line and what gives it, skipped for a job skipped with if:) and the source with -X GET; the check name, the branch and the repository as Markdown code in the prose (a name with a backquote fenced by two); the command run against a stand-in gh that prints its arguments (the check name, with spaces, :, a backquote, $(...), " and ;, arrives as one argument and runs nothing); and the notes under each observation, escaped, and none for one without.
• Records of version 3 keep a github_check and each observation's notes as declared; board record records one and board measure tells a version 2 board which version reads it.
• The command was run by hand against this repository: the newest of two runs of the same name in two check suites (one of them concluded skipped by if:), the second line with the threshold lowered to 1, an empty line with no run, a branch with /, heads/ with a branch named like a commit, a branch that does not exist (exit 1, HTTP 422), and a/./b read as a/b.
• Mutation checks in a copy: each of 25 mutations of the first commit's code fails a test, but one that changes nothing observable (quoting the check name without escaping a ', which the declaration refuses); each of 20 mutations of the second commit's code fails a test.
• pnpm -r build, pnpm typecheck, pnpm -r test:coverage, pnpm test:scripts, pnpm lint, pnpm lint:lang and pnpm lint:paths pass locally.