Adopt scripts-to-rule-them-all: script/ entrypoints, Makefile shims

2026-07-07 00:21:27 +02:00
parent 4463c56490
commit f8fcdcd9ce
16 changed files with 294 additions and 30 deletions
--- a/.gitea/workflows/check.yml
+++ b/.gitea/workflows/check.yml
@@ -6,4 +6,4 @@ jobs:
        steps:
            # actions/checkout v4.2.2, 2026-02-28
            - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
-            - run: docker build .
+            - run: script/cibuild
--- a/52
+++ b/52
@@ -1,48 +1,44 @@
-.PHONY: all build lint fmt fmt-check test check clean hooks docker
+.PHONY: all bootstrap setup build lint fmt fmt-check test check clean hooks docker

 BINARY := dnswatcher
 VERSION := $(shell git describe --tags --always --dirty 2>/dev/null || echo "dev")
 LDFLAGS := -X main.Version=$(VERSION)

+# Standard targets are thin shims; the implementations live in script/
+# per the scripts-to-rule-them-all pattern (see the Entrypoints section
+# of README.md).
+
 all: check build

+bootstrap:
+	@script/bootstrap
+
+setup:
+	@script/setup
+
 build:
 	go build -ldflags "$(LDFLAGS)" -o bin/$(BINARY) ./cmd/dnswatcher

+test:
+	@script/test
+
 lint:
-	golangci-lint run --config .golangci.yml ./...
+	@script/lint

 fmt:
-	gofmt -s -w .
-	goimports -w .
+	@script/fmt

 fmt-check:
-	@test -z "$$(gofmt -l .)" || (echo "gofmt: files not formatted:" && gofmt -l . && exit 1)
+	@script/fmt-check

-test:
-	go test -v -race -timeout 30s -cover ./...
-
-# Check runs all validation without making changes
-# Used by CI and Docker build - fails if anything is wrong
 check:
-	@echo "==> Checking formatting..."
-	@test -z "$$(gofmt -l .)" || (echo "Files not formatted:" && gofmt -l . && exit 1)
-	@echo "==> Running linter..."
-	golangci-lint run --config .golangci.yml ./...
-	@echo "==> Running tests..."
-	go test -v -race -timeout 30s ./...
-	@echo "==> Building..."
-	go build -ldflags "$(LDFLAGS)" -o /dev/null ./cmd/dnswatcher
-	@echo "==> All checks passed!"
+	@script/check
+
+docker:
+	@script/docker
+
+hooks:
+	@script/install-precommit

 clean:
 	rm -rf bin/
-
-hooks:
-	@echo '#!/bin/sh' > .git/hooks/pre-commit
-	@echo 'make check' >> .git/hooks/pre-commit
-	@chmod +x .git/hooks/pre-commit
-	@echo "Pre-commit hook installed."
-
-docker:
-	docker build .
--- a/README.md
+++ b/README.md
@@ -352,6 +352,32 @@ tracks reachability:

 ---

+## Entrypoints
+
+This repository adheres to the
+[Scripts to Rule Them All](https://github.com/github/scripts-to-rule-them-all)
+standard: normalized scripts in `script/` are the entrypoints for the
+development workflow, and the Makefile targets are thin shims that call
+them. We provide:
+
+- `script/bootstrap` — install all dependencies (go, pinned
+  golangci-lint and goimports, `go mod download`)
+- `script/setup` — make a fresh clone ready for development: bootstrap
+  plus the git pre-commit hook
+- `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/fmt` — format all code (gofmt -s, goimports)
+- `script/fmt-check` — check formatting (read-only)
+- `script/check` — run test, lint, and fmt-check
+- `script/docker` — build the Docker image tagged via
+  `script/projectname`
+- `script/cibuild` — CI entrypoint: plain `docker build .`
+- `script/precommit` — run by the git pre-commit hook; `go mod tidy`
+  guard, then `script/check`
+- `script/install-precommit` — install the git pre-commit hook
+
 ## Building

 ```sh
@@ -359,7 +385,7 @@ make build      # Build binary to bin/dnswatcher
 make test       # Run tests with race detector
 make lint       # Run golangci-lint
 make fmt        # Format code
-make check      # Run all checks (format, lint, test, build)
+make check      # Run all checks (test, lint, fmt-check)
 make clean      # Remove build artifacts
 ```

--- a/TODO.md
+++ b/TODO.md
@@ -25,6 +25,8 @@ confirm make check still passes.

 # Completed Steps

+- 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
  with mocked DNS (origin/feature/resolver, unmerged)
 - 2026-02-20: CI actions and go install refs pinned to commit SHAs;
--- a/script/bootstrap
+++ b/script/bootstrap
@@ -0,0 +1,82 @@
+#!/bin/sh
+# script/bootstrap: install all dependencies needed to build and develop
+# 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.
+# golangci-lint and goimports are installed via `go install` at the same
+# pinned commits the Dockerfile uses (never "latest").
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+# Pinned versions, 2026-07-07 (same pins as the Dockerfile)
+# golangci-lint v2.10.1
+GOLANGCI_LINT_REF="github.com/golangci/golangci-lint/v2/cmd/golangci-lint@5d1e709b7be35cb2025444e19de266b056b7b7ee"
+# goimports v0.42.0
+GOIMPORTS_REF="golang.org/x/tools/cmd/goimports@009367f5c17a8d4c45a961a3a509277190a9a6f0"
+
+PKGMGR=""
+SUDO=""
+APT_UPDATED=""
+
+detect_pkgmgr() {
+    [ -n "$PKGMGR" ] && return 0
+    if command -v nix-env >/dev/null 2>&1; then
+        PKGMGR="nix"
+    elif command -v apt-get >/dev/null 2>&1; then
+        PKGMGR="apt"
+    elif command -v brew >/dev/null 2>&1; then
+        PKGMGR="brew"
+    elif command -v apk >/dev/null 2>&1; then
+        PKGMGR="apk"
+    else
+        echo "bootstrap: no supported package manager (nix, apt, brew, apk)" >&2
+        exit 1
+    fi
+    if [ "$PKGMGR" = "apt" ]; then
+        export DEBIAN_FRONTEND=noninteractive
+        if [ "$(id -u)" != "0" ]; then
+            SUDO="sudo"
+        fi
+    fi
+}
+
+# pkg_install <nix-attr> <apt-pkg> <brew-formula> <apk-pkg>
+pkg_install() {
+    detect_pkgmgr
+    case "$PKGMGR" in
+        nix) nix-env -iA "nixpkgs.$1" ;;
+        apt)
+            if [ -z "$APT_UPDATED" ]; then
+                $SUDO env DEBIAN_FRONTEND=noninteractive apt-get update
+                APT_UPDATED=1
+            fi
+            $SUDO env DEBIAN_FRONTEND=noninteractive apt-get install -y "$2"
+            ;;
+        brew) brew install "$3" ;;
+        apk) apk add --no-cache "$4" ;;
+    esac
+}
+
+missing() {
+    ! command -v "$1" >/dev/null 2>&1
+}
+
+main() {
+    cd "$ROOT"
+
+    if missing git; then pkg_install git git git git; fi
+    if missing make; then pkg_install gnumake make make make; fi
+    if missing go; then pkg_install go golang go go; fi
+
+    # Lint/format tools, pinned via go install (installs into
+    # "$(go env GOPATH)/bin"; ensure that is on your PATH).
+    if missing golangci-lint; then go install "$GOLANGCI_LINT_REF"; fi
+    if missing goimports; then go install "$GOIMPORTS_REF"; fi
+
+    go mod download
+
+    echo "bootstrap complete"
+}
+
+main "$@"
--- a/script/check
+++ b/script/check
@@ -0,0 +1,14 @@
+#!/bin/sh
+# script/check: run all checks (test, lint, fmt-check). Our own
+# extension to scripts-to-rule-them-all. Must not modify any files.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+
+main() {
+    "$SCRIPT_DIR/test"
+    "$SCRIPT_DIR/lint"
+    "$SCRIPT_DIR/fmt-check"
+}
+
+main "$@"
--- a/script/cibuild
+++ b/script/cibuild
@@ -0,0 +1,13 @@
+#!/bin/sh
+# script/cibuild: run the CI build. The Dockerfile runs make check, so
+# a successful build implies all checks pass.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    docker build .
+}
+
+main "$@"
--- a/script/docker
+++ b/script/docker
@@ -0,0 +1,14 @@
+#!/bin/sh
+# script/docker: build the Docker image tagged with the project name.
+# Identical in all repos; the tag comes from script/projectname.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    docker build -t "$("$SCRIPT_DIR/projectname")" .
+}
+
+main "$@"
--- a/script/fmt
+++ b/script/fmt
@@ -0,0 +1,13 @@
+#!/bin/sh
+# script/fmt: format all files (writes).
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    gofmt -s -w .
+    goimports -w .
+}
+
+main "$@"
--- a/script/fmt-check
+++ b/script/fmt-check
@@ -0,0 +1,18 @@
+#!/bin/sh
+# script/fmt-check: check formatting (read-only). Same scope as
+# script/fmt, but fails instead of writing.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    files="$(gofmt -l .)"
+    if [ -n "$files" ]; then
+        echo "gofmt: files not formatted:" >&2
+        echo "$files" >&2
+        exit 1
+    fi
+}
+
+main "$@"
--- a/script/install-precommit
+++ b/script/install-precommit
@@ -0,0 +1,16 @@
+#!/bin/sh
+# script/install-precommit: install the git pre-commit hook that runs
+# script/precommit. Our own extension to scripts-to-rule-them-all.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    hook=".git/hooks/pre-commit"
+    printf '#!/bin/sh\nset -e\nscript/precommit\n' > "$hook"
+    chmod +x "$hook"
+    echo "pre-commit hook installed: runs script/precommit"
+}
+
+main "$@"
--- a/script/lint
+++ b/script/lint
@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/lint: run the linter.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    golangci-lint run --config .golangci.yml ./...
+}
+
+main "$@"
--- a/script/precommit
+++ b/script/precommit
@@ -0,0 +1,21 @@
+#!/bin/sh
+# script/precommit: run by the git pre-commit hook; fails the commit if
+# checks fail. Our own extension to scripts-to-rule-them-all. Go extra:
+# go mod tidy must be a no-op before the checks run.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+ROOT="$(cd "$SCRIPT_DIR/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    go mod tidy
+    if ! git diff --exit-code -- go.mod go.sum; then
+        echo "precommit: go mod tidy changed go.mod/go.sum;" \
+            "stage the changes and retry" >&2
+        exit 1
+    fi
+    "$SCRIPT_DIR/check"
+}
+
+main "$@"
--- a/script/projectname
+++ b/script/projectname
@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/projectname: output the name of this project. Our own
+# extension to scripts-to-rule-them-all. Other scripts that need the
+# name (e.g. script/docker) call this, so they can stay identical
+# across all repos.
+set -eu
+
+main() {
+    echo "dnswatcher"
+}
+
+main "$@"
--- a/script/setup
+++ b/script/setup
@@ -0,0 +1,13 @@
+#!/bin/sh
+# script/setup: set up the repo for development after a fresh clone:
+# installs dependencies and the git pre-commit hook.
+set -eu
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd -P)"
+
+main() {
+    "$SCRIPT_DIR/bootstrap"
+    "$SCRIPT_DIR/install-precommit"
+}
+
+main "$@"
--- a/script/test
+++ b/script/test
@@ -0,0 +1,12 @@
+#!/bin/sh
+# script/test: run the test suite.
+set -eu
+
+ROOT="$(cd "$(dirname "$0")/.." && pwd -P)"
+
+main() {
+    cd "$ROOT"
+    go test -v -race -timeout 30s -cover ./...
+}
+
+main "$@"