@appium/support 7.0.4 → 7.0.6

package/lib/{node.js → node.ts}

@@ -2,58 +2,29 @@ import {isWindows} from './system';
 import log from './logger';
 import _ from 'lodash';
 import {exec} from 'teen_process';
-import path from 'path';
-import _fs from 'fs';
+import path from 'node:path';
+import _fs from 'node:fs';
 import {v4 as uuidV4} from 'uuid';
 
-const ECMA_SIZES = Object.freeze({
-  STRING: 2,
-  BOOLEAN: 4,
-  NUMBER: 8,
-});
-
-/**
- * Internal utility to link global package to local context
- *
- * @param {string} packageName - name of the package to link
- * @throws {Error} If the command fails
- */
-async function linkGlobalPackage(packageName) {
-  try {
-    log.debug(`Linking package '${packageName}'`);
-    const cmd = isWindows() ? 'npm.cmd' : 'npm';
-    await exec(cmd, ['link', packageName], {timeout: 20000});
-  } catch (err) {
-    const msg = `Unable to load package '${packageName}', linking failed: ${err.message}`;
-    log.debug(msg);
-    if (err.stderr) {
-      // log the stderr if there, but do not add to thrown error as it is
-      // _very_ verbose
-      log.debug(err.stderr);
-    }
-    throw new Error(msg);
-  }
-}
+const OBJECTS_MAPPING = new WeakMap<object, string>();
 
 /**
  * Utility function to extend node functionality, allowing us to require
  * modules that are installed globally. If the package cannot be required,
  * this will attempt to link the package and then re-require it
  *
- * @param {string} packageName - the name of the package to be required
- * @returns {Promise<unknown>} - the package object
+ * @param packageName - the name of the package to be required
+ * @returns The package object
  * @throws {Error} If the package is not found locally or globally
  */
-async function requirePackage(packageName) {
-  // first, get it in the normal way (see https://nodejs.org/api/modules.html#modules_all_together)
+export async function requirePackage(packageName: string): Promise<unknown> {
   try {
     log.debug(`Loading local package '${packageName}'`);
     return require(packageName);
   } catch (err) {
-    log.debug(`Failed to load local package '${packageName}': ${err.message}`);
+    log.debug(`Failed to load local package '${packageName}': ${(err as Error).message}`);
   }
 
-  // second, get it from where it ought to be in the global node_modules
   try {
     const globalPackageName = path.resolve(
       process.env.npm_config_prefix ?? '',
@@ -64,112 +35,45 @@ async function requirePackage(packageName) {
     log.debug(`Loading global package '${globalPackageName}'`);
     return require(globalPackageName);
   } catch (err) {
-    log.debug(`Failed to load global package '${packageName}': ${err.message}`);
+    log.debug(`Failed to load global package '${packageName}': ${(err as Error).message}`);
   }
 
-  // third, link the file and get locally
   try {
     await linkGlobalPackage(packageName);
     log.debug(`Retrying load of linked package '${packageName}'`);
     return require(packageName);
   } catch (err) {
-    throw log.errorWithException(`Unable to load package '${packageName}': ${err.message}`);
-  }
-}
-
-function extractAllProperties(obj) {
-  const stringProperties = [];
-  for (const prop in obj) {
-    stringProperties.push(prop);
-  }
-  if (_.isFunction(Object.getOwnPropertySymbols)) {
-    stringProperties.push(...Object.getOwnPropertySymbols(obj));
-  }
-  return stringProperties;
-}
-
-function _getSizeOfObject(seen, object) {
-  if (_.isNil(object)) {
-    return 0;
-  }
-
-  let bytes = 0;
-  const properties = extractAllProperties(object);
-  for (const key of properties) {
-    // Do not recalculate circular references
-    if (typeof object[key] === 'object' && !_.isNil(object[key])) {
-      if (seen.has(object[key])) {
-        continue;
-      }
-      seen.add(object[key]);
-    }
-
-    bytes += getCalculator(seen)(key);
-    try {
-      bytes += getCalculator(seen)(object[key]);
-    } catch (ex) {
-      if (ex instanceof RangeError) {
-        // circular reference detected, final result might be incorrect
-        // let's be nice and not throw an exception
-        bytes = 0;
-      }
-    }
+    throw log.errorWithException(
+      `Unable to load package '${packageName}': ${(err as Error).message}`
+    );
   }
-
-  return bytes;
-}
-
-function getCalculator(seen) {
-  return function calculator(obj) {
-    if (_.isBuffer(obj)) {
-      return obj.length;
-    }
-
-    switch (typeof obj) {
-      case 'string':
-        return obj.length * ECMA_SIZES.STRING;
-      case 'boolean':
-        return ECMA_SIZES.BOOLEAN;
-      case 'number':
-        return ECMA_SIZES.NUMBER;
-      case 'symbol':
-        return _.isFunction(Symbol.keyFor) && Symbol.keyFor(obj)
-          ? /** @type {string} */ (Symbol.keyFor(obj)).length * ECMA_SIZES.STRING
-          : (obj.toString().length - 8) * ECMA_SIZES.STRING;
-      case 'object':
-        return _.isArray(obj)
-          ? obj.map(getCalculator(seen)).reduce((acc, curr) => acc + curr, 0)
-          : _getSizeOfObject(seen, obj);
-      default:
-        return 0;
-    }
-  };
 }
 
 /**
  * Calculate the in-depth size in memory of the provided object.
  * The original implementation is borrowed from https://github.com/miktam/sizeof.
  *
- * @param {*} obj An object whose size should be calculated
- * @returns {number} Object size in bytes.
+ * @param obj - An object whose size should be calculated
+ * @returns Object size in bytes.
  */
-function getObjectSize(obj) {
+export function getObjectSize(obj: unknown): number {
   return getCalculator(new WeakSet())(obj);
 }
 
-const OBJECTS_MAPPING = new WeakMap();
-
 /**
  * Calculates a unique object identifier
  *
- * @param {object} object Any valid ECMA object
- * @returns {string} A uuidV4 string that uniquely identifies given object
+ * @param object - Any valid ECMA object
+ * @returns A uuidV4 string that uniquely identifies given object
  */
-function getObjectId(object) {
-  if (!OBJECTS_MAPPING.has(object)) {
-    OBJECTS_MAPPING.set(object, uuidV4());
+export function getObjectId(object: object): string {
+  const existing = OBJECTS_MAPPING.get(object);
+  if (existing !== undefined) {
+    return existing;
   }
-  return OBJECTS_MAPPING.get(object);
+  const id = uuidV4();
+  OBJECTS_MAPPING.set(object, id);
+  return id;
 }
 
 /**
@@ -181,50 +85,147 @@ function getObjectId(object) {
  * ! This function changes the given object,
  * so it becomes immutable.
  *
- * @param {*} object Any valid ECMA object
- * @returns {*} The same object that was passed to the
- * function after it was made immutable.
+ * @param object - Any valid ECMA object
+ * @returns The same object that was passed after it was made immutable.
  */
-function deepFreeze(object) {
-  let propNames;
+export function deepFreeze<T>(object: T): T {
+  let propNames: string[];
   try {
-    propNames = Object.getOwnPropertyNames(object);
+    propNames = Object.getOwnPropertyNames(object as object);
   } catch {
     return object;
   }
   for (const name of propNames) {
-    const value = object[name];
+    const value = (object as Record<string, unknown>)[name];
     if (value && typeof value === 'object') {
       deepFreeze(value);
     }
   }
-  return Object.freeze(object);
+  return Object.freeze(object) as T;
 }
 
 /**
  * Tries to synchronously detect the absolute path to the folder
  * where the given `moduleName` is located.
  *
- * @param {string} moduleName The name of the module as it is written in package.json
- * @param {string} filePath Full path to any of files that `moduleName` contains. Use
+ * @param moduleName - The name of the module as it is written in package.json
+ * @param filePath - Full path to any of files that `moduleName` contains. Use
  * `__filename` to find the root of the module where this helper is called.
- * @returns {string?} Full path to the module root
+ * @returns Full path to the module root, or null if not found
  */
-function getModuleRootSync (moduleName, filePath) {
+export function getModuleRootSync(moduleName: string, filePath: string): string | null {
   let currentDir = path.dirname(path.resolve(filePath));
   let isAtFsRoot = false;
   while (!isAtFsRoot) {
     const manifestPath = path.join(currentDir, 'package.json');
     try {
-      if (_fs.existsSync(manifestPath) &&
-          JSON.parse(_fs.readFileSync(manifestPath, 'utf8')).name === moduleName) {
+      if (
+        _fs.existsSync(manifestPath) &&
+        (JSON.parse(_fs.readFileSync(manifestPath, 'utf8')) as {name?: string}).name === moduleName
+      ) {
         return currentDir;
       }
-    } catch {}
+    } catch {
+      // ignore
+    }
     currentDir = path.dirname(currentDir);
     isAtFsRoot = currentDir.length <= path.dirname(currentDir).length;
   }
   return null;
 }
 
-export {requirePackage, getObjectSize, getObjectId, deepFreeze, getModuleRootSync};
+// #region Private
+
+const ECMA_SIZES = Object.freeze({
+  STRING: 2,
+  BOOLEAN: 4,
+  NUMBER: 8,
+});
+
+type SizeCalculator = (obj: unknown) => number;
+
+async function linkGlobalPackage(packageName: string): Promise<void> {
+  try {
+    log.debug(`Linking package '${packageName}'`);
+    const cmd = isWindows() ? 'npm.cmd' : 'npm';
+    await exec(cmd, ['link', packageName], {timeout: 20000});
+  } catch (err) {
+    const e = err as Error & {stderr?: string};
+    const msg = `Unable to load package '${packageName}', linking failed: ${e.message}`;
+    log.debug(msg);
+    if (e.stderr) {
+      log.debug(e.stderr);
+    }
+    throw new Error(msg);
+  }
+}
+
+function extractAllProperties(obj: object): (string | symbol)[] {
+  const stringProperties: (string | symbol)[] = [];
+  for (const prop in obj) {
+    stringProperties.push(prop);
+  }
+  if (_.isFunction(Object.getOwnPropertySymbols)) {
+    stringProperties.push(...Object.getOwnPropertySymbols(obj));
+  }
+  return stringProperties;
+}
+
+function _getSizeOfObject(seen: WeakSet<object>, object: object): number {
+  if (_.isNil(object)) {
+    return 0;
+  }
+
+  let bytes = 0;
+  const properties = extractAllProperties(object);
+  const calc = getCalculator(seen);
+  for (const key of properties) {
+    const val = (object as Record<string | symbol, unknown>)[key];
+    if (typeof val === 'object' && !_.isNil(val)) {
+      if (seen.has(val as object)) {
+        continue;
+      }
+      seen.add(val as object);
+    }
+
+    bytes += calc(key);
+    try {
+      bytes += calc(val);
+    } catch (ex) {
+      if (ex instanceof RangeError) {
+        bytes = 0;
+      }
+    }
+  }
+
+  return bytes;
+}
+
+function getCalculator(seen: WeakSet<object>): SizeCalculator {
+  return function calculator(obj: unknown): number {
+    if (_.isBuffer(obj)) {
+      return (obj as Buffer).length;
+    }
+
+    switch (typeof obj) {
+      case 'string':
+        return obj.length * ECMA_SIZES.STRING;
+      case 'boolean':
+        return ECMA_SIZES.BOOLEAN;
+      case 'number':
+        return ECMA_SIZES.NUMBER;
+      case 'symbol':
+        return _.isFunction(Symbol.keyFor) && Symbol.keyFor(obj)
+          ? (Symbol.keyFor(obj) as string).length * ECMA_SIZES.STRING
+          : (obj.toString().length - 8) * ECMA_SIZES.STRING;
+      case 'object':
+        return _.isArray(obj)
+          ? obj.map(getCalculator(seen)).reduce((acc, curr) => acc + curr, 0)
+          : _getSizeOfObject(seen, obj as object);
+      default:
+        return 0;
+    }
+  };
+}
+
+// #endregion

package/lib/npm.ts

@@ -0,0 +1,291 @@
+import path from 'node:path';
+import * as semver from 'semver';
+import type {PackageJson} from 'type-fest';
+import type {StringRecord} from '@appium/types';
+import {hasAppiumDependency} from './env';
+import {exec} from 'teen_process';
+import type {ExecError, TeenProcessExecOptions} from 'teen_process';
+import {fs} from './fs';
+import * as util from './util';
+import * as system from './system';
+import resolveFrom from 'resolve-from';
+
+/**
+ * Relative path to directory containing any Appium internal files
+ * XXX: this is duplicated in `appium/lib/constants.js`.
+ */
+export const CACHE_DIR_RELATIVE_PATH = path.join('node_modules', '.cache', 'appium');
+
+/**
+ * Relative path to lockfile used when installing an extension via `appium`
+ */
+export const INSTALL_LOCKFILE_RELATIVE_PATH = path.join(CACHE_DIR_RELATIVE_PATH, '.install.lock');
+
+/** Options for {@link NPM.exec} */
+export interface ExecOpts {
+  /** Current working directory */
+  cwd: string;
+  /** If true, supply `--json` flag to npm and resolve w/ parsed JSON */
+  json?: boolean;
+  /** Path to lockfile to use */
+  lockFile?: string;
+}
+
+/** Options for {@link NPM.installPackage} */
+export interface InstallPackageOpts {
+  /** Name of the package to install */
+  pkgName: string;
+  /** Whether to install from a local path or from npm */
+  installType?: 'local' | string;
+}
+
+/** Result of {@link NPM.installPackage} */
+export interface NpmInstallReceipt {
+  /** Path to installed package */
+  installPath: string;
+  /** Package data */
+  pkg: PackageJson;
+}
+
+export interface NpmExecResult {
+  stdout: string;
+  stderr: string;
+  code: number | null;
+  json?: unknown;
+}
+
+/**
+ * XXX: This should probably be a singleton, but it isn't.  Maybe this module should just export functions?
+ */
+export class NPM {
+  /**
+   * Execute `npm` with given args.
+   *
+   * If the process exits with a nonzero code, the contents of `STDOUT` and `STDERR` will be in the
+   * `message` of any rejected error.
+   */
+  async exec(
+    cmd: string,
+    args: string[],
+    opts: ExecOpts,
+    execOpts: Omit<TeenProcessExecOptions, 'cwd'> = {}
+  ): Promise<NpmExecResult> {
+    const {cwd, json, lockFile} = opts;
+
+    const teenProcessExecOpts: TeenProcessExecOptions = {
+      ...execOpts,
+      shell: system.isWindows() || execOpts.shell,
+      cwd,
+    };
+
+    const argsCopy = [cmd, ...args];
+    if (json) {
+      argsCopy.push('--json');
+    }
+    const npmCmd = system.isWindows() ? 'npm.cmd' : 'npm';
+    type ExecRunnerResult = {stdout: string; stderr: string; code: number | null};
+    let runner = async (): Promise<ExecRunnerResult> =>
+      await exec(npmCmd, argsCopy, teenProcessExecOpts);
+    if (lockFile) {
+      const acquireLock = util.getLockFileGuard(lockFile);
+      const _runner = runner;
+      runner = async () => (await acquireLock(_runner)) as ExecRunnerResult;
+    }
+
+    let ret: NpmExecResult;
+    try {
+      const {stdout, stderr, code} = await runner();
+      ret = {stdout, stderr, code};
+      try {
+        ret.json = JSON.parse(stdout);
+      } catch {
+        // ignore
+      }
+    } catch (e) {
+      const {stdout = '', stderr = '', code = null} = e as ExecError;
+      throw new Error(
+        `npm command '${argsCopy.join(' ')}' failed with code ${code}.\n\nSTDOUT:\n${stdout.trim()}\n\nSTDERR:\n${stderr.trim()}`
+      );
+    }
+    return ret;
+  }
+
+  /**
+   * Gets the latest published version of a package from npm registry.
+   *
+   * @param cwd - Current working directory for npm command
+   * @param pkg - Package name to query
+   * @returns Latest version string, or `null` if package not found (e.g. 404)
+   */
+  async getLatestVersion(cwd: string, pkg: string): Promise<string | null> {
+    try {
+      const result = await this.exec('view', [pkg, 'dist-tags'], {json: true, cwd});
+      const json = result.json as {latest?: string} | undefined;
+      return json?.latest ?? null;
+    } catch (err) {
+      if (!(err instanceof Error) || !err.message.includes('E404')) {
+        throw err;
+      }
+      return null;
+    }
+  }
+
+  /**
+   * Gets the latest version of a package that is a safe upgrade from the current version
+   * (same major, no prereleases). Fetches versions from npm and delegates to
+   * {@link NPM.getLatestSafeUpgradeFromVersions}.
+   *
+   * @param cwd - Current working directory for npm command
+   * @param pkg - Package name to query
+   * @param curVersion - Current installed version
+   * @returns Latest safe upgrade version string, or `null` if none or package not found
+   */
+  async getLatestSafeUpgradeVersion(
+    cwd: string,
+    pkg: string,
+    curVersion: string
+  ): Promise<string | null> {
+    try {
+      const result = await this.exec('view', [pkg, 'versions'], {json: true, cwd});
+      const allVersions = result.json;
+      if (!Array.isArray(allVersions)) {
+        return null;
+      }
+      return this.getLatestSafeUpgradeFromVersions(curVersion, allVersions as string[]);
+    } catch (err) {
+      if (!(err instanceof Error) || !err.message.includes('E404')) {
+        throw err;
+      }
+      return null;
+    }
+  }
+
+  /**
+   * Runs `npm ls`, optionally for a particular package.
+   */
+  async list(cwd: string, pkg?: string): Promise<unknown> {
+    return (await this.exec('list', pkg ? [pkg] : [], {cwd, json: true})).json;
+  }
+
+  /**
+   * Given a current version and a list of all versions for a package, return the version which is
+   * the highest safely-upgradable version (meaning not crossing any major revision boundaries, and
+   * not including any alpha/beta/rc versions)
+   */
+  getLatestSafeUpgradeFromVersions(
+    curVersion: string,
+    allVersions: string[]
+  ): string | null {
+    let safeUpgradeVer: semver.SemVer | null = null;
+    const curSemver = semver.parse(curVersion) ?? semver.parse(semver.coerce(curVersion));
+    if (curSemver === null) {
+      throw new Error(`Could not parse current version '${curVersion}'`);
+    }
+    for (const testVer of allVersions) {
+      const testSemver = semver.parse(testVer) ?? semver.parse(semver.coerce(testVer));
+      if (
+        testSemver === null ||
+        testSemver.prerelease.length > 0 ||
+        curSemver.compare(testSemver) === 1 ||
+        testSemver.major > curSemver.major
+      ) {
+        continue;
+      }
+      if (safeUpgradeVer === null || testSemver.compare(safeUpgradeVer) === 1) {
+        safeUpgradeVer = testSemver;
+      }
+    }
+    return safeUpgradeVer ? safeUpgradeVer.format() : null;
+  }
+
+  /**
+   * Installs a package w/ `npm`
+   */
+  async installPackage(
+    cwd: string,
+    installStr: string,
+    opts: InstallPackageOpts
+  ): Promise<NpmInstallReceipt> {
+    const {pkgName, installType} = opts;
+    let dummyPkgJson: Record<string, unknown>;
+    const dummyPkgPath = path.join(cwd, 'package.json');
+    try {
+      dummyPkgJson = JSON.parse(await fs.readFile(dummyPkgPath, 'utf8')) as Record<string, unknown>;
+    } catch (err) {
+      const nodeErr = err as NodeJS.ErrnoException;
+      if (nodeErr.code === 'ENOENT') {
+        dummyPkgJson = {};
+        await fs.writeFile(dummyPkgPath, JSON.stringify(dummyPkgJson, null, 2), 'utf8');
+      } else {
+        throw err;
+      }
+    }
+
+    const installOpts = ['--save-dev', '--no-progress', '--no-audit'];
+    if (!(await hasAppiumDependency(cwd))) {
+      if (process.env.APPIUM_OMIT_PEER_DEPS) {
+        installOpts.push('--omit=peer');
+      }
+      installOpts.push('--save-exact', '--global-style', '--no-package-lock');
+    }
+
+    const cmd = installType === 'local' ? 'link' : 'install';
+    const res = await this.exec(cmd, [...installOpts, installStr], {
+      cwd,
+      json: true,
+      lockFile: this._getInstallLockfilePath(cwd),
+    });
+
+    if (res.json && typeof res.json === 'object' && 'error' in res.json && res.json.error) {
+      throw new Error(String((res.json as {error: unknown}).error));
+    }
+
+    const pkgJsonPath = resolveFrom(cwd, `${pkgName}/package.json`);
+    try {
+      const pkgJson = await fs.readFile(pkgJsonPath, 'utf8');
+      const pkg = JSON.parse(pkgJson) as PackageJson;
+      return {installPath: path.dirname(pkgJsonPath), pkg};
+    } catch {
+      throw new Error(
+        'The package was not downloaded correctly; its package.json ' +
+          'did not exist or was unreadable. We looked for it at ' +
+          pkgJsonPath
+      );
+    }
+  }
+
+  /**
+   * Uninstalls a package with `npm uninstall`.
+   *
+   * @param cwd - Current working directory (project root)
+   * @param pkg - Package name to uninstall
+   */
+  async uninstallPackage(cwd: string, pkg: string): Promise<void> {
+    await this.exec('uninstall', [pkg], {
+      cwd,
+      lockFile: this._getInstallLockfilePath(cwd),
+    });
+  }
+
+  /**
+   * Fetches package metadata from the npm registry via `npm info`.
+   *
+   * @param pkg - Npm package spec to query
+   * @param entries - Field names to be included into the resulting output. By default all fields are included.
+   * @returns Package metadata as a record of string values
+   */
+  async getPackageInfo(pkg: string, entries: string[] = []): Promise<StringRecord> {
+    const result = await this.exec('info', [pkg, ...entries], {
+      cwd: process.cwd(),
+      json: true,
+    });
+    return (result.json ?? {}) as StringRecord;
+  }
+
+  /** Returns path to "install" lockfile */
+  private _getInstallLockfilePath(cwd: string): string {
+    return path.join(cwd, INSTALL_LOCKFILE_RELATIVE_PATH);
+  }
+}
+
+export const npm = new NPM();