From 2f12a4d1d178dd2257d1386fcc9485e03ef36b92 Mon Sep 17 00:00:00 2001 From: jedarden Date: Sat, 4 Jul 2026 09:16:28 -0400 Subject: [PATCH] docs(notes): add spaxel-build WorkflowTemplate path inventory (bf-1yeh) Appendix A to ci-test-sim-reference-map.md: line-by-line path inventory of the spaxel-build WorkflowTemplate. Every Go step runs with cwd=mothership, so ./cmd/sim (L385), ./cmd/mothership (L392), and ./test/acceptance/ (L400) all resolve under the mothership module. Confirms the template references none of: root cmd/sim, root test/acceptance, tests/e2e/run.sh, or mothership/tests/e2e/e2e_test.go (the latter only transitively compile- covered by go test ./...). Co-Authored-By: Claude --- docs/notes/ci-test-sim-reference-map.md | 176 ++++++++++++++++++++++++ 1 file changed, 176 insertions(+) create mode 100644 docs/notes/ci-test-sim-reference-map.md diff --git a/docs/notes/ci-test-sim-reference-map.md b/docs/notes/ci-test-sim-reference-map.md new file mode 100644 index 0000000..d5bf1de --- /dev/null +++ b/docs/notes/ci-test-sim-reference-map.md @@ -0,0 +1,176 @@ +# CI & go.work Reference Map — test/sim trees + +**Bead:** bf-2tk7 (foundational investigation for parent bf-id5) +**Date:** 2026-07-04 +**Purpose:** Definitive map of what CI (`spaxel-build`, `spaxel-e2e` WorkflowTemplates in +`jedarden/declarative-config`) and `go.work` actually reference, so the parent bead removes / +consolidates only what nothing references. + +## Method & scope note + +The WorkflowTemplates live in `jedarden/declarative-config` (outside this repo). The CI-side +facts below come from the bf-2tk7 task brief's "already-known facts" (read by the brief's +author) and were **verified against the spaxel tree** for every path that exists here: +existence, module boundary, and whether the documented local/CI commands resolve. One item +— the `workingDir` of `spaxel-e2e` line ~72 — cannot be determined from inside this repo and +is flagged for the parent to confirm (see *Suspicious path*). + +## go.work (verified) + +``` +go 1.25.0 +use ./mothership +use ./test/acceptance +``` + +Exactly two modules. **No `./cmd/sim`** — root `cmd/sim` is staged-deleted +(`git status`: `D cmd/sim/{go.mod,go.sum,main.go}`) and there is no root `cmd/` dir. Confirmed. + +## Reference map + +| Path | Referenced by CI? | In go.work? | Exists on disk? | Decision | +|------|-------------------|-------------|-----------------|----------| +| `cmd/sim` (root) | **No** | **No** | **No** — staged-deleted; no root `cmd/` | **REMOVE** — already removed in working tree; commit the deletion. | +| `mothership/cmd/sim` | **Yes** — `spaxel-build` runs `./cmd/sim` after `cd repo/mothership`; **Dockerfile L97** builds `./cmd/sim` from WORKDIR `/app` after `COPY mothership/ ./`; **`tests/e2e/run.sh` L238–242** mounts `mothership:/src` (`-w /src`) and runs `go build ./cmd/sim`. All three resolve `./cmd/sim` from a **mothership** cwd → `mothership/cmd/sim`. | Yes (part of `./mothership`) | Yes (`generator/walker/scenario/verify/main.go` + `main_test.go`, `Makefile`, `README.md`; **no own go.mod** → in `github.com/spaxel/mothership` module) | **KEEP** — sole CSI simulator; CI-built and image-baked. | +| `test/acceptance` (root) | **No** — `spaxel-build` cds into `mothership` and runs `go test ./...`, which does not cross into the separate root module | **Yes** — `use ./test/acceptance` | Yes — own module `github.com/spaxel/acceptance`, `replace github.com/spaxel/mothership => ../../mothership` | **DOCUMENT** — not CI-exercised; run via documented `cd test/acceptance && go test ./...` (README L79). go.work member — do **not** remove blindly; consolidation candidate only. | +| `mothership/test/acceptance` | **Yes** — `spaxel-build` runs `./test/acceptance` from the `mothership` cd; `spaxel-e2e` line ~72 refs `./mothership/test/acceptance` (see *Suspicious path*) | Yes (part of `./mothership`) | Yes — 9 in-module test files + `test_helpers.go` | **KEEP** — canonical in-module acceptance suite; CI compile-covered and explicitly run. | +| `tests/e2e/run.sh` | **No** — per brief, neither template invokes it | **No** | Yes — 429-line shell harness (Docker-based e2e) | **DOCUMENT** — orphaned from CI and go.work; runs only manually. Parent decision: wire into CI or remove. | +| `mothership/tests/e2e/e2e_test.go` | **No explicit CI path** (per brief) | Yes (part of `./mothership`) | Yes — Go e2e (gorilla/websocket, builds binaries via os/exec) | **KEEP / DOCUMENT** — transitively compile-covered by `spaxel-build`'s `go test ./...` (no build tag; skips at runtime via `testing.Short()` / `SPAXEL_INTEGRATION_TEST=1`). Not named explicitly by any CI path. | + +## Suspicious path — `./mothership/test/acceptance/...` at spaxel-e2e ~line 72 + +> **Decision impact: NONE.** `spaxel-build` explicitly runs `./test/acceptance` from its +> `cd repo/mothership` (→ `mothership/test/acceptance`), so that directory is CI-exercised +> and **KEEP regardless** of how the e2e line-72 step resolves. The question below only +> determines whether the e2e *invocation* is live or a dead ref — it does not change any +> keep/remove decision for the directory itself. Recorded for completeness. + +**Structural facts (verified here):** +- `mothership/test/acceptance/` is a **real** directory (9 test files, part of the mothership module). +- Root `test/acceptance/` is **also** a real directory (separate module). +- Both `./test/acceptance` **and** `./mothership/test/acceptance` appear in the e2e template. + +**Resolution depends entirely on the step's `workingDir`** (cannot be read from inside this repo): + +| workingDir of line-~72 step | `./mothership/test/acceptance` resolves to | Verdict | +|------------------------------|--------------------------------------------|---------| +| repo root (`/tmp/spaxel-src`) | `/tmp/spaxel-src/mothership/test/acceptance` (real) | **LIVE** — tests the mothership in-module acceptance suite. (`./test/acceptance` elsewhere in the template then resolves to the *root* module — two distinct suites.) | +| `/tmp/spaxel-src/mothership` (the cd) | `/tmp/spaxel-src/mothership/mothership/test/acceptance` (does **not** exist) | **BUG** — nested path; `go test` errors / finds no packages. | + +**Most-likely verdict:** Because both `./test/acceptance` and `./mothership/test/acceptance` +coexist in the template and resolve to distinct real dirs **only** when cwd = repo root, the +line-~72 step most likely runs from repo root and is **real** — it exercises the mothership +in-module acceptance suite. The "suspicion" is purely that the prefix differs from +`spaxel-build`'s `./test/acceptance` (which is cwd-relative to the `mothership` cd and points +at the *same* `mothership/test/acceptance` dir). + +**Confirm for parent (bf-id5):** read `workingDir:` of the `spaxel-e2e` step at ~line 72. +- repo root → live; leave as-is. +- mothership → dead ref; fix to `./test/acceptance` (matching build) or drop. +- **The directory `mothership/test/acceptance/` itself is KEEP regardless** — it is the + canonical in-module acceptance suite exercised by `spaxel-build`. + +## Related doc-debt surfaced (not in scope to fix here) + +Verified via `grep -rn 'cmd/sim'` across the repo (excluding `.beads/`, `mothership/cmd/sim`, +traces, node_modules). Beyond the live code paths above, root-`cmd/sim` still appears in +**docs/config that were not updated when root `cmd/sim` was removed**: + +- **`README.md` L76** — `go build -o spaxel-sim ./cmd/sim` is now **broken from repo root** + (root `cmd/sim` removed). Should be `cd mothership && go build -o spaxel-sim ./cmd/sim` + (or workspace-aware). +- **`README.md` L33** — table row `` [`cmd/sim/`](cmd/sim/) `` is a **dead link** (no root + `cmd/` dir), and labels the simulator `github.com/spaxel/sim` — a **stale module name**; + it is now `github.com/spaxel/mothership` (no separate sim module). Should point at + `mothership/cmd/sim/`. +- **`.golangci.yml` L139, L144** — exclude rules `path: cmd/sim/main\.go` and + `cmd/sim/scenario\.go` reference the **gone root path**. Update to `mothership/cmd/sim/...` + (or drop) so the excludes still match when lint runs in the mothership module. +- **`PROGRESS.md` L477, L511** — prose references to `cmd/sim` / `cmd/sim/` for the simulator. +- **`docs/plan/plan.md`** — the *Go Module Layout* section (L3480–3530) and L3527 specifically + still describe the **three**-module workspace (`mothership`, `cmd/sim`, `test/acceptance`) + with `cmd/sim/ — Go module (cmd/sim/go.mod)`. That is now **factually stale**: root + `cmd/sim` is gone, the simulator lives at `mothership/cmd/sim` with no own go.mod, and + `go.work` has **two** members. L3375, L3666, L3855–3856 carry the same stale + `go build ./cmd/sim`-from-root framing. **Highest-priority doc-debt for parent bf-id5** — + the plan is the canonical "where things live" reference and now mis-describes the layout + this bead family is consolidating. + +All of the above belong to the cmd/sim-consolidation child (or a dedicated doc-sync child), +**not** to this investigation bead. + +## Summary decisions + +- **Remove:** root `cmd/sim` (deletion already staged — commit it). +- **Keep (CI-active):** `mothership/cmd/sim`, `mothership/test/acceptance`. +- **Keep (transitively compile-covered by `go test ./...`):** `mothership/tests/e2e/e2e_test.go`. +- **Document / parent-decide:** root `test/acceptance` (go.work member, not CI-run), + `tests/e2e/run.sh` (orphaned shell harness). +- **Confirm before acting:** `workingDir` of `spaxel-e2e` line ~72 (see above). + +--- + +## Appendix A — `spaxel-build` line-by-line path inventory (bf-1yeh) + +> Split-child #1 of bf-2tk7. Granular per-line evidence underlying the table above. Template +> read end-to-end at `jedarden/declarative-config` → +> `k8s/iad-ci/argo-workflows/spaxel-build-workflowtemplate.yml` (417 lines). Every Go step +> clones the repo to `/tmp/repo` and then `cd`s into `repo/mothership`, so **every `./...`, +> `./cmd/...`, `./test/...`, `./internal/...` path in a Go step resolves UNDER the mothership +> module** (`/tmp/repo/mothership`). Verified against the spaxel tree on 2026-07-04. + +### Step working directories + +| Step (template) | Clone dest | `cd` to | Effective working dir | Tree | +|-----------------|-----------|---------|-----------------------|------| +| `resolve-version` (L66) | `/tmp/repo` (L77) | `/tmp/repo` (L78) | repo ROOT | root | +| `docker-build` (L117) | n/a — kaniko git context | n/a | repo ROOT (kaniko context root) | root | +| `update-declarative-config` (L155) | `/tmp/dc` (declarative-config repo) | `/tmp/dc` (L170) | **declarative-config**, not spaxel | — | +| `golangci-lint` (L191) | `/tmp/repo` (L210–212) | `repo/mothership` (L213) | `/tmp/repo/mothership` | **mothership** | +| `a11y-test` (L233) | `/tmp/repo` (L250–252) | `repo/dashboard` (L253) | `/tmp/repo/dashboard` | dashboard (Node, non-Go) | +| `go-test` (L272) | `/tmp/repo` (L285–288) | `repo/mothership` (L289) | `/tmp/repo/mothership` | **mothership** | +| `timing-benchmark` (L309) | `/tmp/repo` (L322–325) | `repo/mothership` (L326) | `/tmp/repo/mothership` | **mothership** | +| `acceptance-test` (L365) | `/tmp/repo` (L378–381) | `repo/mothership` (L382) | `/tmp/repo/mothership` | **mothership** | + +### Every Go build / test / vet / bench target + +| Command | Line | cwd base | Resolves to | Exists? | +|---------|------|----------|-------------|---------| +| `golangci-lint run --timeout 5m ./...` | L217 | `mothership` | `mothership/...` (whole module) | yes | +| `go test -v -timeout 20m ./...` | L291 | `mothership` | `mothership/...` (whole module) | yes | +| `go vet ./...` | L293 | `mothership` | `mothership/...` (whole module) | yes | +| `go test -bench=BenchmarkFusionLoop -benchtime=10s -count=1 ./internal/localizer/fusion/` | L329–330 | `mothership` | `mothership/internal/localizer/fusion/` (`BenchmarkFusionLoop` at `…/fusion/timing_budget_test.go:94`) | yes | +| `go build -v -o /tmp/spaxel-sim ./cmd/sim` | **L385** | `mothership` | **`mothership/cmd/sim`** (NOT root `cmd/sim`) | yes (`mothership/cmd/sim/main.go` + others; **no own go.mod** → in `github.com/spaxel/mothership`) | +| `go build -v -o build/spaxel ./cmd/mothership` | **L392** | `mothership` | **`mothership/cmd/mothership`** | yes (`main.go`, `dashboard_embed.go`, `migrate.go`) | +| `go test -v -timeout 8m ./test/acceptance/` | **L400** | `mothership` | **`mothership/test/acceptance/`** (NOT root `test/acceptance`) | yes (9 `as*_test.go` + `io_install_upgrade_test.go`, `integration_test.go`, `test_helpers.go`) | + +### Docker build context / Dockerfile (kaniko, `docker-build` step) + +| Item | Line | Value | Resolves to | +|------|------|-------|-------------| +| Build context | L130 | `--context=git://github.com/jedarden/spaxel.git#refs/heads/main` | repo ROOT | +| Dockerfile | L131 | `--dockerfile=Dockerfile` | root `/Dockerfile` (relative to context root) | +| Image tags | L132–133 | `ronaldraygun/spaxel:` + `:latest` | — | +| Build arg | L134 | `--build-arg=VERSION=` | consumed by Dockerfile | + +### `run.sh` invocations + +**None.** The `spaxel-build` template invokes no shell harness — specifically not +`tests/e2e/run.sh`. (The only scripts are inline `sh -c` step bodies.) + +### Explicit no-references (per bf-1yeh acceptance criteria) + +| Path | Referenced by this template? | Evidence | +|------|------------------------------|----------| +| root `cmd/sim` | **NO** | The sole `./cmd/sim` ref (L385) runs with cwd=`mothership` → `mothership/cmd/sim`. Root `cmd/sim` is removed (staged-deleted; no root `cmd/` dir). | +| root `test/acceptance` | **NO** | The sole `./test/acceptance/` ref (L400) runs with cwd=`mothership` → `mothership/test/acceptance/`. The separate root module `github.com/spaxel/acceptance` is never touched. | +| `tests/e2e/run.sh` | **NO** | No `run.sh` invocation anywhere in the template. | +| `mothership/tests/e2e/e2e_test.go` | **NO explicit path** | Not named by any target. Only transitively compile-covered by `go test ./...` (L291) since it is a no-build-tag file inside the mothership module. | + +### Note on `go test ./...` transitive coverage + +The `go test ./...` at L291 (cwd=`mothership`) compiles and runs every package in the +mothership module, which transitively includes `mothership/cmd/sim` (its `main_test.go`), +`mothership/test/acceptance/`, and `mothership/tests/e2e/` — but only `mothership/test/acceptance/` +is *also* named by an explicit path (L400). `mothership/tests/e2e/e2e_test.go` is reached only +via the wildcard, not by an explicit target.