dhpk-js-static-check-strategy

JS static-check strategy — progressive rollout playbook

Always-loaded SSOT rule: modules/js/references/static-checks.md.

This skill carries the long-form execution detail so the always-loaded rule stays short. Load this when you are actually doing the rollout work.

Legacy-globals — three-list sync

When a leaf introduces a new global, all three lists must update together (no automatic derivation — three independent maintained files):

1. eslint.config.js <projectName>LegacyGlobals constant — readonly / writable annotation. SSOT for no-undef.
2. <frontend-root>/<project>-ambient.d.ts — declare var X: any; block. SSOT for tsc --noEmit bare-identifier resolution.
3. <frontend-root>/jsdoc-globals.js — @typedef (only when the default any from the ambient .d.ts is too loose and a real shape adds value).

A leaf PR that misses any of the three surfaces later as no-undef or TS2304. CI catches drift after the fact; reviewers should still verify three-way sync proactively.

// @ts-check progressive strategy

• One leaf per PR: add // @ts-check + clean up the JSDoc + run the unit / contract tests to confirm no regression.
• Track the rollout against your mechanical-extraction cadence (Stage A, B, C…). Each stage produces a batch of leaves ready for type-check enablement.
• A stuck leaf can land // @ts-nocheck with a TODO comment as a transitional state — but every transitional file should have a tracked exit PR.

Measure progress with the line-anchored grep (anything looser is gameable — see the trap below):

# Step 1 — strict opt-in (exit gate: this list must end up empty)
find <frontend-root> -maxdepth 1 -name '*.js' -exec \
    grep -lE '^[[:space:]]*//[[:space:]]*@ts-check[[:space:]]*$' {} \;

# Step 2 — files still on `// @ts-nocheck` (governance indicator;
# should trend toward zero, but some files may be permanent exclusions —
# see classification below).
find <frontend-root> -maxdepth 1 -name '*.js' -exec \
    grep -lE '^[[:space:]]*//[[:space:]]*@ts-nocheck' {} \;