build: isolate golangci-lint cache and lock per checkout (closes #121)

script/lint used golangci-lint's per-user global state, which breaks
when several checkouts on one host lint concurrently. Two independent
failure modes, two causes:

- Cross-contamination. The analysis cache (GOLANGCI_LINT_CACHE,
  default ~/.cache/golangci-lint) is keyed by content, not by
  checkout, so a hit written by another checkout is replayed with
  that checkout's file paths. A run reports findings for files it
  never linted.

- Lock collision. golangci-lint locks os.TempDir()/golangci-lint.lock
  (pkg/commands/run.go, acquireFileLock), which is NOT in the cache
  directory, with a 5s timeout. Peers that hold it longer make the
  run abort with "parallel golangci-lint is running" - a non-result
  that reads as a lint failure. Isolating the cache does not move it.

Point GOLANGCI_LINT_CACHE and TMPDIR at .lint-cache/ under the
checkout root, using the existing $ROOT idiom. TMPDIR is what makes
the lock per-checkout, so the lock keeps serialising the runs that
actually share a cache instead of being disabled. .lint-cache/ is
git-ignored and Docker-ignored, and the cache persists across runs in
a checkout, so caching is not lost.

Reproduced both modes on the unfixed script across 12 copies of this
tree: 10 of 12 concurrent runs void with the lock error, and 11 of 12
sequential runs reported findings at ../w1/... after an identical
lint-failing file was added to every copy. After the fix, 20-way
concurrency gives 0 void and 0 foreign paths, and each copy reports
only its own relative path.

.dockerignore

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

.gitignore

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

Dockerfile

@@ -5,7 +5,7 @@ FROM golang@sha256:f6751d823c26342f9506c03797d2527668d095b0a15f1862cddb4d927a7a4
 RUN apk add --no-cache git make gcc musl-dev binutils-gold
 
 # golangci-lint v2.12.2, 2026-08-07
-RUN go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2
+RUN go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@c0d3ddc9cf3faa61a4e378e879ece580256d76e5
 # goimports v0.42.0
 RUN go install golang.org/x/tools/cmd/goimports@009367f5c17a8d4c45a961a3a509277190a9a6f0
 

README.md

@@ -17,6 +17,26 @@ without requiring an external database.
 
 ---
 
+## No DNS mocking. Ever.
+
+**DNS is never mocked in this project — not in tests, not anywhere else.**
+No mock resolvers, no fake DNS servers, no stubbed lookups.
+
+dnswatcher's entire purpose is correct behavior against the real DNS.
+Tests exercise real iterative resolution against live nameservers by
+design; a test suite that passes against a mock proves nothing about the
+one thing this program exists to do.
+
+When live tests are flaky, that is a robustness problem, and it gets
+fixed with robustness: retries with backoff, querying multiple
+independent nameservers, longer timeouts — or explicit opt-in gating
+decided by the project owner. Never with mocks.
+
+Contributions that introduce mocked, faked, or stubbed DNS will be
+rejected.
+
+---
+
 ## Features
 
 ### DNS Domain Monitoring (Apex Domains)
@@ -367,7 +387,10 @@ 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
+- `script/lint` — run golangci-lint, with its cache and its lock file
+  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,10 +25,23 @@ confirm make check still passes.
 
 # Completed Steps
 
-- 2026-08-07: golangci-lint bumped to v2.12.2 (pins in `Dockerfile` and
-  `script/bootstrap`), `.golangci.yml` replaced with the canonical v2
-  config (settings moved under `linters.settings` so thresholds now
-  apply); fixed all resulting `goconst`, `dupl`, and `lll` findings
+- 2026-08-09: `script/lint` now isolates golangci-lint's per-user global
+  state to the checkout (#121): `GOLANGCI_LINT_CACHE` and `TMPDIR` are
+  both pointed at the git-ignored, Docker-ignored `.lint-cache/`. The
+  cache fixes cross-contamination; `TMPDIR` is what moves the lock,
+  which lives at `$TMPDIR/golangci-lint.lock` and not in the cache
+  directory. Reproduced both failure modes on the unfixed script (10 of
+  12 concurrent runs void with `parallel golangci-lint is running`; 11
+  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
+  (owner-authorized; same file is being landed as canonical via prompts
+  PR #24), with settings under `linters.settings` so the
+  lll/funlen/cyclop/dupl thresholds apply; fixed the resulting
+  `goconst`, `dupl`, and `lll` findings; the informational `gomodguard`
+  deprecation warning under this config is accepted
 - 2026-07-07 Adopted scripts-to-rule-them-all: `script/` entrypoints,
   Makefile shims, README Entrypoints section
 - 2026-02-20: iterative DNS resolver implemented; tests made hermetic

script/bootstrap

@@ -4,14 +4,14 @@
 # installed tools are skipped. Base tooling comes from nix, apt, brew,
 # or apk (detected in that order); assumes nothing is present.
 # golangci-lint and goimports are installed via `go install` at the same
-# pinned refs the Dockerfile uses (never "latest").
+# pinned commits the Dockerfile uses (never "latest").
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
 
 # Pinned versions, 2026-08-07 (same pins as the Dockerfile)
 # golangci-lint v2.12.2
-GOLANGCI_LINT_REF="github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.12.2"
+GOLANGCI_LINT_REF="github.com/golangci/golangci-lint/v2/cmd/golangci-lint@c0d3ddc9cf3faa61a4e378e879ece580256d76e5"
 # goimports v0.42.0
 GOIMPORTS_REF="golang.org/x/tools/cmd/goimports@009367f5c17a8d4c45a961a3a509277190a9a6f0"
 

script/lint

@@ -1,11 +1,40 @@
 #!/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 ./...
 }