juspay / juspay/rescript-bindgen

Track ReScript compiler version compatibility — keep emitted syntax + compile-check pin moving with ReScript releases

Open
#160 0 comments 0 reactions 0 assignees View on GitHub
enhancement
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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.