emrg: the doc-count span finder reads a /* inside a string as a comment opener #1947

Origin: rant 2026-10-09T01:29:30.096670+08:00

What is wrong

tests/test_doc_counts.py's block-comment tripwire — the one that asks "does any
it(/test( definition sit inside a block comment, where the doc-count guard
counts it but the runner never executes it?" — finds its spans with

_BLOCK_COMMENT = re.compile(r"/\*.*?\*/", re.S)

That regex cannot tell a comment opener from the same two characters inside a
string literal. A file holding const GLOBS = ["renderer/**"]; before any real
block comment gets a span opened inside the string, running to the next */,
so every live definition between the two is reported as commented out.

Reproduction (measured 2026-10-09 on 4f14cc55)

Append an ordinary block to a file this tripwire actually guards,
emrg/gui/test/build-config.test.js — a glob string, a doc block, one live case:

const GLOBS = ["renderer/**", "vendor/**"];

/**
 * whitelist helper
 */
it("added live case", () => {});

The old finder reports ['/**")) {']; there is no commented-out definition in
that file. "dir/**" is the ordinary spelling in this repo's build and nav
tests, so the trigger is a normal addition, not an exotic one.

Why it matters

The remedy the tripwire prints is "Delete the dead definition or restore it."
Its author has no dead definition to delete — the guard hands a person a repair
they cannot perform, which is how a guard gets trained away. (Same class as the
two prior escapes this file documents: a tripwire that fires on nothing real, or
fails to fire on something real, ends up ignored.)

Scope of the defect today

On all 56 files the finder is actually run over
(emrg/gui/renderer/src/**/*.test.ts(x) and emrg/gui/test/**/*.test.js) the
regex and a correct scanner agree — the trap is latent today, not firing.
It is a trap that springs on the next ordinary addition. Elsewhere it is already
wrong: over tests/test_doc_counts.py itself (which spells the pattern out in
prose) the regex reads 20 spans where 2 exist; tests/test_glob_tool.py, 4 where
0 exist.

Acceptance

1. A /* inside a string literal opens no span (asserted on the span text, not
   only on the verdict — a span in the wrong place is exactly what the old
   finder produced).
2. A genuinely commented-out definition is still reported, including when a
   string carrying /* sits above it (the fix must not trade a false red for a
   false green).
3. An apostrophe in a line comment (// don't) is not read as an unterminated
   string that swallows the block below it.