juspay / juspay/rescript-bindgen
TS 7 migration: port extract.mjs from the classic ts.* API to typescript/unstable/sync
- Dominant language
- ReScript
- Stars
- 8
- Forks
- 0
- Avg merge
- 9h 33m
- Merged PRs (30d)
- 15
Description
Split from #137 (the impossible 7.0.2 drop-in bump) and related to #160 (compiler-version tracking).
## Why this exists
The generator reads TypeScript via the **classic JS compiler API** (`ts.createProgram`, `program.getTypeChecker()`, `checker.getTypeOfSymbolAtLocation`, `TypeFlags`, `SymbolFlags`, `forEachChild`, `type.isUnion()`, `checker.isArrayType()`, …) throughout `src/extract.mjs` (~4,700 lines). **TS 7 (native Go rewrite) removed that API** — `typescript@7.0.2`'s top-level export is just `version.cjs`. So 6.x (this repo pins `^6.0.3`, #161) is the end of the classic-API line; moving to TS 7+ means porting to the new API.
## The good news — the new API exists and maps closely
TS 7 exposes a **synchronous** programmatic API at `typescript/unstable/sync` (+ `typescript/unstable/ast`). Verified surface:
- **`Program`** — `getSourceFile`, `getSourceFileNames`, diagnostics.
- **`Checker`** — `getSymbolAtLocation`, `getTypeOfSymbol`, `getDeclaredTypeOfSymbol`, `getTypeAtLocation`, `getSignaturesOfType`, `getTypeFromTypeNode`, `getNonNullableType`, `getBaseTypeOfLiteralType`, `getContextualType`, `getWidenedType`, `isArrayLikeType`, `isTypeAssignableTo`, `resolveName`, `getResolvedSymbol`, …
- **Standalone type predicates** — `isUnionType`, `isObjectType`, `isTupleType`, `isTypeReference`, `isClassOrInterfaceType`, `isStringLiteralType`, `isIntersectionType`, `isConditionalType`, `isIndexedAccessType`, `isTypeParameter`, … (replace `t.isUnion()` / `checker.isArrayType()`).
- **Flags** — `TypeFlags`, `SymbolFlags`, `ObjectFlags`, `ModifierFlags`, `SignatureKind`, `ModuleKind`.
- **`typescript/unstable/ast`** — `SyntaxKind`, `forEachChild*`, `createScanner`, `getJSDocTags`, `cast`, …
So most of `extract.mjs`'s calls have a near-1:1 target; the port is mechanical for the bulk, with a handful of shape changes (a `Checker` **class** vs `program.getTypeChecker()`; standalone predicates vs methods; `Program` construction via the `API`/`parseConfigFile`/`updateSnapshot` lifecycle).
## The catch — it's `unstable/*`
That prefix means the TS team may change the API shape across 7.x **without a semver-major**. Building the *released* tool on it invites churn. This repo's mitigation is strong, though: the **golden suite (105 byte-diffed cases) + benchmark (9 real packages)** catch *any* output drift immediately, so a breaking TS 7.x change surfaces as a red CI, not silent breakage.
## When to actually migrate (trigger)
Not now — 6.0.3 works and parses every package we bind. Migrate when **any** of:
- [ ] the API is promoted out of `typescript/unstable/*` (frozen), **or**
- [ ] a package we must bind ships `.d.ts` using TS-7-only syntax that 6.x can't parse, **or**
- [ ] the 6.x line stops getting maintenance/security fixes.
## Suggested first step — a POC/spike (before the full port)
Prove feasibility + size the effort on a *subset* before touching 4,700 lines:
1. New `makeProgram` on `unstable/sync` (`Program` + `Checker`).
2. Port the core `classify()` path for a handful of shapes (union / object / literal / array / signature).
3. Run ~5 golden cases through it; diff against committed output.
4. Report the API-mapping delta (what's 1:1, what needs rework, any missing capability) — that scopes the full migration.
## Anchors
- `src/extract.mjs` — all classic-API usage (the port target).
- `src/resolve.mjs` — `typesEntry` feeds file paths to the program (largely API-agnostic).
- `test/sandbox` + the golden/benchmark suites — the validation harness (already byte-diffs output, so it doubles as the migration's correctness gate).
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with src/extract.mjs and the unstable/sync Program and Checker APIs, using src/resolve.mjs to understand how input paths reach the program. Build the suggested classify() proof of concept for union, object, literal, array, and signature shapes, then run about five golden cases through the test/sandbox harness. Done means byte-diffed output matches the committed golden results and the API-mapping gaps are documented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- javascript, typescript
- Domain
- tooling
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100