appium 3.5.0 → 3.5.1

package/lib/schema/schema.ts

@@ -1,7 +1,8 @@
 import Ajv, {type ErrorObject, type SchemaObject, type ValidateFunction} from 'ajv';
 import addFormats from 'ajv-formats';
-import _ from 'lodash';
+import {util} from '@appium/support';
 import path from 'node:path';
+import {bindAll, kebabCase, omitKeys, setPath} from '../utils';
 import {AppiumConfigJsonSchema} from '@appium/schema';
 import type {ExtensionType} from '@appium/types';
 import {DRIVER_TYPE, PLUGIN_TYPE} from '../constants';
@@ -40,7 +41,7 @@ export class RoachHotelMap<K, V> extends Map<K, V> {
 }
 
 export const ALLOWED_SCHEMA_EXTENSIONS = Object.freeze(
-  new Set<AllowedSchemaExtension>(['.json', '.js', '.cjs'])
+  new Set<AllowedSchemaExtension>(['.json', '.js', '.cjs']),
 );
 
 const SCHEMA_KEY = '$schema';
@@ -66,7 +67,7 @@ class AppiumSchema {
     if (!AppiumSchema.#instance) {
       const instance = new AppiumSchema();
       AppiumSchema.#instance = instance;
-      _.bindAll(instance, [
+      bindAll(instance, [
         'finalize',
         'flatten',
         'getAllArgSpecs',
@@ -96,7 +97,7 @@ class AppiumSchema {
    * Returns `true` if schema is a plain object and not async.
    */
   static isSupportedSchemaType(schema: any): schema is SchemaObject {
-    return _.isPlainObject(schema) && (schema as any).$async !== true;
+    return util.isPlainObject(schema) && (schema as any).$async !== true;
   }
 
   /**
@@ -107,11 +108,11 @@ class AppiumSchema {
       new Ajv({
         // without this not much validation actually happens
         allErrors: true,
-      })
+      }),
     );
-    _.forEach(keywords, (keyword) => {
+    for (const keyword of Object.values(keywords)) {
       ajv.addKeyword(keyword);
-    });
+    }
     return ajv;
   }
 
@@ -145,12 +146,12 @@ class AppiumSchema {
     }
 
     const ajv = this.#ajv;
-    const baseSchema = _.cloneDeep(AppiumConfigJsonSchema) as any;
+    const baseSchema = structuredClone(AppiumConfigJsonSchema) as any;
 
     const addArgSpecs = (
       schema: Record<string, any>,
       extType?: ExtensionType,
-      extName?: string
+      extName?: string,
     ): void => {
       for (const [propName, propSchema] of Object.entries(schema)) {
         const argSpec = ArgSpec.create(propName, {
@@ -163,7 +164,7 @@ class AppiumSchema {
       }
     };
 
-    addArgSpecs(_.omit(baseSchema.properties.server.properties, [DRIVER_TYPE, PLUGIN_TYPE]));
+    addArgSpecs(omitKeys(baseSchema.properties.server.properties, [DRIVER_TYPE, PLUGIN_TYPE]));
 
     const finalizedSchemas: Record<string, StrictSchemaObject> = {};
 
@@ -174,7 +175,10 @@ class AppiumSchema {
         const $ref = ArgSpec.toSchemaBaseRef(extType, extName);
         (schema as any).$id = $ref;
         (schema as any).additionalProperties = false;
-        baseSchema.properties.server.properties[extType].properties[extName] = {$ref, $comment: extName};
+        baseSchema.properties.server.properties[extType].properties[extName] = {
+          $ref,
+          $comment: extName,
+        };
         await ajv.validateSchema(schema, true);
         addArgSpecs((schema as any).properties, extType, extName);
         ajv.addSchema(schema, $ref);
@@ -207,16 +211,20 @@ class AppiumSchema {
   /**
    * Registers an extension schema.
    */
-  async registerSchema(extType: ExtensionType, extName: string, schema: SchemaObject): Promise<void> {
-    if (!(extType && extName) || _.isUndefined(schema)) {
+  async registerSchema(
+    extType: ExtensionType,
+    extName: string,
+    schema: SchemaObject,
+  ): Promise<void> {
+    if (!(extType && extName) || schema === undefined) {
       throw new TypeError('Expected extension type, extension name, and a defined schema');
     }
     if (!AppiumSchema.isSupportedSchemaType(schema)) {
       throw new SchemaUnsupportedSchemaError(schema, extType, extName);
     }
-    const normalizedExtName = _.kebabCase(extName);
+    const normalizedExtName = kebabCase(extName);
     if (this.hasRegisteredSchema(extType, normalizedExtName)) {
-      if (_.isEqual(this.#registeredSchemas[extType].get(normalizedExtName), schema)) {
+      if (util.isEqual(this.#registeredSchemas[extType].get(normalizedExtName), schema)) {
         return;
       }
       throw new SchemaNameConflictError(extType, extName);
@@ -243,7 +251,7 @@ class AppiumSchema {
    * Returns default values for all args, flattened or nested.
    */
   getDefaults<Flattened extends boolean | undefined = true>(
-    flatten = true as Flattened
+    flatten = true as Flattened,
   ): DefaultValues<Flattened> {
     if (!this.isFinalized()) {
       throw new SchemaFinalizationError();
@@ -251,14 +259,14 @@ class AppiumSchema {
 
     const reducer = flatten
       ? (defaults: any, {defaultValue, dest}: ArgSpec) => {
-          if (!_.isUndefined(defaultValue)) {
+          if (defaultValue !== undefined) {
             defaults[dest] = defaultValue;
           }
           return defaults;
         }
       : (defaults: any, {defaultValue, dest}: ArgSpec) => {
-          if (!_.isUndefined(defaultValue)) {
-            _.set(defaults, dest, defaultValue);
+          if (defaultValue !== undefined) {
+            setPath(defaults as Record<string, unknown>, dest, defaultValue);
           }
           return defaults;
         };
@@ -272,20 +280,23 @@ class AppiumSchema {
    */
   getDefaultsForExtension(
     extType: ExtensionType,
-    extName: string
+    extName: string,
   ): Record<string, ArgSpecDefaultValue> {
     if (!this.isFinalized()) {
       throw new SchemaFinalizationError();
     }
     const specs = [...this.#argSpecs.values()].filter(
-      (spec) => spec.extType === extType && spec.extName === extName
+      (spec) => spec.extType === extType && spec.extName === extName,
+    );
+    return specs.reduce(
+      (defaults, {defaultValue, rawDest}) => {
+        if (defaultValue !== undefined) {
+          defaults[rawDest] = defaultValue;
+        }
+        return defaults;
+      },
+      {} as Record<string, ArgSpecDefaultValue>,
     );
-    return specs.reduce((defaults, {defaultValue, rawDest}) => {
-      if (!_.isUndefined(defaultValue)) {
-        defaults[rawDest] = defaultValue;
-      }
-      return defaults;
-    }, {} as Record<string, ArgSpecDefaultValue>);
   }
 
   /**
@@ -299,7 +310,7 @@ class AppiumSchema {
     const flattened: FlattenedSchema = [];
 
     for (const {properties, prefix} of stack) {
-      const pairs = _.toPairs(properties);
+      const pairs = Object.entries(properties);
       for (const [key, value] of pairs) {
         if (key === SCHEMA_KEY) {
           continue;
@@ -317,19 +328,22 @@ class AppiumSchema {
           const {normalizedExtName} = ArgSpec.extensionInfoFromRootSchemaId($ref);
           if (!normalizedExtName) {
             throw new ReferenceError(
-              `Could not determine extension name from schema ID ${$ref}. This is a bug.`
+              `Could not determine extension name from schema ID ${$ref}. This is a bug.`,
             );
           }
-          stack.push({properties: refSchema.properties, prefix: [...prefix, key, normalizedExtName]});
+          stack.push({
+            properties: refSchema.properties,
+            prefix: [...prefix, key, normalizedExtName],
+          });
         } else if (key !== DRIVER_TYPE && key !== PLUGIN_TYPE) {
           const [extType, extName] = prefix;
           const argSpec = this.getArgSpec(key, extType as ExtensionType, extName);
           if (!argSpec) {
             throw new ReferenceError(
-              `Unknown argument with key ${key}, extType ${extType} and extName ${extName}. This is a bug.`
+              `Unknown argument with key ${key}, extType ${extType} and extName ${extName}. This is a bug.`,
             );
           }
-          flattened.push({schema: _.cloneDeep(value as SchemaObject), argSpec});
+          flattened.push({schema: structuredClone(value as SchemaObject), argSpec});
         }
       }
     }
@@ -348,7 +362,7 @@ class AppiumSchema {
    */
   validate(value: any, ref = APPIUM_CONFIG_SCHEMA_ID): ErrorObject[] {
     const validator = this._getValidator(ref);
-    return !validator(value) && _.isArray(validator.errors) ? [...validator.errors] : [];
+    return !validator(value) && Array.isArray(validator.errors) ? [...validator.errors] : [];
   }
 
   /**
@@ -408,21 +422,21 @@ export class SchemaUnsupportedSchemaError extends TypeError {
     super(
       (() => {
         const msg = `Unsupported schema from ${extType} "${extName}":`;
-        if (_.isBoolean(schema)) {
+        if (typeof schema === 'boolean') {
           return `${msg} schema cannot be a boolean`;
         }
-        if (_.isPlainObject(schema)) {
+        if (util.isPlainObject(schema)) {
           if ((schema as any).$async) {
             return `${msg} schema cannot be an async schema`;
           }
           throw new TypeError(
             `schema IS supported; this error should not be thrown (this is a bug). value of schema: ${JSON.stringify(
-              schema
-            )}`
+              schema,
+            )}`,
           );
         }
         return `${msg} schema must be a plain object without a true "$async" property`;
-      })()
+      })(),
     );
     this.data = {schema, extType, extName};
   }

package/lib/{utils.ts → utils/hash.ts}

@@ -1,21 +1,3 @@
-import _ from 'lodash';
-import {node, fs} from '@appium/support';
-
-export const npmPackage = fs.readPackageJsonFrom(__dirname);
-
-/**
- * Returns the root directory of the Appium module (memoized).
- *
- * @throws {Error} If the appium module root cannot be determined.
- */
-export const getAppiumModuleRoot = _.memoize(function getAppiumModuleRoot(): string {
-  const selfRoot = node.getModuleRootSync('appium', __filename);
-  if (!selfRoot) {
-    throw new Error('Cannot find the appium module root. This is likely a bug in Appium.');
-  }
-  return selfRoot;
-});
-
 /**
  * Adler-32 checksum (see https://github.com/SheetJS/js-adler32).
  */
@@ -27,7 +9,8 @@ export function adler32(str: string, seed: number | null = null): number {
     a = seed & 0xffff;
     b = seed >>> 16;
   }
-  for (let i = 0; i < L;) {
+  let i = 0;
+  while (i < L) {
     let M = Math.min(L - i, 2918);
     while (M > 0) {
       let c = str.charCodeAt(i++);

package/lib/utils/index.ts

@@ -0,0 +1,23 @@
+export {adler32} from './hash';
+export {isPackageChanged} from './is-package-changed';
+export type {IsPackageChangedOptions, IsPackageChangedResult} from './is-package-changed';
+export {appiumPackageRoot, npmPackage} from './package-json';
+export {packageDidChange} from './package-changed';
+export {resolveFrom} from './resolve-from';
+export {
+  bindAll,
+  camelCase,
+  capitalize,
+  compact,
+  defaultsDeep,
+  difference,
+  getPath,
+  kebabCase,
+  mapKeys,
+  mapValues,
+  omitKeys,
+  pickBy,
+  pull,
+  setPath,
+  zip,
+} from './object';

package/lib/utils/is-package-changed.ts

@@ -0,0 +1,78 @@
+import {fs} from '@appium/support';
+import crypto from 'node:crypto';
+import path from 'node:path';
+
+export interface IsPackageChangedOptions {
+  cwd?: string;
+  hashFilename?: string;
+}
+
+export interface IsPackageChangedResult {
+  hash: string;
+  isChanged: boolean;
+  oldHash?: string;
+  writeHash: () => Promise<void>;
+}
+
+/**
+ * Detects whether `package.json` dependencies changed since the last hash write.
+ * Inlined from the `package-changed` package (lockfile support omitted; unused by Appium).
+ */
+export async function isPackageChanged(
+  options: IsPackageChangedOptions = {},
+): Promise<IsPackageChangedResult> {
+  const {hashFilename = '.packagehash', cwd = process.cwd()} = options;
+  const packagePath = await findPackageJson(cwd);
+  if (!packagePath) {
+    throw new Error(`Cannot find package.json travelling up from "${cwd}".`);
+  }
+
+  const packageHashPath = path.join(cwd, hashFilename);
+  const packageHashPathExists = await fs.exists(packageHashPath);
+  const recentDigest = await getPackageHash(packagePath);
+  const previousDigest = packageHashPathExists
+    ? await fs.readFile(packageHashPath, 'utf-8')
+    : undefined;
+  const isChanged = !packageHashPathExists || previousDigest !== recentDigest;
+
+  const writeHash = async () => {
+    await fs.writeFile(packageHashPath, recentDigest, 'utf-8');
+  };
+
+  return {
+    hash: recentDigest,
+    isChanged,
+    oldHash: previousDigest || undefined,
+    writeHash,
+  };
+}
+
+async function findPackageJson(cwd: string): Promise<string | undefined> {
+  let current = cwd;
+  while (true) {
+    const search = path.join(current, 'package.json');
+    if (await fs.exists(search)) {
+      return search;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return;
+    }
+    current = parent;
+  }
+}
+
+async function getPackageHash(packagePath: string): Promise<string> {
+  const contents = await fs.readFile(packagePath, 'utf-8');
+  const packageBlob = JSON.parse(contents) as {
+    dependencies?: Record<string, string>;
+    devDependencies?: Record<string, string>;
+  };
+  const dependencies = {
+    dependencies: packageBlob.dependencies ?? {},
+    devDependencies: packageBlob.devDependencies ?? {},
+  };
+  const hashSum = crypto.createHash('md5');
+  hashSum.update(Buffer.from(JSON.stringify(dependencies)));
+  return hashSum.digest('hex');
+}

package/lib/utils/object.ts

@@ -0,0 +1,312 @@
+import {util} from '@appium/support';
+
+const UNSAFE_PATH_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+
+/**
+ * Converts a string to kebab-case (for Appium CLI and schema property names).
+ *
+ * @param value - Input string
+ * @returns Kebab-cased string
+ */
+export function kebabCase(value: string): string {
+  return splitWords(value).join('-').toLowerCase();
+}
+
+/**
+ * Converts a string to camelCase.
+ *
+ * @param value - Input string
+ * @returns camelCased string
+ */
+export function camelCase(value: string): string {
+  const words = splitWords(value);
+  if (words.length === 0) {
+    return '';
+  }
+  return (
+    words[0].toLowerCase() +
+    words
+      .slice(1)
+      .map((w) => w.charAt(0).toUpperCase() + w.slice(1).toLowerCase())
+      .join('')
+  );
+}
+
+/**
+ * Uppercases the first character of a string.
+ *
+ * @param value - Input string
+ * @returns Capitalized string, or empty string when input is empty
+ */
+export function capitalize(value: string): string {
+  return value ? value.charAt(0).toUpperCase() + value.slice(1) : value;
+}
+
+/**
+ * Returns a shallow copy of `obj` without any of `keys`. Non-plain objects are returned unchanged.
+ *
+ * @param obj - Source object
+ * @param keys - Property names to omit
+ * @returns Shallow copy without the listed keys
+ */
+export function omitKeys<T extends Record<string, unknown>>(obj: T, keys: readonly string[]): T {
+  if (!util.isPlainObject(obj) || keys.length === 0) {
+    return obj;
+  }
+  const omit = new Set(keys);
+  return Object.fromEntries(Object.entries(obj).filter(([k]) => !omit.has(k))) as T;
+}
+
+/**
+ * Returns a shallow copy of `obj` whose entries pass `predicate`.
+ *
+ * @param obj - Source object
+ * @param predicate - Filter invoked with each value and key
+ * @returns Shallow copy containing only matching entries
+ */
+export function pickBy<T extends Record<string, unknown>>(
+  obj: T,
+  predicate: (value: T[keyof T], key: keyof T) => boolean,
+): Partial<T> {
+  return Object.fromEntries(
+    Object.entries(obj).filter(([key, value]) => predicate(value as T[keyof T], key as keyof T)),
+  ) as Partial<T>;
+}
+
+/**
+ * Returns an object with the same keys as `obj` and values transformed by `fn`.
+ *
+ * @param obj - Source object
+ * @param fn - Mapper invoked with each value and key
+ * @returns Object with transformed values
+ */
+export function mapValues<T extends Record<string, unknown>, R>(
+  obj: T,
+  fn: (value: T[keyof T], key: keyof T) => R,
+): Record<string, R> {
+  return Object.fromEntries(
+    Object.entries(obj).map(([key, value]) => [key, fn(value as T[keyof T], key as keyof T)]),
+  );
+}
+
+/**
+ * Returns an object with keys renamed by `fn` and original values preserved.
+ *
+ * @param obj - Source object
+ * @param fn - Key mapper invoked with each value and key
+ * @returns Object with renamed keys
+ */
+export function mapKeys<T extends Record<string, unknown>>(
+  obj: T,
+  fn: (value: T[keyof T], key: keyof T) => string,
+): Record<string, unknown> {
+  return Object.fromEntries(
+    Object.entries(obj).map(([key, value]) => [fn(value as T[keyof T], key as keyof T), value]),
+  );
+}
+
+/**
+ * Reads a dot-separated path on `obj`, returning `defaultValue` when any segment is missing.
+ *
+ * @param obj - Object to read from
+ * @param path - Dot-separated property path
+ * @param defaultValue - Value returned when the path cannot be resolved
+ * @returns Value at the path, or `defaultValue`
+ */
+export function getPath(obj: unknown, path: string, defaultValue?: unknown): unknown {
+  const parts = path.split('.');
+  let current: unknown = obj;
+  for (const part of parts) {
+    if (current == null || (typeof current !== 'object' && typeof current !== 'function')) {
+      return defaultValue;
+    }
+    current = (current as Record<string, unknown>)[part];
+  }
+  return current === undefined ? defaultValue : current;
+}
+
+/**
+ * Assigns `value` at a dot-separated path on `obj`, creating plain object segments as needed.
+ *
+ * No-ops when the path contains empty segments or keys that could trigger prototype pollution
+ * (`__proto__`, `constructor`, `prototype`).
+ *
+ * @param obj - Object to mutate
+ * @param path - Dot-separated property path
+ * @param value - Value to assign at the path
+ */
+export function setPath(obj: Record<string, unknown>, path: string, value: unknown): void {
+  const parts = path.split('.');
+  if (!parts.every(isSafePathKey)) {
+    return;
+  }
+  let current = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const part = parts[i];
+    const next = current[part];
+    if (!util.isPlainObject(next)) {
+      current[part] = {};
+    }
+    current = current[part] as Record<string, unknown>;
+  }
+  current[parts[parts.length - 1]] = value;
+}
+
+/**
+ * Binds listed methods on `obj` so they keep the correct `this` when passed as callbacks.
+ *
+ * @param obj - Target object
+ * @param methodNames - Method names to bind
+ * @returns `obj` (mutated in place)
+ */
+export function bindAll<T extends object>(obj: T, methodNames: readonly string[]): T {
+  for (const name of methodNames) {
+    const method = (obj as Record<string, unknown>)[name];
+    if (typeof method === 'function') {
+      (obj as Record<string, unknown>)[name] = method.bind(obj);
+    }
+  }
+  return obj;
+}
+
+/**
+ * Returns a copy of `arr` with falsy entries removed.
+ *
+ * @param arr - Input array
+ * @returns Array containing only truthy elements
+ */
+export function compact<T>(arr: Array<T | null | undefined | false | '' | 0>): T[] {
+  return arr.filter((x): x is T => Boolean(x));
+}
+
+/**
+ * Removes all occurrences of `values` from `arr` (mutates `arr`).
+ *
+ * @param arr - Array to modify
+ * @param values - Values to remove
+ * @returns `arr`
+ */
+export function pull<T>(arr: T[], ...values: T[]): T[] {
+  for (const v of values) {
+    let idx: number;
+    while ((idx = arr.indexOf(v)) !== -1) {
+      arr.splice(idx, 1);
+    }
+  }
+  return arr;
+}
+
+/**
+ * Zips two arrays into tuples `[a[i], b[i]]`.
+ *
+ * @param a - First array
+ * @param b - Second array
+ * @returns Array of zipped pairs
+ */
+export function zip<A, B>(a: readonly A[], b: readonly B[]): Array<[A, B | undefined]> {
+  return a.map((item, i) => [item, b[i]]);
+}
+
+/**
+ * Returns elements in `a` that are not present in `b`.
+ *
+ * @param a - Source array
+ * @param b - Values to exclude
+ * @returns Filtered array
+ */
+export function difference<T>(a: readonly T[], b: readonly T[]): T[] {
+  const bSet = new Set(b);
+  return a.filter((x) => !bSet.has(x));
+}
+
+/**
+ * Deep-defaults merge: each source fills only `undefined` properties in the result (recursive for plain objects).
+ *
+ * @param sources - Objects merged in order; null/undefined sources are skipped
+ * @returns Merged object
+ */
+export function defaultsDeep<T extends Record<string, unknown>>(
+  ...sources: Array<Partial<T> | undefined>
+): T {
+  let result: Record<string, unknown> = {};
+  for (const source of sources) {
+    if (source == null) {
+      continue;
+    }
+    result = fillUndefinedDeep(result, source as Record<string, unknown>);
+  }
+  return result as T;
+}
+
+/**
+ * Splits a string into words (lodash-compatible), including acronym boundaries.
+ *
+ * @param value - Input string
+ * @returns Word tokens
+ */
+function splitWords(value: string): string[] {
+  return value
+    .replace(/([A-Z]+)([A-Z][a-z])/g, '$1 $2')
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/[-_\s]+/g, ' ')
+    .trim()
+    .split(/\s+/)
+    .filter(Boolean);
+}
+
+function isSafePathKey(key: string): boolean {
+  return key.length > 0 && !UNSAFE_PATH_KEYS.has(key);
+}
+
+/**
+ * Copies a value for {@link defaultsDeep}: plain objects are copied recursively;
+ * other values (including functions) are reused by reference.
+ *
+ * @param value - Value to copy
+ * @returns Copy safe for further defaults merging
+ */
+function copyForDefaultsDeep(value: unknown): unknown {
+  if (!util.isPlainObject(value)) {
+    return value;
+  }
+  const out: Record<string, unknown> = {};
+  for (const [key, val] of Object.entries(value)) {
+    out[key] = copyForDefaultsDeep(val);
+  }
+  return out;
+}
+
+/**
+ * Fills `undefined` keys in a clone of `target` from `source` (recursive for plain objects).
+ *
+ * @param target - Destination object
+ * @param source - Default values
+ * @returns Merged clone
+ */
+function fillUndefinedDeep(
+  target: Record<string, unknown>,
+  source: Record<string, unknown>,
+): Record<string, unknown> {
+  const out = copyForDefaultsDeep(target) as Record<string, unknown>;
+  const stack: Array<{dest: Record<string, unknown>; src: Record<string, unknown>}> = [
+    {dest: out, src: source},
+  ];
+  while (stack.length) {
+    const next = stack.pop();
+    if (!next) {
+      continue;
+    }
+    const {dest, src} = next;
+    for (const [key, srcVal] of Object.entries(src)) {
+      const destVal = dest[key];
+      if (destVal === undefined) {
+        dest[key] = copyForDefaultsDeep(srcVal);
+        continue;
+      }
+      if (util.isPlainObject(destVal) && util.isPlainObject(srcVal)) {
+        stack.push({dest: destVal, src: srcVal});
+      }
+    }
+  }
+  return out;
+}