feat: sync docs JS output from compiled examples (#1255)

* refactor: make test-examples importable

* fix: restore test examples output

* fix: make temp examples build writable

* fix: handle spaced temp paths in test examples

* feat: warn on stale JS output blocks

* fix: limit JS output sync to example blocks

Restrict CodeTab JS-output pairing to explicit res example fences so plain res snippets are not treated as runnable examples.

Add a focused regression test for the pairing scanner and keep the design and implementation notes with the branch.

* docs: add test examples update mode design

Describe the line-oriented --update workflow for JS Output blocks in CodeTab examples.

Document missing-fence insertion, single-label CodeTab upgrades, and README updates.

* feat: add test examples update mode

Implement --update in scripts/test-examples.mjs so JS Output fences can be refreshed, filled, or inserted for eligible CodeTab examples.

Add integration coverage for stale, empty, and missing JS fences plus single-label and multi-label CodeTab behavior, and document the new command in the README.

* fix: improve test examples compiler handling

Invoke the local ReScript CLI directly instead of shelling through npm for each docs example build.

Format compiler failures as cleaned ReScript errors with markdown file locations and add regression coverage for both behaviors.

* docs: update generated JS output examples

Commit the updated manual MDX files produced by the JS Output sync flow.

This commit includes only the tracked docs example updates and leaves unrelated code and untracked files out.

* docs: explain optimized JS output examples

Clarify where ReScript precomputes pure expressions in the function, let-binding, and primitive-types docs.

Also update the multi-argument function example to bind the computed result so the generated JS output matches the explanation.

* more updates to improve example docs

* fix: emit ESM JS output examples

Configure the temp docs example project to compile with the repo's esmodule package spec and update the sync tests accordingly.

Refresh the generated manual and React MDX JS Output blocks from CommonJS exports to ESM export syntax.

* fix: refresh docs example output workflow

Stop warning on stale JS output during read-only checks and keep --update as the rewrite path.

Refresh generated JS output across the docs and rename colliding example-local types so the example checker passes again.

* remove docs

* docs: add ReScript CodeTab expansion design

* add exports.root

* docs: refine ReScript CodeTab expansion design

* docs: revise ReScript fence checking design

* docs: add default res fence migration plan

* test: capture default res fence behavior

* test: strengthen default res fence tests

* test: tighten nocheck and ts output assertions

* test: align codetab fixtures with new res contract

* test: fix ts output skip assertion

* test: prove nocheck fences are excluded from parse output

* test: relax brittle res fence assertions

* test: prove plain res discovery without preludes

* feat: check plain res fences by default

* fix: handle checked res codetabs

* docs: migrate example fences to checked res

Replace res example fences with plain res across the manual and React docs.

Update the authoring guidance in README.md and AGENTS.md to describe the new default checked fence contract.

* docs: migrate runnable examples to checked res fences

Convert the remaining documentation examples from example-only fences to the new default checked res flow.

Add nocheck and sig markers where examples are intentionally non-runnable, then refresh JS output with the updated checker.

* remove commited plans

* test: cover JSX preserved output codetabs

* feat: add JSX preserved output codetabs

* fix: rename generated example module

Rename the temp example source from _tempFile to Example so derived JS output no longer leaks the temp filename.

Refresh the JSX preserved-output docs that are in scope for the new three-tab ReScript CodeTab flow.

* update gitignore

Author: jderochervlk

.gitignore

@@ -11,11 +11,9 @@ out/
 index_data/*.json
 
 # Generated via test examples script
-_tempFile.cmi
-_tempFile.cmj
-_tempFile.cmt
-_tempFile.res
 temp
+temp-js-output
+temp-jsx-preserve
 
 .bsb.lock
 .merlin

AGENTS.md

@@ -192,7 +192,7 @@ let default: unit => React.element
 - Documentation content is in `markdown-pages/` organized by section (blog, docs, community, syntax-lookup).
 - MDX is processed by `react-router-mdx` with remark/rehype plugins.
 - Custom MDX components are mapped in `app/routes/MdxRoute.res` (e.g. `<Info>`, `<Warn>`, `<CodeTab>`, `<Video>`).
-- Code examples in markdown use ` ```res example ` (runnable), ` ```res sig ` (signature), and ` ```res prelude ` (shared context).
+- Code examples in markdown use ` ```res ` (runnable), ` ```res sig ` (signature), and ` ```res prelude ` (shared context).
 
 ## Formatting & Git Hooks
 

README.md

@@ -72,14 +72,27 @@ Please be selective in pushing up changes to screenshots and only update files t
 
 We check the validity of our code examples marked with:
 
-- ` ```res example ` (ReScript code snippet)
+- ` ```res ` (ReScript code snippet)
 - ` ```res sig ` (signature)
 - ` ```res prelude ` (ReScript code snippet available for all subsequent code snippets)
 
 Run the checks with:
 
+```sh
+yarn test
+```
+
+Refresh stale or missing JS Output fences with:
+
+```sh
+yarn test --update
+```
+
+If you only want to run the example checker directly, you can still use:
+
 ```sh
 node scripts/test-examples.mjs
+node scripts/test-examples.mjs --update
 ```
 
 ### Markdown Hyperlink Tests

markdown-pages/docs/manual/array-and-list.mdx

@@ -14,12 +14,14 @@ Arrays are the main ordered data structure in ReScript. They can be randomly acc
 
 <CodeTab labels={["ReScript", "JS Output"]}>
 
-```res example
+```res
 let myArray = ["hello", "world", "how are you"]
 ```
 
 ```js
-var myArray = ["hello", "world", "how are you"];
+let myArray = ["hello", "world", "how are you"];
+
+export { myArray };
 ```
 
 </CodeTab>
@@ -34,7 +36,7 @@ Accessing items in an array will return an `option` and can be done like so:
 
 <CodeTab labels={["ReScript", "JS Output"]}>
 
-```res example
+```res
 let myArray = ["hello", "world", "how are you"]
 
 let firstItem = myArray[0] // Some("hello")
@@ -43,11 +45,13 @@ let tenthItem = myArray->Array.get(10) // None
 ```
 
 ```js
-var myArray = ["hello", "world", "how are you"];
+let myArray = ["hello", "world", "how are you"];
+
+let firstItem = myArray[0];
 
-var firstItem = myArray[0];
+let tenthItem = myArray[10];
 
-var tenthItem = myArray[10];
+export { myArray, firstItem, tenthItem };
 ```
 
 </CodeTab>
@@ -58,7 +62,7 @@ Items in an array can be updated by assigning a value to an index or using a fun
 
 <CodeTab labels={["ReScript", "JS Output"]}>
 
-```res example
+```res
 let myArray = ["hello", "world", "how are you"]
 
 myArray[0] = "hey" // now ["hey", "world", "how are you"]
@@ -69,13 +73,15 @@ myArray->Array.set(0, "bye") //  ["bye", "world", "how are you", "?"]
 ```
 
 ```js
-var myArray = ["hello", "world", "how are you"];
+let myArray = ["hello", "world", "how are you"];
 
 myArray[0] = "hey";
 
 myArray.push("?");
 
 myArray[0] = "bye";
+
+export { myArray };
 ```
 
 </CodeTab>
@@ -88,21 +94,25 @@ You can spread arrays of the same type into new arrays:
 
 <CodeTab labels={["ReScript", "JS Output"]}>
 
-```res example
+```res
 let y = [1, 2]
 let x = [4, 5, ...y]
 let x2 = [4, 5, ...y, 7, ...y]
 let x3 = [...y]
 ```
 
 ```javascript
-var y = [1, 2];
+import * as Belt_Array from "@rescript/runtime/lib/es6/Belt_Array.js";
 
-var x = [4, 5, ...y];
+let y = [1, 2];
 
-var x2 = [4, 5, ...y, 7, ...y];
+let x = Belt_Array.concatMany([[4, 5], y]);
 
-var x3 = [...y];
+let x2 = Belt_Array.concatMany([[4, 5], y, [7], y]);
+
+let x3 = Belt_Array.concatMany([y]);
+
+export { y, x, x2, x3 };
 ```
 
 </CodeTab>
@@ -118,21 +128,23 @@ ReScript provides a singly linked list too. Lists are:
 
 <CodeTab labels={["ReScript", "JS Output"]}>
 
-```res example
+```res
 let myList = list{1, 2, 3}
 ```
 
 ```js
-var myList = {
+let myList = {
   hd: 1,
   tl: {
     hd: 2,
     tl: {
       hd: 3,
-      tl: 0,
+      tl: /* [] */ 0,
     },
   },
 };
+
+export { myList };
 ```
 
 </CodeTab>
@@ -188,7 +200,7 @@ var anotherList = {
 
 <CodeTab labels={["ReScript", "JS Output"]}>
 
-```res example
+```res
 let message =
   switch myList {
   | list{} => "This list is empty"
@@ -198,18 +210,30 @@ let message =
 ```
 
 ```js
+let myList = {
+  hd: 1,
+  tl: {
+    hd: 2,
+    tl: {
+      hd: 3,
+      tl: /* [] */ 0,
+    },
+  },
+};
+
+let anotherList = {
+  hd: 0,
+  tl: myList,
+};
+
 let message =
   myList !== 0
-    ? {
-        hd: 2,
-        tl: {
-          hd: 3,
-          tl: /* [] */ 0,
-        },
-      } !== 0
+    ? myList.tl !== 0
       ? "The list two items and a potenial remainder of items"
       : "The head of the list is the string " + (1).toString()
     : "This list is empty";
+
+export { myList, anotherList, message };
 ```
 
 </CodeTab>

markdown-pages/docs/manual/async-await.mdx

@@ -47,12 +47,12 @@ let logUserDetails = async (userId: string) => {
 
 ```js
 async function logUserDetails(userId) {
-  var email = await GlobalAPI.fetchUserMail(userId);
-  await GlobalAPI.sendAnalytics(
-    "User details have been logged for " + userId + "",
-  );
-  console.log("Email address for user " + userId + ": " + email + "");
+  let email = await GlobalAPI.fetchUserMail(userId);
+  await GlobalAPI.sendAnalytics(`User details have been logged for ` + userId);
+  console.log(`Email address for user ` + userId + `: ` + email);
 }
+
+export { logUserDetails };
 ```
 
 </CodeTab>
@@ -83,7 +83,7 @@ let fetchUserMail: string => promise<string>
 
 The same logic applies to type definitions in `.res` files:
 
-```res example
+```res
 // function type
 type someAsyncFn = int => promise<int>
 
@@ -105,7 +105,7 @@ let fetchData = async (userId: string): string => {
 
 For completeness reasons, let's expand the full signature and inline type definitions in one code snippet:
 
-```res
+```res nocheck
 // Note how the inline return type uses `string`, while the type definition uses `promise<string>`
 let fetchData: string => promise<string> = async (userId: string): string {
   await fetchUserMail(userId)
@@ -179,7 +179,7 @@ This can be done by wrapping your `await` calls in a new `{}` closure.
 
 <CodeTab labels={["ReScript", "JS Output"]}>
 
-```res example
+```res
 @val external fetchUserMail: string => promise<string> = "GlobalAPI.fetchUserMail"
 
 let fetchData = async () => {
@@ -189,10 +189,12 @@ let fetchData = async () => {
 ```
 
 ```js
-async function fetchData(param) {
-  var mail = (await GlobalAPI.fetchUserMail("1234")).toUpperCase();
-  console.log("All upper-cased mail: " + mail + "");
+async function fetchData() {
+  let mail = (await GlobalAPI.fetchUserMail("1234")).toUpperCase();
+  console.log(`All upper-cased mail: ` + mail);
 }
+
+export { fetchData };
 ```
 
 </CodeTab>
@@ -205,7 +207,7 @@ Note how the original closure was removed in the final JS output. No extra alloc
 
 <CodeTab labels={["ReScript", "JS Output"]}>
 
-```res example
+```res
 @val external fetchUserMail: string => promise<string> = "GlobalAPI.fetchUserMail"
 
 let fetchData = async () => {
@@ -221,15 +223,17 @@ let fetchData = async () => {
 ```
 
 ```js
-async function fetchData(param) {
-  var val;
-  var val$1;
+import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
+
+async function fetchData() {
+  let val;
+  let val$1;
   try {
     val = await GlobalAPI.fetchUserMail("user1");
     val$1 = await GlobalAPI.fetchUserMail("user2");
   } catch (raw_err) {
-    var err = Caml_js_exceptions.internalToOCamlException(raw_err);
-    if (err.RE_EXN_ID === "JsError") {
+    let err = Primitive_exceptions.internalToException(raw_err);
+    if (err.RE_EXN_ID === "JsExn") {
       console.log("Some error occurred", err._1);
       return;
     }
@@ -238,6 +242,8 @@ async function fetchData(param) {
   console.log("user 1 mail: " + val);
   console.log("user 2 mail: " + val$1);
 }
+
+export { fetchData };
 ```
 
 </CodeTab>
@@ -275,7 +281,7 @@ let logMultipleValues = async () => {
 
 Here's a full example of using the MDN `fetch` API, using `async` / `await` to simulate a login:
 
-```res
+```res nocheck
 // A generic Response type for typing our fetch requests
 module Response = {
   type t<'data>

markdown-pages/docs/manual/attribute.mdx

@@ -20,7 +20,9 @@ let mode2 = mode
 ```
 
 ```js
-var mode2 = "dev";
+let mode2 = "dev";
+
+export { mode2 };
 ```
 
 </CodeTab>
@@ -59,7 +61,15 @@ let customTriple = foo => foo * 3
 ```
 
 ```js
+function customDouble(foo) {
+  return foo << 1;
+}
+
+function customTriple(foo) {
+  return (foo * 3) | 0;
+}
 
+export { customDouble, customTriple };
 ```
 
 </CodeTab>
@@ -84,7 +94,7 @@ There's a second category of attributes, called "extension points" (a remnant te
 ```
 
 ```js
-var a = 1;
+((var a = 1));
 ```
 
 </CodeTab>