docs(quick-261118-qsd): compile module README Go examples via src= references
This commit is contained in:
@@ -5,10 +5,10 @@ current_phase: 30
|
|||||||
current_phase_name: Płytarium cutover
|
current_phase_name: Płytarium cutover
|
||||||
status: planning
|
status: planning
|
||||||
stopped_at: Phase 35 complete, ready to plan Phase 30
|
stopped_at: Phase 35 complete, ready to plan Phase 30
|
||||||
last_updated: "2026-11-18T14:50:07.827Z"
|
last_updated: "2026-11-18T19:24:37.982Z"
|
||||||
last_activity: 2026-11-18
|
last_activity: 2026-11-18
|
||||||
last_activity_desc: "Completed quick task 261118-lbt: per-app plugin instances, closable limiter store, one router build"
|
last_activity_desc: "Completed quick task 261118-qsd: module README Go examples compiled via src="
|
||||||
state_head: 38f7f3a77757cd456601cd5e31e0a29b7338612c
|
state_head: 8c03cc362190f72d8ba24e8fcc60bc09a5f26cc7
|
||||||
progress:
|
progress:
|
||||||
total_phases: 52
|
total_phases: 52
|
||||||
completed_phases: 37
|
completed_phases: 37
|
||||||
@@ -33,7 +33,7 @@ See: .planning/PROJECT.md (updated 2026-10-22)
|
|||||||
Phase: 30 — Płytarium cutover
|
Phase: 30 — Płytarium cutover
|
||||||
Plan: Not started
|
Plan: Not started
|
||||||
Status: Ready to plan
|
Status: Ready to plan
|
||||||
Last activity: 2026-11-18 — Completed quick task 261118-lbt: per-app plugin instances, closable limiter store, one router build
|
Last activity: 2026-11-18 — Completed quick task 261118-qsd: module README Go examples compiled via src=
|
||||||
|
|
||||||
Progress: [████████░░] 77%
|
Progress: [████████░░] 77%
|
||||||
|
|
||||||
@@ -1138,36 +1138,16 @@ Recent decisions affecting current work:
|
|||||||
|
|
||||||
- [2026-10-01] [docs] Benchmark Płytarium on WinterCMS vs SummerCMS and publish a measured table — [todo file](.planning/todos/pending/2026-10-01-benchmark-the-application-on-wintercms-vs-summercms.md)
|
- [2026-10-01] [docs] Benchmark Płytarium on WinterCMS vs SummerCMS and publish a measured table — [todo file](.planning/todos/pending/2026-10-01-benchmark-the-application-on-wintercms-vs-summercms.md)
|
||||||
- [2026-10-07] [sm-translate-plugin] Translate Messages as a Nuxt i18n JSON editor — [todo file](.planning/todos/pending/2026-10-07-translate-messages-as-nuxt-i18n-json-editor.md)
|
- [2026-10-07] [sm-translate-plugin] Translate Messages as a Nuxt i18n JSON editor — [todo file](.planning/todos/pending/2026-10-07-translate-messages-as-nuxt-i18n-json-editor.md)
|
||||||
- [2026-10-10] [framework] Prompt open admin and site tabs to reload when a new version is deployed — [todo file](.planning/todos/pending/2026-10-11-reload-open-apps-when-a-new-version-is-deployed.md) — Needs TBD. Ideas:.
|
|
||||||
- [2026-10-11] [lagoon/attach, fonoteka.go uploads] Uploads keep the client file extension, so a valid image can be served as HTML (stored XSS) — [todo file](.planning/todos/pending/2026-10-11-uploads-keep-client-extension-stored-xss.md)
|
|
||||||
- [unknown] [sm-user-plugin / cabana] Verified link between a frontend user and a backend user — [todo file](.planning/todos/pending/2026-10-17-frontend-backend-account-link.md)
|
|
||||||
- [unknown] [sm-user-plugin / pact] Plugins register their frontend permission codes in Go — [todo file](.planning/todos/pending/2026-10-17-plugin-registered-frontend-permissions.md)
|
|
||||||
- [2026-10-19] [sm-oauthserver-plugin] Record PHP OIDC parity against WavePath before the OIDC cutover — [todo file](.planning/todos/pending/2026-10-19-record-php-oidc-parity-against-wavepath.md)
|
- [2026-10-19] [sm-oauthserver-plugin] Record PHP OIDC parity against WavePath before the OIDC cutover — [todo file](.planning/todos/pending/2026-10-19-record-php-oidc-parity-against-wavepath.md)
|
||||||
- [2026-10-20] [consumers] Move grzybyfunkcjonalne to NUXT_CACHE_PURGE_TOKEN and the new layers before the NUXT_SITE_CACHE_* names are dropped — [todo file](.planning/todos/pending/2026-10-20-rename-site-cache-purge-env-in-consumers.md)
|
- [2026-10-28] [framework] Earlier phase gate scripts still name consuming applications — [todo file](.planning/todos/pending/2026-10-28-earlier-phase-gates-name-consuming-apps.md)
|
||||||
- [2026-10-21] [framework] Quiet plugin boot logs on console commands like --help — [todo file](.planning/todos/pending/2026-10-21-quiet-plugin-boot-logs-on-console-commands.md) — Needs TBD. Options, possibly combined:.
|
- [2026-10-29] [consumers] Stream-aware previous/next links on the summercms.io changelog — [todo file](.planning/todos/pending/2026-10-29-stream-aware-previous-next-on-summercms-io-changelog.md)
|
||||||
- [2026-10-22] [framework] Console review info findings (IN-01..IN-13) and the delegate signal exit code — [todo file](.planning/todos/pending/2026-10-22-console-review-info-findings.md)
|
- [unknown] [vue-chat-layer app/composables/useChat.ts] Chat messages that start with "/" but name no command are posted as text — [todo file](.planning/todos/pending/chat-slash-text-escape.md)
|
||||||
- [2026-10-22] [sm-user-plugin] User login ignores is_activated — [todo file](.planning/todos/pending/2026-10-22-user-login-ignores-is-activated.md)
|
- [unknown] [vue-forum-layer app/utils/forumClient.ts, vue-userfriends-layer app/utils/friendsClient.ts] Single-flight 401 refresh in the forum and friends clients,… — [todo file](.planning/todos/pending/forum-friends-client-401-refresh.md)
|
||||||
- [2026-10-22] [sm-user-plugin] User login lockout and same-second cutoff — [todo file](.planning/todos/pending/2026-10-22-user-login-lockout-and-same-second-cutoff.md)
|
|
||||||
- [2026-10-22] [sm-user-plugin] User login opt-in session cookie — [todo file](.planning/todos/pending/2026-10-22-user-login-opt-in-session-cookie.md)
|
|
||||||
- [2026-10-22] [sm-user-plugin] User logout blacklist missing under serve — [todo file](.planning/todos/pending/2026-10-22-user-logout-blacklist-missing-under-serve.md)
|
|
||||||
- [2026-10-22] [user-plugin] User plugin logout leaves the session cookie valid for up to 60 minutes — [todo file](.planning/todos/pending/2026-10-22-user-logout-cookie-stays-valid.md)
|
|
||||||
- [2026-10-22] [sm-user-plugin] User password routes 404 switch — [todo file](.planning/todos/pending/2026-10-22-user-password-routes-404-switch.md)
|
|
||||||
- [2026-10-22] [sm-user-plugin] User session routes ignore the cookie — [todo file](.planning/todos/pending/2026-10-22-user-session-routes-ignore-cookie.md)
|
|
||||||
- [unknown] [cabana / admin] Audit-log admin action runs with the admin id (toolbar actions) — [todo file](.planning/todos/pending/admin-action-audit-log.md)
|
|
||||||
- [unknown] [sm-faq-plugin] Port the FAQ plugin as sm-faq-plugin so FAQs become editable — [todo file](.planning/todos/pending/faq-plugin-port.md)
|
|
||||||
- [unknown] [summercms.go lagoon] lagoon README registers an after-commit GORM callback that can sort after the flush — [todo file](.planning/todos/pending/lagoon-readme-after-commit-callback-order.md)
|
|
||||||
- [unknown] [sm-user-plugin mail] Port MailBlocker and the block-mail checkbox with the mailing work — [todo file](.planning/todos/pending/mailblocker-with-mailing.md)
|
- [unknown] [sm-user-plugin mail] Port MailBlocker and the block-mail checkbox with the mailing work — [todo file](.planning/todos/pending/mailblocker-with-mailing.md)
|
||||||
- [unknown] [sm-menu-plugin] Port the menu plugin as sm-menu-plugin so blog menus become editable — [todo file](.planning/todos/pending/menu-plugin-port.md)
|
- [unknown] [sm-menu-plugin] Port the menu plugin as sm-menu-plugin so blog menus become editable — [todo file](.planning/todos/pending/menu-plugin-port.md)
|
||||||
|
- [unknown] [sm-demo-app plugins/demo/moderation.go (with seams in user, userfriends and chat)] Moderate profile names, friend-group names and chat attachment… — [todo file](.planning/todos/pending/moderation-profile-group-and-filenames.md)
|
||||||
- [2026-10-21] [sm-user-plugin] Let password-less social accounts set a first password through change-password — [todo file](.planning/todos/pending/oauth-password-bootstrap-change-password.md)
|
- [2026-10-21] [sm-user-plugin] Let password-less social accounts set a first password through change-password — [todo file](.planning/todos/pending/oauth-password-bootstrap-change-password.md)
|
||||||
- [unknown] [summercms.go/modules/*/README.md, internal/docsite] Convert module README Go code blocks to compiled src= references — [todo file](.planning/todos/pending/readme-go-fences-src.md)
|
|
||||||
- [unknown] [../fonoteka.go/README.md] Refresh fonoteka.go README — short status plus migrate/serve/login — [todo file](.planning/todos/pending/refresh-fonoteka-readme.md)
|
- [unknown] [../fonoteka.go/README.md] Refresh fonoteka.go README — short status plus migrate/serve/login — [todo file](.planning/todos/pending/refresh-fonoteka-readme.md)
|
||||||
- [unknown] [cabana] Show the administrators holding a role on the Roles screen — [todo file](.planning/todos/pending/roles-screen-holders-list.md)
|
|
||||||
- [unknown] [summercms.go internal/build] make:admin-controller output does not boot and names the model after the controller — [todo file](.planning/todos/pending/scaffold-admin-controller-incomplete.md)
|
|
||||||
- [unknown] [summercms.go internal/build] Scaffolded files carry a DO NOT EDIT header, and make:command cannot reach the application — [todo file](.planning/todos/pending/scaffold-generated-header-and-command-deps.md)
|
|
||||||
- [unknown] [summercms.go internal/build] make:model and make:migration in the same second produce migrations that run out of order — [todo file](.planning/todos/pending/scaffold-same-second-migration-order.md)
|
|
||||||
- [2026-10-12] [framework] Purge the Nuxt site cache on menu and FAQ admin saves (framework-level purge service) — [todo file](.planning/todos/pending/site-cache-purge-for-menu-and-faq.md)
|
|
||||||
- [unknown] [sm-sitemap-plugin] Port the sitemap plugin 1:1 as sm-sitemap-plugin for the next blog project — [todo file](.planning/todos/pending/sitemap-plugin-port.md)
|
|
||||||
- [unknown] [sm-sitemap-plugin] Sitemap - replace the browser XSLT view before Chromium drops XSLT — [todo file](.planning/todos/pending/sitemap-xslt-browser-deprecation.md)
|
|
||||||
|
|
||||||
### Blockers/Concerns
|
### Blockers/Concerns
|
||||||
|
|
||||||
@@ -1273,6 +1253,7 @@ Recent decisions affecting current work:
|
|||||||
| 261114-p5n | Style the user and paymentgateway plugin mail layouts like the postcard default layout | 2026-11-14 | 4ef3aa1f | [261114-p5n-style-the-user-and-paymentgateway-plugin](./quick/261114-p5n-style-the-user-and-paymentgateway-plugin/) |
|
| 261114-p5n | Style the user and paymentgateway plugin mail layouts like the postcard default layout | 2026-11-14 | 4ef3aa1f | [261114-p5n-style-the-user-and-paymentgateway-plugin](./quick/261114-p5n-style-the-user-and-paymentgateway-plugin/) |
|
||||||
| 261115-cha | Let a mail template use another plugin's layout by full code (G-35-9) | 2026-11-15 | b8487b02 | [261115-cha-let-a-mail-template-use-another-plugin-s](./quick/261115-cha-let-a-mail-template-use-another-plugin-s/) |
|
| 261115-cha | Let a mail template use another plugin's layout by full code (G-35-9) | 2026-11-15 | b8487b02 | [261115-cha-let-a-mail-template-use-another-plugin-s](./quick/261115-cha-let-a-mail-template-use-another-plugin-s/) |
|
||||||
| 261118-lbt | Per-app plugin instances, closable limiter store, one router build | 2026-11-18 | 38f7f3a7 | [261118-lbt-per-app-plugin-instances-closable-limite](./quick/261118-lbt-per-app-plugin-instances-closable-limite/) |
|
| 261118-lbt | Per-app plugin instances, closable limiter store, one router build | 2026-11-18 | 38f7f3a7 | [261118-lbt-per-app-plugin-instances-closable-limite](./quick/261118-lbt-per-app-plugin-instances-closable-limite/) |
|
||||||
|
| 261118-qsd | Compile module README Go examples via src= references | 2026-11-18 | 8c03cc36 | [261118-qsd-compile-module-readme-go-examples-via-sr](./quick/261118-qsd-compile-module-readme-go-examples-via-sr/) |
|
||||||
|
|
||||||
## Deferred Items
|
## Deferred Items
|
||||||
|
|
||||||
|
|||||||
@@ -0,0 +1,362 @@
|
|||||||
|
---
|
||||||
|
phase: quick-261118-qsd
|
||||||
|
plan: 01
|
||||||
|
type: execute
|
||||||
|
wave: 1
|
||||||
|
depends_on: []
|
||||||
|
files_modified:
|
||||||
|
- internal/docsite/snippet.go
|
||||||
|
- internal/docsite/render.go
|
||||||
|
- internal/docsite/check_policy.go
|
||||||
|
- internal/docsite/checks_test.go
|
||||||
|
- internal/docsite/render_test.go
|
||||||
|
- internal/docsite/snippet_test.go
|
||||||
|
- docs/console/utilities.md
|
||||||
|
- README.md
|
||||||
|
- CLAUDE.md
|
||||||
|
- modules/breakwater/README.md
|
||||||
|
- modules/breakwater/example_test.go
|
||||||
|
- modules/backpack/README.md
|
||||||
|
- modules/backpack/example_test.go
|
||||||
|
- modules/beachcomber/README.md
|
||||||
|
- modules/beachcomber/example_test.go
|
||||||
|
- modules/boardwalk/README.md
|
||||||
|
- modules/boardwalk/example_test.go
|
||||||
|
- modules/bonfire/README.md
|
||||||
|
- modules/bonfire/example_test.go
|
||||||
|
- modules/bouncer/README.md
|
||||||
|
- modules/bouncer/example_test.go
|
||||||
|
- modules/cabana/README.md
|
||||||
|
- modules/cabana/example_test.go
|
||||||
|
- modules/compass/README.md
|
||||||
|
- modules/compass/example_test.go
|
||||||
|
- modules/conga/README.md
|
||||||
|
- modules/conga/example_test.go
|
||||||
|
- modules/cooler/README.md
|
||||||
|
- modules/cooler/example_test.go
|
||||||
|
- modules/diary/README.md
|
||||||
|
- modules/diary/example_test.go
|
||||||
|
- modules/festival/README.md
|
||||||
|
- modules/festival/example_test.go
|
||||||
|
- modules/fetchguard/README.md
|
||||||
|
- modules/fetchguard/example_test.go
|
||||||
|
- modules/flare/README.md
|
||||||
|
- modules/flare/example_test.go
|
||||||
|
- modules/kiosk/README.md
|
||||||
|
- modules/kiosk/example_test.go
|
||||||
|
- modules/lagoon/README.md
|
||||||
|
- modules/lagoon/example_test.go
|
||||||
|
- modules/lighthouse/README.md
|
||||||
|
- modules/lighthouse/example_test.go
|
||||||
|
- modules/pact/README.md
|
||||||
|
- modules/pact/example_test.go
|
||||||
|
- modules/party/README.md
|
||||||
|
- modules/party/example_test.go
|
||||||
|
- modules/phrasebook/README.md
|
||||||
|
- modules/phrasebook/example_test.go
|
||||||
|
- modules/pier/README.md
|
||||||
|
- modules/pier/example_test.go
|
||||||
|
- modules/postcard/README.md
|
||||||
|
- modules/postcard/example_test.go
|
||||||
|
- modules/seaglass/README.md
|
||||||
|
- modules/seaglass/example_test.go
|
||||||
|
- modules/sieve/README.md
|
||||||
|
- modules/sieve/example_test.go
|
||||||
|
- modules/signpost/README.md
|
||||||
|
- modules/signpost/example_test.go
|
||||||
|
- modules/sunrise/README.md
|
||||||
|
- modules/sunrise/example_test.go
|
||||||
|
- modules/sunscreen/README.md
|
||||||
|
- modules/sunscreen/example_test.go
|
||||||
|
- modules/surf/README.md
|
||||||
|
- modules/surf/example_test.go
|
||||||
|
- modules/tide/README.md
|
||||||
|
- modules/tide/example_test.go
|
||||||
|
- modules/towel/README.md
|
||||||
|
- modules/towel/example_test.go
|
||||||
|
- modules/wire/README.md
|
||||||
|
- modules/wire/example_test.go
|
||||||
|
- modules/wristband/README.md
|
||||||
|
- modules/wristband/example_test.go
|
||||||
|
autonomous: true
|
||||||
|
requirements:
|
||||||
|
- QUICK-261118-qsd
|
||||||
|
|
||||||
|
estimate:
|
||||||
|
tokens: 230000
|
||||||
|
raw_tokens: 230000
|
||||||
|
tasks: 3
|
||||||
|
confidence: low
|
||||||
|
|
||||||
|
must_haves:
|
||||||
|
truths:
|
||||||
|
- "summer docs:build --check treats a top-level src= fence in a module README exactly like one in a docs/ page: a body equal to its source passes, a drifted body reports 'body differs from <ref> (run: summer docs:sync)' at the README's own line, a missing target reports '<ref> not found', and a target the run rule refuses (Example without // Output:, file outside the root, dotfile or .env, testdata, nested module) is refused with the existing message; a src= fence nested in a list item, callout or blockquote of a README is refused with the nested-fence message. The old blanket refusal of src= in module READMEs no longer exists"
|
||||||
|
- "summer docs:sync rewrites the drifted top-level src= fence bodies of every modules/<name>/README.md as well as the docs/ pages, leaves every other byte of the README unchanged (summary line, prose, other fences), and writes nothing in any file when any page or README has a refused reference; on the real tree it prints 'docs:sync: all snippets up to date' after the conversion"
|
||||||
|
- "The built API page of a module (site/api/<name>.html) captions each top-level src= fence with a figcaption naming the reference and linking it through source_url, like docs/ pages; nested fences get no caption"
|
||||||
|
- "Every Go code block in modules/*/README.md (68 fences in 32 READMEs at the start) is a top-level src= reference into compiled test code of its module that go test runs: an Example with an // Output: comment, a docs:start/docs:end region inside a function a Test or Example-with-Output calls, or a top-level declaration such a function uses; no bare go fence remains, and any fence whose language tag was changed instead is listed in the SUMMARY with its reason (expected: none)"
|
||||||
|
- "The page policy refuses a Go-lexer fence without src= in module READMEs too (the README exemption in check_policy.go is gone), proven by internal/docsite tests; heading rules still apply to docs/ pages only"
|
||||||
|
- "Every new or changed example runs offline under go test -short (deterministic Example output, httptest, fstest, in-memory config); code that needs Postgres, River or Redis sits in a region of a helper that a TestDocs* test runs through the existing Docker helpers (lagoon.DocsDB, conga.DocsApp, lighthouse.DocsEnv and the like), which skip under -short; no test references a function only to make it reachable"
|
||||||
|
- "No module's exported API changes: under modules/ only README.md and _test.go files change, go.mod and go.sum are unchanged, and PHASE35_BASE_TAG=v0.6.5 scripts/check-phase35.sh --additive passes"
|
||||||
|
- "docs/console/utilities.md, the root README.md and CLAUDE.md describe src= in module READMEs (checked by docs:build, refreshed by docs:sync, required on every Go code block) in the same commit as the behaviour change"
|
||||||
|
artifacts:
|
||||||
|
- path: internal/docsite/snippet.go
|
||||||
|
provides: "checkSnippets runs checkFences on every page (docs/ and module README); Sync walks the docs pages plus each modules/<name>/README.md that moduleNames lists; the README src= refusal constant and its branch are removed"
|
||||||
|
- path: internal/docsite/render.go
|
||||||
|
provides: "fenceAnnotator captions top-level src= fences on every page, not only docs/ pages"
|
||||||
|
- path: internal/docsite/check_policy.go
|
||||||
|
provides: "checkPolicy requires src= on every Go-lexer fence of every page, module READMEs included; headings still checked on docs/ pages only"
|
||||||
|
- path: internal/docsite/snippet_test.go
|
||||||
|
provides: "TestSyncModuleReadme: drifted README fence rewritten byte-exact, second Sync a no-op, a refused README fence blocks every write"
|
||||||
|
- path: internal/docsite/checks_test.go
|
||||||
|
provides: "README src= fences checked (match, drift, nested refusal) and, after task 3, a bare README go fence reported as having no src= reference"
|
||||||
|
- path: internal/docsite/render_test.go
|
||||||
|
provides: "caption test: top-level README src= fence captioned once, nested fence not captioned"
|
||||||
|
- path: modules/breakwater/example_test.go
|
||||||
|
provides: "tracer target: ExampleRender and ExamplePurify referenced from the breakwater README"
|
||||||
|
- path: modules/seaglass/example_test.go
|
||||||
|
provides: "new example file for the seaglass README fence"
|
||||||
|
- path: modules/boardwalk/example_test.go
|
||||||
|
provides: "new example file for the boardwalk README fence"
|
||||||
|
- path: modules/sunrise/example_test.go
|
||||||
|
provides: "new example file for the sunrise README fence"
|
||||||
|
key_links:
|
||||||
|
- from: "modules/*/README.md go src= fences"
|
||||||
|
to: "modules/*/example*_test.go Examples, regions and declarations"
|
||||||
|
via: "docsite.Extract run rule (reachable from a Test or an Example with // Output:)"
|
||||||
|
pattern: "go src=modules/"
|
||||||
|
- from: "internal/docsite checkSnippets / Sync"
|
||||||
|
to: "module README pages"
|
||||||
|
via: "checkFences over README bodies; Sync file list extended with moduleNames(Root) READMEs"
|
||||||
|
pattern: "moduleNames"
|
||||||
|
- from: "internal/docsite fenceAnnotator"
|
||||||
|
to: "codeRenderer figcaption on api/<name> pages"
|
||||||
|
via: "data-src / data-href attributes on top-level src= fences of any page"
|
||||||
|
pattern: "data-src"
|
||||||
|
---
|
||||||
|
|
||||||
|
<objective>
|
||||||
|
Compile every Go code block of the module READMEs. Each block becomes a `src=` reference into the module's example test code, so `go test` compiles and runs it, `summer docs:build --check` compares the README copy with its source, and `summer docs:sync` keeps it current. This implements the pending todo `.planning/todos/pending/readme-go-fences-src.md` (g15office gplauwlb).
|
||||||
|
|
||||||
|
Purpose: Phase 11.1 (D-18) publishes every module README as an `api/<name>` page, but its 68 Go blocks are only identifier-checked, so they rot silently. After this task, every Go example on the docs site is compiled and run code.
|
||||||
|
|
||||||
|
Output: internal/docsite accepts, checks, captions and syncs `src=` fences in module READMEs. Every module README Go fence references compiled test code. The README exemption from the src= policy is removed. The docs pages describe the new rule.
|
||||||
|
</objective>
|
||||||
|
|
||||||
|
<execution_context>
|
||||||
|
@~/.claude/msd-core/workflows/execute-plan.md
|
||||||
|
@~/.claude/msd-core/templates/summary.md
|
||||||
|
</execution_context>
|
||||||
|
|
||||||
|
<context>
|
||||||
|
@CLAUDE.md
|
||||||
|
@.planning/STATE.md
|
||||||
|
@.planning/todos/pending/readme-go-fences-src.md
|
||||||
|
@internal/docsite/snippet.go
|
||||||
|
@internal/docsite/check_policy.go
|
||||||
|
@internal/docsite/render.go
|
||||||
|
@docs/console/utilities.md
|
||||||
|
|
||||||
|
Key facts gathered while planning (line numbers as of HEAD 830f3053):
|
||||||
|
|
||||||
|
- internal/docsite/snippet.go: `checkFences` (~541) already does all of the per-fence work: the top-level rule, Extract, drift detection. `checkSnippets` (~602) skips module README pages (`d.page.Module != ""`) and emits the README refusal (constant ~533-536) for every src= fence in them. `Sync` (~635) only walks `walkPages(opts.Src)`, which covers docs/ alone.
|
||||||
|
- internal/docsite/render.go `fenceAnnotator` (~52-78): `verified` requires `pctx.page.Module == ""`, so README fences never get a caption.
|
||||||
|
- internal/docsite/check_policy.go `checkPolicy` (~19-44): the "Go-lexer fence needs src=" rule runs only when `guide` (`Module == ""`). `headingProblems` is also guide-only and must stay that way.
|
||||||
|
- internal/docsite/load.go: `moduleNames(root)` (~375) lists modules/<name> directories that hold a non-test .go file. `loadModules` builds README pages with `BodyLine: 1` and the summary line blanked, so line indices match the file. A README has no frontmatter, so `splitFrontmatter` returns ok=false and Sync's existing path gives body = raw and bodyLine = 1.
|
||||||
|
- The run rule in `Extract`/`extractIdent` refuses an Example without `// Output:` ("compiled but never run"). The todo description suggests Output-less Examples; that route is NOT available and this plan does not weaken the rule (see Conversion rules R2).
|
||||||
|
- Tests that encode the old behaviour: checks_test.go `TestNestedFenceChecks` (~472-535) expects the README refusal at README:11 and implicitly no problem for the bare `go` fence at README:7. render_test.go `TestFenceCaptionsOnlyVerified` (~74-102) asserts that the README gets no caption. snippet_test.go has `TestSyncPreservesAndReports` and `TestSyncParsedFences` as Sync patterns, plus the `snippetTree` helper.
|
||||||
|
- docs:serve's `addWatches` (serve.go ~205) already scans every page from `Pages()` (READMEs included) for src= directories. No change is needed there.
|
||||||
|
- Existing conventions to copy: lagoon/example_test.go (regions inside helpers, e.g. `create-post` in `createPost`, run by `TestDocsModels` via `lagoon.DocsDB`, which skips under -short), surf/beachcomber/cabana `TestDocsDeclarations` (a Test that calls each shown method and asserts its result, so `#Type.Method` declarations are reachable), docs/backend/settings.md and docs/database/*.md for src= info strings. Docker helpers: modules/lagoon/export_docs_test.go `DocsDB`, modules/conga/export_docs_test.go `DocsApp`, modules/lighthouse/export_docs_test.go `DocsEnv`, modules/beachcomber/export_docs_test.go.
|
||||||
|
- Fence inventory at HEAD (`grep -c` of go fences per README, 68 total): backpack 1, beachcomber 3, boardwalk 1, bonfire 2, bouncer 2, breakwater 1, cabana 1, compass 1, conga 6, cooler 3, diary 2, festival 1, fetchguard 2, flare 2, kiosk 4, lagoon 4, lighthouse 5, pact 2, party 2, phrasebook 1, pier 1, postcard 5, seaglass 1, sieve 1, signpost 4, sunrise 1, sunscreen 2, surf 1, tide 2, towel 1, wire 1, wristband 2. None are nested, and none use a `golang` tag. boardwalk, seaglass and sunrise have no example test file yet. pier has example_mcp_test.go (package pier_test, no build tag): reuse it or add example_test.go.
|
||||||
|
- No scaffold or gate script writes Go fences into module READMEs. scripts/check-phase11.1.sh does not assert the README refusal.
|
||||||
|
|
||||||
|
## Conversion rules (tasks 2 and 3; task 1 applies them to breakwater)
|
||||||
|
|
||||||
|
R1 Reuse first. If the module's example*_test.go already has an Example with `// Output:`, a declaration, or a docs:start region that shows the same API as the README fence, point the README at it and do not duplicate code. Examples: breakwater ExampleRender/ExamplePurify, pact ExampleHasSchedule, surf ExampleAssembleRouter, kiosk ExampleNewestCompatible, festival ExampleBus_Fire. Check the existing Examples and regions first, with grep for `func Example`, `docs:start` and `func TestDocs`.
|
||||||
|
|
||||||
|
R2 Accepted target kinds (internal/docsite Extract):
|
||||||
|
(a) `#ExampleName`: an Example with an `// Output:` comment. The README shows its body dedented, Output lines included.
|
||||||
|
(b) `#region`: `// docs:start region` and `// docs:end region` lines inside ONE function that a Test or an Example-with-Output calls.
|
||||||
|
(c) `#Ident` or `#Type.Method`: a top-level declaration in the test file that a reachable function calls or uses. Follow the TestDocsDeclarations convention: the Test calls each shown method and asserts its result.
|
||||||
|
|
||||||
|
An Example without `// Output:` is refused by the checker, so the todo's "Output-less Example" suggestion is not used. Do not change the run rule. Do not use a fragment-less (whole-file) src= to a _test.go file: it bypasses the run check.
|
||||||
|
|
||||||
|
R3 Runs offline under -short:
|
||||||
|
- Use deterministic Example output, httptest.NewServer/NewRecorder, testing/fstest.MapFS or t.TempDir, and backpack.New with in-memory compass config, as the existing examples do.
|
||||||
|
- Code that needs Postgres, River or Redis goes in a docs:start region of a helper function, called from a TestDocs* test that gets its environment from the module's existing Docker helper. Those helpers skip under -short. Reachability is static, so docs:build --check still verifies the region when the test skips.
|
||||||
|
- Every shown snippet must execute in at least one go test run (the -short run or the Docker run). Never make a function reachable only by naming it in a test body without running it.
|
||||||
|
- If a snippet cannot execute even against an in-process fake, list it in the SUMMARY with the reason instead of gaming reachability.
|
||||||
|
|
||||||
|
R4 Package and names:
|
||||||
|
- Example files are package `<module>_test`. Reuse existing fixture types (BlogPlugin, Plugin, Post, users...) instead of redeclaring them.
|
||||||
|
- Example names must pass go vet's tests analyzer: Example, Example_suffix, ExampleIdent, ExampleIdent_suffix, ExampleType_Method, ExampleType_Method_suffix. Ident, Type and Method must exist in the module package, and the suffix must start with a lowercase letter.
|
||||||
|
- Use neutral names only (acme, blog, example.com), never a consuming application's name; checkForbiddenSources scans sources.
|
||||||
|
|
||||||
|
R5 README shape:
|
||||||
|
- One src= reference per fence, at the top level. The info string format is `go src=modules/<m>/example_test.go#Fragment`, as in docs/database/models.md.
|
||||||
|
- A fence that showed a whole file (package clause, imports, several declarations) becomes one fence per declaration or region, in reading order. Drop the package clause and the import block; the README's import line already gives the import path, and docs/ pages do the same.
|
||||||
|
- Keep the README prose. Change only words that name code the fence no longer shows, for example `models.Post` becomes `Post`.
|
||||||
|
- Fill fence bodies by running `go run ./cmd/summer docs:sync`, never by hand.
|
||||||
|
|
||||||
|
R6 Language tags: if a fence's content is genuinely not Go, change its tag only when the new tag is honest (for example `text`), and list every case in the SUMMARY with its reason. Prefer making it compile; for example, a struct-literal fragment becomes a region around the element inside a function that builds the slice. Expected count: 0.
|
||||||
|
|
||||||
|
R7 Adaptations: whenever README code had to change to compile or run, list it in the SUMMARY under "README code adapted". Examples: a renamed identifier, a literal replaced by an httptest URL or a parameter, a `func main` turned into a function a test calls, a Test that changes into a testdata plugin directory first.
|
||||||
|
|
||||||
|
R8 Per module:
|
||||||
|
- Before touching a module, run `git status --short modules/<m>`. If another session has uncommitted edits to that module's README or example tests, skip it, finish the others, and come back. If it is still dirty at the end, stop and report; do not drop the exemption.
|
||||||
|
- After converting a module, run `go vet ./modules/<m>/...`, `go test -short -count=1 ./modules/<m>/...` and `go run ./cmd/summer docs:build --check`.
|
||||||
|
- Commit by module group (3-6 modules per commit) with the message `docs(<m1>,<m2>,...): compile README Go examples via src= (quick-261118-qsd)`. Stage each README.md and example test file by path, never `git add -A`.
|
||||||
|
- For modules that gain Docker-backed TestDocs* tests, also run `go test -count=1 -run 'TestDocs' ./modules/<m>/`. If the Docker socket is denied, run it through `sudo -u golem`. Record the outcome, or record that Docker is unavailable, in the SUMMARY.
|
||||||
|
</context>
|
||||||
|
|
||||||
|
<tasks>
|
||||||
|
|
||||||
|
<task type="tracer" tdd="true">
|
||||||
|
<name>Task 1: Check, caption and sync src= fences in module READMEs, proven end to end on breakwater</name>
|
||||||
|
<files>internal/docsite/snippet.go, internal/docsite/render.go, internal/docsite/checks_test.go, internal/docsite/render_test.go, internal/docsite/snippet_test.go, modules/breakwater/README.md, modules/breakwater/example_test.go, docs/console/utilities.md, README.md, CLAUDE.md</files>
|
||||||
|
<behavior>
|
||||||
|
- checks_test (rework TestNestedFenceChecks' README fixture, or add a README case next to it): a README top-level src= fence whose body equals its source gives no problem. A drifted one gives "body differs from <ref> (run: summer docs:sync)" at the README's own line. A src= fence inside a README list item or callout gives the nested-fence message. A README src= to a dotfile/.env path, or to an Example without `// Output:`, is refused with the existing Extract messages. The bare `go` fence at README:7 still gives no problem in this task (the policy exemption is dropped in task 3).
|
||||||
|
- render_test (rename TestFenceCaptionsOnlyVerified to TestFenceCaptionsTopLevelSrc): the guide keeps exactly one figcaption. api/alpha now has exactly one figcaption for its top-level README src= fence, and a src= fence nested in a README callout gets none.
|
||||||
|
- snippet_test, new TestSyncModuleReadme: a fixture with modules/alpha/alpha.go, a test file holding a reachable target, and a README whose src= fence is stale. Sync rewrites only that fence body, and the README is byte-identical otherwise (H1, summary line, prose, a second sh fence). SyncResult is {Files:1, Snippets:1} when only the README drifted. A second Sync returns SyncResult{}. A README with a refused src= (for example a .env path) makes Sync return that problem and write nothing in any file, including a drifted docs/ page in the same tree.
|
||||||
|
- Write these tests first and watch them fail (RED) before changing snippet.go and render.go.
|
||||||
|
</behavior>
|
||||||
|
<action>
|
||||||
|
RED: write the behaviour tests above in internal/docsite and run `go test -short ./internal/docsite/ -run 'TestNestedFenceChecks|TestFenceCaptions|TestSyncModuleReadme'` to see them fail.
|
||||||
|
|
||||||
|
GREEN, in internal/docsite:
|
||||||
|
- snippet.go `checkSnippets`: remove the Module branch so every page with a non-nil `page` goes through `checkFences`. A README page's `d.line` is 1 and its body keeps the file's line indices, so problems cite README lines. Delete the README src= refusal constant (the one at ~533-536) and rewrite the doc comments of `checkSnippets` and `checkFences`: src= fences are compared on docs/ pages and module READMEs alike.
|
||||||
|
- snippet.go `Sync`: after `walkPages(opts.Src)`, append `filepath.Join(opts.Root, "modules", name, "README.md")` for every name `moduleNames(opts.Root)` returns whose README exists. Skip a missing README silently, because load already reports it. The existing per-file loop handles READMEs unchanged (no frontmatter, body = raw, bodyLine = 1). Keep the all-or-nothing write: collect every rewrite and every problem across docs pages and READMEs, and write nothing when any problem exists. Update Sync's doc comment. The `--src` flag still selects only the docs directory; READMEs always come from `--root`, matching how `load` ingests them.
|
||||||
|
- render.go `fenceAnnotator`: drop the `pctx.page.Module == ""` condition. `verified` becomes "the page context exists and the fence is a direct child of the document". Update the comment: the captioned fences are the ones checkSnippets compares, the top-level src= fences of every page.
|
||||||
|
- Do NOT touch check_policy.go in this task. Requiring src= on README Go fences now would turn TestDocsTree and docs:build --check red until tasks 2-3 convert every README, and CLAUDE.md requires go test ./... to stay green at every commit.
|
||||||
|
|
||||||
|
Tracer conversion (apply Conversion rules R1-R8 to breakwater):
|
||||||
|
- The single README fence at modules/breakwater/README.md ~28-34 becomes two consecutive top-level fences, `go src=modules/breakwater/example_test.go#ExampleRender` and `go src=modules/breakwater/example_test.go#ExamplePurify`. Their comment lines already match the README's.
|
||||||
|
- Run `go run ./cmd/summer docs:sync` to fill the bodies.
|
||||||
|
- Keep the prose sentence after the fence. If the Example output it quotes stays consistent, leave modules/breakwater/example_test.go unchanged.
|
||||||
|
|
||||||
|
Docs, in the same commit as the docsite change (CLAUDE.md documentation rules):
|
||||||
|
- docs/console/utilities.md ~48: remove the clause listing a src= code block in a module README among the failures. Say that `src=` works on top-level code blocks of docs pages and module READMEs.
|
||||||
|
- utilities.md docs:sync table row: it rewrites src= blocks in docs pages and module READMEs.
|
||||||
|
- Root README.md ~168: "src= works on top-level code blocks of docs/ pages and module READMEs".
|
||||||
|
- CLAUDE.md Commands block: the docs:sync comment reads "refresh src= code copies in docs/ and module READMEs after changing their source".
|
||||||
|
|
||||||
|
Commits:
|
||||||
|
- `feat(docsite): check, caption and sync src= blocks in module READMEs (quick-261118-qsd)`: snippet.go, render.go, the three test files, utilities.md, README.md, CLAUDE.md.
|
||||||
|
- `docs(breakwater): compile README Go examples via src= (quick-261118-qsd)`: modules/breakwater/README.md, plus example_test.go if it changed.
|
||||||
|
|
||||||
|
Stage files by path only. Do not touch .planning/state.json, G15OFFICE.md, examples/hello/plugins.gen.go, .msd/ or node_modules/.
|
||||||
|
</action>
|
||||||
|
<verify>
|
||||||
|
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/summercms.go && go vet ./internal/docsite/... ./modules/breakwater/... && go test -short -count=1 ./internal/docsite/... ./modules/breakwater/... && test "$(go test -short -count=1 -v ./internal/docsite -run 'TestNestedFenceChecks|TestFenceCaptionsTopLevelSrc|TestSyncModuleReadme' | grep -cE -- '--- PASS: Test(NestedFenceChecks|FenceCaptionsTopLevelSrc|SyncModuleReadme) ')" -ge 3 && ! grep -q 'readmeSrcMessage' internal/docsite/*.go && go test -count=1 ./cmd/summer -run 'TestDocsTree|TestCommandsDocumented' && go run ./cmd/summer docs:build --check && go run ./cmd/summer docs:sync | grep -q 'all snippets up to date' && grep -qE '^`{3}go src=modules/breakwater/example_test.go#ExampleRender$' modules/breakwater/README.md && grep -qE '^`{3}go src=modules/breakwater/example_test.go#ExamplePurify$' modules/breakwater/README.md && ! grep -qE '^`{3}go[[:space:]]*$' modules/breakwater/README.md && OUT="$(mktemp -d)" && go run ./cmd/summer docs:build --out "$OUT/site" >/dev/null && grep -o '<figcaption>.*</figcaption>' "$OUT/site/api/breakwater.html" | grep -q 'modules/breakwater/example_test.go#ExampleRender' && git diff --quiet -- go.mod go.sum</automated>
|
||||||
|
</verify>
|
||||||
|
<done>The tracer path works end to end. The breakwater README fences are src= references to ExampleRender/ExamplePurify: docs:build --check compares them, docs:sync reports them up to date, and site/api/breakwater.html captions them. The README src= refusal is gone. Sync covers module READMEs with all-or-nothing writes. The docsite tests prove match, drift, nested refusal, captions and README sync. The docs describe the new rule. Both commits have landed.</done>
|
||||||
|
</task>
|
||||||
|
|
||||||
|
<task type="auto">
|
||||||
|
<name>Task 2: Convert the README Go fences of backpack through lagoon (15 modules, 35 fences)</name>
|
||||||
|
<files>modules/backpack/README.md, modules/backpack/example_test.go, modules/beachcomber/README.md, modules/beachcomber/example_test.go, modules/boardwalk/README.md, modules/boardwalk/example_test.go, modules/bonfire/README.md, modules/bonfire/example_test.go, modules/bouncer/README.md, modules/bouncer/example_test.go, modules/cabana/README.md, modules/cabana/example_test.go, modules/compass/README.md, modules/compass/example_test.go, modules/conga/README.md, modules/conga/example_test.go, modules/cooler/README.md, modules/cooler/example_test.go, modules/diary/README.md, modules/diary/example_test.go, modules/festival/README.md, modules/festival/example_test.go, modules/fetchguard/README.md, modules/fetchguard/example_test.go, modules/flare/README.md, modules/flare/example_test.go, modules/kiosk/README.md, modules/kiosk/example_test.go, modules/lagoon/README.md, modules/lagoon/example_test.go</files>
|
||||||
|
<action>
|
||||||
|
Apply Conversion rules R1-R8 from the context section to every Go fence in these READMEs: backpack 1, beachcomber 3, boardwalk 1, bonfire 2, bouncer 2, cabana 1, compass 1, conga 6, cooler 3, diary 2, festival 1, fetchguard 2, flare 2, kiosk 4, lagoon 4. Work module by module and commit by group, for example backpack-boardwalk-bonfire-bouncer, then cabana-compass-conga, cooler-diary-festival-fetchguard, and flare-kiosk-lagoon.
|
||||||
|
|
||||||
|
Module notes from planning:
|
||||||
|
- boardwalk: has no example test file. Create modules/boardwalk/example_test.go (package boardwalk_test). The notFoundAPI handler fence becomes a region inside an Example or Test that serves a request through it with httptest.
|
||||||
|
- bonfire: the 40-line package-main fence shows a binary's main. Turn it into declarations or a region in a function a test runs with explicit args and a buffer for output (R7: list the adaptation). The catalog fence likely maps to the existing ExampleCatalog or ExampleCall (R1).
|
||||||
|
- cabana: check `git status --short modules/cabana` first (shared, often edited by other sessions). The embed/fs fence may need an `embed.FS` var in the test file; `//go:embed` is allowed in _test.go files and needs a testdata path. Note that src= into testdata is refused, but embedding testdata from a _test.go declaration is fine.
|
||||||
|
- conga: six fences. startImport, importPosts and the Dispatch with tx need a database. Put them as regions in helpers run by TestDocs* through `conga.DocsApp`, extending the existing TestDocsDispatch pattern. The Schedule fence is a declaration on the fixture plugin, made reachable by a Test that calls Schedule() and asserts the entries. The StartWorker fence is a region in a Docker-backed helper.
|
||||||
|
- diary: the `run(args, out)` fence calls diary.Bootstrap, which sets process-wide logging. Restore the previous default in the test (t.Cleanup) so other tests are unaffected.
|
||||||
|
- fetchguard and flare: run network calls against httptest servers. A fetchguard policy that refuses private addresses needs the test to use the policy's allow-list for the loopback test server, or to show the refusal outcome. Keep the README's teaching point and list adaptations (R7). flare subscriptions need gorm: Docker-backed helper, or a fake store if the fence's point is the interface.
|
||||||
|
- kiosk: `kiosk.Write`, NewClient and RegistryURL run against t.TempDir and httptest. The `TestPluginManifest` fence must be a Test that really passes: CheckT on a valid plugin directory, for example after t.Chdir into a fixture made in t.TempDir. Do not reference a testdata path through src=.
|
||||||
|
- lagoon: four fences. OpenFromApp/Publish and the OnDatabase callback go through DocsDB-backed helpers (existing TestDocsOnDatabase may already cover them, R1). Post with Jsonable/Encrypted and Migrations are declarations; check TestDocsModelDeclarations first.
|
||||||
|
|
||||||
|
After the last group: no bare go fence remains in these 15 READMEs, docs:build --check and docs:sync are clean, and the module tests pass under -short. Record per-fence targets for the SUMMARY table as you go (README:line, old fence, new src= references).
|
||||||
|
</action>
|
||||||
|
<verify>
|
||||||
|
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/summercms.go && go vet ./modules/{backpack,beachcomber,boardwalk,bonfire,bouncer,cabana,compass,conga,cooler,diary,festival,fetchguard,flare,kiosk,lagoon}/... && go test -short -count=1 ./modules/{backpack,beachcomber,boardwalk,bonfire,bouncer,cabana,compass,conga,cooler,diary,festival,fetchguard,flare,kiosk,lagoon}/... && ! grep -nE '^`{3}go[[:space:]]*$' modules/{backpack,beachcomber,boardwalk,bonfire,bouncer,cabana,compass,conga,cooler,diary,festival,fetchguard,flare,kiosk,lagoon}/README.md && test "$(cat modules/{backpack,beachcomber,boardwalk,bonfire,bouncer,cabana,compass,conga,cooler,diary,festival,fetchguard,flare,kiosk,lagoon}/README.md | grep -cE '^`{3}go src=modules/')" -ge 35 && go test -count=1 ./cmd/summer -run TestDocsTree && go run ./cmd/summer docs:build --check && go run ./cmd/summer docs:sync | grep -q 'all snippets up to date' && git diff --quiet -- go.mod go.sum</automated>
|
||||||
|
</verify>
|
||||||
|
<done>All 35 Go fences of these 15 READMEs are top-level src= references into compiled, test-run code of their module. The -short tests, docs:build --check and docs:sync are clean. Docker-backed TestDocs* outcomes are recorded. The per-group commits have landed, with only READMEs and _test.go files under modules/.</done>
|
||||||
|
</task>
|
||||||
|
|
||||||
|
<task type="auto">
|
||||||
|
<name>Task 3: Convert lighthouse through wristband (16 modules, 32 fences), drop the README exemption and run every gate</name>
|
||||||
|
<files>modules/lighthouse/README.md, modules/lighthouse/example_test.go, modules/pact/README.md, modules/pact/example_test.go, modules/party/README.md, modules/party/example_test.go, modules/phrasebook/README.md, modules/phrasebook/example_test.go, modules/pier/README.md, modules/pier/example_test.go, modules/postcard/README.md, modules/postcard/example_test.go, modules/seaglass/README.md, modules/seaglass/example_test.go, modules/sieve/README.md, modules/sieve/example_test.go, modules/signpost/README.md, modules/signpost/example_test.go, modules/sunrise/README.md, modules/sunrise/example_test.go, modules/sunscreen/README.md, modules/sunscreen/example_test.go, modules/surf/README.md, modules/surf/example_test.go, modules/tide/README.md, modules/tide/example_test.go, modules/towel/README.md, modules/towel/example_test.go, modules/wire/README.md, modules/wire/example_test.go, modules/wristband/README.md, modules/wristband/example_test.go, internal/docsite/check_policy.go, internal/docsite/checks_test.go, docs/console/utilities.md, CLAUDE.md</files>
|
||||||
|
<action>
|
||||||
|
Part A: apply Conversion rules R1-R8 to lighthouse 5, pact 2, party 2, phrasebook 1, pier 1, postcard 5, seaglass 1, sieve 1, signpost 4, sunrise 1, sunscreen 2, surf 1, tide 2, towel 1, wire 1, wristband 2. Commit by group as in task 2.
|
||||||
|
|
||||||
|
Module notes from planning:
|
||||||
|
- lighthouse: Bind and WithoutBroadcasting need a database. Use regions in helpers run through `lighthouse.DocsEnv`; the existing TestDocsBroadcast and bindPosts may already cover the Bind fence (R1). The Routes/Mount fence is a fixture-plugin declaration whose Test mounts routes on a test router. The MemoryDriver publications fence fits a region printing deterministic output.
|
||||||
|
- pact: the HasSchedule fence likely maps to the existing ExampleHasSchedule (R1). The 32-line plugin fence becomes per-declaration fences.
|
||||||
|
- party: the plugin fence maps to the existing ExamplePlugin or its declarations. The compass.Load/backpack.New fence needs a config dir in t.TempDir, or the same calls on the in-memory equivalents already used by other examples; list any change (R7).
|
||||||
|
- pier: there is example_mcp_test.go (package pier_test, no build tag). Put the createPostInput tool declaration there or in a new example_test.go, reachable from a Test that registers and calls the tool.
|
||||||
|
- postcard: five fences, mostly whole files. Reuse mailFS (fstest) and ExampleMailer_Send. One fence already uses testing/fstest in a test, so it maps onto a real Test function (`#TestName` is a valid declaration target because Tests are roots).
|
||||||
|
- seaglass: there is no example test file yet. Create modules/seaglass/example_test.go with an Example whose `// Output:` replaces the README's "clean ==" and "report.Elements ==" comments, plus seaglass.Check.
|
||||||
|
- signpost: the `{ Key: ... }` composite-literal fragment becomes a region around that element inside a function that builds the content-type slice and is called by a Test (R6: no retag). The Events.Listen fence is a region in a Test that fires a pact.RecordSaved.
|
||||||
|
- sunrise: there is no example test file yet. Create modules/sunrise/example_test.go for its 13-line http fence.
|
||||||
|
- sunscreen: `func main` with InstallDefault becomes a region in an Example or Test that restores slog.Default afterwards. The JSON-handler fence becomes an Example whose `// Output:` shows the redacted line, using deterministic handler options (for example ReplaceAttr dropping time) — R7.
|
||||||
|
- surf: the 62-line plugin fence becomes per-declaration fences on the existing BlogPlugin fixture (Middlewares, Buckets, routes), reachable through TestDocsDeclarations or ExampleAssembleRouter (R1).
|
||||||
|
- tide: RecordFlow and RecordBroadcasts run against an httptest server instead of 127.0.0.1:8000. LoadFlow reads a spec file the test writes to t.TempDir; do not use a testdata path through src=. List every adaptation (R7).
|
||||||
|
- towel, wire, wristband: whole-file fences map onto existing Examples (ExampleWithLocale, ExampleWriteJSON, ExampleNewOIDCServer and similar) or their declarations (R1).
|
||||||
|
|
||||||
|
Part B, once every module README is converted and docs:build --check is clean:
|
||||||
|
- internal/docsite/check_policy.go `checkPolicy`: apply the "Go-lexer fence needs src=" rule to every page, module READMEs included. Keep `headingProblems` limited to docs/ pages. Rewrite the doc comment: every Go-lexer fence on any page carries src=, at any depth; drop the D-18 "rendered as written" remark.
|
||||||
|
- internal/docsite/checks_test.go `TestNestedFenceChecks`: add the expectation that the bare `go` fence at modules/fixture/README.md:7 is reported as "go code block has no src= reference". Keep the task-1 README src= expectations.
|
||||||
|
- docs/console/utilities.md ~48: the "Go code block without a src= reference" failure applies to docs pages and module READMEs alike.
|
||||||
|
- CLAUDE.md "Documentation rules": add one bullet. Go code blocks in docs/ pages and module READMEs are src= references into compiled test code (usually the module's example_test.go). docs:build --check compares them, and `summer docs:sync` refreshes them after the source changes.
|
||||||
|
- Commit `feat(docsite): require src= on Go code blocks of module READMEs (quick-261118-qsd)` with check_policy.go, checks_test.go, utilities.md and CLAUDE.md.
|
||||||
|
|
||||||
|
Part C: run the full gate list in verify. Then write the SUMMARY with:
|
||||||
|
- the per-fence table (module, README line, new src= references, target kind);
|
||||||
|
- the "README code adapted" list (R7);
|
||||||
|
- the retag list (expected empty) (R6);
|
||||||
|
- un-executable snippets, if any (R3);
|
||||||
|
- Docker TestDocs* outcomes;
|
||||||
|
- the note that the todo's Output-less-Example route was not used because Extract's run rule refuses it;
|
||||||
|
- the note that ROADMAP 11.1 SC4 can now be widened back to "every Go example in the docs". ROADMAP.md is NOT edited by this task; that is the user's or orchestrator's call;
|
||||||
|
- the note that moving the todo to .planning/todos/completed/ and the g15office (gplauwlb) comment are left to the orchestrator.
|
||||||
|
</action>
|
||||||
|
<verify>
|
||||||
|
<automated>cd /media/nvme/dev/golem15/summercms.io/summercms/summercms.go && go vet ./... && go test -short -count=1 ./... && (cd examples/hello && go test -short -count=1 ./...) && go test -count=1 ./cmd/summer -run 'TestDocsTree|TestCommandsDocumented' && go test -short -count=1 -v ./internal/docsite -run TestNestedFenceChecks | grep -q -- '--- PASS: TestNestedFenceChecks' && go run ./cmd/summer docs:build --check && go run ./cmd/summer docs:sync | grep -q 'all snippets up to date' && ! grep -nE '^`{3}go[[:space:]]*$' modules/*/README.md && test "$(cat modules/*/README.md | grep -cE '^`{3}go src=modules/')" -ge 68 && QSD_FILES="$(git log --format= --name-only --grep='quick-261118-qsd' 830f3053..HEAD -- modules)" && test -n "$QSD_FILES" && test -z "$(printf '%s\n' "$QSD_FILES" | grep '\.go$' | grep -v '_test\.go$')" && git diff --quiet -- go.mod go.sum && PHASE35_BASE_TAG=v0.6.5 scripts/check-phase35.sh --additive</automated>
|
||||||
|
</verify>
|
||||||
|
<done>Every Go fence in modules/*/README.md (68 or more after splits, with 0 bare fences) is a top-level src= reference to code go test compiles and runs. checkPolicy refuses a README Go fence without src=, and the docsite tests prove it. The docs describe the rule. go vet, go test -short (root and examples/hello), the cmd/summer docs tests, docs:build --check, a no-op docs:sync and the phase-35 additive check all pass. The commits touch only READMEs and _test.go files under modules/, go.mod and go.sum are unchanged, and the SUMMARY carries the fence table, adaptations, retags (none expected), the Docker outcomes and the ROADMAP 11.1 SC4 note.</done>
|
||||||
|
</task>
|
||||||
|
|
||||||
|
</tasks>
|
||||||
|
|
||||||
|
<threat_model>
|
||||||
|
## Trust Boundaries
|
||||||
|
|
||||||
|
| Boundary | Description |
|
||||||
|
|----------|-------------|
|
||||||
|
| README markdown -> docsite Extract (filesystem) | A src= path in a module README now reaches Extract and its bytes are copied into the published site |
|
||||||
|
| docs:sync -> module README files on disk | Sync now rewrites README files, not only docs/ pages |
|
||||||
|
| framework repository -> consuming apps and plugins | Module packages are imported by apps and sm-*-plugin repos; only test files and READMEs may change |
|
||||||
|
|
||||||
|
## STRIDE Threat Register
|
||||||
|
|
||||||
|
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||||
|
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||||
|
| T-qsd-01 | Information disclosure | Extract on README src= paths | medium | mitigate | README fences go through the same checkFences/Extract path as docs/ pages (checkRefPath, symlink resolution within the root, dotfile/.env refusal, testdata and nested-module refusal). Task 1 tests a README src= to a .env path and assert the refusal |
|
||||||
|
| T-qsd-02 | Tampering | Sync rewriting READMEs | medium | mitigate | Only the bodies of drifted top-level src= fences are replaced. Every rewrite is collected first and nothing is written when any page or README has a problem. TestSyncModuleReadme asserts that the rest of the README is byte-identical, that a refused README fence blocks every write, and that a second Sync is a no-op |
|
||||||
|
| T-qsd-03 | Denial of service (breaking change) | module packages used by consumers | high | mitigate | Under modules/ only README.md and _test.go files change (git log gate in task 3), go.mod/go.sum are unchanged, and PHASE35_BASE_TAG=v0.6.5 scripts/check-phase35.sh --additive passes |
|
||||||
|
| T-qsd-04 | Information disclosure | consuming-application names in new example code | low | mitigate | Neutral names only (R4). checkForbiddenSources runs in docs:build --check, which every task's verify includes |
|
||||||
|
| T-qsd-05 | Denial of service | test suite under -short | low | mitigate | Examples run offline. Docker-backed TestDocs* use the existing helpers that skip under -short. Process-wide state (slog default, diary bootstrap) is restored in t.Cleanup. go test -short ./... is in task 3's gate |
|
||||||
|
| T-qsd-SC | Tampering | Go module installs | low | accept | No dependency is added. The gate is git diff --quiet -- go.mod go.sum |
|
||||||
|
</threat_model>
|
||||||
|
|
||||||
|
<verification>
|
||||||
|
- go vet ./... and go test -short ./... pass at every commit. Task 1 does not tighten the policy, so the unconverted READMEs stay green until task 3 drops the exemption.
|
||||||
|
- cd examples/hello && go test -short ./... passes.
|
||||||
|
- go test ./cmd/summer -run 'TestDocsTree|TestCommandsDocumented' passes.
|
||||||
|
- go run ./cmd/summer docs:build --check passes, and go run ./cmd/summer docs:sync prints "all snippets up to date".
|
||||||
|
- No bare go fence remains in modules/*/README.md. The src= fence count is at least 68, and every retag is listed in the SUMMARY (expected: none).
|
||||||
|
- Only README.md and _test.go files change under modules/. go.mod and go.sum are unchanged. scripts/check-phase35.sh --additive passes with PHASE35_BASE_TAG=v0.6.5.
|
||||||
|
</verification>
|
||||||
|
|
||||||
|
<success_criteria>
|
||||||
|
- Module README Go examples are compiled and run by go test, compared by docs:build --check, refreshed by docs:sync and captioned on the docs site. The README exemption is gone.
|
||||||
|
- The internal/docsite tests cover README match, drift, nested refusal, caption, sync and the no-src refusal.
|
||||||
|
- Docs (utilities.md, root README.md, CLAUDE.md) describe the rule.
|
||||||
|
- The SUMMARY lists the fence-to-target table, adaptations, retags (expected none), Docker outcomes, and the ROADMAP 11.1 SC4 note (ROADMAP not edited).
|
||||||
|
</success_criteria>
|
||||||
|
|
||||||
|
<output>
|
||||||
|
Create `.planning/quick/261118-qsd-compile-module-readme-go-examples-via-sr/261118-qsd-SUMMARY.md` when done.
|
||||||
|
</output>
|
||||||
@@ -0,0 +1,362 @@
|
|||||||
|
---
|
||||||
|
phase: quick-261118-qsd
|
||||||
|
plan: 01
|
||||||
|
subsystem: docs
|
||||||
|
tags: [docsite, src-snippets, module-readmes]
|
||||||
|
status: complete
|
||||||
|
requires: []
|
||||||
|
provides:
|
||||||
|
- "docsite checks, captions and syncs top-level src= fences in modules/<name>/README.md"
|
||||||
|
affects: [internal/docsite, cmd/summer, modules/*/README.md]
|
||||||
|
key-files:
|
||||||
|
created: []
|
||||||
|
modified:
|
||||||
|
- internal/docsite/snippet.go
|
||||||
|
- internal/docsite/render.go
|
||||||
|
- internal/docsite/checks_test.go
|
||||||
|
- internal/docsite/render_test.go
|
||||||
|
- internal/docsite/snippet_test.go
|
||||||
|
- internal/docsite/testdata/violations/snippet-readme-src/modules/demo/README.md
|
||||||
|
- internal/docsite/testdata/violations/snippet-readme-src/want.txt
|
||||||
|
- cmd/summer/phase11_1_acceptance_test.go
|
||||||
|
- docs/console/utilities.md
|
||||||
|
- README.md
|
||||||
|
- CLAUDE.md
|
||||||
|
- modules/breakwater/README.md
|
||||||
|
- "Task 2: README.md of backpack, beachcomber, boardwalk, bonfire, bouncer, cabana, compass, conga, cooler, diary, festival, fetchguard, flare, kiosk, lagoon"
|
||||||
|
- "Task 2: example_test.go of beachcomber, bonfire, bouncer, cabana, conga, cooler, diary, festival, fetchguard, flare, kiosk, lagoon; lagoon/export_docs_test.go"
|
||||||
|
- "Task 2 (created): modules/boardwalk/example_test.go"
|
||||||
|
- "Task 3: README.md of lighthouse, pact, party, phrasebook, pier, postcard, seaglass, sieve, signpost, sunrise, sunscreen, surf, tide, towel, wire, wristband"
|
||||||
|
- "Task 3: example_test.go of lighthouse, pact, party, phrasebook, postcard, sieve, sunscreen, tide, towel, wristband; signpost/example_content_test.go; lighthouse/lighthouse_test.go"
|
||||||
|
- "Task 3 (created): modules/seaglass/example_test.go, modules/sunrise/example_test.go, modules/wristband/export_docs_test.go, modules/party/export_docs_test.go"
|
||||||
|
- "Task 3: internal/docsite/check_policy.go, checks_test.go, theme_test.go, testdata/{clean,violations/*}/modules/demo/README.md"
|
||||||
|
- "Task 3: docs/console/utilities.md, CLAUDE.md, docs/architecture/request-lifecycle.md, docs/services/oauth-server.md (synced)"
|
||||||
|
decisions:
|
||||||
|
- "Sync always takes module READMEs from --root (as load does); --src still selects only the docs directory"
|
||||||
|
- "checkPolicy requires src= on every Go-lexer fence of every page, module READMEs included; heading rules stay docs/-only"
|
||||||
|
- "Test-only seams for docs examples follow the export_docs_test.go pattern (wristband.DocsBackend/DocsOIDC, party.DocsRegistry)"
|
||||||
|
metrics:
|
||||||
|
completed: 2026-11-18
|
||||||
|
actuals:
|
||||||
|
tokens: 43600
|
||||||
|
tasks: 3
|
||||||
|
commits: 11
|
||||||
|
plan_head_before: 830f305376c661761df1bc0d2e8596b812efa0f3
|
||||||
|
plan_head_after: 8c03cc36
|
||||||
|
commits: 11
|
||||||
|
---
|
||||||
|
|
||||||
|
# Quick 261118-qsd: compile module README Go examples via src=
|
||||||
|
|
||||||
|
Every Go code block of every module README is now a top-level `src=` reference into compiled test code that `go test` runs. docsite checks, captions and syncs these fences the same way it handles docs/ pages, and the page policy refuses a bare Go fence in a module README. The 68 bare fences of 32 READMEs became 129 `src=` fences. No language tag was changed.
|
||||||
|
|
||||||
|
## Task 1: docsite tooling + breakwater tracer (complete)
|
||||||
|
|
||||||
|
### Commits
|
||||||
|
|
||||||
|
| Hash | Message |
|
||||||
|
|------|---------|
|
||||||
|
| 721830c5 | feat(docsite): check, caption and sync src= blocks in module READMEs (quick-261118-qsd) |
|
||||||
|
| 48527e42 | docs(breakwater): compile README Go examples via src= (quick-261118-qsd) |
|
||||||
|
|
||||||
|
### What changed
|
||||||
|
|
||||||
|
- `snippet.go`: `checkSnippets` runs `checkFences` on every page with a `page`, module READMEs included. Problems cite the README's own line numbers. `readmeSrcMessage` and its branch are gone. `Sync` adds `modules/<name>/README.md` for every name `moduleNames(Root)` returns and skips modules without a README. It is still all-or-nothing: no file is written if any page or README has a problem.
|
||||||
|
- `render.go`: `fenceAnnotator` captions the top-level `src=` fences of every page. `site/api/breakwater.html` now has two figcaptions that link through `source_url`.
|
||||||
|
- Tests (RED seen first, then GREEN):
|
||||||
|
- `TestNestedFenceChecks` covers README match (no problem), drift at README:16, a list-nested fence at :22, a callout-nested fence at :27, a `.env` refusal at :30 and an Example without Output at :33. The bare `go` fence at README:7 still reports nothing.
|
||||||
|
- `TestFenceCaptionsTopLevelSrc` (renamed from `TestFenceCaptionsOnlyVerified`) expects one caption on api/alpha, none on its nested callout fence, and the guide unchanged.
|
||||||
|
- New `TestSyncModuleReadme`: the README is rewritten byte-exact, the result is `{Snippets:1, Files:1}`, a second Sync returns `SyncResult{}`, and a README `.env` reference blocks every write, including a drifted docs/ page.
|
||||||
|
- Docs: `docs/console/utilities.md` (docs:sync row and the failure paragraph), the root `README.md` (src= now covers docs/ pages and module READMEs) and the `CLAUDE.md` docs:sync comment.
|
||||||
|
- breakwater: the Usage fence became `go src=modules/breakwater/example_test.go#ExampleRender` and `#ExamplePurify`, with bodies filled by `summer docs:sync`. `example_test.go` is unchanged, and the prose sentence after the fences still matches ExampleRender's output.
|
||||||
|
|
||||||
|
### Deviations from Plan
|
||||||
|
|
||||||
|
**1. [Rule 1 - Bug] The planted violation `snippet-readme-src` still expected the removed refusal.**
|
||||||
|
- Found during: Task 1 GREEN (`TestPlantedViolations/snippet-readme-src` failed).
|
||||||
|
- Fix: the fixture now plants a drifted README fence (`demo.Hello("world")`). want.txt expects `body differs from modules/demo/example_test.go#ExampleHello (run: summer docs:sync)`. The case name stays.
|
||||||
|
- Files: `internal/docsite/testdata/violations/snippet-readme-src/{modules/demo/README.md,want.txt}`. Commit 721830c5.
|
||||||
|
|
||||||
|
**2. [Rule 1 - Bug] The Phase 11.1 SC4 acceptance test (`cmd/summer/phase11_1_acceptance_test.go`) refused any src= fence in a module README and any figcaption on api/ pages.**
|
||||||
|
- Found during: the full `go test -short ./...` run after the breakwater conversion.
|
||||||
|
- Fix: README src= fences now have to be top-level only, matching the docs/ scan. The figcaption count (= top-level src= fences) applies to every page, README API pages included, and the "api pages have no figcaption" loop is gone. This change was folded (amended, unpushed) into the breakwater commit 48527e42, because that is the commit that first made it red. Every commit stays green.
|
||||||
|
|
||||||
|
### README code adapted (R7)
|
||||||
|
|
||||||
|
- breakwater: the old fence used fictional variables (`post.Content`, `training.ContentHTML`). The README now shows ExampleRender and ExamplePurify as they are: literal input strings plus `fmt.Println` and `// Output:` lines.
|
||||||
|
|
||||||
|
### Retags (R6)
|
||||||
|
|
||||||
|
None.
|
||||||
|
|
||||||
|
### Verification (Task 1 `<verify>`, all passed)
|
||||||
|
|
||||||
|
- `go vet ./internal/docsite/... ./modules/breakwater/...`: ok
|
||||||
|
- `go test -short -count=1 ./internal/docsite/... ./modules/breakwater/...`: ok
|
||||||
|
- 3 PASS lines for TestNestedFenceChecks, TestFenceCaptionsTopLevelSrc and TestSyncModuleReadme; no `readmeSrcMessage` left in the code
|
||||||
|
- `go test -count=1 ./cmd/summer -run 'TestDocsTree|TestCommandsDocumented'`: ok
|
||||||
|
- `summer docs:build --check`: no problems found. `summer docs:sync`: all snippets up to date
|
||||||
|
- breakwater README: both src= info strings are present, there is no bare go fence, and the built api/breakwater.html carries the `#ExampleRender` figcaption
|
||||||
|
- go.mod and go.sum are unchanged
|
||||||
|
- Also ran: `go vet ./...` and `go test -short -count=1 ./...` (root, all ok), and `examples/hello` `go test -short ./...` (ok)
|
||||||
|
- Docker-backed tests were not run; Task 1 adds none.
|
||||||
|
|
||||||
|
### Notes for the Task 2/3 executors
|
||||||
|
|
||||||
|
- The bare `go` fence in a README is still exempt from the src= policy (check_policy.go is untouched). Task 3 drops that exemption. The check_policy.go doc comment still carries the "module READMEs are rendered as written, D-18" remark for Task 3 to rewrite.
|
||||||
|
- When Task 3 drops the exemption, these testdata fixtures carry a bare `go` fence (`import "example.com/docfixture/modules/demo"`) in `modules/demo/README.md`:
|
||||||
|
- `internal/docsite/testdata/clean/modules/demo/README.md`. TestCleanFixture expects zero problems, so this fixture has to change: retag it, or turn it into a src= fence.
|
||||||
|
- `internal/docsite/testdata/violations/snippet-readme-src/...`, plus any other violation case that copies that README. Each case must still yield exactly one problem.
|
||||||
|
- Run `go test ./internal/docsite` after the policy change to find them.
|
||||||
|
- `cmd/summer/phase11_1_acceptance_test.go` SC4: `docsGoFences` scans docs/ only. Task 3 may extend the "go fence without src=" assertion to module READMEs, but that is not required.
|
||||||
|
- `summer docs:sync` now fills README bodies. Write an empty `go src=...` fence, then run `go run ./cmd/summer docs:sync`.
|
||||||
|
- `cmd/summer/docs.go` docs:sync help text is generic ("every code block that has a src= reference") and was left unchanged.
|
||||||
|
|
||||||
|
## Task 2: backpack .. lagoon (complete)
|
||||||
|
|
||||||
|
All 35 bare Go fences in the 15 READMEs are now top-level `src=` fences, 69 in all after splits. Every target is compiled test code that a Test or an Example with `// Output:` reaches. Under `modules/`, only README.md and `_test.go` files changed.
|
||||||
|
|
||||||
|
### Commits
|
||||||
|
|
||||||
|
| Hash | Message |
|
||||||
|
|------|---------|
|
||||||
|
| a0f5b5e5 | docs(backpack,beachcomber,boardwalk,bonfire,bouncer): compile README Go examples via src= (quick-261118-qsd) |
|
||||||
|
| becb31fb | docs(cabana,compass,conga): compile README Go examples via src= (quick-261118-qsd) |
|
||||||
|
| d04454c5 | docs(cooler,diary,festival,fetchguard): compile README Go examples via src= (quick-261118-qsd) |
|
||||||
|
| c517db56 | docs(flare,kiosk,lagoon): compile README Go examples via src= (quick-261118-qsd) |
|
||||||
|
|
||||||
|
No module had uncommitted edits from another session, so none was skipped.
|
||||||
|
|
||||||
|
### Fence map
|
||||||
|
|
||||||
|
Old line is the README line at 48527e42. New targets are listed in README order, all in `modules/<m>/example_test.go` unless another file is named. Kinds: Ex = Example with Output, R = docs:start region, D = declaration.
|
||||||
|
|
||||||
|
| Module | Old line | New src= targets (kind) | Runs in |
|
||||||
|
|--------|----------|-------------------------|---------|
|
||||||
|
| backpack | 33 | Greeter (D), ExampleApp_Publish (Ex) | -short |
|
||||||
|
| beachcomber | 84 | Post.SearchableAs, Post.ShouldBeSearchable, Post.ToSearchableArray, Post.SearchIndexSchema (D, new) | -short (TestDocsDeclarations) |
|
||||||
|
| beachcomber | 111 | Plugin.Boot (D, new), gate (R) | Docker (TestDocsSearch) |
|
||||||
|
| beachcomber | 137 | search (R) | Docker (TestDocsSearch) |
|
||||||
|
| boardwalk | 39 | mount (R, new file) | -short (ExampleHandler) |
|
||||||
|
| bonfire | 56 | importPostsCommand (D, new), acmeMain (D, new) | -short (ExampleExecute) |
|
||||||
|
| bonfire | 101 | ExampleCatalog_Has (Ex, new) | -short |
|
||||||
|
| bouncer | 42 | users (D), users.FindByID (D), ExampleNewJWTGuard (Ex) | -short (new TestDocsDeclarations) |
|
||||||
|
| bouncer | 88 | RefreshRoute (D, new) | -short (TestDocsRefreshRoute) |
|
||||||
|
| cabana | 201 | example_controller_test.go: Post, Post.TableName, PostsController, .ID, .ModelName, .ConfigDir, .NewRecord, BlogPlugin, BlogPlugin.AdminControllers, BlogPlugin.AdminFS (D) | -short (TestDocsDeclarations, extended) |
|
||||||
|
| compass | 40 | mailSettings (D), ExampleOpen (Ex) | -short |
|
||||||
|
| conga | 48 | ImportPostsArgs (D), ImportPostsArgs.Kind (D), BlogPlugin.Jobs (D) | -short and Docker |
|
||||||
|
| conga | 75 | dispatch (R) | Docker (TestDocsDispatch) |
|
||||||
|
| conga | 93 | ImportPostsJob (D) | Docker (TestDocsDispatch) |
|
||||||
|
| conga | 118 | FeedPlugin.Schedule (D, new) | -short (TestDocsSchedule) |
|
||||||
|
| conga | 131 | ReindexArgs (D, new), reindex (R, new) | Docker (TestDocsDispatch) |
|
||||||
|
| conga | 146 | worker (R, new) | Docker (TestDocsDispatch) |
|
||||||
|
| cooler | 49 | ExampleFromApp (Ex) | -short |
|
||||||
|
| cooler | 96 | Article, articlesController, articlesController.purge, articlesController.FormAfterUpdate (D) | -short (ExampleSiteCacheFromApp) |
|
||||||
|
| cooler | 130 | AllowExport (D, new) | -short (TestDocsAllowExport, miniredis) |
|
||||||
|
| diary | 44 | blogLog (D), ExampleFor (Ex) | -short |
|
||||||
|
| diary | 62 | run (D, new) | -short (TestDocsRun) |
|
||||||
|
| festival | 36 | PostPublished (D), ExampleBus_Fire (Ex), PostFormExtended (D), PostFormExtended.Collected (D), ExampleBus_Collect (Ex) | -short (new TestDocsDeclarations) |
|
||||||
|
| fetchguard | 41 | fetch (R, new) | -short (TestDocsFetchImage) |
|
||||||
|
| fetchguard | 65 | client (R, new) | -short (TestDocsSyncItems) |
|
||||||
|
| flare | 46 | send (R, new) | -short (TestDocsNotifyReply) |
|
||||||
|
| flare | 64 | blogSubscriptions (D, new), blogSubscriptions.Subscriptions (D, new), publish-source (R, new) | Docker (TestDocsSubscriptionSource) |
|
||||||
|
| kiosk | 29 | write (R, new) | -short (TestDocsWriteManifest) |
|
||||||
|
| kiosk | 50 | newest (R, new) | -short (ExampleVersionsResponse) |
|
||||||
|
| kiosk | 64 | client (R, new) | -short (TestDocsBlogReleases) |
|
||||||
|
| kiosk | 80 | checkt_test.go: TestPluginManifest (D, a Test root) | -short |
|
||||||
|
| lagoon | 51 | open (R, new) | Docker (TestDocsOpenFromApp) |
|
||||||
|
| lagoon | 63 | Post (D), Post.Fillable (D), create-post (R) | Docker (TestDocsModels) |
|
||||||
|
| lagoon | 89 | on-database (R), publish (R) | Docker (TestDocsOnDatabase, TestDocsTransactions) |
|
||||||
|
| lagoon | 112 | BlogPlugin.Migrations (D) | Docker (TestDocsMigrate) |
|
||||||
|
|
||||||
|
The Docker tests skip under -short. Their regions and declarations are still checked statically by docs:build --check, because reachability is static.
|
||||||
|
|
||||||
|
### README code adapted (R7)
|
||||||
|
|
||||||
|
- backpack: the fence's `Feed`/`staticFeed`/`setup()` became the existing `Greeter` and `ExampleApp_Publish`. The example uses `backpack.New(&compass.Config{})` instead of `compass.Load("config")`.
|
||||||
|
- beachcomber: the `models.Post` methods became the existing `Post` fixture's methods. `ShouldBeSearchable` keeps drafts out, where the old fence returned a constant true. `SearchIndexSchema` was added to the fixture. The Boot fence is now `Plugin.Boot`, which calls `installGate` (the shared `gate` region), and TestDocsSearch boots through it. The blank `beachcomber/typesense` import is no longer code: the prose names the package, because importing it in the test binary would register the engine globally. The search fence is the existing `search` region, which also re-checks the IDs in SQL.
|
||||||
|
- boardwalk: unchanged code, now inside `mountAdmin(mux)`, which `ExampleHandler` serves through httptest.
|
||||||
|
- bonfire: `func main` became `importPostsCommand()` plus `acmeMain(args, stdout, stderr) int`, which returns the exit code where main called `os.Exit`. `NewRoot` gets the stdout parameter, and `Fail` gets the stderr parameter. The catalog fence became `ExampleCatalog_Has`, which reuses the blog:import command, prints the `nil` error and checks `ErrUnknownCommand` for an unregistered name.
|
||||||
|
- bouncer: `Routes`/`Login` became the existing `ExampleNewJWTGuard`: guard name `acme.auth`, test secret, locale `pl`. `users.FindByID` gained the README's doc comment. `RefreshRoute` is unchanged, and TestDocsRefreshRoute runs it on a production compass config with `app.url` set to https and `auth.cookie.domain`.
|
||||||
|
- cabana: `postAdmin` (`acme.blog.post`, `controllers/post`) became the existing `PostsController` (`acme.blog.posts`, `controllers/posts`). `AdminFS` returns `os.DirFS("testdata/docs")`, and its comment says a real plugin returns an `embed.FS`. The `//go:embed` var is not shown.
|
||||||
|
- compass: the fence became the existing `ExampleOpen` (temporary dir, `Environ` override, `MergePlugin`, `Persist`). The YAML block below it now matches the directory `writeConfig` lays out.
|
||||||
|
- conga: the job fence split into `ImportPostsArgs`/`Kind`/`BlogPlugin.Jobs` plus `ImportPostsJob`. The dispatch region uses `Count: 1`, not 100. The schedule is on a new `FeedPlugin`, with commands `feed:prune` and `feed:sync`, not on `BlogPlugin`, so the worker in TestDocsDispatch never fires a scheduled command. The reindex region keeps the row id and returns a wrapped error where the README had an empty branch. The worker region sits in `runWorker`, and TestDocsDispatch now runs its body inside it.
|
||||||
|
- cooler: `Sidebar` became the existing `ExampleFromApp`, which caches popular titles. The purge fence is the existing `articlesController`, where `FormAfterUpdate` delegates to `purge`. `AllowExport` is unchanged.
|
||||||
|
- diary: the `publish` helper became the existing `blogLog` var and `ExampleFor`. `run` gained a `commands` parameter, an error check after `NewRoot`, and a final `bonfire.Execute`, in place of the `// ...` elisions.
|
||||||
|
- festival: the combined Collect/IsHandled fence became `PostPublished` with `ExampleBus_Fire`, plus `PostFormExtended`, `Collected` and `ExampleBus_Collect`. The prose was adjusted to match.
|
||||||
|
- fetchguard: the fetch fence sits in `fetchImage(ctx, cfg, imageHost, imageURL)`. The allow-list host is the `imageHost` parameter (images.example.com in production), so the test can allow 127.0.0.1 and show the private_ip refusal. `app.Config` became the `cfg` parameter. The client fence returns an error with the Retry-After value instead of `// ...`, and the test runs it through `WithTransport` with a stub vendor.
|
||||||
|
- flare: `row` is a new `PushSubscription` test model. `models.User`/`models.PushSubscription` became `User`/`PushSubscription` with `acme_blog_*` tables, and the subscription query gained `Order("id")`. The `// In Boot:` fragment is the `publish-source` region of `publishSubscriptions(app, gdb)`.
|
||||||
|
- kiosk: `"plugins/acme/blog"` became the `dir` parameter (prose: "plugins/acme/blog, say"). The registry fence returns `nil, nil` for a disabled registry and a `fmt.Errorf` for an unlisted plugin. The CheckT fence reuses the existing `TestPluginManifest`, which checks `testdata/literal` instead of `"."`, as its doc comment says.
|
||||||
|
- lagoon: the model fence's `Post` is the shared fixture: more columns, no `NewEncrypted` assignment, and a `nil` translator in `create-post`. The OnDatabase callback appends to a log instead of an empty body. The migrations fence is the fixture's two-step set on the `acme_blog_*` tables. The open fence is unchanged, inside `openDatabase(ctx, app)`.
|
||||||
|
|
||||||
|
### Retags (R6)
|
||||||
|
|
||||||
|
None. Every fence stays `go`.
|
||||||
|
|
||||||
|
### Snippets not fully executable (R3)
|
||||||
|
|
||||||
|
None is unexecuted. One partial note: in fetchguard's `fetch` region, the success path and the non-200 branch need a public HTTPS host, because `Fetch` takes no transport seam and refuses loopback. TestDocsFetchImage runs the private_ip, host-not-allowed and plain-http branches. The other lines are compiled but not reached offline.
|
||||||
|
|
||||||
|
### Verification
|
||||||
|
|
||||||
|
- Task 2 `<verify>`: all passed. `go vet` and `go test -short -count=1` on the 15 modules are ok. No bare go fence remains in the 15 READMEs. There are 69 `go src=modules/` fences (at least 35 required). `TestDocsTree` is ok. `summer docs:build --check` reports no problems found, and `summer docs:sync` reports all snippets up to date. go.mod and go.sum are unchanged.
|
||||||
|
- Before each commit: gofmt clean, `go vet` of the group, `go test -short` of the group, docs:build --check and docs:sync. Before the first and last commits, `go vet ./...` and `go test -short -count=1 ./...` (root) also passed. `examples/hello` `go test -short ./...` is ok.
|
||||||
|
- Docker (socket reachable as this user, no sudo needed): `go test -count=1 -run TestDocs` passed for beachcomber (TestDocsSearch, TestDocsDeclarations), conga (TestDocsDispatch with the reindex and worker regions, TestDocsSchedule), flare (TestDocsSubscriptionSource on its own postgres:16-alpine testcontainer), lagoon (TestDocsModels, Migrate, Queries, Relations, Transactions, OnDatabase, ModelDeclarations and the new TestDocsOpenFromApp), and the non-Docker TestDocs* of bouncer, cabana, cooler, diary, festival, fetchguard and kiosk.
|
||||||
|
- `git log 48527e42..HEAD -- modules` shows no non-test `.go` file.
|
||||||
|
|
||||||
|
### Notes for the Task 3 executor
|
||||||
|
|
||||||
|
- Write an empty `go src=modules/<m>/example_test.go#Frag` fence, then run `go run ./cmd/summer docs:sync`. A refused reference prints the reason and writes nothing.
|
||||||
|
- Methods called only through an interface (by cabana.Activate, flare, festival and similar) are not reachable by name. Add a `TestDocsDeclarations` that calls each shown method and asserts its result (done here for bouncer, cabana, festival and beachcomber).
|
||||||
|
- A `#TestName` target (a Test is a root) works across files, for example `checkt_test.go#TestPluginManifest`.
|
||||||
|
- flare has no Postgres harness. TestDocsSubscriptionSource starts its own container through `postgres.Run` plus `testcontainers.CleanupContainer` and skips under -short. lighthouse and postcard have harnesses (`DocsEnv`, store_postgres_test).
|
||||||
|
- lagoon/export_docs_test.go now also exports `DocsDSN(t, name)`, for a test that needs a DSN in config rather than a handle.
|
||||||
|
- Process-wide state: diary's TestDocsRun uses `t.Chdir(t.TempDir())` and `t.Cleanup(diary.Reset)`. sunscreen's slog default needs the same care.
|
||||||
|
- The internal/docsite fixtures listed under Task 1 still carry bare go fences in module READMEs. They have to change when Task 3 drops the exemption.
|
||||||
|
|
||||||
|
## Task 3: lighthouse .. wristband, drop README exemption, full gates (complete)
|
||||||
|
|
||||||
|
All 32 bare Go fences in the 16 READMEs are now top-level `src=` fences, 58 in all after splits. The README exemption is gone from `check_policy.go`. Under `modules/`, only README.md and `_test.go` files changed.
|
||||||
|
|
||||||
|
### Commits
|
||||||
|
|
||||||
|
| Hash | Message |
|
||||||
|
|------|---------|
|
||||||
|
| 6409837b | docs(phrasebook,sieve,towel,wire,wristband): compile README Go examples via src= (quick-261118-qsd) |
|
||||||
|
| cd55a398 | docs(pier,seaglass,sunrise,sunscreen,tide): compile README Go examples via src= (quick-261118-qsd) |
|
||||||
|
| a2551d83 | docs(pact,party,surf): compile README Go examples via src= (quick-261118-qsd) |
|
||||||
|
| 1e56d750 | docs(lighthouse,postcard,signpost): compile README Go examples via src= (quick-261118-qsd) |
|
||||||
|
| 8c03cc36 | feat(docsite): require src= on Go code blocks of module READMEs (quick-261118-qsd) |
|
||||||
|
|
||||||
|
No module had uncommitted edits from another session, so none was skipped. 6409837b also carries the docs:sync refresh of `docs/architecture/request-lifecycle.md` (it now shows `withAcmeScope` and `listPosts` as their own fences before `ExampleWithLocale`) and `docs/services/oauth-server.md` (`newServer` now takes the backend), because their sources changed in that commit.
|
||||||
|
|
||||||
|
### Fence map
|
||||||
|
|
||||||
|
Old line is the README line at c517db56. Kinds: Ex = Example with Output, R = docs:start region, D = declaration (a Test counts as a declaration root). All targets are in `modules/<m>/example_test.go` unless another file is named.
|
||||||
|
|
||||||
|
| Module | Old line | New src= targets (kind) | Runs in |
|
||||||
|
|--------|----------|-------------------------|---------|
|
||||||
|
| lighthouse | 82 | RoomsPlugin.Boot (D, new) | -short (TestDocsRoomsPlugin, centrifugo driver) |
|
||||||
|
| lighthouse | 115 | RoomsPlugin.Routes (D, new) | -short (TestDocsRoomsPlugin) |
|
||||||
|
| lighthouse | 127 | bind (R) | Docker (TestDocsBroadcast) |
|
||||||
|
| lighthouse | 138 | bulk (R) | Docker (TestDocsBroadcast) |
|
||||||
|
| lighthouse | 160 | publications (R, new, inside ExampleMemoryDriver) | -short |
|
||||||
|
| pact | 51 | BlogPlugin.Routes, BlogPlugin.Permissions (D, new) | -short (new TestDocsDeclarations) |
|
||||||
|
| pact | 88 | BlogPlugin.Schedule (D) | -short (ExampleHasSchedule) |
|
||||||
|
| party | 37 | example_plugin_test.go: BlogPlugin, .ID, .Requires, .Register, .Boot (D); registerBlog (D, new) | -short (ExamplePlugin, TestDocsActivate) |
|
||||||
|
| party | 63 | activate (R, new, in startApp) | -short (TestDocsActivate) |
|
||||||
|
| phrasebook | 47 | ExampleTranslator_Get, ExampleTranslator_Choice (Ex); title (D, new) | -short (ExampleActivate, new) |
|
||||||
|
| pier | 54 | example_mcp_test.go: blogTools (D) | -short (TestExampleBlogPlugin) |
|
||||||
|
| postcard | 51 | sendWelcome (D, new) | -short (TestDocsMailer) |
|
||||||
|
| postcard | 77 | TestWelcomeMail (D, a Test root, new) | -short |
|
||||||
|
| postcard | 128 | BlogPlugin.MailPartialsFS, BlogPlugin.MailPartials (D, new) | -short (TestDocsMailer via postcard.BootPlugin and direct calls) |
|
||||||
|
| postcard | 239 | fixedOverrides, fixedOverrides.MailOverrides, newTestMailer (D, new) | -short (TestDocsMailer) |
|
||||||
|
| postcard | 327 | previewWelcome (D, new) | -short (TestDocsMailer) |
|
||||||
|
| seaglass | 34 | ExampleSanitizeReport, ExampleCheck (Ex, new file) | -short |
|
||||||
|
| sieve | 46 | blogPost, postResponse, shape (D, new); Example_shape (Ex, new) | -short |
|
||||||
|
| signpost | 35 | BlogPlugin.MenuItemTypes (D) | -short (TestBlogPluginResolveAllPosts) |
|
||||||
|
| signpost | 79 | ExampleRegistry_Resolve (Ex); EntriesController.DependentOptions (D) | -short (ExampleReferenceOptions) |
|
||||||
|
| signpost | 93 | example_content_test.go: NewsPlugin.MenuItemTypes, NewsPlugin.describe (D) | -short (ExampleRegistry_MatchPath) |
|
||||||
|
| signpost | 124 | example_content_test.go: listen (R, new, in listenForMoves) | -short (TestDocsRecordListener) |
|
||||||
|
| sunrise | 74 | newScript (D, new file) | -short (Example) |
|
||||||
|
| sunscreen | 35 | startLogging (D, new) | -short (TestDocsInstallDefault) |
|
||||||
|
| sunscreen | 44 | ExampleWrap_json (Ex, new) | -short |
|
||||||
|
| surf | 51 | BlogPlugin.Middlewares, BlogPlugin.Buckets, BlogPlugin.Routes, showPost (D) | -short (TestDocsDeclarations, ExampleAssemble) |
|
||||||
|
| tide | 44 | parity (D, new) | -short (TestDocsParity) |
|
||||||
|
| tide | 73 | broadcasts (R, new) | -short (TestDocsBroadcasts, loopback recorder) |
|
||||||
|
| towel | 32 | withAcmeScope, listPosts (D, new); ExampleWithLocale (Ex) | -short |
|
||||||
|
| wire | 33 | postJSON (D), ExampleWriteJSON (Ex) | -short |
|
||||||
|
| wristband | 44 | newServer, routes, approve (D, new or changed) | -short (TestDocsRoutes, TestDocsApprove, ExampleServer_Metadata) |
|
||||||
|
| wristband | 90 | newOIDCServer (D), providerRoutes (D, new) | -short (TestDocsRoutes, ExampleNewOIDCServer) |
|
||||||
|
|
||||||
|
Totals over the whole quick task: 68 bare fences in 32 READMEs became 129 `src=` fences (breakwater 2, Task 2 69, Task 3 58).
|
||||||
|
|
||||||
|
### Part B: README exemption removed
|
||||||
|
|
||||||
|
- `check_policy.go`: the "Go-lexer fence needs src=" rule runs on every page. `headingProblems` still runs on docs/ pages only. The doc comment no longer carries the D-18 "rendered as written" remark.
|
||||||
|
- `checks_test.go`: `TestNestedFenceChecks` now expects `modules/fixture/README.md:7: snippet: go code block has no src= reference`, and the Task 1 README expectations are unchanged. `TestFencePolicy`'s README uses a `text` fence in the clean case and expects the bare `go` fence it appends at README:17 to be reported.
|
||||||
|
- `docs/console/utilities.md` says the bare-Go-fence failure applies to docs pages and module READMEs alike. `CLAUDE.md` "Documentation rules" gained the bullet on `src=` Go code blocks.
|
||||||
|
|
||||||
|
### Deviations from Plan
|
||||||
|
|
||||||
|
**1. [Rule 3 - Blocking] docsite fixtures carried bare go fences in module READMEs.**
|
||||||
|
- Found during: Part B (`go test ./internal/docsite`).
|
||||||
|
- Fix: the `modules/demo/README.md` of `testdata/clean` and five violation cases (`callout-unknown-readme`, `command-in-readme`, `identifier-module-readme`, `link-module-readme`, `snippet-readme-src`) replaced their fenced `import` block with the real README form: an inline `` `import "..."` `` line, a blank line and a `**Name:**` mnemonic. That is three lines, so every `want.txt` line number still holds. `theme_test.go`'s `themeTree` README fence became `go src=modules/alpha/alpha_test.go#name`, backed by an `alpha_test.go` whose `TestName` calls `name()`. The highlighting assertions (`func`, `"x"`, `// done`) still pass.
|
||||||
|
- Commit: 8c03cc36.
|
||||||
|
|
||||||
|
**2. [Rule 1 - Bug] lighthouse `TestFromSelectsDriver/unknown_lists_registered` asserted an exact run of driver names.**
|
||||||
|
- Found during: the lighthouse conversion. The README's Boot/Mount example now runs on the real centrifugo driver, so `example_test.go` imports `lighthouse/centrifugo`, and "centrifugo" sorts between the drivers that test registers.
|
||||||
|
- Fix: the assertion checks `acme-nil-driver, ` and `log, memory, null` separately, with a comment that names the reason. It still proves the error lists the registered drivers.
|
||||||
|
- Commit: 1e56d750.
|
||||||
|
|
||||||
|
**3. A refactor of existing examples that docs/ pages show.** towel `ExampleWithLocale` now uses the top-level `withAcmeScope`/`listPosts` the README shows, and wristband `newServer` takes the backend. docs:sync refreshed the two docs pages, and `request-lifecycle.md` gained the two declaration fences so the page stays self-contained.
|
||||||
|
|
||||||
|
### README code adapted (R7)
|
||||||
|
|
||||||
|
- lighthouse: `Plugin` became `RoomsPlugin`. `lookupAcmeUser` and `isRoomMember` are real fixtures (user 42 is "Ada", the member of room 7). The blank import of `lighthouse/centrifugo` is no longer shown as code, but the prose still says to import it and the test binary does. The Bind and bulk fences are the existing `bind`/`bulk` regions: model `Post` instead of `models.Post`, the bulk event is `blog.posts_imported` with a `count`-only payload, and the rows come from a `titles` slice. The publications fence sits in the new `ExampleMemoryDriver`, after a `Publish` and a `Broadcast`.
|
||||||
|
- pact: `Plugin` became the existing `BlogPlugin`, whose type comment now says "routes, permissions and a schedule". The compile-time assertions moved into the prose (`var _ pact.HasRoutes = (*BlogPlugin)(nil)`). The handlers write bodies, so the test can serve them. The schedule fence is the existing three-entry schedule (`blog:send-digest` and `blog:sync-feed` instead of `blog:ping`).
|
||||||
|
- party: `Plugin` became the existing `BlogPlugin` from `example_plugin_test.go`, one fence per method. `func init()` is `registerBlog()`, whose comment says a real package names it init, because an `init` is never reachable from a Test. `compass.Load("config")` became `compass.Load(dir)` inside `startApp(dir)`, which returns errors instead of the bare `return err`.
|
||||||
|
- phrasebook: the `Example()` function became the existing `ExampleTranslator_Get` and `ExampleTranslator_Choice`, with `langFS` an `fstest.MapFS`; the prose explains this, and that a plugin uses `//go:embed lang`. `Title` became `title`, run by the new `ExampleActivate` before and after `phrasebook.Activate`.
|
||||||
|
- pier: the two-tool fence became the existing `blogTools` (three tools and a prompt). The prose says the plugin's `MCP` method returns it.
|
||||||
|
- postcard: `SendWelcome` became `sendWelcome`. The partials plugin is `BlogPlugin`, and its `//go:embed` var and `HasMailPartials` assertion moved into the prose. `mailFS` gained `views/mail/partials/note.htm` (the README's own partial). The other declarations are unchanged.
|
||||||
|
- seaglass: the `// clean ==` comments became `// Output:` lines. `Check` runs on one kept and one refused input.
|
||||||
|
- sieve: `Post`/`PostResponse` became `blogPost`/`postResponse`, because the test package already has a `post` type. The prose's `func(p Post)` now reads `func(p blogPost)`. `Example_shape` runs `shape` once with good IDs and once with a bad one.
|
||||||
|
- signpost: the content plugin fence is the existing `BlogPlugin.MenuItemTypes`. The menu-plugin fence became `ExampleRegistry_Resolve` plus the existing `EntriesController.DependentOptions`, which looks the registry up on the app instead of `c.registry()`. The composite-literal fragment became the existing `NewsPlugin.MenuItemTypes` and `NewsPlugin.describe`, so the following paragraph now points at the `Kind`/`Tools`/`Match` shown above. The listener's `log.Printf` became `logger.Printf` on a `*log.Logger` parameter.
|
||||||
|
- sunrise: the handler is unchanged and served through httptest by `Example`.
|
||||||
|
- sunscreen: `func main` became `startLogging(stderr io.Writer)`, which also logs a token attribute and a Bearer line. TestDocsInstallDefault restores `slog.Default`, `log.Writer` and `log.Flags`. The JSON fence became `ExampleWrap_json`: its time attribute is dropped, `key`/`err` are literals, and the output line is exact.
|
||||||
|
- surf: the 62-line `Plugin` became the existing `BlogPlugin` declarations. The `blog.no-store` middleware is now the JWT `acme.auth` guard. The comment bucket allows 1 per minute instead of 5, and there is an auth group with `/me`.
|
||||||
|
- tide: the record/replay fence is `parity(ctx, dir, reference, port, w)`. Paths are under `dir` instead of `testdata/parity`, and targets are parameters (httptest servers) instead of 127.0.0.1:8000/8080. A `MismatchError` is unwrapped, because the old fence returned on it and never printed a diff. Diffs go to `w`. The broadcast fence is the `broadcasts` region: an explicit `Listen` (a free loopback port in the test, the default otherwise), and a golden path under `dir`.
|
||||||
|
- towel: the declarations are unchanged. `ExampleWithLocale` now runs them, with and without a locale.
|
||||||
|
- wire: `postJSON` gained a `Pinned` field, and `ExampleWriteJSON` uses a fixed time instead of `time.Now()`.
|
||||||
|
- wristband: `NewServer`/`Routes`/`Approve` became `newServer`/`routes`/`approve`, and `NewProvider`/`ProviderRoutes` became `newOIDCServer` (which also sets `RefreshEnabled`) and `providerRoutes`. They run through a small `muxRouter` (a `pact.Router` over `http.ServeMux`) and the in-memory stores that `export_docs_test.go` exports (`DocsBackend`, `DocsOIDC`).
|
||||||
|
|
||||||
|
### Retags (R6)
|
||||||
|
|
||||||
|
None. Every fence stays `go`.
|
||||||
|
|
||||||
|
### Snippets not fully executable (R3)
|
||||||
|
|
||||||
|
None is unexecuted. Two partial notes:
|
||||||
|
- lighthouse `bind` and `bulk` run only in the Docker run (TestDocsBroadcast). They were already shown on the Realtime page.
|
||||||
|
- tide `broadcasts` waits for the default 1 s settle, so TestDocsBroadcasts takes about one second under -short.
|
||||||
|
|
||||||
|
### Output-less Examples
|
||||||
|
|
||||||
|
The todo's "Output-less Example" route was not used in any task. Extract's run rule refuses an Example without `// Output:`, and the rule was not weakened. One trap came up: a `// docs:end` line directly above `// Output:` merges into one comment group, and go/doc then sees no Output. `ExampleMemoryDriver` keeps a blank line between the two.
|
||||||
|
|
||||||
|
### Verification (Task 3 `<verify>`, all passed)
|
||||||
|
|
||||||
|
- `go vet ./...`: ok
|
||||||
|
- `go test -short -count=1 ./...`: all ok
|
||||||
|
- `cd examples/hello && go test -short -count=1 ./...`: ok
|
||||||
|
- `go test -count=1 ./cmd/summer -run 'TestDocsTree|TestCommandsDocumented'`: ok
|
||||||
|
- `TestNestedFenceChecks`: PASS
|
||||||
|
- `summer docs:build --check`: no problems found. `summer docs:sync`: all snippets up to date
|
||||||
|
- Bare `go` fences in `modules/*/README.md`: 0. `go src=modules/` fences: 129 (at least 68 required)
|
||||||
|
- `git log --grep=quick-261118-qsd 830f3053..HEAD -- modules`: no non-test `.go` file. go.mod and go.sum are unchanged, both in the worktree and against 830f3053
|
||||||
|
- `PHASE35_BASE_TAG=v0.6.5 scripts/check-phase35.sh --additive`: passed (4 packages against v0.6.5)
|
||||||
|
- A built site captions the README `src=` fences, for example 2 figcaptions in `api/tide.html` and 8 in `api/postcard.html`
|
||||||
|
- Docker (socket reachable as this user, no sudo): non-short `go test -count=1` passed on all 16 Task 3 modules and `internal/docsite`, including lighthouse TestDocsBroadcast (postgres testcontainer) and the pier, postcard, sunrise and surf Docker tests
|
||||||
|
|
||||||
|
### Follow-ups for the orchestrator
|
||||||
|
|
||||||
|
- ROADMAP 11.1 SC4 can be widened back to "every Go example in the docs". ROADMAP.md was not edited.
|
||||||
|
- Moving `.planning/todos/pending/readme-go-fences-src.md` to `completed/` and the g15office comment (gplauwlb) are left to the orchestrator.
|
||||||
|
- Optional: `cmd/summer/phase11_1_acceptance_test.go` `docsGoFences` still scans docs/ only. The docsite policy now covers READMEs, so extending it is not required.
|
||||||
|
|
||||||
|
## Self-Check: PASSED (Task 1)
|
||||||
|
|
||||||
|
- Commits 721830c5 and 48527e42 exist; rev-list 830f3053..HEAD = 2.
|
||||||
|
- Only other sessions' uncommitted edits remain in the working tree.
|
||||||
|
|
||||||
|
## Self-Check: PASSED (Task 2)
|
||||||
|
|
||||||
|
- Commits a0f5b5e5, becb31fb, d04454c5 and c517db56 exist; rev-list 830f3053..HEAD = 6.
|
||||||
|
- modules/boardwalk/example_test.go exists; every src= target in the 15 READMEs resolves (docs:build --check and docs:sync are clean).
|
||||||
|
- Only other sessions' uncommitted edits, plus this SUMMARY, remain in the working tree.
|
||||||
|
|
||||||
|
## Self-Check: PASSED (Task 3)
|
||||||
|
|
||||||
|
- Commits 6409837b, cd55a398, a2551d83, 1e56d750 and 8c03cc36 exist; rev-list 830f3053..HEAD = 11.
|
||||||
|
- modules/seaglass/example_test.go, modules/sunrise/example_test.go, modules/wristband/export_docs_test.go and modules/party/export_docs_test.go exist; every src= target in modules/*/README.md resolves (docs:build --check and docs:sync are clean).
|
||||||
|
- Only other sessions' uncommitted edits, plus this SUMMARY, remain in the working tree.
|
||||||
Reference in New Issue
Block a user