refactor: migrate task runners to Hereby

.eslintignore

@@ -1,2 +1,14 @@
-**/node_modules/**/*.js
-**/test/fixtures/**/*.js
+# Ignore output files.
+**/out/
+
+# Ignore temp directories.
+**/tmp/
+
+# Ignore code coverage reports.
+coverage/
+
+# Ignore static files that are part of JSDoc's output.
+packages/**/static/**
+
+# Ignore test fixtures.
+packages/**/test/fixtures/**

.prettierignore

@@ -1,8 +1,14 @@
-# Ignore test fixtures.
-packages/**/test/fixtures/**/*.js
+# Ignore output files.
+**/out/
 
-# Ignore static JS files.
-packages/**/static/*.js
+# Ignore temp directories.
+**/tmp/
 
 # Ignore code coverage reports.
-.nyc_output/
+coverage/
+
+# Ignore static files that are part of JSDoc's output.
+packages/**/static/**
+
+# Ignore test fixtures.
+packages/**/test/fixtures/**

CHANGES.md

@@ -2,43 +2,36 @@
 
 This file describes notable changes in each version of JSDoc, starting with version 3.0.0.
 
-
 ## 4.0.0 (November 2022)
 
-+ JSDoc releases now use [semantic versioning](https://semver.org/). If JSDoc makes
+- JSDoc releases now use [semantic versioning](https://semver.org/). If JSDoc makes
   backwards-incompatible changes in the future, the major version will be incremented.
-+ JSDoc no longer uses the [`taffydb`](https://taffydb.com/) package. If your JSDoc template or
+- JSDoc no longer uses the [`taffydb`](https://taffydb.com/) package. If your JSDoc template or
   plugin uses the `taffydb` package, see the
   [instructions for replacing `taffydb` with `@jsdoc/salty`](https://github.com/jsdoc/jsdoc/tree/main/packages/jsdoc-salty#use-salty-in-a-jsdoc-template).
-+ JSDoc now supports Node.js 12.0.0 and later.
-
+- JSDoc now supports Node.js 12.0.0 and later.
 
 ## 3.6.11 (July 2022)
 
 Updates dependency versions to make JSDoc compatible with Node.js 12.0.0 and later.
 
-
 ## 3.6.10 (January 2022)
 
 Fixes an issue in JSDoc 3.6.9 that prevented JSDoc from being installed in some continuous
 integration (CI) environments.
 
-
 ## 3.6.9 (January 2022)
 
 Fixes an issue in JSDoc 3.6.8 that prevented `npm install jsdoc` from working.
 
-
 ## 3.6.8 (January 2022)
 
 Updates dependencies.
 
-
 ## 3.6.7 (May 2021)
 
 Updates dependencies.
 
-
 ## 3.6.6 (September 2020)
 
 Fixes an issue that could cause members of an interface to be tracked incorrectly if the interface

Herebyfile.mjs

@@ -0,0 +1,111 @@
+/*
+  Copyright 2023 the JSDoc Authors.
+
+  Licensed under the Apache License, Version 2.0 (the "License");
+  you may not use this file except in compliance with the License.
+  You may obtain a copy of the License at
+
+      https://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing, software
+  distributed under the License is distributed on an "AS IS" BASIS,
+  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+  See the License for the specific language governing permissions and
+  limitations under the License.
+*/
+import { LicenseChecker } from 'js-green-licenses';
+import { execa } from 'execa';
+import path from 'path';
+import { task } from 'hereby';
+
+const BIN_DIR = 'node_modules/.bin';
+const JSDOC_BIN = 'packages/jsdoc/jsdoc.js';
+const NODE_BIN = process.execPath;
+
+const sourceGlob = ['*.js', '*.mjs', 'packages/**/*.js'];
+
+function bin(name) {
+  return path.join(BIN_DIR, name);
+}
+
+export const coverage = task({
+  name: 'coverage',
+  run: async () => {
+    await execa(bin('c8'), [
+      '--exclude=Herebyfile.mjs',
+      "--exclude='**/test{,s}/**'",
+      '--reporter=html',
+      bin('hereby'),
+      'test',
+    ]);
+  },
+});
+
+export const dependencyLicenses = task({
+  name: 'dependency-licenses',
+  run: () => {
+    const checker = new LicenseChecker({ verbose: false });
+    const log = console.log;
+
+    return new Promise((resolve, reject) => {
+      // Temporarily silence console.log() to prevent unnecessary output.
+      console.log = () => {}; // eslint-disable-line no-empty-function
+
+      checker.on('end', () => {
+        console.log = log;
+        resolve();
+      });
+      checker.on('error', (e) => {
+        const message =
+          `Error while processing ${e.packageName}@${e.versionSpec}: ${e.err}. ` +
+          `Parent packages: ${JSON.stringify(e.parentPackages, null, 0)}`;
+
+        console.log = log;
+        reject(new Error(message));
+      });
+      checker.on('non-green-license', (e) => {
+        const message =
+          `${e.packageName}@${e.version} has an invalid license: ${e.licenseName}. ` +
+          `Parent packages: ${JSON.stringify(e.parentPackages, null, 0)}`;
+
+        console.log = log;
+        reject(new Error(message));
+      });
+
+      checker.checkLocalDirectory('.');
+    });
+  },
+});
+
+export const format = task({
+  name: 'format',
+  run: async () => {
+    await execa(bin('prettier'), ['--write', './']);
+  },
+});
+
+export const licenseCheck = task({
+  name: 'license-check',
+  dependencies: [dependencyLicenses],
+});
+
+export const lint = task({
+  name: 'lint',
+  run: async () => {
+    await execa(bin('eslint'), [...sourceGlob]);
+  },
+});
+
+export const test = task({
+  name: 'test',
+  run: async () => {
+    await execa(NODE_BIN, [JSDOC_BIN, '-T']);
+  },
+});
+
+const lintAndTest = task({
+  name: 'lint-and-test',
+  dependencies: [lint, test],
+});
+
+export default lintAndTest;

gulpfile.js

@@ -1,89 +0,0 @@
-const eslint = require('gulp-eslint-new');
-const { exec } = require('child_process');
-const gulp = require('gulp');
-const { LicenseChecker } = require('js-green-licenses');
-const path = require('path');
-const prettier = require('gulp-prettier');
-
-function execCb(cb, err, stdout, stderr) {
-  console.log(stdout);
-  console.error(stderr);
-  cb(err);
-}
-
-const options = {
-  lintPaths: [
-    '*.js',
-    'packages/**/*.js',
-    '!packages/**/static/*.js',
-    '!packages/**/test/fixtures/**/*.js',
-  ],
-  nodeBin: path.resolve(__dirname, './packages/jsdoc/jsdoc.js'),
-  nodePath: process.execPath,
-};
-
-function coverage(cb) {
-  const cmd = `./node_modules/.bin/nyc --reporter=html ${options.nodeBin} -T`;
-
-  return exec(cmd, execCb.bind(null, cb));
-}
-
-function format() {
-  return gulp.src(options.lintPaths, { base: './' }).pipe(prettier()).pipe(gulp.dest('./'));
-}
-
-function licenses() {
-  const checker = new LicenseChecker({ verbose: false });
-  const log = console.log;
-
-  return new Promise((resolve, reject) => {
-    // Temporarily silence console.log() to prevent unnecessary output.
-    /* eslint-disable no-empty-function */
-    console.log = () => {};
-    /* eslint-enable no-empty-function */
-
-    checker.on('end', () => {
-      console.log = log;
-      resolve();
-    });
-    checker.on('error', (e) => {
-      const message =
-        `Error while processing ${e.packageName}@${e.versionSpec}: ${e.err}. ` +
-        `Parent packages: ${JSON.stringify(e.parentPackages, null, 0)}`;
-
-      console.log = log;
-      reject(new Error(message));
-    });
-    checker.on('non-green-license', (e) => {
-      const message =
-        `${e.packageName}@${e.version} has an invalid license: ${e.licenseName}. ` +
-        `Parent packages: ${JSON.stringify(e.parentPackages, null, 0)}`;
-
-      console.log = log;
-      reject(new Error(message));
-    });
-
-    checker.checkLocalDirectory('.');
-  });
-}
-
-function lint() {
-  return gulp
-    .src(options.lintPaths)
-    .pipe(eslint())
-    .pipe(eslint.formatEach())
-    .pipe(eslint.failAfterError());
-}
-
-function test(cb) {
-  const cmd = `${options.nodePath} "${options.nodeBin}" -T`;
-
-  return exec(cmd, execCb.bind(null, cb));
-}
-
-exports.coverage = coverage;
-exports.default = gulp.series(licenses, lint, test);
-exports.format = format;
-exports.licenses = licenses;
-exports.lint = lint;
-exports.test = test;

package.json

@@ -6,12 +6,12 @@
     "@jsdoc/eslint-config": "^1.0.8",
     "@jsdoc/test-matchers": "^0.1.9",
     "ajv": "^8.11.2",
+    "c8": "^7.12.0",
     "eslint": "^8.28.0",
     "eslint-config-prettier": "^8.5.0",
     "eslint-plugin-prettier": "^4.2.1",
-    "gulp": "^4.0.2",
-    "gulp-eslint-new": "^1.7.1",
-    "gulp-prettier": "^4.0.0",
+    "execa": "^6.1.0",
+    "hereby": "^1.6.4",
     "jasmine": "^3.99.0",
     "jasmine-console-reporter": "^3.1.0",
     "js-green-licenses": "^3.0.1",
@@ -19,7 +19,6 @@
     "lerna": "^6.0.3",
     "lodash": "^4.17.21",
     "mock-fs": "^5.2.0",
-    "nyc": "^15.1.0",
     "prettier": "^2.7.1",
     "taffydb": "2.6.2"
   },
@@ -27,6 +26,11 @@
     "node": ">=v18.12.0"
   },
   "scripts": {
-    "test": "gulp"
+    "coverage": "node_modules/.bin/hereby coverage",
+    "default": "node_modules/.bin/hereby",
+    "format": "node_modules/.bin/hereby format",
+    "license-check": "node_modules/.bin/hereby license-check",
+    "lint": "node_modules/.bin/hereby lint",
+    "test": "node_modules/.bin/hereby test"
   }
 }

packages/jsdoc-core/test/specs/lib/env.js

@@ -29,7 +29,7 @@ describe('@jsdoc/core.env', () => {
 
   it('has a `version` object with `number` and `revision` properties', () => {
     expect(env.version).toBeObject();
-    expect(env.version).toHaveOwnProperty('number');
-    expect(env.version).toHaveOwnProperty('revision');
+    expect(Object.hasOwn(env.version, 'number')).toBeTrue();
+    expect(Object.hasOwn(env.version, 'revision')).toBeTrue();
   });
 });

packages/jsdoc-eslint-config/index.js

@@ -6,7 +6,7 @@ module.exports = {
   },
 
   parserOptions: {
-    ecmaVersion: 2018,
+    ecmaVersion: 'latest',
     sourceType: 'module',
   },
 

packages/jsdoc-salty/README.md

@@ -18,11 +18,11 @@ risk. There's no real security risk, but it sure looks like there is.
 
 Also, TaffyDB [can't decide what license it uses](https://github.com/typicaljoe/taffydb/issues/166):
 
-+ The [README](https://github.com/typicaljoe/taffydb/blame/d4870cee370abffe510ba598b02e4e7ad6af5d2a/README.md#L146-L156)
+- The [README](https://github.com/typicaljoe/taffydb/blame/d4870cee370abffe510ba598b02e4e7ad6af5d2a/README.md#L146-L156)
   says that TaffyDB uses the [1-clause BSD License](https://opensource.org/licenses/BSD-1-Clause).
-+ The [`package.json` file](https://github.com/typicaljoe/taffydb/blob/d4870cee370abffe510ba598b02e4e7ad6af5d2a/package.json#L32)
+- The [`package.json` file](https://github.com/typicaljoe/taffydb/blob/d4870cee370abffe510ba598b02e4e7ad6af5d2a/package.json#L32)
   says that TaffyDB uses the [2-clause BSD License](https://opensource.org/licenses/BSD-2-Clause).
-+ The [`License` file](https://github.com/typicaljoe/taffydb/blob/d4870cee370abffe510ba598b02e4e7ad6af5d2a/License)
+- The [`License` file](https://github.com/typicaljoe/taffydb/blob/d4870cee370abffe510ba598b02e4e7ad6af5d2a/License)
   says that TaffyDB uses the [MIT License](https://opensource.org/licenses/MIT).
 
 By replacing TaffyDB with Salty, which uses the
@@ -177,4 +177,3 @@ employer to ignore a specific CVE. For those reasons, it was worth the trouble t
 ## What's with the name?
 
 It's a play on "saltwater taffy." Hilarious!
-

packages/jsdoc/cli.js

@@ -190,7 +190,11 @@ module.exports = (() => {
   };
 
   // TODO: docs
-  cli.runTests = () => require('./test')(dependencies);
+  cli.runTests = async () => {
+    const result = await require('./test')(dependencies);
+
+    return result.overallStatus === 'failed' ? 1 : 0;
+  };
 
   // TODO: docs
   cli.printVersion = () => {

packages/jsdoc/package.json

@@ -36,9 +36,6 @@
   "engines": {
     "node": ">=v18.12.0"
   },
-  "scripts": {
-    "test": "gulp"
-  },
   "bin": {
     "jsdoc": "jsdoc.js"
   },

packages/jsdoc/test/index.js

@@ -22,13 +22,14 @@ module.exports = (deps) => {
     },
   });
 
-  // Don't exit until the promise from jasmine.execute() is resolved.
-  jasmine.exitOnCompletion = false;
   // Treat an unhandled promise rejection as an error.
   process.on('unhandledRejection', (e) => {
     throw e;
   });
 
+  jasmine.clearReporters();
+  jasmine.addReporter(reporter);
+  jasmine.exitOnCompletion = false;
   jasmine.loadConfig({
     helpers: [
       'node_modules/jasmine-expect/index.js',
@@ -38,8 +39,6 @@ module.exports = (deps) => {
     random: false,
     stopSpecOnExpectationFailure: false,
   });
-  jasmine.env.clearReporters();
-  jasmine.addReporter(reporter);
 
   // Make dependencies available to all tests.
   if (!global.jsdoc) {