juspay / juspay/rescript-bindgen
Track ReScript compiler version compatibility — keep emitted syntax + compile-check pin moving with ReScript releases
- Dominant language
- ReScript
- Stars
- 8
- Forks
- 0
- Avg merge
- 9h 33m
- Merged PRs (30d)
- 15
Description
## Problem
The generator emits ReScript that's valid for a **specific compiler version** — **ReScript 12** today. As ReScript releases 13, 14, … two things can drift and we have no explicit process to catch it:
1. **Emitted syntax may need to change.** We rely on version-sensitive features: untagged/tagged variants (`@unboxed`, `@tag(…)` + `@as(…)`, ~24 + ~2 uses in `emit.mjs`), `React.component` (relies on JSX v4 lowering, ~6 uses), `React.componentWithProps` (the #155 wrapper pattern), `@as` field/variant naming (~13), `JsxDOM.*`, first-class `bigint`. A future ReScript could deprecate/rename any of these, and generated bindings would stop compiling for consumers on the new version.
2. **Our compile gate is pinned and could silently lag.** The golden compile check (`test/sandbox`) pins `rescript ^12.0.0` + `@rescript/react ^0.13.0`, and CI names the job "Golden compile (ReScript 12)". Nothing verifies the output still compiles on a *newer* ReScript, so a break would only surface downstream (as it did for the blend beta line — caught only by consumer validation).
There's already mild drift in the wild: `blend-rescript` builds against `rescript ^12.2.0` / `@rescript/react ^0.15.0`, while our sandbox pins `^12.0.0` / `^0.13.0`.
## What we should track / decide
- **A stated "targets ReScript N" contract** (README already says "ReScript 12" in ~5 places — make it the single source of truth, e.g. a `RESCRIPT_TARGET` constant or a README badge).
- **An "on new ReScript release" checklist**, e.g.:
- [ ] bump `test/sandbox` (`rescript`, `@rescript/react`) to the new version, re-run `npm run test:compile` — all goldens must still compile.
- [ ] update the CI job name + any README "ReScript 12" references.
- [ ] note any emitted-syntax change in `docs/TYPE_MAPPING.md` (like the `@tag`/`@unboxed`/`bigint` rows already do).
- [ ] regenerate `blend-rescript` against it as the downstream smoke.
- **Consider a compile MATRIX** — run the golden-compile job against *both* the current target and the next ReScript (e.g. 12 + 13-rc) so a break is caught in our CI, not a consumer's.
- **A compatibility note** — which `@juspay/rescript-bindgen` version emits for which ReScript range (a small table in README/CHANGELOG), so consumers know what to pair.
## Concrete anchors
- `test/sandbox/package.json` — the compile-check ReScript pin (`^12.0.0`, `@rescript/react ^0.13.0`).
- `.github/workflows/ci.yml` — the "Golden compile (ReScript 12)" job.
- `src/emit.mjs` — the version-sensitive syntax the emitter produces.
- `README.md` (lines ~8/40/115/185/193) + `docs/TYPE_MAPPING.md` — where "ReScript 12" is stated.
## Why now
Filed as a tracking issue off the v1.3.0 release — no change needed today (ReScript 12 is current and stable), but we want a deliberate process so a future ReScript bump is a checklist we run, not a surprise a consumer reports.
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with test/sandbox/package.json and .github/workflows/ci.yml to understand the ReScript 12 compile pin and golden-compile job, then inspect src/emit.mjs and the referenced README.md and docs/TYPE_MAPPING.md sections. Done means the repository has an agreed target-version contract and release checklist, with documentation and CI changes covering the selected compatibility strategy.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- github-actions
- Domain
- build-system, ci-cd, documentation, testing
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100