Format Markdown with prettier in make fmt and make fmt-check (closes #19)

script/fmt and script/fmt-check run prettier over every Markdown file
again, next to gofmt. prettier is pinned by hash through package.json
and yarn.lock, copied from the prompts repo with .prettierrc and
.prettierignore, and is never installed on a host: a new prettier stage
of the Dockerfile installs it into a digest-pinned node image, and both
scripts build that stage and run it with the repository mounted. CI
checks the Markdown in a markdown stage that the build stage waits on.
Because make fmt-check now runs docker, the Dockerfile runs gofmt
directly in its lint stage instead. All Markdown is reformatted.

Model: opus-5-5

script/bootstrap

@@ -3,10 +3,12 @@
 # this repo. Idempotent: every install is guarded by a check so already
 # installed tools are skipped. Base tooling comes from nix, apt, brew,
 # or apk (detected in that order); assumes nothing is present (not git,
-# make, or go). The linter is NOT installed: golangci-lint runs via
-# docker only (script/lint), pinned by image digest, so the only lint
+# make, or go). Neither the linter nor the Markdown formatter is
+# installed: golangci-lint (script/lint) and prettier (script/fmt,
+# script/fmt-check) run via docker only, pinned by hash, so their only
 # prerequisite is a working docker — which is warned about, not
-# installed, because everything except linting works without it.
+# installed, because everything except linting and formatting works
+# without it.
 set -eu
 
 ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
@@ -71,15 +73,15 @@ main() {
     if missing make; then pkg_install gnumake make make make; fi
     if missing go; then pkg_install go golang go go; fi
 
-    # Linting runs via docker only (script/lint), so docker is a lint
-    # prerequisite rather than something bootstrap installs. Warn, do
-    # not fail: everything except `make lint` — and, through it,
-    # `make check`, `make docker` and the pre-commit hook — works
-    # without it.
+    # Linting and Markdown formatting run via docker only, so docker is
+    # their prerequisite rather than something bootstrap installs. Warn,
+    # do not fail: everything except `make lint`, `make fmt` and
+    # `make fmt-check` — and, through them, `make check`, `make docker`
+    # and the pre-commit hook — works without it.
     if missing docker; then
-        echo "bootstrap: WARNING: docker not found; make lint, make check" >&2
-        echo "bootstrap: and make docker require it. Install docker to" >&2
-        echo "bootstrap: run the linter." >&2
+        echo "bootstrap: WARNING: docker not found; make lint, make fmt," >&2
+        echo "bootstrap: make fmt-check, make check and make docker" >&2
+        echo "bootstrap: require it." >&2
     fi
 
     go mod download

script/cibuild

@@ -3,17 +3,17 @@
 # push.
 #
 # The Dockerfile runs the gates individually as build steps, not the
-# make check aggregate: the lint stage runs make fmt-check,
+# make check aggregate: the lint stage runs the gofmt check,
 # script/verify-lint-image-pin, golangci-lint config verify and
-# golangci-lint run; the build stage, dropped to an unprivileged user,
-# runs make test and make fmt-check. Neither make lint nor make check
-# appears, because both reach script/lint, which is itself a docker
-# build, and a docker build cannot run inside one. Lint is not skipped
-# by that — the linter is invoked directly in the lint stage, and the
-# build stage's COPY --from=lint makes that stage a prerequisite, so
-# BuildKit must finish it first. Between the two stages everything
-# make check would run has run, which is why a successful build here
-# implies the repo is green.
+# golangci-lint run; the markdown stage runs the prettier check; the
+# build stage, dropped to an unprivileged user, runs make test. None of
+# make lint, make fmt-check or make check appears, because each runs
+# docker, and docker cannot run inside a docker build. Nothing is
+# skipped by that — the linter, gofmt and prettier are invoked directly
+# in their stages, and the build stage's COPY --from lines make those
+# stages prerequisites, so BuildKit must finish them first. Between the
+# three stages everything make check would run has run, which is why a
+# successful build here implies the repo is green.
 #
 # That implication holds only because of CHECK_EPOCH. A COPY layer is
 # invalidated only by changed content, and a rebuild of an unchanged

script/docker

@@ -4,11 +4,11 @@
 #
 # CHECK_EPOCH is passed for the same reason script/cibuild passes it:
 # without it Docker serves the Dockerfile's gate layers from cache on an
-# unchanged tree and this exits 0 having run neither the lint stage's
-# gates nor the builder stage's test and fmt-check gates. This is the
-# set of gates a developer or reviewer runs by hand, so a cached pass
-# here is the most misleading result the repo can produce. Dependency
-# layers sit above the ARG and stay cached.
+# unchanged tree and this exits 0 having run none of the lint stage's
+# gates, the markdown stage's prettier gate or the builder stage's test
+# gate. This is the set of gates a developer or reviewer runs by hand,
+# so a cached pass here is the most misleading result the repo can
+# produce. Dependency layers sit above the ARG and stay cached.
 set -eu
 
 SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"

script/fmt

@@ -1,12 +1,22 @@
 #!/bin/sh
-# script/fmt: format all files (writes).
+# script/fmt: format all files (writes): the Go sources with gofmt, the
+# Markdown with prettier. prettier is never installed on the host: it
+# runs from the Dockerfile's prettier stage with the repository mounted,
+# as the calling user so the files it rewrites keep their owner. The tag
+# makes each build replace the previous image instead of leaving another
+# one behind.
 set -eu
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
     gofmt -s -w .
+    image="$("$SCRIPT_DIR/projectname")-prettier"
+    docker build -q --target prettier -t "$image" . >/dev/null
+    docker run --rm --user "$(id -u):$(id -g)" -v "$ROOT:/src" "$image" \
+        prettier --write '**/*.md' --tab-width 4 --prose-wrap always
 }
 
 main "$@"

script/fmt-check

@@ -1,18 +1,39 @@
 #!/bin/sh
 # script/fmt-check: check formatting (read-only). Same scope as
-# script/fmt, but fails instead of writing.
+# script/fmt, but fails instead of writing. gofmt and prettier both run
+# every time and each reports its own failure, so the output says which
+# one failed.
 set -eu
 
-ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
 
 main() {
     cd "$ROOT"
-    files="$(gofmt -s -l .)"
+    status=0
+
+    # Under set -e a bare assignment would end the script when gofmt
+    # fails (a Go file it cannot parse), and prettier would never run.
+    if ! files="$(gofmt -s -l .)"; then
+        echo "gofmt: failed; see its errors above" >&2
+        status=1
+    fi
     if [ -n "$files" ]; then
         echo "gofmt: files not formatted:" >&2
         echo "$files" >&2
-        exit 1
+        status=1
     fi
+
+    # Same image as script/fmt; see there.
+    image="$("$SCRIPT_DIR/projectname")-prettier"
+    docker build -q --target prettier -t "$image" . >/dev/null
+    if ! docker run --rm -v "$ROOT:/src:ro" "$image" \
+        prettier --check '**/*.md' --tab-width 4 --prose-wrap always; then
+        echo "prettier: Markdown not formatted; run make fmt" >&2
+        status=1
+    fi
+
+    exit "$status"
 }
 
 main "$@"