build: add a make cover target for per-function coverage (closes #17)

make cover writes build/coverage.out and prints the per-function report;
make cover-html renders the same profile to build/coverage.html. The
per-package percentage make test prints cannot say which function is
untested.

Both write files, so neither is in check, and neither may be added to it:
check must not modify the working tree. Their output lands under the
already-ignored build/.

Verified: make cover printed per-function lines and a 62.6% total,
make cover-html wrote build/coverage.html, and git status stayed clean.
GOFLAGS=-count=1 make check green in 24s with the lint layer executing
(12.0s, "0 issues.", not CACHED) and the suite running for real (cmd/rogue
1.037s, game 3.410s); check is still fmt-check lint test and git status is
clean afterwards.

.dockerignore

@@ -0,0 +1,8 @@
+# Part of the lint gate: only what reaches the container is linted, so
+# excluding a self-contained Go source here drops it from the lint silently.
+# Never exclude Go sources, go.mod/go.sum or .golangci.yml.
+.git
+
+# Generated artifacts only; `make build` puts a multi-megabyte binary here
+# and it would otherwise be shipped into the build context.
+/build/

.gitignore

@@ -1,4 +1,5 @@
 *.log
 *.out
 *.test
+/build/
 /rogue

Dockerfile.lint

@@ -0,0 +1,20 @@
+# Lint image, built by script/lint: golangci-lint runs as a build step, so
+# a successful build is a clean lint.
+
+# golangci/golangci-lint:v2.12.2 (Debian-based), 2026-08-07
+FROM golangci/golangci-lint:v2.12.2@sha256:5cceeef04e53efe1470638d4b4b4f5ceefd574955ab3941b2d9a68a8c9ad5240 AS deps
+
+WORKDIR /src
+
+COPY go.mod go.sum ./
+RUN go mod download
+
+# This stage must stay the one that runs golangci-lint, and its name must
+# match $stage in script/lint. --target halts the build at this stage, so
+# moving the lint step to another stage, or adding a stage after this one,
+# is not caught.
+FROM deps AS lint
+
+COPY . .
+
+RUN golangci-lint run --config .golangci.yml ./...

Makefile

@@ -1,18 +1,47 @@
 # Development convenience targets. This repo is exempt from the standard
-# policy scaffold (no Dockerfile, CI, or REPO_POLICIES.md); this Makefile
+# policy scaffold (no CI config, no REPO_POLICIES.md, no application
-# is only a thin wrapper around the Go toolchain, golangci-lint, and
+# Dockerfile) except for the lint container: per sneak's 2026-08-09
-# prettier so `make fmt` / `make check` behave the same as in sneak's
+# ruling, linting runs in docker only, so Dockerfile.lint and script/lint
-# other repos.
+# are part of this repo. This Makefile is otherwise only a thin wrapper
+# around the Go toolchain and prettier so `make fmt` / `make check` behave
+# the same as in sneak's other repos.
 
-GO_PKGS  := ./...
+GO_PKGS   := ./...
-MD_FILES := $(shell git ls-files '*.md')
+MD_FILES  := $(shell git ls-files '*.md')
-PRETTIER := prettier --tab-width 4 --prose-wrap always
+PRETTIER  := prettier --tab-width 4 --prose-wrap always
 
-.PHONY: check fmt fmt-check lint test
+# Every generated artifact goes here, and the whole directory is
+# git-ignored. Targets that write outside it can commit their output.
+BUILD_DIR := build
+BIN       := $(BUILD_DIR)/rogue
+COVERPROF := $(BUILD_DIR)/coverage.out
+COVERHTML := $(BUILD_DIR)/coverage.html
 
-# Format, lint, and test — the full local pre-commit gate.
+.PHONY: build check cover cover-html fmt fmt-check lint test
+
+# Format, lint, and test — the full local pre-commit gate. Keep this list
+# to targets that write nothing into the working tree.
 check: fmt-check lint test
 
+# Build the executable into $(BUILD_DIR). `go build -o` does not create the
+# parent directory.
+build:
+	@mkdir -p $(BUILD_DIR)
+	go build -o $(BIN) ./cmd/rogue
+
+# Per-function coverage, for finding which functions are untested. The
+# percentage `make test` prints is a per-package total and cannot answer
+# that. Writes files, so it stays out of `check`.
+cover:
+	@mkdir -p $(BUILD_DIR)
+	go test -timeout 30s -coverprofile=$(COVERPROF) $(GO_PKGS)
+	go tool cover -func=$(COVERPROF)
+
+# Render the same profile as annotated source.
+cover-html: cover
+	go tool cover -html=$(COVERPROF) -o $(COVERHTML)
+	@echo "wrote $(COVERHTML)"
+
 # Format Go and Markdown in place.
 fmt:
 	gofmt -w .
@@ -26,9 +55,11 @@ fmt-check:
 	fi
 	$(PRETTIER) --check $(MD_FILES)
 
-# Run the house linter (config in .golangci.yml).
+# Run the house linter. golangci-lint is never installed on the host: the
+# work happens inside the pinned container built by Dockerfile.lint, and
+# this target is a thin shim over the script that builds it.
 lint:
-	golangci-lint run $(GO_PKGS)
+	./script/lint
 
 # Run the test suite. Quiet on success; on failure, rerun verbosely for the
 # full output and still fail the target (the first run already proved the

README.md

@@ -21,19 +21,19 @@ original program structure and the design of this port.
 Requires Go 1.25 or later and a terminal at least 80x24.
 
 ```bash
-go build ./cmd/rogue
+make build
-./rogue
+./build/rogue
 ```
 
 ```bash
 # Restore a saved game
-./rogue ~/rogue.save
+./build/rogue ~/rogue.save
 
 # View high scores
-./rogue -s
+./build/rogue -s
 
 # Test the death screen (demo mode)
-./rogue -d
+./build/rogue -d
 ```
 
 ## In-game commands
@@ -57,7 +57,7 @@ Press `?` in game for the full list.
 export ROGUEOPTS="name=YourName,terse,jump,fruit=mango"
 
 # Wizard (debug) mode, with a reproducible dungeon
-ROGUE_WIZARD=1 SEED=12345 ./rogue
+ROGUE_WIZARD=1 SEED=12345 ./build/rogue
 ```
 
 The scoreboard is kept in `~/.rogue.scores`. Save files are Go gob snapshots
@@ -77,10 +77,14 @@ sequences, dungeon-generation golden checks, and an RNG compatibility test
 against the original C generator.
 
 For development, the `Makefile` wraps the toolchain: `make fmt` (gofmt +
-prettier), `make lint` (golangci-lint), `make test` (the suite, under the race
+prettier), `make lint` (`script/lint`, which runs golangci-lint inside the
-detector with coverage and a timeout), and `make check` (all three). Use the
+pinned container built from `Dockerfile.lint` — it is never installed on the
-targets rather than invoking `go test` directly — they carry the flags the
+host, so docker is required), `make test` (the suite, under the race detector
-project relies on.
+with coverage and a timeout), `make check` (all three), `make build` (the
+executable), and `make cover` / `make cover-html` (per-function coverage, and
+the same profile as annotated source at `build/coverage.html`). Everything they
+generate lands in the git-ignored `build/`. Use the targets rather than the
+toolchain directly — they carry the flags the project relies on.
 
 ## License
 

TODO.md

@@ -35,6 +35,55 @@ is finished.
 
 # Completed Steps
 
+- 2026-08-10 `make cover` added (https://git.eeqj.de/sneak/rgoue/issues/17).
+  `make cover` writes `build/coverage.out` and prints the per-function report;
+  `make cover-html` renders the same profile to `build/coverage.html`. The
+  per-package percentage `make test` prints cannot say _which_ function is
+  untested, which is how the coverage gaps closed so far had to be found — by
+  grepping test files for identifiers.
+
+    Neither target is in `check`, and neither may be added to it: both write
+    files, and `make check` must not modify the working tree.
+
+- 2026-08-10 `make build` added (https://git.eeqj.de/sneak/rgoue/issues/19). The
+  executable is built to `build/rogue`; `README.md` no longer contains a raw
+  `go` invocation anywhere. `build` is in neither `check` nor `test` —
+  `make check` stays `fmt-check lint test` and still writes nothing into the
+  working tree.
+
+    Generated artifacts now all live under `build/`, which `.gitignore` covers
+    as a whole. Anything written outside it is committable, so a target that
+    puts its output elsewhere reintroduces the stray-artifact problem.
+
+- 2026-08-10 Linting moved into a container
+  (https://git.eeqj.de/sneak/rgoue/issues/41). `golangci-lint` is no longer
+  invoked on the host anywhere in the repo: `Dockerfile.lint` pins
+  `golangci/golangci-lint:v2.12.2` by digest and runs the linter as a build
+  step, so a successful build is a clean lint, and `make lint` is now a shim
+  over `script/lint`. This is what killed the false green seen earlier, where a
+  branch that was genuinely red with a `goconst` finding reported `0 issues` off
+  the shared host cache; a container per run has its own cache and lock.
+
+    `script/lint` builds with `--target "$stage"`, `--no-cache-filter="$stage"`
+    and `--output=type=cacheonly`. The durable property to check when touching
+    any of this: the lint stage executes on every run and is never served from
+    cache. Three things no tooling checks, left to whoever edits the gate —
+    `$stage` must match the stage name in `Dockerfile.lint`; that stage must
+    stay the one running `golangci-lint`, since `--target` halts the build
+    there; and `.dockerignore` governs what reaches the container, so excluding
+    a self-contained Go source drops it from the lint silently.
+
+    Verified rather than assumed, since a green docker build is the classic
+    false green: two consecutive runs on an unchanged tree each showed the
+    `golangci-lint run` layer executing and reporting `0 issues.` while the
+    `deps` layers reported `CACHED`; the same build with `--no-cache-filter`
+    removed reported that layer `CACHED`, so the re-execution is attributable to
+    the flag rather than to a changed context; deliberate violations failed the
+    build naming the specific finding and reverted clean; a stage-name typo
+    failed loudly at exit 1; and a Go file excluded via `.dockerignore` reported
+    `0 issues.` at exit 0 with the violation still in the tree. Wall-clock
+    durations vary per host and per run, so they are not recorded here.
+
 - 2026-08-09 `TestAutoSaveOnSignalRacesTurnLoop` de-flaked at the cause
   (`fix/autosave-turn-budget-36`, closes #36). The failure text was captured
   before anything was changed and it is **not** a data race: the assertion was
@@ -705,7 +754,11 @@ is finished.
   24 long lines wrapped or their comments tightened, control bytes in
   `term/tcell.go` as character literals, and two `wsl_v5` defer cuddles. The
   repo has no golangci-lint version pin to bump (no Dockerfile or CI;
-  `make lint` runs whatever `golangci-lint` is on the host).
+  `make lint` runs whatever `golangci-lint` is on the host). Superseded
+  2026-08-10: there is a pin now, and no host lint path — `Dockerfile.lint` pins
+  the linter image by digest and `script/lint` runs it in a container. See the
+  2026-08-10 entry at the top of this section
+  (https://git.eeqj.de/sneak/rgoue/issues/41).
 
 - 2026-07-24 Seed compatibility — item tables (seed-compat): instrumented the C
   reference on modern-rogue with a DUMP mode (testdata/c_seedcompat.patch) that
@@ -853,7 +906,13 @@ is finished.
    per-game dungeon dimensions instead of the 80x24 constants; open design
    questions are resize policy, gameplay tuning at larger sizes, and a --classic
    80x24 mode.
-2. Note: this repo is exempt from the standard policy scaffold. A minimal dev
+2. Note: this repo is exempt from the standard policy scaffold, but the
-   Makefile (fmt/fmt-check/lint/test/check targets) exists per sneak's
+   exemption is narrower than it was. A minimal dev Makefile
-   2026-07-07 request, but do not add a Dockerfile, CI config, or
+   (fmt/fmt-check/lint/test/check targets) exists per sneak's 2026-07-07
-   REPO_POLICIES.md.
+   request. `Dockerfile.lint` and `script/lint` are now also permitted, and
+   required, along with the `.dockerignore` that scopes their build context:
+   sneak's 2026-08-09 ruling (https://git.eeqj.de/sneak/rgoue/issues/41) is that
+   every repo lints in a container invoked through `script/lint`, and being
+   later and explicit it overrides the 2026-07-07 exemption for those three
+   files only. Still do not add: CI config, `REPO_POLICIES.md`, an application
+   `Dockerfile`, or any other `script/` entrypoint.

script/lint

@@ -0,0 +1,37 @@
+#!/bin/sh
+# script/lint: lint in docker. golangci-lint is never installed on the host.
+#
+# Traps, each of which yields a green run over an unlinted or partly linted
+# tree:
+#
+# 1. --target and --no-cache-filter must both stay, and $stage must match
+#    the stage name in Dockerfile.lint. BuildKit ignores --no-cache-filter
+#    when no stage matches its argument, serving the lint layer from cache
+#    without a word; --target rejects a name that is not in the file, which
+#    is what makes the single $stage safe.
+#
+# 2. --target checks that the stage exists, not that it is the stage
+#    running golangci-lint, and it halts the build there. Moving the lint
+#    step to another stage, or adding a stage after it, is not caught.
+#
+# 3. .dockerignore decides what reaches the container, and only what
+#    reaches it is linted. Excluding a self-contained Go file drops it from
+#    the lint silently. Never exclude Go sources, go.mod/go.sum or
+#    .golangci.yml.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+# Must match the stage name in Dockerfile.lint.
+stage=lint
+
+main() {
+    cd "$ROOT"
+    docker build \
+        --target "$stage" \
+        --no-cache-filter="$stage" \
+        --output=type=cacheonly \
+        -f Dockerfile.lint .
+}
+
+main "$@"