diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 656324fd..d3cfdd72 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -8,6 +8,8 @@ on: permissions: contents: read + # scripts/ci-tested lists the tested-tree artifacts. + actions: read # A new push to the same branch makes the previous run's result obsolete, and # leaving it running lets a stale result report after the newer one. @@ -30,6 +32,20 @@ jobs: with: fetch-depth: 0 + # A push whose tree a pull request run already passed -- a merge, squash + # or fast-forward onto a base that has not moved since -- would prove that + # tree twice. scripts/ci-tested looks for the tree the run recorded at the + # end of this job, and every doubt runs the checks. Only on a self-hosted + # runner: it is the operator's machine that pays for the second run, and + # it keeps toolchain caches on disk, while on a hosted runner a skipped + # push stops main saving the caches every pull request restores. + - name: Find a passing run on this tree + id: tested + if: github.event_name == 'push' && vars.RUNNER != '' + env: + GH_TOKEN: ${{ github.token }} + run: scripts/ci-tested >> "$GITHUB_OUTPUT" + # adr-index-test and commitlint-test both skip their hook-wiring cases # when pre-commit is absent, and those cases are the ones that catch a # hook pre-commit never invokes -- the failure both suites exist for. @@ -43,11 +59,13 @@ jobs: # path of this job, which was accepted rather than shipping a # commit-message rule to every generated repository unproven. - name: Install pre-commit + if: steps.tested.outputs.skip != 'true' run: pipx install pre-commit # Before the toolchains, since these install none and verify both the # language-capabilities wiring and the local/hosted check boundary. - name: Verify repository scripts + if: steps.tested.outputs.skip != 'true' run: scripts/script-tests # The hook receives the same base-to-head file range a push does. It @@ -63,7 +81,26 @@ jobs: --from-ref "$BASE_SHA" --to-ref "$HEAD_SHA" - name: Set up toolchains + if: steps.tested.outputs.skip != 'true' uses: ./.github/actions/setup-toolchains - name: Run CI checks + if: steps.tested.outputs.skip != 'true' run: scripts/ci + + # The tree this run just passed, the merge ref's, for scripts/ci-tested + # on the push that lands it. Reached only when every check above passed. + - name: Name the tested tree + id: tree + if: github.event_name == 'pull_request' && vars.RUNNER != '' + run: | + git rev-parse 'HEAD^{tree}' > "$RUNNER_TEMP/tested-tree" + echo "tree=$(cat "$RUNNER_TEMP/tested-tree")" >> "$GITHUB_OUTPUT" + + - name: Record the tested tree + if: steps.tree.outcome == 'success' + uses: actions/upload-artifact@v7 + with: + name: ci-tested-tree-${{ steps.tree.outputs.tree }} + path: ${{ runner.temp }}/tested-tree + retention-days: 30 diff --git a/CLAUDE.md b/CLAUDE.md index 607e3904..8b3cf835 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -32,7 +32,7 @@ Use these instead of per-language tools; each detects the languages present and - `scripts/doctor` — verify local toolchains, dependencies, hooks, and configuration without contacting hosted services - `scripts/repo-settings check` — inspect GitHub-hosted security and branch settings; run explicitly, since it needs the network and administration visibility -- `scripts/check` — the full local gate: `doctor`, `structure` and `payload-parity`, then lint, format, type check, test, and build with the script tests beside them, the security audit, and pre-commit over every file, tracked and untracked. It prints only the Result table and always writes the full run to `tmp/check.log`; `--verbose` streams everything. It reads no hosted GitHub state but is not offline: `commitlint-test` and pre-commit's hook environments fetch on first use +- `scripts/check` — the full local gate: `doctor`, `structure` and `payload-parity`, then lint, format, type check, test, and build with the script tests beside them, the security audit, and pre-commit over every file, tracked and untracked. It prints only the Result table and always writes the full run to `tmp/check.log`; `--verbose` streams everything; `--fast` leaves out `build`, which CI runs on the pull request. It reads no hosted GitHub state but is not offline: `commitlint-test` and pre-commit's hook environments fetch on first use - `scripts/fix` — the write half of `check`: lint autofix, then formatting, for every stack, unconditionally and in that order so the formatter lays out what the linter rewrote. Go, Swift and Kotlin have no lint autofix and report `lint-fix` `not-applicable`. A `lint-fix` FAIL means findings remain that need hand work - `scripts/summarize ` — run a check and print only its Result table with findings, then a verdict line of its exit status and a count per state, exiting with that status; read `ci` and other commands through this, since `check` already does - `scripts/clean` — recursively delete build output and tool caches (`dist`, `build`, `coverage`, `__pycache__`, `.*_cache`, `*.pyc`) @@ -53,7 +53,7 @@ The only non-shell code here is the Python under `apps/repo-builder/`, declared ## Git - Pre-commit blocks commits to `main` and `master`; branch first. -- Run `scripts/check` before committing. It runs CI's checks plus pre-commit over every file, but with the machine's tool versions rather than CI's fresh installs, so a lint can pass here and fail there; `scripts/CLAUDE.md` carries the rule. +- Run `scripts/check --fast` before committing, and the whole `scripts/check` when the change could break the build. It runs CI's checks plus pre-commit over every file, `--fast` leaving the build to CI, but with the machine's tool versions rather than CI's fresh installs, so a lint can pass here and fail there; `scripts/CLAUDE.md` carries the rule. - These prompt for approval: `git reset --hard`, `git clean`, `git rebase`, `rm`, `git rm`, and the `gh` commands that merge pull requests, cut releases, or delete the repository. Edits do not: this repository's `.claude/settings.json` allows `Edit(/**)`, anchored at the session's starting directory, so a session started at the checkout root edits or writes any file without a prompt, root files and dotfiles included. Claude Code's built-in protected paths, such as `.claude/`, `.git/`, `.devcontainer/`, and `.pre-commit-config.yaml`, stay gated whatever an allow rule says, and so do the files the operator's global `ask` rules name, such as `.env`, `*.pem`, and `secrets/`, since an `ask` outranks an `allow`. - Work reaches `main` through a pull request under `.github/PULL_REQUEST_TEMPLATE.md`; a ruleset enforces it (Repository settings below). - Commit messages follow [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#specification): `type(optional scope): subject`, a blank line, then the body. commitlint enforces it at `commit-msg`, with rules in `.commitlintrc.yaml`. The subject is lowercase after the type, with no trailing period. A body is expected: it is the only surviving record of why. diff --git a/apps/github-repository-template/docs/github_repository_structure.md b/apps/github-repository-template/docs/github_repository_structure.md index 95d2405d..f09f7a61 100644 --- a/apps/github-repository-template/docs/github_repository_structure.md +++ b/apps/github-repository-template/docs/github_repository_structure.md @@ -5,7 +5,7 @@ type: Note ### GitHub Automation -`.github/workflows/ci.yml`: Runs tests, linting, formatting checks, type checks, and builds on every push and pull request. +`.github/workflows/ci.yml`: Runs tests, linting, formatting checks, type checks, and builds on every pull request and every push to `main`. On a self-hosted runner, a passing pull request run records the tree it tested as an artifact, and a push whose tree one of those records names skips the checks and goes green; `scripts/ci-tested` decides. `.github/workflows/release.yml`: Validates a tagged release and publishes it, both through `scripts/release`. @@ -79,7 +79,9 @@ The specific operating parameters for the AI agent. `scripts/script-tests`: Runs every `scripts/tests/*-test` concurrently, one per CPU, and prints each one's output whole once all have finished, naming every test that failed. Called by `scripts/check` and by `ci.yml`, so both run the suites the same way. The suites spend their time waiting on git and child processes, so running them side by side cuts the wall time several-fold. -`scripts/check`: The full local gate. By default it prints only the Result table and the findings under any check that failed, by running itself under `scripts/summarize`, and it writes the complete run to `tmp/check.log` every time, passing or failing, since a pre-commit fixer repairs the file and a re-run no longer reproduces the failure. `--verbose` streams the whole run live, still writing the log. Exits with the gate's status either way. `scripts/script-tests` runs beside `scripts/ci`, since neither fills the CPUs, with its output printed once `ci` ends; the pre-commit sweep runs last, because its fixers rewrite files the other two read, and skips the hooks that repeat a step the gate already ran over the whole tree. +`scripts/check`: The full local gate. By default it prints only the Result table and the findings under any check that failed, by running itself under `scripts/summarize`, and it writes the complete run to `tmp/check.log` every time, passing or failing, since a pre-commit fixer repairs the file and a re-run no longer reproduces the failure. `--verbose` streams the whole run live, still writing the log. `--fast` is the commit-time gate: every step but `build`, which CI runs on the same commit before it can land. Exits with the gate's status either way. `scripts/script-tests` runs beside `scripts/ci`, since neither fills the CPUs, with its output printed once `ci` ends; the pre-commit sweep runs last, because its fixers rewrite files the other two read, and skips the hooks that repeat a step the gate already ran over the whole tree. + +`scripts/ci-tested`: Called by `ci.yml` on a push to `main` on a self-hosted runner, and nowhere else, since it reads hosted run state. Prints `skip=true` when an unexpired `ci-tested-tree-` artifact from a same-repository pull request run names the push's tree: a merge, squash or fast-forward onto a base that has not moved since that run. Anything else, including a failed query, prints `skip=false` and the checks run. `scripts/summarize`: Runs a check command and prints only its Result table — one line per check, the findings under any that failed — dropping every other thing the command wrote. Exits with that command's status, so it can stand in for the command rather than only report on it, and ends with a verdict line naming that status and a count per state. `scripts/check` is its first caller; it stays the way to read `scripts/ci` and any other command. It is the one consumer of the printed layout `scripts/libs/result.sh` documents, which is where a change to the column widths has to be reflected. diff --git a/apps/github-repository-template/src/base-repo/.github/workflows/ci.yml b/apps/github-repository-template/src/base-repo/.github/workflows/ci.yml index 656324fd..d3cfdd72 100644 --- a/apps/github-repository-template/src/base-repo/.github/workflows/ci.yml +++ b/apps/github-repository-template/src/base-repo/.github/workflows/ci.yml @@ -8,6 +8,8 @@ on: permissions: contents: read + # scripts/ci-tested lists the tested-tree artifacts. + actions: read # A new push to the same branch makes the previous run's result obsolete, and # leaving it running lets a stale result report after the newer one. @@ -30,6 +32,20 @@ jobs: with: fetch-depth: 0 + # A push whose tree a pull request run already passed -- a merge, squash + # or fast-forward onto a base that has not moved since -- would prove that + # tree twice. scripts/ci-tested looks for the tree the run recorded at the + # end of this job, and every doubt runs the checks. Only on a self-hosted + # runner: it is the operator's machine that pays for the second run, and + # it keeps toolchain caches on disk, while on a hosted runner a skipped + # push stops main saving the caches every pull request restores. + - name: Find a passing run on this tree + id: tested + if: github.event_name == 'push' && vars.RUNNER != '' + env: + GH_TOKEN: ${{ github.token }} + run: scripts/ci-tested >> "$GITHUB_OUTPUT" + # adr-index-test and commitlint-test both skip their hook-wiring cases # when pre-commit is absent, and those cases are the ones that catch a # hook pre-commit never invokes -- the failure both suites exist for. @@ -43,11 +59,13 @@ jobs: # path of this job, which was accepted rather than shipping a # commit-message rule to every generated repository unproven. - name: Install pre-commit + if: steps.tested.outputs.skip != 'true' run: pipx install pre-commit # Before the toolchains, since these install none and verify both the # language-capabilities wiring and the local/hosted check boundary. - name: Verify repository scripts + if: steps.tested.outputs.skip != 'true' run: scripts/script-tests # The hook receives the same base-to-head file range a push does. It @@ -63,7 +81,26 @@ jobs: --from-ref "$BASE_SHA" --to-ref "$HEAD_SHA" - name: Set up toolchains + if: steps.tested.outputs.skip != 'true' uses: ./.github/actions/setup-toolchains - name: Run CI checks + if: steps.tested.outputs.skip != 'true' run: scripts/ci + + # The tree this run just passed, the merge ref's, for scripts/ci-tested + # on the push that lands it. Reached only when every check above passed. + - name: Name the tested tree + id: tree + if: github.event_name == 'pull_request' && vars.RUNNER != '' + run: | + git rev-parse 'HEAD^{tree}' > "$RUNNER_TEMP/tested-tree" + echo "tree=$(cat "$RUNNER_TEMP/tested-tree")" >> "$GITHUB_OUTPUT" + + - name: Record the tested tree + if: steps.tree.outcome == 'success' + uses: actions/upload-artifact@v7 + with: + name: ci-tested-tree-${{ steps.tree.outputs.tree }} + path: ${{ runner.temp }}/tested-tree + retention-days: 30 diff --git a/apps/github-repository-template/src/base-repo/CLAUDE.md b/apps/github-repository-template/src/base-repo/CLAUDE.md index b9ae2b5d..32902418 100644 --- a/apps/github-repository-template/src/base-repo/CLAUDE.md +++ b/apps/github-repository-template/src/base-repo/CLAUDE.md @@ -6,7 +6,7 @@ These sections are identical in every repository built from the template. Do not Use these instead of per-language tools. `check` and `fix` run for every language present and report `pass`, `not-applicable`, `unavailable`, or `FAIL`. -- `scripts/check` — the full local gate, a superset of CI except the pull request's changelog check: doctor, structure, then lint, format, type check, test, and build with the script tests beside them, security audit, pre-commit over every file. Prints only the Result table, with the full run in `tmp/check.log`; `--verbose` streams everything +- `scripts/check` — the full local gate, a superset of CI except the pull request's changelog check: doctor, structure, then lint, format, type check, test, and build with the script tests beside them, security audit, pre-commit over every file. Prints only the Result table, with the full run in `tmp/check.log`; `--verbose` streams everything; `--fast`, the commit-time gate, leaves `build` to CI and so is no superset of it - `scripts/fix` — lint autofix, then formatting - `scripts/summarize ` — run a check and print only its Result table, then a verdict line of its exit status and a count per state; read `ci` and other commands through this, since `check` already does - `scripts/run [unit] [--entry ] [-- args…]` — start a unit; the unit name is required when `apps/` holds several diff --git a/apps/github-repository-template/src/base-repo/scripts/check b/apps/github-repository-template/src/base-repo/scripts/check index c2cb3f0a..0a9c5464 100755 --- a/apps/github-repository-template/src/base-repo/scripts/check +++ b/apps/github-repository-template/src/base-repo/scripts/check @@ -20,23 +20,44 @@ cd "$repo_root" # the cause is gone; the log is what a failure outside the table is diagnosed # from. --verbose streams the same text live. --gate is the internal entry that # runs the steps below and nothing else, so the tee wraps exactly one run. -case "${1:-}" in +# +# --fast is the commit-time gate: every step below except build, which CI runs +# on the same commit before it can land and which costs more than the rest of +# the gate together in a repository that compiles. It rides through each entry, +# and tmp/check.log opens by saying build was left out, so a fast run's log +# never reads as the full gate's. +usage() { + echo "usage: scripts/check [--fast] [--verbose]" >&2 + exit 2 +} +mode="" +fast=() +for arg in "$@"; do + case "$arg" in + --verbose | --gate) + [[ -z "$mode" ]] || usage + mode="$arg" + ;; + --fast) fast=(--fast) ;; + *) usage ;; + esac +done +case "$mode" in "") - exec scripts/summarize scripts/check --verbose + exec scripts/summarize scripts/check --verbose "${fast[@]}" ;; --verbose) mkdir -p tmp # pipefail (set above) makes the pipeline's status the gate's, not tee's. - scripts/check --gate 2>&1 | tee tmp/check.log + scripts/check --gate "${fast[@]}" 2>&1 | tee tmp/check.log exit "${PIPESTATUS[0]}" ;; - --gate) ;; - *) - echo "usage: scripts/check [--verbose]" >&2 - exit 2 - ;; esac +if (( ${#fast[@]} )); then + echo "scripts/check --fast: build is left to CI." +fi + if [[ ! -x scripts/doctor ]]; then echo "scripts/doctor is missing or not executable." exit 1 @@ -100,8 +121,12 @@ trap 'exit 130' INT trap 'exit 143' TERM trap 'exit 141' PIPE +ci_args=() +if (( ${#fast[@]} )); then + ci_args=(--no-build) +fi ci_status=0 -scripts/ci || ci_status=$? +scripts/ci "${ci_args[@]}" || ci_status=$? script_tests_status=0 wait "$script_tests_pid" || script_tests_status=$? # Reaped, so its PID may now belong to another process. diff --git a/apps/github-repository-template/src/base-repo/scripts/ci b/apps/github-repository-template/src/base-repo/scripts/ci index 8cfae084..eec43ab3 100755 --- a/apps/github-repository-template/src/base-repo/scripts/ci +++ b/apps/github-repository-template/src/base-repo/scripts/ci @@ -8,6 +8,19 @@ cd "$repo_root" # shellcheck source=libs/detect.sh source "$repo_root/scripts/libs/detect.sh" +# --no-build leaves build out, for `scripts/check --fast`: the commit-time gate +# drops the slowest check CI repeats on the same commit before it can land. +# CI itself never passes it. +capabilities=(lint format-check typecheck test build) +case "${1:-}" in + "") ;; + --no-build) capabilities=(lint format-check typecheck test) ;; + *) + echo "usage: scripts/ci [--no-build]" >&2 + exit 2 + ;; +esac + # The shared policy: orphan search before the checks, which would run green over # the package none of them sees; the no-manifest early-out; the dry run. -capability_command check lint format-check typecheck test build +capability_command check "${capabilities[@]}" diff --git a/apps/github-repository-template/src/base-repo/scripts/ci-tested b/apps/github-repository-template/src/base-repo/scripts/ci-tested new file mode 100755 index 00000000..e806a294 --- /dev/null +++ b/apps/github-repository-template/src/base-repo/scripts/ci-tested @@ -0,0 +1,39 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Whether a passing pull request run of ci.yml already tested the tree a push to +# the default branch landed, so ci.yml can skip its checks instead of proving +# the same tree twice. Prints `skip=true` or `skip=false` for $GITHUB_OUTPUT +# and the reason on stderr, which the job log keeps. +# +# scripts/ci-tested +# +# A pull request run that passes uploads an artifact named for the tree it +# tested, its merge ref's: ci-tested-tree-. The push skips when an +# unexpired one of those names HEAD's tree, so any merge, squash or +# fast-forward whose result is a tree some run already passed skips, and one +# onto a base that moved since does not. Only the name says the run passed, and +# a pull request can rewrite the workflow that uploads it, so artifacts from a +# fork's run, or with no run at all, are ignored. A branch in this repository +# is trusted the same way: whoever can push one can already push to the +# default branch. +# +# Called by ci.yml alone: it reads hosted run state, which no local command does. +# Every doubt answers skip=false, since running the checks again costs minutes +# and skipping them wrongly leaves the branch unproven. + +decide() { + echo "ci-tested: $2" >&2 + echo "skip=$1" + exit 0 +} + +tree="$(git rev-parse 'HEAD^{tree}')" +count="$(gh api "repos/${GITHUB_REPOSITORY:?}/actions/artifacts?name=ci-tested-tree-$tree&per_page=100" \ + --jq '[.artifacts[] | select((.expired | not) and .workflow_run.repository_id != null + and .workflow_run.head_repository_id == .workflow_run.repository_id)] | length' \ + 2>/dev/null)" || decide false "could not read the tested-tree artifacts" + +[[ "$count" =~ ^[1-9] ]] || + decide false "no passing pull request run tested tree $tree" +decide true "a passing pull request run tested tree $tree, the tree now on the branch" diff --git a/apps/github-repository-template/src/base-repo/scripts/tests/capabilities-test b/apps/github-repository-template/src/base-repo/scripts/tests/capabilities-test index 6cd66cde..286e527d 100755 --- a/apps/github-repository-template/src/base-repo/scripts/tests/capabilities-test +++ b/apps/github-repository-template/src/base-repo/scripts/tests/capabilities-test @@ -167,6 +167,28 @@ out="$(ci)" assert_dispatches python "$out" assert_absent node "$out" +fixture "--no-build leaves build out and nothing else" +printf '[project]\nname = "p"\nversion = "0.1.0"\n' > "$work/pyproject.toml" +out="$(cd "$work" && CI_DRY_RUN=1 scripts/ci --no-build 2>&1 /dev/null 2>&1 "$work/package.json" out="$(ci)" diff --git a/apps/github-repository-template/src/base-repo/scripts/tests/check-test b/apps/github-repository-template/src/base-repo/scripts/tests/check-test index 2135817d..2b2398ed 100755 --- a/apps/github-repository-template/src/base-repo/scripts/tests/check-test +++ b/apps/github-repository-template/src/base-repo/scripts/tests/check-test @@ -4,8 +4,8 @@ set -uo pipefail # What scripts/check prints, writes, and exits with. The gate's steps are # stubbed in a scratch copy of the scripts, so the cases assert the wrapper's # contract -- table only by default, the whole run in tmp/check.log every time, -# raw output under --verbose, the gate's own exit status -- and not the output -# of any real check. +# raw output under --verbose, the gate's own exit status, --fast handing ci +# --no-build -- and not the output of any real check. repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" @@ -128,6 +128,55 @@ else fail "wanted the table and exit 0 from a subdirectory, got exit $status: $out" fi +# ci records the arguments it was given, so a case can tell the full gate from +# the fast one without running a real build. +ci_args_fixture() { + gate_fixture "$1" + printf '#!/usr/bin/env bash\necho "ci:$*" > ci-args\necho "lint pass python"\n' \ + > "$work/scripts/ci" +} + +ci_args_fixture "the default gate runs ci whole" +(cd "$work" && scripts/check >/dev/null 2>&1) +if [[ "$(cat "$work/ci-args" 2>&1)" == "ci:" ]]; then + pass +else + fail "wanted ci with no arguments, got: $(cat "$work/ci-args" 2>&1)" +fi + +ci_args_fixture "--fast leaves build to CI and says so in the log" +out="$(cd "$work" && scripts/check --fast 2>&1)" +status=$? +if (( status == 0 )) \ + && [[ "$(cat "$work/ci-args" 2>&1)" == "ci:--no-build" ]] \ + && grep -q 'chatter from security' "$work/tmp/check.log" \ + && grep -q 'build is left to CI' "$work/tmp/check.log" \ + && grep -qE '^lint +pass' <<< "$out"; then + pass +else + fail "wanted ci --no-build, every other step, and the log naming the skip, got exit $status: $out" +fi + +ci_args_fixture "--fast and --verbose combine in either order" +out="$(cd "$work" && scripts/check --fast --verbose 2>&1)" +status=$? +if (( status == 0 )) \ + && [[ "$(cat "$work/ci-args" 2>&1)" == "ci:--no-build" ]] \ + && grep -q 'chatter from doctor' <<< "$out"; then + pass +else + fail "wanted the streamed fast run, got exit $status: $out" +fi + +gate_fixture "two modes are a usage error" +(cd "$work" && scripts/check --verbose --gate >/dev/null 2>&1) +status=$? +if (( status == 2 )); then + pass +else + fail "wanted exit 2, got $status" +fi + gate_fixture "an unknown argument is a usage error" (cd "$work" && scripts/check --bogus >/dev/null 2>&1) status=$? diff --git a/apps/github-repository-template/src/base-repo/scripts/tests/ci-tested-test b/apps/github-repository-template/src/base-repo/scripts/tests/ci-tested-test new file mode 100755 index 00000000..43cf9d61 --- /dev/null +++ b/apps/github-repository-template/src/base-repo/scripts/tests/ci-tested-test @@ -0,0 +1,106 @@ +#!/usr/bin/env bash +set -uo pipefail + +# Whether scripts/ci-tested skips the default branch's checks only when a +# passing pull request run recorded the tree that landed. `gh` is a stub that +# answers the artifacts query with a fixed listing, run through the --jq filter +# it was given as gh would, and records what it was asked. + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" + +# shellcheck source-path=SCRIPTDIR +# shellcheck source=libs/harness.sh +source "$repo_root/scripts/tests/libs/harness.sh" + +echo "ci-tested-test" + +export GITHUB_REPOSITORY=owner/repo + +# A repository with one commit, and a gh stub answering with the artifacts +# listing $2, or failing when $2 is `error`. +fixture() { + scratch_repo + current="$1" + printf '%s\n' "$2" > "$work/listing" + stub gh <> "$work/gh-calls" +[[ "\$(cat "$work/listing")" == error ]] && exit 1 +while (( \$# )); do + [[ "\$1" == --jq ]] && exec jq "\$2" "$work/listing" + shift +done +cat "$work/listing" +STUB + git -C "$work" add -A + git -C "$work" commit -qm base + tree="$(git -C "$work" rev-parse 'HEAD^{tree}')" +} + +decide() { + (cd "$work" && scripts/ci-tested 2>"$work/reason") +} + +# One artifact entry: expired true|false, then the head repository's id against +# the repository's 1. +artifact() { + printf '{"expired": %s, "workflow_run": {"repository_id": 1, "head_repository_id": %s}}' "$1" "$2" +} + +if ! command -v jq >/dev/null 2>&1; then + current="ci-tested" + skip "jq is not installed, and the stub runs gh's --jq filter through it" + report + exit +fi + +fixture "a tree a same-repository run recorded skips" "{\"artifacts\": [$(artifact false 1)]}" +out="$(decide)" +if [[ "$out" == "skip=true" ]] \ + && grep -q "repos/owner/repo/actions/artifacts?name=ci-tested-tree-$tree&" "$work/gh-calls"; then + pass +else + fail "wanted skip=true from a query for tree $tree, got '$out': $(cat "$work/reason" "$work/gh-calls" 2>&1)" +fi + +fixture "a tree no run recorded runs the checks" '{"artifacts": []}' +out="$(decide)" +if [[ "$out" == "skip=false" ]] && grep -q 'no passing pull request run' "$work/reason"; then + pass +else + fail "wanted skip=false, got '$out': $(cat "$work/reason" 2>&1)" +fi + +fixture "an expired record runs the checks" "{\"artifacts\": [$(artifact true 1)]}" +out="$(decide)" +if [[ "$out" == "skip=false" ]]; then + pass +else + fail "wanted skip=false for an expired artifact, got '$out': $(cat "$work/reason" 2>&1)" +fi + +fixture "a record from a fork's run runs the checks" "{\"artifacts\": [$(artifact false 2)]}" +out="$(decide)" +if [[ "$out" == "skip=false" ]]; then + pass +else + fail "wanted skip=false for a fork's artifact, got '$out': $(cat "$work/reason" 2>&1)" +fi + +fixture "a record with no run runs the checks" '{"artifacts": [{"expired": false, "workflow_run": null}]}' +out="$(decide)" +if [[ "$out" == "skip=false" ]]; then + pass +else + fail "wanted skip=false for an artifact with no run, got '$out': $(cat "$work/reason" 2>&1)" +fi + +fixture "a failed query runs the checks" error +out="$(decide)" +if [[ "$out" == "skip=false" ]] && grep -q 'could not read' "$work/reason"; then + pass +else + fail "wanted skip=false when gh fails, got '$out': $(cat "$work/reason" 2>&1)" +fi + +report diff --git a/scripts/CLAUDE.md b/scripts/CLAUDE.md index b6c512ab..2c059f0e 100644 --- a/scripts/CLAUDE.md +++ b/scripts/CLAUDE.md @@ -11,7 +11,7 @@ One flat directory, not a `ci/` and a `scripts/` split: `check` calls `ci` and ` Each script's header comment says what it does and why it is shaped that way, and the lists below say who calls it; each `tests/*-test` header says what that suite covers. Read the header before editing the file. This document holds only the rules that span scripts. - Run by a person: `doctor`, `check`, `fix`, `clean`, `run`, `integration`, `package`, `summarize`, `repo-settings check` -- Called by `.github/`: `ci`, `security`, `release`, `detect`, `changelog-check`, `system-packages`, `script-tests` +- Called by `.github/`: `ci`, `ci-tested`, `security`, `release`, `detect`, `changelog-check`, `system-packages`, `script-tests` - Called by pre-commit: `adr-index`, `structure`, `payload-parity`, `attribute-commit` (`prepare-commit-msg`, and `--check` at `commit-msg`), `changelog-check` and `protect-branch` (`pre-push`), `worktree-cleanup` (`post-checkout`, `post-merge`, and SessionStart with `--report`) - Sourced: `libs/detect.sh`, `libs/result.sh`, `libs/unit.sh`, `libs/precommit.sh`, `libs/dependabot.sh`, `libs/quadlet.sh`, `tests/libs/harness.sh` @@ -25,7 +25,7 @@ Each script's header comment says what it does and why it is shaped that way, an - **An adapter is honest about what it did.** Capture the tool's exit status, not only its output. No function stands in for an absent one: the probe reads `absent` off the function table and the dispatch reports `unavailable`. A runner that exits non-zero without a real failure is translated, and `libs/detect.sh`'s header lists the four. - **`libs/*.sh` and `harness.sh` are sourced, never executed**: no shebang, no executable bit, `.sh`. Every other script is extensionless and executable; pre-commit reads a shebang only on one. - **`adr-index` and `structure` are hooks, not capabilities**, and run `always_run` with no `files:` filter, since staged paths exclude deletions. -- **Local commands stay off hosted GitHub state.** The boundary is hosted state, not connectivity; only `repo-settings check` crosses it. +- **Local commands stay off hosted GitHub state.** The boundary is hosted state, not connectivity; only `repo-settings check` crosses it, and `ci-tested`, which only `ci.yml` calls. ## Work Guidance diff --git a/scripts/check b/scripts/check index c2cb3f0a..0a9c5464 100755 --- a/scripts/check +++ b/scripts/check @@ -20,23 +20,44 @@ cd "$repo_root" # the cause is gone; the log is what a failure outside the table is diagnosed # from. --verbose streams the same text live. --gate is the internal entry that # runs the steps below and nothing else, so the tee wraps exactly one run. -case "${1:-}" in +# +# --fast is the commit-time gate: every step below except build, which CI runs +# on the same commit before it can land and which costs more than the rest of +# the gate together in a repository that compiles. It rides through each entry, +# and tmp/check.log opens by saying build was left out, so a fast run's log +# never reads as the full gate's. +usage() { + echo "usage: scripts/check [--fast] [--verbose]" >&2 + exit 2 +} +mode="" +fast=() +for arg in "$@"; do + case "$arg" in + --verbose | --gate) + [[ -z "$mode" ]] || usage + mode="$arg" + ;; + --fast) fast=(--fast) ;; + *) usage ;; + esac +done +case "$mode" in "") - exec scripts/summarize scripts/check --verbose + exec scripts/summarize scripts/check --verbose "${fast[@]}" ;; --verbose) mkdir -p tmp # pipefail (set above) makes the pipeline's status the gate's, not tee's. - scripts/check --gate 2>&1 | tee tmp/check.log + scripts/check --gate "${fast[@]}" 2>&1 | tee tmp/check.log exit "${PIPESTATUS[0]}" ;; - --gate) ;; - *) - echo "usage: scripts/check [--verbose]" >&2 - exit 2 - ;; esac +if (( ${#fast[@]} )); then + echo "scripts/check --fast: build is left to CI." +fi + if [[ ! -x scripts/doctor ]]; then echo "scripts/doctor is missing or not executable." exit 1 @@ -100,8 +121,12 @@ trap 'exit 130' INT trap 'exit 143' TERM trap 'exit 141' PIPE +ci_args=() +if (( ${#fast[@]} )); then + ci_args=(--no-build) +fi ci_status=0 -scripts/ci || ci_status=$? +scripts/ci "${ci_args[@]}" || ci_status=$? script_tests_status=0 wait "$script_tests_pid" || script_tests_status=$? # Reaped, so its PID may now belong to another process. diff --git a/scripts/ci b/scripts/ci index 8cfae084..eec43ab3 100755 --- a/scripts/ci +++ b/scripts/ci @@ -8,6 +8,19 @@ cd "$repo_root" # shellcheck source=libs/detect.sh source "$repo_root/scripts/libs/detect.sh" +# --no-build leaves build out, for `scripts/check --fast`: the commit-time gate +# drops the slowest check CI repeats on the same commit before it can land. +# CI itself never passes it. +capabilities=(lint format-check typecheck test build) +case "${1:-}" in + "") ;; + --no-build) capabilities=(lint format-check typecheck test) ;; + *) + echo "usage: scripts/ci [--no-build]" >&2 + exit 2 + ;; +esac + # The shared policy: orphan search before the checks, which would run green over # the package none of them sees; the no-manifest early-out; the dry run. -capability_command check lint format-check typecheck test build +capability_command check "${capabilities[@]}" diff --git a/scripts/ci-tested b/scripts/ci-tested new file mode 100755 index 00000000..e806a294 --- /dev/null +++ b/scripts/ci-tested @@ -0,0 +1,39 @@ +#!/usr/bin/env bash +set -euo pipefail + +# Whether a passing pull request run of ci.yml already tested the tree a push to +# the default branch landed, so ci.yml can skip its checks instead of proving +# the same tree twice. Prints `skip=true` or `skip=false` for $GITHUB_OUTPUT +# and the reason on stderr, which the job log keeps. +# +# scripts/ci-tested +# +# A pull request run that passes uploads an artifact named for the tree it +# tested, its merge ref's: ci-tested-tree-. The push skips when an +# unexpired one of those names HEAD's tree, so any merge, squash or +# fast-forward whose result is a tree some run already passed skips, and one +# onto a base that moved since does not. Only the name says the run passed, and +# a pull request can rewrite the workflow that uploads it, so artifacts from a +# fork's run, or with no run at all, are ignored. A branch in this repository +# is trusted the same way: whoever can push one can already push to the +# default branch. +# +# Called by ci.yml alone: it reads hosted run state, which no local command does. +# Every doubt answers skip=false, since running the checks again costs minutes +# and skipping them wrongly leaves the branch unproven. + +decide() { + echo "ci-tested: $2" >&2 + echo "skip=$1" + exit 0 +} + +tree="$(git rev-parse 'HEAD^{tree}')" +count="$(gh api "repos/${GITHUB_REPOSITORY:?}/actions/artifacts?name=ci-tested-tree-$tree&per_page=100" \ + --jq '[.artifacts[] | select((.expired | not) and .workflow_run.repository_id != null + and .workflow_run.head_repository_id == .workflow_run.repository_id)] | length' \ + 2>/dev/null)" || decide false "could not read the tested-tree artifacts" + +[[ "$count" =~ ^[1-9] ]] || + decide false "no passing pull request run tested tree $tree" +decide true "a passing pull request run tested tree $tree, the tree now on the branch" diff --git a/scripts/tests/capabilities-test b/scripts/tests/capabilities-test index 6cd66cde..286e527d 100755 --- a/scripts/tests/capabilities-test +++ b/scripts/tests/capabilities-test @@ -167,6 +167,28 @@ out="$(ci)" assert_dispatches python "$out" assert_absent node "$out" +fixture "--no-build leaves build out and nothing else" +printf '[project]\nname = "p"\nversion = "0.1.0"\n' > "$work/pyproject.toml" +out="$(cd "$work" && CI_DRY_RUN=1 scripts/ci --no-build 2>&1 /dev/null 2>&1 "$work/package.json" out="$(ci)" diff --git a/scripts/tests/check-test b/scripts/tests/check-test index 2135817d..2b2398ed 100755 --- a/scripts/tests/check-test +++ b/scripts/tests/check-test @@ -4,8 +4,8 @@ set -uo pipefail # What scripts/check prints, writes, and exits with. The gate's steps are # stubbed in a scratch copy of the scripts, so the cases assert the wrapper's # contract -- table only by default, the whole run in tmp/check.log every time, -# raw output under --verbose, the gate's own exit status -- and not the output -# of any real check. +# raw output under --verbose, the gate's own exit status, --fast handing ci +# --no-build -- and not the output of any real check. repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" @@ -128,6 +128,55 @@ else fail "wanted the table and exit 0 from a subdirectory, got exit $status: $out" fi +# ci records the arguments it was given, so a case can tell the full gate from +# the fast one without running a real build. +ci_args_fixture() { + gate_fixture "$1" + printf '#!/usr/bin/env bash\necho "ci:$*" > ci-args\necho "lint pass python"\n' \ + > "$work/scripts/ci" +} + +ci_args_fixture "the default gate runs ci whole" +(cd "$work" && scripts/check >/dev/null 2>&1) +if [[ "$(cat "$work/ci-args" 2>&1)" == "ci:" ]]; then + pass +else + fail "wanted ci with no arguments, got: $(cat "$work/ci-args" 2>&1)" +fi + +ci_args_fixture "--fast leaves build to CI and says so in the log" +out="$(cd "$work" && scripts/check --fast 2>&1)" +status=$? +if (( status == 0 )) \ + && [[ "$(cat "$work/ci-args" 2>&1)" == "ci:--no-build" ]] \ + && grep -q 'chatter from security' "$work/tmp/check.log" \ + && grep -q 'build is left to CI' "$work/tmp/check.log" \ + && grep -qE '^lint +pass' <<< "$out"; then + pass +else + fail "wanted ci --no-build, every other step, and the log naming the skip, got exit $status: $out" +fi + +ci_args_fixture "--fast and --verbose combine in either order" +out="$(cd "$work" && scripts/check --fast --verbose 2>&1)" +status=$? +if (( status == 0 )) \ + && [[ "$(cat "$work/ci-args" 2>&1)" == "ci:--no-build" ]] \ + && grep -q 'chatter from doctor' <<< "$out"; then + pass +else + fail "wanted the streamed fast run, got exit $status: $out" +fi + +gate_fixture "two modes are a usage error" +(cd "$work" && scripts/check --verbose --gate >/dev/null 2>&1) +status=$? +if (( status == 2 )); then + pass +else + fail "wanted exit 2, got $status" +fi + gate_fixture "an unknown argument is a usage error" (cd "$work" && scripts/check --bogus >/dev/null 2>&1) status=$? diff --git a/scripts/tests/ci-tested-test b/scripts/tests/ci-tested-test new file mode 100755 index 00000000..43cf9d61 --- /dev/null +++ b/scripts/tests/ci-tested-test @@ -0,0 +1,106 @@ +#!/usr/bin/env bash +set -uo pipefail + +# Whether scripts/ci-tested skips the default branch's checks only when a +# passing pull request run recorded the tree that landed. `gh` is a stub that +# answers the artifacts query with a fixed listing, run through the --jq filter +# it was given as gh would, and records what it was asked. + +repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)" + +# shellcheck source-path=SCRIPTDIR +# shellcheck source=libs/harness.sh +source "$repo_root/scripts/tests/libs/harness.sh" + +echo "ci-tested-test" + +export GITHUB_REPOSITORY=owner/repo + +# A repository with one commit, and a gh stub answering with the artifacts +# listing $2, or failing when $2 is `error`. +fixture() { + scratch_repo + current="$1" + printf '%s\n' "$2" > "$work/listing" + stub gh <> "$work/gh-calls" +[[ "\$(cat "$work/listing")" == error ]] && exit 1 +while (( \$# )); do + [[ "\$1" == --jq ]] && exec jq "\$2" "$work/listing" + shift +done +cat "$work/listing" +STUB + git -C "$work" add -A + git -C "$work" commit -qm base + tree="$(git -C "$work" rev-parse 'HEAD^{tree}')" +} + +decide() { + (cd "$work" && scripts/ci-tested 2>"$work/reason") +} + +# One artifact entry: expired true|false, then the head repository's id against +# the repository's 1. +artifact() { + printf '{"expired": %s, "workflow_run": {"repository_id": 1, "head_repository_id": %s}}' "$1" "$2" +} + +if ! command -v jq >/dev/null 2>&1; then + current="ci-tested" + skip "jq is not installed, and the stub runs gh's --jq filter through it" + report + exit +fi + +fixture "a tree a same-repository run recorded skips" "{\"artifacts\": [$(artifact false 1)]}" +out="$(decide)" +if [[ "$out" == "skip=true" ]] \ + && grep -q "repos/owner/repo/actions/artifacts?name=ci-tested-tree-$tree&" "$work/gh-calls"; then + pass +else + fail "wanted skip=true from a query for tree $tree, got '$out': $(cat "$work/reason" "$work/gh-calls" 2>&1)" +fi + +fixture "a tree no run recorded runs the checks" '{"artifacts": []}' +out="$(decide)" +if [[ "$out" == "skip=false" ]] && grep -q 'no passing pull request run' "$work/reason"; then + pass +else + fail "wanted skip=false, got '$out': $(cat "$work/reason" 2>&1)" +fi + +fixture "an expired record runs the checks" "{\"artifacts\": [$(artifact true 1)]}" +out="$(decide)" +if [[ "$out" == "skip=false" ]]; then + pass +else + fail "wanted skip=false for an expired artifact, got '$out': $(cat "$work/reason" 2>&1)" +fi + +fixture "a record from a fork's run runs the checks" "{\"artifacts\": [$(artifact false 2)]}" +out="$(decide)" +if [[ "$out" == "skip=false" ]]; then + pass +else + fail "wanted skip=false for a fork's artifact, got '$out': $(cat "$work/reason" 2>&1)" +fi + +fixture "a record with no run runs the checks" '{"artifacts": [{"expired": false, "workflow_run": null}]}' +out="$(decide)" +if [[ "$out" == "skip=false" ]]; then + pass +else + fail "wanted skip=false for an artifact with no run, got '$out': $(cat "$work/reason" 2>&1)" +fi + +fixture "a failed query runs the checks" error +out="$(decide)" +if [[ "$out" == "skip=false" ]] && grep -q 'could not read' "$work/reason"; then + pass +else + fail "wanted skip=false when gh fails, got '$out': $(cat "$work/reason" 2>&1)" +fi + +report