build: Refactor gulpfiles from CJS to ESM (#9149)

* refactor(build): Rename "package" gulp task (but not npm script) to "pack"

  This is to avoid an issue due to "package" being a reserved word
  in JavaScript, and therefore not a valid export identifier.

* refactor(build): Convert gulpfile.js from CJS to ESM.

* refactor(build): Convert scripts/gulpfiles/*.js from CJS to ESM

* fix(build): Fix eslint warning for @license tag in gulpfile.mjs

* chore(build): Remove unused imports

* fix(build): Fix incorrect import of gulp-gzip

* fix(build): Fix incorrect sourcemaps import reference

Author: cpcallen

eslint.config.mjs

@@ -184,7 +184,7 @@ export default [
     files: [
       'eslint.config.mjs',
       '.prettierrc.js',
-      'gulpfile.js',
+      'gulpfile.mjs',
       'scripts/helpers.js',
       'tests/mocha/.mocharc.js',
       'tests/migration/validate-renamings.mjs',

gulpfile.js

@@ -0,0 +1,95 @@
+/**
+ * @license
+ * Copyright 2018 Google LLC
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+/**
+ * @fileoverview Gulp script to build Blockly for Node & NPM.
+ * Run this script by calling "npm install" in this directory.
+ */
+/* eslint-env node */
+
+// Needed to prevent prettier from munging exports order, due to
+// https://github.com/simonhaenisch/prettier-plugin-organize-imports/issues/146
+// - but has the unfortunate side effect of suppressing ordering of
+// imports too:
+//
+// organize-imports-ignore
+
+import {parallel} from 'gulp';
+import {
+  deployDemos,
+  deployDemosBeta,
+  prepareDemos,
+} from './scripts/gulpfiles/appengine_tasks.mjs';
+import {
+  build,
+  buildAdvancedCompilationTest,
+  cleanBuildDir,
+  langfiles,
+  messages,
+  minify,
+  tsc,
+} from './scripts/gulpfiles/build_tasks.mjs';
+import {docs} from './scripts/gulpfiles/docs_tasks.mjs';
+import {
+  createRC,
+  syncDevelop,
+  syncMaster,
+  updateGithubPages,
+} from './scripts/gulpfiles/git_tasks.mjs';
+import {cleanReleaseDir, pack} from './scripts/gulpfiles/package_tasks.mjs';
+import {
+  publish,
+  publishBeta,
+  recompile,
+} from './scripts/gulpfiles/release_tasks.mjs';
+import {generators, test} from './scripts/gulpfiles/test_tasks.mjs';
+
+const clean = parallel(cleanBuildDir, cleanReleaseDir);
+
+// Default target if gulp invoked without specifying.
+export default build;
+
+// Main sequence targets.  They already invoke prerequisites.  Listed
+// in typical order of invocation, and strictly listing prerequisites
+// before dependants.
+//
+// prettier-ignore
+export {
+  langfiles,
+  tsc,
+  minify,
+  build,
+  pack,  // Formerly package.
+  publishBeta,
+  publish,
+  prepareDemos,
+  deployDemosBeta,
+  deployDemos,
+  updateGithubPages as gitUpdateGithubPages,
+}
+
+// Manually-invokable targets that also invoke prerequisites where
+// required.
+//
+// prettier-ignore
+export {
+  messages, // Generate msg/json/en.json et al.
+  clean,
+  test,
+  generators as testGenerators,
+  buildAdvancedCompilationTest,
+  createRC as gitCreateRC,
+  docs,
+}
+
+// Legacy targets, to be deleted.
+//
+// prettier-ignore
+export {
+  recompile,
+  syncDevelop as gitSyncDevelop,
+  syncMaster as gitSyncMaster,
+}

gulpfile.mjs

@@ -33,7 +33,7 @@
     "lint:fix": "eslint . --fix",
     "langfiles": "gulp langfiles",
     "minify": "gulp minify",
-    "package": "gulp package",
+    "package": "gulp pack",
     "postinstall": "patch-package",
     "prepareDemos": "gulp prepareDemos",
     "publish": "npm ci && gulp publish",

package.json

@@ -8,16 +8,16 @@
  * @fileoverview Gulp script to deploy Blockly demos on appengine.
  */
 
-const gulp = require('gulp');
+import * as gulp from 'gulp';
 
-const fs = require('fs');
-const path = require('path');
-const execSync = require('child_process').execSync;
-const buildTasks = require('./build_tasks.js');
-const packageTasks = require('./package_tasks.js');
-const {rimraf} = require('rimraf');
+import * as fs from 'fs';
+import * as path from 'path';
+import {execSync} from 'child_process';
+import * as buildTasks from './build_tasks.mjs';
+import {getPackageJson} from './helper_tasks.mjs';
+import * as packageTasks from './package_tasks.mjs';
+import {rimraf} from 'rimraf';
 
-const packageJson = require('../../package.json');
 const demoTmpDir = '../_deploy';
 const demoStaticTmpDir = '../_deploy/static';
 
@@ -123,7 +123,7 @@ function deployToAndClean(demoVersion) {
  */
 function getDemosVersion() {
   // Replace all '.' with '-' e.g. 9-3-3-beta-2
-  return packageJson.version.replace(/\./g, '-');
+  return getPackageJson().version.replace(/\./g, '-');
 }
 
 /**
@@ -162,7 +162,7 @@ function deployBetaAndClean(done) {
  *
  * Prerequisites (invoked): clean, build
  */
-const prepareDemos = gulp.series(
+export const prepareDemos = gulp.series(
     prepareDeployDir,
     gulp.parallel(
         gulp.series(
@@ -180,16 +180,9 @@ const prepareDemos = gulp.series(
 /**
  * Deploys demos.
  */
-const deployDemos = gulp.series(prepareDemos, deployAndClean);
+export const deployDemos = gulp.series(prepareDemos, deployAndClean);
 
 /**
  * Deploys beta version of demos (version appended with -beta).
  */
-const deployDemosBeta = gulp.series(prepareDemos, deployBetaAndClean);
-
-module.exports = {
-  // Main sequence targets.  Each should invoke any immediate prerequisite(s).
-  deployDemos: deployDemos,
-  deployDemosBeta: deployDemosBeta,
-  prepareDemos: prepareDemos
-};
+export const deployDemosBeta = gulp.series(prepareDemos, deployBetaAndClean);

scripts/gulpfiles/appengine_tasks.js renamed to scripts/gulpfiles/appengine_tasks.mjs

@@ -8,25 +8,32 @@
  * @fileoverview Gulp script to build Blockly for Node & NPM.
  */
 
-const gulp = require('gulp');
-gulp.replace = require('gulp-replace');
-gulp.rename = require('gulp-rename');
-gulp.sourcemaps = require('gulp-sourcemaps');
+import * as gulp from 'gulp';
+import replace from 'gulp-replace';
+import rename from 'gulp-rename';
+import sourcemaps from 'gulp-sourcemaps';
 
-const path = require('path');
-const fs = require('fs');
-const fsPromises = require('fs/promises');
-const {exec, execSync} = require('child_process');
+import * as path from 'path';
+import * as fs from 'fs';
+import * as fsPromises from 'fs/promises';
+import {exec, execSync} from 'child_process';
 
-const {globSync} = require('glob');
-const closureCompiler = require('google-closure-compiler').gulp();
-const argv = require('yargs').argv;
-const {rimraf} = require('rimraf');
+import {globSync} from 'glob';
+// For v20250609.0.0 and later:
+// import {gulp as closureCompiler} from 'google-closure-compiler';
+import ClosureCompiler from 'google-closure-compiler';
+import yargs from 'yargs';
+import {hideBin} from 'yargs/helpers';
+import {rimraf} from 'rimraf';
 
-const {BUILD_DIR, LANG_BUILD_DIR, RELEASE_DIR, TSC_OUTPUT_DIR, TYPINGS_BUILD_DIR} = require('./config');
-const {getPackageJson} = require('./helper_tasks');
+import {BUILD_DIR, LANG_BUILD_DIR, RELEASE_DIR, TSC_OUTPUT_DIR, TYPINGS_BUILD_DIR} from './config.mjs';
+import {getPackageJson} from './helper_tasks.mjs';
 
-const {posixPath, quote} = require('../helpers');
+import {posixPath, quote} from '../helpers.js';
+
+const closureCompiler = ClosureCompiler.gulp();
+
+const argv = yargs(hideBin(process.argv)).parse();
 
 ////////////////////////////////////////////////////////////
 //                        Build                           //
@@ -182,7 +189,7 @@ function stripApacheLicense() {
   // Closure Compiler preserves dozens of Apache licences in the Blockly code.
   // Remove these if they belong to Google or MIT.
   // MIT's permission to do this is logged in Blockly issue #2412.
-  return gulp.replace(new RegExp(licenseRegex, 'g'), '\n\n\n\n');
+  return replace(new RegExp(licenseRegex, 'g'), '\n\n\n\n');
   // Replace with the same number of lines so that source-maps are not affected.
 }
 
@@ -306,7 +313,7 @@ const JSCOMP_OFF = [
  * Builds Blockly as a JS program, by running tsc on all the files in
  * the core directory.
  */
-function buildJavaScript(done) {
+export function tsc(done) {
   execSync(
       `tsc -outDir "${TSC_OUTPUT_DIR}" -declarationDir "${TYPINGS_BUILD_DIR}"`,
       {stdio: 'inherit'});
@@ -318,7 +325,7 @@ function buildJavaScript(done) {
  * This task regenerates msg/json/en.js and msg/json/qqq.js from
  * msg/messages.js.
  */
-function generateMessages(done) {
+export function messages(done) {
   // Run js_to_json.py
   const jsToJsonCmd = `${PYTHON} scripts/i18n/js_to_json.py \
       --input_file ${path.join('msg', 'messages.js')} \
@@ -573,10 +580,10 @@ function buildCompiled() {
   // Fire up compilation pipline.
   return gulp.src(chunkOptions.js, {base: './'})
       .pipe(stripApacheLicense())
-      .pipe(gulp.sourcemaps.init())
+      .pipe(sourcemaps.init())
       .pipe(compile(options))
-      .pipe(gulp.rename({suffix: COMPILED_SUFFIX}))
-      .pipe(gulp.sourcemaps.write('.'))
+      .pipe(rename({suffix: COMPILED_SUFFIX}))
+      .pipe(sourcemaps.write('.'))
       .pipe(gulp.dest(RELEASE_DIR));
 }
 
@@ -668,7 +675,7 @@ async function buildLangfileShims() {
   // (We have to do it this way because messages.js is a script and
   // not a CJS module with exports.)
   globalThis.Blockly = {Msg: {}};
-  require('../../msg/messages.js');
+  await import('../../msg/messages.js');
   const exportedNames = Object.keys(globalThis.Blockly.Msg);
   delete globalThis.Blockly;
 
@@ -689,12 +696,14 @@ ${exportedNames.map((name) => `  ${name},`).join('\n')}
 }
 
 /**
- * This task builds Blockly core, blocks and generators together and uses
- * Closure Compiler's ADVANCED_COMPILATION mode.
+ * This task uses Closure Compiler's ADVANCED_COMPILATION mode to
+ * compile together Blockly core, blocks and generators with a simple
+ * test app; the purpose is to verify that Blockly is compatible with
+ * the ADVANCED_COMPILATION mode.
  *
  * Prerequisite: buildJavaScript.
  */
-function buildAdvancedCompilationTest() {
+function compileAdvancedCompilationTest() {
   // If main_compressed.js exists (from a previous run) delete it so that
   // a later browser-based test won't check it should the compile fail.
   try {
@@ -718,17 +727,17 @@ function buildAdvancedCompilationTest() {
   };
   return gulp.src(srcs, {base: './'})
       .pipe(stripApacheLicense())
-      .pipe(gulp.sourcemaps.init())
+      .pipe(sourcemaps.init())
       .pipe(compile(options))
-      .pipe(gulp.sourcemaps.write(
+      .pipe(sourcemaps.write(
           '.', {includeContent: false, sourceRoot: '../../'}))
       .pipe(gulp.dest('./tests/compile/'));
 }
 
 /**
  * This task cleans the build directory (by deleting it).
  */
-function cleanBuildDir() {
+export function cleanBuildDir() {
   // Sanity check.
   if (BUILD_DIR === '.' || BUILD_DIR === '/') {
     return Promise.reject(`Refusing to rm -rf ${BUILD_DIR}`);
@@ -737,16 +746,13 @@ function cleanBuildDir() {
 }
 
 // Main sequence targets.  Each should invoke any immediate prerequisite(s).
-exports.cleanBuildDir = cleanBuildDir;
-exports.langfiles = gulp.parallel(buildLangfiles, buildLangfileShims);
-exports.tsc = buildJavaScript;
-exports.minify = gulp.series(exports.tsc, buildCompiled, buildShims);
-exports.build = gulp.parallel(exports.minify, exports.langfiles);
+// function cleanBuildDir, above
+export const langfiles = gulp.parallel(buildLangfiles, buildLangfileShims);
+export const minify = gulp.series(tsc, buildCompiled, buildShims);
+// function tsc, above
+export const build = gulp.parallel(minify, langfiles);
 
 // Manually-invokable targets, with prerequisites where required.
-exports.messages = generateMessages;  // Generate msg/json/en.json et al.
-exports.buildAdvancedCompilationTest =
-    gulp.series(exports.tsc, buildAdvancedCompilationTest);
-
-// Targets intended only for invocation by scripts; may omit prerequisites.
-exports.onlyBuildAdvancedCompilationTest = buildAdvancedCompilationTest;
+// function messages, above
+export const buildAdvancedCompilationTest =
+    gulp.series(tsc, compileAdvancedCompilationTest);