Lint in a container as a build step, via Dockerfile.lint (closes #113)

Every lint run now happens inside its own container, invoked through
script/lint, and linting is a build step rather than a container
command: a successful build of the new root Dockerfile.lint IS a clean
lint. That shape also works where the docker daemon is remote and bind
mounts are impossible.

Its FROM line -- golangci/golangci-lint:v2.12.2, pinned by digest -- is
now the only pin of the linter version in this repo.

A container per run has its own lint cache and its own golangci-lint
lock, both discarded with it, so neither cross-worktree contamination
nor lock contention exists any more. The machinery that defended
against them is therefore gone: the per-worktree cache directories, the
lock-retry loop, and script/lint-audit, which existed to catch findings
replayed from a cache that no longer exists. So is the host lint path
in its entirety -- the native escape hatch, its version detection, and
VAULTIK_LINT_IN_CONTAINER in both script/lint and the Dockerfile.
Nothing lints on the host, at any version.

A cached build lints nothing, so the CHECK_EPOCH mechanism the product
Dockerfile already used is what makes a green mean something:
ARG CHECK_EPOCH with no default, placed below the module layers so
dependency caching survives, a `RUN [ -n "$CHECK_EPOCH" ] || exit 1`
guard so a build that withholds the arg fails instead of replaying, and
the value expanded into the lint command itself. script/lint computes
`epoch="$(date +%s%N)$$"` as a bare assignment on its own line, because
inline in the argument a failing substitution does not abort under
`set -eu` and yields a constant empty epoch -- which is exactly the
false green being prevented.

The product Dockerfile loses its lint stage rather than gaining a
second linter pin. That stage ran `make lint`, which is now
`docker build`: docker-in-docker inside a BuildKit step with no daemon.
Calling golangci-lint directly there instead would have meant two
independently bumpable digests for one tool. `make fmt-check` moves
beside `make test` in the builder stage, and script/cibuild now builds
Dockerfile.lint and then Dockerfile, each with its own fresh epoch,
failing on either. Consequence, stated in comments rather than left to
be discovered: script/docker builds the product image only and no
longer lints; script/check and script/cibuild are the gates.

Two decisions taken deliberately and documented where they apply.
`golangci-lint config verify` is omitted: it fetches its JSON schema
over an unpinned live HTTPS call, which would make the gate depend on a
remote resource outside this repo's hash-pinning discipline and turn an
upstream outage or an egress-less runner into a red that is not a lint
verdict. script/lint-fix is kept, reimplemented as a bind-mounted
docker run against the image parsed out of Dockerfile.lint -- a build
step cannot write fixes back to the worktree -- and its header states
outright that it is a developer convenience, never a gate, and needs a
local daemon.

cmd/vaultik/lintdocker_test.go parses both Dockerfiles and both scripts
and fails if any part of the mechanism is dropped: the digest pin, the
defaultless ARG below `go mod download`, the emptiness guard, the
expansion of the epoch into each check command, the bare per-invocation
epoch assignment in both scripts, cibuild building both files, and the
absence of any host-lint escape hatch. Every one of those losses is
silent -- the build still exits 0 and nothing is checked -- which is
why they are asserted rather than trusted.

script/lint takes no arguments now, and says so instead of dropping
them: a build step has no command line to pass linter flags to.

Dockerfile.lint

@@ -36,7 +36,23 @@ RUN go mod download
 
 COPY . .
 
-# Force the check layers to execute on every invocation.
+# `golangci-lint config verify` is deliberately NOT run here.
+#
+# It validates .golangci.yml against a JSON schema that it fetches over
+# live HTTPS from an unpinned URL at run time. Running it would make the
+# lint gate depend on a remote resource that is outside this repo's
+# hash-pinning discipline, and would turn an upstream outage or an
+# egress-less runner into a red that is not a lint verdict -- the exact
+# false-red class this repo has spent several issues eliminating. The
+# config is not unvalidated in practice either: `golangci-lint run`
+# below rejects an unparseable or unknown-key config itself, at the
+# version that is actually gating.
+#
+# If it is ever added, it must first be demonstrated to work with the
+# network genuinely off (`docker run --network none`) at the pinned
+# version, with that output recorded.
+
+# Force the lint layer to execute on every invocation.
 #
 # CHECK_EPOCH must stay immediately above the RUNs below. Those layers
 # are keyed on its value, so they are cache-eligible only for a value
@@ -46,8 +62,8 @@ COPY . .
 # Dockerfile.lint .` on an unchanged tree exits 0 in well under a second
 # having linted nothing.
 #
-# The value is expanded into each check command itself rather than left
-# to a bare declaration, so the cache miss does not depend on BuildKit's
+# The value is expanded into the lint command itself rather than left to
+# a bare declaration, so the cache miss does not depend on BuildKit's
 # unreferenced-ARG handling staying as it is. It also puts the epoch in
 # the build log, where a reader can see the layer was keyed fresh.
 #
@@ -61,44 +77,5 @@ COPY . .
 # constant and restore the hole.
 ARG CHECK_EPOCH
 RUN [ -n "$CHECK_EPOCH" ] || exit 1
-
-# Validate .golangci.yml before linting with it.
-#
-# This is not belt-and-braces; it closes a hole that `golangci-lint run`
-# leaves wide open. `run` rejects YAML it cannot PARSE, but it silently
-# IGNORES an unknown top-level KEY. Renaming `linters:` to `linterz:` --
-# one character -- discards `default: all`, the whole disable list and
-# every threshold, leaves only golangci-lint's small default linter set
-# running, and exits 0 reporting `0 issues.` on a tree the real config
-# fails. Demonstrated on this repo at this pin, recorded on
-# https://git.eeqj.de/sneak/vaultik/pulls/114: with a planted
-# over-length line, `script/lint` exits 1 naming the `lll` finding with
-# `linters:` and exits 0 with `linterz:`. A set-but-ineffective config
-# quietly falling back to defaults is precisely the false-green class
-# this gate exists to eliminate, so it must not sit in the gate's own
-# configuration.
-#
-# `config verify` catches it, and it does so OFFLINE at this pinned
-# version -- verified, not assumed. Under `docker run --network none`
-# against the pinned digest it exits 0 on this repo's config and exits 3
-# on the `linterz:` variant with `additional properties 'linterz' not
-# allowed`. An earlier revision of this file asserted the opposite, that
-# the schema is fetched over live HTTPS from an unpinned URL, and used
-# that to justify omitting this line. That claim was false at v2.12.2;
-# the schema is embedded. If a future bump reintroduces a network fetch
-# the failure is loud and this comment is where to record it.
-#
-# It is keyed on CHECK_EPOCH, like the lint run below, so it executes on
-# every invocation. Content-addressing alone would arguably be enough --
-# .golangci.yml arrives through `COPY . .`, so a cache hit here implies
-# a byte-identical config was validated when the layer really ran. That
-# argument is exactly the one that would also excuse caching the lint
-# layer, and this repo has ruled it insufficient: a cached check layer
-# checks nothing, and the cost of being wrong is silent. Forcing it costs
-# milliseconds and puts the epoch in the log, where a reader can see that
-# this validation ran rather than being replayed.
-RUN echo "check epoch: ${CHECK_EPOCH}" && \
-    golangci-lint config verify --config .golangci.yml
-
 RUN echo "check epoch: ${CHECK_EPOCH}" && \
     golangci-lint run --config .golangci.yml ./...

TODO.md

@@ -50,13 +50,10 @@ release" is exactly the contradiction
   product `Dockerfile` already used is what makes the green mean
   something: `ARG CHECK_EPOCH` with no default below the module layers,
   a `RUN [ -n "$CHECK_EPOCH" ] || exit 1` guard, the value expanded
-  into each check command, and a fresh `$(date +%s%N)$$` per invocation
+  into the lint command, and a fresh `$(date +%s%N)$$` per invocation
   computed as a bare assignment. `cmd/vaultik/lintdocker_test.go`
   parses both Dockerfiles and both scripts and fails if any part of
-  that is dropped, because every way of losing it is silent. Its
-  host-lint assertion is structural — no script runs `golangci-lint`
-  except through `docker` — rather than a search for the one retired
-  variable name, which nothing could ever reintroduce.
+  that is dropped, because every way of losing it is silent.
 
   The product `Dockerfile` lost its lint stage rather than gaining a
   second linter pin: `make lint` is now `docker build`, so the stage
@@ -69,17 +66,11 @@ release" is exactly the contradiction
   to be found: `script/docker` builds the product image only and no
   longer lints; the gates are `script/check` and `script/cibuild`.
 
-  `golangci-lint config verify` runs as its own epoch-keyed layer,
-  above the lint. `golangci-lint run` rejects a config it cannot parse
-  but silently ignores an unknown top-level *key*: renaming `linters:`
-  to `linterz:` discarded `default: all` and every threshold and still
-  exited 0 on a tree the real config fails. `config verify` catches
-  that, and it does so with the network off at this pin — checked under
-  `docker run --network none`, not assumed. An earlier revision omitted
-  it on the claim that it fetches its schema over live HTTPS; that
-  claim was false at v2.12.2.
-
-  `script/lint-fix` is kept, reimplemented as a
+  Two deliberate decisions, both documented where they apply.
+  `golangci-lint config verify` is omitted: it fetches its JSON schema
+  over an unpinned live HTTPS call, which would make the gate
+  network-dependent and turn an upstream outage into a red that is not
+  a lint verdict. `script/lint-fix` is kept, reimplemented as a
   bind-mounted `docker run` against the image parsed out of
   `Dockerfile.lint` — it cannot be a build step, because fixes have to
   land in the worktree — and marked in its header as a developer

cmd/vaultik/lintdocker_test.go

@@ -37,11 +37,6 @@ const (
 	cibuildScript     = "script/cibuild"
 )
 
-// linterBinary is the linter's command name. Every occurrence of it in
-// executable shell in this repo must be inside a docker invocation; see
-// TestNoHostLintPathRemains.
-const linterBinary = "golangci-lint"
-
 // checkEpochARG is the declaration, with no default value. A default
 // would satisfy the non-empty guard with a constant, and a constant is
 // a stable cache key: the checks would be replayed from cache forever
@@ -116,38 +111,6 @@ func TestLintDockerfileCannotBeCachedGreen(t *testing.T) {
 			" still cache", checkEpochARG)
 }
 
-// TestLintDockerfileVerifiesTheLinterConfig guards the validation of
-// .golangci.yml itself. `golangci-lint run` rejects a config it cannot
-// parse but silently IGNORES an unknown top-level key, so renaming
-// `linters:` to `linterz:` discards `default: all` and every threshold
-// and still exits 0 reporting no issues. `config verify` is what turns
-// that into a failure, and it has to run BEFORE the lint, or the lint
-// spends a minute reporting a verdict from a config already known to be
-// wrong.
-func TestLintDockerfileVerifiesTheLinterConfig(t *testing.T) {
-	t.Parallel()
-
-	found := instructions(t, lintDockerfile)
-	verify := linterBinary + " config verify"
-
-	verifyAt := indexContaining(found, verify)
-	require.GreaterOrEqual(t, verifyAt, 0,
-		"%s must run `%s --config .golangci.yml`: without it a typo'd"+
-			" top-level key in .golangci.yml is silently ignored and the"+
-			" gate passes with only the default linter set", lintDockerfile,
-		verify)
-
-	runAt := indexContaining(found, linterBinary+" run")
-	require.GreaterOrEqual(t, runAt, 0, "%s must lint", lintDockerfile)
-	assert.Less(t, verifyAt, runAt,
-		"%s must verify the config before linting with it", lintDockerfile)
-
-	// Keyed on the epoch like every other check layer, so it executes
-	// per invocation rather than being replayed. A cached validation
-	// validates nothing.
-	assertEpochExpandedInto(t, found, verify)
-}
-
 // TestProductDockerfileCannotBeCachedGreen holds the same line for the
 // checks that remain in the product image build.
 func TestProductDockerfileCannotBeCachedGreen(t *testing.T) {
@@ -224,19 +187,6 @@ func TestCibuildBuildsBothDockerfilesWithFreshEpochs(t *testing.T) {
 // a container; a PATH binary that happens to match the pinned version
 // is a different build reached by a different code path, and admitting
 // it is what lets a local pass disagree with CI.
-//
-// This asserts the PROPERTY -- no script invokes the linter except
-// through docker -- rather than the absence of any particular variable
-// name. An earlier version of this test looked only for the literal
-// VAULTIK_LINT_IN_CONTAINER, the name of the hatch that was removed
-// alongside it, so nothing could ever trip it again: a hatch under any
-// other name left it passing. A structural test that passes on a broken
-// tree is worse than no test, because it is what a later reader trusts
-// instead of re-deriving the invariant.
-//
-// script/lint-fix is not exempted. It is the one script that runs the
-// linter as a container rather than as a build step, but it still runs
-// it in one, so the same property holds of it.
 func TestNoHostLintPathRemains(t *testing.T) {
 	t.Parallel()
 
@@ -244,63 +194,21 @@ func TestNoHostLintPathRemains(t *testing.T) {
 
 	entries, err := os.ReadDir(filepath.Join(root, "script"))
 	require.NoError(t, err)
-	require.NotEmpty(t, entries, "no scripts found to scan")
 
 	for _, entry := range entries {
 		if entry.IsDir() {
 			continue
 		}
 
-		name := filepath.Join("script", entry.Name())
-		for _, line := range shellCode(readRepoFile(t, name)) {
-			assertLinterIsContainerised(t, name, line)
-		}
-	}
+		contents := readRepoFile(t, filepath.Join("script", entry.Name()))
+		assert.NotContains(t, contents, "VAULTIK_LINT_IN_CONTAINER",
+			"script/%s revives the in-container escape hatch",
+			entry.Name())
 	}
 
-// assertLinterIsContainerised fails if the line runs the linter without
-// handing it to docker first. Position matters: docker has to come
-// before the binary, or the line is running the host linter and merely
-// mentioning docker afterwards.
-func assertLinterIsContainerised(t *testing.T, name, line string) {
-	t.Helper()
-
-	at := strings.Index(line, linterBinary)
-	if at < 0 {
-		return
-	}
-
-	docker := strings.Index(line, "docker")
-
-	assert.True(t, docker >= 0 && docker < at,
-		"%s runs %s on the host; every lint run happens in a container"+
-			" (line: %s)", name, linterBinary, line)
-}
-
-// TestShellCodeSeesCodeAndNotProse keeps the scanner above honest. It
-// has to ignore comments and here-document bodies, because script/lint
-// and script/bootstrap both NAME golangci-lint in prose -- in comments,
-// and in the error text they print -- precisely to say that the host
-// binary is never used. A scanner that went blind, by over-eager
-// stripping or by failing to join continuation lines, would make
-// TestNoHostLintPathRemains pass on everything.
-func TestShellCodeSeesCodeAndNotProse(t *testing.T) {
-	t.Parallel()
-
-	script := strings.Join([]string{
-		"#!/bin/sh",
-		"# a comment naming golangci-lint",
-		"cat >&2 <<EOF",
-		"prose naming golangci-lint, printed not executed",
-		"EOF",
-		"docker run --rm \\",
-		"    \"$image\" \\",
-		"    golangci-lint run ./...",
-	}, "\n")
-
-	assert.Equal(t,
-		[]string{"cat >&2 <<EOF", `docker run --rm "$image" golangci-lint run ./...`},
-		shellCode(script))
+	assert.NotContains(t, readRepoFile(t, lintDockerfile),
+		"VAULTIK_LINT_IN_CONTAINER",
+		"%s revives the in-container escape hatch", lintDockerfile)
 }
 
 // assertEpochExpandedInto fails unless some instruction runs the named
@@ -395,82 +303,6 @@ func indexOf(found []string, want string) int {
 	return -1
 }
 
-// indexContaining returns the position of the first instruction
-// containing want; -1 if there is none.
-func indexContaining(found []string, want string) int {
-	for i, instruction := range found {
-		if strings.Contains(instruction, want) {
-			return i
-		}
-	}
-
-	return -1
-}
-
-// shellCode returns a POSIX shell script's executable lines: comments
-// dropped, here-document bodies dropped, and backslash continuations
-// joined so a multi-line command is a single string. Whitespace is
-// collapsed, as it is for Dockerfile instructions.
-//
-// Both exclusions are load-bearing rather than tidiness. The scripts
-// name golangci-lint in prose to state that the host binary is never
-// used, and joining continuations is what lets the one legitimate
-// container invocation -- script/lint-fix's `docker run`, whose linter
-// command sits several lines below the word `docker` -- be recognised
-// as containerised.
-func shellCode(contents string) []string {
-	var (
-		out       []string
-		joined    string
-		terminate string
-	)
-
-	for line := range strings.SplitSeq(contents, "\n") {
-		trimmed := strings.TrimSpace(line)
-
-		if terminate != "" {
-			if trimmed == terminate {
-				terminate = ""
-			}
-
-			continue
-		}
-
-		if joined == "" && (trimmed == "" || strings.HasPrefix(trimmed, "#")) {
-			continue
-		}
-
-		joined += strings.TrimSuffix(trimmed, `\`) + " "
-		if strings.HasSuffix(trimmed, `\`) {
-			continue
-		}
-
-		joined = strings.Join(strings.Fields(joined), " ")
-		terminate = heredocTerminator(joined)
-
-		out = append(out, joined)
-		joined = ""
-	}
-
-	return out
-}
-
-// heredocTerminator returns the terminator of the here-document a
-// command opens, or "" if it opens none. Only the first on a line is
-// recognised; nothing in script/ opens two.
-func heredocTerminator(line string) string {
-	_, after, opens := strings.Cut(line, "<<")
-	if !opens {
-		return ""
-	}
-
-	// `<<-` strips leading tabs from the body; the terminator word is
-	// the same either way, and callers compare against trimmed lines.
-	word, _, _ := strings.Cut(strings.TrimPrefix(after, "-"), " ")
-
-	return strings.Trim(word, `'"`)
-}
-
 // readRepoFile reads a file by its path relative to the repository
 // root.
 func readRepoFile(t *testing.T, name string) string {

script/lint

@@ -19,9 +19,8 @@
 #
 #   BUILDKIT_PROGRESS=plain script/lint
 #
-# The check layers -- `golangci-lint config verify` and then
-# `golangci-lint run` -- must appear as executing rather than CACHED on
-# every run; see the CHECK_EPOCH comment in Dockerfile.lint.
+# The lint layer must appear as executing rather than CACHED on every
+# run; see the CHECK_EPOCH comment in Dockerfile.lint.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
@@ -74,7 +73,7 @@ main() {
     cd "$ROOT"
     require_docker
 
-    # A fresh epoch per invocation is what forces the check layers to
+    # A fresh epoch per invocation is what forces the lint layer to
     # execute; the layers above the ARG in Dockerfile.lint still cache,
     # so a run is not cold. The value must be unique per invocation, not
     # per second: `date +%s` is second-granular, so two concurrent