Move the task runner to ESM (#27247)

Enable bumping ESM-only dependencies of the task runner,
such as `cpy`, which we use a lot.

And related chores and refactors:

- remove unused and gone tasks
- use makefile in Github Actions
- make docs clearer
- remove redundant NODE_ENV
- update examples
- remove unused eslint comments

.github/workflows/build.yml

@@ -34,13 +34,11 @@ jobs:
 
       - run: make reinstall
 
-      - name: assets test
-        run: ./tools/task-runner/runner validate test
+      - run: make validate
 
-      - name: assets compile
-        run: ./tools/task-runner/runner compile
-        env:
-          NODE_ENV: production
+      - run: make test
+
+      - run: make compile
 
       - name: Test, compile
         # Australia/Sydney  -because it is too easy for devs to forget about timezones

git-hooks/pre-push

@@ -41,8 +41,8 @@ const confirmIfMain = execa
     .catch(() => Promise.reject(new Error('Ok, stopping 😉')));
 const validate = () =>
     execa(
-        './tools/task-runner/runner',
-        ['validate/scalafmt', 'validate-head/index', 'validate/check-for-disallowed-strings'],
+        './tools/task-runner/runner.mjs',
+        ['validate/scalafmt.js', 'validate-head/index.js', 'validate/check-for-disallowed-strings.js'],
         {
             stdio: 'inherit',
         }

makefile

@@ -40,73 +40,67 @@ sbt: # PRIVATE
 
 # Compile all assets in production.
 compile: install
-	@NODE_ENV=production ./tools/task-runner/runner compile
+	@NODE_ENV=production ./tools/task-runner/runner.mjs compile/index.js
 
 # Compile all assets in development.
 compile-dev: install
 	@NODE_ENV=development ./tools/task-runner/runner compile/index.dev
+	@NODE_ENV=development ./tools/task-runner/runner.mjs compile/index.dev.js
 
 # Compile atom-specific JS
 compile-atoms: install
-	@./tools/task-runner/runner compile/javascript/index.atoms
+	@./tools/task-runner/runner.mjs compile/javascript/index.atoms.js
 
 # Compile all assets for watch.
 compile-watch: install # PRIVATE
-	@NODE_ENV=development ./tools/task-runner/runner compile/index.watch
+	@NODE_ENV=development ./tools/task-runner/runner.mjs compile/index.watch.js
 
 compile-javascript: install # PRIVATE
-	@./tools/task-runner/runner compile/javascript
+	@./tools/task-runner/runner.mjs compile/javascript/index.js
 
 compile-javascript-dev: install # PRIVATE
-	@./tools/task-runner/runner compile/javascript/index.dev
+	@./tools/task-runner/runner.mjs compile/javascript/index.dev.js
 
 compile-css: install # PRIVATE
-	@./tools/task-runner/runner compile/css
+	@./tools/task-runner/runner.mjs compile/css/index.js
 
 compile-images: install # PRIVATE
-	@./tools/task-runner/runner compile/images
+	@./tools/task-runner/runner.mjs compile/images/index.js
 
 compile-svgs: install # PRIVATE
-	@./tools/task-runner/runner compile/inline-svgs
-
-compile-fonts: install # PRIVATE
-	@./tools/task-runner/runner compile/fonts
+	@./tools/task-runner/runner.mjs compile/inline-svgs/index.js
 
 # *********************** CHECKS ***********************
 
 # Run the JS test suite.
 test: install
-	@./tools/task-runner/runner test/javascript --verbose
+	@./tools/task-runner/runner.mjs test/javascript/index.js --verbose
 
 # Run the modern JS test suite in watch mode.
 test-watch: install
 	@yarn test -- --watch --coverage
 
-# Check the JS test suite coverage.
-coverage: install
-	@./tools/task-runner/runner test/javascript/coverage --stdout
-
 # Validate all assets.
 validate: install
-	@./tools/task-runner/runner validate --verbose
+	@./tools/task-runner/runner.mjs validate/index.js --verbose
 	@yarn prettier */test/resources/*.json --check
 
 # Validate all SCSS.
 validate-sass: install # PRIVATE
-	@./tools/task-runner/runner validate/sass --verbose
+	@./tools/task-runner/runner.mjs validate/sass.js --verbose
 
 # Validate all JS.
 validate-javascript: install # PRIVATE
-	@./tools/task-runner/runner validate/javascript
+	@./tools/task-runner/runner.mjs validate/javascript.js
 
 # Fix JS linting errors.
 fix: install
-	@./tools/task-runner/runner validate/javascript-fix
+	@./tools/task-runner/runner.mjs validate/javascript-fix.js
 	@yarn prettier */test/resources/*.json --write
 
 # Fix committed JS linting errors.
 fix-commits: install
-	@./tools/task-runner/runner validate-head/javascript-fix
+	@./tools/task-runner/runner.mjs validate-head/javascript-fix.js
 
 # Update caniuse db used by browserslist
 # https://github.com/browserslist/update-db

tools/__tasks__/compile/javascript/index.dev.js

@@ -1,8 +1,8 @@
 const inlineSVGs = require('../inline-svgs/index.js');
 const clean = require('./clean.js');
 const copy = require('./copy.js');
-const webpack = require('./webpack.dev');
-const bundlePolyfills = require('./bundle-polyfills');
+const webpack = require('./webpack.dev.js');
+const bundlePolyfills = require('./bundle-polyfills.js');
 
 const task = {
 	description: 'Prepare JS for development',

tools/task-runner/README.md

@@ -9,7 +9,7 @@ It's intended to exist ‘behind the scenes’, and you should probably be runni
 It takes one or more tasks to run as arguments, which should be relative paths within the `__tasks__` directory, so that:
 
 ```
-./tools/task-runner/runner fakemodule/fakemodule
+./tools/task-runner/runner.mjs fakemodule/fakemodule.js
 ```
 
 will run the task defined in `tools/__tasks__/fakemodule/fakemodule.js`.
@@ -19,7 +19,7 @@ will run the task defined in `tools/__tasks__/fakemodule/fakemodule.js`.
 You can pass a `--dev` flag to prefer a dev version, if it exists (suffix the task's filename with `.dev`), so that:
 
 ```
-./tools/task-runner/runner fakemodule/fakemodule --dev
+./tools/task-runner/runner.mjs fakemodule/fakemodule.dev.js
 ```
 
 -   runs `tools/__tasks__/fakemodule/fakemodule.dev.js` if it exists
@@ -31,7 +31,7 @@ Tasks can be run with `--verbose` flag for fuller output, but this shouldn't usu
 
 ### Options
 
-For a full list, run `./tools/task-runner/runner -h`.
+For a full list, run `./tools/task-runner/runner.mjs -h`.
 
 ## Defining tasks
 

tools/task-runner/run-task-verbose-formater.js → tools/task-runner/run-task-verbose-formater.mjs

@@ -1,5 +1,5 @@
-const figures = require('figures');
-const chalk = require('chalk');
+import figures from 'figures';
+import chalk from 'chalk';
 
 const log = (title, parents, message = '') => {
 	console.log(
@@ -39,7 +39,7 @@ const render = (tasks, parents = []) => {
 	}
 };
 
-class VerboseRenderer {
+export class VerboseRenderer {
 	constructor(tasks) {
 		// eslint-disable-next-line no-underscore-dangle
 		this._tasks = tasks;
@@ -60,5 +60,3 @@ class VerboseRenderer {
 		// do nothing
 	}
 }
-
-module.exports = { VerboseRenderer };

tools/task-runner/runner → tools/task-runner/runner.mjs

@@ -1,20 +1,20 @@
 #!/usr/bin/env node
-/* eslint-disable import/no-dynamic-require, global-require */
 
 // force any plugins that use `chalk` to output in full colour
 process.env.FORCE_COLOR = true;
 
-const path = require('path');
-const os = require('os');
+import path from 'node:path';
+import os from 'node:os';
+import { fileURLToPath } from 'node:url';
 
-const yargs = require('yargs');
-const { hideBin } = require('yargs/helpers');
-const { Listr } = require('listr2');
-const execa = require('execa');
-const chalk = require('chalk');
-const figures = require('figures');
-const uniq = require('lodash.uniq');
-const { VerboseRenderer } = require('./run-task-verbose-formater.js');
+import yargs from 'yargs';
+import { hideBin } from 'yargs/helpers';
+import { Listr } from 'listr2';
+import execa from 'execa';
+import chalk from 'chalk';
+import figures from 'figures';
+import uniq from 'lodash.uniq';
+import { VerboseRenderer } from './run-task-verbose-formater.mjs';
 
 // name of the tasks directory
 const tasksDirectory = '__tasks__';
@@ -48,27 +48,28 @@ const {
 	})
 	.usage('Usage: $0 <task> [<task>] [--dev]')
 	.command('task', `Run a task defined in '${tasksDirectory}'.`)
-	.example('$0 copy', 'Run all the copy tasks.')
-	.example('$0 javascript/copy', 'Run the javascript copy task.')
+	.example('$0 copy/index.js', 'Run all the copy tasks.')
+	.example('$0 javascript/copy.js', 'Run the javascript copy task.')
+	.example('$0 compile/index.dev.js', 'Run the compile dev copy task.')
 	.example(
-		'$0 javascript/copy --dev',
-		'Run the javascript copy task, and prefer the development version, if it exists.',
-	)
-	.example(
-		'$0 javascript/copy css/copy --dev',
-		'Run the javascript and css copy tasks, and prefer the development versions, if they exist.',
+		'$0 compile/javascript/copy.js compile/css/copy.js',
+		'Run the javascript copy and css copy tasks.',
 	)
 	.demand(1)
 	.help()
-	.alias('h', 'help') // eslint-disable-line newline-per-chained-call
+	.alias('h', 'help')
 	.version()
-	.alias('v', 'version').argv; // eslint-disable-line newline-per-chained-call
+	.alias('v', 'version').argv;
 
 // if this is true, we log as much as we can
 const VERBOSE = IS_VERBOSE || IS_DEBUG;
 
 // look here for tasks that come in from yargs
-const taskSrc = path.resolve(__dirname, '..', tasksDirectory);
+const taskSrc = path.resolve(
+	path.dirname(fileURLToPath(import.meta.url)),
+	'..',
+	tasksDirectory,
+);
 
 // we will store tasks that we run in here, to prevent running them more than once
 // e.g. if two tasks rely on the same thing
@@ -170,10 +171,10 @@ function listrify(steps, { concurrent = false } = {}) {
 }
 
 // resolve the tasks from yargs to actual files
-const getTasksFromModule = (taskName) => {
+const getTasksFromModule = async (taskName) => {
 	try {
 		const modulePath = path.resolve(taskSrc, taskName);
-		return require(modulePath);
+		return (await import(modulePath)).default;
 	} catch (e) {
 		// we can't find any modules, or something else has gone wrong in resolving it
 		// so output an erroring task
@@ -185,7 +186,7 @@ const getTasksFromModule = (taskName) => {
 };
 
 // get a list of the tasks we're going to run
-const taskModules = TASKS.map(getTasksFromModule);
+const taskModules = await Promise.all(TASKS.map(getTasksFromModule));
 
 // run them!
 listrify(taskModules)