diff --git a/.github/workflows/container.yml b/.github/workflows/container.yml index 5be1bd3..5ffc52f 100644 --- a/.github/workflows/container.yml +++ b/.github/workflows/container.yml @@ -89,7 +89,7 @@ jobs: podman run --rm -v "$PWD:/mnt:ro,z" -w /mnt \ docker.io/koalaman/shellcheck:v0.11.0@sha256:61862eba1fcf09a484ebcc6feea46f1782532571a34ed51fedf90dd25f925a8d bin/sdlc tests/contract.sh \ tests/test_host_contract.sh tests/test_container_stack.sh scripts/release-version.sh \ - scripts/revision-of.sh tests/test_revision_of.sh + scripts/revision-of.sh tests/test_revision_of.sh bin/sdlc-bootstrap tests/test_host_contract.sh tests/test_revision_of.sh tests/test_release_version.py @@ -126,7 +126,7 @@ jobs: set -eu for t in tests/test_plan.py tests/test_codeql_globs.py \ tests/test_pycache_prefix.py tests/test_gourmand_sidecar.py \ - tests/test_codeql_resilience.py; do + tests/test_codeql_resilience.py tests/test_convert_repo.py; do podman run --rm -v "$PWD:/src:ro,z" -w /src \ --entrypoint /opt/constitution-venv/bin/python3 \ "localhost/python-sdlc:$GITHUB_SHA" "$t" diff --git a/CHANGELOG.md b/CHANGELOG.md index 40f883d..fc7adab 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,51 @@ All notable changes to this project are documented here, following ## [Unreleased] +### Added + +- **No `rev:` to pin.** The image now carries its own launcher + (`/usr/share/sdlc/launcher`) and prints it with `sdlc launcher `, the + ref written into it. `bin/sdlc-bootstrap` -- committed in a repo as + `.sdlc/bin/sdlc` -- pulls `quay.io/crunchtools/sdlc:${SDLC_IMAGE:-latest}` + when newer, asks it for the launcher and runs it, so a repo's hooks and CI + float with the image and a release needs no bump pull requests. An image + that cannot print its launcher is a 2. `SDLC_IMAGE` there may name only + `quay.io/crunchtools/sdlc` -- `main`, `latest`, `X.Y.Z` or `@sha256:<64 + hex>` -- and anything else is refused with exit 2 before podman runs. `examples/pre-commit-floating.yaml` + and `examples/ci.yml` are the hook and CI forms; the CI job keeps the name + `sdlc ci`, and a repo opts its CI into `:main` with the repository variable + `SDLC_IMAGE`. +- README "When :latest is broken": `--no-verify` locally, the organization + variable `SDLC_IMAGE` set to the last good release for CI, and why that + works only once two releases carry `launcher`. +- `scripts/convert_repo.py`: converts one checkout to the floating form, from + either the rev-pinned python-sdlc hooks or the standalone Gourmand and + Gatehouse hooks. Deterministic; prints the diff and writes nothing without + `--apply`; keeps every workflow the stubs do not cover; never touches + `.specify/`; refuses with exit 2 a shape it would have to guess at. Every + file it would write is parsed back and held to the floating wiring before + anything is written, and a second run is a no-op. + +- `container-smoke` SKIPS an image whose PID 1 is systemd (`/sbin/init`, + `/usr/sbin/init`, `systemd`, as in ubi-init and bootc images): systemd needs + privileges the smoke run withholds on purpose. The run says why and prints + `SKIPPED, not judged`, never `passed`; the build and the scan still run. The + check's record carries exit 4. Only the smoke run can skip: a 4 from a tool + in the image is still a finding. + +### Changed + +- `containerfile-lint` without a `.hadolint.yaml` now fails at `error`, not + `warning`, and ignores DL3007 (floating base tags) and DL3041 (unpinned dnf + packages), which the fleet does on purpose. Warnings such as DL3002 are + printed and do not fail. A repo's `.hadolint.yaml` replaces these defaults. + +### Fixed + +- `container-smoke` removes the smoke container with `-v`, so an image that + declares a `VOLUME` no longer leaks an anonymous volume on every run. A fleet + measurement filled a seat's disk with 13 GB of them. + ## [0.8.0] - 2026-11-17 ### Added diff --git a/Containerfile b/Containerfile index cdbf29c..39d046a 100644 --- a/Containerfile +++ b/Containerfile @@ -210,6 +210,12 @@ COPY sdlc /usr/local/bin/sdlc COPY validate /usr/local/bin/sdlc-validate RUN chmod 0755 /usr/local/bin/sdlc /usr/local/bin/sdlc-validate +# The host launcher rides in the image it starts, so a repo with no `rev:` gets +# it with `sdlc launcher ` (bin/sdlc-bootstrap) and it floats with the tag. +# Data here, not a program: it runs on the host, never in this container. +COPY bin/sdlc /usr/share/sdlc/launcher +COPY bin/sdlc-bootstrap /usr/share/sdlc/bootstrap + # Stays root, and WORKDIR /repo, because that is what Gourmand and Gatehouse do # and those two have been getting code into a container for analysis across this # fleet for a year. Copying their convention rather than inventing one: diff --git a/README.md b/README.md index d955767..cfb85fa 100644 --- a/README.md +++ b/README.md @@ -49,37 +49,63 @@ replace it. ## Wiring a repo -`.pre-commit-config.yaml`, the whole file: +A repo carries one file, `.sdlc/bin/sdlc` (this repo's `bin/sdlc-bootstrap`), +and pins nothing. The launcher ships inside `quay.io/crunchtools/sdlc`; the +bootstrap asks the image for it (`sdlc launcher `, which writes that ref +into it) and runs it. So the launcher, the image and every tool inside it float +together on `:latest`, for the laptop and CI both, and a release reaches every +repo without a pull request. + +`.pre-commit-config.yaml` is +[`examples/pre-commit-floating.yaml`](examples/pre-commit-floating.yaml): two +`language: system` hooks, `.sdlc/bin/sdlc commit` and `.sdlc/bin/sdlc push`. +CI is [`examples/ci.yml`](examples/ci.yml), whose job is still named `sdlc ci`, +so the required check does not change: + +```yaml + - name: sdlc ci + env: + SDLC_IMAGE: ${{ vars.SDLC_IMAGE }} + run: .sdlc/bin/sdlc ci +``` + +`scripts/convert_repo.py ` converts a repo wired the old way -- the +rev-pinned hooks below, or the standalone Gourmand and Gatehouse hooks -- and +prints the diff; `--apply` writes it. It replaces a workflow only when the CI +stub covers every job in it (`sdlc ci`, Gourmand), refreshes `gatehouse.yml` +from [`examples/gatehouse.yml`](examples/gatehouse.yml) when it differs only in +comments, keeps everything else (publish, release, container builds), and +refuses with exit 2 a shape it would have to guess at. + +**What floating trusts.** Whoever can move `quay.io/crunchtools/sdlc:latest` +now decides the host-side code every seat and runner runs, and that code is no +longer read in git at a pinned rev before it runs. Only this repo's release +workflow, after the contract test, moves the tag, and never backwards. Signing +the image and verifying it on pull (a `policy.json` sigstore entry for +`quay.io/crunchtools/sdlc`) would close the rest, and is not done yet. + +**An `sdlc` RPM, later.** It installs the same bootstrap as `/usr/bin/sdlc` on +hosts and seats, so a person can type `sdlc tiers` anywhere. Nothing in a repo +changes when it lands: the hooks keep starting the repo's own copy, which is +identical, and the RPM never needs a release of its own, because the launcher +it fetches floats with the image. + +The rev-pinned form still works, and is what a repo has until it converts: ```yaml default_install_hook_types: [pre-commit, pre-push] repos: - repo: https://github.com/crunchtools/python-sdlc - rev: v0.3.4 + rev: v0.8.0 hooks: - id: sdlc-commit - id: sdlc-push ``` -CI, one job, which reads the release from that same `rev:`: - -```yaml - sdlc: - name: sdlc ci - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v7 - - name: sdlc ci - run: | - rev=$(awk '/repo: https:\/\/github.com\/crunchtools\/python-sdlc/ {f=1; next} - f && /rev:/ {print $2; exit}' .pre-commit-config.yaml) - git clone -q --depth 1 --branch "$rev" https://github.com/crunchtools/python-sdlc "$RUNNER_TEMP/sdlc" - $RUNNER_TEMP/sdlc/bin/sdlc ci -``` - -That `rev:` pins the launcher, the image and every tool inside it, for the -laptop and CI both. One pin. +with a CI step that clones this repo at that `rev:` and runs +`$RUNNER_TEMP/sdlc/bin/sdlc ci`. That `rev:` pins the launcher, the image and +every tool inside it. ### A project in a subdirectory @@ -136,9 +162,9 @@ refused. | Check | Command | What it does | |---|---|---| -| `containerfile-lint` | push, ci | hadolint over the Containerfile; the repo's `.hadolint.yaml` applies, and without one the threshold is `warning` | +| `containerfile-lint` | push, ci | hadolint over the Containerfile. Without a `.hadolint.yaml` the threshold is `error` and DL3007 (floating base tags) and DL3041 (unpinned dnf) are ignored, as fleet conventions; warnings such as DL3002 are printed and do not fail. A repo's `.hadolint.yaml` replaces all of that | | `container-build` | ci | `podman build`, at the tag the next two read | -| `container-smoke` | ci | starts the built image detached, with no network and no capabilities, and reads its state from podman: still running after `seconds`, or exited 0, passes; any other exit, the OOM killer, or an entrypoint that cannot start (126/127) fails | +| `container-smoke` | ci | starts the built image detached, with no network and no capabilities, and reads its state from podman: still running after `seconds`, or exited 0, passes; any other exit, the OOM killer, or an entrypoint that cannot start (126/127) fails. An image whose PID 1 is systemd (`/sbin/init`, `systemd`) is SKIPPED with its reason: systemd needs privileges the run withholds | | `container-scan` | ci | grype over the built image's filesystem, mounted read-only by podman; fails on a fixable Critical by default, and the repo's `.grype.yaml` applies | Build, smoke and scan are one lane, beside everything else. @@ -224,6 +250,10 @@ worktree: $ jq -r '.checks[] | "\(.seconds)s \(.check) exit \(.exit)"' .git/sdlc/last-push.json ``` +A check's `exit` is its status: 0 passed, 1 found something, 2 could not run, +3 deferred to CI, and 4 SKIPPED, which only `container-smoke` reports, for a +systemd PID 1 it cannot boot. A 4 never decides the command's own exit. + The checks appear in the order they **finished**, which with lanes is not the order they were listed in. A check that streamed to your terminal has no log file: the terminal had it. @@ -338,7 +368,12 @@ It is the digest the contract test ran against at `:`, read back after the copy, and it never moves back onto an older commit. Only a release moves `latest` and the version tags, and no pull request run touches a registry at all. The release is the gate. -To run one on your machine, first matching wins: +A floating repo opts its CI into `:main` with the repository variable +`SDLC_IMAGE=main` -- a setting only an admin can change, rather than a one-line +edit a pull request could slip in. It is not a wall: a pull request from a +branch can still edit `ci.yml` or `.sdlc/bin/sdlc` themselves, as it always +could edit its workflows; an org ruleset's required workflow is what would +close that. To run one on your machine, first matching wins: | How | Value | |---|---| @@ -357,8 +392,31 @@ planner runs inside whichever image was chosen. **Nothing built on a laptop or a seat is ever pushed.** To try a change to this image before it merges, build it locally (`podman build -t localhost/python-sdlc:dev .`) and run it with -`SDLC_IMAGE=localhost/python-sdlc:dev`. `sdlc` has no push step, and only this -repo's GitHub Actions on main publish to quay.io. +`SDLC_IMAGE=localhost/python-sdlc:dev` through this clone's `bin/sdlc`. A +converted repo's `.sdlc/bin/sdlc` will not take it: the bootstrap runs what it +pulls, so it pulls only `quay.io/crunchtools/sdlc` at `main`, `latest`, a +release `X.Y.Z` or `@sha256:`, and refuses anything else with exit 2. +`sdlc` has no push step, and only this repo's GitHub Actions on main publish to +quay.io. + +## When :latest is broken + +A floating repo runs whatever `:latest` is, so a bad release reaches every repo +at once. Until a fixed release ships: + +- **A local commit or push:** `git commit --no-verify` / `git push --no-verify`. + CI still judges the pull request. +- **CI, fleet-wide:** set the organization variable `SDLC_IMAGE` to the last + good release, `X.Y.Z`. Every floating repo's CI picks it up on its next run, + with no pull request; a repository variable of the same name does the same + for one repo. Clear it once the fix is on `:latest`. +- **A seat:** `SDLC_IMAGE=X.Y.Z git push`. + +The fallback needs a release that carries the launcher. The bootstrap asks the +image for it, so a tag older than the first release with `sdlc launcher` cannot +be pinned this way: it exits 2. +Rolling back works only once two releases carry `launcher` -- the broken one +and a good one before it. ## Skipping a check diff --git a/bin/sdlc b/bin/sdlc index f2cd005..2b77081 100755 --- a/bin/sdlc +++ b/bin/sdlc @@ -32,7 +32,12 @@ set -eu ME=$(basename "$0") -HOOKS_DIR=$(CDPATH='' cd -- "$(dirname -- "$0")/.." && pwd) + +# The image this file came from, when it came from one. `sdlc launcher `, +# run inside quay.io/crunchtools/sdlc, prints this file with the ref written on +# the next line; that is how a repo with no `rev:` gets its launcher +# (bin/sdlc-bootstrap). Empty in a clone of python-sdlc, which pins by IMAGE_TAG. +LAUNCHED_FROM= die() { printf '%s: GATE CANNOT RUN: %s\n' "$ME" "$*" >&2; exit 2; } fail() { printf '%s: GATE FAILED: %s\n' "$ME" "$*" >&2; exit 1; } @@ -40,16 +45,26 @@ step() { printf '\n== %s\n' "$*"; } # ------------------------------------------------------------------ the image -[ -f "$HOOKS_DIR/IMAGE_TAG" ] || die "$HOOKS_DIR/IMAGE_TAG is missing" -IMAGE_TAG=$(tr -d ' \t\n\r' < "$HOOKS_DIR/IMAGE_TAG") -[ -n "$IMAGE_TAG" ] || die "IMAGE_TAG is empty" -# Read from the cloned hooks repo, so the `rev:` a repo pins fixes the launcher -# and the image together and they cannot disagree. An override -- below, once -# the repo is known -- replaces it for the inner loop, and says so every run. -DEFAULT_IMAGE=quay.io/crunchtools/python-sdlc:$IMAGE_TAG -# The fleet image: releases at their version tags, and `:main`, which is what -# has merged to main and not yet been released. +# The fleet image: releases at their version tags, `:latest` the newest of +# them, and `:main`, which is what has merged to main and not yet been released. FLEET_IMAGE=quay.io/crunchtools/sdlc +if [ -n "$LAUNCHED_FROM" ]; then + # Floating: the launcher and the image are one artifact, so the image that + # printed this file is the one it runs. The release it floats on is :latest. + DEFAULT_IMAGE=$LAUNCHED_FROM + RELEASE_IMAGE=$FLEET_IMAGE:latest +else + HOOKS_DIR=$(CDPATH='' cd -- "$(dirname -- "$0")/.." && pwd) + [ -f "$HOOKS_DIR/IMAGE_TAG" ] || die "$HOOKS_DIR/IMAGE_TAG is missing" + IMAGE_TAG=$(tr -d ' \t\n\r' < "$HOOKS_DIR/IMAGE_TAG") + [ -n "$IMAGE_TAG" ] || die "IMAGE_TAG is empty" + # Read from the cloned hooks repo, so the `rev:` a repo pins fixes the + # launcher and the image together and they cannot disagree. An override -- + # below, once the repo is known -- replaces it for the inner loop, and says + # so every run. + DEFAULT_IMAGE=quay.io/crunchtools/python-sdlc:$IMAGE_TAG + RELEASE_IMAGE=$DEFAULT_IMAGE +fi # --------------------------------------------------------------- preconditions @@ -111,6 +126,7 @@ if [ -n "$SDLC_CONFIG_IMAGE" ]; then fi IMAGE=$DEFAULT_IMAGE IMAGE_FROM= +[ -z "$LAUNCHED_FROM" ] || IMAGE_FROM="the image that printed this launcher" if [ -n "${SDLC_IMAGE:-}" ]; then case "$SDLC_IMAGE" in */*) IMAGE=$SDLC_IMAGE ;; @@ -124,12 +140,14 @@ fi PULL_NEWER= if [ "$IMAGE" != "$DEFAULT_IMAGE" ]; then case "$IMAGE" in localhost/*) ;; *) PULL_NEWER=yes ;; esac +fi +if [ "$IMAGE" != "$RELEASE_IMAGE" ]; then { printf '%s: ************************************************************\n' "$ME" printf '%s: NOT THE PINNED RELEASE. This run is judged by\n' "$ME" printf '%s: %s\n' "$ME" "$IMAGE" printf '%s: set by %s, in place of\n' "$ME" "$IMAGE_FROM" - printf '%s: %s\n' "$ME" "$DEFAULT_IMAGE" + printf '%s: %s\n' "$ME" "$RELEASE_IMAGE" printf '%s: ************************************************************\n' "$ME" } >&2 fi @@ -557,6 +575,26 @@ check_image_word() { # run-args -> dies unless the word after `--` is an image return 0 } +pid1_of() { # run-args -> what the container would start as PID 1 + # The image's entrypoint if it has one; else the run's first argument, which + # replaces CMD; else the CMD. Empty when podman cannot say, and then the run + # goes ahead and is judged as any other. + _pafter= + _pimg= + _parg= + for _pw in "$@"; do + if [ -n "$_pimg" ]; then _parg=$_pw; break; fi + if [ "$_pafter" = yes ]; then _pimg=$_pw; continue; fi + [ "$_pw" = -- ] && _pafter=yes + done + _pep=$(podman image inspect --format '{{range .Config.Entrypoint}}{{println .}}{{end}}' \ + "$_pimg" 2>/dev/null | head -1) + if [ -n "$_pep" ]; then printf '%s' "$_pep"; return 0; fi + if [ -n "$_parg" ]; then printf '%s' "$_parg"; return 0; fi + podman image inspect --format '{{range .Config.Cmd}}{{println .}}{{end}}' \ + "$_pimg" 2>/dev/null | head -1 +} + run_up() { # seconds run-args -> the smoke verdict # A `podman run` that may be a service. It starts detached, and its STATE is # asked once a second for up to : still running at the end passes, @@ -571,6 +609,17 @@ run_up() { # seconds run-args -> the smoke verdict _upsecs=$1; shift case " $* " in *" -- "*) ;; *) die "a run given time to stay up must name its image after '--'" ;; esac check_image_word "$@" + # A systemd PID 1 (ubi-init, bootc) needs capabilities and a cgroup mount + # this run withholds on purpose, so it dies whatever the image is like. That + # is not judged: 4 is SKIPPED, printed as such, and never a pass. The build + # and the scan are separate checks and still run. + _pid1=$(pid1_of "$@") + case "$_pid1" in + /sbin/init|/usr/sbin/init|/lib/systemd/systemd|/usr/lib/systemd/systemd|init|systemd) + printf '%s: SKIPPED: the image starts %s as PID 1, and systemd PID 1 needs privileges smoke cannot grant\n' \ + "$ME" "$_pid1" >&2 + return 4 ;; + esac _cname=sdlc-smoke-$$-$(now_s) _uprc=0 podman --events-backend=none run -d --name "$_cname" --log-driver=k8s-file \ @@ -580,13 +629,13 @@ run_up() { # seconds run-args -> the smoke verdict case "$_uprc" in 0) ;; # 125 is podman itself: the container never existed, nothing was judged. - 125) podman rm -f "$_cname" >/dev/null 2>&1 || : + 125) podman rm -f -v "$_cname" >/dev/null 2>&1 || : printf '%s: podman could not create the container (exit 125); nothing was judged\n' "$ME" >&2 return 2 ;; # 126/127 is the image: an entrypoint that is missing or cannot execute, # which is exactly what a smoke run exists to catch. *) podman logs "$_cname" 2>&1 || : - podman rm -f "$_cname" >/dev/null 2>&1 || : + podman rm -f -v "$_cname" >/dev/null 2>&1 || : printf '%s: the image could not start its entrypoint (exit %s)\n' "$ME" "$_uprc" >&2 return 1 ;; esac @@ -600,7 +649,7 @@ run_up() { # seconds run-args -> the smoke verdict _upstate=$(podman inspect --format '{{.State.Running}} {{.State.ExitCode}} {{.State.OOMKilled}}' \ "$_cname" 2>/dev/null) || _upstate= podman logs "$_cname" 2>&1 || : - podman rm -f "$_cname" >/dev/null 2>&1 || : + podman rm -f -v "$_cname" >/dev/null 2>&1 || : case "$_upstate" in 'true '*) printf 'still running after %ss: the image starts and stays up\n' "$_upsecs"; return 0 ;; *' true') printf '%s: the container was killed for memory\n' "$ME" >&2; return 1 ;; @@ -667,6 +716,9 @@ run_step() { # mode payload -> the step's exit status _run_step "$@" || _rs=$? # Only a push may defer to CI. Anything else that reports 3 could not run. if [ "$_rs" -eq 3 ] && [ "${SDLC_TIER:-}" != push ]; then return 2; fi + # Only run_up may skip, and only by its own decision. A tool inside a check + # exiting 4 found something, as it always has. + if [ "$_rs" -eq 4 ] && [ "$1" != host-up ]; then return 1; fi return "$_rs" } @@ -700,6 +752,7 @@ _close_serial() { # the open check is finished: footer and record # Only a PASS prints here. A failure has already said so, at the moment it # happened, rather than when the next check starts. [ "$_scur_rc" -eq 0 ] && printf '\n== %s passed in %ss\n' "$_scur" "$_scur_took" + [ "$_scur_rc" -eq 4 ] && printf '\n== %s SKIPPED, not judged, after %ss\n' "$_scur" "$_scur_took" record_check "$_scur" "$_scur_rc" "$_scur_took" "" _scur= } @@ -742,6 +795,8 @@ run_serial() { # the plan -> its worst step status _failed="$_failed $_check" _scur_rc=3 deferred "$_check" + elif [ "$_rc" -eq 4 ]; then + _scur_rc=4 elif [ "$_rc" -ne 0 ]; then _failed="$_failed $_check" _scur_rc=$_rc @@ -807,6 +862,8 @@ _close_check() { # the open check's block is complete # and then the run -- ended with two, the first of them "passed in 0s". if [ "$_cur_rc" -eq 0 ]; then printf '\n== %s passed in %ss\n' "$_cur_name" "$_cur_took" >> "$OUT/out.$_cur" + elif [ "$_cur_rc" -eq 4 ]; then + printf '\n== %s SKIPPED, not judged, after %ss\n' "$_cur_name" "$_cur_took" >> "$OUT/out.$_cur" elif [ "$_cur_rc" -eq 3 ]; then deferred "$_cur_name" 2>> "$OUT/out.$_cur" else @@ -867,6 +924,8 @@ run_lane() { # lane-index steps-file lane-cpus -> the lane's worst if [ "$_rc" -eq 3 ]; then _failed="$_failed $_check" _cur_rc=3 + elif [ "$_rc" -eq 4 ]; then + _cur_rc=4 elif [ "$_rc" -ne 0 ]; then _failed="$_failed $_check" _cur_rc=$_rc diff --git a/bin/sdlc-bootstrap b/bin/sdlc-bootstrap new file mode 100755 index 0000000..6fbb342 --- /dev/null +++ b/bin/sdlc-bootstrap @@ -0,0 +1,62 @@ +#!/bin/sh +# Run `sdlc` with no `rev:` to pin: get the launcher from the image, then run it. +# +# The launcher (bin/sdlc) ships inside quay.io/crunchtools/sdlc, so it floats +# with the image tag exactly as the tools in the image do: `:latest` by +# default, SDLC_IMAGE=main for what has merged and not been released, a +# release such as SDLC_IMAGE=0.9.0, or SDLC_IMAGE=@sha256:. Nothing +# else: this file runs whatever it pulls, so it pulls from that one repository. +# A seat trying a local build runs a python-sdlc clone's bin/sdlc instead. The +# image prints the launcher with its own ref written into it (`sdlc launcher +# `), so the launcher and the image it starts cannot disagree. +# +# A converted repo carries this file as .sdlc/bin/sdlc, and its hooks and its +# CI job run it (scripts/convert_repo.py writes it). Nothing in it names a +# release, so nothing ever bumps it, and the constitution pins its bytes. An +# `sdlc` RPM would install the same file as /usr/bin/sdlc. +# +# Host contract: podman and POSIX sh, nothing else. Never a pipe into `sh`: a +# failed pull would hand sh nothing, and nothing runs and exits 0. An image +# that cannot print its launcher is a 2 -- the gate could not run. + +set -u + +FLEET=quay.io/crunchtools/sdlc +refuse() { + printf 'sdlc: GATE CANNOT RUN: SDLC_IMAGE=%s is not main, latest, X.Y.Z or @sha256:<64 hex> of %s\n' \ + "${SDLC_IMAGE:-}" "$FLEET" >&2 + exit 2 +} + +# The value, with the repository named in full or not at all. +want=${SDLC_IMAGE:-latest} +case $want in + "$FLEET":*) want=${want#"$FLEET":} ;; + "$FLEET"@*) want=${want#"$FLEET"} ;; +esac +case $want in + main|latest) image=$FLEET:$want ;; + @sha256:*) + hex=${want#@sha256:} + case $hex in *[!0-9a-f]*) refuse ;; esac + [ "${#hex}" -eq 64 ] || refuse + image=$FLEET$want ;; + *[!0-9.]*|.*|*.|*..*|*.*.*.*) refuse ;; + *.*.*) image=$FLEET:$want ;; + *) refuse ;; +esac + +dir=$(mktemp -d) || exit 2 +trap 'rm -rf "$dir"' EXIT +trap 'exit 2' HUP INT TERM + +# --pull=newer: :latest moves, and a stale local copy is how a two-week-old +# reviewer once judged trentina. Offline, podman keeps the copy it has. +if ! podman --events-backend=none run --rm --log-driver=none --network=none \ + --cap-drop=all --security-opt=no-new-privileges --pull=newer \ + -- "$image" launcher "$image" > "$dir/sdlc" || [ ! -s "$dir/sdlc" ]; then + printf 'sdlc: GATE CANNOT RUN: %s could not print its launcher\n' "$image" >&2 + exit 2 +fi +# The launcher reads SDLC_IMAGE too; it gets the full reference checked here. +SDLC_IMAGE=$image sh "$dir/sdlc" "$@" diff --git a/examples/ci.yml b/examples/ci.yml new file mode 100644 index 0000000..3af87ab --- /dev/null +++ b/examples/ci.yml @@ -0,0 +1,52 @@ +# The repo's own checks, from quay.io/crunchtools/sdlc -- the same image, the +# same launcher and the same commands the laptop's hooks run, so a green push +# predicts a green CI (constitution XII). Nothing here pins a release: the +# image prints its own launcher, and both float on :latest. +# +# The variable SDLC_IMAGE -- a repository's, or the organization's for the +# whole fleet -- picks other tooling: `main` for what has merged to python-sdlc +# and not been released, or a release such as `0.9.0` to hold one back. A +# variable, which only an admin sets, rather than a line a pull request could +# change in passing. +# +# Gourmand runs as its own job, not inside `sdlc ci`: XII has CI run push's +# checks except Gourmand and Gatehouse, which run through their own workflows +# (Gatehouse: gatehouse.yml). +# +# The job NAME `sdlc ci` is the required check in the org ruleset "Python SDLC +# gates", and the Gourmand job keeps the name its own workflow gave it. Renaming +# a job stops it gating, silently. +# +# python-sdlc's examples/ci.yml, written by scripts/convert_repo.py. Copy it +# unchanged. + +name: CI + +on: + push: + branches: [main, master] + pull_request: + workflow_dispatch: + +permissions: + contents: read + +jobs: + sdlc: + name: sdlc ci + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + + # .sdlc/bin/sdlc is python-sdlc's bin/sdlc-bootstrap: it asks the image + # for its launcher and runs it, as the hooks do. + - name: sdlc ci + env: + SDLC_IMAGE: ${{ vars.SDLC_IMAGE }} + run: .sdlc/bin/sdlc ci + + gourmand: + name: Code Quality (Gourmand) + uses: crunchtools/gatehouse/.github/workflows/gourmand.yml@v0 diff --git a/examples/gatehouse.yml b/examples/gatehouse.yml new file mode 100644 index 0000000..f0a31d7 --- /dev/null +++ b/examples/gatehouse.yml @@ -0,0 +1,121 @@ +# Gatehouse — fork-safe code review + workflow protection, in ONE file. +# +# Drop this in your repo at .github/workflows/gatehouse.yml, add a OPENROUTER_API_KEY +# secret, and you get: +# • AI review of every PR (including from forks) — posted as a PR review +# • rejection of untrusted PRs that try to modify your workflow files +# +# Nothing is ever checked out from the PR. The fork's change is only ever read as +# a diff (data); the reviewer logic lives in the pinned gatehouse container; the +# rules (your styleguide/constitution) are fetched from YOUR base branch, not the +# PR. The one thing you don't trust — the proposed change — is only ever read. +# +# Three jobs with DIFFERENT authority: +# • guard — a real blocking gate. Mark it a REQUIRED status check so a PR +# that tampers with your workflow files is rejected. +# • review — ADVISORY. It posts findings as PR comments and no finding +# fails it; it fails only when the review did not happen: +# fewer than half of the agents finished (provider down, +# key refused), or the reviewer could not run at all. Do +# NOT mark it required. An LLM reviewer is non-deterministic, +# so it must never hold merge authority. (Opt into blocking with +# `blocking: true` below only if you accept that tradeoff — and +# even then, keep it out of branch protection.) +# • triage — deterministic. Fails while any finding has no answer +# (`fixed in `, `not a bug: ` or +# `deferred: `), or while the +# last review did not finish. Safe to mark +# REQUIRED: it never judges code, only whether a human answered. + +name: Gatehouse + +on: + pull_request_target: + types: [opened, synchronize, reopened] + # A reply rings the doorbell: this run's own checks do not count toward + # branch rules, so gatehouse-retriage.yml answers it by re-running + # triage inside the pull_request_target run. Add that file too. + pull_request_review_comment: + types: [created, edited, deleted] + +permissions: {} # default-deny; each job grants only what it needs + +jobs: + # ── 1) Protect the workflow files themselves ──────────────────────────────── + # Rejects PRs from forks that touch .github/workflows/. Safe under + # pull_request_target because it only reads the changed-file LIST via the + # API — it never checks out or runs your code. And because pull_request_target + # runs the BASE version of this file, a PR can't edit this job to disable it. + guard: + name: Protect workflows + # Runs on replies too. A job skipped on the reply event reports + # "skipped", which a required check counts as passing: skipping the + # guard there would let any comment on a rejected fork PR clear it. + runs-on: ubuntu-latest + permissions: + contents: read + pull-requests: write + steps: + - name: Reject workflow changes from untrusted PRs + env: + GH_TOKEN: ${{ github.token }} + EVENT: ${{ github.event_name }} + PR: ${{ github.event.pull_request.number }} + HEAD_REPO: ${{ github.event.pull_request.head.repo.full_name }} + run: | + set -euo pipefail + # Gate on where the branch lives, not on the author's role: a branch + # pushed into this repo already required write access, and a fork is + # what pull_request_target actually guards against. + if [ "$HEAD_REPO" = "$GITHUB_REPOSITORY" ]; then + echo "Head branch is in $GITHUB_REPOSITORY; allowing."; exit 0 + fi + # Both sides of a rename: `gh pr diff --name-only` lists only the new + # path, so a fork could move a workflow out of .github/workflows/ unseen. + changed="$(gh api --paginate "repos/$GITHUB_REPOSITORY/pulls/$PR/files" \ + --jq '.[] | .filename, (.previous_filename // empty)')" + if echo "$changed" | grep -qE '^\.github/workflows/'; then + echo "::error::PR modifies .github/workflows/ — not accepted from external contributors." + # Explain once, on the PR event; replies re-run the check, not the comment. + if [ "$EVENT" = "pull_request_target" ]; then + gh pr comment "$PR" --repo "$GITHUB_REPOSITORY" --body \ + $'🚫 **Workflow changes are not accepted via pull request.** Please open an issue and a maintainer will make the change.' + fi + exit 1 + fi + echo "No workflow files changed." + + # ── 2) Review the PR diff (no checkout, BYO key) ──────────────────────────── + # The reviewer is maintained centrally in gatehouse's reusable workflow and the + # container it names, called at the major tag — so a fix reaches you with no + # change to this file. + # Scope OPENROUTER_API_KEY to this reusable workflow so only it can read the key. + review: + name: Gatehouse review + if: github.event_name == 'pull_request_target' + permissions: + contents: read + pull-requests: write + uses: crunchtools/gatehouse/.github/workflows/review.yml@v0 + # Advisory by default — findings post as comments and never fail the check. + # Uncomment to let critical/high findings fail the check (still not required): + # with: + # blocking: true + secrets: + OPENROUTER_API_KEY: ${{ secrets.OPENROUTER_API_KEY }} + + # ── 3) Every finding answered ────────────────────────────────────────────── + # Runs after the review on a push, and alone on a reply (review is skipped + # then, hence always()). Read-only, no secrets. LOW findings need an answer + # only from Bug Hunter and Security Scan; other LOWs are advisory. To change + # which agents' LOWs are required (agent names, comma-separated), set the + # same list here and on the review job above, so the review posts them all: + # with: + # required_low_agents: "Bug Hunter,Security Scan,Test Coverage" + triage: + name: Gatehouse triage + needs: review + if: always() + permissions: + pull-requests: read + uses: crunchtools/gatehouse/.github/workflows/triage.yml@v0 diff --git a/examples/pre-commit-floating.yaml b/examples/pre-commit-floating.yaml new file mode 100644 index 0000000..36c99b3 --- /dev/null +++ b/examples/pre-commit-floating.yaml @@ -0,0 +1,36 @@ +# Every check runs from quay.io/crunchtools/sdlc (constitution XII). Nothing +# here pins it: .sdlc/bin/sdlc asks the image for its own launcher and runs it, +# so the launcher, the image and every tool inside it float together on +# :latest -- for this laptop and, through .github/workflows/ci.yml, for CI. +# There is no `rev:` to bump, ever. +# +# SDLC_IMAGE=main git push judges this push with what has merged to +# python-sdlc and not been released. A repo opts +# its CI in with the repository variable SDLC_IMAGE. +# +# What each hook runs is configured in pyproject.toml ([tool.sdlc.commit], +# [tool.sdlc.push], [tool.sdlc.ci]) or, in a repo with no pyproject.toml, +# sdlc.toml. `.sdlc/bin/sdlc tiers` prints it. +# +# `default_install_hook_types` must name both: without pre-push, `pre-commit +# install` wires only the commit hook and every verdict silently stops running. + +default_install_hook_types: [pre-commit, pre-push] + +repos: + - repo: local + hooks: + - id: sdlc-commit + name: sdlc commit + entry: .sdlc/bin/sdlc commit + language: system + pass_filenames: false + always_run: true + stages: [pre-commit, pre-merge-commit] + - id: sdlc-push + name: sdlc push + entry: .sdlc/bin/sdlc push + language: system + pass_filenames: false + always_run: true + stages: [pre-push] diff --git a/gatehouse-findings.toml b/gatehouse-findings.toml index 69fbbb7..b344f55 100644 --- a/gatehouse-findings.toml +++ b/gatehouse-findings.toml @@ -53,3 +53,21 @@ language is stable across every version the fleet ships. Pinning it would \ freeze a CVE-bearing RPM into the gate image for no gain in reproducibility \ that the digest-addressed release does not already provide. """ + +[[findings]] +agent = "constitution" +category = "constitution" +file = "bin/sdlc-bootstrap" +evidence = "image=${SDLC_IMAGE:-latest}\ncase $image in\n */*) ;;\n *) image=quay.io/crunchtools/sdlc:$image ;;" +status = "not-a-bug" +reason = """ +Floating on :latest is the decision this file implements, not a slip: the \ +fleet operator decided (a206) that nothing in a repo pins the launcher any \ +more and that it floats with :latest exactly as the tools already do, so the \ +conversion is the last fleet-wide pull-request wave. The pin moves from each \ +repo to the release gate: only a tagged, contract-tested release moves \ +:latest (container.yml promote), it never moves backwards, and a repo can hold \ +a release back with the repository variable SDLC_IMAGE. The constitution's \ +XII wording still describes the rev pin; amending it is the constitution \ +repo's change, flagged with this work rather than made here. +""" diff --git a/pyproject.toml b/pyproject.toml index 44702a8..1bc18a4 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -55,3 +55,6 @@ max-complexity = 10 # bytecode anywhere near it, and reading it any other way would not be a copy # of the behaviour under test. "tests/*" = ["S101", "PT018", "S302"] +# Its fixtures are the fleet's files byte for byte, long lines included: the +# script matches the pinned CI step exactly, so a wrapped copy tests nothing. +"tests/test_convert_repo.py" = ["S101", "E501"] diff --git a/scripts/convert_repo.py b/scripts/convert_repo.py new file mode 100755 index 0000000..17712ca --- /dev/null +++ b/scripts/convert_repo.py @@ -0,0 +1,590 @@ +#!/usr/bin/env python3 +"""Convert one repo to the floating sdlc: no `rev:` to pin, ever again. + +Rewrites a checkout so its gates come from quay.io/crunchtools/sdlc:latest +with nothing in the repo naming a release -- which makes the PR wave that +applies this the last one: what the gates run changes when the image does. + + .sdlc/bin/sdlc python-sdlc's bin/sdlc-bootstrap: asks the image for + its launcher and runs it. The one file a converted + repo carries; it names no release, so nothing bumps it + .pre-commit-config.yaml the rev-pinned python-sdlc hooks, and the standalone + Gourmand and Gatehouse hooks, become the two hooks of + examples/pre-commit-floating.yaml, which run it + .github/workflows/ a workflow whose every job the stubs cover -- the + `sdlc ci` job, the Gourmand job -- is replaced by + examples/ci.yml; gatehouse.yml becomes + examples/gatehouse.yml when it differs from it only in + comments. Everything else (publish, release, a + container build) is kept. An `sdlc ci` job that + shares its workflow with jobs the stub does not cover + keeps its place and has its step rewritten instead. + any image reference quay.io/crunchtools/python-sdlc becomes + quay.io/crunchtools/sdlc, in workflows and config + +Deterministic and offline: the same checkout gives the same diff. It prints +that diff and changes nothing without --apply. It never touches .specify/, +the per-repo constitution. + +Exit 0 when it converted (or there was nothing to do), 2 when the repo has a +shape it will not guess at -- named, so it can be converted by hand. + +Usage: scripts/convert_repo.py REPO_DIR [--apply] +Needs PyYAML, to read the workflows; it never writes YAML, only text. +""" + +from __future__ import annotations + +import argparse +import difflib +import re +import sys +from pathlib import Path + +try: + import yaml +except ImportError: # the image's constitution venv has it; main() says so + yaml = None + +ROOT = Path(__file__).resolve().parent.parent +EXAMPLES = ROOT / "examples" +HOOKS_TEMPLATE = EXAMPLES / "pre-commit-floating.yaml" +CI_TEMPLATE = EXAMPLES / "ci.yml" +GATEHOUSE_TEMPLATE = EXAMPLES / "gatehouse.yml" +BOOTSTRAP = ROOT / "bin" / "sdlc-bootstrap" +# Where a converted repo keeps the bootstrap. A path, because the constitution's +# host contract lets a `system` hook start a script in the repo named by one; +# and `bin/sdlc`, because the image reads a line running `...bin/sdlc ci` as the +# job that runs `sdlc ci`. +BOOTSTRAP_AT = Path(".sdlc/bin/sdlc") +FLOATING_CI_LINE = f"{BOOTSTRAP_AT} ci" + +OLD_IMAGE = "quay.io/crunchtools/python-sdlc" +NEW_IMAGE = "quay.io/crunchtools/sdlc" +SDLC_REPO = re.compile(r"^https://github\.com/crunchtools/python-sdlc(?:\.git)?/?$") +STANDALONE_HOOKS = {"gourmand", "gatehouse"} +SDLC_HOOKS = {"sdlc-commit", "sdlc-push"} +GOURMAND_CALL = re.compile(r"^crunchtools/gatehouse/\.github/workflows/gourmand\.yml@") +SDLC_CI_LINE = re.compile(r"^\s*[\"']?(?:\S*/)?sdlc[\"']?\s+ci\b", re.M) + +# The step every converted repo's `sdlc ci` job runs today, rev read from the +# hooks file and the launcher cloned at it. Matched exactly, indent aside: a +# step that says anything else is not one this script will guess at. +PINNED_STEP = re.compile( + r"^(?P[ \t]*)rev=\$\(awk " + r"'/repo: https:\\/\\/github\.com\\/crunchtools\\/python-sdlc/ \{f=1; next\}\n" + r"[ \t]*f && /rev:/ \{print \$2; exit\}' \.pre-commit-config\.yaml\)\n" + r"[ \t]*\[ -n \"\$rev\" \] \|\| " + r"\{ echo \"no python-sdlc rev in \.pre-commit-config\.yaml\" >&2; exit 2; \}\n" + r"[ \t]*git clone -q --depth 1 --branch \"\$rev\" " + r"https://github\.com/crunchtools/python-sdlc \"\$RUNNER_TEMP/sdlc\"\n" + r"[ \t]*\$RUNNER_TEMP/sdlc/bin/sdlc ci\n", + re.M, +) +STEP_NAME = re.compile(r"^(?P[ \t]*)- name: sdlc ci\n(?P[ \t]*)run: \|\n", re.M) + + +class RefusedError(Exception): + """A shape this script will not guess at.""" + + +# ------------------------------------------------------------------ templates + + +def parse(name: str, text: str) -> dict: + """A YAML mapping, or a refusal naming the file.""" + try: + parsed = yaml.safe_load(text) + except yaml.YAMLError as exc: + raise RefusedError(f"{name} is not YAML: {exc}") from exc + if parsed is None: + return {} + if not isinstance(parsed, dict): + raise RefusedError(f"{name} is not a YAML mapping") + return parsed + + +def floating_hooks_item() -> str: + """The `- repo: local` item of examples/pre-commit-floating.yaml.""" + text = HOOKS_TEMPLATE.read_text() + return text[text.index(" - repo: local\n") :] + + +# -------------------------------------------------------- .pre-commit-config + + +def split_items(body: list[str]) -> list[list[str]]: + """The `repos:` list as items, each the lines from one `- repo:` to the next.""" + items: list[list[str]] = [] + for line in body: + if re.match(r"^\s*-\s+repo:", line): + items.append([line]) + elif items: + items[-1].append(line) + elif line.strip() and not line.lstrip().startswith("#"): + raise RefusedError(f".pre-commit-config.yaml: `repos:` starts with {line.strip()!r}") + return items + + +def drop_hooks(item: list[str], ids: set[str]) -> list[str]: + """A `repo: local` item without the hooks named in `ids`.""" + out: list[str] = [] + skipping = False + hook_indent = None + for line in item: + found = re.match(r"^(\s*)-\s+id:\s*(\S+)", line) + if found: + hook_indent = len(found.group(1)) + skipping = found.group(2) in ids + elif hook_indent is not None and line.strip(): + indent = len(line) - len(line.lstrip()) + if indent <= hook_indent and not line.lstrip().startswith("#"): + skipping = False + if not skipping: + out.append(line) + return out + + +def refuse_hooks(repos: list) -> None: + """Refuse a hooks file this script would have to guess at.""" + pinned = [r for r in repos if SDLC_REPO.match(str(r.get("repo", "")))] + if any({h.get("id") for h in r.get("hooks") or []} != SDLC_HOOKS for r in pinned): + raise RefusedError( + ".pre-commit-config.yaml: python-sdlc is pinned with hooks other than its two" + ) + local = {h.get("id") for r in repos if r.get("repo") == "local" for h in r.get("hooks") or []} + if local & SDLC_HOOKS: + raise RefusedError( + ".pre-commit-config.yaml already has local sdlc hooks that are not the floating form" + ) + if not pinned and local & STANDALONE_HOOKS != STANDALONE_HOOKS: + raise RefusedError( + ".pre-commit-config.yaml has neither the python-sdlc pin nor both standalone " + "hooks (gourmand, gatehouse); there is nothing this script knows to replace" + ) + + +def only_replaced(repos: list) -> bool: + """True when every hook in the file is one the floating hooks replace.""" + for r in repos: + if SDLC_REPO.match(str(r.get("repo", ""))): + continue + if r.get("repo") != "local": + return False + if any(h.get("id") not in STANDALONE_HOOKS for h in r.get("hooks") or []): + return False + return True + + +def without_replaced(lines: list[str]) -> str: + """The `repos:` items that survive: all but python-sdlc and the standalone hooks.""" + kept: list[str] = [] + for item in split_items(lines): + repo = re.match(r"^\s*-\s+repo:\s*(\S+)", item[0]).group(1) + if SDLC_REPO.match(repo): + continue + trimmed = drop_hooks(item, STANDALONE_HOOKS) if repo == "local" else item + if any(re.match(r"^\s*-\s+id:", line) for line in trimmed): + kept += trimmed + return "".join(kept).rstrip("\n") + "\n" if kept else "" + + +FLOATING_ENTRIES = {"sdlc-commit": f"{BOOTSTRAP_AT} commit", "sdlc-push": f"{BOOTSTRAP_AT} push"} +BOTH_HOOK_TYPES = "default_install_hook_types: [pre-commit, pre-push]" + + +def is_floating(repos: list) -> bool: + """Already converted: the floating hooks, and nothing they replace.""" + local = { + h.get("id"): h.get("entry") + for r in repos + if r.get("repo") == "local" + for h in r.get("hooks") or [] + } + pinned = any(SDLC_REPO.match(str(r.get("repo", ""))) for r in repos) + return ( + not pinned + and not set(local) & STANDALONE_HOOKS + and all(local.get(hook) == entry for hook, entry in FLOATING_ENTRIES.items()) + ) + + +def with_both_hook_types(head: list[str]) -> list[str]: + """The lines above `repos:`, with `default_install_hook_types` naming both. + + By line, not by pattern: the key may be written in block style, its list + items on the lines below it, and a comment may say `repos:` too. + """ + out: list[str] = [] + replaced = False + skipping = False + for line in head: + if skipping and re.match(r"^\s+-", line): + continue # an item of the block-style list being replaced + skipping = False + if re.match(r"^default_install_hook_types:", line): + out.append(BOTH_HOOK_TYPES + "\n") + replaced = skipping = True + continue + out.append(line) + if not replaced: + out += [BOTH_HOOK_TYPES + "\n", "\n"] + return out + + +def convert_hooks(text: str) -> str: + """The hooks file with the floating hooks in place of the pinned or standalone ones.""" + template = HOOKS_TEMPLATE.read_text() + if text == template: + return text + repos = parse(".pre-commit-config.yaml", text).get("repos") or [] + if is_floating(repos): + return text + refuse_hooks(repos) + if only_replaced(repos): + # Nothing else in it: the template, header and all, since the old + # header explains a `rev:` that is gone. + return template + lines = text.splitlines(keepends=True) + start = next((n for n, line in enumerate(lines) if re.match(r"^repos:\s*$", line)), None) + if start is None: + raise RefusedError(".pre-commit-config.yaml: no top-level `repos:` line") + head = "".join(with_both_hook_types(lines[:start])) + lines[start] + return head + without_replaced(lines[start + 1 :]) + floating_hooks_item() + + +# ------------------------------------------------------------------ workflows + + +def jobs_of(parsed: dict) -> dict: + jobs = parsed.get("jobs") + return jobs if isinstance(jobs, dict) else {} + + +def is_sdlc_job(job: object) -> bool: + return ( + isinstance(job, dict) + and job.get("name") == "sdlc ci" + and any( + isinstance(step, dict) and SDLC_CI_LINE.search(str(step.get("run", ""))) + for step in job.get("steps") or [] + ) + ) + + +def is_gourmand_job(job: object) -> bool: + return isinstance(job, dict) and bool(GOURMAND_CALL.match(str(job.get("uses", "")))) + + +# What examples/ci.yml replaces whole: a job with nothing on it but these keys, +# and steps that are only the checkout and the `sdlc ci` step. Anything more -- +# another step, a service, an env, a matrix -- is something ci.yml would +# drop, so that workflow keeps its place and only its step is rewritten. +COVERED_SDLC_KEYS = {"name", "runs-on", "steps", "permissions"} +COVERED_GOURMAND_KEYS = {"name", "uses"} +COVERED_WORKFLOW_KEYS = {"name", True, "on", "permissions", "jobs"} # YAML 1.1 reads on: as True +CHECKOUT = re.compile(r"^actions/checkout@") + + +def is_covered_step(step: object) -> bool: + if not isinstance(step, dict): + return False + if CHECKOUT.match(str(step.get("uses", ""))): + return set(step) <= {"uses", "with"} and set(step.get("with") or {}) <= { + "persist-credentials" + } + run = str(step.get("run", "")) + "\n" + rest = PINNED_STEP.sub("", run, count=1).replace("set -eu\n", "", 1).strip() + pinned = PINNED_STEP.search(run) is not None and not rest + floating = run.strip() == FLOATING_CI_LINE + # examples/ci.yml's step carries one env entry; any other would be dropped. + env_kept = (step.get("env") or {}) in ({}, FLOATING_ENV) + return set(step) <= {"name", "run", "env"} and env_kept and (pinned or floating) + + +FLOATING_ENV = {"SDLC_IMAGE": "${{ vars.SDLC_IMAGE }}"} +GOURMAND_JOB_NAME = "Code Quality (Gourmand)" # a required check: never renamed by this +# The events a floated `sdlc ci` step may run under. The bootstrap now comes +# from the checkout, so under any event that hands secrets to code a pull +# request controls (pull_request_target, workflow_run, issue_comment and the +# rest) it would run that code with them. An allowlist, not a denylist: an +# event added to GitHub later is refused until someone has looked at it. +FLOATABLE_EVENTS = {"push", "pull_request", "workflow_dispatch", "schedule", "merge_group"} +READ_ONLY = {"contents": "read"} +# The events examples/ci.yml answers. A workflow that also runs on a schedule, a +# release, another branch or a path filter would lose that by being replaced. +STUB_BRANCHES = {"main", "master"} + + +def is_covered_job(job: object) -> bool: + """A job examples/ci.yml has in full, so replacing it loses nothing.""" + if is_gourmand_job(job): + return set(job) <= COVERED_GOURMAND_KEYS and job.get("name") == GOURMAND_JOB_NAME + return ( + is_sdlc_job(job) + and set(job) <= COVERED_SDLC_KEYS + and job.get("permissions", READ_ONLY) == READ_ONLY + and all(is_covered_step(step) for step in job.get("steps") or []) + ) + + +def is_covered_trigger(on: object) -> bool: + """`on:` asks for no more than examples/ci.yml answers.""" + if isinstance(on, str): + on = {on: None} + if isinstance(on, list): + on = dict.fromkeys(on) + if not isinstance(on, dict) or not set(on) <= {"push", "pull_request", "workflow_dispatch"}: + return False + # examples/ci.yml answers every pull request, so a pull_request limited to the + # default branch loses nothing by being replaced; a push must be to one. + return not on.get("workflow_dispatch") and all( + isinstance(on.get(event) or {}, dict) + and set(on.get(event) or {}) <= {"branches"} + and set((on.get(event) or {}).get("branches") or []) <= STUB_BRANCHES + for event in ("push", "pull_request") + ) + + +def is_covered_workflow(parsed: dict, jobs: list) -> bool: + """A workflow examples/ci.yml replaces with nothing lost: events, permissions, jobs.""" + return ( + bool(jobs) + and set(parsed) <= COVERED_WORKFLOW_KEYS + and is_covered_trigger(parsed.get("on", parsed.get(True))) + and parsed.get("permissions", READ_ONLY) == READ_ONLY + and all(is_covered_job(j) for j in jobs) + ) + + +def float_sdlc_step(name: str, text: str) -> str: + """The pinned `sdlc ci` step of a workflow the stub cannot replace, floated.""" + if not PINNED_STEP.search(text): + if re.search(rf"^\s*{re.escape(FLOATING_CI_LINE)}\s*$", text, re.M): + return text # already floating + raise RefusedError( + f"{name}: its `sdlc ci` step is not the pinned form this script rewrites" + ) + found = STEP_NAME.search(text) + if found is None or len(STEP_NAME.findall(text)) != 1: + raise RefusedError( + f"{name}: no single `- name: sdlc ci` step directly followed by `run: |`" + ) + j = found.group("j") + env = f"{j}env:\n{j} SDLC_IMAGE: ${{{{ vars.SDLC_IMAGE }}}}\n" + text = text.replace(found.group(0), f"{found.group('i')}- name: sdlc ci\n{env}{j}run: |\n", 1) + # `set -eu` stays the step's first line; the clone becomes the bootstrap. + return PINNED_STEP.sub(lambda m: f"{m.group('i')}{FLOATING_CI_LINE}\n", text, count=1) + + +def classify(files: list[Path]) -> tuple[list[Path], list[Path]]: + """Workflows the CI stub covers whole, and ones that share an `sdlc ci` job.""" + covered: list[Path] = [] + mixed: list[Path] = [] + for path in files: + if path.name.startswith("gatehouse"): + continue + parsed = parse(path.name, path.read_text()) + jobs = list(jobs_of(parsed).values()) + if is_covered_workflow(parsed, jobs): + covered.append(path) + elif any(is_sdlc_job(j) for j in jobs): + mixed.append(path) + return covered, mixed + + +def convert_workflows(repo: Path, planned: dict[Path, str | None], notes: list[str]) -> None: + wf_dir = repo / ".github" / "workflows" + files = sorted(wf_dir.glob("*.y*ml")) if wf_dir.is_dir() else [] + covered, mixed = classify(files) + if mixed: + # The `sdlc ci` job stays where it is, beside jobs examples/ci.yml does not + # have; writing ci.yml as well would run it twice. Nothing is deleted. + for path in mixed: + on = parse(path.name, path.read_text()) + on = on.get("on", on.get(True)) + events = set(on) if isinstance(on, (dict, list)) else {on} + if not events <= FLOATABLE_EVENTS: + others = ", ".join(sorted(map(str, events - FLOATABLE_EVENTS))) + raise RefusedError( + f"{rel(repo, path)} runs on {others}; " + f"its `sdlc ci` step could run a pull request's .sdlc/bin/sdlc with secrets" + ) + planned[path] = float_sdlc_step(rel(repo, path), path.read_text()) + notes.append(f"floated: {rel(repo, path)} (its `sdlc ci` job shares the file)") + notes += [f"kept: {rel(repo, p)} (no ci.yml stub to take its jobs)" for p in covered] + else: + ci = wf_dir / "ci.yml" + if ci.exists() and ci not in covered: + raise RefusedError( + f"{rel(repo, ci)} has jobs the stub does not cover; move them to their " + f"own workflow, then convert" + ) + planned.update(dict.fromkeys(covered)) + planned[ci] = CI_TEMPLATE.read_text() + + gatehouse = wf_dir / "gatehouse.yml" + canonical = GATEHOUSE_TEMPLATE.read_text() + current = gatehouse.read_text() if gatehouse.exists() else canonical + if parse(gatehouse.name, current) == parse(GATEHOUSE_TEMPLATE.name, canonical): + planned[gatehouse] = canonical + else: + notes.append(f"kept: {rel(repo, gatehouse)} (differs from the stub in more than comments)") + + notes += [ + f"kept: {rel(repo, path)}" + for path in files + if path not in planned and path not in covered and path != gatehouse + ] + + +# ---------------------------------------------------------------- the repo + + +def rel(repo: Path, path: Path) -> str: + return str(path.relative_to(repo)) + + +def refuse_links(repo: Path, paths: list[Path]) -> None: + """Refuse a planned path that is, or sits under, a symlink. + + A checkout is someone else's content: a `.sdlc` or `.pre-commit-config.yaml` + that links outside it would have --apply write, delete or chmod a file of + the person running this. + """ + for path in paths: + for part in [path, *path.parents]: + if part == repo: + break + if part.is_symlink(): + raise RefusedError(f"{rel(repo, part)} is a symlink; this script writes no links") + + +def plan(repo: Path) -> tuple[dict[Path, str | None], list[str]]: + """Every file the conversion writes (None: deletes), and what it kept.""" + planned: dict[Path, str | None] = {repo / BOOTSTRAP_AT: BOOTSTRAP.read_text()} + notes: list[str] = [] + hooks = repo / ".pre-commit-config.yaml" + wf_dir = repo / ".github" / "workflows" + refuse_links(repo, [hooks, *planned, wf_dir, repo / "pyproject.toml", repo / "sdlc.toml"]) + planned[hooks] = convert_hooks(hooks.read_text() if hooks.exists() else "") + convert_workflows(repo, planned, notes) + notes.append(f"writes: {BOOTSTRAP_AT}, executable (python-sdlc's bin/sdlc-bootstrap)") + # An image reference in anything that survives, and in the repo's config. + candidates = [repo / "pyproject.toml", repo / "sdlc.toml"] + candidates += sorted(wf_dir.glob("*.y*ml")) if wf_dir.is_dir() else [] + refuse_links(repo, candidates) + for path in candidates: + if not path.exists() or planned.get(path, "") is None: + continue + text = planned.get(path) or path.read_text() + moved = re.sub(re.escape(OLD_IMAGE) + r"(?![\w.-])", NEW_IMAGE, text) + if moved != text: + planned[path] = moved + refuse_links(repo, list(planned)) + verify(repo, planned) + return planned, notes + + +def verify(repo: Path, planned: dict[Path, str | None]) -> None: + """Refuse a plan whose files do not load, or do not wire what they should. + + Every YAML file this writes is parsed back, and the result is held to the + wiring itself -- the floating hooks, both hook types, a job named `sdlc ci` + running the bootstrap -- rather than to how the text was produced. + """ + for path, text in planned.items(): + if text is not None and path.suffix in (".yml", ".yaml"): + parse(rel(repo, path), text) + hooks = parse(".pre-commit-config.yaml", planned[repo / ".pre-commit-config.yaml"] or "") + types = hooks.get("default_install_hook_types") or [] + if not (isinstance(types, list) and {"pre-commit", "pre-push"} <= set(types)): + raise RefusedError("the converted hooks file does not install both hook types") + if not is_floating(hooks.get("repos") or []): + raise RefusedError("the converted hooks file does not run .sdlc/bin/sdlc as its only sdlc") + if planned[repo / BOOTSTRAP_AT] != BOOTSTRAP.read_text(): + raise RefusedError(f"{BOOTSTRAP_AT} would not be bin/sdlc-bootstrap") + wf_dir = repo / ".github" / "workflows" + texts = {p: planned.get(p, "") for p in planned if p.parent == wf_dir and planned[p]} + texts |= { + p: p.read_text() + for p in (sorted(wf_dir.glob("*.y*ml")) if wf_dir.is_dir() else []) + if p not in planned + } + # Nothing may still clone python-sdlc at the hooks file's rev: the rev is + # gone, so such a step would exit 2 on every run from now on. + for path, text in texts.items(): + if PINNED_STEP.search(text) or "github.com/crunchtools/python-sdlc" in text: + raise RefusedError( + f"{rel(repo, path)} still fetches python-sdlc by the rev this removes; " + f"convert that step by hand" + ) + floating = re.compile(rf"^\s*{re.escape(FLOATING_CI_LINE)}\s*$", re.M) + if not any( + is_sdlc_job(job) + and any(floating.search(str(step.get("run", ""))) for step in job.get("steps") or []) + for path, text in texts.items() + for job in jobs_of(parse(rel(repo, path), text)).values() + ): + raise RefusedError( + "no converted workflow has a job named `sdlc ci` running .sdlc/bin/sdlc ci" + ) + + +def diff(repo: Path, planned: dict[Path, str | None]) -> str: + out = [] + for path in sorted(planned): + before = path.read_text() if path.exists() else "" + after = planned[path] or "" + if before == after and (planned[path] is not None or not path.exists()): + continue + name = rel(repo, path) + out += difflib.unified_diff( + before.splitlines(keepends=True), + after.splitlines(keepends=True), + f"a/{name}" if path.exists() else "/dev/null", + f"b/{name}" if planned[path] is not None else "/dev/null", + ) + return "".join(out) + + +def main() -> int: + ap = argparse.ArgumentParser(description=__doc__.split("\n\n")[0]) + ap.add_argument("repo", type=Path, help="a checkout of the repo to convert") + ap.add_argument("--apply", action="store_true", help="write the changes; default prints them") + args = ap.parse_args() + if yaml is None: + print("convert_repo: needs PyYAML (python3-pyyaml)", file=sys.stderr) + return 2 + repo = args.repo.resolve() + if not (repo / ".git").exists(): + print(f"convert_repo: {repo} is not a git checkout", file=sys.stderr) + return 2 + try: + planned, notes = plan(repo) + except RefusedError as exc: + print(f"convert_repo: {repo.name}: NOT CONVERTED: {exc}", file=sys.stderr) + return 2 + sys.stdout.write(diff(repo, planned)) + for note in notes: + print(f"convert_repo: {repo.name}: {note}", file=sys.stderr) + if args.apply: + # Again at the moment of writing: plan() refused links, and the + # checkout is not ours to trust between then and now. + try: + refuse_links(repo, list(planned)) + except RefusedError as exc: + print(f"convert_repo: {repo.name}: NOT CONVERTED: {exc}", file=sys.stderr) + return 2 + for path, text in planned.items(): + if text is None: + path.unlink(missing_ok=True) + elif not path.exists() or path.read_text() != text: + path.parent.mkdir(parents=True, exist_ok=True) + path.write_text(text) + (repo / BOOTSTRAP_AT).chmod(0o755) + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/sdlc b/sdlc index c887b52..3bad699 100755 --- a/sdlc +++ b/sdlc @@ -373,6 +373,7 @@ RESERVED = ( "list", "versions", "stacks", + "launcher", "pytest-deps", "codeql-baseline", "scan-rootfs", @@ -1065,13 +1066,22 @@ HOST_CHECKS = { } +# What the fleet does on purpose, so hadolint is told not to call it a defect. +# DL3007: base tags float, because the Container Image profile rebuilds every +# week to pick up errata through them. DL3041: dnf installs are not pinned to a +# package version, for the same reason. +HADOLINT_FLEET_IGNORES = ("DL3007", "DL3041") + + def t_containerfile_lint(s: dict) -> int: """hadolint over the Containerfile, with the repo's own `.hadolint.yaml`. - Without a config the threshold is `warning`: hadolint's own default fails - on style notes, and a gate that fails on taste is a gate people skip. A - repo with a config file sets its own threshold there, and `threshold` in - this check's table beats both. + Without a config the threshold is `error` and the fleet's deliberate + choices (HADOLINT_FLEET_IGNORES) are not reported: a warning such as + DL3002, a root last USER, is printed and does not fail, because a gate that + fails on taste is a gate people skip. A repo with a config file sets its + own rules there and gets none of these defaults, and `threshold` in this + check's table beats both. """ files = names(s.get("containerfiles"), "containerfile-lint.containerfiles") if not files: @@ -1082,8 +1092,10 @@ def t_containerfile_lint(s: dict) -> int: files = [in_repo("containerfile-lint", "containerfiles", f) for f in files] cmd = ["hadolint", "--no-color"] threshold = s.get("threshold") - if threshold is None and not any((REPO / c).is_file() for c in HADOLINT_CONFIGS): - threshold = "warning" + if not any((REPO / c).is_file() for c in HADOLINT_CONFIGS): + threshold = threshold or "error" + for rule in HADOLINT_FLEET_IGNORES: + cmd += ["--ignore", rule] if threshold is not None: if threshold not in HADOLINT_THRESHOLDS: cannot(f"containerfile-lint: threshold must be one of {', '.join(HADOLINT_THRESHOLDS)}") @@ -2168,6 +2180,33 @@ def t_stacks() -> int: return CLEAN +# The host launcher, bin/sdlc, shipped inside the image that it starts. A repo +# with no `rev:` to pin gets it from here (bin/sdlc-bootstrap), so the launcher +# floats with the image tag exactly as every tool in the image does. +LAUNCHER = Path("/usr/share/sdlc/launcher") +LAUNCHED_FROM_LINE = "LAUNCHED_FROM=\n" + + +def t_launcher(ref: str | None) -> int: + """Print the launcher, with the image it came from written into it. + + The caller names the ref because only it knows which one it pulled: the + image cannot see its own tag. The ref is checked before it is written into + a shell script, and written single-quoted all the same. + """ + if not ref: + cannot("launcher needs the image it is run from, e.g. quay.io/crunchtools/sdlc:latest") + ref = image_ref("launcher", "image", ref) + try: + text = LAUNCHER.read_text() + except OSError as exc: + cannot(f"this image ships no launcher at {LAUNCHER}: {exc}") + if text.count(LAUNCHED_FROM_LINE) != 1: + cannot(f"{LAUNCHER} has no single `LAUNCHED_FROM=` line to write the image into") + sys.stdout.write(text.replace(LAUNCHED_FROM_LINE, f"LAUNCHED_FROM='{ref}'\n", 1)) + return CLEAN + + TOOL_COMMANDS = { "tiers": t_tiers, "list": t_list, @@ -2189,6 +2228,8 @@ def main() -> int: ap.add_argument("arg", nargs="?", help="for plan: commit, push, ci or a check name") args = ap.parse_args() + if args.what == "launcher": + return t_launcher(args.arg) if args.what == "plan": if not args.arg: cannot("plan needs commit, push, ci or a check name") diff --git a/tests/contract.sh b/tests/contract.sh index aae102d..a59d9b6 100755 --- a/tests/contract.sh +++ b/tests/contract.sh @@ -459,14 +459,37 @@ else bad "containerfile-lint failed on a clean fixture Containerfile" printf '%s\n' "$out" | sed 's/^/ /' | tail -8 fi -printf 'FROM quay.io/hummingbird/python\nRUN cd /tmp && ls\n' > "$CFIX/Containerfile" +lint() { podman run --rm -v "$CFIX:/repo:ro,z" -w /repo --entrypoint="" "$IMAGE" sdlc containerfile-lint 2>&1; } +# The fleet's own conventions: a floating base tag (DL3007), dnf without +# package versions (DL3041), and root as the last USER (DL3002, a warning). +printf 'FROM registry.access.redhat.com/ubi10/ubi-init:latest\nRUN dnf install -y less && dnf clean all\nUSER root\n' \ + > "$CFIX/Containerfile" rc=0 -podman run --rm -v "$CFIX:/repo:ro,z" -w /repo --entrypoint="" \ - "$IMAGE" sdlc containerfile-lint >/dev/null 2>&1 || rc=$? +out=$(lint) || rc=$? +if [ "$rc" -eq 0 ] && printf '%s' "$out" | grep -q DL3002 \ + && ! printf '%s' "$out" | grep -q 'DL3007\|DL3041'; then + ok "containerfile-lint passes the fleet's conventions, ignores DL3007/DL3041, still prints DL3002" +else + bad "containerfile-lint on the fleet's conventions exited $rc" + printf '%s\n' "$out" | sed 's/^/ /' | tail -6 +fi +printf 'FROM quay.io/hummingbird/python:3.14\nWORKDIR app\n' > "$CFIX/Containerfile" +rc=0 +lint >/dev/null || rc=$? if [ "$rc" -eq 1 ]; then - ok "containerfile-lint finds an untagged FROM and a cd (exit 1)" + ok "containerfile-lint fails on an error-level rule, a relative WORKDIR (exit 1)" +else + bad "containerfile-lint on a relative WORKDIR exited $rc, want 1" +fi +# A repo's own .hadolint.yaml takes the defaults away: here it asks for warnings. +printf 'FROM registry.access.redhat.com/ubi10/ubi-init:latest\n' > "$CFIX/Containerfile" +printf 'failure-threshold: warning\n' > "$CFIX/.hadolint.yaml" +rc=0 +out=$(lint) || rc=$? +if [ "$rc" -eq 1 ] && printf '%s' "$out" | grep -q DL3007; then + ok "a repo's .hadolint.yaml overrides the stack defaults (DL3007 fails at warning)" else - bad "containerfile-lint on a bad Containerfile exited $rc, want 1" + bad "containerfile-lint with a .hadolint.yaml exited $rc, want 1 on DL3007" fi rm -rf "$CFIX" @@ -504,6 +527,32 @@ do fi done +# ------------------------------------------- the launcher the image carries + +# A repo with no `rev:` runs the launcher this image prints, so the image must +# carry THIS commit's bin/sdlc and write the ref it was asked for into it. +printf '\n== the launcher\n\n' +CLAUNCH=$(mktemp) +if podman run --rm --network=none "$IMAGE" launcher quay.io/crunchtools/sdlc:latest > "$CLAUNCH" \ + && sed "s|^LAUNCHED_FROM=\$|LAUNCHED_FROM='quay.io/crunchtools/sdlc:latest'|" bin/sdlc | cmp -s - "$CLAUNCH"; then + ok "sdlc launcher prints this commit's bin/sdlc, with the ref written in" +else + bad "sdlc launcher does not print this commit's bin/sdlc" +fi +rm -f "$CLAUNCH" +rc=0 +podman run --rm --network=none "$IMAGE" launcher "x'; id; '" > /dev/null 2>&1 || rc=$? +if [ "$rc" -eq 2 ]; then + ok "sdlc launcher refuses a ref that is not an image reference (exit 2)" +else + bad "sdlc launcher took a ref with quotes in it (exit $rc)" +fi +if inside cat /usr/share/sdlc/bootstrap | cmp -s - bin/sdlc-bootstrap; then + ok "the image carries this commit's bin/sdlc-bootstrap" +else + bad "/usr/share/sdlc/bootstrap is not this commit's bin/sdlc-bootstrap" +fi + printf '\n' if [ "$FAILED" -eq 0 ]; then printf 'contract test PASSED\n' diff --git a/tests/test_container_stack.sh b/tests/test_container_stack.sh index ce20b3f..e4fca8f 100755 --- a/tests/test_container_stack.sh +++ b/tests/test_container_stack.sh @@ -80,6 +80,43 @@ else fi fi +# A systemd PID 1 needs privileges a smoke run withholds, so the smoke check +# is SKIPPED with its reason -- read from the built image by real podman -- +# while the build and the scan still run and judge it. +fixture systemd '["/sbin/init"]' +rc=0 +(cd "$WORK/systemd" && SDLC_IMAGE=$IMAGE "$HERE/bin/sdlc" ci) > "$WORK/systemd.out" 2>&1 || rc=$? +if [ "$rc" -eq 0 ] \ + && grep -q 'systemd PID 1 needs privileges smoke cannot grant' "$WORK/systemd.out" \ + && grep -q '== container-smoke SKIPPED, not judged' "$WORK/systemd.out" \ + && ! grep -q 'container-smoke passed' "$WORK/systemd.out" \ + && grep -q 'container-build passed' "$WORK/systemd.out" \ + && grep -q 'container-scan passed' "$WORK/systemd.out"; then + ok "a systemd image: smoke SKIPPED with its reason, build and scan still pass" +else + bad "sdlc ci on a systemd image exited $rc" + tail -20 "$WORK/systemd.out" | sed 's/^/ /' +fi + +# An image that declares a VOLUME gets an anonymous volume per run. The smoke +# run must take it away with the container, or every run leaks one: a fleet +# measurement once filled a seat's disk with 13 GB of them. +fixture volume '["python3", "-m", "http.server", "8080"]' +printf 'VOLUME /data\n' >> "$WORK/volume/Containerfile" +git -C "$WORK/volume" -c user.email=t@t -c user.name=t commit -qam volume +podman volume ls -q | sort > "$WORK/volumes.before" +rc=0 +(cd "$WORK/volume" && SDLC_IMAGE=$IMAGE "$HERE/bin/sdlc" container-build \ + && SDLC_IMAGE=$IMAGE "$HERE/bin/sdlc" container-smoke) > "$WORK/volume.out" 2>&1 || rc=$? +podman volume ls -q | sort > "$WORK/volumes.after" +leaked=$(comm -13 "$WORK/volumes.before" "$WORK/volumes.after" | wc -l | tr -d ' ') +if [ "$rc" -eq 0 ] && [ "$leaked" -eq 0 ]; then + ok "a smoke run of an image with a VOLUME leaves no volume behind" +else + bad "smoke run of a VOLUME image exited $rc and left $leaked volume(s)" + tail -10 "$WORK/volume.out" | sed 's/^/ /' +fi + printf '\n' [ "$FAILED" -eq 0 ] && { printf 'container stack PASSED\n'; exit 0; } printf 'container stack FAILED: %s check(s)\n' "$FAILED"; exit 1 diff --git a/tests/test_convert_repo.py b/tests/test_convert_repo.py new file mode 100755 index 0000000..3f24896 --- /dev/null +++ b/tests/test_convert_repo.py @@ -0,0 +1,682 @@ +#!/usr/bin/env python3 +"""scripts/convert_repo.py, over repos built here in the shapes the fleet has. + +The conversion is the last PR wave, so what it writes is pinned case by case: + + - the rev-pinned python-sdlc hooks and the standalone Gourmand and Gatehouse + hooks both become examples/pre-commit-floating.yaml, and a hooks file with + other repos in it keeps them + - a workflow whose every job the CI stub covers is replaced by it; one that + shares its `sdlc ci` job with other jobs keeps them and floats in place + - what the stubs do not cover is kept, and a ci.yml it cannot replace is + refused rather than guessed at + - the result runs `sdlc ci` by the constitution validator's reading and by + the image's own, so the required check is the same job + - nothing is written without --apply, a second run finds nothing to do, and + .specify/ is never touched + +Run inside the image, which has the interpreter and PyYAML the script needs: + podman run --rm -v .:/src:ro,z -w /src --entrypoint /opt/constitution-venv/bin/python3 \ + quay.io/crunchtools/sdlc: tests/test_convert_repo.py +""" + +from __future__ import annotations + +import importlib.util +import re +import subprocess +import sys +import tempfile +from pathlib import Path + +import yaml + +ROOT = Path(__file__).resolve().parent.parent +SCRIPT = ROOT / "scripts" / "convert_repo.py" +HOOKS = (ROOT / "examples" / "pre-commit-floating.yaml").read_text() +CI = (ROOT / "examples" / "ci.yml").read_text() +GATEHOUSE = (ROOT / "examples" / "gatehouse.yml").read_text() +BOOTSTRAP = (ROOT / "bin" / "sdlc-bootstrap").read_text() + +# constitution validate-constitution.py `_runs_sdlc_ci`, and the image's own +# CodeQL-deferral reading (`_RUNS_SDLC_CI` in sdlc). Both must still see the job. +VALIDATOR = re.compile(r"^\s*[\"']?(?:\S*/)?sdlc[\"']?\s+ci\b", re.M) +IMAGE = re.compile(r"""(?:^|[\s;&|("'=])\S*bin/sdlc\s+ci\b""") + +FAILED: list[str] = [] +REFUSED = 2 # the script's exit code for a shape it will not guess at +EXECUTABLE = 0o111 + + +def check(name: str, cond: bool, detail: str = "") -> None: + print(f"{'ok ' if cond else 'FAIL'} {name}" + (f" -- {detail}" if detail and not cond else "")) + if not cond: + FAILED.append(name) + + +PINNED_HOOKS = """\ +# Every check runs from python-sdlc, pinned here once. +default_install_hook_types: [pre-commit, pre-push] + +repos: + - repo: https://github.com/crunchtools/python-sdlc + rev: v0.8.0 + hooks: + - id: sdlc-commit + - id: sdlc-push +""" + +STANDALONE_HOOKS = """\ +repos: + - repo: local + hooks: + - id: gourmand + name: Gourmand (AI slop detection) + entry: podman run --rm -v .:/src:Z -w /src quay.io/crunchtools/gourmand:latest check --full + language: system + pass_filenames: false + always_run: true + stages: [pre-commit, pre-merge-commit] + - id: gatehouse + name: Gatehouse (AI code review, staged diff) + entry: bash -c 'git diff --cached | podman run --rm -i quay.io/crunchtools/gatehouse:latest --stdin' + language: system + pass_filenames: false + always_run: true + stages: [pre-commit, pre-merge-commit] +""" + +RUFF_AND_STANDALONE = """\ +repos: + - repo: https://github.com/astral-sh/ruff-pre-commit + rev: v0.17.1 + hooks: + - id: ruff-check +""" + STANDALONE_HOOKS.split("repos:\n", 1)[1] + +PINNED_STEP = """\ + - name: sdlc ci + run: | + set -eu + rev=$(awk '/repo: https:\\/\\/github.com\\/crunchtools\\/python-sdlc/ {f=1; next} + f && /rev:/ {print $2; exit}' .pre-commit-config.yaml) + [ -n "$rev" ] || { echo "no python-sdlc rev in .pre-commit-config.yaml" >&2; exit 2; } + git clone -q --depth 1 --branch "$rev" https://github.com/crunchtools/python-sdlc "$RUNNER_TEMP/sdlc" + $RUNNER_TEMP/sdlc/bin/sdlc ci +""" + +OLD_CI = ( + """\ +name: CI +on: + pull_request: +jobs: + sdlc: + name: sdlc ci + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v7 +""" + + PINNED_STEP + + """ + gourmand: + name: Code Quality (Gourmand) + uses: crunchtools/gatehouse/.github/workflows/gourmand.yml@v0 +""" +) + +GOURMAND = """\ +name: Gourmand +on: + pull_request: +jobs: + gourmand: + name: Code Quality (Gourmand) + uses: crunchtools/gatehouse/.github/workflows/gourmand.yml@v0 +""" + +MIXED = ( + """\ +name: Tests +on: + pull_request: +jobs: + unit: + name: unit + runs-on: ubuntu-latest + steps: + - run: make test + sdlc: + name: sdlc ci + runs-on: ubuntu-latest + steps: +""" + + PINNED_STEP +) + +PUBLISH = """\ +name: Publish +on: + release: +jobs: + publish: + runs-on: ubuntu-latest + steps: + - run: podman pull quay.io/crunchtools/python-sdlc:0.8.0 + - run: echo quay.io/crunchtools/python-sdlc-extras +""" + +CONSTITUTION = "# per-repo constitution\nInherits: v1.44.0\n" + + +def make_repo(files: dict[str, str]) -> Path: + repo = Path(tempfile.mkdtemp()) + (repo / ".git").mkdir() + for name, text in files.items(): + (repo / name).parent.mkdir(parents=True, exist_ok=True) + (repo / name).write_text(text) + return repo + + +def snapshot(repo: Path) -> dict[str, str]: + return { + str(p.relative_to(repo)): p.read_text() + for p in sorted(repo.rglob("*")) + if p.is_file() and ".git" not in p.parts + } + + +def convert(repo: Path, apply: bool = False) -> subprocess.CompletedProcess: + return subprocess.run( + [sys.executable, str(SCRIPT), str(repo), *(["--apply"] if apply else [])], + capture_output=True, + text=True, + check=False, + ) + + +def runs_sdlc_ci(text: str) -> bool: + for job in (yaml.safe_load(text).get("jobs") or {}).values(): + if job.get("name") != "sdlc ci": + continue + for step in job.get("steps") or []: + run = str(step.get("run", "")) + if VALIDATOR.search(run) and any(IMAGE.search(line) for line in run.splitlines()): + return True + return False + + +# ------------------------------------------------- a rev-pinned Python repo + +repo = make_repo( + { + ".pre-commit-config.yaml": PINNED_HOOKS, + ".github/workflows/ci.yml": OLD_CI, + ".github/workflows/gourmand.yml": GOURMAND, + ".github/workflows/gatehouse.yml": "# an older comment\n" + GATEHOUSE, + ".github/workflows/publish.yml": PUBLISH, + ".specify/memory/constitution.md": CONSTITUTION, + } +) +before = snapshot(repo) +dry = convert(repo) +check("python: the dry run exits 0", dry.returncode == 0, dry.stderr) +check("python: the dry run prints a diff", "+++ b/.github/workflows/ci.yml" in dry.stdout) +check("python: the dry run changes nothing", snapshot(repo) == before) +done = convert(repo, apply=True) +after = snapshot(repo) +check("python: --apply exits 0", done.returncode == 0, done.stderr) +check("python: the hooks file is the floating example", after[".pre-commit-config.yaml"] == HOOKS) +check("python: ci.yml is the stub", after.get(".github/workflows/ci.yml") == CI) +check( + "python: .sdlc/bin/sdlc is bin/sdlc-bootstrap, executable", + after.get(".sdlc/bin/sdlc") == BOOTSTRAP + and (repo / ".sdlc/bin/sdlc").stat().st_mode & EXECUTABLE == EXECUTABLE, +) +check( + "python: gourmand.yml, covered by the stub, is gone", + ".github/workflows/gourmand.yml" not in after, +) +check("python: gatehouse.yml is the stub", after[".github/workflows/gatehouse.yml"] == GATEHOUSE) +check( + "python: publish.yml is kept, its image moved to quay.io/crunchtools/sdlc", + "podman pull quay.io/crunchtools/sdlc:0.8.0" in after[".github/workflows/publish.yml"] + and "quay.io/crunchtools/python-sdlc-extras" in after[".github/workflows/publish.yml"], +) +check( + "python: .specify is untouched", + after[".specify/memory/constitution.md"] == CONSTITUTION, +) +check( + "python: no hook repo is pinned at a rev", + all("rev" not in r for r in yaml.safe_load(after[".pre-commit-config.yaml"])["repos"]), +) +check( + "python: the stub runs `sdlc ci` by both readings", + runs_sdlc_ci(after[".github/workflows/ci.yml"]), +) +again = convert(repo) +check( + "python: a second run finds nothing to do", + again.returncode == 0 and again.stdout == "", + again.stdout, +) + +# An image reference in the repo's config moves too; a longer name that only +# starts the same way does not. +for config in ("pyproject.toml", "sdlc.toml"): + text = ( + '[tool.sdlc.ci.tests]\nimage = "quay.io/crunchtools/python-sdlc:0.8.0"\n' + 'other = "quay.io/crunchtools/python-sdlc-extras:1"\n' + ) + repo = make_repo({".pre-commit-config.yaml": PINNED_HOOKS, config: text}) + convert(repo, apply=True) + moved = snapshot(repo)[config] + check( + f"{config}: the python-sdlc image moves to quay.io/crunchtools/sdlc, a longer name stays", + 'image = "quay.io/crunchtools/sdlc:0.8.0"' in moved + and "quay.io/crunchtools/python-sdlc-extras:1" in moved, + moved, + ) + +# ------------------------------------------------ a container-only repo + +repo = make_repo( + { + ".pre-commit-config.yaml": STANDALONE_HOOKS, + ".github/workflows/gourmand.yml": GOURMAND, + ".github/workflows/container.yml": ( + "name: Container\non: push\njobs:\n build:\n uses: x/y/.github/workflows/c.yml@v1\n" + ), + "Containerfile": "FROM scratch\n", + } +) +done = convert(repo, apply=True) +after = snapshot(repo) +check("container: --apply exits 0", done.returncode == 0, done.stderr) +check( + "container: the standalone hooks become the floating ones", + after[".pre-commit-config.yaml"] == HOOKS, +) +check("container: ci.yml is written", after.get(".github/workflows/ci.yml") == CI) +check( + "container: gatehouse.yml is written", after.get(".github/workflows/gatehouse.yml") == GATEHOUSE +) +check("container: container.yml is kept", ".github/workflows/container.yml" in after) +check("container: gourmand.yml is gone", ".github/workflows/gourmand.yml" not in after) + +# ------------------------------- an sdlc ci job sharing its workflow + +repo = make_repo( + { + ".pre-commit-config.yaml": PINNED_HOOKS, + ".github/workflows/tests.yml": MIXED, + ".github/workflows/gourmand.yml": GOURMAND, + } +) +done = convert(repo, apply=True) +after = snapshot(repo) +tests_yml = after[".github/workflows/tests.yml"] +check("mixed: --apply exits 0", done.returncode == 0, done.stderr) +check("mixed: no ci.yml stub beside it", ".github/workflows/ci.yml" not in after) +check("mixed: the other job is kept", "make test" in tests_yml) +check("mixed: gourmand.yml is kept, no stub took it", ".github/workflows/gourmand.yml" in after) +check( + "mixed: the step floats, reading SDLC_IMAGE from the repository variable", + "\n .sdlc/bin/sdlc ci\n" in tests_yml + and "SDLC_IMAGE: ${{ vars.SDLC_IMAGE }}" in tests_yml + and "git clone" not in tests_yml, +) +check("mixed: it still runs `sdlc ci` by both readings", runs_sdlc_ci(tests_yml)) +check("mixed: the result is still YAML", isinstance(yaml.safe_load(tests_yml), dict)) +again = convert(repo) +check( + "mixed: a second run finds nothing to do", + again.returncode == 0 and again.stdout == "", + again.stdout, +) + +# ------------------------------------------------------ what it refuses + +repo = make_repo( + { + ".pre-commit-config.yaml": STANDALONE_HOOKS, + ".github/workflows/ci.yml": ( + "name: CI\non: push\njobs:\n build:\n runs-on: x\n steps:\n - run: make\n" + ), + } +) +before = snapshot(repo) +refused = convert(repo, apply=True) +check( + "a ci.yml the stub cannot replace is refused (exit 2), and nothing is written", + refused.returncode == REFUSED + and "NOT CONVERTED" in refused.stderr + and snapshot(repo) == before, + refused.stderr, +) + +for broken in ("repos: [\n", "- a list\n"): + repo = make_repo({".pre-commit-config.yaml": broken}) + refused = convert(repo) + check( + f"a hooks file that is not a YAML mapping ({broken.strip()!r}) is refused, not a traceback", + refused.returncode == REFUSED and "Traceback" not in refused.stderr, + refused.stderr, + ) + +repo = make_repo({".pre-commit-config.yaml": "repos: []\n"}) +refused = convert(repo) +check( + "a hooks file with nothing to replace is refused (exit 2)", + refused.returncode == REFUSED, + refused.stderr, +) + +custom = GATEHOUSE.replace( + "uses: crunchtools/gatehouse/.github/workflows/review.yml@v0", + "uses: crunchtools/gatehouse/.github/workflows/review.yml@v0\n with:\n blocking: true", +) +repo = make_repo( + { + ".pre-commit-config.yaml": RUFF_AND_STANDALONE, + ".github/workflows/gatehouse.yml": custom, + } +) +done = convert(repo, apply=True) +after = snapshot(repo) +hooks = yaml.safe_load(after[".pre-commit-config.yaml"]) +check("other hooks: --apply exits 0", done.returncode == 0, done.stderr) +check( + "other hooks: ruff is kept, the standalone hooks are gone, the floating ones added", + [r["repo"] for r in hooks["repos"]] == ["https://github.com/astral-sh/ruff-pre-commit", "local"] + and [h["id"] for h in hooks["repos"][1]["hooks"]] == ["sdlc-commit", "sdlc-push"], +) +check( + "other hooks: both hook types are installed", + hooks.get("default_install_hook_types") == ["pre-commit", "pre-push"], +) +check( + "a gatehouse.yml that differs in more than comments is kept", + after[".github/workflows/gatehouse.yml"] == custom + and "kept: .github/workflows/gatehouse.yml" in done.stderr, +) + + +# A mixed workflow whose `sdlc ci` step is not the exact pinned form, or has +# two of them, is not rewritten by guesswork. +for label, text in ( + ("an edited pinned step", MIXED.replace("--depth 1", "--depth 2")), + ("two sdlc ci steps", MIXED + PINNED_STEP), +): + repo = make_repo({".pre-commit-config.yaml": PINNED_HOOKS, ".github/workflows/tests.yml": text}) + before = snapshot(repo) + refused = convert(repo, apply=True) + check( + f"mixed: {label} is refused (exit 2) and nothing is written", + refused.returncode == REFUSED and snapshot(repo) == before, + refused.stderr, + ) + +# Standalone hooks sharing their `repo: local` item with a hook of the repo's +# own: only the two standalone hooks go. +OWN_HOOK = """\ + - id: shellcheck + name: shellcheck + entry: podman run --rm -v .:/mnt:ro,z -w /mnt docker.io/koalaman/shellcheck:v0.11.0 run.sh + language: system + pass_filenames: false + stages: [pre-commit] +""" +repo = make_repo( + { + ".pre-commit-config.yaml": STANDALONE_HOOKS.replace( + " hooks:\n", " hooks:\n" + OWN_HOOK, 1 + ) + } +) +done = convert(repo, apply=True) +hooks = yaml.safe_load(snapshot(repo)[".pre-commit-config.yaml"]) +local = [[h["id"] for h in r["hooks"]] for r in hooks["repos"] if r["repo"] == "local"] +check( + "a repo's own local hook survives beside the floating ones, with its settings", + done.returncode == 0 + and local == [["shellcheck"], ["sdlc-commit", "sdlc-push"]] + and hooks["repos"][0]["hooks"][0]["stages"] == ["pre-commit"], + f"{local} {done.stderr}", +) + +# ---------------------------------------------- what the stub would drop + +# A job carrying more than examples/ci.yml has -- a step, an env, a service -- +# keeps its workflow; only its `sdlc ci` step is rewritten. +richer = OLD_CI.replace( + " - uses: actions/checkout@v7\n", + " - uses: actions/checkout@v7\n - run: make generated-files\n", +) +repo = make_repo({".pre-commit-config.yaml": PINNED_HOOKS, ".github/workflows/ci.yml": richer}) +done = convert(repo, apply=True) +after = snapshot(repo) +check( + "a richer sdlc ci job keeps its extra step, floated in place", + done.returncode == 0 + and "make generated-files" in after[".github/workflows/ci.yml"] + and "\n .sdlc/bin/sdlc ci\n" in after[".github/workflows/ci.yml"], + done.stderr, +) +for extra in (" env:\n FOO: bar\n", " services:\n db:\n image: x\n"): + job_level = OLD_CI.replace( + " runs-on: ubuntu-latest\n", f" runs-on: ubuntu-latest\n{extra}", 1 + ) + repo = make_repo( + {".pre-commit-config.yaml": PINNED_HOOKS, ".github/workflows/ci.yml": job_level} + ) + done = convert(repo, apply=True) + check( + f"a job with {extra.split(':')[0].strip()} is not replaced by the stub", + extra in snapshot(repo)[".github/workflows/ci.yml"], + done.stderr, + ) + +# Events and permissions are part of what a workflow does. One that runs on +# more than the stub does, or with other permissions, is not replaced. +for label, old_text, new_text in ( + ( + "a schedule", + "on:\n pull_request:\n", + "on:\n pull_request:\n schedule:\n - cron: '0 6 * * 1'\n", + ), + ( + "a release branch", + "on:\n pull_request:\n", + "on:\n pull_request:\n push:\n branches: [release]\n", + ), + ("a path filter", "on:\n pull_request:\n", "on:\n pull_request:\n paths: ['src/**']\n"), + ( + "workflow permissions", + "on:\n pull_request:\n", + "on:\n pull_request:\npermissions:\n contents: write\n", + ), + ( + "job permissions", + " runs-on: ubuntu-latest\n", + " runs-on: ubuntu-latest\n permissions:\n packages: write\n", + ), +): + text = OLD_CI.replace(old_text, new_text, 1) + repo = make_repo({".pre-commit-config.yaml": PINNED_HOOKS, ".github/workflows/ci.yml": text}) + done = convert(repo, apply=True) + kept = snapshot(repo)[".github/workflows/ci.yml"] + check( + f"a ci.yml with {label} keeps it, its step floated in place", + done.returncode == 0 + and new_text.strip() in kept + and "\n .sdlc/bin/sdlc ci\n" in kept, + done.stderr, + ) + +# The review's nits: what a replacement would silently change, or break. +renamed = OLD_CI.replace(" name: Code Quality (Gourmand)\n", " name: Gourmand\n") +repo = make_repo({".pre-commit-config.yaml": PINNED_HOOKS, ".github/workflows/ci.yml": renamed}) +done = convert(repo, apply=True) +check( + "a Gourmand job under another name keeps its workflow (its required check name)", + done.returncode == 0 and " name: Gourmand\n" in snapshot(repo)[".github/workflows/ci.yml"], + done.stderr, +) +with_env = OLD_CI.replace( + " - name: sdlc ci\n", " - name: sdlc ci\n env:\n FOO: bar\n" +) +repo = make_repo({".pre-commit-config.yaml": PINNED_HOOKS, ".github/workflows/ci.yml": with_env}) +before = snapshot(repo) +refused = convert(repo, apply=True) +check( + "an sdlc ci step with its own env is not replaced; it is refused, nothing written", + refused.returncode == REFUSED and snapshot(repo) == before, + refused.stderr, +) +for event in ("pull_request_target", "workflow_run", "issue_comment", "pull_request_review"): + privileged = MIXED.replace("on:\n pull_request:\n", f"on:\n {event}:\n") + repo = make_repo( + {".pre-commit-config.yaml": PINNED_HOOKS, ".github/workflows/tests.yml": privileged} + ) + before = snapshot(repo) + refused = convert(repo, apply=True) + check( + f"an sdlc ci step under {event} is refused, nothing written", + refused.returncode == REFUSED and snapshot(repo) == before, + refused.stderr, + ) +orphan = PUBLISH.replace( + " - run: echo quay.io/crunchtools/python-sdlc-extras\n", + ' - run: git clone --branch "$rev" https://github.com/crunchtools/python-sdlc x\n', +) +repo = make_repo( + { + ".pre-commit-config.yaml": PINNED_HOOKS, + ".github/workflows/ci.yml": OLD_CI, + ".github/workflows/publish.yml": orphan, + } +) +before = snapshot(repo) +refused = convert(repo, apply=True) +check( + "a kept workflow still cloning python-sdlc by rev is refused, nothing written", + refused.returncode == REFUSED and snapshot(repo) == before and "publish.yml" in refused.stderr, + refused.stderr, +) + +# ------------------------------------------------------------- symlinks + +# --apply writes, deletes and chmods. A checkout whose planned paths link +# elsewhere must not steer those at the runner's own files. +outside = Path(tempfile.mkdtemp()) / "victim" +outside.write_text("mine\n") +for linked in (".pre-commit-config.yaml", ".sdlc", ".github/workflows/gourmand.yml"): + files = {".pre-commit-config.yaml": PINNED_HOOKS, ".github/workflows/ci.yml": OLD_CI} + repo = make_repo({k: v for k, v in files.items() if k != linked}) + target = repo / linked + target.parent.mkdir(parents=True, exist_ok=True) + if target.exists(): + target.unlink() + target.symlink_to(outside.parent if linked == ".sdlc" else outside) + refused = convert(repo, apply=True) + check( + f"a symlinked {linked} is refused and nothing outside is touched", + refused.returncode == REFUSED + and outside.read_text() == "mine\n" + and not (outside.parent / "bin").exists(), + refused.stderr, + ) + + +# ------------------------------------------- review findings, one test each + +# 1. A second run is a no-op even when the converted file kept other hooks. +repo = make_repo({".pre-commit-config.yaml": RUFF_AND_STANDALONE}) +first = convert(repo, apply=True) +again = convert(repo, apply=True) +check( + "a converted repo that kept other hooks: the second run exits 0 and changes nothing", + first.returncode == 0 and again.returncode == 0 and again.stdout == "", + again.stderr + again.stdout, +) + + +def load(text: str) -> dict: + """The YAML, or {} when it does not load: a test reports, it does not crash.""" + try: + return yaml.safe_load(text) or {} + except yaml.YAMLError: + return {} + + +# 2. A block-style default_install_hook_types is replaced whole. +block_style = "default_install_hook_types:\n - pre-commit\n\n" + RUFF_AND_STANDALONE +repo = make_repo({".pre-commit-config.yaml": block_style}) +done = convert(repo, apply=True) +written = snapshot(repo)[".pre-commit-config.yaml"] +check( + "a block-style default_install_hook_types becomes valid YAML naming both", + done.returncode == 0 + and load(written).get("default_install_hook_types") == ["pre-commit", "pre-push"] + and " - pre-commit\n" not in written.split("repos:")[0], + done.stderr + written, +) + +# 3. A `repos:` in a header comment is not where the key goes. +commented = "# repos: below are the gates\n" + RUFF_AND_STANDALONE +repo = make_repo({".pre-commit-config.yaml": commented}) +done = convert(repo, apply=True) +written = snapshot(repo)[".pre-commit-config.yaml"] +check( + "a header comment that says repos: is left as it was", + done.returncode == 0 + and written.startswith("# repos: below are the gates\n") + and load(written).get("default_install_hook_types") == ["pre-commit", "pre-push"], + done.stderr + written, +) + +# 4. The guard: what would be written is parsed back and held to the wiring. +_SPEC = importlib.util.spec_from_file_location("convert_repo", SCRIPT) +C = importlib.util.module_from_spec(_SPEC) +_SPEC.loader.exec_module(C) +repo = make_repo({}) +good = { + repo / ".sdlc/bin/sdlc": BOOTSTRAP, + repo / ".pre-commit-config.yaml": HOOKS, + repo / ".github/workflows/ci.yml": CI, +} +for label, path, text in ( + ("YAML that does not load", ".github/workflows/ci.yml", "jobs: [\n"), + ("hooks without pre-push", ".pre-commit-config.yaml", HOOKS.replace(", pre-push]", "]")), + ("hooks still pinned", ".pre-commit-config.yaml", PINNED_HOOKS), + ("no sdlc ci job running the bootstrap", ".github/workflows/ci.yml", GOURMAND), +): + bad = {**good, repo / path: text} + try: + C.verify(repo, bad) + refused = False + except C.RefusedError: + refused = True + check(f"the guard refuses a plan with {label}", refused) +try: + C.verify(repo, good) + accepted = True +except C.RefusedError as exc: + accepted = False + print(exc) +check("the guard accepts the floating wiring", accepted) + + +def main() -> int: + print() + if FAILED: + print(f"{len(FAILED)} FAILED") + return 1 + print("all passed") + return 0 + + +if __name__ == "__main__": + sys.exit(main()) diff --git a/tests/test_host_contract.sh b/tests/test_host_contract.sh index f408da8..cfbc468 100755 --- a/tests/test_host_contract.sh +++ b/tests/test_host_contract.sh @@ -83,6 +83,17 @@ printf '%s\n' "\$*" >> "$LOG" for _last in "\$@"; do :; done # container-smoke: a detached run records which case it is, and inspect # answers that case's state as: Running ExitCode OOMKilled. +# The image's own entrypoint and command, for the systemd PID 1 check: an +# image named systemd-ep has ENTRYPOINT /sbin/init, one named systemd-cmd only +# CMD /usr/lib/systemd/systemd, and any other image neither. +case " \$* " in + *" image inspect "*) + case "\$*:\$_last" in + *Entrypoint*:*systemd-ep*) printf '/sbin/init\n' ;; + *Cmd*:*systemd-cmd*) printf '/usr/lib/systemd/systemd\n--system\n' ;; + esac + exit 0 ;; +esac case " \$* " in *" inspect "*) _st=\$(cat "$SHIM/upcase" 2>/dev/null) @@ -102,6 +113,17 @@ case " \$* " in *" logs "*) printf 'CONTAINER LOG\n'; exit 0 ;; *" rm -f "*) exit 0 ;; esac +# sdlc launcher REF: print this repo's launcher with the ref written in, as +# the image does -- or fail, or print nothing, as $SHIM/launchcase says. +case " \$* " in + *" launcher "*) + case "\$(cat "$SHIM/launchcase" 2>/dev/null)" in + fail) exit 125 ;; + empty) exit 0 ;; + esac + sed "s|^LAUNCHED_FROM=\$|LAUNCHED_FROM='\$_last'|" "$PWD/bin/sdlc" + exit 0 ;; +esac case " \$* " in *" plan gatehouse-direct "*) printf 'gatehouse${TAB}main${TAB}local${TAB}gatehouse\n' ;; @@ -149,6 +171,17 @@ case " \$* " in printf 'inject-comma${TAB}main${TAB}host${TAB}podman${US}run${US}--rm${US}--${US}a,b\n' ;; *" plan inject-nodd "*) printf 'inject-nodd${TAB}main${TAB}host-up${TAB}5${US}podman${US}run${US}--privileged${US}img\n' ;; + *" plan up-systemd-ep "*) + printf 'up-systemd-ep${TAB}main${TAB}host-up${TAB}1${US}podman${US}run${US}--${US}localhost/systemd-ep:sdlc\n' ;; + *" plan up-systemd-cmd "*) + printf 'up-systemd-cmd${TAB}main${TAB}host-up${TAB}1${US}podman${US}run${US}--${US}localhost/systemd-cmd:sdlc\n' ;; + *" plan up-systemd-args "*) + printf 'up-systemd-args${TAB}main${TAB}host-up${TAB}1${US}podman${US}run${US}--${US}localhost/systemd-cmd:sdlc${US}go-up-stays\n' ;; + *" plan lanes-skip "*) + printf 'b${TAB}one${TAB}image-ro${TAB}quiet-ok\n' + printf 'up-systemd-ep${TAB}two${TAB}host-up${TAB}1${US}podman${US}run${US}--${US}localhost/systemd-ep:sdlc\n' ;; + *" plan rc-four "*) + printf 'rc-four${TAB}main${TAB}image-ro${TAB}exit-four\n' ;; *" plan up-"*) _secs=1; _what=\$_last case "\$_last" in up-build) _what=build ;; up-noseconds) _secs=soon ;; esac @@ -177,6 +210,7 @@ case "\$_last" in rc-one) printf 'RAN rc-one\n'; exit 1 ;; rc-two) printf 'RAN rc-two\n'; exit 2 ;; rc-three) printf 'RAN rc-three\n'; exit 3 ;; + exit-four) printf 'RAN exit-four\n'; exit 4 ;; slow-rc-one) printf 'RAN slow-rc-one\n'; sleep 2; exit 1 ;; very-slow-rc-one) printf 'RAN very-slow-rc-one\n'; sleep 6; printf 'LAST LINE\n'; exit 1 ;; step-one) printf 'RAN step-one\n'; sleep 1 ;; @@ -254,12 +288,60 @@ log_mark PATH="$SHIM" sh bin/sdlc up-stays >/dev/null 2>&1 || true log_since if grep -q -- 'run -d --name sdlc-smoke-[0-9-]* --log-driver=k8s-file --cap-drop=all --security-opt=no-new-privileges .* -- localhost/x:sdlc go-up-stays$' "$RUN/podman.log" \ - && grep -q -- '^rm -f sdlc-smoke-' "$RUN/podman.log"; then - ok "host-up runs detached and locked down, and removes the container" + && grep -q -- '^rm -f -v sdlc-smoke-' "$RUN/podman.log"; then + ok "host-up runs detached and locked down, and removes the container and its volumes" else bad "host-up's run or cleanup is wrong: $(grep -E 'up-stays|rm -f' "$RUN/podman.log" | tail -2)" fi +# A systemd PID 1 cannot boot under this run's lockdown, so container-smoke +# says SKIPPED -- never "passed" -- and starts nothing. Not for an image whose +# CMD a run argument replaces, and a 4 from anything else is still a finding. +for case_ in up-systemd-ep up-systemd-cmd; do + log_mark + rc=0 + PATH="$SHIM" sh bin/sdlc "$case_" > "$RUN/out" 2>&1 || rc=$? + log_since + if [ "$rc" -eq 0 ] && grep -q "SKIPPED: the image starts .* as PID 1, and systemd PID 1 needs privileges smoke cannot grant" "$RUN/out" \ + && grep -q "== $case_ SKIPPED, not judged" "$RUN/out" && ! grep -q 'passed in' "$RUN/out" \ + && ! grep -q ' run -d ' "$RUN/podman.log"; then + ok "$case_: a systemd PID 1 is SKIPPED with its reason, never run and never a pass" + else + bad "$case_ exited $rc: $(tail -3 "$RUN/out")" + fi +done +log_mark +rc=0 +PATH="$SHIM" sh bin/sdlc up-systemd-args > "$RUN/out" 2>&1 || rc=$? +log_since +if [ "$rc" -eq 0 ] && grep -q ' run -d ' "$RUN/podman.log" && ! grep -q SKIPPED "$RUN/out"; then + ok "a run argument that replaces a systemd CMD is run and judged" +else + bad "up-systemd-args exited $rc: $(tail -2 "$RUN/out")" +fi +rc=0 +PATH="$SHIM" SDLC_CPUS=4 sh bin/sdlc lanes-skip > "$RUN/out" 2>&1 || rc=$? +if [ "$rc" -eq 0 ] && grep -q '== up-systemd-ep SKIPPED, not judged' "$RUN/out" \ + && grep -q '== b passed' "$RUN/out"; then + ok "in a lane, the skip is printed as SKIPPED and the run still exits 0" +else + bad "lanes-skip exited $rc: $(tail -4 "$RUN/out")" +fi +rc=0 +PATH="$SHIM" sh bin/sdlc rc-four > "$RUN/out" 2>&1 || rc=$? +if [ "$rc" -eq 1 ] && grep -q 'rc-four FAILED' "$RUN/out" && ! grep -q SKIPPED "$RUN/out"; then + ok "a 4 from a check in the image is a finding, not a skip" +else + bad "rc-four exited $rc: $(tail -2 "$RUN/out")" +fi + +# Every smoke cleanup, whatever the case, takes the anonymous volumes with it. +if grep -q -- '^rm -f -v sdlc-smoke-' "$LOG" && ! grep -q -- '^rm -f sdlc-smoke-' "$LOG"; then + ok "every smoke container is removed with -v" +else + bad "a smoke cleanup left its volumes: $(grep -- '^rm -f sdlc-smoke-' "$LOG" | head -1)" +fi + # A repo's config must never reach the host's podman as an option. The planner # refuses such an image; the launcher refuses it again, here, on the host. for case_ in inject-up inject-run inject-comma inject-nodd; do @@ -799,6 +881,119 @@ else fi rm -rf "$CREPO" +printf '\n== the floating launcher, from the image (bin/sdlc-bootstrap)\n\n' + +# A repo with no `rev:` runs the launcher the image prints. The bootstrap is the +# whole of what such a repo carries, so it is held to the same host contract: +# this PATH has podman and POSIX utilities and nothing else. +boot() { PATH="$SHIM" sh "$PWD/bin/sdlc-bootstrap" "$@"; } + +log_mark +boot tiers > "$RUN/out" 2>&1 || true +log_since +if grep -q -- '--security-opt=no-new-privileges --pull=newer -- quay.io/crunchtools/sdlc:latest launcher quay.io/crunchtools/sdlc:latest$' "$RUN/podman.log" \ + && last_run | grep -q -- ' quay.io/crunchtools/sdlc:latest tiers$' && ! last_run | grep -q -- '--pull' \ + && ! grep -q 'NOT THE PINNED RELEASE' "$RUN/out"; then + ok "no SDLC_IMAGE: the launcher from :latest runs :latest, no banner" +else + bad "bootstrap on :latest: $(last_run) / $(head -3 "$RUN/out")" +fi + +log_mark +SDLC_IMAGE=main boot tiers > "$RUN/out" 2>&1 || true +log_since +if grep -q -- '-- quay.io/crunchtools/sdlc:main launcher quay.io/crunchtools/sdlc:main$' "$RUN/podman.log" \ + && last_run | grep -q -- ' quay.io/crunchtools/sdlc:main tiers$' \ + && grep -q 'NOT THE PINNED RELEASE' "$RUN/out"; then + ok "SDLC_IMAGE=main: main's own launcher runs main, and says it is not the release" +else + bad "bootstrap on main: $(last_run) / $(head -3 "$RUN/out")" +fi + +# What the bootstrap runs is what it pulls, so it pulls from one repository: +# quay.io/crunchtools/sdlc at main, latest, a release or a digest. +D64=0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef +for good in "0.9.0:quay.io/crunchtools/sdlc:0.9.0" \ + "@sha256:$D64:quay.io/crunchtools/sdlc@sha256:$D64" \ + "quay.io/crunchtools/sdlc:main:quay.io/crunchtools/sdlc:main" \ + "quay.io/crunchtools/sdlc@sha256:$D64:quay.io/crunchtools/sdlc@sha256:$D64"; do + case "$good" in + @sha256:*|quay.io/crunchtools/sdlc@*) value=${good%:quay.io/*}; want=${good#"$value":} ;; + *) value=${good%%:quay.io/*}; want=${good#"$value":} ;; + esac + case "$good" in quay.io/crunchtools/sdlc:main:*) value=quay.io/crunchtools/sdlc:main; want=$value ;; esac + log_mark + SDLC_IMAGE=$value boot tiers > "$RUN/out" 2>&1 || true + log_since + if grep -q -- "-- $want launcher $want\$" "$RUN/podman.log" && last_run | grep -q -- " $want tiers\$"; then + ok "SDLC_IMAGE=$value pulls and runs $want" + else + bad "SDLC_IMAGE=$value: $(last_run) / $(tail -1 "$RUN/out")" + fi +done +for bad_ in localhost/sdlc:dev quay.io/evil/sdlc:latest quay.io/crunchtools/sdlcx:latest \ + 1.2 v1.2.3 1.2.3.4 1..3 @sha256:abc "@sha256:$(printf '%s' "$D64" | tr a G)" \ + 'main;id' '--privileged' quay.io/crunchtools/sdlc \ + quay.io/crunchtools/sdlc1.2.3 quay.io/crunchtools/sdlcmain; do + log_mark + rc=0 + SDLC_IMAGE=$bad_ boot tiers > "$RUN/out" 2>&1 || rc=$? + log_since + if [ "$rc" -eq 2 ] && grep -q 'is not main, latest, X.Y.Z or @sha256' "$RUN/out" \ + && ! [ -s "$RUN/podman.log" ]; then + ok "SDLC_IMAGE='$bad_' is refused (exit 2) before podman runs" + else + bad "SDLC_IMAGE='$bad_' exited $rc" + fi +done + +# Nothing printed must never become nothing run and exit 0. +for case_ in fail empty; do + printf '%s\n' "$case_" > "$SHIM/launchcase" + rc=0 + boot tiers > "$RUN/out" 2>&1 || rc=$? + if [ "$rc" -eq 2 ]; then + ok "an image that cannot print its launcher ($case_) is a 2" + else + bad "launcher $case_: bootstrap exited $rc" + fi +done +rm -f "$SHIM/launchcase" + +# The launcher's verdict is the bootstrap's: a 1 stays a 1. +rc=0 +rm -f "$SHIM/must-not-run" +boot lanes-keeps-going > "$RUN/out" 2>&1 || rc=$? +if [ "$rc" -eq 1 ] && grep -q 'RAN rc-one' "$RUN/out"; then + ok "the launcher's exit code comes back through the bootstrap" +else + bad "a failing check through the bootstrap exited $rc" +fi + +# Floating, the launcher needs no clone of python-sdlc: no IMAGE_TAG beside it. +FLOAT=$(mktemp -d) +sed "s|^LAUNCHED_FROM=\$|LAUNCHED_FROM='quay.io/crunchtools/sdlc:latest'|" bin/sdlc > "$FLOAT/sdlc" +log_mark +PATH="$SHIM" sh "$FLOAT/sdlc" tiers > "$RUN/out" 2>&1 || true +log_since +if last_run | grep -q -- ' quay.io/crunchtools/sdlc:latest tiers$'; then + ok "a printed launcher runs with no IMAGE_TAG and no clone" +else + bad "printed launcher alone: $(last_run) / $(head -2 "$RUN/out")" +fi +rm -rf "$FLOAT" + +# A converted repo carries the bootstrap as .sdlc/bin/sdlc, and its hooks and +# CI job start that file -- a script in the repo, which is what XII's host +# contract lets a `system` hook run -- and nothing else. +if grep -q '^ entry: \.sdlc/bin/sdlc commit$' examples/pre-commit-floating.yaml \ + && grep -q '^ entry: \.sdlc/bin/sdlc push$' examples/pre-commit-floating.yaml \ + && grep -q '^ run: \.sdlc/bin/sdlc ci$' examples/ci.yml; then + ok "the floating hooks and the CI stub run .sdlc/bin/sdlc" +else + bad "examples/ do not run .sdlc/bin/sdlc as the hooks and the CI job" +fi + # container-scan runs the gate's own image as a host step, and only the # launcher knows which image that is: the plan names it `@sdlc-image`. log_mark diff --git a/tests/test_plan.py b/tests/test_plan.py index 56bbf36..8e325ab 100644 --- a/tests/test_plan.py +++ b/tests/test_plan.py @@ -963,6 +963,47 @@ def scan_with(grype_rc: int, *, broken_cache: bool = False, **env) -> tuple[int os.environ["SDLC_ARGS"] = saved +# ----------------------------------------------- the launcher the image prints + +# A repo with no `rev:` gets bin/sdlc from the image, with the ref it was pulled +# by written in. The ref lands in a shell script, so it is checked first. +_launcher_saved = S.LAUNCHER +S.LAUNCHER = Path(__file__).resolve().parent.parent / "bin" / "sdlc" +try: + out = io.StringIO() + with contextlib.redirect_stdout(out): + rc = S.t_launcher("quay.io/crunchtools/sdlc:latest") + printed = out.getvalue() + original = S.LAUNCHER.read_text() + check("launcher prints bin/sdlc", rc == S.CLEAN and len(printed) > len(original) - 10) + check( + "launcher writes the ref into the one LAUNCHED_FROM line, quoted", + "LAUNCHED_FROM='quay.io/crunchtools/sdlc:latest'\n" in printed + and printed.replace("LAUNCHED_FROM='quay.io/crunchtools/sdlc:latest'\n", "LAUNCHED_FROM=\n") + == original, + ) + check("launcher with no ref cannot run", cannot_run(S.t_launcher, None) is not None) + for bad in [*INJECTIONS, "x'; touch /tmp/p; '", "$(id)", "quay.io/a:b\nrm -rf /"]: + check(f"launcher refuses ref {bad!r}", cannot_run(S.t_launcher, bad) is not None) + S.LAUNCHER = Path("/nonexistent/launcher") + check( + "an image without its launcher cannot run", + "ships no launcher" in (cannot_run(S.t_launcher, "localhost/x:y") or ""), + ) + # A launcher whose line was edited away must not be printed unpinned. + with tempfile.NamedTemporaryFile("w", suffix="sdlc", delete=False) as handle: + handle.write(original.replace("LAUNCHED_FROM=\n", "LAUNCHED_FROM=x\n")) + S.LAUNCHER = Path(handle.name) + check( + "a launcher with no LAUNCHED_FROM= line is refused", + "LAUNCHED_FROM" in (cannot_run(S.t_launcher, "localhost/x:y") or ""), + ) + os.unlink(handle.name) +finally: + S.LAUNCHER = _launcher_saved +check("launcher is a reserved name", "launcher" in S.RESERVED) + + def main() -> int: print() if FAILED: