From 1c2f44ae83fed3745d9934a1267dfcacb967b9a9 Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Mon, 28 Sep 2026 13:03:41 +0200 Subject: [PATCH] docs(10.2-01): summarize modules migration --- .../10.2-01-SUMMARY.md | 118 ++++++++++++++++++ 1 file changed, 118 insertions(+) create mode 100644 .planning/phases/10.2-nest-framework-packages-under-modules-and-write-run-docs/10.2-01-SUMMARY.md diff --git a/.planning/phases/10.2-nest-framework-packages-under-modules-and-write-run-docs/10.2-01-SUMMARY.md b/.planning/phases/10.2-nest-framework-packages-under-modules-and-write-run-docs/10.2-01-SUMMARY.md new file mode 100644 index 0000000..224d0d2 --- /dev/null +++ b/.planning/phases/10.2-nest-framework-packages-under-modules-and-write-run-docs/10.2-01-SUMMARY.md @@ -0,0 +1,118 @@ +--- +phase: 10.2-nest-framework-packages-under-modules-and-write-run-docs +plan: "01" +subsystem: framework-layout +tags: [go, modules, imports, monorepo, migration] + +requires: + - phase: 10-admin-vue-spa + provides: complete framework and Fonoteka consumers before the package-layout migration +provides: + - all 18 beach-named framework packages nested under modules/ with package names unchanged + - nested import paths across summercms.go, examples/hello, and fonoteka.go + - retargeted build stubs, validation scripts, Vite output, and repository-relative tests + - green vet and test matrix for both repositories and all nested Go modules +affects: [10.2-02, 11] + +actuals: + tasks: 3 + commits: 7 +plan_head_before: a9a7bbef73e7e61b01796d9803c06367ab06c34b +plan_head_after: 57e7b56983d2cb4032fbf44aa6bcc433d4dab96c +app_plan_head_before: 21c0f12 +app_plan_head_after: e8b22d3078b7811fb736c45866c71813fc10c5e4 + +tech-stack: + added: [] + patterns: + - Framework libraries live at modules/ while retaining their existing Go package names + - Historical planning evidence remains immutable; executable audits translate historical package columns to the current modules/ layout + - Nested-module examples are vetted and compiled explicitly because root ./... does not traverse them + +key-files: + created: + - modules/ + modified: + - cmd/summer/** + - internal/build/** + - examples/hello/** + - scripts/check-phase*.sh + - scripts/check-admin-*.sh + - admin/vite.config.ts + - ../fonoteka.go/app/** + - ../fonoteka.go/parity/** + - ../fonoteka.go/plugins/** + +key-decisions: + - "Kept the migration as one tracer task plus one bulk task: the change is mechanically broad but one atomic import-graph rewrite." + - "Kept one root go.mod and the existing go.work entries; modules/ is an organizational directory, not a Go multi-module boundary." + - "Updated the Fonoteka parity audit instead of rewriting historical Phase 08 evidence." + +requirements-completed: [] + +coverage: + - id: D-01-D-06 + description: "All framework packages are nested, all controlled consumers resolve the new imports, and both repositories remain green." + verification: + - kind: unit + ref: "go vet ./... && go test ./..." + status: pass + - kind: integration + ref: "go vet/go test for examples/hello plus base, greeter, and optional nested modules" + status: pass + - kind: integration + ref: "go vet/go test in ../fonoteka.go including both plugin modules" + status: pass + human_judgment: false + +completed: 2026-09-28 +status: complete +--- + +# Phase 10.2 Plan 01: Nest framework packages under modules Summary + +**All 18 framework packages now live under `modules/`; every controlled importer and path-sensitive tool follows the new layout, and the complete two-repository Go validation matrix passes.** + +## Accomplishments + +- Proved the migration with `festival`, including its framework, example, and Fonoteka importers. +- Moved the remaining 17 packages with history-preserving renames and retained all existing Go package names. +- Rewrote imports across the framework, generator templates, nested examples, and 125 Fonoteka consumer files. +- Retargeted admin output, OpenAPI/dist checks, phase gates, fixture paths, and source-audit paths that depended on the old repository-relative layout. +- Verified the root framework module, all four `examples/hello` module contexts, the Fonoteka root, and both Fonoteka plugin modules with `go vet` and `go test`. + +## Task Commits + +1. **Task 1: festival tracer.** `ac1f6d1` (summercms.go), `32bd982` (fonoteka.go) +2. **Task 2: remaining packages and all importers/path literals.** `5e50b16` (summercms.go), `03a417a` (fonoteka.go) +3. **Task 3: full validation and phase-caused fixture/audit fixes.** `57e7b56` (summercms.go), `e8b22d3` (fonoteka.go) + +**Plan metadata:** committed separately with this summary. + +## Decisions Made + +- The two-plan lean structure was retained. Splitting a single import-graph rewrite by arbitrary file count would have introduced broken intermediate states or temporary compatibility scaffolding. +- No package aliases, forwarding packages, new `go.mod` files, or dependency changes were introduced. +- Historical `.planning/phases/**` paths were left unchanged. The live Fonoteka audit maps their `summercms.go` package column into the current `modules/` directory. + +## Deviations from Plan + +### Auto-fixed issues + +1. **Five moved tests retained repository-relative paths.** Two CLI parity tests still referenced root `tide`, two cabana tests resolved root `admin/` from one directory too shallow, and phrasebook did the same. Their path calculations were updated after the first full test pass exposed them. +2. **Fonoteka's historical PHP-test-map audit interpreted `wristband` as a current root directory.** The audit now prefixes framework package rows with `modules/`, preserving the historical Phase 08 document exactly as required. +3. **Sandbox-only validation failures.** Localhost listeners and the default Go build cache were unavailable inside the restricted sandbox. The identical validation command was rerun outside it; the command then exposed the real stale audit path above and passed after that fix. + +## Verification + +- `go vet ./... && go test ./...` in summercms.go: pass +- Explicit vet and compile-only test across `examples/hello`, `base`, `greeter`, and `optional`: pass +- `go vet` and `go test` in fonoteka.go including both plugin modules: pass +- No root beach-package directories or per-package `go.mod` files remain. + +## Self-Check: PASSED + +- Root commits present: `ac1f6d1`, `5e50b16`, `57e7b56` +- Fonoteka commits present: `32bd982`, `03a417a`, `e8b22d3` +- `modules/festival`, `modules/compass`, and `modules/boardwalk/dist` exist. +- Full declared Task 3 validation exits 0.