qunitx-cli 0.5.4 → 0.5.6

package/lib/commands/generate.js

@@ -4,7 +4,11 @@ import findProjectRoot from '../utils/find-project-root.js';
 import pathExists from '../utils/path-exists.js';
 import readBoilerplate from '../utils/read-boilerplate.js';
 
-export default async function () {
+/**
+ * Generates a new test file from the boilerplate template.
+ * @returns {Promise<void>}
+ */
+export default async function generateTestFiles() {
   const projectRoot = await findProjectRoot();
   const moduleName = process.argv[3]; // TODO: classify this maybe in future
   const path =
@@ -13,7 +17,8 @@ export default async function () {
       : `${projectRoot}/${process.argv[3]}.js`;
 
   if (await pathExists(path)) {
-    return console.log(`${path} already exists!`);
+    console.log(`${path} already exists!`);
+    return;
   }
 
   const testJSContent = await readBoilerplate('test.js');

package/lib/commands/help.js

@@ -4,7 +4,8 @@ import pkg from '../../package.json' with { type: 'json' };
 const highlight = (text) => kleur.magenta().bold(text);
 const color = (text) => kleur.blue(text);
 
-export default function () {
+/** Prints qunitx-cli usage information to stdout. */
+export default function displayHelpOutput() {
   const config = pkg;
 
   console.log(`${highlight('[qunitx v' + config.version + '] Usage:')} qunitx ${color('[targets] --$flags')}

package/lib/commands/init.js

@@ -2,10 +2,11 @@ import fs from 'node:fs/promises';
 import path from 'node:path';
 import findProjectRoot from '../utils/find-project-root.js';
 import pathExists from '../utils/path-exists.js';
-import defaultProjectConfigValues from '../boilerplates/default-project-config-values.js';
+import defaultProjectConfigValues from '../setup/default-project-config-values.js';
 import readBoilerplate from '../utils/read-boilerplate.js';
 
-export default async function () {
+/** Bootstraps a new qunitx project: writes the test HTML template, updates package.json, and optionally writes tsconfig.json. */
+export default async function initializeProject() {
   const projectRoot = await findProjectRoot();
   const oldPackageJSON = JSON.parse(await fs.readFile(`${projectRoot}/package.json`));
   const htmlPaths = process.argv.slice(2).reduce(

package/lib/commands/run/tests-in-browser.js

@@ -13,7 +13,10 @@ class BundleError extends Error {
   }
 }
 
-// Exported so run.js can pre-build all group bundles in parallel with Chrome startup.
+/**
+ * Pre-builds the esbuild bundle for all test files and caches the result in `cachedContent`.
+ * @returns {Promise<void>}
+ */
 export async function buildTestBundle(config, cachedContent) {
   const { projectRoot, output } = config;
   const allTestFilePaths = Object.keys(config.fsTree);
@@ -28,7 +31,7 @@ export async function buildTestBundle(config, cachedContent) {
       logLevel: 'error',
       outfile: `${projectRoot}/${output}/tests.js`,
       keepNames: true,
-      sourcemap: 'inline',
+      sourcemap: config.debug || config.watch ? 'inline' : false,
     }),
     Promise.all(
       cachedContent.htmlPathsToRunTests.map(async (htmlPath) => {
@@ -44,6 +47,10 @@ export async function buildTestBundle(config, cachedContent) {
   cachedContent.allTestCode = await fs.readFile(`${projectRoot}/${output}/tests.js`);
 }
 
+/**
+ * Runs the esbuild-bundled tests inside a Puppeteer-controlled browser page and streams TAP output.
+ * @returns {Promise<object>}
+ */
 export default async function runTestsInBrowser(
   config,
   cachedContent = {},
@@ -68,7 +75,7 @@ export default async function runTestsInBrowser(
 
     if (runHasFilter) {
       const outputPath = `${projectRoot}/${output}/filtered-tests.js`;
-      await buildFilteredTests(targetTestFilesToFilter, outputPath);
+      await buildFilteredTests(targetTestFilesToFilter, outputPath, config);
       cachedContent.filteredTestCode = (await fs.readFile(outputPath)).toString();
     }
 
@@ -117,7 +124,7 @@ export default async function runTestsInBrowser(
   return connections;
 }
 
-function buildFilteredTests(filteredTests, outputPath) {
+function buildFilteredTests(filteredTests, outputPath, config) {
   return esbuild.build({
     stdin: {
       contents: filteredTests.map((f) => `import "${f}";`).join(''),
@@ -126,7 +133,7 @@ function buildFilteredTests(filteredTests, outputPath) {
     bundle: true,
     logLevel: 'error',
     outfile: outputPath,
-    sourcemap: 'inline',
+    sourcemap: config.debug || config.watch ? 'inline' : false,
   });
 }
 

package/lib/commands/run.js

@@ -15,7 +15,11 @@ import TAPDisplayFinalResult from '../tap/display-final-result.js';
 import findChrome from '../utils/find-chrome.js';
 import readBoilerplate from '../utils/read-boilerplate.js';
 
-export default async function (config) {
+/**
+ * Runs qunitx tests in headless Chrome, either in watch mode or concurrent batch mode.
+ * @returns {Promise<void>}
+ */
+export default async function run(config) {
   const cachedContent = await buildCachedContent(config, config.htmlPaths);
 
   if (config.watch) {
@@ -88,6 +92,18 @@ export default async function (config) {
             '--disable-gpu',
             '--remote-debugging-port=0',
             '--window-size=1440,900',
+            '--disable-extensions',
+            '--disable-sync',
+            '--no-first-run',
+            '--disable-default-apps',
+            '--mute-audio',
+            '--disable-background-networking',
+            '--disable-background-timer-throttling',
+            '--disable-renderer-backgrounding',
+            '--disable-dev-shm-usage',
+            '--disable-translate',
+            '--metrics-recording-only',
+            '--disable-hang-monitor',
           ],
           executablePath: chromePath,
           headless: true,

package/lib/servers/http.js

@@ -1,7 +1,9 @@
 import http from 'node:http';
+// @deno-types="npm:@types/ws"
 import WebSocket, { WebSocketServer } from 'ws';
 import bindServerToPort from '../setup/bind-server-to-port.js';
 
+/** Map of file extensions to their corresponding MIME type strings. */
 export const MIME_TYPES = {
   html: 'text/html; charset=UTF-8',
   js: 'application/javascript',
@@ -13,7 +15,12 @@ export const MIME_TYPES = {
   svg: 'image/svg+xml',
 };
 
+/** Minimal HTTP + WebSocket server used to serve test bundles and push reload events. */
 export default class HTTPServer {
+  /**
+   * Creates and starts a plain `http.createServer` instance on the given port.
+   * @returns {Promise<object>}
+   */
   static serve(config = { port: 1234 }, handler) {
     const onListen = config.onListen || ((_server) => {});
     const onError = config.onError || ((_error) => {});
@@ -60,7 +67,7 @@ export default class HTTPServer {
         res.end(JSON.stringify(data));
       };
 
-      return this.handleRequest(req, res);
+      return this.#handleRequest(req, res);
     });
     this.wss = new WebSocketServer({ server: this._server });
     this.wss.on('error', (error) => {
@@ -69,14 +76,23 @@ export default class HTTPServer {
     });
   }
 
+  /**
+   * Closes the underlying HTTP server.
+   * @returns {object}
+   */
   close() {
     return this._server.close();
   }
 
+  /** Registers a GET route handler. */
   get(path, handler) {
-    this.registerRouteHandler('GET', path, handler);
+    this.#registerRouteHandler('GET', path, handler);
   }
 
+  /**
+   * Starts listening on the given port (0 = OS-assigned).
+   * @returns {Promise<void>}
+   */
   listen(port = 0, callback = () => {}) {
     return new Promise((resolve, reject) => {
       const onError = (err) => {
@@ -93,6 +109,7 @@ export default class HTTPServer {
     });
   }
 
+  /** Broadcasts a message to all connected WebSocket clients. */
   publish(data) {
     this.wss.clients.forEach((client) => {
       if (client.readyState === WebSocket.OPEN) {
@@ -101,23 +118,27 @@ export default class HTTPServer {
     });
   }
 
+  /** Registers a POST route handler. */
   post(path, handler) {
-    this.registerRouteHandler('POST', path, handler);
+    this.#registerRouteHandler('POST', path, handler);
   }
 
+  /** Registers a DELETE route handler. */
   delete(path, handler) {
-    this.registerRouteHandler('DELETE', path, handler);
+    this.#registerRouteHandler('DELETE', path, handler);
   }
 
+  /** Registers a PUT route handler. */
   put(path, handler) {
-    this.registerRouteHandler('PUT', path, handler);
+    this.#registerRouteHandler('PUT', path, handler);
   }
 
+  /** Adds a middleware function to the chain. */
   use(middleware) {
     this.middleware.push(middleware);
   }
 
-  registerRouteHandler(method, path, handler) {
+  #registerRouteHandler(method, path, handler) {
     if (!this.routes[method]) {
       this.routes[method] = {};
     }
@@ -125,22 +146,22 @@ export default class HTTPServer {
     this.routes[method][path] = {
       path,
       handler,
-      paramNames: this.extractParamNames(path),
+      paramNames: this.#extractParamNames(path),
       isWildcard: path === '/*',
     };
   }
 
-  handleRequest(req, res) {
+  #handleRequest(req, res) {
     const { method, url } = req;
     const urlObj = new URL(url, 'http://localhost');
     const pathname = urlObj.pathname;
     req.path = pathname;
     req.query = Object.fromEntries(urlObj.searchParams);
-    const matchingRoute = this.findRouteHandler(method, pathname);
+    const matchingRoute = this.#findRouteHandler(method, pathname);
 
     if (matchingRoute) {
-      req.params = this.extractParams(matchingRoute, pathname);
-      this.runMiddleware(req, res, matchingRoute.handler);
+      req.params = this.#extractParams(matchingRoute, pathname);
+      this.#runMiddleware(req, res, matchingRoute.handler);
     } else {
       res.statusCode = 404;
       res.setHeader('Content-Type', 'text/plain');
@@ -148,7 +169,7 @@ export default class HTTPServer {
     }
   }
 
-  runMiddleware(req, res, callback) {
+  #runMiddleware(req, res, callback) {
     let index = 0;
     const next = () => {
       if (index >= this.middleware.length) {
@@ -162,7 +183,7 @@ export default class HTTPServer {
     next();
   }
 
-  findRouteHandler(method, url) {
+  #findRouteHandler(method, url) {
     const routes = this.routes[method];
     if (!routes) {
       return null;
@@ -177,9 +198,9 @@ export default class HTTPServer {
           return false;
         }
 
-        if (isWildcard || this.matchPathSegments(path, url)) {
+        if (isWildcard || this.#matchPathSegments(path, url)) {
           if (route.paramNames.length > 0) {
-            const regexPattern = this.buildRegexPattern(path, route.paramNames);
+            const regexPattern = this.#buildRegexPattern(path, route.paramNames);
             const regex = new RegExp(`^${regexPattern}$`);
             const regexMatches = regex.exec(url);
             if (regexMatches) {
@@ -196,7 +217,7 @@ export default class HTTPServer {
     );
   }
 
-  matchPathSegments(path, url) {
+  #matchPathSegments(path, url) {
     const pathSegments = path.split('/');
     const urlSegments = url.split('/');
 
@@ -220,21 +241,21 @@ export default class HTTPServer {
     return true;
   }
 
-  buildRegexPattern(path, _paramNames) {
+  #buildRegexPattern(path, _paramNames) {
     let regexPattern = path.replace(/:[^/]+/g, '([^/]+)');
     regexPattern = regexPattern.replace(/\//g, '\\/');
 
     return regexPattern;
   }
 
-  extractParamNames(path) {
+  #extractParamNames(path) {
     const paramRegex = /:(\w+)/g;
     const paramMatches = path.match(paramRegex);
 
     return paramMatches ? paramMatches.map((match) => match.slice(1)) : [];
   }
 
-  extractParams(route, _url) {
+  #extractParams(route, _url) {
     const { paramNames, paramValues } = route;
     const params = {};
 

package/lib/setup/bind-server-to-port.js

@@ -1,3 +1,7 @@
+/**
+ * Binds an HTTPServer to an OS-assigned port and writes the resolved port back to `config.port`.
+ * @returns {Promise<object>}
+ */
 export default async function bindServerToPort(server, config) {
   await server.listen(0);
   config.port = server._server.address().port;

package/lib/setup/browser.js

@@ -3,6 +3,10 @@ import setupWebServer from './web-server.js';
 import bindServerToPort from './bind-server-to-port.js';
 import findChrome from '../utils/find-chrome.js';
 
+/**
+ * Launches a Puppeteer browser (or reuses an existing one), starts the web server, and returns the page/server/browser connection object.
+ * @returns {Promise<{server: object, browser: object, page: object}>}
+ */
 export default async function setupBrowser(
   config = {
     port: 1234,
@@ -24,6 +28,18 @@ export default async function setupBrowser(
             '--disable-gpu',
             '--remote-debugging-port=0',
             '--window-size=1440,900',
+            '--disable-extensions',
+            '--disable-sync',
+            '--no-first-run',
+            '--disable-default-apps',
+            '--mute-audio',
+            '--disable-background-networking',
+            '--disable-background-timer-throttling',
+            '--disable-renderer-backgrounding',
+            '--disable-dev-shm-usage',
+            '--disable-translate',
+            '--metrics-recording-only',
+            '--disable-hang-monitor',
           ],
           executablePath: await findChrome(),
           headless: true,

package/lib/setup/config.js

@@ -1,10 +1,14 @@
 import fs from 'node:fs/promises';
-import defaultProjectConfigValues from '../boilerplates/default-project-config-values.js';
+import defaultProjectConfigValues from './default-project-config-values.js';
 import findProjectRoot from '../utils/find-project-root.js';
 import setupFSTree from './fs-tree.js';
 import setupTestFilePaths from './test-file-paths.js';
 import parseCliFlags from '../utils/parse-cli-flags.js';
 
+/**
+ * Builds the merged qunitx config from package.json settings and CLI flags.
+ * @returns {Promise<object>}
+ */
 export default async function setupConfig() {
   const projectRoot = await findProjectRoot();
   const cliConfigFlags = parseCliFlags(projectRoot);

package/lib/setup/default-project-config-values.js

@@ -0,0 +1,7 @@
+/** Default qunitx config values: build output directory, test timeout (ms), fail-fast flag, and HTTP server port. */
+export default {
+  output: 'tmp',
+  timeout: 20000,
+  failFast: false,
+  port: 1234,
+};

package/lib/setup/file-watcher.js

@@ -1,6 +1,10 @@
 import chokidar from 'chokidar';
 import kleur from 'kleur';
 
+/**
+ * Starts chokidar watchers for each lookup path and calls `onEventFunc` on JS/TS file changes, debounced via a global flag.
+ * @returns {object}
+ */
 export default function setupFileWatchers(testFileLookupPaths, config, onEventFunc, onFinishFunc) {
   const extensions = ['js', 'ts'];
   const fileWatchers = testFileLookupPaths.reduce((watcher, watchPath) => {

package/lib/setup/fs-tree.js

@@ -1,7 +1,13 @@
 import fs from 'node:fs/promises';
+// @deno-types="npm:@types/picomatch"
 import picomatch from 'picomatch';
+// @deno-types="./recursive-lookup.d.ts"
 import recursiveLookup from 'recursive-lookup';
 
+/**
+ * Resolves an array of file paths, directories, or glob patterns into a flat `{ absolutePath: null }` map.
+ * @returns {Promise<object>}
+ */
 export default async function buildFSTree(fileAbsolutePaths, _config = {}) {
   const targetExtensions = ['js', 'ts'];
   const fsTree = {};

package/lib/setup/keyboard-events.js

@@ -2,6 +2,10 @@ import kleur from 'kleur';
 import listenToKeyboardKey from '../utils/listen-to-keyboard-key.js';
 import runTestsInBrowser from '../commands/run/tests-in-browser.js';
 
+/**
+ * Registers watch-mode keyboard shortcuts: `qq` to abort, `qa` to run all, `qf` for last failed, `ql` for last run.
+ * @returns {void}
+ */
 export default function setupKeyboardEvents(config, cachedContent, connections) {
   listenToKeyboardKey('qq', () => abortBrowserQUnit(config, connections));
   listenToKeyboardKey('qa', () => {

package/lib/setup/recursive-lookup.d.ts

@@ -0,0 +1,7 @@
+/** Recursively lists files under `folderPath`, optionally filtered by a predicate. */
+declare function recursiveLookup(
+  folderPath: string,
+  filter?: (name: string) => boolean,
+): Promise<string[]>;
+
+export default recursiveLookup;

package/lib/setup/test-file-paths.js

@@ -1,5 +1,10 @@
+// @deno-types="npm:@types/picomatch"
 import picomatch from 'picomatch';
 
+/**
+ * Deduplicates a list of file, folder, and glob inputs so that more-specific paths covered by broader ones are removed.
+ * @returns {string[]}
+ */
 export default function setupTestFilePaths(_projectRoot, inputs) {
   // NOTE: very complex algorithm, order is very important
   const [folders, filesWithGlob, filesWithoutGlob] = inputs.reduce(

package/lib/setup/web-server.js

@@ -7,6 +7,10 @@ import HTTPServer, { MIME_TYPES } from '../servers/http.js';
 
 const fsPromise = fs.promises;
 
+/**
+ * Creates and returns an HTTPServer with routes for the test HTML, filtered test page, and static assets, plus a WebSocket handler that streams TAP events.
+ * @returns {object}
+ */
 export default function setupWebServer(
   config = {
     port: 1234,
@@ -246,16 +250,12 @@ function testRuntimeToInject(port, config) {
       });
       window.QUnit.done((details) => {
         if (window.IS_PUPPETEER) {
-          window.setTimeout(() => {
-            window.socket.send(JSON.stringify({ event: 'done', details: details, abort: window.abortQUnit }, getCircularReplacer()))
-          }, 50);
+          window.socket.send(JSON.stringify({ event: 'done', details: details, abort: window.abortQUnit }, getCircularReplacer()));
         }
-        window.setTimeout(() => {
-          window.testTimeout = ${config.timeout};
-        }, 75);
+        window.testTimeout = ${config.timeout};
       });
 
-      window.setTimeout(() => window.QUnit.start(), 25);
+      window.QUnit.start();
     }
   </script>`;
 }

package/lib/setup/write-output-static-files.js

@@ -1,5 +1,9 @@
 import fs from 'node:fs/promises';
 
+/**
+ * Copies static HTML files and referenced assets from the project into the configured output directory.
+ * @returns {Promise<void>}
+ */
 export default async function writeOutputStaticFiles({ projectRoot, output }, cachedContent) {
   const staticHTMLPromises = Object.keys(cachedContent.staticHTMLs).map(async (staticHTMLKey) => {
     const htmlRelativePath = staticHTMLKey.replace(`${projectRoot}/`, '');

package/lib/tap/display-final-result.js

@@ -1,4 +1,11 @@
-export default function ({ testCount, passCount, skipCount, failCount }, timeTaken) {
+/**
+ * Prints the TAP plan line and test-run summary (total, pass, skip, fail, duration).
+ * @returns {void}
+ */
+export default function TAPDisplayFinalResult(
+  { testCount, passCount, skipCount, failCount },
+  timeTaken,
+) {
   console.log('');
   console.log(`1..${testCount}`);
   console.log(`# tests ${testCount}`);

package/lib/tap/display-test-result.js

@@ -1,9 +1,14 @@
+// @deno-types="npm:@types/js-yaml"
 import yaml from 'js-yaml';
 import indentString from '../utils/indent-string.js';
 
 // tape TAP output: ['operator', 'stack', 'at', 'expected', 'actual']
 // ava TAP output: ['message', 'name', 'at', 'assertion', 'values'] // Assertion #5, message
-export default function (COUNTER, details) {
+/**
+ * Formats and prints a single QUnit testEnd event as a TAP `ok`/`not ok` line with optional YAML failure block.
+ * @returns {void}
+ */
+export default function TAPDisplayTestResult(COUNTER, details) {
   // NOTE: https://github.com/qunitjs/qunit/blob/master/src/html-reporter/diff.js
   COUNTER.testCount++;
 

package/lib/utils/find-chrome.js

@@ -2,6 +2,10 @@ import { exec } from 'node:child_process';
 
 const CANDIDATES = ['google-chrome-stable', 'google-chrome', 'chromium', 'chromium-browser'];
 
+/**
+ * Resolves the Chrome/Chromium executable path from `CHROME_BIN` or by probing common binary names.
+ * @returns {Promise<string|null>}
+ */
 export default function findChrome() {
   if (process.env.CHROME_BIN) return Promise.resolve(process.env.CHROME_BIN);
 

package/lib/utils/find-internal-assets-from-html.js

@@ -2,6 +2,10 @@ import { load } from 'cheerio';
 
 const ABSOLUTE_URL_REGEX = new RegExp('^(?:[a-z]+:)?//', 'i');
 
+/**
+ * Parses an HTML string and returns all internal (non-absolute-URL) `<script src>` and `<link href>` paths.
+ * @returns {string[]}
+ */
 export default function findInternalAssetsFromHTML(htmlContent) {
   const $ = load(htmlContent);
   const internalJSFiles = $('script[src]')

package/lib/utils/find-project-root.js

@@ -1,7 +1,11 @@
 import process from 'node:process';
 import searchInParentDirectories from './search-in-parent-directories.js';
 
-export default async function () {
+/**
+ * Walks up parent directories from `cwd` to find the nearest `package.json` and returns its directory path.
+ * @returns {Promise<string>}
+ */
+export default async function findProjectRoot() {
   try {
     const absolutePath = await searchInParentDirectories('.', 'package.json');
     if (!absolutePath.includes('package.json')) {

package/lib/utils/indent-string.js

@@ -1,3 +1,12 @@
+/**
+ * Prepends `count` repetitions of `indent` (default: one space) to each non-empty line of `string`.
+ * @example
+ * ```js
+ * import indentString from './lib/utils/indent-string.js';
+ * console.assert(indentString('hello\nworld', 2) === '  hello\n  world');
+ * ```
+ * @returns {string}
+ */
 export default function indentString(string, count = 1, options = {}) {
   const { indent = ' ', includeEmptyLines = false } = options;
 

package/lib/utils/listen-to-keyboard-key.js

@@ -5,6 +5,10 @@ const targetInputs = {};
 const inputs = [];
 let listenerAdded = false;
 
+/**
+ * Registers a stdin listener that fires `closure` when the user types `inputString` (case-insensitive by default).
+ * @returns {void}
+ */
 export default function listenToKeyboardKey(
   inputString,
   closure,

package/lib/utils/parse-cli-flags.js

@@ -1,5 +1,9 @@
 // { inputs: [], debug: true, watch: true, failFast: true, htmlPaths: [], output }
-export default function (projectRoot) {
+/**
+ * Parses `process.argv` into a qunitx flag object (`inputs`, `debug`, `watch`, `failFast`, `timeout`, `output`, `port`, `before`, `after`).
+ * @returns {object}
+ */
+export default function parseCliFlags(projectRoot) {
   const providedFlags = process.argv.slice(2).reduce(
     (result, arg) => {
       if (arg.startsWith('--debug')) {

package/lib/utils/path-exists.js

@@ -1,5 +1,15 @@
 import fs from 'node:fs/promises';
 
+/**
+ * Returns `true` if the given filesystem path is accessible, `false` otherwise.
+ * @example
+ * ```js
+ * import pathExists from './lib/utils/path-exists.js';
+ * console.assert(await pathExists('/tmp') === true);
+ * console.assert(await pathExists('/tmp/nonexistent-qunitx-file') === false);
+ * ```
+ * @returns {Promise<boolean>}
+ */
 export default async function pathExists(path) {
   try {
     await fs.access(path);

package/lib/utils/read-boilerplate.js

@@ -1,11 +1,15 @@
-import { isSea, getAsset } from 'node:sea';
 import fs from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
+/**
+ * Reads a boilerplate file by relative path, using the SEA asset store when running as a Node.js binary.
+ * @returns {Promise<string>}
+ */
 export default async function readBoilerplate(relativePath) {
-  if (isSea()) return getAsset(relativePath, 'utf8');
-  return (await fs.readFile(join(__dirname, '../boilerplates', relativePath))).toString();
+  const sea = await import('node:sea').catch(() => null);
+  if (sea?.isSea()) return sea.getAsset(relativePath, 'utf8');
+  return (await fs.readFile(join(__dirname, '../../templates', relativePath))).toString();
 }

package/lib/utils/resolve-port-number-for.js

@@ -1,3 +1,7 @@
+/**
+ * Returns `portNumber` if it is free, otherwise recursively tries `portNumber + 1` until a free port is found.
+ * @returns {Promise<number>}
+ */
 export default async function resolvePortNumberFor(portNumber) {
   if (await portIsAvailable(portNumber)) {
     return portNumber;

package/lib/utils/run-user-module.js

@@ -1,5 +1,9 @@
 import kleur from 'kleur';
 
+/**
+ * Dynamically imports `modulePath` and calls its default export with `params`; exits with code 1 on error.
+ * @returns {Promise<void>}
+ */
 export default async function runUserModule(modulePath, params, scriptPosition) {
   try {
     const func = await import(modulePath);