Merge branch 'next' into feat/multi-apiml-support-v3

packages/zowe-explorer-api/CHANGELOG.md

@@ -39,6 +39,67 @@ All notable changes to the "zowe-explorer-api" extension will be documented in t
 - Added the `onVaultUpdate` VSCode event to notify extenders when credentials are updated on the OS vault by other applications. [#2994](https://github.com/zowe/zowe-explorer-vscode/pull/2994)
 - Added the `onCredMgrsUpdate` VSCode event to notify extenders when the local PC's credential manager has been updated by other applications. [#2994](https://github.com/zowe/zowe-explorer-vscode/pull/2994)
 - **Breaking:** Updated most function signatures for exported programmatic interfaces. Changes make developing with the Zowe Explorer API more efficient for extenders by showing which properties they can expect when calling our APIs. [#2952](https://github.com/zowe/zowe-explorer-vscode/issues/2952)
+- **LTS Breaking:** Updated most function signatures for exported programmatic interfaces. Changes make developing with the Zowe Explorer API more efficient for extenders by showing which properties they can expect when calling our APIs. [#2952](https://github.com/zowe/zowe-explorer-vscode/issues/2952)
+
+  - Updated `IApiExplorerExtender.ts`, see changes below:
+    - Allowed `reloadProfiles` and `initForZowe` to be synchronous methods (non-breaking)
+  - Updated `MainframeInteraction.ts`, see changes below:
+    - Modified `getStatus` to add `string` type to the optional parameter `profileType`
+  - Updated `IZoweTree.ts`, see changes below:
+
+    - Modified `checkCurrentProfile(node: IZoweTreeNode);` to return `Validation.IValidationProfile | Promise<Validation.IValidationProfile>`
+    - Modified `getSearchHistory()` to return `string[]`
+    - Modified `getAllLoadedItems()` to return `IZoweTreeNode[] | Promise<IZoweTreeNode[]>`
+    - Modified `getFileHistory()` to return `string[]`
+    - Modified `createFilterString?(newFilter: string, node: IZoweTreeNode);` to return `string`
+    - Allowed the following methods to be implemented synchronously: (non-breaking)
+      - `addSession`
+      - `addSingleSession`
+      - `editSession`
+      - `createZoweSession`
+      - `createZoweSchema`
+      - `ssoLogin`
+      - `ssoLogout`
+      - `addFavorite`
+      - `removeFavorite`
+      - `removeFavProfile`
+      - `onDidChangeConfiguration`
+      - `flipState` _synchronous - no `Promise` returned_
+      - `rename`
+      - `open`
+      - `copy`
+      - `paste`
+      - `delete`
+      - `setItem` _synchronous - no `Promise` returned_
+      - `saveSearch`
+      - `saveFile`
+      - `refreshPS`
+      - `uploadDialog`
+      - `filterPrompt`
+      - `addSearchHistory` _synchronous - no `Promise` returned_
+      - `deleteSession` _synchronous - no `Promise` returned_
+      - `updateFavorites`
+      - `renameFavorite`
+      - `addFileHistory` _synchronous - no `Promise` returned_
+      - `removeFileHistory` _synchronous - no `Promise` returned_
+      - `renameNode`
+      - `openItemFromPath`
+      - `addDsTemplate`
+      - `pollData`
+      - `openWithEncoding`
+
+    **Note**: Developers should not expect a value to be returned from the methods above (breaking)
+
+  - Updated `IZoweTreeNode.ts`, see changes below:
+    - Modified `rename?(newNamePath: string);` to return `Promise<IZosFilesResponse>`
+    - Developers should not be expecting output from the following methods:
+      - `openUSS`
+      - `refreshUSS`
+      - `deleteUSSNode`
+      - `renameUSSNode`
+      - `reopen`
+      - `saveSearch`
+
 - Enhanced the `ZoweVsCodeExtension.loginWithBaseProfile` and `ZoweVsCodeExtension.logoutWithBaseProfile` methods to store SSO token in parent profile when nested profiles are in use. [#2264](https://github.com/zowe/zowe-explorer-vscode/issues/2264)
 - **Next Breaking:** Changed return type of `ZoweVsCodeExtension.logoutWithBaseProfile` method from `void` to `boolean` to indicate whether logout was successful.
 

packages/zowe-explorer-api/__mocks__/vscode.ts

@@ -136,7 +136,7 @@ export class CancellationTokenSource {
 }
 
 export namespace extensions {
-    export function getExtension(identifier: string) {
+    export function getExtension(_identifier: string): { packageJSON: { version: string } } {
         return {
             packageJSON: {
                 version: "2.0.0",
@@ -289,32 +289,32 @@ export namespace window {
      * @param items A set of items that will be rendered as actions in the message.
      * @return A thenable that resolves to the selected item or `undefined` when being dismissed.
      */
-    export function showInformationMessage(message: string, ...items: string[]): Thenable<string> {
+    export function showInformationMessage(_message: string, ..._items: string[]): Thenable<string> {
         return Promise.resolve("");
     }
 
-    export function showErrorMessage(message: string, ...items: string[]): undefined {
+    export function showErrorMessage(_message: string, ..._items: string[]): undefined {
         return undefined;
     }
 
-    export function showWarningMessage(message: string, ...items: string[]): undefined {
+    export function showWarningMessage(_message: string, ..._items: string[]): undefined {
         return undefined;
     }
 
-    export function setStatusBarMessage(message: string, ...items: string[]): undefined {
+    export function setStatusBarMessage(_message: string, ..._items: string[]): undefined {
         return undefined;
     }
 
-    export function createQuickPick<T extends QuickPickItem>(): QuickPick<T> {
+    export function createQuickPick<T extends QuickPickItem>(): QuickPick<T> | undefined {
         return undefined;
     }
 
     export function showQuickPick<T extends QuickPickItem>(
-        items: readonly T[] | Thenable<readonly T[]>,
-        options?: QuickPickOptions & { canPickMany: true },
-        token?: CancellationToken
+        _items: readonly T[] | Thenable<readonly T[]>,
+        _options?: QuickPickOptions & { canPickMany: true },
+        _token?: CancellationToken
     ): Thenable<T[] | undefined> {
-        return undefined;
+        return Promise.resolve(undefined);
     }
 
     /**
@@ -360,11 +360,11 @@ export namespace commands {
      * @param thisArg The `this` context used when invoking the handler function.
      * @return Disposable which unregisters this command on disposal.
      */
-    export function registerCommand(command: string, callback: (...args: any[]) => any, thisArg?: any): Disposable {
+    export function registerCommand(_command: string, callback: (...args: any[]) => any, _thisArg?: any): Disposable | undefined {
         return undefined;
     }
 
-    export function executeCommand(command: string): undefined {
+    export function executeCommand(_command: string): undefined {
         return undefined;
     }
 }
@@ -377,7 +377,7 @@ export class Disposable {
     constructor() {}
 }
 
-export function RelativePattern(base: string, pattern: string) {
+export function RelativePattern(_base: string, _pattern: string): {} {
     return {};
 }
 
@@ -430,7 +430,7 @@ export class Uri {
     public static file(path: string): Uri {
         return Uri.parse(path);
     }
-    public static parse(value: string, strict?: boolean): Uri {
+    public static parse(value: string, _strict?: boolean): Uri {
         const newUri = new Uri();
         newUri.path = value;
 
@@ -722,7 +722,7 @@ export class EventEmitter<T> {
      *
      * @param data The event object.
      */
-    fire(data?: T): void {}
+    fire(_data?: T): void {}
 
     /**
      * Dispose this object and free resources.
@@ -827,7 +827,7 @@ export class FileSystemError extends Error {
      * Create an error to signal that a file or folder wasn't found.
      * @param messageOrUri Message or uri.
      */
-    static FileNotFound(messageOrUri?: string | Uri): FileSystemError {
+    static FileNotFound(_messageOrUri?: string | Uri): FileSystemError {
         return new FileSystemError("file not found");
     }
 
@@ -836,31 +836,31 @@ export class FileSystemError extends Error {
      * creating but not overwriting a file.
      * @param messageOrUri Message or uri.
      */
-    static FileExists(messageOrUri?: string | Uri): FileSystemError {
+    static FileExists(_messageOrUri?: string | Uri): FileSystemError {
         return new FileSystemError("file exists");
     }
 
     /**
      * Create an error to signal that a file is not a folder.
      * @param messageOrUri Message or uri.
      */
-    static FileNotADirectory(messageOrUri?: string | Uri): FileSystemError {
+    static FileNotADirectory(_messageOrUri?: string | Uri): FileSystemError {
         return new FileSystemError("file not a directory");
     }
 
     /**
      * Create an error to signal that a file is a folder.
      * @param messageOrUri Message or uri.
      */
-    static FileIsADirectory(messageOrUri?: string | Uri): FileSystemError {
+    static FileIsADirectory(_messageOrUri?: string | Uri): FileSystemError {
         return new FileSystemError("file is a directory");
     }
 
     /**
      * Create an error to signal that an operation lacks required permissions.
      * @param messageOrUri Message or uri.
      */
-    static NoPermissions(messageOrUri?: string | Uri): FileSystemError {
+    static NoPermissions(_messageOrUri?: string | Uri): FileSystemError {
         return new FileSystemError("no permissions");
     }
 
@@ -869,7 +869,7 @@ export class FileSystemError extends Error {
      * complete a request.
      * @param messageOrUri Message or uri.
      */
-    static Unavailable(messageOrUri?: string | Uri): FileSystemError {
+    static Unavailable(_messageOrUri?: string | Uri): FileSystemError {
         return new FileSystemError("unavailable");
     }
 
@@ -902,7 +902,7 @@ export class FileSystemError extends Error {
  */
 export namespace workspace {
     export const textDocuments: TextDocument[] = [];
-    export function getConfiguration(configuration: string) {
+    export function getConfiguration(_configuration: string): { update: () => void; inspect: () => void } {
         return {
             update: () => {
                 return;
@@ -913,19 +913,19 @@ export namespace workspace {
         };
     }
 
-    export function createFileSystemWatcher() {
+    export function createFileSystemWatcher(): { onDidCreate: () => void; onDidChange: () => void; onDidDelete: () => void } {
         return {
             onDidCreate: () => {},
             onDidChange: () => {},
             onDidDelete: () => {},
         };
     }
 
-    export function onDidCloseTextDocument(event) {
+    export function onDidCloseTextDocument(_event): Disposable {
         return Disposable;
     }
 
-    export function onWillSaveTextDocument(event) {
+    export function onWillSaveTextDocument(_event): Disposable {
         return Disposable;
     }
 
@@ -966,7 +966,7 @@ export namespace workspace {
          * @returns The file metadata about the file.
          * @throws {@linkcode FileSystemError.FileNotFound FileNotFound} when `uri` doesn't exist.
          */
-        export function stat(uri: Uri): FileStat | Thenable<FileStat> {
+        export function stat(_uri: Uri): FileStat | Thenable<FileStat> {
             return {} as FileStat;
         }
 
@@ -977,7 +977,7 @@ export namespace workspace {
          * @returns An array of name/type-tuples or a thenable that resolves to such.
          * @throws {@linkcode FileSystemError.FileNotFound FileNotFound} when `uri` doesn't exist.
          */
-        export function readDirectory(uri: Uri): Array<[string, FileType]> | Thenable<Array<[string, FileType]>> {
+        export function readDirectory(_uri: Uri): Array<[string, FileType]> | Thenable<Array<[string, FileType]>> {
             return [];
         }
 
@@ -989,7 +989,7 @@ export namespace workspace {
          * @throws {@linkcode FileSystemError.FileExists FileExists} when `uri` already exists.
          * @throws {@linkcode FileSystemError.NoPermissions NoPermissions} when permissions aren't sufficient.
          */
-        export function createDirectory(uri: Uri): void | Thenable<void> {
+        export function createDirectory(_uri: Uri): void | Thenable<void> {
             return;
         }
 
@@ -1000,7 +1000,7 @@ export namespace workspace {
          * @returns An array of bytes or a thenable that resolves to such.
          * @throws {@linkcode FileSystemError.FileNotFound FileNotFound} when `uri` doesn't exist.
          */
-        export function readFile(uri: Uri): Uint8Array | Thenable<Uint8Array> {
+        export function readFile(_uri: Uri): Uint8Array | Thenable<Uint8Array> {
             return new Uint8Array();
         }
 
@@ -1016,9 +1016,9 @@ export namespace workspace {
          * @throws {@linkcode FileSystemError.NoPermissions NoPermissions} when permissions aren't sufficient.
          */
         export function writeFile(
-            uri: Uri,
-            content: Uint8Array,
-            options: {
+            _uri: Uri,
+            _content: Uint8Array,
+            _options: {
                 /**
                  * Create the file if it does not exist already.
                  */
@@ -1044,9 +1044,9 @@ export namespace workspace {
          * @throws {@linkcode FileSystemError.NoPermissions NoPermissions} when permissions aren't sufficient.
          */
         export function rename(
-            oldUri: Uri,
-            newUri: Uri,
-            options: {
+            _oldUri: Uri,
+            _newUri: Uri,
+            _options: {
                 /**
                  * Overwrite the file if it does exist.
                  */
@@ -1069,9 +1069,9 @@ export namespace workspace {
          * @throws {@linkcode FileSystemError.NoPermissions NoPermissions} when permissions aren't sufficient.
          */
         export function copy(
-            source: Uri,
-            destination: Uri,
-            options: {
+            _source: Uri,
+            _destination: Uri,
+            _options: {
                 /**
                  * Overwrite the file if it does exist.
                  */
@@ -1120,7 +1120,7 @@ export namespace env {
      * The system clipboard.
      */
     export const clipboard: Clipboard = {
-        writeText() {
+        writeText(): Thenable<void> {
             return Promise.resolve();
         },
     };

packages/zowe-explorer-api/src/extend/IApiExplorerExtender.ts

@@ -37,12 +37,12 @@ export interface IApiExplorerExtender {
      * to make them automatically appears in the Explorer drop-
      * down dialogs.
      */
-    reloadProfiles(profileType?: string): Promise<void>;
+    reloadProfiles(profileType?: string): void | Promise<void>;
 
     /**
      * After an extenders registered all its API extensions it
      * might want to check for an existing profile folder with meta-file
      * or to create them automatically if it is non-existant.
      */
-    initForZowe(type: string, profileTypeConfigurations: imperative.ICommandProfileTypeConfiguration[]): Promise<void>;
+    initForZowe(type: string, profileTypeConfigurations: imperative.ICommandProfileTypeConfiguration[]): void | Promise<void>;
 }

packages/zowe-explorer-api/src/extend/MainframeInteraction.ts

@@ -40,13 +40,13 @@ export namespace MainframeInteraction {
         getSession(profile?: imperative.IProfileLoaded): imperative.Session;
 
         /**
-         * Create a session for the specific profile type.
+         * Retrieve the status of a specific profile.
          *
-         * @param {imperative.IProfileLoaded} profile
-         *      will use the profile the API was retrieved with by default
-         * @returns {IZosmfInfoResponse} z/OSMF Check Status response
+         * @param {imperative.IProfileLoaded} profile the profile for which we will retrieve the status
+         * @param {string} profileType the type of profile being requested
+         * @returns {Promise<string>} The status of the profile (e.g. active, inactive, unverified)
          */
-        getStatus?(profile: imperative.IProfileLoaded, profileType?): Promise<string>;
+        getStatus?(profile: imperative.IProfileLoaded, profileType?: string): Promise<string>;
 
         /**
          * Create a session for a set command arguments. The session will be created independent

packages/zowe-explorer-api/src/fs/types/abstract.ts

@@ -40,7 +40,7 @@ export class BufferBuilder extends Duplex {
         this.chunks = [];
     }
 
-    public _write(chunk: any, encoding: BufferEncoding, callback: (error?: Error) => void): void {
+    public _write(chunk: any, _encoding: BufferEncoding, callback: (error?: Error) => void): void {
         this.chunks.push(chunk);
         callback();
     }