libdragon 10.7.1 → 10.8.1

package/modules/actions/utils.js

@@ -21,6 +21,9 @@ const {
 const { dockerHostUserParams } = require('./docker-utils');
 const { installNPMDependencies } = require('./npm-utils');
 
+/**
+ * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ */
 const installDependencies = async (libdragonInfo) => {
   const buildScriptPath = path.join(
     libdragonInfo.root,
@@ -51,9 +54,8 @@ const installDependencies = async (libdragonInfo) => {
 /**
  * Downloads the given docker image. Returns false if the local image is the
  * same, new image name otherwise.
- * @param libdragonInfo
- * @param newImageName
- * @returns false | string
+ * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ * @param {string} newImageName
  */
 const updateImage = async (libdragonInfo, newImageName) => {
   // Will not take too much time if already have the same
@@ -90,6 +92,9 @@ const updateImage = async (libdragonInfo, newImageName) => {
   return newImageName;
 };
 
+/**
+ * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ */
 const destroyContainer = async (libdragonInfo) => {
   if (libdragonInfo.containerId) {
     await spawnProcess('docker', [
@@ -110,39 +115,50 @@ const destroyContainer = async (libdragonInfo) => {
  * Invokes host git with provided params. If host does not have git, falls back
  * to the docker git, with the nix user set to the user running libdragon.
  */
-async function runGitMaybeHost(libdragonInfo, params) {
+
+/**
+ *
+ * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ * @param {string[]} params
+ * @param {import('../helpers').SpawnOptions} options
+ * @returns
+ */
+async function runGitMaybeHost(libdragonInfo, params, options = {}) {
   assert(
     libdragonInfo.vendorStrategy !== 'manual',
     new Error('Should never run git if vendoring strategy is manual.')
   );
   try {
     const isWin = /^win/.test(process.platform);
-    await spawnProcess(
+    return await spawnProcess(
       'git',
       ['-C', libdragonInfo.root, ...params],
       // Windows git is breaking the TTY somehow - disable TTY for now
       // We are not able to display progress for the initial clone b/c of this
       // Enable progress otherwise.
       isWin
-        ? { inheritStdin: false }
-        : { inheritStdout: true, inheritStderr: true }
+        ? { inheritStdin: false, ...options }
+        : { inheritStdout: true, inheritStderr: true, ...options }
     );
   } catch (e) {
     if (e instanceof CommandError) {
       throw e;
     }
 
-    await dockerExec(
+    return await dockerExec(
       libdragonInfo,
       // Use the host user when initializing git as we will need access
       [...dockerHostUserParams(libdragonInfo)],
       ['git', ...params],
       // Let's enable tty here to show the progress
-      { inheritStdout: true, inheritStderr: true }
+      { inheritStdout: true, inheritStderr: true, ...options }
     );
   }
 }
 
+/**
+ * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ */
 async function checkContainerAndClean(libdragonInfo) {
   const id =
     libdragonInfo.containerId &&
@@ -169,6 +185,9 @@ async function checkContainerAndClean(libdragonInfo) {
   return id ? libdragonInfo.containerId : undefined;
 }
 
+/**
+ * @param {string} containerId
+ */
 async function checkContainerRunning(containerId) {
   const running = (
     await spawnProcess('docker', [
@@ -181,6 +200,9 @@ async function checkContainerRunning(containerId) {
   return running ? containerId : undefined;
 }
 
+/**
+ * @param {import('../project-info').LibdragonInfo} libdragonInfo
+ */
 async function initGitAndCacheContainerId(libdragonInfo) {
   // If there is managed vendoring, make sure we have a git repo. `git init` is
   // safe anyways...

package/modules/actions/version.js

@@ -5,13 +5,13 @@ const printVersion = async () => {
   log(`libdragon-cli v${version}`);
 };
 
-module.exports = {
+module.exports = /** @type {const} */ ({
   name: 'version',
   fn: printVersion,
-  mustHaveProject: false,
+  forwardsRestParams: false,
   usage: {
     name: 'version',
     summary: 'Display cli version.',
     description: `Displays currently running cli version.`,
   },
-};
+});

package/modules/constants.js

@@ -1,4 +1,4 @@
-module.exports = {
+module.exports = /** @type {const} */ ({
   DOCKER_HUB_IMAGE: 'ghcr.io/dragonminded/libdragon:latest',
   LIBDRAGON_GIT: 'https://github.com/DragonMinded/libdragon',
   LIBDRAGON_BRANCH: 'trunk',
@@ -9,6 +9,8 @@ module.exports = {
   CONFIG_FILE: 'config.json',
   DEFAULT_STRATEGY: 'submodule',
 
+  ACCEPTED_STRATEGIES: ['submodule', 'subtree', 'manual'],
+
   // cli exit codes
   STATUS_OK: 0,
   STATUS_ERROR: 1,
@@ -16,4 +18,4 @@ module.exports = {
   STATUS_VALIDATION_ERROR: 4,
 
   IMAGE_FILE: 'docker-image', // deprecated
-};
+});

package/modules/helpers.js

@@ -6,31 +6,86 @@ const { spawn } = require('child_process');
 
 const { globals } = require('./globals');
 
-// An error caused by a command explicitly run by the user
+/**
+ * A structure to keep additional error information
+ * @typedef {Object} ErrorState
+ * @property {number} code
+ * @property {string} out
+ * @property {boolean} userCommand
+ */
+
+/**
+ * An error caused by a command exiting with a non-zero exit code
+ * @class
+ */
 class CommandError extends Error {
+  /**
+   * @param {string} message Error message to report
+   * @param {ErrorState} errorState
+   */
   constructor(message, { code, out, userCommand }) {
     super(message);
+
+    /**
+     * Exit code
+     * @type {number}
+     * @public
+     */
     this.code = code;
+
+    /**
+     * Error output as a single concatanated string
+     * @type {string}
+     * @public
+     */
     this.out = out;
+
+    /**
+     * true when the error caused by a command explicitly run by the end user
+     * @type {boolean}
+     * @public
+     */
     this.userCommand = userCommand;
   }
 }
 
-// The user provided an unexpected input
+/**
+ * An error caused by the user providing an unexpected input
+ * @class
+ */
 class ParameterError extends Error {
+  /**
+   * @param {string} message Error message to report
+   * @param {string} actionName
+   */
   constructor(message, actionName) {
     super(message);
+
+    /**
+     * true when the error caused by a command explicitly run by the end user
+     * @type {string}
+     * @public
+     */
     this.actionName = actionName;
   }
 }
 
-// Something was not as expected to continue the operation
+/**
+ * Something was not as expected to continue the operation
+ * @class
+ */
 class ValidationError extends Error {
+  /**
+   * @param {string} message
+   */
   constructor(message) {
     super(message);
   }
 }
 
+/**
+ * @param {string} path
+ */
 async function fileExists(path) {
   return fs
     .stat(path)
@@ -41,6 +96,9 @@ async function fileExists(path) {
     });
 }
 
+/**
+ * @param {string} path
+ */
 async function dirExists(path) {
   return fs
     .stat(path)
@@ -51,9 +109,27 @@ async function dirExists(path) {
     });
 }
 
+/**
+ * @typedef {{
+ *  userCommand?: boolean,
+ *  inheritStdin?: boolean,
+ *  inheritStdout?: boolean,
+ *  inheritStderr?: boolean,
+ *  spawnOptions?: import('child_process').SpawnOptions,
+ *  stdin?: fsClassic.ReadStream,
+ * }} SpawnOptions
+ */
+
 // A simple Promise wrapper for child_process.spawn. Return the err/out streams
 // from the process by default. Specify inheritStdout / inheritStderr to disable
 // this and inherit the parent process's stream, passing through the TTY if any.
+/**
+ *
+ * @param {string} cmd
+ * @param {string[]} params
+ * @param {SpawnOptions} options
+ * @returns {Promise<string>}
+ */
 function spawnProcess(
   cmd,
   params = [],
@@ -81,7 +157,10 @@ function spawnProcess(
   }
 ) {
   return new Promise((resolve, reject) => {
+    /** @type {Buffer[]} */
     const stdout = [];
+
+    /** @type {Buffer[]} */
     const stderr = [];
 
     log(chalk.grey(`Spawning: ${cmd} ${params.join(' ')}`), true);
@@ -102,6 +181,9 @@ function spawnProcess(
     // See a very old related issue: https://github.com/nodejs/node/issues/947
     // When the stream is not fully consumed by the pipe target and it exits,
     // an EPIPE or EOF is thrown. We don't care about those.
+    /**
+     * @param {Error & {code: string}} err
+     */
     const eatEpipe = (err) => {
       if (err.code !== 'EPIPE' && err.code !== 'EOF') {
         throw err;
@@ -140,11 +222,17 @@ function spawnProcess(
       });
     }
 
+    /**
+     * @param {Error} err
+     */
     const errorHandler = (err) => {
       command.off('close', closeHandler);
       reject(err);
     };
 
+    /**
+     * @param {number} code
+     */
     const closeHandler = function (code) {
       // The stream was fully consumed, if there is this an additional error on
       // stdout, it must be a legitimate error
@@ -170,9 +258,21 @@ function spawnProcess(
   });
 }
 
-function dockerExec(libdragonInfo, dockerParams, cmdWithParams, options) {
+/**
+ * @typedef {{
+ * (libdragonInfo: import('./project-info').LibdragonInfo, dockerParams: string[], cmdWithParams: string[], options?: SpawnOptions): Promise<string>;
+ * (libdragonInfo: import('./project-info').LibdragonInfo, cmdWithParams: string[], options?: SpawnOptions, unused?: unknown): Promise<string>;
+ * }} DockerExec
+ */
+const dockerExec = /** @type {DockerExec} */ function (
+  libdragonInfo,
+  dockerParams,
+  cmdWithParams,
+  /** @type {SpawnOptions} */
+  options
+) {
   assert(
-    libdragonInfo.containerId,
+    !!libdragonInfo.containerId,
     new Error('Trying to invoke dockerExec without a containerId.')
   );
 
@@ -181,7 +281,7 @@ function dockerExec(libdragonInfo, dockerParams, cmdWithParams, options) {
     Array.isArray(dockerParams) && Array.isArray(cmdWithParams);
 
   if (!haveDockerParams) {
-    options = cmdWithParams;
+    options = /** @type {SpawnOptions} */ (cmdWithParams);
   }
 
   const additionalParams = [];
@@ -215,10 +315,12 @@ function dockerExec(libdragonInfo, dockerParams, cmdWithParams, options) {
     ],
     options
   );
-}
+};
 
 /**
  * Recursively copies directories and files
+ * @param {string} src
+ * @param {string} dst
  */
 async function copyDirContents(src, dst) {
   log(`Copying from ${src} to ${dst}`, true);
@@ -269,14 +371,24 @@ async function copyDirContents(src, dst) {
   );
 }
 
+/**
+ * @param {string} p
+ */
 function toPosixPath(p) {
   return p.replace(new RegExp('\\' + path.sep, 'g'), path.posix.sep);
 }
 
+/**
+ * @param {string} p
+ */
 function toNativePath(p) {
   return p.replace(new RegExp('\\' + path.posix.sep, 'g'), path.sep);
 }
 
+/**
+ * @param {boolean} condition
+ * @param {Error} error
+ */
 function assert(condition, error) {
   if (!condition) {
     error.message = `[ASSERTION FAILED] ${error.message}`;
@@ -284,12 +396,19 @@ function assert(condition, error) {
   }
 }
 
+/**
+ * @param {string} text
+ */
 function print(text) {
   // eslint-disable-next-line no-console
   console.log(text);
   return;
 }
 
+/**
+ * @param {string} text
+ * @param {boolean} verboseOnly
+ */
 function log(text, verboseOnly = false) {
   if (!verboseOnly) {
     // eslint-disable-next-line no-console

package/modules/parameters.js

@@ -2,10 +2,31 @@ const chalk = require('chalk').stderr;
 
 const { log } = require('./helpers');
 const actions = require('./actions');
-const { STATUS_BAD_PARAM } = require('./constants');
+const { STATUS_BAD_PARAM, ACCEPTED_STRATEGIES } = require('./constants');
 const { globals } = require('./globals');
 
+/** @typedef { import('./actions') } Actions */
+
+/** @typedef { typeof import('./constants').ACCEPTED_STRATEGIES[number] } VendorStrategy */
+
+/**
+ * @template {keyof Actions} [T=keyof Actions]
+ * @typedef {{
+ *  EXTRA_PARAMS: string[];
+ *  CURRENT_ACTION: Actions[T];
+ *  VERBOSE?: boolean;
+ *  DOCKER_IMAGE?: string;
+ *  VENDOR_DIR?: string;
+ *  VENDOR_STRAT?: VendorStrategy;
+ *  FILE?: string;
+ * }} CommandlineOptions
+ */
+
+/**
+ * @param {string[]} argv
+ */
 const parseParameters = async (argv) => {
+  /** @type CommandlineOptions */
   const options = {
     EXTRA_PARAMS: [],
     CURRENT_ACTION: undefined,
@@ -38,12 +59,19 @@ const parseParameters = async (argv) => {
     }
 
     if (['--strategy', '-s'].includes(val)) {
-      options.VENDOR_STRAT = argv[++i];
+      options.VENDOR_STRAT = /** @type VendorStrategy */ (argv[++i]);
       continue;
     } else if (val.indexOf('--strategy=') === 0) {
-      options.VENDOR_STRAT = val.split('=')[1];
+      options.VENDOR_STRAT = /** @type VendorStrategy */ (val.split('=')[1]);
       continue;
     }
+    if (
+      options.VENDOR_STRAT &&
+      !ACCEPTED_STRATEGIES.includes(options.VENDOR_STRAT)
+    ) {
+      log(chalk.red(`Invalid strategy \`${options.VENDOR_STRAT}\``));
+      process.exit(STATUS_BAD_PARAM);
+    }
 
     if (['--file', '-f'].includes(val)) {
       options.FILE = argv[++i];
@@ -63,7 +91,7 @@ const parseParameters = async (argv) => {
       process.exit(STATUS_BAD_PARAM);
     }
 
-    options.CURRENT_ACTION = actions[val];
+    options.CURRENT_ACTION = actions[/** @type {keyof Actions} */ (val)];
 
     if (!options.CURRENT_ACTION) {
       log(chalk.red(`Invalid action \`${val}\``));
@@ -90,8 +118,12 @@ const parseParameters = async (argv) => {
   }
 
   if (
-    ![actions.init, actions.install, actions.update].includes(
-      options.CURRENT_ACTION
+    !(
+      /** @type {typeof actions[keyof actions][]} */ ([
+        actions.init,
+        actions.install,
+        actions.update,
+      ]).includes(options.CURRENT_ACTION)
     ) &&
     options.DOCKER_IMAGE
   ) {
@@ -100,14 +132,13 @@ const parseParameters = async (argv) => {
   }
 
   if (
-    options.VENDOR_STRAT &&
-    !['submodule', 'subtree', 'manual'].includes(options.VENDOR_STRAT)
+    !(
+      /** @type {typeof actions[keyof actions][]} */ ([
+        actions.disasm,
+      ]).includes(options.CURRENT_ACTION)
+    ) &&
+    options.FILE
   ) {
-    log(chalk.red(`Invalid strategy \`${options.VENDOR_STRAT}\``));
-    process.exit(STATUS_BAD_PARAM);
-  }
-
-  if (![actions.disasm].includes(options.CURRENT_ACTION) && options.FILE) {
     log(chalk.red('Invalid flag: file'));
     process.exit(STATUS_BAD_PARAM);
   }

package/modules/project-info.js

@@ -29,9 +29,36 @@ const {
   ParameterError,
 } = require('./helpers');
 
-const initAction = require('./actions/init');
-const destroyAction = require('./actions/destroy');
+// These do not need a project to exist.
+const NO_PROJECT_ACTIONS = /** @type {const} */ (['help', 'version']);
 
+/**
+ * @typedef { typeof NO_PROJECT_ACTIONS[number] } ActionsNoProject
+ * @typedef { Exclude<keyof import('./parameters').Actions, ActionsNoProject> } ActionsWithProject
+ * @typedef { import('./parameters').CommandlineOptions<ActionsNoProject> } ActionsNoProjectOptions
+ * @typedef { import('./parameters').CommandlineOptions<ActionsWithProject> } ActionsWithProjectOptions
+ *
+ * @typedef { {
+ *  options: ActionsNoProjectOptions
+ * } } CLIInfo
+ *
+ * @typedef { {
+ *  root: string;
+ *  userInfo: os.UserInfo<string>;
+ *  haveProjectConfig: boolean;
+ *  imageName: string;
+ *  vendorDirectory: string;
+ *  vendorStrategy: import('./parameters').VendorStrategy;
+ *  containerId: string
+ * } } ExtendedInfo
+ *
+ * @typedef { CLIInfo & Partial<ExtendedInfo> } LibdragonInfo
+ */
+
+/**
+ * @param {LibdragonInfo} libdragonInfo
+ * @returns string
+ */
 async function findContainerId(libdragonInfo) {
   const idFile = path.join(libdragonInfo.root, '.git', CACHED_CONTAINER_FILE);
   if (await fileExists(idFile)) {
@@ -66,17 +93,24 @@ async function findContainerId(libdragonInfo) {
     const idIndex = str.indexOf(shortId);
     const longId = str.slice(idIndex, idIndex + 64);
     if (longId.length === 64) {
-      const newInfo = { ...libdragonInfo, containerId: longId };
       // This shouldn't happen but if the user somehow deleted the .git folder
       // (we don't have the container id file at this point) we can recover the
       // project. `git init` is safe anyways and it is not executed if strategy
       // is `manual`
-      await initGitAndCacheContainerId(newInfo);
+      await initGitAndCacheContainerId({
+        ...libdragonInfo,
+        containerId: longId,
+      });
       return longId;
     }
   }
 }
 
+/**
+ * @param {string} start
+ * @param {string} relativeFile
+ * @return {Promise<string>}
+ */
 async function findLibdragonRoot(
   start = '.',
   relativeFile = path.join(LIBDRAGON_PROJECT_MANIFEST, CONFIG_FILE)
@@ -104,18 +138,19 @@ async function findGitRoot() {
   }
 }
 
-async function readProjectInfo(info) {
+/**
+ * @param {LibdragonInfo} optionInfo
+ */
+const readProjectInfo = async function (optionInfo) {
   // No need to do anything here if the action does not depend on the project
   // The only exception is the init and destroy actions, which do not need an
   // existing project but readProjectInfo must always run to analyze the situation
-  const forceReadProjectInfo = [initAction, destroyAction].includes(
-    info.options.CURRENT_ACTION
-  );
   if (
-    info.options.CURRENT_ACTION.mustHaveProject === false &&
-    !forceReadProjectInfo
+    NO_PROJECT_ACTIONS.includes(
+      /** @type {ActionsNoProject} */ (optionInfo.options.CURRENT_ACTION.name)
+    )
   ) {
-    return info;
+    return /** @type {CLIInfo} */ (optionInfo);
   }
 
   const migratedRoot = await findLibdragonRoot();
@@ -128,15 +163,19 @@ async function readProjectInfo(info) {
       path.join(LIBDRAGON_PROJECT_MANIFEST, IMAGE_FILE)
     ));
 
-  if (!projectRoot && !forceReadProjectInfo) {
+  if (
+    !projectRoot &&
+    !['init', 'destroy'].includes(optionInfo.options.CURRENT_ACTION.name)
+  ) {
     throw new ParameterError(
       'This is not a libdragon project. Initialize with `libdragon init` first.',
-      info.options.CURRENT_ACTION.name
+      optionInfo.options.CURRENT_ACTION.name
     );
   }
 
-  info = {
-    ...info,
+  /** @type {LibdragonInfo} */
+  let info = {
+    ...optionInfo,
     root: projectRoot ?? (await findNPMRoot()) ?? (await findGitRoot()),
     userInfo: os.userInfo(),
 
@@ -209,10 +248,10 @@ async function readProjectInfo(info) {
   log(`Active vendor strategy: ${info.vendorStrategy}`, true);
 
   return info;
-}
+};
 
 /**
- * @param info This is only the base info without options
+ * @param { LibdragonInfo | void } info This is only the base info without options
  * fn and command line options
  */
 async function writeProjectInfo(info) {