fix(hub-client): unbreak main — escape lone tilde in changelog (bd-q5o7ekzn)

claude-notes/plans/2026-07-07-broken-main-ci-changelog-subscript.md

@@ -0,0 +1,161 @@
+# Broken `main`: PWA precache limit + changelog unclosed-subscript
+
+**Strand:** `bd-q5o7ekzn`
+**Date:** 2026-07-07
+**Branch under repair:** `main`
+**Failing check:** `TS Test Suite` (both `ubuntu-latest` and `macos-latest`)
+
+## Overview
+
+`main` went red on the **TS Test Suite**. Two *distinct* failures surfaced
+in sequence. The first came in with a merged feature (#379); the second I
+introduced myself while fixing the first — and then pushed to `main`
+without local verification, so `main` stayed red.
+
+The immediate content fix is a one-liner. The more important deliverable
+the user asked for is a **process** that stops this class of "push a fix,
+break something adjacent, push again" churn on `main`. This document
+records both.
+
+## The two failures
+
+### Failure 1 — PWA precache size ceiling (came in with #379, now fixed)
+
+- **Symptom:** `vite build` bundle succeeds (`✓ built in 15.55s`), then the
+  `vite-plugin-pwa` service-worker step throws:
+  ```
+  error during build:
+  Error:
+    Configure "workbox.maximumFileSizeToCacheInBytes" to change the limit...
+    - assets/wasm_quarto_hub_client_bg-*.wasm is 36.7 MB, and won't be precached.
+      at logWorkboxResult (…/vite-plugin-pwa/dist/chunk-…)
+  ```
+- **Root cause:** `hub-client/vite.config.ts` capped
+  `maximumFileSizeToCacheInBytes` at **35 MB** (comment: *"largest is
+  ~32MB"*). Workbox globs the WASM into the precache manifest; when a
+  globbed asset exceeds the size limit it emits a *warning*, and
+  `vite-plugin-pwa`'s `logWorkboxResult` **throws that warning as fatal**.
+  #379 (`render_printable` + self-contained inliner) grew the WASM past 35 MB.
+- **Why macOS-only at first:** the margin was razor-thin. Local/ubuntu WASM
+  = 36,689,700 B (≈10 KB *under* 35 MiB); macOS CI = 36,701,150 B (≈990 B
+  *over*). The build was flapping on the boundary.
+- **Fix (shipped, commit `6cfc098f`):** raise ceiling to **64 MB** with a
+  comment explaining the throw-on-exceed trap. Verified locally: PWA step
+  now emits `precache 73 entries (50270.00 KiB)` and writes `dist/sw.js`.
+  **This fix is correct and confirmed by CI** — the "Build WASM module"
+  step is now green.
+
+### Failure 2 — changelog unclosed subscript (self-inflicted, commit `6cd4dd5a`, NOT yet fixed)
+
+- **Symptom:**
+  ```
+  FAIL src/services/changelogRender.wasm.test.ts > changelog.md renders successfully
+  AssertionError: Render failed: Error: [Q-2-17] Unclosed Subscript
+  Tests  1 failed | 128 passed (129)
+  ```
+  Fails identically on ubuntu and macOS.
+- **Root cause:** the changelog entry I added in `6cd4dd5a` reads
+  `…the (now ~37MB) WASM module…`. The **lone `~`** is parsed by qmd as an
+  opening subscript delimiter with no closing `~` → `Q-2-17 Unclosed
+  Subscript`. `changelogRender.wasm.test.ts` renders `hub-client/changelog.md`
+  through the WASM parser and asserts `result.success === true`; the parse
+  error makes it `false`.
+- **This is the *only* remaining failure.** Run summary: `1 failed | 128
+  passed`; `Smoke-all WASM results: 63 passed, 23 skipped, 0 failed`.
+- The test's own docstring states its purpose: *"catches syntax errors
+  (e.g., unescaped underscores) before they reach users as an
+  '(unavailable)' changelog button."* It did its job; I ignored it by not
+  running it locally.
+
+## The real problem: pushed to `main` without local verification (twice)
+
+`CLAUDE.md` is explicit:
+
+> **GIT PUSH POLICY** … 2. Verify the full workspace compiles … 3. Verify
+> the full workspace tests pass … 4. Run `cargo xtask verify` … 5. Ask the
+> user for permission before pushing.
+
+and, for hub-client specifically:
+
+> passing tests alone is NOT sufficient. You must also verify that
+> `npm run build:all` … For CI … `npm run test:ci`.
+
+`cargo xtask verify` runs `cd hub-client && npm run test:ci`, and
+`test:ci = test && test:integration && test:wasm`. The failing test is in
+the `test:wasm` leg. **A single `cargo xtask verify` (or even just
+`cd hub-client && npm run test:wasm`) before pushing would have caught
+Failure 2 on my machine.** I ran only the isolated `vite build`, saw it go
+green, and pushed — verifying the thing I fixed but not the thing I broke.
+
+That is the process defect to fix: *verify the whole relevant suite, not
+just the file you touched, before every push to `main`.*
+
+## Plan
+
+### Phase 1 — Confirm the diagnosis (TDD: reproduce locally first)
+
+- [x] Reproduce Failure 2 locally: `cd hub-client && npm run test:wasm`
+      → expect `changelog.md renders successfully` to FAIL with
+      `[Q-2-17] Unclosed Subscript`. (This is the "verify the test fails"
+      step I skipped the first time.)
+- [x] Confirm no *other* WASM test is failing (expect exactly 1 failure).
+
+### Phase 2 — Content fix
+
+- [x] Edit `hub-client/changelog.md` line 20: replace the lone `~` in
+      `(now ~37MB)`. Preferred: reword to avoid the delimiter entirely,
+      e.g. `(now about 37 MB)`. (Rewording is lower-risk than relying on
+      `\~` escaping and reads better in the rendered About tab.)
+- [x] Re-run `cd hub-client && npm run test:wasm` → expect
+      `changelog.md renders successfully` to PASS, `129 passed`.
+
+### Phase 3 — Full local verification BEFORE pushing (the step that was skipped)
+
+- [x] `cargo xtask verify` — full leg (Rust build + tests, ts-packages,
+      hub-client `build:all`, `test:ci`). Do **not** use `--skip-hub-*`
+      here; the hub legs are exactly where both failures lived.
+- [ ] Only after green: single commit, then ask for push permission.
+      **Push once, not per-fix.**
+
+### Phase 4 — Guardrail against recurrence (process, not just content)
+
+Options to reduce the chance a lone-delimiter or size-ceiling regression
+reaches `main` again. To be discussed with the user before implementing —
+this phase is a menu, not a commitment:
+
+- [ ] **(cheap, recommended)** Add a `lint`-style check or a note in
+      `hub-client/changelog.md`'s HTML comment header reminding authors
+      that changelog prose is rendered through qmd, so `~`, `_`, `^`, `$`
+      etc. must be escaped or avoided. The `changelogRender.wasm.test.ts`
+      test already enforces this — the gap is *authors not running it*, not
+      missing coverage.
+- [ ] **(process)** Treat "changelog touched" as implying "run
+      `npm run test:wasm`" — because the changelog is a rendered artifact,
+      editing it is a code change, not a docs change.
+- [ ] **(optional, heavier)** Consider whether `cargo xtask verify` should
+      be the default pre-push gate for any `hub-client/**` change, and
+      whether a git pre-push hook or CI-required-status-check on `main`
+      should enforce it. Flag: hooks that run `cargo xtask verify` are slow
+      (full WASM build); may not be worth the friction. **Decision deferred
+      to the user.**
+
+## Non-goals / notes
+
+- The 64 MB PWA ceiling (Failure 1 fix) is **not** being reverted — it is
+  correct and CI-confirmed. This plan only repairs Failure 2 on top of it.
+- Do **not** "fix" the subscript by loosening the qmd parser or the
+  `changelogRender` test. The parser behavior is correct; the changelog
+  content is what's wrong.
+- Escaping via `\~` would also work, but rewording is clearer for readers
+  of the About tab and avoids a backslash showing up if escaping semantics
+  ever differ between the WASM path and the rendered path.
+
+## Appendix — evidence
+
+- Failing run: `gh run view 28877875823` (TS Test Suite, push of `6cd4dd5a`).
+  - `Build WASM module`: ✓ (Failure 1 fix confirmed).
+  - `Run hub-client tests`: ✗ — `changelogRender.wasm.test.ts`.
+- Only `~` in `hub-client/changelog.md` is line 20 (my entry).
+- CI test command: `.github/workflows/ts-test-suite.yml:147` → `npm run test:ci`.
+- `test:ci` definition: `hub-client/package.json:29`.
+- Q-2-17 definition + conversion: `crates/qmd-syntax-helper/src/conversions/q_2_17.rs`.

hub-client/changelog.md

@@ -17,7 +17,7 @@ be in reverse chronological order (latest first).
 
 ### 2026-07-07
 
-- [`6cfc098f`](https://github.com/quarto-dev/q2/commits/6cfc098f): Raised the service-worker precache size limit so the (now ~37MB) WASM module is cached again for offline use, and to stop continued WASM growth from breaking the production build.
+- [`6cfc098f`](https://github.com/quarto-dev/q2/commits/6cfc098f): Raised the service-worker precache size limit so the (now about 37 MB) WASM module is cached again for offline use, and to stop continued WASM growth from breaking the production build.
 
 ### 2026-07-06