From 14d5f54a2a585d590b7575ebb4eadd3c14054cb0 Mon Sep 17 00:00:00 2001 From: pseudo Date: Sun, 23 Aug 2026 22:20:54 -0600 Subject: [PATCH] Record the template-literal backtick trap (#21) Third occurrence in this repo -- phase-stop-guard.ts once, schema.ts twice -- each time while adding an explanatory comment inside a big template literal. db/schema.ts holds the entire SQL schema in one, and SQL comments are the natural place to write prose about columns, so a backticked identifier terminates the string mid-schema and reports TS1005 on a line 200 further down. Cold tier: it is a recognition cue for one file shape, not something that should change a decision up front, and the hot cap is load-bearing. Co-Authored-By: Claude Opus 5 (1M context) --- codev/resources/lessons-learned.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/codev/resources/lessons-learned.md b/codev/resources/lessons-learned.md index f9ff943ad..9d72f9d74 100644 --- a/codev/resources/lessons-learned.md +++ b/codev/resources/lessons-learned.md @@ -697,6 +697,8 @@ so it survives review. Pin the constant to the highest migration block in a test - [From #1347] Verify image transforms numerically, never visually: white-on-transparent output renders invisibly on light preview grounds, and ImageMagick 7's `-channel RGB -fill white -colorize 100` silently produced red glyphs with corrupted alpha while *looking* plausible in a montage. Recolor glyphs by alpha-composition (PIL: white layer + `putalpha`) and assert channel means (`magick -format "%[fx:mean.r]"`) before committing assets. - [From #1150] When users report a **newly recurring** symptom, correlate the report window against what shipped just before it, before accepting a low-probability failure theory. The issue's root-cause analysis blamed a swallowed SQLite error and WAL loss (both real defects, both rare); a reviewer's "is a failed SQLite update actually probable?" challenge prompted enumerating every writer of the table, which surfaced the #1118 consolidation (shipped one week before the reports) deterministically re-inserting stale snapshot rows. The rare-event defects were still worth fixing, but ranking them as *the* cause would have shipped a fix while misdescribing the bug. Enumerate all writers of the corrupted state, not just the suspicious-looking one. - [From #1055] A VS Code command whose button is **visible but does nothing** after an extension change is often a **stale Extension Development Host**, not a code regression — package.json contribution + compiled-JS changes don't fully take effect until a `Developer: Reload Window`. Before hunting a dispatch bug, confirm the symptom survives a clean reload. Here an "editor delete no longer works" report against a byte-for-byte-unchanged delete command evaporated on reload; a speculative menu-placement fix was started, then reverted once it proved environmental. Diff-the-actual-code first, and let the tester rule out a stale host before you change working behavior. +- [From #21] **A backtick inside a comment in a TypeScript template literal ends the literal, and the parse error points somewhere else entirely.** `db/schema.ts` holds the whole SQL schema in one template literal, and SQL comments are the natural place to write prose about columns — so writing ``-- `reason` collapses every verdict to 'busy'`` terminated the string mid-schema and reported `TS1005: ',' expected` on a line 200 further down. Three times now in this repo (`phase-stop-guard.ts` once, `schema.ts` twice), each time while adding a well-intentioned explanatory comment. In a file whose body is one big template literal, quote identifiers with plain words or single quotes; the giveaway is a syntax error at a line you did not touch. + - [From 0107] Commander.js `.alias()` does NOT hide aliases from `--help` output -- they show as `command|alias`. Use `towerCmd.addCommand(cmd, { hidden: true })` to add hidden backward-compatible commands. - [From 0107] `body && body.name` treats `{ name: "" }` as falsy, falling through to reconnect instead of validation. Use `body && 'name' in body` for field presence checks where empty string is a meaningful (invalid) value. - [From 0107] Nonce must be embedded in the callback URL, not the initial auth URL, so that the OAuth callback can validate state.