From 6932e3adceef1c76796fee600830bf6c954cf786 Mon Sep 17 00:00:00 2001
From: sneak <sneak@sneak.berlin>
Date: Tue, 6 Oct 2026 03:11:54 +0000
Subject: [PATCH] Run the linter only in Docker (closes #20)

script/lint now builds the new Dockerfile.lint, whose last step runs
golangci-lint. The build cache is off, so every run executes the
linter, and no image is kept. The Dockerfile lint stage calls
golangci-lint directly, since make lint is now a docker build of its
own. script/fmt no longer runs golangci-lint --fix, and
script/bootstrap no longer installs it. golangci-lint config verify is
left out: it fetches its schema over the network, unpinned. The README,
TODO.md and the script/cibuild comment say what now runs.

Model: opus-5-5
---
 Dockerfile       |  3 ++-
 Dockerfile.lint  | 13 +++++++++++++
 README.md        | 11 ++++++-----
 TODO.md          |  3 +++
 script/bootstrap |  7 +------
 script/cibuild   |  4 ++--
 script/fmt       |  1 -
 script/lint      |  7 +++++--
 8 files changed, 32 insertions(+), 17 deletions(-)
 create mode 100644 Dockerfile.lint

diff --git a/Dockerfile b/Dockerfile
index 31c56bf..b46d80b 100644
--- a/Dockerfile
+++ b/Dockerfile
@@ -6,7 +6,8 @@ COPY go.mod go.sum ./
 RUN go mod download
 COPY . .
 RUN make fmt-check
-RUN make lint
+# Called directly: make lint is itself a docker build (Dockerfile.lint).
+RUN golangci-lint run --config .golangci.yml ./...
 
 # Test stage: run full test suite
 # golang 1.22.12 (2025-02-04)
diff --git a/Dockerfile.lint b/Dockerfile.lint
new file mode 100644
index 0000000..a60b0dd
--- /dev/null
+++ b/Dockerfile.lint
@@ -0,0 +1,13 @@
+# Built by script/lint. The build runs golangci-lint, so a successful build
+# is a clean lint.
+#
+# `golangci-lint config verify` is left out on purpose: it downloads its
+# schema over the network on every run, unpinned.
+#
+# golangci/golangci-lint:v2.12.2 (Debian-based), 2026-08-07
+FROM golangci/golangci-lint:v2.12.2@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240
+WORKDIR /src
+COPY go.mod go.sum ./
+RUN go mod download
+COPY . .
+RUN golangci-lint run --config .golangci.yml ./...
diff --git a/README.md b/README.md
index 4cd1a4f..4d5dd7b 100644
--- a/README.md
+++ b/README.md
@@ -113,16 +113,17 @@ development workflow, and the Makefile targets are thin shims that call them.
 The scripts are POSIX sh (not bash) so they run in minimal containers such as
 alpine. We provide:
 
-- `script/bootstrap` — install all dependencies (go and golangci-lint if
-  missing, then `go mod download`)
+- `script/bootstrap` — install all dependencies (go if missing, then
+  `go mod download`); golangci-lint is not installed, since it runs only in
+  Docker
 - `script/setup` — set up the repo for development after a fresh clone: runs
   `script/bootstrap`, then `script/install-precommit`
 - `script/projectname` — output the project name (our own extension); used by
   `script/docker` for the image tag
 - `script/test` — run the test suite (`go test -v ./...`)
-- `script/lint` — run golangci-lint
-- `script/fmt` — format all files (goimports plus `golangci-lint run --fix`;
-  writes)
+- `script/lint` — run golangci-lint in Docker by building `Dockerfile.lint`
+  without the build cache, so every run lints; keeps no image
+- `script/fmt` — format all files with goimports (writes)
 - `script/fmt-check` — check formatting (read-only); fails if `gofmt -l`
   reports files
 - `script/check` — run all checks: `test`, `lint`, `fmt-check` (our own
diff --git a/TODO.md b/TODO.md
index 7cfdd45..173371d 100644
--- a/TODO.md
+++ b/TODO.md
@@ -24,6 +24,9 @@ files it depends on: .golangci.yml, REPO_POLICIES.md, .editorconfig,
 
 # Completed Steps
 
+* 2026-10-06: the linter runs only in Docker: `script/lint` builds
+    `Dockerfile.lint` without the build cache, and `script/bootstrap` no
+    longer installs golangci-lint
 * 2026-08-10: fixed every handler discarding slog attributes: console,
     JSON and webhook handlers now emit record attributes, accumulate
     WithAttrs without mutating the receiver, and honour WithGroup;
diff --git a/script/bootstrap b/script/bootstrap
index afece87..d0f3814 100755
--- a/script/bootstrap
+++ b/script/bootstrap
@@ -54,12 +54,7 @@ main() {
     if missing git; then pkg_install git git git git; fi
 
     if missing go; then pkg_install go golang go go; fi
-    # golangci-lint is packaged in nix, brew, and apk; there is no apt
-    # package (on apt hosts, install it from a hash-verified GitHub
-    # release archive manually, never curl | sh).
-    if missing golangci-lint; then
-        pkg_install golangci-lint golangci-lint golangci-lint golangci-lint
-    fi
+    # golangci-lint is not installed: it runs only in docker (script/lint).
 
     go mod download
 
diff --git a/script/cibuild b/script/cibuild
index 75cc3e6..20341d0 100755
--- a/script/cibuild
+++ b/script/cibuild
@@ -1,6 +1,6 @@
 #!/bin/sh
-# script/cibuild: run the CI build. The Dockerfile runs script/check, so
-# a successful build implies all checks pass.
+# script/cibuild: run the CI build. The Dockerfile runs the format check,
+# the linter and the tests, so a successful build means they all pass.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
diff --git a/script/fmt b/script/fmt
index 216a8aa..64817df 100755
--- a/script/fmt
+++ b/script/fmt
@@ -7,7 +7,6 @@ ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 main() {
     cd "$ROOT"
     goimports -l -w .
-    golangci-lint run --fix
 }
 
 main "$@"
diff --git a/script/lint b/script/lint
index 004c999..7277e99 100755
--- a/script/lint
+++ b/script/lint
@@ -1,12 +1,15 @@
 #!/bin/sh
-# script/lint: run the linter.
+# script/lint: run the linter, in docker only, by building Dockerfile.lint;
+# the build fails on any finding. --no-cache makes every run execute the
+# linter: a cached build of an unchanged tree succeeds without linting
+# anything. --output type=cacheonly keeps no image.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    golangci-lint run
+    docker build --no-cache --output type=cacheonly -f Dockerfile.lint .
 }
 
 main "$@"