ADR-0002: strict TypeScript migration — gate + phases 1–5 (generated schema types, state, contract spine, param pipeline, dashboard runtime, tests)

[BorisTyshkevich]

Implements all of ADR-0002 (docs/ADR-0002-static-typing.md) in one PR — phase 0 (the gate) plus the five follow-up phases from the migration proposal pack, per maintainer decision to avoid per-phase issue/PR churn. Closes #262.

Phase 0 — TypeScript gate (original scope)

• tsconfig.json (strict, allowJs, checkJs: false, noEmit, erasableSyntaxOnly, bundler resolution); typescript devDependency; check:types wired into pretest → npm test → CI.
• Type-only seam interfaces: EditorPort, SpecEditorPort, CodeViewer, CreateAppEnv/BootstrapEnv, and the App controller surface.

Phase 1 — generated persisted-data types

• build/emit-schema-types.mjs: a hand-rolled deterministic emitter (json-schema-to-typescript was evaluated and rejected — Ajv-$id-registry ref resolution, 2020-12 unevaluatedProperties/not gaps, unstable title-derived names; recorded as an ADR-0002 addendum). Emits src/generated/json-schema.types.ts (QuerySpecV1, SavedQueryV2, LibraryV2, and a usable PanelCfg discriminated union with a FuturePanelCfg { type: string & {} } forward-compat member). Joins generatedSources() (4→5 artifacts) so generate:schemas/check:schemas staleness covers it; unhandled shape keywords throw. src/schema-contract.types.ts pins semantic invariants (spec open / library+saved-query closed / Extract<> narrowing) at check:types time.

Phases 2–5 — 19 modules converted to strict TS (zero behavior change)

• State model: src/state.ts — signals typed by value, persisted SavedQueryV2 vs runtime QueryTab separated, localStorage ingress narrowed honestly (decodeStoredSavedQueries discriminated result; visible commented assertions on the six undecoded prefs). app.types.ts placeholders became re-exports of the real types.
• Contract spine: saved-query, panel-cfg, result-choice, panel-execution, core/dashboard — panel-type ids derive from the generated union; validation boundaries keep cfg: unknown.
• Param/execution pipeline: param-type, param-validate, optional-blocks, query-params, param-pipeline, dashboard-filters, filter-execution — exported contracts for analysis/prepared-batch/field-control/validation-mode shapes.
• Dashboard runtime: ui/dashboard, ui/dashboard-kpi-band, ui/panels — discriminated DashSlot = TileSlot | KpiSourceSlot lifecycle (generations, owned AbortControllers, PanelRenderResult.destroy), generic FavoriteSourceHooks<S> so tile/KPI handler mixups don't compile, progress callbacks typed label-only.
• Still-.js imports are typed via local non-exported wrapper consts (no sibling .d.ts shims) that self-delete as those modules convert later. Coverage parity was verified branch-by-branch on the risky files; no test assertions changed.

Test second wave + tooling

• 18 tests/unit/*.test.js specs → .ts (it() counts unchanged); tsconfig/vitest include widened.
• tests/vitest.config.ts gains a mixed-tree resolveId shim (Vite only retries .js→.ts from TS importers — tsc/esbuild/Node all resolve it natively).
• build/e2e-serve.mjs replaces python3 -m http.server for the Playwright harness: the fixtures import raw /src/**/*.js as native ESM, so renamed modules 404'd — the new server falls back to the .ts sibling and type-strips via esbuild. Full e2e suite: 80/80 on chromium+webkit (~12s).

Verification

• npm test: 101 files / 2850 tests, per-file coverage thresholds green, check:schemas + check:types in pretest.
• npm run build: dist/sql.html unchanged in kind — four runtime deps, zero third-party requests, no new runtime dependency.
• High-effort multi-agent code review (8 angles) ran over the full diff; all confirmed findings fixed in 7eb9eeb (e2e harness break, ADR self-contradiction, emitter required gap, one new uncovered branch). Semantic .js-vs-.ts deep-dives on state/dashboard/panels found zero behavior deltas.

Known follow-ups (deliberately not in this PR)

• Duplicated typed wrappers mostly resolved in-PR: dom.js, param-scan.js, and diagnostics.js converted and their 8 wrapper copies deleted (the schemaKey/CHART_TYPES casts remain until chart-data.js converts). The triplicated test App stub (fix tests/helpers/fake-app.js) and the remaining conversion inventory are tracked in Finish the ADR-0002 TypeScript migration: remaining .js modules, fake-app App stub, mixed-tree scaffolding retirement #267.
• ResultLike.rows doesn't type the keyed-object row variant readKpiFields also accepts (type-vs-runtime gap, noted in kpi-band test comments).
• Share-link bootstrap writes unvalidated spec.view into resultView #266 (inbox): share-link bootstrap writes unvalidated spec.view into the now-union-typed resultView signal (found during state typing).

🤖 Generated with Claude Code

https://claude.ai/code/session_01XP1KN94N969SVMNFPdVtGg