TypeScript guidelines: Add Migrating JavaScript to TypeScript section on runtime neutrality

[MajorLift]

Adds a Migrating JavaScript to TypeScript section with one guideline — a typing change should not change runtime behavior — plus a subsection on weighing a conversion's risk by observability.

Kept separate from #178 on purpose: that PR is about deriving types from authoritative sources, and this is a different rule. Bundling them would mean a reviewer of either has to litigate both.

Why it needs saying

A conversion PR is a type-level edit. The reason to state that explicitly is asymmetric scrutiny: a PR described as mechanical, rename-only, or no behavior change gets a lighter review than a behavior change would — so a runtime edit smuggled in as typing work receives the least attention of anything in the diff.

What it covers

• Four patterns that read as typing work but are not:
  • a literal replaced by a runtime lookup (check the declaration first — many platform-API parameters are template-literal string types that accept the literal already);
  • a default parameter or fallback deleted, usually the | undefined a restated type just dropped;
  • a call made optional (obj.m() → obj.m?.()), which converts a throw into a silent no-op;
  • a local widened to keep an existing check compiling, when the input type is the thing that's wrong.
• A reachability requirement. Each hit gets a verdict either way — "traced, and inert on today's call paths" is a useful review outcome; "this might be a bug" is not.
• Risk weighted by observability. A change inside catch { captureException(e); return; } degrades a feature with nothing going red, so an unlikely failure there can outrank a likely one in a loud path.

The example

A real conversion that replaced ['OFFSCREEN_DOCUMENT'] and ['IFRAME_SCRIPTING'] with runtime enum lookups and added a cast — against declarations that are template-literal string types and a function that already returns the cast-to type. The types had asked for none of it, and the change traded two constants for an assumption about the host environment inside a swallowed captureException path.

Worth noting for reviewers: the 🚫 version is not broken — the enum objects do exist at runtime. The point is the trade, not a defect, and the example says so rather than overclaiming.

Related

• TypeScript guidelines: Add Derive types from authoritative sources guideline #178 — Derive types from authoritative sources, the other half of reviewing a migration PR. The deleted-default-parameter bullet links into it.
• MetaMask/skills — typescript-type-proof — the review-side procedure that makes these checkable.

---

Note

Low Risk
Documentation-only change to TypeScript guidelines; no application code, build, or runtime behavior is modified.

Overview
Adds a Migrating JavaScript to TypeScript section to docs/typescript.md, after the selector guidance.

The core rule is that a typing change must not change runtime behavior, with emphasis on why conversion PRs get lighter review and runtime edits can slip through as “mechanical” typing work.

It lists anti-patterns that look like typing fixes (literal → runtime enum lookup, removed defaults/fallbacks, optional chaining that silences throws, widening locals to preserve dead checks, swapping thrown errors and breaking error-tracker grouping) and requires reviewers to trace reachability with a clear verdict.

A subsection Weigh a conversion's risk by observability argues swallowed catch + captureException paths can be worse than loud hot paths, illustrated with a Chrome offscreen API example contrasting unnecessary enum lookups/casts vs keeping string literals.

^{Reviewed by Cursor Bugbot for commit 99e7a68. Bugbot is set up for automated code reviews on this repo. Configure here.}