Replace AI (NeuroLink) binding generation with deterministic @juspay/rescript-bindgen + 1:1 versioning

[jagguji]

Proposal

Replace blend-rescript's AI-based binding generation (scripts/generate-bindings.mjs → NeuroLink + LiteLLM, model kimi-latest) with the deterministic @juspay/rescript-bindgen, and switch to 1:1 versioning with @juspay/blend-design-system.

Why switch the generator

The current flow uses an LLM to write the .res files. rescript-bindgen is purpose-built to replace exactly this, and is strictly better for a published, consumed binding package:

	AI (current: NeuroLink/LiteLLM)	rescript-bindgen (proposed)
Determinism	non-deterministic — same blend version can produce different bindings per run	same input → byte-identical output, every run
Secrets/infra	needs LITELLM_BASE_URL / LITELLM_API_KEY / TEST_KEY + a model endpoint	none — pure TS-compiler-driven, runs anywhere
Correctness guarantee	can hallucinate a plausible-but-wrong type	contract: "flag, don't fake" — unmodellable types are flagged (⚠️ REVIEW), never faked; no Obj.magic/%identity
Speed/cost	per-component LLM calls	seconds, free
Review	opaque	the regen diff is exact and reviewable

Already proven: rescript-bindgen generates blend today at 154 files, 94/94 usable, 0 review, 0 broken, compiles on ReScript 12 (it's a pinned package in rescript-bindgen's benchmark suite).

The swap (keeps the parts that already work)

The existing sync-bindings.yml flow is good — keep its shape (manual workflow_dispatch, prerelease guard, build-to-confirm, create-pull-request). Only change how bindings are produced:

• npm run generate -- --all (NeuroLink) → npx @juspay/rescript-bindgen --pkg @juspay/blend-design-system@<v> --from @juspay/blend-design-system --out src --report
• Drop the LLM env block (LITELLM_*, TEST_KEY) from the workflow.
• Remove deps no longer needed: @juspay/neurolink, dotenv (and the litellm/model config); retire scripts/generate-bindings.mjs + bindings-instructions.md (keep known-errors.md if still useful as review notes).
• Add @juspay/rescript-bindgen as a devDependency (pinned).
• Flagged props (the ⚠️ REVIEW subset) → handle via the diff-review or layered-overrides pattern (see versioning note below); a src/*.failed.res check is no longer needed (rescript-bindgen flags inline + in _REPORT.md).

1:1 versioning with blend-design-system

@juspay/rescript-blend's version mirrors the blend version it was generated from — rescript-blend@0.0.37 = bindings for blend-design-system@0.0.37. The sync workflow already resolves the installed blend version (steps.blend.outputs.version); set package.json version to it and publish that.

• This replaces semantic-release's independent versioning (currently 1.0.2; also see the failing-release The automated release is failing 🚨 #63) — the release flow sets version = blend version instead of computing one from commits.
• Edge case — binding-only re-release (a manual tweak to a flagged prop, or a rescript-bindgen upgrade regenerating better output for an unchanged blend version): strict 1:1 can't express two releases for one blend version. Proposed: a -N suffix (0.0.37 → 0.0.37-1). Decide here.

Deliverables

• sync-bindings.yml: generate step → rescript-bindgen; drop LLM env + secrets.
• Remove NeuroLink/dotenv deps + AI scripts; add @juspay/rescript-bindgen devDep.
• First regen PR against current blend, diff reviewed (expect ~94/94 usable; eyeball the flagged props).
• Switch release to 1:1 versioning (= blend version); resolve the binding-only-re-release scheme.
• README: document the new deterministic flow.

Out of scope (separate issues, already tracked)

#46 (downstream preview for unreleased blend), #48 (pkg.pr.new mirror) — orthogonal; this is about the generator + versioning.

[jagguji]

✅ Implemented in #74

The migration is built and verified locally on branch feat/bindgen-deterministic-sync. Summary of what landed and how it maps to the plan above.

What changed

• Generator → deterministic. New scripts/generate.mjs runs the @juspay/rescript-bindgen CLI directly on blend's shipped .d.ts — no LLM, no secrets, no network model calls. Deleted scripts/generate-bindings.mjs, bindings-instructions.md, known-errors.md.
• Deps. Removed @juspay/neurolink, dotenv, undici, semantic-release + all @semantic-release/* and the embedded release block. Added @juspay/rescript-bindgen (devDep). Moved @juspay/blend-design-system to a peer dependency (>=0.0.36) + dev pin (0.0.36).
• src/ regenerated wholesale against blend 0.0.36: 153 .res files, 94/94 usable, 0 broken (1 loose: DataTable's 3 multi-shape props, widened to string with inline ⚠️ REVIEW — never faked). src/_REPORT.md committed as a review artifact.

The exact command that runs (behind npm run generate)

npm run generate → node scripts/generate.mjs → executes:

node_modules/.bin/rescript-bindgen \
  --pkg @juspay/blend-design-system@<version> \
  --out src \
  --project . \
  --webapi \
  --report \
  --json-summary src/_bindgen-summary.json \
  --clean \
  --yes
# then: npx rescript format

The wrapper resolves <version>, prefers the locally-installed (pinned) bin, formats output, and fails the run if any component is broken (deterministic replacement for the old .failed.res check). Flags: --blend <v>, --set-version (1:1), --only <Comp>.

Versioning & sync

• 1:1 versioning: @juspay/rescript-blend@X = bindings for @juspay/blend-design-system@X. version set to 0.0.36. semantic-release removed; release.yml publishes the package.json version with a skip-if-already-published gate.
• Binding-only re-release scheme resolved: -N suffix (0.0.36 → 0.0.36-1).
• Sync: sync-bindings.yml now polls npm daily for a newer stable blend (plus manual workflow_dispatch), regenerates deterministically, sets the 1:1 version, and opens a sync/blend-<version> PR. No LLM secrets. Prerelease guard kept. (Self-driven — no dependency on the blend team / webhooks.)
• Deleted release-mirror.yml; dropped the dead .failed.res gates in ci.yml/release.yml.

Verified locally

• npm run build ✅ (280 modules) · npm run format:check ✅
• Determinism ✅ — two generate runs produce byte-identical src/
• All 3 workflows parse as valid YAML · npm pack clean (158 files, .res + config only)

Deliverables

• sync-bindings.yml: generate step → rescript-bindgen; drop LLM env + secrets
• Remove NeuroLink/dotenv deps + AI scripts; add @juspay/rescript-bindgen devDep
• First regen PR against blend 0.0.36, diff reviewed (94/94 usable; flagged props eyeballed)
• Switch release to 1:1 versioning (= blend version); binding-only re-release = -N suffix
• README + docs document the new deterministic flow

⚠️ Notes for reviewers

1. Version 1.0.2 → 0.0.36 is a backwards jump. On publish, npm moves the latest dist-tag down to 0.0.36; existing consumers on ^1.0.0 stay on 1.0.2 and won't auto-upgrade. Consider npm deprecate-ing the 1.x line after the first publish.
2. Breaking binding surface (record-props + shared *Types/CommonTypes/HtmlAttrs modules) → a separate juspay-portal branch must update call sites; coordinate after merge.

Review in #74.