appium 3.2.2 → 3.3.0

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

@@ -8,31 +8,25 @@ import os from 'node:os';
 import {npmPackage} from './utils';
 import B from 'bluebird';
 import {getDefaultsForSchema, getAllArgSpecs} from './schema/schema';
+import type {BuildInfo, Args} from 'appium/types';
+import type {ReadConfigFileResult} from './config-file';
 
 export const APPIUM_VER = npmPackage.version;
-const ENGINES = /** @type {Record<string,string>} */ (npmPackage.engines);
+const ENGINES = npmPackage.engines as Record<string, string>;
 const MIN_NODE_VERSION = ENGINES.node;
 export const rootDir = fs.findRoot(__dirname);
 
 const GIT_BINARY = `git${system.isWindows() ? '.exe' : ''}`;
 const GITHUB_API = 'https://api.github.com/repos/appium/appium';
 
-/**
- * @type {import('appium/types').BuildInfo}
- */
-const BUILD_INFO = {
+const BUILD_INFO: BuildInfo = {
   version: APPIUM_VER,
 };
 
-function getNodeVersion() {
-  return /** @type {import('semver').SemVer} */ (semver.coerce(process.version));
-}
-
 /**
- * @param {boolean} [useGithubApiFallback]
- * @returns {Promise<void>}
+ * Update mutable build info metadata from local git or GitHub fallback.
  */
-export async function updateBuildInfo(useGithubApiFallback = false) {
+export async function updateBuildInfo(useGithubApiFallback = false): Promise<void> {
   const sha = await getGitRev(useGithubApiFallback);
   if (!sha) {
     return;
@@ -44,35 +38,22 @@ export async function updateBuildInfo(useGithubApiFallback = false) {
   }
 }
 
-/** @type {() => Promise<string?>} */
-const getFullGitPath = _.memoize(async function getFullGitPath() {
-  try {
-    return await fs.which(GIT_BINARY);
-  } catch {
-    return null;
-  }
-});
-
 /**
- * Prints server debug into into the console.
- *
- * @param {{
- * driverConfig: import('./extension/driver-config').DriverConfig,
- * pluginConfig: import('./extension/plugin-config').PluginConfig,
- * appiumHome: string
- * }} info
- * @returns {Promise<void>}
+ * Prints server debug info to stdout.
  */
-export async function showDebugInfo({driverConfig, pluginConfig, appiumHome}) {
-  const getNpmVersion = async () => {
+export async function showDebugInfo({driverConfig, pluginConfig, appiumHome}: DebugInfoInput): Promise<void> {
+  const getNpmVersion = async (): Promise<string> => {
     const {stdout} = await npm.exec('--version', [], {cwd: process.cwd()});
     return _.trim(stdout);
   };
-  const findNpmLocation = async () => await fs.which(system.isWindows() ? 'npm.cmd' : 'npm');
+  const findNpmLocation = async (): Promise<string> =>
+    await fs.which(system.isWindows() ? 'npm.cmd' : 'npm');
+
   const [npmVersion, npmLocation] = await B.all([
-    ...([getNpmVersion, findNpmLocation].map((f) => getSafeResult(f, 'unknown'))),
-    /** @type {any} */ (updateBuildInfo()),
+    ...[getNpmVersion, findNpmLocation].map((f) => getSafeResult(f, 'unknown')),
+    updateBuildInfo() as Promise<unknown>,
   ]);
+
   const debugInfo = {
     os: {
       platform: os.platform(),
@@ -104,10 +85,12 @@ export async function showDebugInfo({driverConfig, pluginConfig, appiumHome}) {
 }
 
 /**
- * @param {boolean} [useGithubApiFallback]
- * @returns {Promise<string?>}
+ * Returns the current git commit SHA for this Appium checkout.
+ *
+ * Attempts to read from local git first; when unavailable and fallback is enabled,
+ * queries the GitHub API for the tag matching the current Appium version.
  */
-export async function getGitRev(useGithubApiFallback = false) {
+export async function getGitRev(useGithubApiFallback = false): Promise<string | null> {
   const fullGitPath = await getFullGitPath();
   if (fullGitPath) {
     try {
@@ -136,90 +119,56 @@ export async function getGitRev(useGithubApiFallback = false) {
   return null;
 }
 
-/**
- * @param {string} commitSha
- * @param {boolean} [useGithubApiFallback]
- * @returns {Promise<string?>}
- */
-async function getGitTimestamp(commitSha, useGithubApiFallback = false) {
-  const fullGitPath = await getFullGitPath();
-  if (fullGitPath) {
-    try {
-      const {stdout} = await exec(fullGitPath, ['show', '-s', '--format=%ci', commitSha], {
-        cwd: __dirname,
-      });
-      return stdout.trim();
-    } catch {}
-  }
-
-  if (!useGithubApiFallback) {
-    return null;
-  }
-
-  try {
-    return (
-      await axios.get(`${GITHUB_API}/git/tags/${commitSha}`, {
-        headers: {
-          'User-Agent': `Appium ${APPIUM_VER}`,
-        },
-      })
-    ).data?.tagger?.date;
-  } catch {}
-  return null;
-}
-
 /**
  * Mutable object containing Appium build information. By default it
  * only contains the Appium version, but is updated with the build timestamp
  * and git commit hash asynchronously as soon as `updateBuildInfo` is called
  * and succeeds.
- * @returns {import('appium/types').BuildInfo}
  */
-export function getBuildInfo() {
+export function getBuildInfo(): BuildInfo {
   return BUILD_INFO;
 }
 
 /**
- * @returns {void}
  * @throws {Error} If Node version is outside of the supported range
  */
-export function checkNodeOk() {
+export function checkNodeOk(): void {
   const version = getNodeVersion();
   if (!semver.satisfies(version, MIN_NODE_VERSION)) {
-    throw new Error(
-      `Node version must be at least ${MIN_NODE_VERSION}; current is ${version.version}`
-    );
+    throw new Error(`Node version must be at least ${MIN_NODE_VERSION}; current is ${version.version}`);
   }
 }
 
-export async function showBuildInfo() {
+/**
+ * Prints the current build info JSON to stdout.
+ *
+ * This updates build metadata first (using GitHub fallback) and then logs the
+ * resulting {@link BuildInfo} object.
+ */
+export async function showBuildInfo(): Promise<void> {
   await updateBuildInfo(true);
   console.log(JSON.stringify(getBuildInfo()));
 }
 
 /**
  * Returns k/v pairs of server arguments which are _not_ the defaults.
- * @param {Args} parsedArgs
- * @returns {Args}
  */
-export function getNonDefaultServerArgs(parsedArgs) {
+export function getNonDefaultServerArgs(parsedArgs: Args): Args {
   /**
    * Flattens parsed args into a single level object for comparison with
    * flattened defaults across server args and extension args.
-   * @param {Args} args
-   * @returns {Record<string, { value: any, argSpec: ArgSpec }>}
    */
-  const flatten = (args) => {
+  const flatten = (args: Args): Record<string, FlattenedArg> => {
     const argSpecs = getAllArgSpecs();
     const flattened = _.reduce(
       [...argSpecs.values()],
-      (acc, argSpec) => {
+      (acc: Record<string, FlattenedArg>, argSpec: {dest: string}) => {
         if (_.has(args, argSpec.dest)) {
           acc[argSpec.dest] = {value: _.get(args, argSpec.dest), argSpec};
         }
         return acc;
       },
-      /** @type {Record<string, { value: any, argSpec: ArgSpec }>} */ ({})
+      {}
     );
 
     return flattened;
@@ -228,25 +177,21 @@ export function getNonDefaultServerArgs(parsedArgs) {
   const args = flatten(parsedArgs);
 
   // hopefully these function names are descriptive enough
-  const typesDiffer = /** @param {string} dest */ (dest) =>
+  const typesDiffer = (dest: string): boolean =>
     typeof args[dest].value !== typeof defaultsFromSchema[dest];
 
-  const defaultValueIsArray = /** @param {string} dest */ (dest) =>
-    _.isArray(defaultsFromSchema[dest]);
+  const defaultValueIsArray = (dest: string): boolean => _.isArray(defaultsFromSchema[dest]);
 
-  const argsValueIsArray = /** @param {string} dest */ (dest) => _.isArray(args[dest].value);
+  const argsValueIsArray = (dest: string): boolean => _.isArray(args[dest].value);
 
-  const arraysDiffer = /** @param {string} dest */ (dest) =>
-    _.gt(_.size(_.difference(args[dest].value, defaultsFromSchema[dest])), 0);
+  const arraysDiffer = (dest: string): boolean =>
+    _.gt(_.size(_.difference(args[dest].value as any[], defaultsFromSchema[dest] as any[])), 0);
 
-  const valuesDiffer = /** @param {string} dest */ (dest) =>
-    args[dest].value !== defaultsFromSchema[dest];
+  const valuesDiffer = (dest: string): boolean => args[dest].value !== defaultsFromSchema[dest];
 
-  const defaultIsDefined = /** @param {string} dest */ (dest) =>
-    !_.isUndefined(defaultsFromSchema[dest]);
+  const defaultIsDefined = (dest: string): boolean => !_.isUndefined(defaultsFromSchema[dest]);
 
   // note that `_.overEvery` is like an "AND", and `_.overSome` is like an "OR"
-
   const argValueNotArrayOrArraysDiffer = _.overSome([_.negate(argsValueIsArray), arraysDiffer]);
 
   const defaultValueNotArrayAndValuesDiffer = _.overEvery([
@@ -264,7 +209,6 @@ export function getNonDefaultServerArgs(parsedArgs) {
    * - if so, and the default is an array:
    *   - ensures the args value is an array
    *   - ensures the args values do not differ from the default values
-   * @type {(dest: string) => boolean}
    */
   const isNotDefault = _.overEvery([
     defaultIsDefined,
@@ -275,42 +219,29 @@ export function getNonDefaultServerArgs(parsedArgs) {
     ]),
   ]);
 
-  const defaultsFromSchema = getDefaultsForSchema(true);
+  const defaultsFromSchema = getDefaultsForSchema(true) as Record<string, unknown>;
 
   return _.reduce(
-    _.pickBy(args, (__, key) => isNotDefault(key)),
+    _.pickBy(args, (_v, key) => isNotDefault(key)),
     // explodes the flattened object back into nested one
-    (acc, {value, argSpec}) => _.set(acc, argSpec.dest, value),
-    /** @type {Args} */ ({})
+    (acc: Args, {value, argSpec}: FlattenedArg) => _.set(acc, argSpec.dest, value),
+    {} as Args
   );
 }
 
-/**
- * Compacts an object for {@link showConfig}:
- * 1. Removes `subcommand` key/value
- * 2. Removes `undefined` values
- * 3. Removes empty objects (but not `false` values)
- * Does not operate recursively.
- */
-const compactConfig = _.partial(
-  _.omitBy,
-  _,
-  (value, key) =>
-    key === 'subcommand' || _.isUndefined(value) || (_.isObject(value) && _.isEmpty(value))
-);
-
 /**
  * Shows a breakdown of the current config after CLI params, config file loaded & defaults applied.
  *
- * The actual shape of `preConfigParsedArgs` and `defaults` does not matter for the purposes of this function,
- * but it's intended to be called with values of type {@link ParsedArgs} and `DefaultValues<true>`, respectively.
- *
- * @param {Partial<ParsedArgs>} nonDefaultPreConfigParsedArgs - Parsed CLI args (or param to `init()`) before config & defaults applied
- * @param {import('./config-file').ReadConfigFileResult} configResult - Result of attempting to load a config file.  _Must_ be normalized
- * @param {Partial<ParsedArgs>} defaults - Configuration defaults from schemas
- * @param {ParsedArgs} parsedArgs - Entire parsed args object
+ * The actual shape of `preConfigParsedArgs` and `defaults` does not matter for the purposes of this
+ * function, but it's intended to be called with values of type {@link ParsedArgs} and
+ * `DefaultValues<true>`, respectively.
  */
-export function showConfig(nonDefaultPreConfigParsedArgs, configResult, defaults, parsedArgs) {
+export function showConfig(
+  nonDefaultPreConfigParsedArgs: Partial<Args>,
+  configResult: ReadConfigFileResult,
+  defaults: Partial<Args>,
+  parsedArgs: Args
+): void {
   console.log('Appium Configuration\n');
   console.log('from defaults:\n');
   console.dir(compactConfig(defaults));
@@ -332,17 +263,22 @@ export function showConfig(nonDefaultPreConfigParsedArgs, configResult, defaults
 }
 
 /**
- * @param {string} root
- * @param {boolean} [requireWriteable=true]
- * @param {string} [displayName='folder path']
+ * Ensures a directory exists and (optionally) is writeable.
+ *
+ * If the directory does not exist, this attempts to create it recursively.
+ *
  * @throws {Error}
  */
-export async function requireDir(root, requireWriteable = true, displayName = 'folder path') {
+export async function requireDir(
+  root: string,
+  requireWriteable = true,
+  displayName = 'folder path'
+): Promise<void> {
   let stat;
   try {
     stat = await fs.stat(root);
   } catch (e) {
-    if (e.code === 'ENOENT') {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') {
       try {
         await fs.mkdir(root, {recursive: true});
         return;
@@ -358,23 +294,70 @@ export async function requireDir(root, requireWriteable = true, displayName = 'f
       await fs.access(root, fs.constants.W_OK);
     } catch {
       throw new Error(
-        `The ${displayName} '${root}' must be ` +
-        `writeable for the current user account '${os.userInfo().username}'`
+        `The ${displayName} '${root}' must be writeable for the current user account '${os.userInfo().username}'`
       );
     }
   }
 }
 
+function getNodeVersion(): semver.SemVer {
+  return semver.coerce(process.version) as semver.SemVer;
+}
+
+const getFullGitPath = _.memoize(async function getFullGitPath(): Promise<string | null> {
+  try {
+    return await fs.which(GIT_BINARY);
+  } catch {
+    return null;
+  }
+});
+
+async function getGitTimestamp(commitSha: string, useGithubApiFallback = false): Promise<string | null> {
+  const fullGitPath = await getFullGitPath();
+  if (fullGitPath) {
+    try {
+      const {stdout} = await exec(fullGitPath, ['show', '-s', '--format=%ci', commitSha], {
+        cwd: __dirname,
+      });
+      return stdout.trim();
+    } catch {}
+  }
+
+  if (!useGithubApiFallback) {
+    return null;
+  }
+
+  try {
+    return (
+      await axios.get(`${GITHUB_API}/git/tags/${commitSha}`, {
+        headers: {
+          'User-Agent': `Appium ${APPIUM_VER}`,
+        },
+      })
+    ).data?.tagger?.date;
+  } catch {}
+  return null;
+}
+
+/**
+ * Compacts an object for {@link showConfig}:
+ * 1. Removes `subcommand` key/value
+ * 2. Removes `undefined` values
+ * 3. Removes empty objects (but not `false` values)
+ * Does not operate recursively.
+ */
+const compactConfig = _.partial(
+  _.omitBy,
+  _,
+  (value: unknown, key: string) =>
+    key === 'subcommand' || _.isUndefined(value) || (_.isObject(value) && _.isEmpty(value))
+);
+
 /**
  * Calculates the result of the given function and return its value
  * or the default one if there was an exception.
- *
- * @template T
- * @param {() => Promise<T>} f
- * @param {T} defaultValue
- * @returns {Promise<T>}
  */
-async function getSafeResult(f, defaultValue) {
+async function getSafeResult<T>(f: () => Promise<T>, defaultValue: T): Promise<T> {
   try {
     return await f();
   } catch {
@@ -382,8 +365,13 @@ async function getSafeResult(f, defaultValue) {
   }
 }
 
-/**
- * @typedef {import('appium/types').ParsedArgs} ParsedArgs
- * @typedef {import('appium/types').Args} Args
- * @typedef {import('./schema/arg-spec').ArgSpec} ArgSpec
- */
+interface DebugInfoInput {
+  driverConfig: {installedExtensions: unknown};
+  pluginConfig: {installedExtensions: unknown};
+  appiumHome: string;
+}
+
+interface FlattenedArg {
+  value: unknown;
+  argSpec: {dest: string};
+}

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

@@ -20,7 +20,6 @@ export const SERVER_SUBCOMMAND = 'server';
  */
 export const SETUP_SUBCOMMAND = 'setup';
 
-
 /**
  * The value of `--use-plugins` if _all_ plugins should be loaded
  */
@@ -30,51 +29,41 @@ export const USE_ALL_PLUGINS = 'all';
 // The plugins in this list will be available to the CLI so users can just
 // type 'appium plugin install 'name'', rather than having to specify the full
 // npm package. I.e., these are the officially recognized plugins.
-export const KNOWN_PLUGINS = Object.freeze(
-  /** @type {const} */ ({
-    'execute-driver': '@appium/execute-driver-plugin',
-    images: '@appium/images-plugin',
-    inspector: 'appium-inspector-plugin',
-    'relaxed-caps': '@appium/relaxed-caps-plugin',
-    storage: '@appium/storage-plugin',
-    'universal-xml': '@appium/universal-xml-plugin',
-  }),
-);
-
-export const MOBILE_DRIVERS = Object.freeze(
-  /** @type {const} */ ({
-    uiautomator2: 'appium-uiautomator2-driver',
-    xcuitest: 'appium-xcuitest-driver',
-    espresso: 'appium-espresso-driver',
-  }),
-);
-
-export const DESKTOP_DRIVERS = Object.freeze(
-  /** @type {const} */ ({
-    mac2: 'appium-mac2-driver',
-    windows: 'appium-windows-driver',
-  }),
-);
-
-export const DESKTOP_BROWSERS = Object.freeze(
-  /** @type {const} */ ({
-    safari: 'appium-safari-driver',
-    gecko: 'appium-geckodriver',
-    chromium: 'appium-chromium-driver',
-  }),
-);
+export const KNOWN_PLUGINS = Object.freeze({
+  'execute-driver': '@appium/execute-driver-plugin',
+  images: '@appium/images-plugin',
+  inspector: 'appium-inspector-plugin',
+  'relaxed-caps': '@appium/relaxed-caps-plugin',
+  storage: '@appium/storage-plugin',
+  'universal-xml': '@appium/universal-xml-plugin',
+} as const);
+
+export const MOBILE_DRIVERS = Object.freeze({
+  uiautomator2: 'appium-uiautomator2-driver',
+  xcuitest: 'appium-xcuitest-driver',
+  espresso: 'appium-espresso-driver',
+} as const);
+
+export const DESKTOP_DRIVERS = Object.freeze({
+  mac2: 'appium-mac2-driver',
+  windows: 'appium-windows-driver',
+} as const);
+
+export const DESKTOP_BROWSERS = Object.freeze({
+  safari: 'appium-safari-driver',
+  gecko: 'appium-geckodriver',
+  chromium: 'appium-chromium-driver',
+} as const);
 
 // This is a map of driver names to npm packages representing those drivers.
 // The drivers in this list will be available to the CLI so users can just
 // type 'appium driver install 'name'', rather than having to specify the full
 // npm package. I.e., these are the officially recognized drivers.
-export const KNOWN_DRIVERS = Object.freeze(
-  /** @type {const} */ ({
-    ...MOBILE_DRIVERS,
-    ...DESKTOP_DRIVERS,
-    ...DESKTOP_BROWSERS,
-  }),
-);
+export const KNOWN_DRIVERS = Object.freeze({
+  ...MOBILE_DRIVERS,
+  ...DESKTOP_DRIVERS,
+  ...DESKTOP_BROWSERS,
+} as const);
 
 /**
  * Relative path to directory containing any Appium internal files