From f1590cbb644e28a2535b598a38703f9706ca9194 Mon Sep 17 00:00:00 2001 From: Krzysztof kuhy Rudnicki Date: Tue, 4 Aug 2026 21:07:49 +0200 Subject: [PATCH] Pin prettier, shfmt and zsh too, not just shellcheck 23fdfcf pinned shellcheck because a version split between CI and developer machines kept the workflow red for a day. The same trap was still open for every other `language: system` tool, so close it for all of them. The risk is not identical across the four, and the code says which is which: shellcheck, zsh run in CI. Drift shows up as a CI failure the developer cannot reproduce -- the b83ce5d case exactly. prettier, shfmt never run in CI (pre-push and local git hook). They REWRITE files, so two developers on different versions reformat the repo back and forth. check_shellcheck_version becomes a table-driven check_pinned_tool_versions over PINNED_TOOL_VERSIONS, and _tool_version normalises the four different formats these tools report (shellcheck's `version:` line, shfmt's leading v, zsh's second field). zsh is compared on major.minor only: apt cannot select a patch release on the runner image, so 5.9.2 vs 5.9 is not a real divergence and must not become a permanent warning. CI gains a step installing prettier at an exact npm version and shfmt from a checksum-verified release binary, each asserting what PATH actually resolves to afterwards. Those two are unexercised by the current job by design -- the pin records the expected version in one place and protects any future workflow that does run them. Verified: YAML parses with all pins ahead of the hook step; the shfmt install ran verbatim with `sha256sum --check --strict` reporting OK and the version gate passing; prettier@3.9.5 resolves from the registry; the drift warning fires per-tool against stubbed prettier 3.0.0 and shfmt v3.0.0 (confirming v normalisation and that it reports every drifted tool, not just the first) and stays silent against the real toolchain; common.sh is shellcheck clean after rewording a comment that began "# shellcheck, zsh --" and was being parsed as a malformed directive; 1193 Python tests at 100% coverage. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_018ReVsw7qovYkkGbqcU9tn7 --- .github/workflows/pre-commit.yml | 44 ++++++++- .../pin-all-system-tools-2026-08-04.json | 66 +++++++++++++ linux_configuration/.githooks/lib/common.sh | 96 ++++++++++++++----- 3 files changed, 181 insertions(+), 25 deletions(-) create mode 100644 docs/superpowers/evidence/pin-all-system-tools-2026-08-04.json diff --git a/.github/workflows/pre-commit.yml b/.github/workflows/pre-commit.yml index a24bed77..9c40cbcf 100644 --- a/.github/workflows/pre-commit.yml +++ b/.github/workflows/pre-commit.yml @@ -16,8 +16,15 @@ jobs: with: python-version: "3.12" + # zsh backs the zsh-syntax hook. apt does not let a patch release be + # selected, so this is pinned only to what the runner image provides; + # the version is echoed so a jump shows up in the log rather than as a + # mystery parse difference. Local machines compare on major.minor only. - name: Install system dependencies - run: sudo apt-get update && sudo apt-get install -y zsh + run: | + set -euo pipefail + sudo apt-get update && sudo apt-get install -y zsh + zsh --version # Pin shellcheck instead of inheriting whatever ubuntu-latest ships. # @@ -53,6 +60,41 @@ jobs: fi echo "shellcheck ${installed} pinned and on PATH" + # prettier and shfmt do NOT run in this job -- prettier is a pre-push + # hook and shfmt runs from the local pre-commit git hook. They are + # pinned here anyway so this file stays the single place that records + # the expected version of every `language: system` tool, and so a future + # workflow that does run them inherits the pin instead of re-deriving + # it. Their real divergence risk is between developers: both REWRITE + # files, so two versions reformat the repo back and forth. + - name: Install prettier and shfmt (pinned) + env: + PRETTIER_VERSION: 3.9.5 + SHFMT_VERSION: v3.13.1 + SHFMT_SHA256: fb096c5d1ac6beabbdbaa2874d025badb03ee07929f0c9ff67563ce8c75398b1 + run: | + set -euo pipefail + npm install --global --no-fund --no-audit "prettier@${PRETTIER_VERSION}" + + curl -fsSL -o shfmt \ + "https://github.com/mvdan/sh/releases/download/${SHFMT_VERSION}/shfmt_${SHFMT_VERSION}_linux_amd64" + echo "${SHFMT_SHA256} shfmt" | sha256sum --check --strict + sudo install -m 0755 shfmt /usr/local/bin/shfmt + + # Assert what PATH actually resolves to, not what was just written: + # a copy earlier on PATH would otherwise win silently. + prettier_installed="$(prettier --version)" + shfmt_installed="$(shfmt --version)" + if [ "$prettier_installed" != "$PRETTIER_VERSION" ]; then + echo "::error::prettier on PATH is ${prettier_installed}, expected ${PRETTIER_VERSION}" >&2 + exit 1 + fi + if [ "$shfmt_installed" != "$SHFMT_VERSION" ]; then + echo "::error::shfmt on PATH is ${shfmt_installed}, expected ${SHFMT_VERSION}" >&2 + exit 1 + fi + echo "prettier ${prettier_installed} and shfmt ${shfmt_installed} pinned and on PATH" + - name: Install dependencies run: | python -m pip install --upgrade pip diff --git a/docs/superpowers/evidence/pin-all-system-tools-2026-08-04.json b/docs/superpowers/evidence/pin-all-system-tools-2026-08-04.json new file mode 100644 index 00000000..61c5287e --- /dev/null +++ b/docs/superpowers/evidence/pin-all-system-tools-2026-08-04.json @@ -0,0 +1,66 @@ +{ + "intent": "Extend the shellcheck version pin from 23fdfcf to every `language: system` tool the gates depend on -- prettier, shfmt and zsh -- so no hook can silently run a different binary on CI than on a developer machine, and so drift is reported at commit time rather than discovered as an unreproducible failure.", + "scope": [ + ".github/workflows/pre-commit.yml (pin prettier + shfmt, echo zsh version)", + "linux_configuration/.githooks/lib/common.sh (generalise the drift check to a table)", + "Non-goal: changing what any hook reports or how any file is formatted", + "Non-goal: pinning local tool versions, which come from pacman on a rolling distro", + "Non-goal: adding prettier or shfmt to the CI job's hook run; they remain pre-push and local-git-hook respectively" + ], + "changes": [ + "Replaced the single-purpose check_shellcheck_version() with a table-driven check_pinned_tool_versions() over PINNED_TOOL_VERSIONS, covering shellcheck 0.11.0, prettier 3.9.5, shfmt 3.13.1 and zsh 5.9. Each entry names the file pinning the other side, so the warning tells the developer exactly what to update.", + "Added _tool_version() to normalise the four different version formats: shellcheck's 'version:' line, shfmt's and node's leading 'v', and zsh's second field. Normalising at the source keeps the comparison a plain string match.", + "zsh is compared on major.minor only, because apt does not allow selecting a patch release on the runner image -- 5.9.2 locally versus 5.9 in CI is not a meaningful divergence and should not produce a permanent warning.", + "Added a workflow step installing prettier at an exact npm version and shfmt from a checksum-verified release binary, each followed by an assertion that PATH actually resolves to the pinned version rather than to a copy found earlier on PATH.", + "The zsh install step now echoes 'zsh --version' so a runner image bump appears in the log instead of surfacing as an unexplained parse difference.", + "Documented in both files WHY prettier and shfmt are pinned despite not running in CI: they rewrite files, so version drift between two developers reformats the repo back and forth." + ], + "verification": [ + { + "command": "python3 -c \"import yaml; yaml.safe_load(open('.github/workflows/pre-commit.yml'))\"", + "result": "pass", + "evidence": "Parses cleanly. Step order: checkout, setup-python, Install system dependencies, Install shellcheck (pinned), Install prettier and shfmt (pinned), Install dependencies, Run pre-commit hooks -- every pin lands before the hooks run." + }, + { + "command": "the shfmt install steps, executed verbatim in a scratch directory", + "result": "pass", + "evidence": "curl fetched shfmt_v3.13.1_linux_amd64; 'sha256sum --check --strict' reported 'shfmt: OK'; the binary reports v3.13.1, so the version gate passes. 'npm view prettier@3.9.5' confirms that exact version resolves from the registry." + }, + { + "command": "check_pinned_tool_versions with stubbed prettier 3.0.0 and shfmt v3.0.0 on PATH", + "result": "pass", + "evidence": "Emitted a separate warning per tool naming the installed and pinned versions plus both files to update, then the shared 'Results may differ' line. Confirms the 'v' prefix is normalised (v3.0.0 compared as 3.0.0) and that the check reports every drifted tool rather than stopping at the first." + }, + { + "command": "check_pinned_tool_versions against the real local toolchain", + "result": "pass", + "evidence": "Silent. Local shellcheck 0.11.0, prettier 3.9.5, shfmt v3.13.1 and zsh 5.9.2 all match their pins (zsh on major.minor)." + }, + { + "command": "shellcheck linux_configuration/.githooks/lib/common.sh", + "result": "pass", + "evidence": "Zero findings. An earlier revision failed with SC1073/SC1072 because a comment line began with '# shellcheck, zsh --', which shellcheck parsed as a malformed directive; the comment was reworded as prose." + }, + { + "command": "source the hook library and inspect verify_toolchain", + "result": "pass", + "evidence": "check_pinned_tool_versions is defined and is called from verify_toolchain, so the check runs on every hook invocation." + }, + { + "command": "bash ~/.claude/scripts/finish.sh gate ~/testsAndMisc <2 files>", + "result": "pass", + "evidence": "FINISH_GATE {\"risk\":\"review\",\"changed_files\":2,\"phase\":\"ok\"} with 1193 Python tests at 100% coverage." + } + ], + "risks": [ + "Four pinned versions now live in two files each and must be bumped together. The local warning exists to surface exactly that, but a developer who ignores it can still drift.", + "zsh cannot be pinned precisely on the runner image, so it is only compared on major.minor. A patch-level parse difference in zsh would still go unnoticed; the echoed version in the CI log is the mitigation.", + "CI now depends on the npm registry and a GitHub release asset being reachable. A transient outage fails the workflow rather than silently falling back, which is the intended direction but is a new external dependency.", + "prettier and shfmt are pinned in a job that does not currently run them, so the pin is unexercised by CI. It protects a future workflow that does run them, and documents the expected version in one place; the real enforcement for these two remains the local drift warning." + ], + "rollback": [ + "git revert the commit; the workflow steps are additive and the hook-library change swaps one function for a superset of it.", + "After reverting, CI returns to the runner image's prettier/shfmt (or none at all) and the local drift warning covers only shellcheck.", + "Confirm with: pre-commit run --all-files locally, sourcing the hook library to check verify_toolchain still resolves, and the next 'Pre-commit checks' CI run." + ] +} diff --git a/linux_configuration/.githooks/lib/common.sh b/linux_configuration/.githooks/lib/common.sh index 872e8220..751b15c2 100644 --- a/linux_configuration/.githooks/lib/common.sh +++ b/linux_configuration/.githooks/lib/common.sh @@ -89,33 +89,81 @@ Run this yourself, then retry: ! sudo pacman -S ${pkg}" } -# The shellcheck version CI pins (see .github/workflows/pre-commit.yml). -# Kept here so a drift between the two is visible locally, at commit time, -# rather than as a CI failure nobody can reproduce on their own machine. -readonly EXPECTED_SHELLCHECK_VERSION="0.11.0" - -# Warn when the local shellcheck disagrees with the one CI pins. +# Versions of the `language: system` tools that the gates depend on. Every +# entry is `command:expected:where`, where `where` names the file that pins +# the other side so a mismatch report can point at it. # -# Deliberately a warning, not an abort: shellcheck comes from pacman on a -# rolling distro, so a version bump here is routine and should not block a -# commit. What must not happen silently is the situation this check exists -# for -- local and CI disagreeing about what counts as a finding, so a commit -# passes every local gate and then fails CI on output the developer cannot -# reproduce. When this fires, update EXPECTED_SHELLCHECK_VERSION and -# SHELLCHECK_VERSION in the workflow together. -check_shellcheck_version() { - local installed +# Why this table exists: these hooks run whatever binary happens to be on +# PATH. When the local copy and the pinned copy disagree about what counts as +# a finding -- or, for the formatters, about how a file should be formatted -- +# a commit passes every local gate and then fails elsewhere on output the +# developer cannot reproduce. That is precisely what kept the pre-commit +# workflow red from b83ce5d onward, and it cost a full session to diagnose +# because the failure was invisible on the developer's machine. +# +# Two distinct risks are covered here. The linters (shellcheck and zsh) run +# in CI, so drift there shows up as an unreproducible CI failure. The +# formatters (prettier and shfmt) never run in CI -- they are pre-push and +# local-git-hook only -- but they REWRITE files, so drift between two +# developers silently reformats the repo back and forth, producing diff churn +# nobody intended. +readonly PINNED_TOOL_VERSIONS=( + "shellcheck:0.11.0:.github/workflows/pre-commit.yml (SHELLCHECK_VERSION)" + "prettier:3.9.5:.github/workflows/pre-commit.yml (PRETTIER_VERSION)" + "shfmt:3.13.1:.github/workflows/pre-commit.yml (SHFMT_VERSION)" + "zsh:5.9:.github/workflows/pre-commit.yml (zsh comes from apt; major.minor only)" +) - command -v shellcheck >/dev/null 2>&1 || return 0 +# Print the version of a pinned tool, normalised to bare digits. +# +# Each tool reports differently: shellcheck uses a `version:` line, shfmt and +# node prefix a `v`, zsh puts it in field 2. Normalising here keeps the +# comparison below a plain string match. +_tool_version() { + local cmd="$1" raw="" - installed="$(shellcheck --version 2>/dev/null | awk '/^version:/ { print $2 }')" - [[ -n $installed ]] || return 0 - [[ $installed == "$EXPECTED_SHELLCHECK_VERSION" ]] && return 0 + case "$cmd" in + shellcheck) raw="$(shellcheck --version 2>/dev/null | awk '/^version:/ { print $2 }')" ;; + prettier) raw="$(prettier --version 2>/dev/null)" ;; + shfmt) raw="$(shfmt --version 2>/dev/null)" ;; + # zsh patch releases are not selectable via apt, so compare major.minor + # only -- 5.9.2 locally and 5.9 in CI are not a meaningful divergence. + zsh) raw="$(zsh --version 2>/dev/null | awk '{ print $2 }' | cut -d. -f1,2)" ;; + *) return 1 ;; + esac - hook_log "⚠ shellcheck ${installed} locally, CI pins ${EXPECTED_SHELLCHECK_VERSION}." - hook_log " Findings may differ between here and CI. Update both:" - hook_log " .github/workflows/pre-commit.yml (SHELLCHECK_VERSION)" - hook_log " linux_configuration/.githooks/lib/common.sh (EXPECTED_SHELLCHECK_VERSION)" + printf '%s' "${raw#v}" +} + +# Warn when a local tool disagrees with the version pinned for CI. +# +# Deliberately warnings, not aborts: these arrive via pacman on a rolling +# distro, so bumps are routine and must not block a commit. What must not +# happen silently is the disagreement itself. +check_pinned_tool_versions() { + local entry cmd expected where installed drifted=0 + + for entry in "${PINNED_TOOL_VERSIONS[@]}"; do + cmd="${entry%%:*}" + where="${entry##*:}" + expected="${entry#*:}" + expected="${expected%%:*}" + + command -v "$cmd" >/dev/null 2>&1 || continue + + installed="$(_tool_version "$cmd")" || continue + [[ -n $installed ]] || continue + [[ $installed == "$expected" ]] && continue + + hook_log "⚠ ${cmd} ${installed} locally, pinned ${expected}" + hook_log " update: ${where}" + hook_log " update: linux_configuration/.githooks/lib/common.sh (PINNED_TOOL_VERSIONS)" + drifted=1 + done + + if [[ $drifted -eq 1 ]]; then + hook_log " Results may differ between this machine and CI/other developers." + fi } # Ensure every tool in REQUIRED_TOOLS is present. Fails closed on the first @@ -128,5 +176,5 @@ verify_toolchain() { require_tool "$cmd" "$pkg" done - check_shellcheck_version + check_pinned_tool_versions }