Developer playground

.github/workflows/ci.yml

@@ -382,6 +382,18 @@ jobs:
         if: matrix.build_playground
         run: yarn workspace playground test
 
+      - name: Stage dev playground compiler bundle
+        if: ${{ matrix.build_playground && github.event_name == 'push' && github.ref == 'refs/heads/master' }}
+        run: yarn workspace dev-playground stage-master-bundle
+
+      - name: "Upload artifacts: dev playground compiler bundle"
+        if: ${{ matrix.build_playground && github.event_name == 'push' && github.ref == 'refs/heads/master' }}
+        uses: actions/upload-artifact@v7
+        with:
+          name: dev-playground-master-bundle
+          path: packages/dev-playground/public/playground-bundles/master
+          if-no-files-found: error
+
       - name: Setup Rclone
         if: ${{ matrix.build_playground && startsWith(github.ref, 'refs/tags/v') }}
         uses: cometkim/rclone-actions/setup-rclone@main
@@ -430,6 +442,62 @@ jobs:
           name: api
           path: scripts/res/apiDocs/
 
+  dev-playground:
+    needs:
+      - build-compiler
+    if: ${{ github.event_name == 'push' && github.ref == 'refs/heads/master' }}
+    runs-on: ubuntu-24.04
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}dev-playground/
+    env:
+      VITE_DEFAULT_COMPILER_VERSION: master
+      VITE_COMPILER_VERSIONS: '[{"id":"master","label":"master"}]'
+      GITHUB_PAGES_PATH: dev-playground
+      PLAYGROUND_BUNDLE_ID: master
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Use Node.js
+        uses: actions/setup-node@v6
+        with:
+          cache: yarn
+          node-version-file: .nvmrc
+
+      - name: Install npm packages
+        run: yarn install
+
+      - name: Download dev playground compiler bundle
+        uses: actions/download-artifact@v8
+        with:
+          name: dev-playground-master-bundle
+          path: packages/dev-playground/public/playground-bundles/master
+
+      - name: Configure GitHub Pages
+        id: pages
+        uses: actions/configure-pages@v6
+
+      - name: Build dev playground Pages site
+        env:
+          VITE_BASE: ${{ steps.pages.outputs.base_path }}/dev-playground/
+        run: |
+          yarn workspace dev-playground build
+          yarn workspace dev-playground prepare-pages-site
+
+      - name: Upload GitHub Pages artifact
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: packages/dev-playground/pages-site
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5
+
   pkg-pr-new:
     needs:
       - build-compiler

.gitignore

@@ -72,6 +72,12 @@ playground/*.cmj
 playground/*.cmi
 playground/.netrc
 playground/compiler.*js
+packages/dev-playground/dist/
+packages/dev-playground/pages-site/
+packages/dev-playground/lib/
+packages/dev-playground/src/*.res.mjs
+packages/dev-playground/public/playground-bundles/*
+!packages/dev-playground/public/playground-bundles/.gitignore
 
 rewatch/target/
 rewatch/rewatch

CHANGELOG.md

@@ -44,6 +44,7 @@
 #### :house: Internal
 
 - Remove `Primitive_option.toUndefined`; use `valFromOption` for optional ffi args. https://github.com/rescript-lang/rescript/pull/8380
+- Add a developer playground for testing the current compiler bundle locally and deploy the latest `master` build to GitHub Pages. https://github.com/rescript-lang/rescript/pull/8435
 - Expand `super_errors` fixture coverage for warnings and errors. https://github.com/rescript-lang/rescript/pull/8429
 - Run `super_errors` fixtures in parallel (~2.4× faster locally). https://github.com/rescript-lang/rescript/pull/8430
 - Expand `super_errors` fixture coverage for the remaining reachable single-file error variants. https://github.com/rescript-lang/rescript/pull/8432

Makefile

@@ -204,6 +204,15 @@ $(PLAYGROUND_CMI_BUILD_STAMP): $(RUNTIME_BUILD_STAMP)
 playground-test: playground
 	yarn workspace playground test
 
+dev-playground-stage: playground
+	yarn workspace dev-playground stage-local-bundle
+
+dev-playground: dev-playground-stage
+	yarn workspace dev-playground dev
+
+dev-playground-build: dev-playground-stage
+	yarn workspace dev-playground build
+
 # Builds the playground, runs some e2e tests and releases the playground to the
 # Cloudflare R2 (requires Rclone `rescript:` remote)
 playground-release: playground-test

compiler/jsoo/jsoo_playground_main.ml

@@ -51,8 +51,9 @@
  * modules in the playground.
  * v5: Removed .ml support.
  * v6: Added `config.experimental_features` and `config.jsx_preserve_mode` to the BundleConfig.
+ * v7: Added opt-in debug dump output APIs for developer playground tooling.
  * *)
-let api_version = "6"
+let api_version = "7"
 
 module Js = Js_of_ocaml.Js
 
@@ -298,6 +299,8 @@ let rescript_parse ~filename src =
   structure
 
 module Printer = struct
+  let to_string printer value = Format.asprintf "%a@." printer value
+
   let print_expr typ =
     Printtyp.reset_names ();
     Printtyp.reset_and_mark_loops typ;
@@ -312,6 +315,23 @@ module Printer = struct
          (Printtyp.tree_of_type_declaration (Ident.create name) decl rec_status))
 end
 
+module DebugOutput = struct
+  type t = ParseTree | TypedTree | Lambda | Lam
+
+  let from_string = function
+    | "parsetree" -> Some ParseTree
+    | "typedtree" -> Some TypedTree
+    | "lambda" -> Some Lambda
+    | "lam" -> Some Lam
+    | _ -> None
+
+  let from_js_array value =
+    value |> Js.to_array |> Array.to_list
+    |> List.filter_map (fun item -> from_string (Js.to_string item))
+
+  let has output outputs = List.exists (fun item -> item = output) outputs
+end
+
 module Compile = struct
   (* Apparently it's not possible to retrieve the loc info from
    * Location.error_of_exn properly, so we need to do some extra
@@ -472,7 +492,12 @@ module Compile = struct
     List.iter Iter.iter_structure_item structure.str_items;
     Js.array (!acc |> Array.of_list)
 
-  let implementation ~(config : BundleConfig.t) ~lang str =
+  let optional_string_attr name = function
+    | Some value -> Js.Unsafe.[|(name, inject @@ Js.string value)|]
+    | None -> [||]
+
+  let implementation ?(debug_outputs = []) ~(config : BundleConfig.t) ~lang str
+      =
     let {
       BundleConfig.module_system;
       warn_flags;
@@ -505,6 +530,11 @@ module Compile = struct
       (* default *)
       let ast = impl str in
       let ast = Ppx_entry.rewrite_implementation ast in
+      let debug_parsetree =
+        if DebugOutput.has DebugOutput.ParseTree debug_outputs then
+          Some (Printer.to_string Printast.implementation ast)
+        else None
+      in
       let typed_tree =
         let a, b, _, signature =
           Typemod.type_implementation_more modulename modulename modulename env
@@ -514,19 +544,38 @@ module Compile = struct
         types_signature := signature;
         (a, b)
       in
+      let debug_typedtree =
+        if DebugOutput.has DebugOutput.TypedTree debug_outputs then
+          Some
+            (Printer.to_string Printtyped.implementation_with_coercion
+               typed_tree)
+        else None
+      in
       typed_tree |> Translmod.transl_implementation modulename
-      |> (* Printlambda.lambda ppf *) fun (lam, exports) ->
+      |> fun (lambda, exports) ->
+      let debug_lambda =
+        if DebugOutput.has DebugOutput.Lambda debug_outputs then
+          Some (Printer.to_string Printlambda.lambda lambda)
+        else None
+      in
+      let debug_lam =
+        if DebugOutput.has DebugOutput.Lam debug_outputs then
+          let export_ident_sets = Set_ident.of_list exports in
+          let lam, _ = Lam_convert.convert export_ident_sets lambda in
+          Some (Lam_print.lambda_to_string lam)
+        else None
+      in
       let buffer = Buffer.create 1000 in
       let () =
         Js_dump_program.pp_deps_program ~output_prefix:""
           (* does not matter here *) module_system
-          (Lam_compile_main.compile "" exports lam)
+          (Lam_compile_main.compile "" exports lambda)
           (Ext_pp.from_buffer buffer)
       in
       let v = Buffer.contents buffer in
       let type_hints = collect_type_hints typed_tree in
-      Js.Unsafe.(
-        obj
+      let attrs =
+        Js.Unsafe.
           [|
             ("js_code", inject @@ Js.string v);
             ( "warnings",
@@ -536,7 +585,18 @@ module Compile = struct
                  |> Js.array |> inject) );
             ("type_hints", inject @@ type_hints);
             ("type", inject @@ Js.string "success");
-          |])
+          |]
+      in
+      Js.Unsafe.(
+        obj
+          (Array.concat
+             [
+               attrs;
+               optional_string_attr "parsetree" debug_parsetree;
+               optional_string_attr "typedtree" debug_typedtree;
+               optional_string_attr "lambda" debug_lambda;
+               optional_string_attr "lam" debug_lam;
+             ]))
     with e -> (
       match e with
       | Arg.Bad msg -> ErrorRet.make_warning_flag_error ~warn_flags msg
@@ -582,6 +642,12 @@ module Export = struct
           inject
           @@ Js.wrap_meth_callback (fun _ code ->
                  Compile.implementation ~config ~lang (Js.to_string code)) );
+        ( "compileWithDebug",
+          inject
+          @@ Js.wrap_meth_callback (fun _ code debug_outputs ->
+                 Compile.implementation
+                   ~debug_outputs:(DebugOutput.from_js_array debug_outputs)
+                   ~config ~lang (Js.to_string code)) );
         ("version", inject @@ Js.string Bs_version.version);
       |]
     in