appium 2.0.0-beta.46 → 2.0.0-beta.48

package/lib/extension/extension-config.js

@@ -33,13 +33,18 @@ const INSTALL_TYPES = new Set([
  * @template {ExtensionType} ExtType
  */
 export class ExtensionConfig {
-  /** @type {ExtType} */
+  /**
+   * The type of extension this class is responsible for.
+   * @type {ExtType}
+   */
   extensionType;
 
-  /** @type {`${ExtType}s`} */
-  configKey;
-
-  /** @type {ExtRecord<ExtType>} */
+  /**
+   * Manifest data for the extensions of this type.
+   *
+   * This data should _not_ be written to by anything but {@linkcode Manifest}.
+   * @type {Readonly<ExtRecord<ExtType>>}
+   */
   installedExtensions;
 
   /** @type {import('@appium/types').AppiumLogger} */
@@ -49,9 +54,9 @@ export class ExtensionConfig {
   manifest;
 
   /**
-   * @type {ExtensionListData}
+   * @type {ExtensionListData|undefined}
    */
-  _listDataCache;
+  #listDataCache;
 
   /**
    * @protected
@@ -60,7 +65,6 @@ export class ExtensionConfig {
    */
   constructor(extensionType, manifest) {
     this.extensionType = extensionType;
-    this.configKey = `${extensionType}s`;
     this.installedExtensions = manifest.getExtensionData(extensionType);
     this.manifest = manifest;
   }
@@ -204,8 +208,8 @@ export class ExtensionConfig {
     if (!_.isEmpty(errorSummaries)) {
       log.error(
         `Appium encountered ${util.pluralize('error', errorMap.size, true)} while validating ${
-          this.configKey
-        } found in manifest ${this.manifestPath}`
+          this.extensionType
+        }s found in manifest ${this.manifestPath}`
       );
       for (const summary of errorSummaries) {
         log.error(summary);
@@ -219,7 +223,7 @@ export class ExtensionConfig {
             'warning',
             warningMap.size,
             true
-          )} while validating ${this.configKey} found in manifest ${this.manifestPath}`
+          )} while validating ${this.extensionType}s found in manifest ${this.manifestPath}`
         );
         for (const summary of warningSummaries) {
           log.warn(summary);
@@ -231,18 +235,20 @@ export class ExtensionConfig {
 
   /**
    * Retrieves listing data for extensions via command class.
-   * Caches the result in {@linkcode ExtensionConfig._listDataCache}
+   *
+   * This is an expensive operation, so the result is cached.  Currently, there is no
+   * use case for invalidating the cache.
    * @protected
    * @returns {Promise<ExtensionListData>}
    */
   async getListData() {
-    if (this._listDataCache) {
-      return this._listDataCache;
+    if (this.#listDataCache) {
+      return this.#listDataCache;
     }
     const CommandClass = /** @type {ExtCommand<ExtType>} */ (commandClasses[this.extensionType]);
     const cmd = new CommandClass({config: this, json: true});
     const listData = await cmd.list({showInstalled: true, showUpdates: true});
-    this._listDataCache = listData;
+    this.#listDataCache = listData;
     return listData;
   }
 
@@ -433,7 +439,7 @@ export class ExtensionConfig {
    * @returns {Promise<void>}
    */
   async addExtension(extName, extManifest, {write = true} = {}) {
-    this.manifest.addExtension(this.extensionType, extName, extManifest);
+    this.manifest.setExtension(this.extensionType, extName, extManifest);
     if (write) {
       await this.manifest.write();
     }
@@ -441,15 +447,15 @@ export class ExtensionConfig {
 
   /**
    * @param {ExtName<ExtType>} extName
-   * @param {ExtManifest<ExtType>|import('../cli/extension-command').ExtensionFields<ExtType>} extManifest
+   * @param {ExtManifest<ExtType>} extManifest
    * @param {ExtensionConfigMutationOpts} [opts]
    * @returns {Promise<void>}
    */
   async updateExtension(extName, extManifest, {write = true} = {}) {
-    this.installedExtensions[extName] = {
+    this.manifest.setExtension(this.extensionType, extName, {
       ...this.installedExtensions[extName],
       ...extManifest,
-    };
+    });
     if (write) {
       await this.manifest.write();
     }
@@ -463,7 +469,7 @@ export class ExtensionConfig {
    * @returns {Promise<void>}
    */
   async removeExtension(extName, {write = true} = {}) {
-    delete this.installedExtensions[extName];
+    this.manifest.deleteExtension(this.extensionType, extName);
     if (write) {
       await this.manifest.write();
     }
@@ -477,13 +483,13 @@ export class ExtensionConfig {
   print(activeNames) {
     if (_.isEmpty(this.installedExtensions)) {
       log.info(
-        `No ${this.configKey} have been installed in ${this.appiumHome}. Use the "appium ${this.extensionType}" ` +
+        `No ${this.extensionType}s have been installed in ${this.appiumHome}. Use the "appium ${this.extensionType}" ` +
           'command to install the one(s) you want to use.'
       );
       return;
     }
 
-    log.info(`Available ${this.configKey}:`);
+    log.info(`Available ${this.extensionType}s:`);
     for (const [extName, extManifest] of /** @type {[string, ExtManifest<ExtType>][]} */ (
       _.toPairs(this.installedExtensions)
     )) {
@@ -504,11 +510,17 @@ export class ExtensionConfig {
   }
 
   /**
-   * @param {string} extName
+   * Returns--with reasonable accuracy--the path on disk to the extension.
+   *
+   * If `installPath` is present in the manifest, then it is used; otherwise we just guess.
+   * @param {keyof typeof this.installedExtensions} extName
    * @returns {string}
    */
   getInstallPath(extName) {
-    return path.join(this.appiumHome, 'node_modules', this.installedExtensions[extName].pkgName);
+    return (
+      this.installedExtensions[extName]?.installPath ??
+      path.join(this.appiumHome, 'node_modules', this.installedExtensions[extName].pkgName)
+    );
   }
 
   /**
@@ -546,7 +558,7 @@ export class ExtensionConfig {
    * @returns {boolean}
    */
   isInstalled(extName) {
-    return _.includes(Object.keys(this.installedExtensions), extName);
+    return extName in this.installedExtensions;
   }
 
   /**
@@ -628,36 +640,39 @@ export {INSTALL_TYPE_NPM, INSTALL_TYPE_GIT, INSTALL_TYPE_LOCAL, INSTALL_TYPE_GIT
 /**
  * @typedef {import('@appium/types').ExtensionType} ExtensionType
  * @typedef {import('./manifest').Manifest} Manifest
+ * @typedef {import('../cli/extension-command').ExtensionListData} ExtensionListData
+ * @typedef {import('../cli/extension-command').InstalledExtensionListData} InstalledExtensionListData
+ * @typedef {import('appium/types').InstallType} InstallType
  */
 
 /**
- * @template T
- * @typedef {import('appium/types').ExtManifest<T>} ExtManifest
+ * @template {ExtensionType} ExtType
+ * @typedef {import('appium/types').ExtManifest<ExtType>} ExtManifest
  */
 
 /**
- * @template T
- * @typedef {import('appium/types').ExtManifestWithSchema<T>} ExtManifestWithSchema
+ * @template {ExtensionType} ExtType
+ * @typedef {ExtManifest<ExtType> & {schema: NonNullable<ExtManifest<ExtType>['schema']>}} ExtManifestWithSchema
  */
 
 /**
- * @template T
- * @typedef {import('appium/types').ExtName<T>} ExtName
+ * @template {ExtensionType} ExtType
+ * @typedef {import('appium/types').ExtName<ExtType>} ExtName
  */
 
 /**
- * @template T
- * @typedef {import('appium/types').ExtClass<T>} ExtClass
+ * @template {ExtensionType} ExtType
+ * @typedef {import('appium/types').ExtClass<ExtType>} ExtClass
  */
 
 /**
- * @template T
- * @typedef {import('appium/types').ExtRecord<T>} ExtRecord
+ * @template {ExtensionType} ExtType
+ * @typedef {import('appium/types').ExtRecord<ExtType>} ExtRecord
  */
 
 /**
- * @template T
- * @typedef {import('../cli/extension').ExtCommand<T>} ExtCommand
+ * @template {ExtensionType} ExtType
+ * @typedef {import('../cli/extension').ExtCommand<ExtType>} ExtCommand
  */
 
 /**
@@ -665,13 +680,3 @@ export {INSTALL_TYPE_NPM, INSTALL_TYPE_GIT, INSTALL_TYPE_LOCAL, INSTALL_TYPE_GIT
  * @typedef ExtensionConfigMutationOpts
  * @property {boolean} [write=true] Whether or not to write the manifest to disk after a mutation operation
  */
-
-/**
- * A valid install type
- * @typedef {typeof INSTALL_TYPE_NPM | typeof INSTALL_TYPE_GIT | typeof INSTALL_TYPE_LOCAL | typeof INSTALL_TYPE_GITHUB} InstallType
- */
-
-/**
- * @typedef {import('../cli/extension-command').ExtensionListData} ExtensionListData
- * @typedef {import('../cli/extension-command').InstalledExtensionListData} InstalledExtensionListData
- */

package/lib/extension/manifest-migrations.js

@@ -0,0 +1,120 @@
+import {DRIVER_TYPE, PLUGIN_TYPE} from '../constants';
+import log from '../logger';
+
+/**
+ * This contains logic to migrate old versions of `extensions.yaml` to new versions.
+ *
+ * @module
+ */
+
+/**
+ * Constant for v3 of the schema rev.
+ */
+const SCHEMA_REV_3 = 3;
+
+/**
+ * Collection of functions to migrate from one version to another.
+ *
+ * These functions _should not actually perform the migration_; rather, they
+ * should return `true` if the migration should be performed.  The migration
+ * itself will happen within {@linkcode Manifest.syncWithInstalledExtensions}; the extensions
+ * will be checked and the manifest file updated per the state of the filesystem.
+ *
+ * @type {{[P in keyof ManifestDataVersions]?: Migration}}
+ */
+const Migrations = {
+  /**
+   * If `installPath` is missing from the `ExtManifest` for any extension, return `true`.
+   *
+   * We cannot easily determine the path of any given extension here, but returning `true`
+   * will cause the `Manifest` to sync with the filesystem, which will populate the missing field.
+   *
+   * @type {Migration}
+   */
+  [SCHEMA_REV_3]: (manifest) => {
+    let shouldSync = false;
+    /** @type {Array<ExtManifest<PluginType>|ExtManifest<DriverType>>} */
+    const allExtData = [
+      ...Object.values(manifest.getExtensionData(DRIVER_TYPE)),
+      ...Object.values(manifest.getExtensionData(PLUGIN_TYPE)),
+    ];
+    for (const metadata of allExtData) {
+      if (!('installPath' in metadata)) {
+        shouldSync = true;
+        break;
+      }
+    }
+    return shouldSync;
+  },
+};
+
+/**
+ * Set `schemaRev` to a specific version.
+ *
+ * This _does_ mutate `data` in-place, unlike functions in
+ * {@linkcode Migrations}.
+ *
+ * Again, returning `true` means that the manifest should be--at
+ * minimum--persisted to disk, since we changed it.
+ * @param {Readonly<Manifest>} manifest
+ * @param {keyof ManifestDataVersions} version
+ * @returns {boolean} Whether the data was modified
+ */
+function setSchemaRev(manifest, version) {
+  if (manifest.schemaRev ?? 0 < version) {
+    manifest.setSchemaRev(version);
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Applies a series of migration functions to a manifest to update its manifest schema version.
+ *
+ * `data` is modified in-place.
+ *
+ * @param {Readonly<Manifest>} manifest
+ * @returns {Promise<boolean>} If `true` existing packages should be synced from disk and the manifest should be persisted.
+ */
+export async function migrate(manifest) {
+  let didChange = false;
+  for await (const [v, migration] of Object.entries(Migrations)) {
+    const version = /** @type {keyof ManifestDataVersions} */ (Number(v));
+    didChange = (await migration(manifest)) || didChange;
+    didChange = setSchemaRev(manifest, version) || didChange;
+  }
+
+  if (didChange) {
+    // this is not _technically_ true, since we don't actually write the file here.
+    log.info(`Upgraded extension manifest to schema v${manifest.schemaRev}`);
+  }
+
+  return didChange;
+}
+
+/**
+ * A migration function. It will return `true` if a change _should be made_.
+ *
+ * A migration function should not modify `schemaRev`, as this is done automatically.
+ *
+ * Note that at the time of writing, we're not able to determine the version of the _current_ manifest file if there is no `schemaRev` prop present (and we may not want to trust it anyway).
+ * @callback Migration
+ * @param {Readonly<Manifest>} manifest - The `Manifest` instance
+ * @returns {boolean|Promise<boolean>} If `true`, then something changed
+ */
+
+/**
+ * @typedef {import('appium/types').ManifestData} ManifestData
+ * @typedef {import('@appium/types').DriverType} DriverType
+ * @typedef {import('@appium/types').PluginType} PluginType
+ * @typedef {import('appium/types').AnyManifestDataVersion} AnyManifestDataVersion
+ * @typedef {import('appium/types').ManifestDataVersions} ManifestDataVersions
+ * @typedef {import('@appium/types').ExtensionType} ExtensionType
+ * @typedef {import('appium/types').ManifestV2.ManifestData} ManifestDataV2
+ * @typedef {import('./manifest').Manifest} Manifest
+ */
+
+/**
+ * @template {ExtensionType} ExtType
+ * @typedef {import('appium/types').ExtManifest<ExtType>} ExtManifest
+ */