Rongsong Shen
375c49ecee
Checkbox update for commit 6fabdba9 (deleted the file, but its
tasks.md diff wasn't included in that commit due to a git-add
pathspec issue on the already-git-rm'd path). Marks 4/4.1/4.2 done
and records the two out-of-boundary doc mentions found during
task 4.2's post-deletion review. All 12 tasks / 4 major groups are
now [x] -- the eliminate-frontend-makefile feature is complete.
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XYdtrEWWZfKRRGED7raEYg
90 lines
13 KiB
Markdown
90 lines
13 KiB
Markdown
# Implementation Plan
|
|
|
|
- [x] 1. Core: CGO-backed backend test coverage via Meson
|
|
- [x] 1.1 (P) Add a Meson test target for the apiserver CGO-backed backend suite, reusing the existing CGO flag derivation
|
|
- Resolve the `@CURRENT_SOURCE_DIR@`/`@BUILD_ROOT@` placeholder tokens already present in `apiserver_cgo_deps`'s computed CGO flags at Meson-configure time (they are otherwise only resolved by `tools/go_build`'s own runtime sed machinery, which this new target does not go through)
|
|
- Register the target with Meson's test runner (`suite: 'apiserver'`), scoped to the apiserver source directory, depending on `libxce` having already been built
|
|
- Set the same offline/hermetic Go environment `tools/go_build` already uses (`GOFLAGS=-mod=vendor`, `GOPROXY=off`) plus an explicit, build-dir-scoped `GOCACHE`/`GOPATH` (this target invokes the Go toolchain directly, not through `go_build`, so it inherits none of `go_build`'s own internal exports)
|
|
- Observable: `meson test -C <build_dir> --suite apiserver` lists and runs the new backend test target, distinct from the existing apiserver build's `custom_target`, and exits 0 against the current (unmodified) `backend/` source
|
|
- _Requirements: 3.1, 3.2_
|
|
- _Boundary: apiserver/meson.build_
|
|
|
|
- [x] 1.2 Prove the new backend test exercises the real CGO path rather than the `//go:build !cgo` stub
|
|
- Deliberately break `apiserver_cgo_deps` (e.g. temporarily drop one dependency) and confirm the new test fails with a genuine linker/undefined-symbol error, not a silent pass
|
|
- Restore the dependency list and confirm the test is green again
|
|
- Observable: a captured failing run shows a real link-time error tied to the removed dependency; the immediately following restored run passes with no other change
|
|
- _Requirements: 3.2, 3.3_
|
|
|
|
- [x] 2. (P) Core: migrate xce-build.sh's unit-test invocation off Make
|
|
- Replace both `cd frontend && make test` call sites (the `apiserver` case and the `all` case) with direct `go test` invocations covering the exact same package set and flags the Makefile's `test` target runs today (apiserver: `store`/`utils`/`controllers`/`backend` under `CGO_ENABLED=0`; xcecli: full module), mirroring the `xcecli` case's own already-Makefile-free style in the same file
|
|
- Observable: `/xce-build apiserver` and `/xce-build all` run unit tests with zero invocation of `make`, reporting the identical test package set and pass/fail counts as the pre-migration baseline
|
|
- _Requirements: 2.1, 2.2, 2.3_
|
|
- _Boundary: xce-build.sh_
|
|
|
|
- [x] 3. Integration: eliminate every remaining live reference to the Makefile
|
|
- [x] 3.1 (P) Fix run-resource-verify.sh's apiserver-binary discovery
|
|
- Change `APISERVER_BIN`'s default from the fixed `/tmp/apiserver` path to the same `$BUILD_DIR/<component>/<binary>`-relative convention its sibling binaries (`BINARY`, `SCHED_BIN`, `XT`) already use, and update its failure message to name `/xce-build apiserver` instead of the Makefile target
|
|
- Observable: with a binary present only in the Meson build dir (no `/tmp/apiserver`), the script locates and uses it; with neither present, the failure message names `/xce-build apiserver`, not `make build-server`
|
|
- _Requirements: 5.1, 5.2, 5.3_
|
|
- _Boundary: run-resource-verify.sh_
|
|
- _Depends: 1.1, 2_
|
|
|
|
- [x] 3.2 (P) Update deploy-ha.sh's and run.sh's stale message strings
|
|
- `deploy-ha.sh`: update its `/tmp/apiserver`-fallback branch's two log lines and the preceding block comment describing "two ways" to build apiserver, dropping the `make build-server` mention; its meson-first/`/tmp/apiserver`-fallback discovery logic itself is unchanged
|
|
- `tests/regression/run.sh`: update the `XCE` binary-not-found error to name `/xce-build apiserver` instead of reproducing the deleted `build-cli` target's manual `go build` recipe; its `XCE="${XCE:-/tmp/xce_static}"` default is left as-is (an inert placeholder — callers are still expected to pass `XCE=` explicitly)
|
|
- Observable: neither file's live text names a `make` target anywhere; deleting `src/frontend/Makefile` and re-running each script's own failure path shows only Meson-based guidance
|
|
- _Requirements: 5.2, 5.3, 6.2_
|
|
- _Boundary: deploy-ha.sh, tests/regression/run.sh_
|
|
- _Depends: 1.1, 2_
|
|
|
|
- [x] 3.3 (P) Update live steering, skill, and status documentation
|
|
- Update every current-fact reference to a `src/frontend/Makefile` target or a Makefile-specific fixed path in: `tech.md` (Build Systems table and code block, plus the "Testing Requirements" lines), `build-deployment.md` (Go Frontend Build section), `testing.md` (Build targets bullets, Philosophy line, and the "What Not to Mock" CGO-bridge line), `structure.md`, `frontend/CLAUDE.md`, root `CLAUDE.md`'s Key Files entry, `src/docs/deployment.md`'s Build gotcha section, `xce-deploy-ha/SKILL.md` (all four references, including the Step 4d intro), `xce-test-resources/SKILL.md`'s `$XCE_RESVERIFY_APISERVER_BIN` default description, `src/frontend/docs/status.md`, and `src/docs/apiserver-backend-tasks.md`
|
|
- Replace each with the equivalent Meson-based guidance (`/xce-build apiserver`, `meson test --suite apiserver`, direct `tests/regression/run.sh` invocation) already established by tasks 1-3.2
|
|
- Observable: none of the 11 files contains a live `make (build-server|build-cli|test|test-backend|test-integration|test-all)` or `/tmp/apiserver`/`/tmp/xce_static` reference presented as current fact
|
|
- _Requirements: 6.1, 6.2, 6.3_
|
|
- _Boundary: Documentation set (11 files)_
|
|
- _Depends: 1.1, 2, 3.1_
|
|
|
|
- [x] 3.4 (P) Update source-code comments referencing the Makefile
|
|
- `src/controller/testsuite/test_ha_bootstrap.c` and `test_ha_ctrlhello.c`: rename their `make test-integration` pointers to reference the regression suite (`tests/regression/run.sh`) directly, with no change to test logic
|
|
- `src/frontend/apiserver/cmd/main.go` and `src/frontend/xcecli/cmd/main.go`: drop the Makefile clause from each ldflags-injection comment, keeping only `src/tools/go_build`
|
|
- Observable: none of the four files' comments name a `make` target; no production or test logic changes
|
|
- _Requirements: 1.2, 6.1, 6.2_
|
|
- _Boundary: test_ha_bootstrap.c, test_ha_ctrlhello.c, apiserver/cmd/main.go, xcecli/cmd/main.go_
|
|
- _Depends: 1.1, 2_
|
|
|
|
- [x] 3.5 (P) Verify the regression suite runs against a Meson-built binary with parity to the pre-migration baseline
|
|
- Run `tests/regression/run.sh` directly (`XCE=<meson-built xcecli path> URL=<live apiserver>`) against a live apiserver built via `/xce-build apiserver`
|
|
- Observable: the run reports the same PASS/FAIL/SKIP counts as the documented pre-migration `make test-integration` baseline, using no Makefile-built artifact
|
|
- _Requirements: 4.1, 4.2, 4.3_
|
|
- _Boundary: tests/regression/run.sh (verification only, no file changes)_
|
|
- _Depends: 1.1, 2_
|
|
|
|
- [x] 3.6 Run the live-reference sweep across the whole repository and confirm zero hits outside the named exclusion classes
|
|
- Grep the full repository for `make (build-server|build-cli|test|test-backend|test-integration|test-all)` and `/tmp/apiserver`/`/tmp/xce_static`; classify every hit as either fixed by 3.1-3.4 or falling into one of design.md's named exclusion classes (`.kiro/specs/**` historical spec documents, `**/vendor/**` third-party files, dated historical records, `roadmap.md`'s own backlog entry for this spec, OpenWolf's own logs, `run.sh:12`'s retained placeholder default)
|
|
- Observable: the sweep's full output is captured and every hit is accounted for by name — either as an already-completed fix or a cited exclusion class — with none left unexplained
|
|
- _Requirements: 5.3, 6.1, 6.2_
|
|
- _Depends: 3.1, 3.2, 3.3, 3.4_
|
|
|
|
- [x] 4. Validation: final regression gate and Makefile removal
|
|
- [x] 4.1 Run the full coverage-preservation validation suite as the final go/no-go gate before deletion
|
|
- Confirm: `/xce-build apiserver` and `/xce-build all` pass with the migrated unit-test invocation (task 2); `meson test -C <dir> --suite apiserver` passes including the new backend test target (task 1); the regression suite parity check (task 3.5) and the live-reference sweep (task 3.6) both already passed
|
|
- Observable: a single consolidated run confirms all four checks pass together against the same build, immediately before the Makefile is deleted
|
|
- _Requirements: 3.3, 4.3_
|
|
- _Depends: 1.2, 2, 3.5, 3.6_
|
|
|
|
- [x] 4.2 Delete src/frontend/Makefile and confirm no functional path still depends on it
|
|
- Delete the file; re-run the full coverage-preservation validation from 4.1 unchanged, confirming no regression from the deletion itself
|
|
- Re-run task 3.1's discovery scenario (`run-resource-verify.sh` locating the apiserver binary from the Meson build dir) with the Makefile now genuinely absent from disk — this closes design.md's Testing Strategy "Discovery-path regression" check, which specifically requires this to be re-verified post-deletion, not just pre-deletion
|
|
- Re-run the live-reference sweep (task 3.6's grep) one more time, full-repository, now that the file genuinely no longer exists
|
|
- Observable: `src/frontend/Makefile` no longer exists in the tree; the full validation suite, the post-deletion discovery-path re-check, and the post-deletion sweep all pass with no unaccounted hits
|
|
- _Requirements: 1.1, 1.2, 1.3, 5.1_
|
|
- _Depends: 4.1_
|
|
|
|
## Implementation Notes
|
|
|
|
- Task 4.2 (final): `src/frontend/Makefile` is deleted. Post-deletion review found two files with prose mentions of "src/frontend/Makefile" outside this spec's approved File Structure Plan and outside the sweep's regex pattern: `src/docs/resreq-ast-cse-design.md:3376` and `src/tools/test-version-startup-consistency.sh:49,63,69`. Both are comment-only with zero functional dependency (no executable `make` invocation), and were never in this spec's requirements/design scope -- flagged as a future doc-hygiene item, not reopened here.
|
|
- Task 4.1: task 3.6's commit message said "188 hits" for the live-reference sweep; the actual, reproducible count (verified both at commit `c554ed25` and now, byte-identical) is **190** -- a message-only miscount, not drift or a missed hit; all 190 were independently reclassified with zero unaccounted. Also confirmed via a full `meson test` run that the two failures blocking a literal `/xce-build all` are exactly bug-1723 and bug-1758 (pre-existing, unrelated, NOT FIXED) and nothing else. `.claude/skills/kiro-impl/SKILL.md:171` ("...to make test pass...") is a recurring grep false positive (generic TDD prose, not an XCE Makefile reference) that will keep showing up in any future sweep of this same pattern -- expected, not a new violation.
|
|
- Task 3.3 (round 1 rejection, fixed in round 2): when removing a stale Makefile reference from a doc, check whether the underlying script it describes still has a genuine fallback behavior before deleting the mention entirely. `run-resource-verify.sh` (task 3.1) removed its `/tmp/apiserver` fallback outright, so `xce-test-resources/SKILL.md` correctly dropped all mention of it. `deploy-ha.sh` (task 3.2) deliberately KEPT its `/tmp/apiserver` fallback logic (only removed the `make build-server` association from its text) — so `xce-deploy-ha/SKILL.md` needed to keep describing that fallback accurately (just without the Make instruction), not delete it. Two visually-similar edits, two different correct outcomes, because the two underlying scripts' behaviors diverged.
|
|
- Task 2: `/xce-build all` currently aborts (`set -euo pipefail`) at the pre-existing `meson test --print-errorlogs` step, BEFORE reaching the migrated Go-test line — two unrelated, already-logged C-side failures (bug-1723, LeakSanitizer on `xcelib_test`; bug-1758, `sched_core_events_test` deterministic failure), both predating this spec. Task 2's `all`-case line itself is verified (byte-identical to the fully-verified `apiserver`-case line), but this means task 4.1's "final go/no-go gate" and task 4.2's post-deletion re-validation will hit the SAME pre-existing abort when running `/xce-build all` — those tasks will need to either scope their validation to `/xce-build apiserver` + a separate `meson test` invocation that tolerates these 2 known-unrelated failures, or note them as pre-existing/out-of-scope rather than treating them as a regression from this spec.
|
|
- Task 1.2: design.md's Testing Strategy suggests `librtti_dep` as the example dependency to remove when proving the new backend test() exercises the real CGO path. Empirically (implementer + independent reviewer both reproduced this live), removing `librtti_dep` does NOT reproduce a link failure for the `apiserver/backend/...` test package — none of `librtti`'s exported symbols are actually pulled into this specific link unit's undefined-symbol set. `c_capnproto_dep` (real `capn_*` undefined-reference errors from `request.c`/`controller.capnp.c`) is the dependency that genuinely reproduces the failure and was used instead. `apiserver_cgo_deps` itself was left byte-identical to task 1.1's state (verification-only task, no permanent code change).
|