fix(build): make formatting and CI converge (#901)
This commit is contained in:
1 parent
301ced4dc0
commit
2935010504
9 files changed
+164
-53
No files matched your search
@@ -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
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -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
@@ -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)
|
||||
|
||||
@@ -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
@@ -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
@@ -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,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)
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -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",
|
||||
|
||||
Reference in new issue
Block a user