From dce002ee45b49833975a0ae9a5caad63c570107c Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Sat, 14 Nov 2026 16:08:01 +0100 Subject: [PATCH] docs(35-09): complete site name safety unit tests plan --- .../35-09-SUMMARY.md | 234 ++++++++++++++++++ 1 file changed, 234 insertions(+) create mode 100644 .planning/phases/35-mail-templates-and-layouts-editor/35-09-SUMMARY.md diff --git a/.planning/phases/35-mail-templates-and-layouts-editor/35-09-SUMMARY.md b/.planning/phases/35-mail-templates-and-layouts-editor/35-09-SUMMARY.md new file mode 100644 index 00000000..5ac7b3e2 --- /dev/null +++ b/.planning/phases/35-mail-templates-and-layouts-editor/35-09-SUMMARY.md @@ -0,0 +1,234 @@ +--- +phase: 35-mail-templates-and-layouts-editor +plan: 09 +subsystem: mail +tags: [postcard, cabana, tests, gate, gap-closure, CR-01] + +requires: + - phase: 35-08 + provides: decoded URL-scheme check (unsafeMarkup), postcard.UnsafeText, render-time site-name drop, Branding 422, inliner fallback, literal footer +provides: + - named Docker-free regression tests for site names on the send path, the scheme check, the unsafe inlined result and the literal footer + - cabana Postgres test for the Branding refusal and names stored before the check + - check-phase35.sh requires every new name; IN-03 self-test compares the planted consumer's go.mod + - 35-VALIDATION.md CR-01, WR-01, WR-05 rows and the CR-01 status line +affects: [35-verify-work, mail, postcard, cabana] + +actuals: + tokens: 9052 + tasks: 3 + commits: 5 +plan_head_before: 8751f922307fe476961a5e97e1525b8bbff84c52 +plan_head_after: fbbfce07024f162c30e8ce4d44a7e0984a7a4b46 + +tech-stack: + added: [] + patterns: + - "Tests that pin shipped behaviour show they are not vacuous through mutation runs (break the rule, see the named test fail, restore with git checkout)" + - "Site-name tests are table subtests named //" + +key-files: + created: + - modules/postcard/sitename_test.go + - modules/postcard/safety_test.go + - modules/cabana/mail_site_name_postgres_test.go + modified: + - modules/cabana/mail_screens_smoke_test.go + - scripts/check-phase35.sh + - .planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md + +key-decisions: + - "The mail screens test env reads mail.from from its configuration (default noreply@example.test unchanged), so a mutate hook sets the sender; the plan assumed it already did" + +patterns-established: + - "A Postgres test models data saved before a save-time check by writing the row through env.gdb and clearing it in t.Cleanup" + +requirements-completed: [CR-01, WR-01, WR-05, D-13, D-14, D-21] + +coverage: + - id: D1 + description: "Prose site names from mail.from and Branding send on the default and system layouts on the file-version, override and override-failure fallback paths" + requirement: CR-01 + verification: + - kind: unit + ref: "modules/postcard/sitename_test.go#TestSiteNameSend" + status: pass + human_judgment: false + - id: D2 + description: "Unsafe site names are dropped on every render path with one value-free warning; editor validate and preview are not refused" + requirement: D-14 + verification: + - kind: unit + ref: "modules/postcard/sitename_test.go#TestUnsafeSiteNameDropped" + status: pass + - kind: unit + ref: "modules/postcard/sitename_test.go#TestUnsafeText" + status: pass + human_judgment: false + - id: D3 + description: "Anchored, decoded scheme check: prose passes, every URL-bearing attribute and encoded form refused, send and editor with inlining on and off" + requirement: WR-05 + verification: + - kind: unit + ref: "modules/postcard/safety_test.go#TestURLSchemeCheck" + status: pass + human_judgment: false + - id: D4 + description: "An inlined result that fails the check sends the style-block version with one warning per layout" + requirement: WR-05 + verification: + - kind: unit + ref: "modules/postcard/safety_test.go#TestInlineUnsafeOutput" + status: pass + human_judgment: false + - id: D5 + description: "Footer prints the site name literally and escaped; body argument stays Markdown" + requirement: WR-01 + verification: + - kind: unit + ref: "modules/postcard/sitename_test.go#TestFooterSiteNameLiteral" + status: pass + human_judgment: false + - id: D6 + description: "Branding 422 on site_name in en and pl, prose names save, stored unsafe names never block saves or sends, mail.from prose name shows" + requirement: D-13 + verification: + - kind: integration + ref: "modules/cabana/mail_site_name_postgres_test.go#TestMailSiteNameSafety" + status: pass + human_judgment: false + - id: D7 + description: "Branding refusal line under the Site name field in the embedded admin" + verification: [] + human_judgment: true + rationale: "Visual; recorded as a Manual-Only row in 35-VALIDATION.md for /msd-verify-work 35" + +duration: 31min +completed: 2026-11-14 +status: complete +--- + +# Phase 35 Plan 09: Unit tests for the CR-01 site name safety fix Summary + +**Seven named postcard tests and one cabana Postgres test pin the 35-08 fix (prose site names send on every render path, unsafe ones are dropped or refused at save, decoded scheme check, style-block fallback, literal footer). Fourteen mutation runs prove they are not vacuous, and `check-phase35.sh --all` requires every name and passes with Docker.** + +## Performance + +- **Duration:** 31 min +- **Started:** 2026-11-14T14:35:52Z +- **Completed:** 2026-11-14T15:07:06Z +- **Tasks:** 3 +- **Files modified:** 6 + +## Accomplishments + +- `TestSiteNameSend`, `TestUnsafeSiteNameDropped`, `TestUnsafeText` (Task 1, tracer) cover the verifier's regression on a small MapFS catalog. Subtests are named `//`. +- `TestURLSchemeCheck` covers 5 accepts and 21 refuses, each refuse checked for its error text and for a snippet that points at the markup. It also covers the send path through `assertFileFallback` and the editor, each with inlining on and off. `TestInlineUnsafeOutput` uses plain and entity-encoded links and checks the per-layout warning key. `TestFooterSiteNameLiteral` covers the footer (Task 2). +- `TestMailSiteNameSafety` covers the admin side with six subtests: `refused_on_save` (en and pl), `prose_names_saved`, `preview_drops_unsafe_name`, `stored_unsafe_name_saves`, `stored_unsafe_name_send` and `mail_from_prose_name` (Task 3). +- IN-03: the self-test's workspace-modfile case now compares the planted consumer's go.mod with `cmp -s` against a copy taken before the run. +- 35-VALIDATION.md maps CR-01 (3 rows), WR-01 and WR-05, closes the open item with a "CR-01 status" line, and adds a Manual-Only row for the Branding refusal and the Wave 0 entry. + +## Task Commits + +1. **Task 1: site-name send tests (tracer)**: `e0016e0c` test(postcard): site names on the built-in layouts never stop a send +2. **Task 2: scheme check, unsafe inlined output, literal footer**: `446a77ef` test(postcard): decoded URL scheme check, unsafe inlined output and the literal footer +3. **Task 3: cabana test, IN-03, validation map**: `54617f78` test(cabana): unsafe Branding site names refused at save, stored ones never block saves or sends; `e54be76c` test(35): self-test compares the planted consumer's go.mod; `fbbfce07` docs(35): validation map for the site name safety gap + +**Plan metadata:** recorded in the docs(35-09) completion commit. + +## Required test names (scripts/check-phase35.sh) + +- GO_TESTS (new): `./modules/postcard:` TestMailSafetySmoke, TestSiteNameSend, TestUnsafeSiteNameDropped, TestUnsafeText, TestURLSchemeCheck, TestInlineUnsafeOutput, TestFooterSiteNameLiteral +- DOCKER_TESTS (new): `./modules/cabana:TestMailSiteNameSafety` + +## Gate output + +`bash scripts/check-phase35.sh --all` exit 0, with the Docker daemon up (PHASE35_ALLOW_NO_DOCKER not used): +- PASS self-test (includes `PASS self-test workspace-modfile`), go (24 postcard top-level tests by name), consumers, admin, docs, marker, additive (8 packages against v0.6.3), docker (full `go test ./...`, 12 cabana top-level tests by name, no skips) +- "Phase 35 gate passed" +- `git status --porcelain` of sm-user-plugin and sm-paymentgateway-plugin was empty before and after; go.mod and go.sum unchanged + +## Mutation runs (stand-ins for RED) + +Each test was green on its first run, as expected for tests of shipped code. Each mutation was applied, run, and then restored with `git checkout -- `: + +| # | Mutation | Failing tests | +|---|----------|---------------| +| M1 | validateHTML checks dangerousScheme over the whole document (35-06 rule) | TestSiteNameSend (all 14 subtests), TestUnsafeText | +| M2 | UnsafeText always false | TestUnsafeText, TestUnsafeSiteNameDropped (handler, mail_from_source, ...) | +| M3 | scriptURLText without the scheme boundary | TestUnsafeText, TestSiteNameSend (mail_from) | +| M4 | site-name warning not rate-limited | TestUnsafeSiteNameDropped (warning count) | +| M5 | formaction, background, poster, xlink:href dropped from urlAttributes | TestURLSchemeCheck refuse/{button_formaction,table_background,video_poster,svg_xlink_href} | +| M6 | hasDangerousScheme keeps whitespace and case | TestURLSchemeCheck refuse/{href_space_mixed_case,tab_split,newline_split} | +| M7 | text tokens checked for schemes | TestURLSchemeCheck accept/prose_*, editor/*; TestSiteNameSend | +| M8 | an inlined result that fails the check stops the send | TestInlineUnsafeOutput/{plain,encoded} | +| M9 | footer partial renders text as Markdown | TestFooterSiteNameLiteral (all 6 layout cases, partial/text_literal) | +| M10 | Branding BeforeValidate accepts unsafe names | TestMailSiteNameSafety/refused_on_save | +| M11 | layouts get the Branding name unfiltered | TestMailSiteNameSafety/{preview_drops_unsafe_name,stored_unsafe_name_send} | +| M12 | settings refusal returned unlocalized | TestMailSiteNameSafety/refused_on_save | +| M13 | pre-35-08 behaviour (M1 + M11) | TestMailSiteNameSafety: 5 of 6 subtests, including stored_unsafe_name_saves | +| M14 | env mailer ignores mail.from (helper before the deviation) | TestMailSiteNameSafety/mail_from_prose_name | +| M15 | self-test: the modfile run appends to the planted consumer's go.mod | `refuse: self-test the modfile run wrote the planted consumer's go.mod` | + +M11 alone leaves `stored_unsafe_name_saves` green, because the decoded check no longer reads text. A stored name could only refuse a save with both halves of the old code in place, which is what M13 restores. + +## Files Created/Modified + +- `modules/postcard/sitename_test.go`: TestSiteNameSend, TestUnsafeSiteNameDropped, TestUnsafeText, TestFooterSiteNameLiteral, fixture `siteNameMailer` +- `modules/postcard/safety_test.go`: TestURLSchemeCheck, TestInlineUnsafeOutput +- `modules/cabana/mail_site_name_postgres_test.go`: TestMailSiteNameSafety, helpers `storedSiteName`, `putInLanguage`, `moveWelcome` +- `modules/cabana/mail_screens_smoke_test.go`: env mailer From read from `mail.from` (deviation 1) +- `scripts/check-phase35.sh`: GO_TESTS/DOCKER_TESTS entries, IN-03 `cmp -s` +- `.planning/phases/35-mail-templates-and-layouts-editor/35-VALIDATION.md` + +## Decisions Made + +- The mail screens env takes its sender from `mail.from` in its configuration (see deviation 1). + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 3 - Blocking] The mail screens env ignored mail.from** +- **Found during:** Task 3 (`mail_from_prose_name`) +- **Issue:** `newMailScreensEnvWith` built the mailer with a hard-coded `From: "noreply@example.test"`, so the plan's "mail.from through the mutate hook" never reached the mailer. +- **Fix:** the env sets `mail.from` to `noreply@example.test` before `mutate` and builds the mailer with `cfg.String("mail.from")`. Every other mail test sees the same sender as before. This is a test-helper change, not production code. The full cabana Docker suite is green. +- **Files modified:** modules/cabana/mail_screens_smoke_test.go +- **Verification:** M14 above; `go test ./modules/cabana` (Docker) green +- **Committed in:** `54617f78` + +**2. [Note] No production defects found** +- None of the new tests exposed a defect in the 35-08 code, so no `fix(...)` commits were needed. The prohibition on production changes holds: only test files, the gate script and the validation doc changed. + +--- + +**Total deviations:** 1 auto-fixed (blocking, test helper), 1 note +**Impact on plan:** none on scope; the mail.from case runs in its own environment as planned. + +## TDD Gate Compliance + +Tasks 2 and 3 carry `tdd="true"`, but they pin code 35-08 already shipped, so no failing commit was possible (CLAUDE.md keeps every commit green). As the plan directs, the mutation runs M1-M15 above stand in for RED. Each one shows a named test failing against broken code and passing against the shipped code. + +## Issues Encountered + +- `gofmt -l` still lists modules/postcard/store_postgres_test.go and modules/cabana/mail_routes.go. Both predate this plan and were left alone, as in 35-08. + +## Verification + +- `go vet ./...` and `go test -short ./...` were green after every code commit. `go test ./modules/postcard` and `go test ./modules/cabana` (Docker) were green, and `check-phase35.sh --all` ran the full `go test ./...`. +- Acceptance greps: 3 `func Test` lines in sitename_test.go for Task 1 and 1 for the footer; 2 in safety_test.go; 1 in the cabana file; no `t.Skip` in the Docker-free files; 7 encoded-colon lines in safety_test.go; no non-comment `unsafe_name_current_behaviour` in modules/cabana; no non-comment `status --porcelain -- go.mod` and 1 `cmp -s` in `self_test_consumers`; 6 CR-01 lines, 2 WR-01/WR-05 lines and 1 "CR-01 status" line in 35-VALIDATION.md. +- Nothing pushed or tagged; no sibling repository changed. + +## User Setup Required + +None. + +## Next Phase Readiness + +- Ready for `/msd-verify-work 35`. It re-verifies the CR-01 gap, then runs the pending human items in 35-VERIFICATION.md (UAT test 1 re-run, scoped UAT test 8 re-run, real-inbox check, judgment-tier prohibitions) and the new Manual-Only row for the Branding refusal. + +--- +*Phase: 35-mail-templates-and-layouts-editor* +*Completed: 2026-11-14* + +## Self-Check: PASSED