Adopt TypeScript?

[wittjeff]

I have gotten the TypeScript religion and I wonder what you think of it. I seem to recall you had an issue to explore it a couple of years ago but I can't find it anywhere. Anyway if you're into it, I'd propose a staged migration with a bunch of independent PRs, and probably a bunch of new CI tests. Thoughts?

[wittjeff]

Following up with the concrete proposal. I had the codebase surveyed for TypeScript-readiness (testaro and testilo both), and the shape of the work is clearer than I expected — the hard parts are few and well-localized.

Where we are

Both repos are 100% untyped JavaScript: no TS, no JSDoc types, no tsconfig, no @types. Testaro is ~12.7k first-party LOC across 95 files (excluding vendored htmlcs/ and ed11y/, which I'd leave untyped forever). The favorable news: the 52 rule modules average 85 lines and follow about three shapes, so most of the migration is mechanical repetition. The genuinely hard parts are exactly four:

1. The getBadWhat pipeline — 34 rule modules ship a predicate to the page as source text (.toString() → eval in procs/testaro.js). Its return contract (falsy | string | {description, data}) exists only as tribal knowledge.
2. No declared shapes — the report object is threaded through 74 files and mutated at every layer; standardResult is re-declared ad hoc in all 11 tool adapters; actSpecs.js is a hand-rolled runtime type system.
3. Two dynamic requires — tool adapters by ID (doTestAct.js) and rule modules by ID (tests/testaro.js).
4. 33 page.evaluate callbacks (Node/DOM boundary) plus 7 custom window.* globals injected in launch.js and consumed in other files' callbacks.

Proposed approach

Strict from day one, incrementally. strict: true applies to every converted file from the first PR; the file set grows, the strictness never ratchets (ratcheting means re-reviewing everything twice). No JSDoc/checkJs detour — it's the same annotation work paid twice.

Flat in-place layout, CommonJS forever. foo.ts lives beside its compiled foo.js at the same path — no src/→dist/ split. Reason: consumers (mine included) depend on published file paths (patch-package patches, deep requires), and a layout change is an ecosystem break for zero typing benefit. Compiled output is committed, with a CI drift check (tsc && git diff --exit-code) and prepublishOnly: tsc. Staying CJS (module: commonjs) is an explicit non-goal boundary — ESM migration is out of scope, so we never relitigate it per-PR.

getBadWhat: type both ends, keep the wire format. The string-shipping channel stays exactly as is (it's load-bearing — autocomplete.js even mutates the serialized source). We declare type GetBadWhat = (element: Element) => false | null | undefined | string | {description: string, data?: unknown}, annotate all 34 definition sites, and put exactly one documented cast at the eval. The runtime doesn't change; the contract becomes checked.

Registries for the dynamic requires. A hand-written lazy-thunk registry for the 11 tool adapters (IDs already enumerated in procs/job.js) and a codegen'd, committed one for the 52 rule modules — which makes RuleID a real union type and turns adapter signature drift into compile errors. Thunks stay lazy so startup/memory behavior is unchanged.

actSpecs.js stays. It remains the runtime validator; the Act discriminated union is hand-written in a new types.ts and actSpecs gets a satisfies check. No zod rewrite, no clever type-level derivation of the tuple DSL.

Types live in testaro. One types.ts exporting Report, Act, StandardResult, StandardInstance, CatalogEntry, ToolID, RuleID, GetBadWhat, plus a declare global block for the injected window.* functions. Testilo vendors a copy short-term; if the shared shape proves stable across both migrations, it can graduate to a tiny zero-runtime testaro-report-types package that testaro, testilo, and downstream consumers all use.

Phasing (testaro)

Phase	Content	Size
0	CI (first ever for this repo: typecheck + validation), dep pinning (everything is "*" today), engines, tsconfig, hand-written types.d.ts, fix the dangling "main": "index.js"	1 PR, no runtime change
1	types.ts + core procs (procs/testaro.js incl. the one eval cast, xPath.js, catalog.js)	2–3 PRs
2	52 rule modules, batched by shape (~10/PR); rule registry codegen	5–6 PRs
3	11 tool adapters; unified StandardResult replaces the 11 ad-hoc declarations; adapter registry	3–4 PRs
4	Engine procs (doActs.js, launch.js, job.js+actSpecs, doTestAct.js) + entry points	4–5 PRs
5	Strict closure: stub deletion, any audit (goal: the one eval cast only), required CI gate	1–2 PRs

Roughly 20–30 working days of effort spread over a couple of months at a reviewable cadence; no PR over ~700 changed lines, and each phase has a go/no-go point. Phase 0 is worth merging even if you decide to stop there — CI, pinned deps, and a consumable types.d.ts stand on their own.

Testilo would trail one phase behind (its types vendor from testaro's), with its own short RFC once this one settles. Preview of its specifics: tic.js becomes a satisfies-checked const (a typo net over ~364 issues × ~1000 tool-rule entries), the frozen historical tic45/49/50/tsp4x scorers stay JS forever, tic-old.js (342 KB, superseded) gets deleted, and the FUNCTIONDIR dispatch stays dynamic by design — typed as unknown with a runtime shape check, since user-supplied score procs are an open universe.

What I'd like your sign-off on

1. Strict TS as the endgame (not JSDoc annotations).
2. In-place layout with committed compiled output, staying CommonJS.
3. The getBadWhat treatment (type both ends, keep string-shipping).
4. Registry codegen for rule/tool loading.
5. The PR cadence above — batched, shape-per-PR, sized for solo review.

If any of these give you pause, they're independently negotiable — the phasing survives swapping any one decision. Happy to start with the Phase 0 PR so there's something concrete to look at.