build: always install pinned lint tools in script/bootstrap (closes #117)

`script/bootstrap` guarded its pinned `go install` calls with
`missing()`, which only tests whether a binary is on `PATH`. On any
machine that already had some `golangci-lint`, the install was skipped
and the commit pin had no effect: a v1.x binary cannot parse this
repo's v2-schema `.golangci.yml`, and a different v2.x can silently
disagree with CI. The same reasoning made the v2.12.2 pin bump inert
on every already-provisioned machine.

Install both pinned tools unconditionally. `go install` at a fixed
commit ref is idempotent and cheap with a warm module cache, so
skipping it saved nothing. The `missing()` presence check is kept for
`git`, `make`, and `go`, which really are system-package presence
checks.

Also warn when `PATH` resolves either tool somewhere other than the
directory `go install` writes to, since a shadowing copy earlier on
`PATH` is what `make lint` and `make fmt` would actually run. This is
a warning, not a failure: the remedy is the user's `PATH`.

The pins themselves are unchanged and still match the Dockerfile.

.dockerignore

@@ -1,6 +1,5 @@
 .git/
 bin/
-.lint-cache/
 *.md
 LICENSE
 .editorconfig

.gitignore

@@ -1,7 +1,6 @@
 bin/
 vendor/
 data/
-.lint-cache/
 .env
 *.exe
 /dnswatcher

README.md

@@ -387,10 +387,7 @@ them. We provide:
 - `script/projectname` — print the project name (used for the Docker
   image tag)
 - `script/test` — run the test suite (race detector, coverage)
-- `script/lint` — run golangci-lint, with its cache and its lock file
+- `script/lint` — run golangci-lint
-  isolated to this checkout (under the git-ignored `.lint-cache/`) so
-  concurrent checkouts on one host cannot share cache entries or
-  contend on a single lock
 - `script/fmt` — format all code (gofmt -s, goimports)
 - `script/fmt-check` — check formatting (read-only)
 - `script/check` — run test, lint, and fmt-check

TODO.md

@@ -25,15 +25,13 @@ confirm make check still passes.
 
 # Completed Steps
 
-- 2026-08-09: `script/lint` now isolates golangci-lint's per-user global
+- 2026-08-09: `script/bootstrap` now installs the pinned `golangci-lint`
-  state to the checkout (#121): `GOLANGCI_LINT_CACHE` and `TMPDIR` are
+  and `goimports` unconditionally instead of only when the binary is
-  both pointed at the git-ignored, Docker-ignored `.lint-cache/`. The
+  absent from `PATH`, so the commit pins actually take effect on
-  cache fixes cross-contamination; `TMPDIR` is what moves the lock,
+  already-provisioned machines; it also warns when `PATH` resolves
-  which lives at `$TMPDIR/golangci-lint.lock` and not in the cache
+  either tool to a copy outside the directory `go install` writes to.
-  directory. Reproduced both failure modes on the unfixed script (10 of
+  The `missing` presence check is retained for `git`, `make`, and `go`
-  12 concurrent runs void with `parallel golangci-lint is running`; 11
+  (#117)
-  of 12 reporting another checkout's paths) and both are gone at 20-way
-  concurrency after the fix
 - 2026-08-07: golangci-lint bumped to v2.12.2 (commit-pinned installs
   in `Dockerfile` and `script/bootstrap`); `.golangci.yml` set to the
   org-standard v2-schema config used across the org's repos

script/bootstrap

@@ -1,10 +1,13 @@
 #!/bin/sh
 # script/bootstrap: install all dependencies needed to build and develop
-# this repo. Idempotent: every install is guarded by a check so already
+# this repo. Base tooling (git, make, go) comes from nix, apt, brew, or
-# installed tools are skipped. Base tooling comes from nix, apt, brew,
+# apk (detected in that order) and is installed only when absent;
-# or apk (detected in that order); assumes nothing is present.
+# assumes nothing is present. golangci-lint and goimports are always
-# golangci-lint and goimports are installed via `go install` at the same
+# (re)installed via `go install` at the same pinned commits the
-# pinned commits the Dockerfile uses (never "latest").
+# Dockerfile uses (never "latest") -- a presence check cannot tell the
+# pinned build from an arbitrary one already on PATH, so guarding them
+# would make the pins inert. Idempotent either way: running this twice
+# succeeds both times and leaves the same result.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
@@ -62,6 +65,31 @@ missing() {
     ! command -v "$1" >/dev/null 2>&1
 }
 
+# go_bin_dir: directory `go install` writes binaries to.
+go_bin_dir() {
+    gobin="$(go env GOBIN)"
+    if [ -n "$gobin" ]; then
+        echo "$gobin"
+    else
+        echo "$(go env GOPATH)/bin"
+    fi
+}
+
+# warn_if_shadowed <tool> <dir>: the pinned build was just installed
+# into <dir>. If PATH resolves <tool> anywhere else, that other copy is
+# what `make lint` and `make fmt` will actually run, and it is not the
+# pinned version. Warn loudly rather than failing, since the fix is the
+# user's PATH and not anything this script can do.
+warn_if_shadowed() {
+    resolved="$(command -v "$1" 2>/dev/null || true)"
+    if [ "$resolved" != "$2/$1" ]; then
+        echo "bootstrap: WARNING: installed pinned $1 to $2/$1, but PATH" >&2
+        echo "bootstrap: WARNING: resolves $1 to ${resolved:-(not on PATH)};" >&2
+        echo "bootstrap: WARNING: put $2 first on PATH or lint results will" >&2
+        echo "bootstrap: WARNING: not match CI." >&2
+    fi
+}
+
 main() {
     cd "$ROOT"
 
@@ -69,10 +97,17 @@ main() {
     if missing make; then pkg_install gnumake make make make; fi
     if missing go; then pkg_install go golang go go; fi
 
-    # Lint/format tools, pinned via go install (installs into
+    # Lint/format tools, pinned via go install. These are installed
-    # "$(go env GOPATH)/bin"; ensure that is on your PATH).
+    # unconditionally: `command -v` only proves *some* build is on PATH,
-    if missing golangci-lint; then go install "$GOLANGCI_LINT_REF"; fi
+    # and a wrong golangci-lint either cannot parse our v2-schema
-    if missing goimports; then go install "$GOIMPORTS_REF"; fi
+    # .golangci.yml at all or silently disagrees with CI. Installing at
+    # a fixed commit ref is idempotent and cheap with a warm module
+    # cache, so there is nothing to save by skipping it.
+    GOBIN_DIR="$(go_bin_dir)"
+    go install "$GOLANGCI_LINT_REF"
+    go install "$GOIMPORTS_REF"
+    warn_if_shadowed golangci-lint "$GOBIN_DIR"
+    warn_if_shadowed goimports "$GOBIN_DIR"
 
     go mod download
 

script/lint

@@ -1,40 +1,11 @@
 #!/bin/sh
 # script/lint: run the linter.
-#
-# golangci-lint keeps two pieces of per-user global state, and both of
-# them break when several checkouts on one host lint concurrently:
-#
-#   1. Its analysis cache (GOLANGCI_LINT_CACHE, default
-#      ~/.cache/golangci-lint). Entries are keyed by content, not by
-#      checkout, so a hit written by another checkout is replayed
-#      verbatim - including that checkout's file paths. The run then
-#      reports findings for files it never linted.
-#
-#   2. Its "one runner at a time" lock, which does NOT live in the
-#      cache directory: golangci-lint locks
-#      $(os.TempDir())/golangci-lint.lock, i.e.
-#      "$TMPDIR"/golangci-lint.lock (pkg/commands/run.go,
-#      acquireFileLock). It waits 5s, then aborts with "parallel
-#      golangci-lint is running" - a non-result that looks like a lint
-#      failure. Setting GOLANGCI_LINT_CACHE alone does not move it.
-#
-# So both are pinned under the checkout root. The cache is never shared,
-# and TMPDIR makes the lock file per-checkout, which keeps the lock
-# doing its actual job (serialising runs that share one cache) at the
-# right scope. .lint-cache/ is git-ignored and Docker-ignored, and
-# caching still works: it persists across runs in this checkout.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-
-    GOLANGCI_LINT_CACHE="$ROOT/.lint-cache/cache"
-    TMPDIR="$ROOT/.lint-cache/tmp"
-    export GOLANGCI_LINT_CACHE TMPDIR
-    mkdir -p "$GOLANGCI_LINT_CACHE" "$TMPDIR"
-
     golangci-lint run --config .golangci.yml ./...
 }