fix(build): make formatting and CI converge (#901)

This commit is contained in:
sam authored and GitHub committed 2026-09-20 00:38:51 +10:00
1 parent 301ced4dc0
commit 2935010504
9 files changed
+164 -53

No files matched your search

+15 -23
View File
@@ -35,7 +35,7 @@ task --list
```bash
go version
go env GOTOOLCHAIN GOVERSION GOOS GOARCH CGO_ENABLED GOTMPDIR GOCACHE GOMODCACHE
task --version; gofumpt -version; golangci-lint version
task --version; golangci-lint version; gofumpt -version
node --version; npm --version # UI only; docs need no Node toolchain
docker --version; docker compose version
git --version; gpg --version
@@ -45,32 +45,23 @@ Classify a missing command as an environment prerequisite. Bootstrap (verified
2026-09-19): Go ≥ 1.27.0, Task ≥ 3.x, gofumpt v0.11.0, golangci-lint 2.13.2,
Node 24.x for the `ui/` frontend.
`gofumpt` and `golangci-lint` are one pair, not two independent tools.
`task fmt` formats with the standalone gofumpt; `task lint` re-checks that
formatting with the gofumpt golangci-lint vendors, and `task check` runs
`fmt` then `lint` without diffing the tree, so `lint` is the only hard
failure for formatting. Install the pair from `Dockerfile`
(`GOLANGCI_LINT_VERSION` 2.13.2 -> gofumpt `GOFUMPT_VERSION` 0.11.0) rather
than `@latest` for either: on a construct the two versions disagree on,
`task fmt` cannot converge `task lint`, and the gate is unsatisfiable.
`task fmt` runs `go fix` and then `golangci-lint fmt`; `task lint` uses the
same binary and `.golangci.yml`, so its gofumpt, goimports, and gci rules have
one owner and the writer converges the checker. Standalone `gofumpt` remains
only for generated protobuf contracts in `tools/proto.sh`.
A rule only one side applies fails the same way, so `task fmt` also passes
`-extra` to match the formatter's `extra-rules`. Both mismatches are
reachable in ordinary code: gofumpt <= v0.9.2 keeps the redundant parens in
`any((Trees)(nil))` that >= v0.10.0 removes, and without `-extra`
`func f(a int, b int)` stays put while `task lint` demands `func f(a, b int)`.
Formatting that only `task lint` can produce is still a real gap -- `gci`'s
`custom-order` places archie-core imports last, where gofumpt sorts them
alphabetically -- so run `golangci-lint fmt` when `task fmt` leaves a
formatting failure standing.
The three Yaegi secret-engine examples carry `//go:build ignore`. goimports
cannot type-check them and deletes a genuinely used `internal/secret` import,
so `.golangci.yml` excludes those exact files from the formatter set. Their
runtime loading remains covered by `internal/secret/engines_test.go`.
| Surface | Repository declaration | Installed snapshot | Interpretation |
|---|---|---|---|
| Runtime Go | `go 1.27.0` in `go.mod` | Go 1.27.0, linux/amd64 | Requires at least declared Go level. |
| Tools Go | `go 1.27.0` in `tools/go.mod` | Same Go 1.27.0 binary | Toolchain must satisfy both modules. |
| Task | Taskfile schema `version: "3"` | Task 3.48.0 | Installed version is environment fact. |
| gofumpt | `task fmt`; pinned in `Dockerfile` (`GOFUMPT_VERSION`) | v0.11.0 | Must equal the gofumpt golangci-lint vendors. |
| golangci-lint | v2 config in `.golangci.yml`; pinned in `Dockerfile` | 2.13.2 | Vendors gofumpt v0.11.0; `golangci-lint run` enables the formatters. |
| gofumpt | Generated protobuf formatting; pinned in `Dockerfile` | v0.11.0 | Not the ordinary source formatter. |
| golangci-lint | v2 config in `.golangci.yml`; pinned in `Dockerfile` | 2.13.2 | Owns ordinary formatting and lint checks. |
| Node | `ui/` frontend build | 26.9.0 / npm 11.19.1 | No `engines`/`packageManager` field. Docs need no Node. |
| Containers | Compose commands in `Taskfile.yml` | Podman-backed, unusable in this sandbox | Verify CLI, Compose plugin, daemon/socket separately. |
@@ -123,19 +114,20 @@ golangci-lint run ./...
| Task | Exact effect |
|---|---|
| `task fmt` | `gofumpt -extra -w .`, then `go fix ./...` — both may rewrite source. |
| `task fmt` | `go fix ./...`, then `golangci-lint fmt` — both may rewrite source. |
| `task vet` | `go vet ./...` in the runtime module. |
| `task lint` | `golangci-lint run ./...`. |
| `task build` | Builds both commands into `bin/`. |
| `task test` | `go test ./... -count=1` in the runtime module. |
| `task check` | `fmt` + `go fix ./...` again + `proto:lint` + `proto:check` + `docs:check` + `vet` + `lint` + `build` + `test` + `test:tools` + `test:ui`. |
| `task check` | `fmt` + `proto:lint` + `proto:check` + `docs:check` + `vet` + `lint` + `build` + `test` + `test:tools` + `test:ui`. |
| `task clean` | Recursively removes `bin/`; destructive. |
| `task docker-build` | `docker compose build agent` only. |
`task check` is the definitive gate but omits race tests, `task vuln`, and
`task docker-build`. Its docs step, `docs:check`, verifies committed generated
data and never renders anything: there is still no documentation build.
Run only in authorized writable worktree. For read-only preview: `gofumpt -l .`.
Run only in an authorized writable worktree. For a read-only ordinary-source
preview, use `golangci-lint fmt --diff`.
## Verify the tools module separately
+7 -7
View File
@@ -64,12 +64,10 @@ jobs:
with:
node-version: "22"
# Pinned, not @latest: this gate rewrites formatting with the standalone
# gofumpt, and the agent image that gates PRs re-checks it with the
# gofumpt bundled in its golangci-lint. Those two versions must agree
# (see Dockerfile), or a PR passes here and fails there unfixably.
- name: Install gofumpt
run: go install mvdan.cc/gofumpt@v0.11.0
- name: Install quality tools
run: |
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.13.2
go install mvdan.cc/gofumpt@v0.11.0
- name: Install protobuf tools
run: bash tools/proto.sh install
@@ -85,11 +83,13 @@ jobs:
- name: Quality gate
run: |
gofumpt -w .
go fix ./...
golangci-lint fmt
git diff --exit-code
bash tools/proto.sh lint
bash tools/proto.sh check
go vet ./...
golangci-lint run ./...
go build ./...
go test ./... -count=1
+51
View File
@@ -0,0 +1,51 @@
name: Quality
on:
pull_request:
push:
branches: [main]
permissions:
contents: read
concurrency:
group: quality-${{ github.ref }}
cancel-in-progress: true
jobs:
check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-go@v5
with:
go-version-file: go.mod
- uses: actions/setup-node@v4
with:
node-version: "24"
cache: npm
cache-dependency-path: ui/package-lock.json
- name: Install quality tools
run: |
go install github.com/go-task/task/v3/cmd/task@v3.48.0
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.13.2
go install mvdan.cc/gofumpt@v0.11.0
bash tools/proto.sh install
sudo apt-get update
sudo apt-get install -y --no-install-recommends ripgrep
- name: Ensure contract baseline ref
run: |
if ! git show-ref --verify --quiet refs/heads/main; then
git branch main origin/main
fi
- name: Run definitive gate
run: |
task check
git diff --exit-code
+7 -1
View File
@@ -120,7 +120,8 @@ formatters:
- gci
settings:
gofumpt:
extra-rules: true
extra:
group-params: true
gci:
# Matches the grouping already used across this repo.
sections:
@@ -130,6 +131,11 @@ formatters:
custom-order: true
exclusions:
generated: strict
# These are Yaegi programs shipped as examples. goimports cannot type-check
# files excluded by //go:build ignore and deletes their genuinely used
# internal/secret import, leaving the interpreter unable to load them.
paths:
- ^examples/secret-engines/(age|sops|vault)\.go$
issues:
# 0 = report everything. The defaults (50 per linter, 3 per message)
+7 -8
View File
@@ -85,20 +85,19 @@ automatically and note it in the handoff.
Commands are defined in `Taskfile.yml` (requires Go 1.27.0,
[Task](https://taskfile.dev), `gofumpt`, `golangci-lint`, and Node/npm).
Install `gofumpt` and `golangci-lint` as the pinned pair from `Dockerfile`,
never `@latest` for either: `task fmt` formats with the standalone gofumpt
while `task lint` re-checks it with the gofumpt golangci-lint vendors, so a
version mismatch makes `task check` unsatisfiable.
Install the versions pinned in `Dockerfile`, never `@latest`. `golangci-lint`
is the single writer for ordinary Go formatting; standalone `gofumpt` formats
generated protobuf contracts only.
```bash
task build # build archied and archie-agent binaries into bin/
task test # go test ./... -count=1
task test:ui # dashboard node tests (DOM-building primitives)
task ui # build dashboard into ui/dist (LAW asset)
task fmt # gofumpt -w . && go fix ./...
task fmt # go fix ./... && golangci-lint fmt
task vet # go vet ./...
task lint # golangci-lint run ./...
task check # fmt + go fix + proto:lint + proto:check + docs:check + vet + lint + build + test + test:tools + test:ui (The Definitive Gate)
task check # fmt + proto:lint + proto:check + docs:check + vet + lint + build + test + test:tools + test:ui (The Definitive Gate)
task dev # archied live-reload + Vite HMR together on :5173
```
@@ -265,8 +264,8 @@ structures found in legacy packages.
tests.
3. **Quality Gate:** Run `task check`.
4. **Formatting is LAW:** Adopt all formatting and simplification changes from
`task fmt` (`gofumpt` + `go fix`) verbatim. Never revert or fight canonical
linter/formatter diffs.
`task fmt` (`go fix` + the configured golangci-lint formatters) verbatim.
Never revert or fight canonical linter/formatter diffs.
5. **No standing adversarial-review pass (for contributors):** Do not spawn a
separate fresh-context reviewer pass on every change as a matter of course.
Red-green TDD plus `task check` is the gate; a manual adversarial pass is
+2 -6
View File
@@ -62,12 +62,8 @@ ENV PATH="/usr/local/go/bin:/go/bin:${PATH}"
# module and build cache into the image. delve is omitted because it ships no
# prebuilt binary; `go install ...@latest` at runtime if an agent needs it.
#
# `task fmt` formats with this gofumpt and `task lint` then re-checks
# formatting with the gofumpt golangci-lint vendors. Any construct the two
# versions disagree on makes the gate unsatisfiable -- `task fmt` cannot
# converge a check run by a different formatter. So GOFUMPT_VERSION must equal
# the mvdan.cc/gofumpt version in golangci-lint v${GOLANGCI_LINT_VERSION}'s
# go.mod (2.13.2 -> v0.11.0). Bump the two together, never separately.
# golangci-lint owns ordinary source formatting and lint checks. Standalone
# gofumpt is retained for generated protobuf contracts in tools/proto.sh.
ARG GOLANGCI_LINT_VERSION=2.13.2
ARG GOFUMPT_VERSION=0.11.0
ARG BUF_VERSION=1.72.0
+6 -8
View File
@@ -10,14 +10,13 @@ tasks:
- task --list
fmt:
desc: Format and fix Go source (gofumpt, go fix)
desc: Fix and format Go source with the gate's configured formatters
cmds:
# -extra must match the gofumpt formatter's extra-rules in
# .golangci.yml. Without it `task fmt` cannot produce what `task lint`
# demands -- e.g. func f(a int, b int) -> func f(a, b int) -- so a
# contributor has no command that satisfies the gate.
- gofumpt -extra -w .
- go fix ./...
# This must use the same engine and configuration as task lint. Running
# standalone gofumpt cannot reproduce goimports or gci's custom import
# grouping, so it can leave a tree that the gate rejects.
- golangci-lint fmt
proto:install:
desc: Install the pinned Buf and protobuf Go generators
@@ -355,10 +354,9 @@ tasks:
- go -C tools test -mod=readonly ./... -count=1
check:
desc: "Full quality gate: fmt, go fix, proto, docs, vet, lint, build, test, tools tests, ui tests and bundle"
desc: "Full quality gate: fmt, proto, docs, vet, lint, build, test, tools tests, ui tests and bundle"
cmds:
- task: fmt
- go fix ./...
- task: proto:lint
- task: proto:check
- task: docs:check
+40
View File
@@ -40,3 +40,43 @@ func TestDeployWorkflowOnlyPublishesRuntimeImageForRuntimeTag(t *testing.T) {
t.Fatal("archied build step is unexpectedly conditional")
}
}
func TestDeployWorkflowUsesConfiguredFormatters(t *testing.T) {
source := readDeploymentFile(t, ".github/workflows/deploy.yml")
for _, required := range []string{
"github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.13.2",
"golangci-lint fmt",
"git diff --exit-code",
"golangci-lint run ./...",
} {
if !strings.Contains(source, required) {
t.Errorf("deploy workflow is missing formatter gate %q", required)
}
}
if strings.Contains(source, "gofumpt -w .") {
t.Error("deploy workflow bypasses the configured formatter set")
}
}
func TestPullRequestsRunTheDefinitiveGateWithoutPublishAccess(t *testing.T) {
source := readDeploymentFile(t, ".github/workflows/quality.yml")
for _, required := range []string{
"pull_request:",
"contents: read",
"task check",
"git diff --exit-code",
} {
if !strings.Contains(source, required) {
t.Errorf("quality workflow is missing %q", required)
}
}
for _, forbidden := range []string{
"packages: write",
"docker/login-action",
"docker/build-push-action",
} {
if strings.Contains(source, forbidden) {
t.Errorf("quality workflow has publishing capability %q", forbidden)
}
}
}
+29
View File
@@ -67,6 +67,35 @@ func TestWorkerImageIsNotDocumentedAsAStandaloneExecutor(t *testing.T) {
}
}
func TestFormattingUsesOneConfiguredWriter(t *testing.T) {
taskfile := readDeploymentFile(t, "Taskfile.yml")
fmtStart := strings.Index(taskfile, " fmt:\n")
fmtEnd := strings.Index(taskfile, " proto:install:\n")
if fmtStart < 0 || fmtEnd < fmtStart {
t.Fatal("Taskfile has no bounded fmt task")
}
fmtTask := taskfile[fmtStart:fmtEnd]
fix := strings.Index(fmtTask, "- go fix ./...")
format := strings.Index(fmtTask, "- golangci-lint fmt")
if fix < 0 || format < 0 || fix > format {
t.Error("fmt task must run go fix before the configured golangci-lint formatters")
}
if strings.Contains(fmtTask, "gofumpt -") {
t.Error("fmt task bypasses the configured formatter set with standalone gofumpt")
}
if got := strings.Count(taskfile, "- go fix ./..."); got != 1 {
t.Errorf("Taskfile runs go fix %d times, want exactly once through task fmt", got)
}
}
func TestFormattersExcludeInterpretedSecretEngines(t *testing.T) {
config := readDeploymentFile(t, ".golangci.yml")
if !strings.Contains(config, `^examples/secret-engines/(age|sops|vault)\.go$`) {
t.Fatal("formatter config does not protect the interpreted secret engines")
}
}
func TestSupportedProfilesUseOneExecutionTopology(t *testing.T) {
profiles := []string{
"deployments/single-forge-github.toml",