transpile.js should not be used. Changes to output-js grunt tasks needed.

[zepumph]

We run transpile.js directly too often. There are grunt tasks that are a bit clunky, and don't support watch, like output-js, and we should make those the public api for transpilation. This is of utmost importance as it pertains to the phet codebase. This needs stability, maintainability, and discoverability. This should be a grunt task.

This issue will be informed by discussion in phetsims/perennial#370.

We should not forget about this scary line of public doc telling everything to run a node script. How should we change that?

https://github.com/phetsims/phet-info/blob/9763f6e5b9d2e0c94cbf34d43dd80a8d6070dcda/doc/phet-development-overview.md#L116:

• Run the TypeScript transpiler: node js/scripts/transpile.js --watch which starts a process that will auto-transpile

@samreid and I believe the best api mimics how we are setting up lint and check commands:

grunt output-js                       # transpile your repo and its dependencies (output-js-project is an alias for this).
grunt output-js --all                # transpile all active repos
grunt output-js --all --watch  # support the watch process.

the maintenance tooling uses output-js-project, so keeping that API stable is a very good idea.

Note that the implementation may change to swc in #1354 but the API is stable so nothing will change. This should block that conversion so that entry points only need to be changed once.

• Do the above api
• delete output-js-all in exchange for the option
• update all usages of chipper/js/scripts/transpile.js to use the grunt task.
• Documentation and communication about using the grunt task instead of the script.

[zepumph]

• Apply this patch before merging to main:

Subject: [PATCH] use --all
---
Index: phettest/phettest-server.js
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/phettest/phettest-server.js b/phettest/phettest-server.js
--- a/phettest/phettest-server.js	(revision c307d0825ab226ab8c62a6b2c20a49589db48549)
+++ b/phettest/phettest-server.js	(date 1729535670265)
@@ -260,7 +260,7 @@
       console.log( 'Running output-js-all...' );
 
       // If successful, stdout is returned by execute
-      console.log( await execute( gruntCommand, [ 'output-js-all' ], '../chipper/' ) );
+      console.log( await execute( gruntCommand, [ 'output-js', '--all' ], '../perennial/' ) );
     }
     catch( e ) {
       errorFunction( req, res, 'pull-all\'s output-js-all failed: ' + e.toString() )();
Index: aqua/js/server/QuickServer.js
IDEA additional info:
Subsystem: com.intellij.openapi.diff.impl.patch.CharsetEP
<+>UTF-8
===================================================================
diff --git a/aqua/js/server/QuickServer.js b/aqua/js/server/QuickServer.js
--- a/aqua/js/server/QuickServer.js	(revision 7fe3c88c2115b59392ae5678682b937d970f0f3e)
+++ b/aqua/js/server/QuickServer.js	(date 1729535670282)
@@ -259,7 +259,7 @@
    */
   async transpile() {
     winston.info( 'QuickServer: transpiling' );
-    return execute( gruntCommand, [ 'output-js-all' ], `${this.rootDir}/chipper`, EXECUTE_OPTIONS );
+    return execute( gruntCommand, [ 'output-js', '--all' ], `${this.rootDir}/perennial`, EXECUTE_OPTIONS );
   }
 
   /**

[zepumph]

I feel like grunt output-js --watch is so weird. Maybe we can rename it to transpile without breaking the API for output-js-project. Let's ask JO.

[zepumph]

Alright. 10 TODOs store the main challenge of this issue. @samreid and I would also like to ask @jonathanolson tomorrow if we can rename output-js to transpile, even though we will keep output-js-project for backwards compatibility.

Everything is still on the development branches for perennial and chipper.