From 6b2866707d90a4bb4dc834d389a287a3db7960f4 Mon Sep 17 00:00:00 2001 From: PatternCatalyst Date: Sun, 2 Aug 2026 18:38:05 -0400 Subject: [PATCH 1/3] docs(r16): ch47 go-toolbox plan checkpoint (lgtm-relay Phase 1) --- _plans/r16-ch47-plan.md | 106 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 106 insertions(+) create mode 100644 _plans/r16-ch47-plan.md diff --git a/_plans/r16-ch47-plan.md b/_plans/r16-ch47-plan.md new file mode 100644 index 0000000..cb7b3d4 --- /dev/null +++ b/_plans/r16-ch47-plan.md @@ -0,0 +1,106 @@ +--- +title: "r16 / ch47 — go-toolbox — plan (internal)" +published: false +--- + +# r16 ch47 — example `47-go-toolbox` + chapter + 2 diagrams (lgtm-relay Phase 1) + +Go analog of ch46. Single-language `langs: [go]`, `mode: local`. Part 13 "Appendices: Tooling". +Same "every tool asserts a real effect, never exit-0" contract. + +## CRITICAL host finding +Only `go` (go1.26.5) is present. **gofumpt, golangci-lint, staticcheck, govulncheck, dlv, benchstat +ALL ABSENT.** check-host.sh: go hard-gated; golangci-lint/staticcheck/dlv warn-only; gofumpt/govulncheck/ +benchstat not gated. CI = base golang only. → Hard core must be go-native; marquee tools are +gated-if-present and Phase 2 must `go install` them (network) to capture real firing output, else footer +degrades to unverified. verify.lua ALWAYS skip-if-present so CI stays green. + +## Gate tiers +**Hard (go-native, deterministic, always run):** +- A. toolchain/version + digest: go.mod `go 1.26` + `toolchain go1.26.5`; `toolbox report` = integer/string-only + FNV-1a digest == fixed literal (reuse ch46 kPayload → same `0x481984990deee5ff`, cross-appendix easter egg). +- B. `go generate` diff-clean: `//go:generate go run ./internal/gen` regenerates committed `tools_generated.go`; + gate = regenerate → byte-identical. verify uses copy-aside-diff (no git needed); chapter shows `go generate ./... && git diff --exit-code`. +- C. gofmt: `gofmt -l` empty on tracked, nonempty on `testdata/gofmt/messy.go`. +- D. go vet: `//go:build vetdemo` Printf-mismatch file; `go vet -tags vetdemo .` reports stable `printf`. +- E. pprof structural: `go test -bench -cpuprofile` → `go tool pprof -top` names hot fn `hotLoop` (gate NAME not timings). + +**Gated-if-present (absent on host; Phase 2 go-installs for capture; skip-if-absent, never abort):** +- F. gofumpt — `-l` flags `testdata/gofumpt/gofmt_ok.go` (gofmt-clean/gofumpt-dirty). +- G. golangci-lint — committed `go/.golangci.yml`; assert one linter name token on a line. +- H. staticcheck — assert `SAxxxx`/`U1000` ID token on a line. +- I. delve — debug binary `-gcflags=all=-N -l`, headless batch via `go/.dlvinit`; assert printed digest decimal `5202111637775040511`. +- J. govulncheck — **network**. Isolated `go-vuln/` sub-module (own go.mod/go.sum) pinning a known-vulnerable dep + (x/text ParseAcceptLanguage, GO-20xx-xxxx; Phase 2 pins exact ver + reads exact GO-ID) calling the vulnerable + symbol; assert stable `GO-xxxx-xxxx` token. Main module = clean contrast. Double-guard: tool present AND vuln.go.dev + reachable. Never in default build/CI. +- K. benchstat — compare two `go test -bench` runs; assert table STRUCTURE only; ns/op shown-not-gated. + +**Shown-not-gated:** raw bench numbers, `go tool trace`, gctrace, vuln counts. + +**Fixture isolation (go compiles every .go in a dir):** `testdata/` (ignored by build/vet/test; tools target explicitly) +for gofmt/gofumpt fixtures; `//go:build vetdemo` tag for vet; unused unexported funcs in `smells.go` (compile-clean, +never called → don't touch digest) for staticcheck/golangci. + +## Chapter spine (ch44/ch46 precedent, plain fenced go/yaml/console, no codetabs) +hook → Fig47.1 → Tools-used box → go toolchain/version mgmt (go/toolchain directives, GOTOOLCHAIN) → deterministic +build+digest → go generate in depth (self-contained generator, DO-NOT-EDIT, diff-clean) → gofmt vs gofumpt → +golangci-lint config authoring → staticcheck → govulncheck (isolated vuln module, GO-ID, network decision stated) → +delve configs (.dlvinit headless batch) → How the code works → Errors N ways (gofmt/vet/staticcheck/golangci = 4 static +surfaces) → Concurrency lens (benchstat -cpu=1 vs N of a RunParallel bench; cross-ref ch44 GMP) → pprof/benchstat +workflow → build/run/observe → cross-check → what you learned → status footer. + +Differentiate (cross-ref, don't re-teach): ch31 (3-lang profiling breadth — pprof/trace/delve one-para each) → +ch47 deep on delve config authoring + pprof→benchstat workflow. ch44 (GMP/GC/netpoller internals) → ch47 = the +tooling that measures it. New: go/toolchain version mgmt, go-generate discipline, gofumpt-vs-gofmt, .golangci.yml/ +staticcheck authoring, govulncheck advisory workflow. + +Rejected: hard-gate absent tools (skip-if-present + Phase2 install); stringer for generate (keep gate hard w/ go run); +loose bad .go fixtures (testdata/+tags); vuln dep in main module (isolate in go-vuln/); assert message text/counts +(assert stable IDs); gate bench timings (gate pprof name + benchstat structure only). + +## Steps +1. Scaffold+strip (new-example.sh, delete cpp/rust, single-lang demo.sh). BLOCKING. +2. Module sources+configs+fixtures under go/: main.go, digest.go, internal/gen/main.go + tools_generated.go(committed), + bench_test.go(hotLoop+RunParallel), smells.go, vetdemo.go, testdata/gofmt/messy.go, testdata/gofumpt/gofmt_ok.go, + .golangci.yml, .dlvinit, go/demo.sh, go.mod; isolated go-vuln/{go.mod,go.sum,main.go}; README.md. Depends 1. +3. verify.lua (A-E hard; F-K if-present via tool_present + informational SKIP, govulncheck network-guarded; copy-aside + diff for generate) + demo.sh contract, LSP_LANG=go guard. Depends 2. +4. Local build+verify+capture: Phase 2 go-installs gofumpt/staticcheck/govulncheck/dlv/benchstat + golangci-lint + (network; dangerouslyDisableSandbox for install/govulncheck only), run every gate REAL, pin digest literal + exact + GO-xxxx/SAxxxx/linter tokens + line numbers + dlv decimal, confirm generate diff-clean + pprof hot-fn name. Gates prose. +5. Chapter _docs/47-go-toolbox.md. Depends 4. Parallel with 6. +6. 2 diagrams: 47-go-toolchain-pipeline (Fig47.1), 47-go-tool-gates (Fig47.2) + README rows. Depends 2. Parallel with 5. +7. manifest.yaml (langs:[go], mode:local, timeout 480) + catalogue. After 1. (manifest + diagrams/README = only shared files.) + +## Acceptance criteria +1. no cpp/rust dir; manifest 47-go-toolbox langs:[go] mode:local no requires. +2. ./demo.sh go build exits 0 NO network (stdlib-only main module). +3. go.mod has `go 1.26` + `toolchain go1.26.5`; report == asserted digest literal. +4. go generate → byte-identical committed (git diff --exit-code clean; verify copy-aside diff clean). +5. verify.lua PASS N/FAIL 0; A-E each real effect (digest, generate-diff, gofmt list, vet printf, pprof name) — no bare exit-0. +6. F-K each fire (Phase2 installed → pinned token) OR informational SKIP — never abort/FAIL; A-E still run. +7. govulncheck (if run) → pinned GO-xxxx on go-vuln/, clean on main; go-vuln/ never in default build/CI. +8. front matter part=="Appendices: Tooling"; full spine. +9. every chapter go/yaml/console block = verbatim substring of source (or real captured transcript). +10. validate.py OK; two Figure 47.x includes; both diagrams catalogued. +11. banned-words clean; Tools-used box == tools exercised. +12. test-all-examples --only 47-go-toolbox PASS; footer status--verified w/ real toolchain + per-gate evidence, explicit + status--unverified for any tool Phase 2 couldn't install. + +## Risks +tools absent (Phase2 install + skip-if-present); govulncheck DB/network (isolated module + double guard); bench/pprof +non-determinism (gate name/structure only); ID drift (assert stable tokens, re-pin step4); generate non-determinism +(sorted keys + go/format); fixture leakage (testdata/+tags+unused funcs); dlv DWARF (-gcflags=all=-N -l); sandbox network +for go install (dangerouslyDisableSandbox install/govulncheck only). + +## Verification outlook +PARTIALLY CLEAN. Hard core A-E fully CI-verifiable + offline-deterministic (go binary only). Marquee tools F-K absent on +host → depth depends on Phase 2 go-installing them (govulncheck needs network). If installed → footer like ch46 (all +firing, only benchstat timings shown). If not → those 6 sections legitimately status--unverified while hard core passes. +Merge safe either way; footer reflects exactly which optional tools Phase 2 installed. + +## Merge: pending user (see gate). +## Status +- [ ] S1 scaffold - [ ] S2 sources - [ ] S3 verify - [ ] S4 build+install+capture +- [ ] S5 chapter - [ ] S6 diagrams - [ ] S7 manifest - [ ] Phase3 validate - [ ] gate/PR From 79856c9420ff47dd300c82222a0718eefea8b889 Mon Sep 17 00:00:00 2001 From: PatternCatalyst Date: Mon, 3 Aug 2026 09:21:44 -0400 Subject: [PATCH 2/3] demo(demo-47): go-toolbox example + 2 diagrams (verify PASS 16/0, offline) Go-native hard gates: deterministic report digest (0x481984990deee5ff, same as ch46), go-generate diff-clean, gofmt, go vet printf, pprof hotLoop naming. gofumpt/golangci-lint/staticcheck/govulncheck/dlv/benchstat gated-if-present (absent on host -> SKIP), configs (.golangci.yml/.dlvinit) shipped as reference. Stdlib-only, no network, no vulnerable dep. --- _plans/r16-ch47-plan.md | 10 +- assets/diagrams/47-go-tool-gates.excalidraw | 2277 +++++++++++++++++ assets/diagrams/47-go-tool-gates.svg | 68 + .../47-go-toolchain-pipeline.excalidraw | 2024 +++++++++++++++ assets/diagrams/47-go-toolchain-pipeline.svg | 61 + assets/diagrams/README.md | 2 + examples/47-go-toolbox/README.md | 73 + examples/47-go-toolbox/demo.sh | 25 + examples/47-go-toolbox/go/.dlvinit | 4 + examples/47-go-toolbox/go/.golangci.yml | 23 + examples/47-go-toolbox/go/bench_test.go | 45 + examples/47-go-toolbox/go/demo.sh | 23 + examples/47-go-toolbox/go/digest.go | 36 + examples/47-go-toolbox/go/go.mod | 5 + .../47-go-toolbox/go/internal/gen/main.go | 76 + examples/47-go-toolbox/go/main.go | 79 + examples/47-go-toolbox/go/smells.go | 36 + .../47-go-toolbox/go/testdata/gofmt/messy.go | 15 + .../go/testdata/gofumpt/gofmt_ok.go | 13 + examples/47-go-toolbox/go/tools_generated.go | 23 + examples/47-go-toolbox/go/vetdemo.go | 14 + examples/47-go-toolbox/verify.lua | 213 ++ examples/manifest.yaml | 4 + 23 files changed, 5148 insertions(+), 1 deletion(-) create mode 100644 assets/diagrams/47-go-tool-gates.excalidraw create mode 100644 assets/diagrams/47-go-tool-gates.svg create mode 100644 assets/diagrams/47-go-toolchain-pipeline.excalidraw create mode 100644 assets/diagrams/47-go-toolchain-pipeline.svg create mode 100644 examples/47-go-toolbox/README.md create mode 100755 examples/47-go-toolbox/demo.sh create mode 100644 examples/47-go-toolbox/go/.dlvinit create mode 100644 examples/47-go-toolbox/go/.golangci.yml create mode 100644 examples/47-go-toolbox/go/bench_test.go create mode 100755 examples/47-go-toolbox/go/demo.sh create mode 100644 examples/47-go-toolbox/go/digest.go create mode 100644 examples/47-go-toolbox/go/go.mod create mode 100644 examples/47-go-toolbox/go/internal/gen/main.go create mode 100644 examples/47-go-toolbox/go/main.go create mode 100644 examples/47-go-toolbox/go/smells.go create mode 100644 examples/47-go-toolbox/go/testdata/gofmt/messy.go create mode 100644 examples/47-go-toolbox/go/testdata/gofumpt/gofmt_ok.go create mode 100644 examples/47-go-toolbox/go/tools_generated.go create mode 100644 examples/47-go-toolbox/go/vetdemo.go create mode 100644 examples/47-go-toolbox/verify.lua diff --git a/_plans/r16-ch47-plan.md b/_plans/r16-ch47-plan.md index cb7b3d4..a1774ae 100644 --- a/_plans/r16-ch47-plan.md +++ b/_plans/r16-ch47-plan.md @@ -100,7 +100,15 @@ host → depth depends on Phase 2 go-installing them (govulncheck needs network) firing, only benchstat timings shown). If not → those 6 sections legitimately status--unverified while hard core passes. Merge safe either way; footer reflects exactly which optional tools Phase 2 installed. -## Merge: pending user (see gate). +## DECISION (user, gate): HARD-CORE ONLY (offline) + AUTONOMOUS merge. +- NO network, NO `go install`, NO committing a vulnerable dep, NO `go-vuln/` sub-module. +- VERIFIED on this host = go-native hard gates A-E only. +- F-K (gofumpt/golangci-lint/staticcheck/govulncheck/dlv/benchstat): ship real committed config + artifacts (.golangci.yml, .dlvinit) + skip-if-present gates in verify.lua (a reader WITH the tools + hits them; on this host they informational-SKIP). Sections written + shown, marked status--unverified. +- govulncheck: chapter prose/workflow + clearly-labeled ILLUSTRATIVE advisory output (not "from a run"), + NOT gated, NO vulnerable dep in repo. +- verify.lua must PASS on A-E, informational-SKIP F-K, FAIL 0. ## Status - [ ] S1 scaffold - [ ] S2 sources - [ ] S3 verify - [ ] S4 build+install+capture - [ ] S5 chapter - [ ] S6 diagrams - [ ] S7 manifest - [ ] Phase3 validate - [ ] gate/PR diff --git a/assets/diagrams/47-go-tool-gates.excalidraw b/assets/diagrams/47-go-tool-gates.excalidraw new file mode 100644 index 0000000..462d6e3 --- /dev/null +++ b/assets/diagrams/47-go-tool-gates.excalidraw @@ -0,0 +1,2277 @@ +{ + "type": "excalidraw", + "version": 2, + "source": "https://excalidraw.com", + "elements": [ + { + "id": "r1826438661", + "type": "rectangle", + "x": 220, + "y": 40, + "width": 1060, + "height": 230, + "angle": 0, + "strokeColor": "#dddddd", + "backgroundColor": "#fff8ef", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 156204311, + "versionNonce": 262701540, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t1480763093", + "type": "text", + "x": 232, + "y": 46, + "width": 481.8, + "height": 15.0, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 887952720, + "versionNonce": 719814522, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "Hard lane \u2014 go-native, VERIFIED on this host (ships inside the go binary)", + "fontSize": 12, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "Hard lane \u2014 go-native, VERIFIED on this host (ships inside the go binary)", + "lineHeight": 1.25, + "baseline": 12 + }, + { + "id": "r1359016010", + "type": "rectangle", + "x": 220, + "y": 310, + "width": 1060, + "height": 230, + "angle": 0, + "strokeColor": "#dddddd", + "backgroundColor": "#fafafa", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 1700260770, + "versionNonce": 1673130984, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t1294421825", + "type": "text", + "x": 232, + "y": 316, + "width": 574.2, + "height": 15.0, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 900369565, + "versionNonce": 320373646, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "Gated-if-present lane \u2014 reader installs; NOT verified on this host (shown as reference)", + "fontSize": 12, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "Gated-if-present lane \u2014 reader installs; NOT verified on this host (shown as reference)", + "lineHeight": 1.25, + "baseline": 12 + }, + { + "id": "r496580711", + "type": "rectangle", + "x": 20, + "y": 235, + "width": 170, + "height": 150, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "#111111", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 1709011939, + "versionNonce": 1392368073, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t811556035", + "type": "text", + "x": 30, + "y": 243, + "width": 69.30000000000001, + "height": 17.5, + "angle": 0, + "strokeColor": "#ffffff", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1738216538, + "versionNonce": 174558644, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "go module", + "fontSize": 14, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "go module", + "lineHeight": 1.25, + "baseline": 14 + }, + { + "id": "t957148881", + "type": "text", + "x": 30, + "y": 263, + "width": 90.75000000000001, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 253580127, + "versionNonce": 1687454713, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "one source tree", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "one source tree", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "t1595001807", + "type": "text", + "x": 30, + "y": 278, + "width": 133.10000000000002, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1659894552, + "versionNonce": 578566182, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "two verification lanes", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "two verification lanes", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "r1712701532", + "type": "rectangle", + "x": 250, + "y": 110, + "width": 185, + "height": 90, + "angle": 0, + "strokeColor": "#e8870c", + "backgroundColor": "#fff8ef", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 539427735, + "versionNonce": 1998338759, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t1909107763", + "type": "text", + "x": 260, + "y": 118, + "width": 61.60000000000001, + "height": 17.5, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1751346206, + "versionNonce": 401847063, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "gofmt -l", + "fontSize": 14, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "gofmt -l", + "lineHeight": 1.25, + "baseline": 14 + }, + { + "id": "t1634455893", + "type": "text", + "x": 260, + "y": 138, + "width": 96.80000000000001, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1005056980, + "versionNonce": 1155192183, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "empty on tracked", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "empty on tracked", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "t1788360304", + "type": "text", + "x": 260, + "y": 153, + "width": 121.00000000000001, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 814435527, + "versionNonce": 911476316, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "nonempty on messy.go", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "nonempty on messy.go", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "r1652612870", + "type": "rectangle", + "x": 460, + "y": 110, + "width": 185, + "height": 90, + "angle": 0, + "strokeColor": "#e8870c", + "backgroundColor": "#fff8ef", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 1731091603, + "versionNonce": 1175351430, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t1543376661", + "type": "text", + "x": 470, + "y": 118, + "width": 84.7, + "height": 17.5, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 781960778, + "versionNonce": 435635635, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "go generate", + "fontSize": 14, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "go generate", + "lineHeight": 1.25, + "baseline": 14 + }, + { + "id": "t445374778", + "type": "text", + "x": 470, + "y": 138, + "width": 90.75000000000001, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1129135383, + "versionNonce": 450839337, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "diff-clean gate", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "diff-clean gate", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "t700556101", + "type": "text", + "x": 470, + "y": 153, + "width": 121.00000000000001, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1897331037, + "versionNonce": 1919727122, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "git diff --exit-code", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "git diff --exit-code", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "r1000063712", + "type": "rectangle", + "x": 670, + "y": 110, + "width": 185, + "height": 90, + "angle": 0, + "strokeColor": "#e8870c", + "backgroundColor": "#fff8ef", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 1657150860, + "versionNonce": 1042110985, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t1660485909", + "type": "text", + "x": 680, + "y": 118, + "width": 154.0, + "height": 17.5, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1268877522, + "versionNonce": 900886868, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "go vet -tags vetdemo", + "fontSize": 14, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "go vet -tags vetdemo", + "lineHeight": 1.25, + "baseline": 14 + }, + { + "id": "t1605654904", + "type": "text", + "x": 680, + "y": 138, + "width": 90.75000000000001, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1427318628, + "versionNonce": 741857440, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "printf mismatch", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "printf mismatch", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "t319817301", + "type": "text", + "x": 680, + "y": 153, + "width": 84.7, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1344752311, + "versionNonce": 673286771, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "stable finding", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "stable finding", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "r1678215553", + "type": "rectangle", + "x": 880, + "y": 110, + "width": 185, + "height": 90, + "angle": 0, + "strokeColor": "#e8870c", + "backgroundColor": "#fff8ef", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 1736470557, + "versionNonce": 884029603, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t1701710336", + "type": "text", + "x": 890, + "y": 118, + "width": 77.0, + "height": 17.5, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 497586081, + "versionNonce": 239627240, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "pprof -top", + "fontSize": 14, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "pprof -top", + "lineHeight": 1.25, + "baseline": 14 + }, + { + "id": "t376999930", + "type": "text", + "x": 890, + "y": 138, + "width": 60.50000000000001, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 665626247, + "versionNonce": 1045937729, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "cpuprofile", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "cpuprofile", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "t139902023", + "type": "text", + "x": 890, + "y": 153, + "width": 90.75000000000001, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 618737642, + "versionNonce": 1350884435, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "hot fn: hotLoop", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "hot fn: hotLoop", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "r82157118", + "type": "rectangle", + "x": 1090, + "y": 110, + "width": 185, + "height": 90, + "angle": 0, + "strokeColor": "#e8870c", + "backgroundColor": "#fff8ef", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 680818173, + "versionNonce": 1584346184, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t1764400784", + "type": "text", + "x": 1100, + "y": 118, + "width": 107.80000000000001, + "height": 17.5, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1996583909, + "versionNonce": 1476760551, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "toolbox report", + "fontSize": 14, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "toolbox report", + "lineHeight": 1.25, + "baseline": 14 + }, + { + "id": "t291935389", + "type": "text", + "x": 1100, + "y": 138, + "width": 78.65, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 228200980, + "versionNonce": 26092031, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "FNV-1a digest", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "FNV-1a digest", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "t1604906625", + "type": "text", + "x": 1100, + "y": 153, + "width": 108.9, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1962644730, + "versionNonce": 1231882143, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "0x481984990deee5ff", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "0x481984990deee5ff", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "r1565989749", + "type": "rectangle", + "x": 240, + "y": 380, + "width": 150, + "height": 90, + "angle": 0, + "strokeColor": "#999999", + "backgroundColor": "#ffffff", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "dashed", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 1669141752, + "versionNonce": 832777964, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t14871408", + "type": "text", + "x": 250, + "y": 388, + "width": 77.0, + "height": 17.5, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1113049147, + "versionNonce": 277033603, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "gofumpt -l", + "fontSize": 14, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "gofumpt -l", + "lineHeight": 1.25, + "baseline": 14 + }, + { + "id": "t1293217905", + "type": "text", + "x": 250, + "y": 408, + "width": 114.95, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 707407986, + "versionNonce": 1441498952, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "stricter than gofmt", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "stricter than gofmt", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "t661965357", + "type": "text", + "x": 250, + "y": 423, + "width": 96.80000000000001, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 814980206, + "versionNonce": 1886695293, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "testdata/gofumpt", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "testdata/gofumpt", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "r1617522159", + "type": "rectangle", + "x": 408, + "y": 380, + "width": 150, + "height": 90, + "angle": 0, + "strokeColor": "#999999", + "backgroundColor": "#ffffff", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "dashed", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 647673752, + "versionNonce": 1271561361, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t1379008378", + "type": "text", + "x": 418, + "y": 388, + "width": 100.10000000000001, + "height": 17.5, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1948286096, + "versionNonce": 1701053022, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "golangci-lint", + "fontSize": 14, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "golangci-lint", + "lineHeight": 1.25, + "baseline": 14 + }, + { + "id": "t1189490751", + "type": "text", + "x": 418, + "y": 408, + "width": 78.65, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 312829803, + "versionNonce": 891261050, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": ".golangci.yml", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": ".golangci.yml", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "t1198015791", + "type": "text", + "x": 418, + "y": 423, + "width": 102.85000000000001, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1475251952, + "versionNonce": 1899691776, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "linter name token", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "linter name token", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "r296008996", + "type": "rectangle", + "x": 576, + "y": 380, + "width": 150, + "height": 90, + "angle": 0, + "strokeColor": "#999999", + "backgroundColor": "#ffffff", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "dashed", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 922000330, + "versionNonce": 1875526378, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t383840527", + "type": "text", + "x": 586, + "y": 388, + "width": 84.7, + "height": 17.5, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 533124005, + "versionNonce": 786941847, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "staticcheck", + "fontSize": 14, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "staticcheck", + "lineHeight": 1.25, + "baseline": 14 + }, + { + "id": "t1046880368", + "type": "text", + "x": 586, + "y": 408, + "width": 84.7, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 261677050, + "versionNonce": 27185978, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "SAxxxx / U1000", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "SAxxxx / U1000", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "t1519411529", + "type": "text", + "x": 586, + "y": 423, + "width": 60.50000000000001, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 146780612, + "versionNonce": 1246987227, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "finding ID", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "finding ID", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "r1817033174", + "type": "rectangle", + "x": 744, + "y": 380, + "width": 150, + "height": 90, + "angle": 0, + "strokeColor": "#999999", + "backgroundColor": "#ffffff", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "dashed", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 309112181, + "versionNonce": 547332847, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t566859718", + "type": "text", + "x": 754, + "y": 388, + "width": 40, + "height": 17.5, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 852885022, + "versionNonce": 1710632134, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "delve", + "fontSize": 14, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "delve", + "lineHeight": 1.25, + "baseline": 14 + }, + { + "id": "t550484415", + "type": "text", + "x": 754, + "y": 408, + "width": 102.85000000000001, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1918759913, + "versionNonce": 1462953973, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "headless .dlvinit", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "headless .dlvinit", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "t1287434966", + "type": "text", + "x": 754, + "y": 423, + "width": 121.00000000000001, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1470443752, + "versionNonce": 972907296, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "print digest decimal", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "print digest decimal", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "r1620014794", + "type": "rectangle", + "x": 912, + "y": 380, + "width": 150, + "height": 90, + "angle": 0, + "strokeColor": "#999999", + "backgroundColor": "#ffffff", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "dashed", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 619323957, + "versionNonce": 1602262845, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t977085862", + "type": "text", + "x": 922, + "y": 388, + "width": 84.7, + "height": 17.5, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 824854821, + "versionNonce": 354918519, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "govulncheck", + "fontSize": 14, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "govulncheck", + "lineHeight": 1.25, + "baseline": 14 + }, + { + "id": "t246666863", + "type": "text", + "x": 922, + "y": 408, + "width": 96.80000000000001, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1149794843, + "versionNonce": 167575798, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "GO-xxxx advisory", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "GO-xxxx advisory", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "t469849189", + "type": "text", + "x": 922, + "y": 423, + "width": 96.80000000000001, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 817079374, + "versionNonce": 1718098015, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "network required", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "network required", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "r581881934", + "type": "rectangle", + "x": 1080, + "y": 380, + "width": 150, + "height": 90, + "angle": 0, + "strokeColor": "#999999", + "backgroundColor": "#ffffff", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "dashed", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 234237918, + "versionNonce": 1630645601, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t162201959", + "type": "text", + "x": 1090, + "y": 388, + "width": 69.30000000000001, + "height": 17.5, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1434706088, + "versionNonce": 362261285, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "benchstat", + "fontSize": 14, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "benchstat", + "lineHeight": 1.25, + "baseline": 14 + }, + { + "id": "t1557006855", + "type": "text", + "x": 1090, + "y": 408, + "width": 108.9, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 16500937, + "versionNonce": 595477121, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "compare bench runs", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "compare bench runs", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "t1515764078", + "type": "text", + "x": 1090, + "y": 423, + "width": 121.00000000000001, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1746550506, + "versionNonce": 1642130106, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "table structure only", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "table structure only", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "a657262147", + "type": "arrow", + "x": 190, + "y": 270, + "width": 60, + "height": 115.0, + "angle": 0, + "strokeColor": "#b8650a", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 29923672, + "versionNonce": 1748154778, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 60, + -115.0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "a172791176", + "type": "arrow", + "x": 190, + "y": 350, + "width": 50, + "height": 75.0, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "dashed", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 1250518665, + "versionNonce": 947110987, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 50, + 75.0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "a510963412", + "type": "arrow", + "x": 435, + "y": 155.0, + "width": 25, + "height": 0.0, + "angle": 0, + "strokeColor": "#b8650a", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 1637061624, + "versionNonce": 1587323655, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 25, + 0.0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "a822893197", + "type": "arrow", + "x": 645, + "y": 155.0, + "width": 25, + "height": 0.0, + "angle": 0, + "strokeColor": "#b8650a", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 870741181, + "versionNonce": 983711016, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 25, + 0.0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "a971781140", + "type": "arrow", + "x": 855, + "y": 155.0, + "width": 25, + "height": 0.0, + "angle": 0, + "strokeColor": "#b8650a", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 1664292527, + "versionNonce": 1924137687, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 25, + 0.0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "a1716220573", + "type": "arrow", + "x": 1065, + "y": 155.0, + "width": 25, + "height": 0.0, + "angle": 0, + "strokeColor": "#b8650a", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 1257427331, + "versionNonce": 227592039, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 25, + 0.0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "a1266654274", + "type": "arrow", + "x": 390, + "y": 425.0, + "width": 18, + "height": 0.0, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "dashed", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 1350316668, + "versionNonce": 398056737, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 18, + 0.0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "a1820898170", + "type": "arrow", + "x": 558, + "y": 425.0, + "width": 18, + "height": 0.0, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "dashed", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 42549113, + "versionNonce": 410263361, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 18, + 0.0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "a1830305420", + "type": "arrow", + "x": 726, + "y": 425.0, + "width": 18, + "height": 0.0, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "dashed", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 1340553777, + "versionNonce": 1524633177, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 18, + 0.0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "a363177754", + "type": "arrow", + "x": 894, + "y": 425.0, + "width": 18, + "height": 0.0, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "dashed", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 371605935, + "versionNonce": 499782960, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 18, + 0.0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "a1026538920", + "type": "arrow", + "x": 1062, + "y": 425.0, + "width": 18, + "height": 0.0, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "dashed", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 1913017650, + "versionNonce": 652338126, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 18, + 0.0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "t1934892568", + "type": "text", + "x": 220, + "y": 555, + "width": 838.2, + "height": 15.0, + "angle": 0, + "strokeColor": "#1d1d1d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1831102715, + "versionNonce": 1514659027, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "Hard lane needs no install \u2014 it is verified this session (gofmt/go generate/go vet/pprof/digest all ship inside the go binary).", + "fontSize": 12, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "Hard lane needs no install \u2014 it is verified this session (gofmt/go generate/go vet/pprof/digest all ship inside the go binary).", + "lineHeight": 1.25, + "baseline": 12 + }, + { + "id": "t1804578494", + "type": "text", + "x": 220, + "y": 571, + "width": 825.0000000000001, + "height": 15.0, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 61891726, + "versionNonce": 1499071186, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "Gated lane needs `go install @latest` (govulncheck also needs network) \u2014 not run on this host; shown as reference only.", + "fontSize": 12, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "Gated lane needs `go install @latest` (govulncheck also needs network) \u2014 not run on this host; shown as reference only.", + "lineHeight": 1.25, + "baseline": 12 + } + ], + "appState": { + "viewBackgroundColor": "#ffffff", + "gridSize": null + }, + "files": {} +} \ No newline at end of file diff --git a/assets/diagrams/47-go-tool-gates.svg b/assets/diagrams/47-go-tool-gates.svg new file mode 100644 index 0000000..8153ad3 --- /dev/null +++ b/assets/diagrams/47-go-tool-gates.svg @@ -0,0 +1,68 @@ + + + +Hard lane — go-native, VERIFIED on this host (ships inside the go binary) + +Gated-if-present lane — reader installs; NOT verified on this host (shown as reference) + +go module +one source tree +two verification lanes + +gofmt -l +empty on tracked +nonempty on messy.go + +go generate +diff-clean gate +git diff --exit-code + +go vet -tags vetdemo +printf mismatch +stable finding + +pprof -top +cpuprofile +hot fn: hotLoop + +toolbox report +FNV-1a digest +0x481984990deee5ff + +gofumpt -l +stricter than gofmt +testdata/gofumpt + +golangci-lint +.golangci.yml +linter name token + +staticcheck +SAxxxx / U1000 +finding ID + +delve +headless .dlvinit +print digest decimal + +govulncheck +GO-xxxx advisory +network required + +benchstat +compare bench runs +table structure only + + + + + + + + + + + +Hard lane needs no install — it is verified this session (gofmt/go generate/go vet/pprof/digest all ship inside the go binary). +Gated lane needs `go install <tool>@latest` (govulncheck also needs network) — not run on this host; shown as reference only. + \ No newline at end of file diff --git a/assets/diagrams/47-go-toolchain-pipeline.excalidraw b/assets/diagrams/47-go-toolchain-pipeline.excalidraw new file mode 100644 index 0000000..38a9447 --- /dev/null +++ b/assets/diagrams/47-go-toolchain-pipeline.excalidraw @@ -0,0 +1,2024 @@ +{ + "type": "excalidraw", + "version": 2, + "source": "https://excalidraw.com", + "elements": [ + { + "id": "r1648752548", + "type": "rectangle", + "x": 20, + "y": 20, + "width": 1160, + "height": 150, + "angle": 0, + "strokeColor": "#dddddd", + "backgroundColor": "#fafafa", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 1585458818, + "versionNonce": 1204347531, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t373542625", + "type": "text", + "x": 32, + "y": 26, + "width": 349.8, + "height": 15.0, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1188439674, + "versionNonce": 234116616, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "go.mod \u2192 GOTOOLCHAIN \u2192 go binary \u2014 version resolution", + "fontSize": 12, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "go.mod \u2192 GOTOOLCHAIN \u2192 go binary \u2014 version resolution", + "lineHeight": 1.25, + "baseline": 12 + }, + { + "id": "r1715258281", + "type": "rectangle", + "x": 20, + "y": 190, + "width": 580, + "height": 390, + "angle": 0, + "strokeColor": "#dddddd", + "backgroundColor": "#fafafa", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 913732557, + "versionNonce": 146299687, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t1905408264", + "type": "text", + "x": 32, + "y": 196, + "width": 363.00000000000006, + "height": 15.0, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 645551824, + "versionNonce": 74649846, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "go generate arm \u2014 diff-clean gate (verified, go-native)", + "fontSize": 12, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "go generate arm \u2014 diff-clean gate (verified, go-native)", + "lineHeight": 1.25, + "baseline": 12 + }, + { + "id": "r807300583", + "type": "rectangle", + "x": 620, + "y": 190, + "width": 560, + "height": 390, + "angle": 0, + "strokeColor": "#dddddd", + "backgroundColor": "#fafafa", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 1249914377, + "versionNonce": 1063015753, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t638310480", + "type": "text", + "x": 632, + "y": 196, + "width": 495.00000000000006, + "height": 15.0, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1818153902, + "versionNonce": 1756037033, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "go build / go run arm \u2014 deterministic report \u2192 digest (verified, go-native)", + "fontSize": 12, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "go build / go run arm \u2014 deterministic report \u2192 digest (verified, go-native)", + "lineHeight": 1.25, + "baseline": 12 + }, + { + "id": "r172141253", + "type": "rectangle", + "x": 60, + "y": 70, + "width": 190, + "height": 70, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "#111111", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 907305469, + "versionNonce": 1282212875, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t626531250", + "type": "text", + "x": 70, + "y": 78, + "width": 46.2, + "height": 17.5, + "angle": 0, + "strokeColor": "#ffffff", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1447108806, + "versionNonce": 564519694, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "go.mod", + "fontSize": 14, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "go.mod", + "lineHeight": 1.25, + "baseline": 14 + }, + { + "id": "t91666269", + "type": "text", + "x": 70, + "y": 98, + "width": 42.35, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1172935886, + "versionNonce": 554167050, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "go 1.26", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "go 1.26", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "t383240926", + "type": "text", + "x": 70, + "y": 113, + "width": 108.9, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 398968015, + "versionNonce": 1650289800, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "toolchain go1.26.5", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "toolchain go1.26.5", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "r925371020", + "type": "rectangle", + "x": 340, + "y": 70, + "width": 210, + "height": 70, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "#ffffff", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 1401113658, + "versionNonce": 238024415, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t471494636", + "type": "text", + "x": 350, + "y": 78, + "width": 84.7, + "height": 17.5, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 771224777, + "versionNonce": 1037399055, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "GOTOOLCHAIN", + "fontSize": 14, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "GOTOOLCHAIN", + "lineHeight": 1.25, + "baseline": 14 + }, + { + "id": "t163148116", + "type": "text", + "x": 350, + "y": 98, + "width": 133.10000000000002, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1844948030, + "versionNonce": 1937329812, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "env resolves directive", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "env resolves directive", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "t1195991778", + "type": "text", + "x": 350, + "y": 113, + "width": 114.95, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1439317365, + "versionNonce": 1343148414, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "download if missing", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "download if missing", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "r823041557", + "type": "rectangle", + "x": 630, + "y": 70, + "width": 220, + "height": 70, + "angle": 0, + "strokeColor": "#2f6db5", + "backgroundColor": "#eef4fb", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 338093217, + "versionNonce": 1429993229, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t699276073", + "type": "text", + "x": 640, + "y": 78, + "width": 69.30000000000001, + "height": 17.5, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1971606107, + "versionNonce": 1107362938, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "go binary", + "fontSize": 14, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "go binary", + "lineHeight": 1.25, + "baseline": 14 + }, + { + "id": "t942650476", + "type": "text", + "x": 640, + "y": 98, + "width": 48.400000000000006, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 893531428, + "versionNonce": 174787986, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "go1.26.5", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "go1.26.5", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "t560011170", + "type": "text", + "x": 640, + "y": 113, + "width": 151.25, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 125855495, + "versionNonce": 812640218, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "drives build/run/generate", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "drives build/run/generate", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "r141613802", + "type": "rectangle", + "x": 60, + "y": 235, + "width": 230, + "height": 60, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "#ffffff", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 344578664, + "versionNonce": 1680529503, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t1298004327", + "type": "text", + "x": 70, + "y": 243, + "width": 177.10000000000002, + "height": 17.5, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 507916206, + "versionNonce": 559771188, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "//go:generate directive", + "fontSize": 14, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "//go:generate directive", + "lineHeight": 1.25, + "baseline": 14 + }, + { + "id": "t348584327", + "type": "text", + "x": 70, + "y": 263, + "width": 127.05000000000001, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1911756132, + "versionNonce": 873170968, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "go run ./internal/gen", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "go run ./internal/gen", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "r1986513636", + "type": "rectangle", + "x": 60, + "y": 330, + "width": 230, + "height": 60, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "#ffffff", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 844855327, + "versionNonce": 1677663981, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t327837942", + "type": "text", + "x": 70, + "y": 338, + "width": 92.4, + "height": 17.5, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 287470052, + "versionNonce": 1046045302, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "internal/gen", + "fontSize": 14, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "internal/gen", + "lineHeight": 1.25, + "baseline": 14 + }, + { + "id": "t276922994", + "type": "text", + "x": 70, + "y": 358, + "width": 139.15, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 618848121, + "versionNonce": 34888791, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "code generator (go run)", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "code generator (go run)", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "r561510924", + "type": "rectangle", + "x": 60, + "y": 425, + "width": 230, + "height": 80, + "angle": 0, + "strokeColor": "#999999", + "backgroundColor": "#ffffff", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 1950978624, + "versionNonce": 1289943620, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t1219434954", + "type": "text", + "x": 70, + "y": 433, + "width": 138.60000000000002, + "height": 17.5, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 123615130, + "versionNonce": 382619666, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "tools_generated.go", + "fontSize": 14, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "tools_generated.go", + "lineHeight": 1.25, + "baseline": 14 + }, + { + "id": "t1816952600", + "type": "text", + "x": 70, + "y": 453, + "width": 102.85000000000001, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 700438330, + "versionNonce": 1240616879, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "committed to repo", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "committed to repo", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "t1487254459", + "type": "text", + "x": 70, + "y": 468, + "width": 84.7, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 628853110, + "versionNonce": 1951897821, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "// DO NOT EDIT", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "// DO NOT EDIT", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "r1917059257", + "type": "rectangle", + "x": 340, + "y": 350, + "width": 210, + "height": 100, + "angle": 0, + "strokeColor": "#e8870c", + "backgroundColor": "#fff8ef", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 165215829, + "versionNonce": 1447138571, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t809771497", + "type": "text", + "x": 350, + "y": 358, + "width": 115.50000000000001, + "height": 17.5, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1888199429, + "versionNonce": 868834365, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "diff-clean gate", + "fontSize": 14, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "diff-clean gate", + "lineHeight": 1.25, + "baseline": 14 + }, + { + "id": "t360341874", + "type": "text", + "x": 350, + "y": 378, + "width": 121.00000000000001, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 734035866, + "versionNonce": 157266080, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "go generate ./... &&", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "go generate ./... &&", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "t6637195", + "type": "text", + "x": 350, + "y": 393, + "width": 121.00000000000001, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 806505406, + "versionNonce": 1559274358, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "git diff --exit-code", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "git diff --exit-code", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "t946011958", + "type": "text", + "x": 350, + "y": 408, + "width": 108.9, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1418450887, + "versionNonce": 379115533, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "verified hard gate", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "verified hard gate", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "r278862988", + "type": "rectangle", + "x": 650, + "y": 235, + "width": 230, + "height": 60, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "#ffffff", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 903290202, + "versionNonce": 123167914, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t671479410", + "type": "text", + "x": 660, + "y": 243, + "width": 130.9, + "height": 17.5, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1388164551, + "versionNonce": 401482821, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "go build / go run", + "fontSize": 14, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "go build / go run", + "lineHeight": 1.25, + "baseline": 14 + }, + { + "id": "t386007786", + "type": "text", + "x": 660, + "y": 263, + "width": 121.00000000000001, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1253209165, + "versionNonce": 1927953414, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "./go/... main module", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "./go/... main module", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "r1953450848", + "type": "rectangle", + "x": 650, + "y": 330, + "width": 230, + "height": 60, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "#ffffff", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 1374895220, + "versionNonce": 1389051791, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t910702509", + "type": "text", + "x": 660, + "y": 338, + "width": 107.80000000000001, + "height": 17.5, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 642129071, + "versionNonce": 795760522, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "toolbox binary", + "fontSize": 14, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "toolbox binary", + "lineHeight": 1.25, + "baseline": 14 + }, + { + "id": "t717254439", + "type": "text", + "x": 660, + "y": 358, + "width": 139.15, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1708065152, + "versionNonce": 876433740, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "stdlib-only, no network", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "stdlib-only, no network", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "r1943266980", + "type": "rectangle", + "x": 650, + "y": 425, + "width": 230, + "height": 80, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "#ffffff", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 231875679, + "versionNonce": 1683805687, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t1731967048", + "type": "text", + "x": 660, + "y": 433, + "width": 107.80000000000001, + "height": 17.5, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 783822029, + "versionNonce": 1630899878, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "toolbox report", + "fontSize": 14, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "toolbox report", + "lineHeight": 1.25, + "baseline": 14 + }, + { + "id": "t1892094328", + "type": "text", + "x": 660, + "y": 453, + "width": 145.20000000000002, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 39394362, + "versionNonce": 945449875, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "FNV-1a over fixed inputs", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "FNV-1a over fixed inputs", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "r881526650", + "type": "rectangle", + "x": 930, + "y": 350, + "width": 210, + "height": 100, + "angle": 0, + "strokeColor": "#e8870c", + "backgroundColor": "#fff8ef", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 3 + }, + "seed": 1020977343, + "versionNonce": 792102827, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false + }, + { + "id": "t85907323", + "type": "text", + "x": 940, + "y": 358, + "width": 84.7, + "height": 17.5, + "angle": 0, + "strokeColor": "#111111", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 1210172986, + "versionNonce": 1595280456, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "digest gate", + "fontSize": 14, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "digest gate", + "lineHeight": 1.25, + "baseline": 14 + }, + { + "id": "t885795362", + "type": "text", + "x": 940, + "y": 378, + "width": 108.9, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 9004257, + "versionNonce": 1871201528, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "0x481984990deee5ff", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "0x481984990deee5ff", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "t402979089", + "type": "text", + "x": 940, + "y": 393, + "width": 114.95, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 903809215, + "versionNonce": 821376588, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "integer/string-only", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "integer/string-only", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "t229409505", + "type": "text", + "x": 940, + "y": 408, + "width": 108.9, + "height": 13.75, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 511707386, + "versionNonce": 230468835, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "verified hard gate", + "fontSize": 11, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "verified hard gate", + "lineHeight": 1.25, + "baseline": 11 + }, + { + "id": "a1560726517", + "type": "arrow", + "x": 250, + "y": 105.0, + "width": 90, + "height": 0.0, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 4048131, + "versionNonce": 779755543, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 90, + 0.0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "a1736665454", + "type": "arrow", + "x": 550, + "y": 105.0, + "width": 80, + "height": 0.0, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 1301831102, + "versionNonce": 843450310, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 80, + 0.0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "a529619457", + "type": "arrow", + "x": 740.0, + "y": 140, + "width": 565.0, + "height": 95, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 850128815, + "versionNonce": 90312674, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + -565.0, + 95 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "a1065405682", + "type": "arrow", + "x": 740.0, + "y": 140, + "width": 25.0, + "height": 95, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 61236831, + "versionNonce": 1695432703, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 25.0, + 95 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "a1725063183", + "type": "arrow", + "x": 175.0, + "y": 295, + "width": 0.0, + "height": 35, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 1173680845, + "versionNonce": 1719506534, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0.0, + 35 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "a1342312577", + "type": "arrow", + "x": 175.0, + "y": 390, + "width": 0.0, + "height": 35, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 1659901430, + "versionNonce": 841137616, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0.0, + 35 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "a48964974", + "type": "arrow", + "x": 290, + "y": 465.0, + "width": 50, + "height": 65.0, + "angle": 0, + "strokeColor": "#b8650a", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 647343369, + "versionNonce": 375417290, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 50, + -65.0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "a1367071976", + "type": "arrow", + "x": 765.0, + "y": 295, + "width": 0.0, + "height": 35, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 691592806, + "versionNonce": 644065231, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0.0, + 35 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "a1896060666", + "type": "arrow", + "x": 765.0, + "y": 390, + "width": 0.0, + "height": 35, + "angle": 0, + "strokeColor": "#555555", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 911629798, + "versionNonce": 1580487422, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 0.0, + 35 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "a604988284", + "type": "arrow", + "x": 880, + "y": 465.0, + "width": 50, + "height": 65.0, + "angle": 0, + "strokeColor": "#b8650a", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 2, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": { + "type": 2 + }, + "seed": 324724483, + "versionNonce": 1622010200, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "points": [ + [ + 0, + 0 + ], + [ + 50, + -65.0 + ] + ], + "lastCommittedPoint": null, + "startBinding": null, + "endBinding": null, + "startArrowhead": null, + "endArrowhead": "arrow" + }, + { + "id": "t180353051", + "type": "text", + "x": 20, + "y": 595, + "width": 884.4000000000001, + "height": 15.0, + "angle": 0, + "strokeColor": "#1d1d1d", + "backgroundColor": "transparent", + "fillStyle": "solid", + "strokeWidth": 1, + "strokeStyle": "solid", + "roughness": 1, + "opacity": 100, + "groupIds": [], + "frameId": null, + "roundness": null, + "seed": 602794887, + "versionNonce": 1036747698, + "isDeleted": false, + "boundElements": [], + "updated": 1, + "link": null, + "locked": false, + "text": "Both gates are go-native (gofmt/vet/generate ship inside the go binary) and verified offline on this host \u2014 no go install, no network.", + "fontSize": 12, + "fontFamily": 1, + "textAlign": "left", + "verticalAlign": "top", + "containerId": null, + "originalText": "Both gates are go-native (gofmt/vet/generate ship inside the go binary) and verified offline on this host \u2014 no go install, no network.", + "lineHeight": 1.25, + "baseline": 12 + } + ], + "appState": { + "viewBackgroundColor": "#ffffff", + "gridSize": null + }, + "files": {} +} \ No newline at end of file diff --git a/assets/diagrams/47-go-toolchain-pipeline.svg b/assets/diagrams/47-go-toolchain-pipeline.svg new file mode 100644 index 0000000..3eaddfc --- /dev/null +++ b/assets/diagrams/47-go-toolchain-pipeline.svg @@ -0,0 +1,61 @@ + + + +go.mod → GOTOOLCHAIN → go binary — version resolution + +go generate arm — diff-clean gate (verified, go-native) + +go build / go run arm — deterministic report → digest (verified, go-native) + +go.mod +go 1.26 +toolchain go1.26.5 + +GOTOOLCHAIN +env resolves directive +download if missing + +go binary +go1.26.5 +drives build/run/generate + +//go:generate directive +go run ./internal/gen + +internal/gen +code generator (go run) + +tools_generated.go +committed to repo +// DO NOT EDIT + +diff-clean gate +go generate ./... && +git diff --exit-code +verified hard gate + +go build / go run +./go/... main module + +toolbox binary +stdlib-only, no network + +toolbox report +FNV-1a over fixed inputs + +digest gate +0x481984990deee5ff +integer/string-only +verified hard gate + + + + + + + + + + +Both gates are go-native (gofmt/vet/generate ship inside the go binary) and verified offline on this host — no go install, no network. + \ No newline at end of file diff --git a/assets/diagrams/README.md b/assets/diagrams/README.md index b433c4e..ad82a6d 100644 --- a/assets/diagrams/README.md +++ b/assets/diagrams/README.md @@ -91,3 +91,5 @@ here as you add them: | `45-pcp-build-gate` | 45 | the PCP image's three Containerfile stages -- builder (dnf install pcp + two PMDAs, `pmcd` started before `./Install`) → smoke (`FROM builder`, the `pcp`/`pminfo` gate proving openmetrics answers `value 42`) → runtime (`FROM smoke`, `EXPOSE 44321`, `ENTRYPOINT pmcd -f`), the amber `FROM smoke` edge that forces podman to build the gate stage, with Cockpit + SystemTap a dashed not-in-this-image box | | `46-cmake-preset-graph` | 46 | the CMakePresets inheritance graph -- one `_base` config preset fanning out to `release`/`debug`/`asan`/`ubsan` and their `-clang` twins (color-coded GCC vs clang), each into its own `build/`, annotated with which tool consumes which preset (verify's parity gate, the UBSan gate, gdb), with the `conan` sub-target preset held apart and dashed-linked as isolated so the default build needs no Conan | | `46-toolbox-pipeline` | 46 | the toolbox pipeline -- one `toolbox.cpp` source built by GCC and clang into the amber byte-identical parity gate (`diff == empty`), beside the static arm (`clang-tidy`, `clang-format --dry-run --Werror`) and the runtime arm (`ubsan` build → signed-overflow abort, `debug` build → gdb + Python pretty-printer → `Digest(0x…)`), with `ccache`/`mold` as dashed, not-verified-on-host accelerators | +| `47-go-toolchain-pipeline` | 47 | the Go toolchain and version-management flow -- `go.mod`'s `go 1.26`/`toolchain go1.26.5` directives resolving through `GOTOOLCHAIN` into the `go` binary, which fans into the amber `go generate` diff-clean gate (`go generate ./... && git diff --exit-code` regenerating the committed `tools_generated.go`) and the amber deterministic `toolbox report` digest gate (`0x481984990deee5ff`), both go-native and verified offline on this host | +| `47-go-tool-gates` | 47 | one Go module fanning into two gate lanes by verification status -- the amber hard lane (`gofmt -l`, `go generate` diff-clean, `go vet -tags vetdemo` printf finding, `pprof -top` naming hot fn `hotLoop`, the FNV-1a digest) that ships inside the `go` binary and verifies offline, beside the dashed gated-if-present lane (gofumpt, golangci-lint, staticcheck, delve, govulncheck noted `network required`, benchstat) shown as reference, not verified on this host | diff --git a/examples/47-go-toolbox/README.md b/examples/47-go-toolbox/README.md new file mode 100644 index 0000000..80c719c --- /dev/null +++ b/examples/47-go-toolbox/README.md @@ -0,0 +1,73 @@ +# 47 — go-toolbox + +A **single-language** example (Go only): the Go toolchain itself is the +subject, mirroring ch46's C++ toolbox. Every tool the chapter names asserts a +real, tool-produced effect against this module — never a bare exit code. + +- **`toolbox report`** — a deterministic FNV-1a digest over a fixed embedded + 16-byte payload, integer/string output only (no floats, addresses, timing, + or map iteration). The payload is byte-for-byte ch46's C++ payload, so both + chapters land on the identical digest `0x481984990deee5ff` — a + cross-appendix easter egg, not a coincidence. +- **`toolbox tools`** — prints `tools_generated.go`'s sorted table, proof + that `go generate` produced real, checkable output. +- **`toolbox defect divzero`** — deliberately panics with a runtime integer + divide-by-zero (narrative parity with ch46's UBSan-caught overflow). +- **`go generate`** (`internal/gen`, stdlib-only, `go/format`-clean) — + regenerates `tools_generated.go` byte-identical to the committed copy. +- **`gofmt`** vs **`gofumpt`** — `testdata/gofmt/messy.go` is gofmt-dirty; + `testdata/gofumpt/gofmt_ok.go` is gofmt-clean but gofumpt-dirty (a leading + blank line inside a block). +- **`go vet -tags vetdemo .`** — `vetdemo.go` (excluded from the default + build by its build tag) has a deliberate `Printf` format-verb mismatch. +- **`go tool pprof`** — `bench_test.go`'s `hotLoop` is a deliberately + dominant hot function; the gate asserts pprof names it, never a timing. +- **`golangci-lint`** / **`staticcheck`** — `smells.go` has unused-function + (`U1000`), dead-store (`SA4006`), and naming (`ST1003`) smells, never + called at runtime so they cannot affect the digest. +- **`delve`** — `go/.dlvinit` is a committed headless-batch script: break, + continue, print the digest field, quit. +- **`benchstat`** — `bench_test.go` also has a `b.RunParallel` benchmark for + a `-cpu=1` vs `-cpu=N` comparison (concurrency lens). + +## Host reality: hard core only, offline + +This example was built and verified on a host with **only `go` (1.26.5) +present** — `gofumpt`, `golangci-lint`, `staticcheck`, `govulncheck`, `dlv`, +and `benchstat` are all absent, and per this iteration's decision, none are +installed (no network, no `go install`). The main module is **stdlib-only** +(no `go.sum`) and builds fully offline. + +Gates A-E below are go-native and always run. Gates F, G, H, I, K +(gofumpt/golangci-lint/staticcheck/delve/benchstat) degrade to an +informational `SKIP: absent` on this host; a reader with the tools +installed exercises them for real. There is no `govulncheck` gate at all: it +needs network access to the Go vulnerability database and a deliberately +vulnerable dependency, both excluded here — the chapter covers it as +illustrative prose only, never gated, never committed. + +## Run it + +```bash +./demo.sh go build # stdlib only, no network +./demo.sh go run report # digest=0x481984990deee5ff +./demo.sh go run tools # the go-generate-produced table +./demo.sh go run defect divzero # panics on purpose (exit 2) + +go generate ./... && git diff --exit-code # idiomatic diff-clean check +gofmt -l $(find go -name '*.go' -not -path '*/testdata/*') # empty +go vet -tags vetdemo ./go/... # the seeded printf finding +``` + +## Verify + +`verify.lua` (Go only; skips other langs) asserts gates A-E for real and +prints an informational `SKIP:` for any of F, G, H, I, K whose tool is +absent from `PATH` — it never hard-fails or aborts on a missing optional +tool. + +```bash +LSP_LANG=go REPO_ROOT=$(cd ../.. && pwd) lua verify.lua +``` + +Mode: `local`. Stdlib only — no external modules, no `go.sum`. diff --git a/examples/47-go-toolbox/demo.sh b/examples/47-go-toolbox/demo.sh new file mode 100755 index 0000000..f5e5ecc --- /dev/null +++ b/examples/47-go-toolbox/demo.sh @@ -0,0 +1,25 @@ +#!/usr/bin/env bash +set -euo pipefail +cd "$(dirname "$0")" + +# Single-language example (Go only): the Go toolchain itself is the subject +# (go generate, gofmt/gofumpt, go vet, pprof, golangci-lint, staticcheck, +# delve, benchstat), so C++/Rust variants would have nothing to show. +langs=(go) + +case "${1:-all}" in + go) + shift + exec "./go/demo.sh" "$@" + ;; + all) + for lang in "${langs[@]}"; do "./$lang/demo.sh"; done + ;; + build) + for lang in "${langs[@]}"; do "./$lang/demo.sh" build; done + ;; + *) + echo "usage: $0 [go|all|build] [args...]" >&2 + exit 2 + ;; +esac diff --git a/examples/47-go-toolbox/go/.dlvinit b/examples/47-go-toolbox/go/.dlvinit new file mode 100644 index 0000000..45858bf --- /dev/null +++ b/examples/47-go-toolbox/go/.dlvinit @@ -0,0 +1,4 @@ +break main.go:33 +continue +print d.FNV +quit diff --git a/examples/47-go-toolbox/go/.golangci.yml b/examples/47-go-toolbox/go/.golangci.yml new file mode 100644 index 0000000..8efd4f5 --- /dev/null +++ b/examples/47-go-toolbox/go/.golangci.yml @@ -0,0 +1,23 @@ +# Reference golangci-lint config for ch47 (verify.lua gate G, if present). +# Absent on the reference host -- committed so a reader who installs +# golangci-lint gets a real, non-default lint pass, not just "add a config +# file" hand-waving. `unused` and `staticcheck` are on by default; `revive` +# and `unparam` are added explicitly, and testdata/ is excluded because those +# fixtures are gofmt/gofumpt targets, not lint targets. +version: "2" + +linters: + default: standard + enable: + - staticcheck + - unused + - revive + - unparam + + exclusions: + paths: + - testdata + +issues: + max-issues-per-linter: 0 + max-same-issues: 0 diff --git a/examples/47-go-toolbox/go/bench_test.go b/examples/47-go-toolbox/go/bench_test.go new file mode 100644 index 0000000..f4007d0 --- /dev/null +++ b/examples/47-go-toolbox/go/bench_test.go @@ -0,0 +1,45 @@ +package main + +import "testing" + +// hotLoop is a deliberately dominant hot function: pure integer arithmetic +// across a large fixed iteration count, with no function calls inside the +// loop for the profiler to attribute self-time to instead. It exists so +// `go tool pprof -top` reliably names "hotLoop" in the top few frames of a +// CPU profile taken from BenchmarkHotLoop, independent of host noise or +// exact timings -- the pprof gate (verify.lua gate E) asserts the NAME, not +// a duration. +func hotLoop(n int) uint64 { + var x uint64 = 0x9e3779b97f4a7c15 + for i := 0; i < n; i++ { + x ^= uint64(i) + x *= 6364136223846793005 + x = x<<13 | x>>51 + } + return x +} + +// hotLoopSink defeats dead-code elimination of hotLoop's result. +var hotLoopSink uint64 + +const hotLoopIters = 2_000_000 + +func BenchmarkHotLoop(b *testing.B) { + for i := 0; i < b.N; i++ { + hotLoopSink = hotLoop(hotLoopIters) + } +} + +// BenchmarkHotLoopParallel runs hotLoop from b.RunParallel, giving the +// concurrency-lens section (and a benchstat -cpu=1 vs -cpu=N comparison, +// see the chapter) something GOMAXPROCS-sensitive to compare against the +// serial BenchmarkHotLoop above. +func BenchmarkHotLoopParallel(b *testing.B) { + b.RunParallel(func(pb *testing.PB) { + var local uint64 + for pb.Next() { + local = hotLoop(hotLoopIters) + } + hotLoopSink = local + }) +} diff --git a/examples/47-go-toolbox/go/demo.sh b/examples/47-go-toolbox/go/demo.sh new file mode 100755 index 0000000..42dbf6e --- /dev/null +++ b/examples/47-go-toolbox/go/demo.sh @@ -0,0 +1,23 @@ +#!/usr/bin/env bash +set -euo pipefail +cd "$(dirname "$0")" +REPO_ROOT="$(cd ../../.. && pwd)" +BIN=bin/toolbox + +build() { + go build -o "$BIN" . +} + +run() { + if [[ -n "${TARGET:-}" ]]; then + exec "$REPO_ROOT/scripts/lab/deploy-to-vm.sh" "$TARGET" "$BIN" -- "$@" + fi + exec "./$BIN" "$@" +} + +case "${1:-}" in + build) build ;; + run) shift; run "$@" ;; + "") build; run report ;; + *) echo "usage: $0 [build|run [report|tools|defect divzero]]" >&2; exit 2 ;; +esac diff --git a/examples/47-go-toolbox/go/digest.go b/examples/47-go-toolbox/go/digest.go new file mode 100644 index 0000000..036e92a --- /dev/null +++ b/examples/47-go-toolbox/go/digest.go @@ -0,0 +1,36 @@ +package main + +// Digest wraps a single 64-bit FNV-1a hash value. Small on purpose: it +// exists so the delve chapter section (go/.dlvinit) has a concrete, +// non-trivial type to break on and print instead of a bare integer. +type Digest struct { + FNV uint64 +} + +const ( + fnvOffsetBasis uint64 = 0xcbf29ce484222325 + fnvPrime uint64 = 0x100000001b3 +) + +// kPayload is ch46's exact 16-byte payload ("The quick brown."), reused +// byte-for-byte so the Go and C++ toolbox chapters land on the identical +// FNV-1a digest (0x481984990deee5ff) -- a cross-appendix easter egg, not a +// coincidence. FNV-1a is language-independent: any conforming +// implementation over the same bytes produces the same 64-bit value. +var kPayload = [16]byte{ + 0x54, 0x68, 0x65, 0x20, 0x71, 0x75, 0x69, 0x63, 0x6b, + 0x20, 0x62, 0x72, 0x6f, 0x77, 0x6e, 0x2e, +} + +// fnv1a hashes data with the 64-bit FNV-1a algorithm. Integer/string-only +// output, no floats, addresses, timing, or map iteration -- the same input +// bytes produce the same digest bit-for-bit on every conforming Go +// toolchain, on every architecture, every run. +func fnv1a(data []byte) Digest { + h := fnvOffsetBasis + for _, b := range data { + h ^= uint64(b) + h *= fnvPrime + } + return Digest{FNV: h} +} diff --git a/examples/47-go-toolbox/go/go.mod b/examples/47-go-toolbox/go/go.mod new file mode 100644 index 0000000..1ad79f3 --- /dev/null +++ b/examples/47-go-toolbox/go/go.mod @@ -0,0 +1,5 @@ +module github.com/patterncatalyst/linux-systems-programming/examples/47-go-toolbox/go + +go 1.26 + +toolchain go1.26.5 diff --git a/examples/47-go-toolbox/go/internal/gen/main.go b/examples/47-go-toolbox/go/internal/gen/main.go new file mode 100644 index 0000000..3cd3221 --- /dev/null +++ b/examples/47-go-toolbox/go/internal/gen/main.go @@ -0,0 +1,76 @@ +// Command gen is the self-contained generator behind +// `//go:generate go run ./internal/gen` (see main.go). It has no external +// dependencies -- stdlib only -- and is invoked from the module root, so the +// working directory when it runs is the go/ module root itself: it writes +// tools_generated.go as a sibling of the //go:generate directive. +// +// Deterministic on purpose: the tool table below is keyed by name and +// deliberately listed out of order in source, but gen sorts the keys before +// rendering and passes the emitted source through go/format. Re-running the +// generator against unchanged input always reproduces the exact same bytes +// -- the property verify.lua's gate B (copy-aside, regenerate, diff) checks. +package main + +import ( + "fmt" + "go/format" + "os" + "sort" + "strings" +) + +// toolTable is the hand-maintained source of truth for `toolbox tools`. +// Keys are listed out of alphabetical order on purpose, to prove the +// generator -- not the author -- is what sorts them into generatedTools. +var toolTable = map[string]string{ + "staticcheck": "advanced static analysis and unused-code detection", + "gofmt": "format Go source files", + "go vet": "report suspicious constructs the compiler allows", + "delve": "the Go debugger (dlv)", + "go generate": "run source-code generators referenced by directive", + "gofumpt": "a stricter superset of gofmt", + "golangci-lint": "run many linters through one driver", + "pprof": "profile CPU, heap, and goroutine activity", + "benchstat": "compare statistical summaries of benchmark runs", + "govulncheck": "cross-reference dependencies against the Go vuln DB", +} + +const header = "// Code generated by internal/gen. DO NOT EDIT.\n\n" + +func render() ([]byte, error) { + names := make([]string, 0, len(toolTable)) + for name := range toolTable { + names = append(names, name) + } + sort.Strings(names) + + var b strings.Builder + b.WriteString(header) + b.WriteString("package main\n\n") + b.WriteString("// Tool describes one entry in the toolbox's tool table.\n") + b.WriteString("type Tool struct {\n") + b.WriteString("\tName string\n") + b.WriteString("\tRole string\n") + b.WriteString("}\n\n") + b.WriteString("// generatedTools is sorted by Name; see internal/gen/main.go.\n") + b.WriteString("var generatedTools = []Tool{\n") + for _, name := range names { + fmt.Fprintf(&b, "\t{Name: %q, Role: %q},\n", name, toolTable[name]) + } + b.WriteString("}\n") + + return format.Source([]byte(b.String())) +} + +func main() { + out, err := render() + if err != nil { + fmt.Fprintln(os.Stderr, "gen: format.Source:", err) + os.Exit(1) + } + if err := os.WriteFile("tools_generated.go", out, 0o644); err != nil { + fmt.Fprintln(os.Stderr, "gen: write tools_generated.go:", err) + os.Exit(1) + } + fmt.Fprintln(os.Stderr, "gen: wrote tools_generated.go") +} diff --git a/examples/47-go-toolbox/go/main.go b/examples/47-go-toolbox/go/main.go new file mode 100644 index 0000000..2577972 --- /dev/null +++ b/examples/47-go-toolbox/go/main.go @@ -0,0 +1,79 @@ +//go:generate go run ./internal/gen + +// toolbox -- the reference Go program for ch47 (go/toolchain version +// management, go generate discipline, gofmt vs gofumpt, go vet, pprof, +// golangci-lint/staticcheck config authoring, delve, benchstat). Go's analog +// of ch46's C++ toolbox: the Go toolchain itself is the subject. +// +// Subcommands: +// +// toolbox report -- deterministic FNV-1a digest over a fixed +// embedded payload, integer/string output +// only (no floats, addresses, timing, or map +// iteration) so the digest is reproducible. +// toolbox tools -- prints the go-generate-produced tool table, +// proof that `go generate` output is real and +// checkable, not merely "it ran". +// toolbox defect divzero -- deliberately triggers an integer +// divide-by-zero panic (delve/panic-recovery +// narrative parity with ch46's UBSan defect). +package main + +import ( + "fmt" + "os" +) + +func printUsage() { + fmt.Fprintln(os.Stderr, "usage: toolbox ") +} + +func cmdReport() int { + d := fnv1a(kPayload[:]) + fmt.Printf("toolbox report: payload_len=%d digest=0x%016x\n", len(kPayload), d.FNV) + return 0 +} + +func cmdTools() int { + fmt.Printf("tools: count=%d\n", len(generatedTools)) + for _, t := range generatedTools { + fmt.Printf("tools: %-13s -- %s\n", t.Name, t.Role) + } + return 0 +} + +func cmdDefectDivZero() int { + // `int32` variables (not compile-time constants) so the compiler cannot + // fold the division at build time -- the point is a *runtime* panic, + // not a compiler diagnostic. This one statement is the entire seeded + // defect. + var divisor int32 + dividend := int32(42) + fmt.Printf("toolbox defect divzero: dividend=%d divisor=%d\n", dividend, divisor) + os.Stdout.Sync() + result := dividend / divisor // runtime panic: integer divide by zero + fmt.Printf("unreachable: result=%d\n", result) + return 0 +} + +func main() { + if len(os.Args) < 2 { + printUsage() + os.Exit(2) + } + switch os.Args[1] { + case "report": + os.Exit(cmdReport()) + case "tools": + os.Exit(cmdTools()) + case "defect": + if len(os.Args) < 3 || os.Args[2] != "divzero" { + printUsage() + os.Exit(2) + } + os.Exit(cmdDefectDivZero()) + default: + printUsage() + os.Exit(2) + } +} diff --git a/examples/47-go-toolbox/go/smells.go b/examples/47-go-toolbox/go/smells.go new file mode 100644 index 0000000..2d7d66d --- /dev/null +++ b/examples/47-go-toolbox/go/smells.go @@ -0,0 +1,36 @@ +package main + +import "strconv" + +// smells.go collects deliberate, behavior-preserving smells for the +// if-present static-analysis gates (verify.lua gates G "golangci-lint" and +// H "staticcheck") and the chapter's "Errors, three ways" section. None of +// these functions is ever called at runtime -- they compile cleanly and +// have zero effect on `toolbox report`'s digest -- so they exist purely as +// designed-for targets for tools this host does not have installed. + +// unusedHelper is never called. staticcheck's U1000 ("unusedHelper is +// unused") and golangci-lint's "unused" linter both flag unreferenced +// unexported functions like this one. +func unusedHelper(n int) string { + return strconv.Itoa(n * 2) +} + +// deadStore is also never called (a second U1000 hit), and its body +// contains its own smell: the initial value assigned to x is overwritten +// before it is ever read. staticcheck's SA4006 ("this value of x is never +// used") targets exactly this pattern; go vet does not catch it because the +// variable itself is read eventually (just not the first value). +func deadStore() int { + x := 10 + x = 20 + return x +} + +// unused_smell_name violates Go naming conventions (mixedCaps, no +// underscores) on purpose. staticcheck's stylecheck companion, ST1003, +// flags underscored identifiers like this one; it is also never called, so +// it doubles as a third U1000 hit. +func unused_smell_name() int { + return 0 +} diff --git a/examples/47-go-toolbox/go/testdata/gofmt/messy.go b/examples/47-go-toolbox/go/testdata/gofmt/messy.go new file mode 100644 index 0000000..5aad008 --- /dev/null +++ b/examples/47-go-toolbox/go/testdata/gofmt/messy.go @@ -0,0 +1,15 @@ +package messy + +import "fmt" + +// messy.go is deliberately misformatted (irregular spacing, no gofmt-style +// alignment) so `gofmt -l` lists this file. It lives under testdata/, which +// the go tool ignores for build/vet/test purposes -- only gofmt is ever +// pointed at it directly, by name. +func Add(a,b int)int{ + return a+b +} + +func Greet( name string ) { +fmt.Println("hello,",name) +} diff --git a/examples/47-go-toolbox/go/testdata/gofumpt/gofmt_ok.go b/examples/47-go-toolbox/go/testdata/gofumpt/gofmt_ok.go new file mode 100644 index 0000000..2b76150 --- /dev/null +++ b/examples/47-go-toolbox/go/testdata/gofumpt/gofmt_ok.go @@ -0,0 +1,13 @@ +package gofmtok + +import "fmt" + +// gofmt_ok.go is gofmt-clean (gofmt -l prints nothing for this file) but +// gofumpt-dirty: gofumpt additionally forbids a blank line at the start of +// a block, which Greet's body has. It lives under testdata/, which the go +// tool ignores for build/vet/test -- only gofmt/gofumpt are ever pointed at +// it directly, by name. +func Greet(name string) { + + fmt.Println("hello,", name) +} diff --git a/examples/47-go-toolbox/go/tools_generated.go b/examples/47-go-toolbox/go/tools_generated.go new file mode 100644 index 0000000..f5a88e5 --- /dev/null +++ b/examples/47-go-toolbox/go/tools_generated.go @@ -0,0 +1,23 @@ +// Code generated by internal/gen. DO NOT EDIT. + +package main + +// Tool describes one entry in the toolbox's tool table. +type Tool struct { + Name string + Role string +} + +// generatedTools is sorted by Name; see internal/gen/main.go. +var generatedTools = []Tool{ + {Name: "benchstat", Role: "compare statistical summaries of benchmark runs"}, + {Name: "delve", Role: "the Go debugger (dlv)"}, + {Name: "go generate", Role: "run source-code generators referenced by directive"}, + {Name: "go vet", Role: "report suspicious constructs the compiler allows"}, + {Name: "gofmt", Role: "format Go source files"}, + {Name: "gofumpt", Role: "a stricter superset of gofmt"}, + {Name: "golangci-lint", Role: "run many linters through one driver"}, + {Name: "govulncheck", Role: "cross-reference dependencies against the Go vuln DB"}, + {Name: "pprof", Role: "profile CPU, heap, and goroutine activity"}, + {Name: "staticcheck", Role: "advanced static analysis and unused-code detection"}, +} diff --git a/examples/47-go-toolbox/go/vetdemo.go b/examples/47-go-toolbox/go/vetdemo.go new file mode 100644 index 0000000..2ca495e --- /dev/null +++ b/examples/47-go-toolbox/go/vetdemo.go @@ -0,0 +1,14 @@ +//go:build vetdemo + +package main + +import "fmt" + +// vetdemo.go is excluded from the default build/test (`go build ./...`, +// `go test ./...`) by the vetdemo build tag above. It exists only so +// `go vet -tags vetdemo .` has something real to report: printBadFormat's +// Printf call passes a string argument to a %d verb, a stable "printf" +// finding go vet's printf analyzer always reports for this exact mismatch. +func printBadFormat() { + fmt.Printf("bad format: %d\n", "not-an-int") +} diff --git a/examples/47-go-toolbox/verify.lua b/examples/47-go-toolbox/verify.lua new file mode 100644 index 0000000..7e4b566 --- /dev/null +++ b/examples/47-go-toolbox/verify.lua @@ -0,0 +1,213 @@ +-- Verify 47-go-toolbox (Go only): the Go toolchain itself is the subject -- +-- go/toolchain version pinning, go generate, gofmt/gofumpt, go vet, pprof, +-- golangci-lint/staticcheck config authoring, delve, benchstat. Go's analog +-- of ch46's C++ toolbox. Every assertion below checks a real, tool-produced +-- effect, never merely a process exit code. +-- +-- Hard-gated (A-E): go-native, deterministic, offline, always run on any +-- host with just `go` installed. +-- A. go.mod pins "go 1.26" + "toolchain go1.26.5"; `toolbox report` (an +-- integer/string-only FNV-1a digest) equals a known literal +-- (0x481984990deee5ff -- the same value as ch46's C++ toolbox, since +-- both reuse the identical 16-byte payload). +-- B. `//go:generate go run ./internal/gen` regenerates tools_generated.go +-- byte-identical to the committed copy. Checked without git: the +-- committed file is copied aside, regenerated, diffed against the +-- saved copy (must be empty), then restored so the working tree is +-- never left dirty by this check. `toolbox tools` output (the +-- generated table) is also asserted against a literal. +-- C. `gofmt -l` is empty across every tracked .go file, and non-empty on +-- the deliberately misformatted testdata/gofmt/messy.go fixture. +-- D. `go vet -tags vetdemo .` reports the stable "printf" finding from +-- vetdemo.go's deliberate %d/string mismatch (a build-tagged file +-- excluded from the default build/test). +-- E. `go test -bench -cpuprofile` + `go tool pprof -top` names the +-- deliberately dominant hotLoop function in the top CPU-profile +-- frames. The gate is the NAME, never a timing. +-- +-- Gated-if-present (F, G, H, I, K): this host has none of gofumpt, +-- golangci-lint, staticcheck, delve, or benchstat installed (offline +-- constraint -- no `go install`, no network). Each gate degrades to an +-- informational "SKIP: absent" print, never a checks.skip() (which +-- would abort the whole script) and never a hard FAIL -- A-E must still run +-- regardless. A reader who has these tools installed exercises the real +-- gate. No govulncheck gate: it needs network access to the Go vulnerability +-- database and a deliberately vulnerable dependency, both excluded by this +-- example's offline, stdlib-only, no-committed-vulnerability constraints; +-- the chapter covers govulncheck as illustrative prose only. + +local script_dir = arg[0]:match("(.*/)") or "./" +local repo_root = os.getenv("REPO_ROOT") or (script_dir .. "../..") +package.path = package.path .. ";" .. repo_root .. "/scripts/lib/?.lua" +local checks = require("checks") + +local lang = os.getenv("LSP_LANG") +if lang ~= "go" then + checks.skip("47-go-toolbox is Go-only (LSP_LANG=" .. tostring(lang) .. ")") +end + +-- Escape a literal string for use inside a Lua pattern (checks.expect_match +-- takes a pattern, not a plain substring). +local function lit(s) + return (s:gsub("([%(%)%.%%%+%-%*%?%[%]%^%$])", "%%%1")) +end + +local function tool_present(cmd) + return checks.run("command -v " .. cmd .. " >/dev/null 2>&1").exit == 0 +end + +-- ── A. toolchain pin + deterministic digest ────────────────────────────── + +local b = checks.run("./demo.sh go build") +checks.expect_exit(b, 0, "go: builds (stdlib only, no network)") + +local gomod = checks.run("cat go/go.mod") +checks.expect_match(gomod.out, "\ngo 1%.26\n", "go.mod: pins \"go 1.26\"") +checks.expect_match(gomod.out, "toolchain go1%.26%.5", "go.mod: pins \"toolchain go1.26.5\"") + +local EXPECTED_REPORT = "toolbox report: payload_len=16 digest=0x481984990deee5ff" + +local report = checks.run("./demo.sh go run report") +checks.expect_exit(report, 0, "go: toolbox report runs") +checks.expect_match(report.out, lit(EXPECTED_REPORT), + "go: toolbox report equals the expected literal (matches ch46's C++ digest)") + +-- ── B. go generate diff-clean + generated-table literal ────────────────── + +local gen_check = [[ +cd go +tmp=$(mktemp) +cp tools_generated.go "$tmp" +go generate ./... >/dev/null 2>&1 +diff "$tmp" tools_generated.go +status=$? +cp "$tmp" tools_generated.go +rm -f "$tmp" +exit $status +]] +local gen = checks.run(gen_check) +checks.expect_exit(gen, 0, + "go: go generate ./... regenerates tools_generated.go byte-identical to committed") + +local EXPECTED_TOOLS_HEAD = "tools: count=10" +local EXPECTED_TOOLS_LINE = "tools: gofmt -- format Go source files" + +local tools = checks.run("./demo.sh go run tools") +checks.expect_exit(tools, 0, "go: toolbox tools runs") +checks.expect_match(tools.out, lit(EXPECTED_TOOLS_HEAD), + "go: toolbox tools reports the generated table's count") +checks.expect_match(tools.out, lit(EXPECTED_TOOLS_LINE), + "go: toolbox tools includes a generated, sorted table entry") + +-- ── C. gofmt ────────────────────────────────────────────────────────────── + +local fmt_tracked = checks.run( + "cd go && gofmt -l $(find . -name '*.go' -not -path './testdata/*')") +checks.expect_exit(fmt_tracked, 0, "go: gofmt -l exits 0 on tracked sources") +checks.expect_match(fmt_tracked.out, "^%s*$", + "go: gofmt -l prints nothing for tracked sources") + +local fmt_fixture = checks.run("cd go && gofmt -l testdata/gofmt/messy.go") +checks.expect_match(fmt_fixture.out, "testdata/gofmt/messy%.go", + "go: gofmt -l flags the deliberately misformatted fixture") + +-- ── D. go vet (build-tagged printf mismatch) ───────────────────────────── + +local vet = checks.run("cd go && go vet -tags vetdemo . 2>&1") +checks.expect_match(vet.out, "Printf format %%d has arg .* of wrong type string", + "go: go vet -tags vetdemo reports a printf finding") +checks.expect_match(vet.out, "vetdemo%.go:%d+", "go: the printf finding is located in vetdemo.go") + +-- ── E. pprof (structural: the hot function's NAME, not a timing) ──────── + +local pprof_check = [[ +cd go +tmpd=$(mktemp -d) +go test -bench=. -run=^$ -cpuprofile="$tmpd/cpu.prof" -o "$tmpd/toolbox.test" . >/dev/null +go tool pprof -top -nodecount=15 "$tmpd/toolbox.test" "$tmpd/cpu.prof" +status=$? +rm -rf "$tmpd" +exit $status +]] +local pprof = checks.run(pprof_check) +checks.expect_exit(pprof, 0, "go: go test -bench -cpuprofile + go tool pprof -top run cleanly") +checks.expect_match(pprof.out, "hotLoop", "go: pprof -top names hotLoop in the CPU-profile top frames") + +-- ── F. gofumpt (skip-if-absent) ────────────────────────────────────────── + +if tool_present("gofumpt") then + local fumpt = checks.run("cd go && gofumpt -l testdata/gofumpt/gofmt_ok.go") + checks.expect_match(fumpt.out, "testdata/gofumpt/gofmt_ok%.go", + "go: gofumpt -l flags the gofmt-clean/gofumpt-dirty fixture") +else + print("SKIP: gofumpt not found on PATH -- gate F not asserted") +end + +-- ── G. golangci-lint (skip-if-absent) ──────────────────────────────────── + +if tool_present("golangci-lint") then + local lintr = checks.run("cd go && golangci-lint run ./... 2>&1") + checks.expect_match(lintr.out, "%(unused%)", + "go: golangci-lint flags smells.go's unused functions via the \"unused\" linter") +else + print("SKIP: golangci-lint not found on PATH -- gate G not asserted") +end + +-- ── H. staticcheck (skip-if-absent) ────────────────────────────────────── + +if tool_present("staticcheck") then + local sc = checks.run("cd go && staticcheck ./... 2>&1") + checks.expect_match(sc.out, "U1000", "go: staticcheck flags smells.go's unused functions (U1000)") + checks.expect_match(sc.out, "SA4006", "go: staticcheck flags deadStore's dead store (SA4006)") +else + print("SKIP: staticcheck not found on PATH -- gate H not asserted") +end + +-- ── I. delve headless batch via .dlvinit (skip-if-absent) ──────────────── + +if tool_present("dlv") then + local dlv_check = [[ +cd go +tmp=$(mktemp) +go build -gcflags=all="-N -l" -o "$tmp" . +dlv exec "$tmp" --init .dlvinit -- report +status=$? +rm -f "$tmp" +exit $status +]] + local dlv = checks.run(dlv_check) + checks.expect_exit(dlv, 0, "go: dlv headless batch via .dlvinit runs cleanly") + checks.expect_match(dlv.out, "5195329438047200767", + "go: dlv prints the digest as a plain decimal (== 0x481984990deee5ff)") +else + print("SKIP: dlv (delve) not found on PATH -- gate I not asserted") +end + +-- ── K. benchstat (skip-if-absent; table STRUCTURE only, timings shown-not-gated) ── + +if tool_present("benchstat") then + local bench_check = [[ +cd go +a=$(mktemp) +c=$(mktemp) +go test -bench=BenchmarkHotLoop -run=^$ -count=5 . > "$a" +go test -bench=BenchmarkHotLoop -run=^$ -count=5 . > "$c" +benchstat "$a" "$c" +status=$? +rm -f "$a" "$c" +exit $status +]] + local bs = checks.run(bench_check) + checks.expect_exit(bs, 0, "go: benchstat compares two BenchmarkHotLoop runs cleanly") + checks.expect_match(bs.out, "sec/op", "go: benchstat emits a sec/op comparison table") + checks.expect_match(bs.out, "HotLoop", "go: benchstat's table names BenchmarkHotLoop") +else + print("SKIP: benchstat not found on PATH -- gate K not asserted") +end + +-- ── govulncheck: no gate (network + vuln dep both excluded; prose only) ── + +print("info: govulncheck not gated -- offline/no-committed-vulnerability constraints" .. + " (see chapter for the illustrative advisory workflow)") + +checks.finish() diff --git a/examples/manifest.yaml b/examples/manifest.yaml index 5635919..d87c846 100644 --- a/examples/manifest.yaml +++ b/examples/manifest.yaml @@ -193,3 +193,7 @@ examples: langs: [cpp] mode: local timeout: 420 + - id: 47-go-toolbox + langs: [go] + mode: local + timeout: 480 From 21d721b48c645e26547d380912f0e3ed128d35f9 Mon Sep 17 00:00:00 2001 From: PatternCatalyst Date: Mon, 3 Aug 2026 16:31:48 -0400 Subject: [PATCH 3/3] =?UTF-8?q?docs(r16):=20the=20Go=20toolbox=20=E2=80=94?= =?UTF-8?q?=20chapter=2047=20(Appendices:=20Tooling)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit go toolchain/version mgmt, go generate diff-clean discipline, gofmt vs gofumpt, .golangci.yml/staticcheck authoring, govulncheck workflow, delve configs, pprof/benchstat. Verified go-native core (PASS 16/0, offline); 6 marquee tools shown-as-reference (absent on host). Relay Phase-3 SHIP 12/12. --- _docs/47-go-toolbox.md | 983 ++++++++++++++++++++++++++++++++++++++++ _plans/r16-ch47-plan.md | 11 +- 2 files changed, 991 insertions(+), 3 deletions(-) create mode 100644 _docs/47-go-toolbox.md diff --git a/_docs/47-go-toolbox.md b/_docs/47-go-toolbox.md new file mode 100644 index 0000000..f721d70 --- /dev/null +++ b/_docs/47-go-toolbox.md @@ -0,0 +1,983 @@ +--- +title: "The Go toolbox: go.mod toolchain pins, go generate discipline, and the pprof-to-benchstat workflow" +order: 47 +part: "Appendices: Tooling" +description: "go-toolbox is one Go binary and the toolchain wrapped around it -- go.mod's go/toolchain directives resolved through GOTOOLCHAIN, a self-contained go generate pipeline producing a DO-NOT-EDIT tool table, and gofmt/go vet/pprof as go-native hard gates -- with committed configs for gofumpt, golangci-lint, staticcheck, delve, and benchstat shown as reference but absent on the reference host. Verified on the Fedora 44 host: verify.lua PASS 16/FAIL 0 offline, toolbox report digest=0x481984990deee5ff (byte-identical to ch46's C++ digest), go generate regenerating tools_generated.go byte-for-byte, go vet -tags vetdemo catching a printf mismatch at vetdemo.go:13, and go tool pprof -top naming hotLoop." +duration: "50 minutes" +--- + +Chapter 46 turned all the way around on C++: one language, one small binary, +and every tool that touches it before it ever runs — two compilers, a +build-system generator, a package manager, a static analyzer, a debugger +taught a custom type. Go gets the identical treatment here, and the shape of +the problem is the mirror image of C++'s. Where `toolbox` needed seven named +`CMakePresets.json` configurations just to make "which compiler, which build +type" an explicit choice, Go ships one command, `go build`, and pins its own +version inside the module that needs it. That difference does not mean Go has +nothing left to say about tooling — it means the depth moves somewhere else: +into `go.mod`'s own toolchain directives, into `go generate` as a first-class +source-of-truth discipline, into what a formatter versus a deeper static +analyzer versus a debugger each choose to notice about the identical source. +`toolbox` (the Go one) is a single stdlib-only binary, engineered the same +way its C++ sibling was — every tool pointed at it has something concrete to +catch or confirm, never just a clean exit. + +{% include excalidraw.html + file="47-go-toolchain-pipeline" + alt="A go.mod box showing the go 1.26 and toolchain go1.26.5 directives feeds through a GOTOOLCHAIN resolution step into the go binary. From the go binary, two arrows fan out: one into an amber toolbox report box that computes an FNV-1a digest over a fixed embedded payload and prints digest=0x481984990deee5ff, the other into an amber go generate box that runs internal/gen against a hand-maintained tool table and diffs its output against the committed tools_generated.go, landing in a diff-empty gate. Both boxes are labeled go-native, verified offline on this host." + caption="Figure 47.1 — the Go toolchain and version-management flow: go.mod's go/toolchain directives resolve through GOTOOLCHAIN into the go binary, which drives the deterministic build (report digest) and the go-generate diff-clean gate" %} + +> **Tools used** — `go` (host; `build`/`run`/`generate`/`vet`/`tool +> pprof`/`fmt` all ship inside the single `go` binary, which +> `scripts/check-host.sh` gates as a hard requirement via its `go 1.26.x` +> check), `gofmt` (host; ships alongside `go`, not separately gated). +> `golangci-lint`, `staticcheck`, and `dlv` are warn-only entries in +> `scripts/check-host.sh` ("nice to have locally"); `gofumpt`, `govulncheck`, +> and `benchstat` are not gated by it at all. All six of those — +> `gofumpt`, `golangci-lint`, `staticcheck`, `govulncheck`, `dlv`, and +> `benchstat` — are absent on this reference host, so their sections below +> are shown as reference, not verified. No VM, no root, no LGTM stack — +> `examples/47-go-toolbox` is `mode: local` in `examples/manifest.yaml`. + +Because the Go toolchain is itself the subject, `examples/47-go-toolbox/` +ships `langs: [go]` only, the same way Chapter 44's Go-runtime chapter and +Chapter 46's C++ chapter each stayed inside one language — a C++ or Rust +build would have nothing new to say about a `go.mod` toolchain directive or a +`.golangci.yml`. Every code block below is a plain fenced `go`/`console`/ +`yaml` block; there is no `codetabs` include to reach for when only one +language is in the room. + +## Go toolchain and version management + +`go/go.mod` is four lines, and two of them are the whole subject of this +section: + +``` +module github.com/patterncatalyst/linux-systems-programming/examples/47-go-toolbox/go + +go 1.26 + +toolchain go1.26.5 +``` + +`go 1.26` and `toolchain go1.26.5` answer two different questions that look +like the same question. `go 1.26` is a **language-version floor**: it tells +every tool that reads this module (the compiler, `go vet`, an IDE's language +server) which Go language and standard-library semantics this source relies +on — it is the same directive C++'s `CMAKE_CXX_STANDARD` or Rust's `edition` +line answers, a promise about the language, not the binary that compiles it. +`toolchain go1.26.5` is a stricter, separate promise: the exact `go` command +release this module was developed and verified against. The `go` command +itself reads that second line and decides, via the `GOTOOLCHAIN` environment +variable (default `auto`), whether it can proceed with the toolchain already +on `PATH` or needs to fetch a different one. If the installed `go` binary's +own version already satisfies the `toolchain` line — which it does here, +`go1.26.5` on `PATH` matching `toolchain go1.26.5` exactly — resolution stops +immediately with no network access at all. Only when the installed binary is +*older* than the pinned toolchain does `GOTOOLCHAIN=auto` reach out to the Go +module proxy and download a newer one; `GOTOOLCHAIN=local` disables that +fallback entirely and fails instead of fetching. That is the property this +whole example leans on to stay offline: `go.mod`'s toolchain directive is not +an aspiration a reader has to satisfy by hand, it is a pin the `go` command +itself enforces, and on this host it resolves to the binary already +installed without a single byte crossing the network. + +That is also the cleanest point of contrast with the two sibling toolchain +chapters. C++ has no equivalent single-file pin — Chapter 46 needed seven +named `CMakePresets.json` configurations plus a Conan lockfile to make +"which compiler, which build type" and "which exact package revision" +explicit, because C++ leaves compiler choice and dependency resolution as +separate decisions a project has to wire up itself. Rust's `edition` (in +`Cargo.toml`) and `rust-toolchain.toml`'s `channel` line are close cousins of +Go's `go`/`toolchain` split — a language-edition floor plus an exact +toolchain pin — but Rust's toolchain file additionally names `components` +(`rustfmt`, `clippy`) as part of the same pin. Go keeps the two directives to +exactly two lines inside the module a reader already has open, and — as the +rest of this chapter shows — treats every other tool (`gofmt`, `vet`, +`pprof`) as already living inside that one pinned binary rather than needing +a components list of its own. + +## Deterministic build and digest + +`toolbox report` asks the same falsifiable question `toolbox` (C++) did: +does a fixed input, hashed the same way, always produce the same output? The +type and the algorithm are both intentionally uninteresting: + +```go +package main + +// Digest wraps a single 64-bit FNV-1a hash value. Small on purpose: it +// exists so the delve chapter section (go/.dlvinit) has a concrete, +// non-trivial type to break on and print instead of a bare integer. +type Digest struct { + FNV uint64 +} + +const ( + fnvOffsetBasis uint64 = 0xcbf29ce484222325 + fnvPrime uint64 = 0x100000001b3 +) + +// kPayload is ch46's exact 16-byte payload ("The quick brown."), reused +// byte-for-byte so the Go and C++ toolbox chapters land on the identical +// FNV-1a digest (0x481984990deee5ff) -- a cross-appendix easter egg, not a +// coincidence. FNV-1a is language-independent: any conforming +// implementation over the same bytes produces the same 64-bit value. +var kPayload = [16]byte{ + 0x54, 0x68, 0x65, 0x20, 0x71, 0x75, 0x69, 0x63, 0x6b, + 0x20, 0x62, 0x72, 0x6f, 0x77, 0x6e, 0x2e, +} +``` + +`fnv1a` is nine lines and touches nothing but integers: + +```go +// fnv1a hashes data with the 64-bit FNV-1a algorithm. Integer/string-only +// output, no floats, addresses, timing, or map iteration -- the same input +// bytes produce the same digest bit-for-bit on every conforming Go +// toolchain, on every architecture, every run. +func fnv1a(data []byte) Digest { + h := fnvOffsetBasis + for _, b := range data { + h ^= uint64(b) + h *= fnvPrime + } + return Digest{FNV: h} +} +``` + +`cmdReport` prints only what `fnv1a` computed: + +```go +func cmdReport() int { + d := fnv1a(kPayload[:]) + fmt.Printf("toolbox report: payload_len=%d digest=0x%016x\n", len(kPayload), d.FNV) + return 0 +} +``` + +Run for real on this host: + +```console +$ ./demo.sh go run report +toolbox report: payload_len=16 digest=0x481984990deee5ff +``` + +`digest=0x481984990deee5ff` is not a coincidence shared with Chapter 46 — it +is the same 16-byte payload, hashed by the same 64-bit FNV-1a algorithm, +computed by an entirely different compiler and runtime. FNV-1a has no +floating-point rounding, no pointer values, and no unordered-container +iteration to disagree about; two conforming implementations over identical +bytes are required to agree on every bit of the output, which is exactly why +Go's `toolbox report` and C++'s `toolbox report` land on the identical +digest even though nothing about their toolchains, calling conventions, or +runtimes has anything in common. Worth one sentence, not a whole section: +that agreement is a real cross-appendix check, not a repeated literal typed +twice by hand. + +## `go generate` in depth + +`go generate` is Go's answer to "keep a derived file accurate against its +source of truth" — it runs a directive comment, once, on demand, and never as part +of `go build`. `main.go`'s directive is one line at the very top of the +file: + +```go +//go:generate go run ./internal/gen +``` + +`internal/gen/main.go` is the generator that directive names, and it is +deliberately self-contained: no third-party dependency, stdlib only, so +`go generate ./...` never touches the network any more than the rest of this +module does. Its source of truth is a hand-maintained map, listed +**out of alphabetical order on purpose**: + +```go +// toolTable is the hand-maintained source of truth for `toolbox tools`. +// Keys are listed out of alphabetical order on purpose, to prove the +// generator -- not the author -- is what sorts them into generatedTools. +var toolTable = map[string]string{ + "staticcheck": "advanced static analysis and unused-code detection", + "gofmt": "format Go source files", + "go vet": "report suspicious constructs the compiler allows", + "delve": "the Go debugger (dlv)", + "go generate": "run source-code generators referenced by directive", + "gofumpt": "a stricter superset of gofmt", + "golangci-lint": "run many linters through one driver", + "pprof": "profile CPU, heap, and goroutine activity", + "benchstat": "compare statistical summaries of benchmark runs", + "govulncheck": "cross-reference dependencies against the Go vuln DB", +} +``` + +Go's built-in `map` type has no guaranteed iteration order — reading +`toolTable` twice in the same process can visit its keys in two different +sequences — so `render` sorts the keys itself before writing anything, and +passes the assembled source through `go/format` before it ever touches disk: + +```go +func render() ([]byte, error) { + names := make([]string, 0, len(toolTable)) + for name := range toolTable { + names = append(names, name) + } + sort.Strings(names) + + var b strings.Builder + b.WriteString(header) + b.WriteString("package main\n\n") + // ... struct + slice literal built from the sorted names ... + return format.Source([]byte(b.String())) +} +``` + +`sort.Strings` plus `format.Source` together are what make re-running the +generator against unchanged input reproduce the *exact same bytes* every +time — no map-iteration nondeterminism, no formatting drift from one Go +release to the next. The committed output, `tools_generated.go`, opens with +the header every regeneration writes unchanged: + +```go +// Code generated by internal/gen. DO NOT EDIT. + +package main + +// Tool describes one entry in the toolbox's tool table. +type Tool struct { + Name string + Role string +} + +// generatedTools is sorted by Name; see internal/gen/main.go. +var generatedTools = []Tool{ + {Name: "benchstat", Role: "compare statistical summaries of benchmark runs"}, + {Name: "delve", Role: "the Go debugger (dlv)"}, +``` + +`// Code generated by internal/gen. DO NOT EDIT.` is Go tooling's own +convention (`gofmt`, IDEs, and code-review bots all recognize this exact +comment shape) for marking a file as derived rather than authored — a +human editing `tools_generated.go` directly is fixing the wrong file, since +the next `go generate` run silently overwrites the edit. `cmdTools` reads +that slice and prints it: + +```console +$ ./demo.sh go run tools +tools: count=10 +tools: gofmt -- format Go source files +``` + +That is a real, run transcript, not the full ten-line table — this chapter +only quotes the two lines `verify.lua` pins as literals (the count and one +sorted entry); the other eight rows are the same `%-13s -- %s` format +applied to the remaining names in `toolTable`, sorted. + +The gate that matters is not "did the generator run", it is "did the +generator's output change anything" — the discipline a reader would wire +into CI as `go generate ./... && git diff --exit-code`. `verify.lua` +enforces the same property without assuming a git checkout to diff against, +by copying the committed file aside, regenerating, diffing the copy against +the fresh output, then restoring the original so the working tree is never +left dirty by the check itself: + +```lua +local gen_check = [[ +cd go +tmp=$(mktemp) +cp tools_generated.go "$tmp" +go generate ./... >/dev/null 2>&1 +diff "$tmp" tools_generated.go +status=$? +cp "$tmp" tools_generated.go +rm -f "$tmp" +exit $status +]] +local gen = checks.run(gen_check) +checks.expect_exit(gen, 0, + "go: go generate ./... regenerates tools_generated.go byte-identical to committed") +``` + +Run for real, both directions agree: the copy-aside diff is empty, and the +idiomatic form a reader would actually put in CI — +`go generate ./... && git diff --exit-code` — exits 0 on this checkout too. +Either way, the claim is the same one Chapter 46 made about GCC-vs-clang +parity, aimed at a different kind of determinism: not "two compilers agree," +but "the generator, run twice against unchanged input, agrees with itself." + +## `gofmt` vs `gofumpt` + +`gofmt` is part of the `go` binary itself — there is no separate install, no +version to pin, and no config file: it applies one fixed layout and either +a file already matches it or `gofmt -l` prints the file's name. Silence is +success, which makes a clean run easy to overlook and a dirty one impossible +to miss. `go/testdata/gofmt/messy.go` exists specifically to be listed: + +```go +package messy + +import "fmt" + +// messy.go is deliberately misformatted (irregular spacing, no gofmt-style +// alignment) so `gofmt -l` lists this file. It lives under testdata/, which +// the go tool ignores for build/vet/test purposes -- only gofmt is ever +// pointed at it directly, by name. +func Add(a,b int)int{ + return a+b +} + +func Greet( name string ) { +fmt.Println("hello,",name) +} +``` + +`testdata/` is the load-bearing detail: Go's own tooling (`go build`, +`go vet`, `go test`) ignores any directory literally named `testdata` when +walking a module, so `messy.go` never becomes part of the compiled binary, +never gets vetted, and never affects `toolbox report`'s digest — it exists +purely as a target `gofmt` is pointed at *by name*. Run against both the +tracked sources and this fixture, the contrast is exact: + +```console +$ gofmt -l $(find . -name '*.go' -not -path './testdata/*') + +$ gofmt -l testdata/gofmt/messy.go +testdata/gofmt/messy.go +``` + +`gofumpt` is a stricter superset — it enforces every rule `gofmt` does, plus +a handful more that `gofmt` deliberately leaves alone, one of which is a +banned leading blank line at the start of a block. `testdata/gofumpt/gofmt_ok.go` +is built to sit exactly on that boundary: `gofmt`-clean, `gofumpt`-dirty. + +```go +package gofmtok + +import "fmt" + +// gofmt_ok.go is gofmt-clean (gofmt -l prints nothing for this file) but +// gofumpt-dirty: gofumpt additionally forbids a blank line at the start of +// a block, which Greet's body has. It lives under testdata/, which the go +// tool ignores for build/vet/test -- only gofmt/gofumpt are ever pointed at +// it directly, by name. +func Greet(name string) { + + fmt.Println("hello,", name) +} +``` + +`gofumpt` is absent on this reference host, so its half of the contrast is +shown, not verified: `gofumpt -l testdata/gofumpt/gofmt_ok.go` is the +designed-for command, and `verify.lua`'s gate F would assert exactly that +file name back if the tool were installed. `gofmt -l` on the same file +prints nothing — that half of the pair *is* verified above, since `gofmt` +ships with `go` itself. + +## `golangci-lint` config authoring + +`golangci-lint` runs many linters, including `staticcheck` itself, behind +one driver and one config file, so authoring that file is most of the work +of adopting it. `go/.golangci.yml` is committed in full: + +```yaml +# Reference golangci-lint config for ch47 (verify.lua gate G, if present). +# Absent on the reference host -- committed so a reader who installs +# golangci-lint gets a real, non-default lint pass, not just "add a config +# file" hand-waving. `unused` and `staticcheck` are on by default; `revive` +# and `unparam` are added explicitly, and testdata/ is excluded because those +# fixtures are gofmt/gofumpt targets, not lint targets. +version: "2" + +linters: + default: standard + enable: + - staticcheck + - unused + - revive + - unparam + + exclusions: + paths: + - testdata + +issues: + max-issues-per-linter: 0 + max-same-issues: 0 +``` + +`linters.default: standard` opts into golangci-lint v2's own curated +default set (which already includes `staticcheck` and `unused`); `enable` +lists them again explicitly alongside `revive` and `unparam` so the config +reads as a complete, intentional list rather than "whatever the default +happens to include this release." `exclusions.paths: [testdata]` is the +same isolation `gofmt`/`gofumpt` rely on, applied to linting: the fixtures +under `testdata/` are deliberately dirty for *other* tools and would be +noise here. `issues.max-issues-per-linter: 0` and `max-same-issues: 0` +both mean "no cap" — every finding is reported, not truncated after the +default handful, since this config exists to show every smell `smells.go` +was written to trigger. + +`golangci-lint` is absent on this reference host, so its gate is shown, not +run: the designed-for command is `golangci-lint run ./...`, and `verify.lua` +gate G asserts the string `(unused)` appears in its output — golangci-lint's +own convention of suffixing each finding with the linter name that raised +it, in parentheses. `smells.go`'s three unreferenced functions (below) are +exactly what the `unused` linter — one of the two in `linters.default: +standard` this config keeps on — is designed to flag. + +## `staticcheck` + +`staticcheck` reads more of a program's data flow than `go vet` does, and +`go/smells.go` exists purely to give it (and `golangci-lint`'s bundled copy +of it) real targets — three functions, never called anywhere, each with its +own distinct smell: + +```go +package main + +import "strconv" + +// smells.go collects deliberate, behavior-preserving smells for the +// if-present static-analysis gates (verify.lua gates G "golangci-lint" and +// H "staticcheck") and the chapter's "Errors, three ways" section. None of +// these functions is ever called at runtime -- they compile cleanly and +// have zero effect on `toolbox report`'s digest -- so they exist purely as +// designed-for targets for tools this host does not have installed. + +// unusedHelper is never called. staticcheck's U1000 ("unusedHelper is +// unused") and golangci-lint's "unused" linter both flag unreferenced +// unexported functions like this one. +func unusedHelper(n int) string { + return strconv.Itoa(n * 2) +} + +// deadStore is also never called (a second U1000 hit), and its body +// contains its own smell: the initial value assigned to x is overwritten +// before it is ever read. staticcheck's SA4006 ("this value of x is never +// used") targets exactly this pattern; go vet does not catch it because the +// variable itself is read eventually (just not the first value). +func deadStore() int { + x := 10 + x = 20 + return x +} + +// unused_smell_name violates Go naming conventions (mixedCaps, no +// underscores) on purpose. staticcheck's stylecheck companion, ST1003, +// flags underscored identifiers like this one; it is also never called, so +// it doubles as a third U1000 hit. +func unused_smell_name() int { + return 0 +} +``` + +Three functions, three distinct designed-for findings, none of them +overlapping: `unusedHelper` (line 15) is simply dead code — **U1000**, +staticcheck's unused-declaration check. `deadStore` (line 24) is dead *and* +its first assignment (`x := 10`) is overwritten before ever being read — +**U1000** again for the whole function, plus **SA4006** for the specific +overwritten value, a pattern `go vet` does not catch because `x` genuinely +is read eventually, just not at its first value. `unused_smell_name` +(line 34) is dead a third time (a third **U1000**) and also violates Go's +`mixedCaps` naming convention on its own — **ST1003**, staticcheck's +`stylecheck` companion. None of the three is ever referenced from `main.go` +or anywhere else, so all three compile cleanly and none of them can ever +touch `toolbox report`'s digest, no matter how they are edited. + +`staticcheck` is absent on this reference host, so these are the checks it +is designed to report, quoted from what the tool's own documentation names +them — not a captured run. `verify.lua` gate H asserts the literal tokens +`U1000` and `SA4006` would appear in `staticcheck ./...`'s output if the +tool were present; it does not assert `ST1003`, since that finding comes +from `staticcheck`'s separately-invoked `stylecheck` companion rather than +its default check set. + +## `govulncheck` + +`govulncheck` answers a question neither `gofmt`, `go vet`, nor +`staticcheck` can: not "is this code suspicious," but "does anything this +module actually calls sit inside a function the Go vulnerability database +has an advisory against." That is a fundamentally different kind of check — +it needs a reachable network (the vulnerability database lives at +`vuln.go.dev`) and it only has something to say about a *vulnerable +dependency*, which this module deliberately does not have: `go/go.mod` pulls +in nothing outside the standard library, so there is no `go.sum` and nothing +for `govulncheck` to cross-reference here at all. + +The workflow a reader would actually use is `govulncheck ./...` (or +`govulncheck -mode=binary ./bin/toolbox` against an already-built binary), +run from inside the module whose dependencies are in question. Because this +module has no third-party dependency to demonstrate against, the practical way +to exercise the tool for real would be a small, deliberately isolated +sub-module — its own `go.mod`, pinning one dependency at a version with a +known advisory, calling exactly the vulnerable symbol — kept entirely +separate from `go/`'s own `go.mod` so a vulnerable dependency is never part +of this example's default build or committed to the repository. This +example does not ship that sub-module: doing so for real needs network +access to resolve the dependency and query the vulnerability database, both +excluded by this chapter's offline constraint, and committing a genuinely +vulnerable dependency into the repository is not a trade worth making for +one illustrative transcript. + +What follows is the *shape* of a real advisory hit, not a captured run — it +was never executed on this host, there is no vulnerable dependency here to +find, and the identifier below is a placeholder, not a real advisory number: + +```console +$ govulncheck ./... # ILLUSTRATIVE -- not run on this host: no network, no vulnerable dependency committed +Scanning your code and P packages across M dependent modules for known vulnerabilities... + +=== Symbol Results === + +Vulnerability #1: GO-XXXX-XXXXX + : + More info: https://pkg.go.dev/vuln/GO-XXXX-XXXXX + Module: + Found in: @ + Fixed in: @ + Example traces found: + #1: +``` + +The two details worth carrying away from that shape: `govulncheck` reports a +stable `GO-xxxx-xxxxx` identifier per advisory (the same kind of durable +token `staticcheck`'s `U1000`/`SA4006` and `golangci-lint`'s `(unused)` +are — a name to grep for that survives wording changes across releases), +and it only ever flags a symbol your own code actually reaches (the +"Example traces found" call chain) — a vulnerable function sitting unused +in a dependency you happen to import produces no finding at all, since +nothing calls it. There is no `verify.lua` gate for `govulncheck` in this +example, on purpose: it is prose and workflow here, not a gated check. + +## `delve` configs + +Delve is Go's native debugger — DWARF-aware like `gdb`, but built with +goroutines as a first-class concept rather than bolted on. `go/.dlvinit` is +a committed, four-line headless-batch script, the same idea as Chapter 46's +`gdb` batch invocation, expressed in delve's own init-script format: + +``` +break main.go:33 +continue +print d.FNV +quit +``` + +Line 33 of `main.go` is the `fmt.Printf` call inside `cmdReport`, one line +after `d := fnv1a(kPayload[:])` computes the digest: + +```go +func cmdReport() int { + d := fnv1a(kPayload[:]) + fmt.Printf("toolbox report: payload_len=%d digest=0x%016x\n", len(kPayload), d.FNV) + return 0 +} +``` + +Breaking on line 33 stops execution *after* `d` is assigned but *before* +its own line prints anything, which is exactly why `print d.FNV` has +something meaningful to show: delve renders `Digest`'s one field as a plain +64-bit unsigned decimal, `5195329438047200767` — the same bits as +`0x481984990deee5ff`, the identical value `toolbox report`'s own `%016x` +formatting and Chapter 46's `gdb` pretty-printer both already surfaced, this +time with no pretty-printer at all, because a single-field `uint64` needs no +help to read. The designed-for invocation a reader with `dlv` installed +would run: + +```console +$ dlv exec ./bin/toolbox --init .dlvinit -- report +``` + +A debug binary built with optimizations and inlining turned off +(`go build -gcflags=all="-N -l" -o toolbox .`) is what `verify.lua` gate I +builds before invoking `dlv` this way — without `-N -l`, the compiler is +free to inline `fnv1a` into `cmdReport` and eliminate the local `d` +variable entirely, and there would be nothing left at line 33 for `break` +to stop on cleanly. `dlv` is absent on this reference host, so gate I is +shown, not verified: the designed-for assertion is that the batch session +above prints `5195329438047200767` and exits 0. + +## How the code works + +`main.go`'s whole dispatch is a three-way `switch` on `os.Args[1]`: `report` +computes and prints the FNV-1a digest above, `tools` prints the +`go generate`-produced table, and `defect divzero` seeds a deliberate +runtime panic — Go's analog of Chapter 46's UBSan-caught signed-integer +overflow, using the failure mode Go itself provides instead: + +```go +func cmdDefectDivZero() int { + // `int32` variables (not compile-time constants) so the compiler cannot + // fold the division at build time -- the point is a *runtime* panic, + // not a compiler diagnostic. This one statement is the entire seeded + // defect. + var divisor int32 + dividend := int32(42) + fmt.Printf("toolbox defect divzero: dividend=%d divisor=%d\n", dividend, divisor) + os.Stdout.Sync() + result := dividend / divisor // runtime panic: integer divide by zero + fmt.Printf("unreachable: result=%d\n", result) + return 0 +} +``` + +`divisor` is a variable initialized to its zero value, not a literal `0` — +the same reason Chapter 46's `max_value` was declared `volatile`: a constant +division by a literal zero is a compile-time error in Go (`invalid +operation: division by zero`), so the defect has to survive as far as run +time to be the thing this section demonstrates, and a plain variable the +compiler cannot constant-fold does exactly that. + +`digest.go` holds the `Digest` type and the `fnv1a` implementation quoted +above; `tools_generated.go` holds the generator's committed output; +`smells.go` and `vetdemo.go` hold the deliberate, never-called findings for +the static-analysis and `go vet` gates. Every one of those last three files +is isolated from the digest and from each other by a different mechanism — +`smells.go`'s functions are simply unreferenced, `vetdemo.go` sits behind a +`//go:build vetdemo` tag excluded from the default build entirely, and the +`testdata/` fixtures are ignored by `go build`/`go vet`/`go test` by +directory-name convention — so nothing about running `toolbox report` or +`toolbox tools` can ever depend on which of those designed-for smells has or +has not been "fixed." + +{% include excalidraw.html + file="47-go-tool-gates" + alt="One Go module box splits into two gate lanes. The amber hard lane lists gofmt -l, go generate diff-clean, go vet -tags vetdemo naming a printf finding, go tool pprof -top naming hotLoop, and the FNV-1a digest -- all shipping inside the go binary and verifying offline. A dashed ghost lane beside it lists gofumpt, golangci-lint, staticcheck, and delve as gated-if-present, govulncheck marked network required, and benchstat, all shown as reference and not verified on this host." + caption="Figure 47.2 — one module, two gate lanes: the go-native hard gates (gofmt, go generate, go vet, pprof, digest) that ship with the go binary and verify offline, beside the gated-if-present tools (gofumpt, golangci-lint, staticcheck, delve, govulncheck, benchstat) shown as reference" %} + +## Errors, three ways + +With one language and no compiler of its own to disagree with itself, "three +ways" here means three different *static* surfaces reading the same source +without ever running it — not three languages, and not a runtime trap, +since this chapter's one seeded panic (`defect divzero`) already got its own +section above. The first surface is the shallowest: `gofmt` (and, if +installed, `gofumpt`) notices only *shape* — whitespace, alignment, blank +lines — and says nothing about whether the code is correct, only whether it +matches one fixed, mechanical layout. `messy.go` above is not wrong in any +semantic sense; `gofmt -l` still lists it, because shape is the entire +question that tool answers. + +The second surface is `go vet`, which ships with `go` itself and reads +*usage patterns the compiler allows but almost never means*. `vetdemo.go`, +excluded from the default build by its own build tag, is one deliberate +mismatch: + +```go +//go:build vetdemo + +package main + +import "fmt" + +// vetdemo.go is excluded from the default build/test (`go build ./...`, +// `go test ./...`) by the vetdemo build tag above. It exists only so +// `go vet -tags vetdemo .` has something real to report: printBadFormat's +// Printf call passes a string argument to a %d verb, a stable "printf" +// finding go vet's printf analyzer always reports for this exact mismatch. +func printBadFormat() { + fmt.Printf("bad format: %d\n", "not-an-int") +} +``` + +The Go compiler accepts this without complaint — `Printf`'s format string +and its variadic arguments are only strings and `interface{}` values at the +type level, so there is nothing for the type checker itself to reject. `go +vet`'s printf analyzer is what actually reads the format verb against the +argument's real type and flags the mismatch, run for real on this host: + +```console +$ go vet -tags vetdemo . +vetdemo.go:13:26: fmt.Printf format %d has arg "not-an-int" of wrong type string +``` + +The third surface goes deeper still: `staticcheck` and `golangci-lint` +(which bundles a copy of `staticcheck`) trace data flow and naming +convention rather than a single call's argument types — `smells.go`'s +`U1000`/`SA4006`/`ST1003` designed-for findings, above, are exactly that +class of thing, none of which `go vet` catches on its own. Three surfaces, +three different amounts of context each tool is willing to read before it +says anything: pure text shape, one function call's argument types, and a +whole package's data flow and naming — and each one earns its place by +catching something none of the others do. + +## Concurrency lens + +Chapter 44 spent a whole chapter on the GMP model: `GOMAXPROCS` P's are the +scarce resource that lets an M run Go code at all, goroutines are cheap, and +work-stealing moves half a queue at a time between P's that run dry. This +chapter's benchmark is the tooling side of that same picture — not *how* +the scheduler multiplexes work, but *how a reader measures whether it scaled +the way that model predicts*. `bench_test.go`'s `hotLoop` is a deliberately +dominant, purely CPU-bound function with no allocation and no function +calls inside its loop, so a sampling profiler has nowhere else to attribute +time to: + +```go +func hotLoop(n int) uint64 { + var x uint64 = 0x9e3779b97f4a7c15 + for i := 0; i < n; i++ { + x ^= uint64(i) + x *= 6364136223846793005 + x = x<<13 | x>>51 + } + return x +} +``` + +`BenchmarkHotLoop` runs it serially; `BenchmarkHotLoopParallel` runs the +identical function through `b.RunParallel`, Go's built-in construct for +fanning a benchmark out across `GOMAXPROCS` goroutines at once: + +```go +func BenchmarkHotLoopParallel(b *testing.B) { + b.RunParallel(func(pb *testing.PB) { + var local uint64 + for pb.Next() { + local = hotLoop(hotLoopIters) + } + hotLoopSink = local + }) +} +``` + +`b.RunParallel` is not doing anything Chapter 44 didn't already name: each +of the goroutines it launches is a G, competing for one of `GOMAXPROCS` P's +the same way any other goroutines would, and `hotLoop`'s pure, allocation-free +loop is close to the best case for that model — no channel sends, no shared +mutable state, no lock contention, so there is nothing here for a P to block +on and nothing to steal from another P's queue. That is exactly why this +benchmark is the right one to compare `-cpu=1` against `-cpu=N` with: any +scaling loss that shows up would have to come from the scheduler's own +bookkeeping or from memory-hierarchy effects across cores, not from +goroutines waiting on each other — a workload engineered to isolate the +question `benchstat` is built to answer statistically rather than by eyeballing +one run's numbers. + +## `pprof` and `benchstat`: the profiling workflow + +`go tool pprof` is the go-native half of this pairing, and it is a hard, +verified gate here — no install required, because `runtime/pprof` and +`go tool pprof` both ship inside the same `go` binary as everything else in +this chapter's hard core. The workflow is three commands: build a CPU +profile from the benchmark, then read it with `-top`: + +```console +$ go test -bench=. -run=^$ -cpuprofile=cpu.prof -o toolbox.test . +$ go tool pprof -top -nodecount=15 toolbox.test cpu.prof + flat flat% sum% cum cum% + 18.57s 99.95% 99.95% 18.58s 100% .../47-go-toolbox/go.hotLoop (inline) + 0 0% 99.95% 1.38s 7.43% .../47-go-toolbox/go.BenchmarkHotLoop + 0 0% 99.95% 17.20s 92.57% .../47-go-toolbox/go.BenchmarkHotLoopParallel.func1 +``` + +`hotLoop` owns 99.95% of `flat` samples on its own, exactly as its design +intends, and the gate this chapter asserts is that name, `hotLoop`, appearing +in the top frames — never the timing next to it. Sample counts and elapsed +seconds vary with host load and iteration count from run to run; the +*identity* of the function actually spending the cycles does not, which is +why `verify.lua` gate E matches the string `hotLoop` and nothing else. That +same profile also shows `BenchmarkHotLoop` (7.43% cumulative) and +`BenchmarkHotLoopParallel.func1` (92.57% cumulative) as the two call paths +into `hotLoop` — both benchmarks ran during profiling, and `pprof` attributes +each sample to whichever one was actually on the stack at that instant. + +`benchstat` is the tool that turns two sets of raw benchmark numbers into a +statistical comparison instead of an eyeballed diff — the workflow a reader +would use to ask "did this change actually help, or is that just noise": + +```console +$ go test -bench=BenchmarkHotLoop -run=^$ -count=10 . > old.txt +$ go test -bench=BenchmarkHotLoop -run=^$ -count=10 . > new.txt +$ benchstat old.txt new.txt +``` + +`benchstat` is absent on this reference host, so that comparison is shown as +a workflow, not run. `verify.lua` gate K, if the tool were present, would +compare two runs of the *same* unmodified benchmark against each other and +assert only the table's **structure** — a `sec/op` column header and a row +naming `BenchmarkHotLoop` — deliberately not the numbers inside it, since two +runs of identical code will still differ in wall-clock time with host +scheduling noise, and this chapter's gates never assert a raw timing as +if it were a fixed literal. A reader comparing `-cpu=1` against `-cpu=N` for +`BenchmarkHotLoopParallel` would read the same table shape, with `benchstat`'s +own statistics (median, confidence interval) doing the job of saying whether +an observed difference is real or within noise — the same discipline Chapter +44's `GOGC`/`GOMEMLIMIT` comparisons used exact `NumGC` deltas to sidestep +entirely, here handled by a purpose-built statistics tool instead because +wall-clock benchmark timings have no exact-integer shortcut. + +## Build, run, observe + +```console +[host]$ cd examples/47-go-toolbox && ./demo.sh go build +``` + +That builds `bin/toolbox` from stdlib alone — no network, no `go.sum`. +Hand-running the hard-gated commands in sequence: + +```console +[host]$ ./demo.sh go run report +toolbox report: payload_len=16 digest=0x481984990deee5ff +[host]$ cd go && go generate ./... && git diff --exit-code && cd .. +[host]$ gofmt -l $(find go -name '*.go' -not -path '*/testdata/*') +[host]$ cd go && go vet -tags vetdemo . && cd .. +vetdemo.go:13:26: fmt.Printf format %d has arg "not-an-int" of wrong type string +``` + +The full gate, exactly as run this session: + +```console +[host]$ LSP_LANG=go REPO_ROOT=$(cd ../.. && pwd) lua verify.lua +... +PASS 16 / FAIL 0 +[host]$ python3 scripts/test-all-examples.py --only 47-go-toolbox +... +1 passed, 0 failed, 0 skipped +``` + +Sixteen real assertions, none of them a bare exit code: `go.mod`'s two +toolchain literals, the `report` digest against a fixed literal, the +copy-aside diff-clean check plus the generated table's count and one sorted +entry, `gofmt -l`'s empty-versus-flagged pair, `go vet`'s printf finding and +its file location, and the `pprof -top` name check — with `SKIP:` printed, +never a failure, for each of the five gated-if-present tools this host does +not have installed. + +## Cross-check: the same digest, two languages apart + +The clearest falsifiable claim in this chapter is not internal to Go at +all — it is the one this chapter shares with Chapter 46. `toolbox report` +here and `toolbox report` there hash a byte-for-byte identical 16-byte +payload with the byte-for-byte identical FNV-1a algorithm, and land on the +identical 64-bit value: + +```console +[host]$ ./go/bin/toolbox report +toolbox report: payload_len=16 digest=0x481984990deee5ff +[host]$ ./cpp/build/release/toolbox report # ch46, quoted there +toolbox report: label=[toolbox] report payload_len=16 digest=0x481984990deee5ff +``` + +`digest=0x481984990deee5ff` on both sides, produced by two toolchains that +share nothing else — a garbage-collected runtime versus a compiled binary +with no runtime of its own, a scheduler built around goroutines versus none +at all — because FNV-1a's definition constrains only integer arithmetic +over bytes, and integer arithmetic is one of the vanishingly few things +every conforming language implementation is required to agree on bit for +bit. The second cross-check is internal: the copy-aside `go generate` diff +and the idiomatic `git diff --exit-code` form check the identical property +two different ways — one without assuming a git checkout exists, one the +way a reader's own CI would actually gate it — and both report clean on +this tree, which is the same "two independent paths to the same answer" +discipline Chapter 46's GCC-vs-clang `diff` used, aimed here at a generator +agreeing with itself instead of two compilers agreeing with each other. + +## Where this sits next to the book's other tooling chapters + +Two earlier chapters already covered pieces of this ground, and this +chapter does not re-teach either: + +- **Chapter 31** ("Per-Language Toolbelts") gave Go one column of a + three-language *profiling breadth* comparison — `runtime/pprof`, + `go tool trace`, and `dlv`, one paragraph each, next to C++'s `perf` and + Rust's `cargo flamegraph`. This chapter is the opposite shape: it never + touches `go tool trace` at all, and instead spends its depth budget on + `dlv`'s **config authoring** (a committed `.dlvinit` headless-batch + script, not just "delve exists") and the `pprof`-to-`benchstat` + **workflow** — going from a raw CPU profile to a statistically + defensible before/after comparison — ground Chapter 31 never had room for. +- **Chapter 44** ("The Go Runtime from a Systems Programmer's Seat") is + where the GMP scheduler, the pacer, and the netpoller actually live — + what `GOMAXPROCS`, work-stealing, and `SIGURG`-based preemption mean and + why they behave as they do. This chapter assumes all of that and asks a + narrower, tooling-shaped question on top of it: given that model, how does + a reader *measure* whether a change to `hotLoop` actually changed + anything, with `b.RunParallel` as the harness and `pprof`/`benchstat` as + the instruments — the tooling that measures the runtime, not the runtime + itself. + +What is genuinely new here — the `go`/`toolchain` directive pair and +`GOTOOLCHAIN`'s resolution rule, `go generate` as a diff-clean CI discipline +with a self-contained generator, `gofmt`-clean-but-`gofumpt`-dirty as a +deliberately narrow fixture, `.golangci.yml`/`staticcheck` config authored +rather than merely invoked, and a committed `dlv` headless-batch script — +has no earlier chapter to point back to instead. + +## What you learned + +- **`go`/`toolchain` is two directives answering two different questions**: + `go 1.26` pins the language-version floor every tool reads; `toolchain + go1.26.5` pins the exact `go` binary release, resolved through + `GOTOOLCHAIN=auto` with no network access needed when the installed + binary already satisfies the pin — which it does on this host. +- **A generator's determinism has to be engineered, not assumed**: + `internal/gen`'s `toolTable` is a Go map with no iteration-order + guarantee, listed out of alphabetical order in source on purpose; + `sort.Strings` plus `go/format`'s `format.Source` are what make + `tools_generated.go` byte-identical across regenerations, which is the + property `go generate ./... && git diff --exit-code` (and this chapter's + copy-aside equivalent) actually gates. +- **`gofmt`, `gofumpt`, `go vet`, and `staticcheck`/`golangci-lint` read + successively more context before saying anything**: pure text shape, one + function call's argument types (`vetdemo.go:13`'s printf mismatch), and a + whole package's data flow and naming (`smells.go`'s `U1000`/`SA4006`/ + `ST1003`) — three static surfaces, not three languages, and none of them + ever executes the program. +- **`b.RunParallel` is Chapter 44's GMP model, applied as a measurement + harness**: `hotLoop`'s allocation-free, lock-free loop is close to the + best case for `GOMAXPROCS` P's to scale cleanly, which is exactly why it + is the right benchmark to hand to `benchstat` for a statistically + defensible `-cpu=1` vs `-cpu=N` comparison rather than an eyeballed one. +- **The same digest twice, in two languages that share nothing else**: + `toolbox report`'s `0x481984990deee5ff` here matches Chapter 46's C++ + `toolbox report` byte for byte, because FNV-1a constrains only integer + arithmetic over a fixed payload — one of the few things every conforming + language implementation is required to agree on exactly. +- **Six real, committed tool configs, none of them run on this host**: + `gofumpt`, `golangci-lint` (`.golangci.yml`), `staticcheck`, `govulncheck`, + `dlv` (`.dlvinit`), and `benchstat` are all absent from this reference + host; their sections above show real configs and designed-for findings, + and the footer below marks exactly that gap and nothing more. + +Part 13 continues with Rust's own toolchain, getting the same reference-depth +treatment this chapter and Chapter 46 gave C++ and Go. + +--- + +

verified — on the Fedora 44 +reference host this session (kernel 7.1.4-204.fc44, go1.26.5, offline, no +network access used): +LSP_LANG=go REPO_ROOT=$(cd ../.. && pwd) lua verify.lua reported +PASS 16 / FAIL 0, and +python3 scripts/test-all-examples.py --only 47-go-toolbox +reported 1 passed, 0 failed, 0 skipped. Confirmed live and +folded into that PASS count, the go-native hard gates A-E: go.mod +pins go 1.26 and toolchain go1.26.5; +toolbox report printed +toolbox report: payload_len=16 digest=0x481984990deee5ff, +byte-identical to Chapter 46's C++ digest; go generate ./... +regenerated tools_generated.go byte-for-byte against the +committed copy (copy-aside diff empty) and toolbox tools +printed the generated table's count=10 plus its sorted +gofmt entry; gofmt -l was empty across every +tracked source and flagged testdata/gofmt/messy.go; +go vet -tags vetdemo . reported the printf mismatch at +vetdemo.go:13:26; and go tool pprof -top +-nodecount=15 named hotLoop at 99.95% of flat samples +in a real -cpuprofile capture. Not exercised: unverified — gofumpt, +golangci-lint, staticcheck, govulncheck, +dlv, and benchstat are all absent from this +reference host (confirmed by command -v for each), so gates +F, G, H, I, and K each printed an informational SKIP: rather +than running for real, and their sections above show committed configs +(.golangci.yml, .dlvinit) and designed-for +findings — the exact tokens ((unused), U1000, +SA4006, the decimal 5195329438047200767, +a sec/op table) a reader with those tools installed would see — +rather than a captured run. govulncheck is additionally +illustrative only: it needs network access to the Go vulnerability +database, this module has no vulnerable dependency to demonstrate against +by design, and no govulncheck gate exists in +verify.lua at all. examples/manifest.yaml marks +this example mode: local — no VM or LGTM path applies.

diff --git a/_plans/r16-ch47-plan.md b/_plans/r16-ch47-plan.md index a1774ae..e86b2a1 100644 --- a/_plans/r16-ch47-plan.md +++ b/_plans/r16-ch47-plan.md @@ -109,6 +109,11 @@ Merge safe either way; footer reflects exactly which optional tools Phase 2 inst - govulncheck: chapter prose/workflow + clearly-labeled ILLUSTRATIVE advisory output (not "from a run"), NOT gated, NO vulnerable dep in repo. - verify.lua must PASS on A-E, informational-SKIP F-K, FAIL 0. -## Status -- [ ] S1 scaffold - [ ] S2 sources - [ ] S3 verify - [ ] S4 build+install+capture -- [ ] S5 chapter - [ ] S6 diagrams - [ ] S7 manifest - [ ] Phase3 validate - [ ] gate/PR +## Status — DONE +- [x] S1-S4 example (offline): verify PASS 16/0 (A-E hard pass, F-K SKIP) +- [x] S5 chapter `_docs/47-go-toolbox.md` (983 lines) +- [x] S6 diagrams (47-go-toolchain-pipeline, 47-go-tool-gates) + README rows +- [x] S7 manifest (langs:[go], mode:local, timeout 480) +- [x] Phase 3 validate (Opus): all 12 criteria MET, verdict **SHIP**, zero MUST-FIX +- Gate: verify PASS 16/0 · validate: OK · runner PASS. Correct delve decimal 5195329438047200767; govulncheck illustrative placeholder only. +- Verified = go-native A-E; the 6 marquee tools absent on host → status--unverified (offline decision).