Error correlator and troubleshoot webview

packages/zowe-explorer-api/CHANGELOG.md

@@ -18,6 +18,7 @@ All notable changes to the "zowe-explorer-api" extension will be documented in t
 
 - Zowe Explorer now includes support for the [VS Code display languages](https://code.visualstudio.com/docs/getstarted/locales) French, German, Japanese, Portuguese, and Spanish. [#3239](https://github.com/zowe/zowe-explorer-vscode/pull/3239)
 - Localization of strings within the webviews. [#2983](https://github.com/zowe/zowe-explorer-vscode/issues/2983)
+- Leverage the new error correlation facility to provide user-friendly summaries of API and network errors. Extenders can also contribute to the correlator to provide human-readable translations of error messages, as well as tips and additional resources for how to resolve the error. [#3243](https://github.com/zowe/zowe-explorer-vscode/pull/3243)
 
 ## `3.0.1`
 

packages/zowe-explorer-api/__tests__/__unit__/fs/BaseProvider.unit.test.ts

@@ -13,6 +13,7 @@ import * as vscode from "vscode";
 import { BaseProvider, ConflictViewSelection, DirEntry, FileEntry, ZoweScheme } from "../../../src/fs";
 import { Gui } from "../../../src/globals";
 import { MockedProperty } from "../../../__mocks__/mockUtils";
+import { ErrorCorrelator, ZoweExplorerApiType } from "../../../src";
 
 function getGlobalMocks(): { [key: string]: any } {
     return {
@@ -542,6 +543,35 @@ describe("_handleConflict", () => {
         expect(diffOverwriteMock).toHaveBeenCalledWith(globalMocks.testFileUri);
     });
 });
+describe("_handleError", () => {
+    it("calls ErrorCorrelator.displayError to display error to user - no options provided", async () => {
+        const displayErrorMock = jest.spyOn(ErrorCorrelator.prototype, "displayError").mockReturnValue(new Promise((res, rej) => {}));
+        const prov = new (BaseProvider as any)();
+        prov._handleError(new Error("example"));
+        expect(displayErrorMock).toHaveBeenCalledWith(ZoweExplorerApiType.All, new Error("example"), {
+            additionalContext: undefined,
+            allowRetry: false,
+            profileType: "any",
+            templateArgs: undefined,
+        });
+    });
+    it("calls ErrorCorrelator.displayError to display error to user - options provided", async () => {
+        const displayErrorMock = jest.spyOn(ErrorCorrelator.prototype, "displayError").mockReturnValue(new Promise((res, rej) => {}));
+        const prov = new (BaseProvider as any)();
+        prov._handleError(new Error("example"), {
+            additionalContext: "Failed to list data sets",
+            apiType: ZoweExplorerApiType.Mvs,
+            profileType: "zosmf",
+            templateArgs: {},
+        });
+        expect(displayErrorMock).toHaveBeenCalledWith(ZoweExplorerApiType.Mvs, new Error("example"), {
+            additionalContext: "Failed to list data sets",
+            allowRetry: false,
+            profileType: "zosmf",
+            templateArgs: {},
+        });
+    });
+});
 
 describe("_relocateEntry", () => {
     it("returns early if the entry does not exist in the file system", () => {

packages/zowe-explorer-api/__tests__/__unit__/profiles/ProfilesCache.unit.test.ts

@@ -317,6 +317,21 @@ describe("ProfilesCache", () => {
             expect(profCache.getAllTypes()).toEqual([...profileTypes, "ssh", "base"]);
         });
 
+        it("should refresh profile data for existing profile and keep object reference", async () => {
+            const profCache = new ProfilesCache(fakeLogger as unknown as imperative.Logger);
+            const profInfoSpy = jest.spyOn(profCache, "getProfileInfo").mockResolvedValue(createProfInfoMock([lpar1Profile, zftpProfile]));
+            await profCache.refresh(fakeApiRegister as unknown as Types.IApiRegisterClient);
+            expect(profCache.allProfiles.length).toEqual(2);
+            expect(profCache.allProfiles[0]).toMatchObject(lpar1Profile);
+            const oldZosmfProfile = profCache.allProfiles[0];
+            const newZosmfProfile = { ...lpar1Profile, profile: lpar2Profile.profile };
+            profInfoSpy.mockResolvedValue(createProfInfoMock([newZosmfProfile, zftpProfile]));
+            await profCache.refresh(fakeApiRegister as unknown as Types.IApiRegisterClient);
+            expect(profCache.allProfiles.length).toEqual(2);
+            expect(profCache.allProfiles[0]).toMatchObject(newZosmfProfile);
+            expect(oldZosmfProfile.profile).toEqual(newZosmfProfile.profile);
+        });
+
         it("should refresh profile data for and merge tokens with base profile", async () => {
             const profCache = new ProfilesCache(fakeLogger as unknown as imperative.Logger);
             jest.spyOn(profCache, "getProfileInfo").mockResolvedValue(

packages/zowe-explorer-api/__tests__/__unit__/utils/ErrorCorrelator.unit.test.ts

@@ -0,0 +1,148 @@
+/**
+ * This program and the accompanying materials are made available under the terms of the
+ * Eclipse Public License v2.0 which accompanies this distribution, and is available at
+ * https://www.eclipse.org/legal/epl-v20.html
+ *
+ * SPDX-License-Identifier: EPL-2.0
+ *
+ * Copyright Contributors to the Zowe Project.
+ *
+ */
+
+import { ErrorCorrelator, Gui, CorrelatedError, ZoweExplorerApiType } from "../../../src/";
+import { commands } from "vscode";
+
+describe("addCorrelation", () => {
+    it("adds a correlation for the given API and existing profile type", () => {
+        const fakeErrorSummary = "Example error summary for the correlator";
+        ErrorCorrelator.getInstance().addCorrelation(ZoweExplorerApiType.Mvs, "zosmf", {
+            errorCode: "403",
+            summary: fakeErrorSummary,
+            matches: ["Specific sequence 1234 encountered"],
+        });
+        expect(
+            (ErrorCorrelator.getInstance() as any).errorMatches.get(ZoweExplorerApiType.Mvs)["zosmf"].find((err) => err.summary === fakeErrorSummary)
+        ).not.toBe(null);
+    });
+    it("adds a correlation for the given API and new profile type", () => {
+        const fakeErrorSummary = "Example error summary for the correlator";
+        ErrorCorrelator.getInstance().addCorrelation(ZoweExplorerApiType.Mvs, "fake-type", {
+            errorCode: "403",
+            summary: fakeErrorSummary,
+            matches: ["Specific sequence 5678 encountered"],
+        });
+        expect(
+            (ErrorCorrelator.getInstance() as any).errorMatches
+                .get(ZoweExplorerApiType.Mvs)
+                ["fake-type"].find((err) => err.summary === fakeErrorSummary)
+        ).not.toBe(null);
+    });
+});
+
+describe("correlateError", () => {
+    it("correctly correlates an error in the list of error matches", () => {
+        expect(
+            ErrorCorrelator.getInstance().correlateError(ZoweExplorerApiType.Mvs, "Client is not authorized for file access.", {
+                profileType: "zosmf",
+            })
+        ).toStrictEqual(
+            new CorrelatedError({
+                correlation: {
+                    errorCode: "500",
+                    summary: "Insufficient write permissions for this data set. The data set may be read-only or locked.",
+                    tips: [
+                        "Check that your user or group has the appropriate permissions for this data set.",
+                        "Ensure that the data set is not opened within a mainframe editor tool.",
+                    ],
+                },
+                errorCode: "500",
+                initialError: "Client is not authorized for file access.",
+            })
+        );
+    });
+    it("returns a generic CorrelatedError if no matches are available for the given profile type", () => {
+        expect(
+            ErrorCorrelator.getInstance().correlateError(ZoweExplorerApiType.Mvs, "This is the full error message", { profileType: "nonsense" })
+        ).toStrictEqual(new CorrelatedError({ initialError: "This is the full error message" }));
+    });
+    it("returns a generic CorrelatedError with the full error details if no matches are found", () => {
+        expect(
+            ErrorCorrelator.getInstance().correlateError(ZoweExplorerApiType.Mvs, "A cryptic error with no available match", { profileType: "zosmf" })
+        ).toStrictEqual(new CorrelatedError({ initialError: "A cryptic error with no available match" }));
+    });
+});
+
+describe("displayError", () => {
+    it("calls correlateError to get an error correlation", async () => {
+        const correlateErrorMock = jest
+            .spyOn(ErrorCorrelator.prototype, "correlateError")
+            .mockReturnValueOnce(
+                new CorrelatedError({ correlation: { summary: "Summary of network error" }, initialError: "This is the full error message" })
+            );
+        const errorMessageMock = jest.spyOn(Gui, "errorMessage").mockResolvedValueOnce(undefined);
+        await ErrorCorrelator.getInstance().displayError(ZoweExplorerApiType.Mvs, "This is the full error message", { profileType: "zosmf" });
+        expect(correlateErrorMock).toHaveBeenCalledWith(ZoweExplorerApiType.Mvs, "This is the full error message", { profileType: "zosmf" });
+        expect(errorMessageMock).toHaveBeenCalledWith("Summary of network error", { items: ["More info"] });
+    });
+    it("presents an additional dialog when the user selects 'More info'", async () => {
+        const correlateErrorMock = jest
+            .spyOn(ErrorCorrelator.prototype, "correlateError")
+            .mockReturnValueOnce(
+                new CorrelatedError({ correlation: { summary: "Summary of network error" }, initialError: "This is the full error message" })
+            );
+        const errorMessageMock = jest.spyOn(Gui, "errorMessage").mockResolvedValueOnce("More info").mockResolvedValueOnce(undefined);
+        await ErrorCorrelator.getInstance().displayError(ZoweExplorerApiType.Mvs, "This is the full error message", { profileType: "zosmf" });
+        expect(correlateErrorMock).toHaveBeenCalledWith(ZoweExplorerApiType.Mvs, "This is the full error message", { profileType: "zosmf" });
+        expect(errorMessageMock).toHaveBeenCalledWith("Summary of network error", { items: ["More info"] });
+        expect(errorMessageMock).toHaveBeenCalledWith("This is the full error message", { items: ["Show log", "Troubleshoot"] });
+    });
+    it("opens the Zowe Explorer output channel when the user selects 'Show log'", async () => {
+        const correlateErrorMock = jest
+            .spyOn(ErrorCorrelator.prototype, "correlateError")
+            .mockReturnValueOnce(
+                new CorrelatedError({ correlation: { summary: "Summary of network error" }, initialError: "This is the full error message" })
+            );
+        const errorMessageMock = jest.spyOn(Gui, "errorMessage").mockResolvedValueOnce("More info").mockResolvedValueOnce("Show log");
+        const executeCommandMock = jest.spyOn(commands, "executeCommand").mockImplementation();
+        await ErrorCorrelator.getInstance().displayError(ZoweExplorerApiType.Mvs, "This is the full error message", { profileType: "zosmf" });
+        expect(correlateErrorMock).toHaveBeenCalledWith(ZoweExplorerApiType.Mvs, "This is the full error message", { profileType: "zosmf" });
+        expect(errorMessageMock).toHaveBeenCalledWith("Summary of network error", { items: ["More info"] });
+        expect(errorMessageMock).toHaveBeenCalledWith("This is the full error message", { items: ["Show log", "Troubleshoot"] });
+        expect(executeCommandMock).toHaveBeenCalledWith("zowe.revealOutputChannel");
+        executeCommandMock.mockRestore();
+    });
+    it("opens the troubleshoot webview if the user selects 'Troubleshoot'", async () => {
+        const error = new CorrelatedError({
+            correlation: { summary: "Summary of network error" },
+            initialError: "This is the full error message",
+        });
+        const correlateErrorMock = jest.spyOn(ErrorCorrelator.getInstance(), "correlateError").mockReturnValueOnce(error);
+        const errorMessageMock = jest.spyOn(Gui, "errorMessage").mockResolvedValueOnce("More info").mockResolvedValueOnce("Troubleshoot");
+        const executeCommandMock = jest.spyOn(commands, "executeCommand").mockImplementation();
+        await ErrorCorrelator.getInstance().displayError(ZoweExplorerApiType.Mvs, "This is the full error message", { profileType: "zosmf" });
+        expect(correlateErrorMock).toHaveBeenCalledWith(ZoweExplorerApiType.Mvs, "This is the full error message", { profileType: "zosmf" });
+        expect(errorMessageMock).toHaveBeenCalledWith("Summary of network error", { items: ["More info"] });
+        expect(errorMessageMock).toHaveBeenCalledWith("This is the full error message", { items: ["Show log", "Troubleshoot"] });
+        expect(executeCommandMock).toHaveBeenCalledWith("zowe.troubleshootError", error, error.stack);
+        executeCommandMock.mockRestore();
+    });
+});
+
+describe("displayCorrelatedError", () => {
+    it("returns 'Retry' for the userResponse whenever the user selects 'Retry'", async () => {
+        const error = new CorrelatedError({
+            correlation: { summary: "Summary of network error" },
+            initialError: "This is the full error message",
+        });
+        const correlateErrorMock = jest.spyOn(ErrorCorrelator.getInstance(), "correlateError").mockReturnValueOnce(error);
+        const errorMessageMock = jest.spyOn(Gui, "errorMessage").mockResolvedValueOnce("Retry");
+        const handledErrorInfo = await ErrorCorrelator.getInstance().displayError(ZoweExplorerApiType.Mvs, "This is the full error message", {
+            additionalContext: "Some additional context",
+            allowRetry: true,
+            profileType: "zosmf",
+        });
+        expect(correlateErrorMock).toHaveBeenCalledWith(ZoweExplorerApiType.Mvs, "This is the full error message", { profileType: "zosmf" });
+        expect(errorMessageMock).toHaveBeenCalledWith("Some additional context: Summary of network error", { items: ["Retry", "More info"] });
+        expect(handledErrorInfo.userResponse).toBe("Retry");
+    });
+});

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

@@ -11,6 +11,7 @@
 
 import * as imperative from "@zowe/imperative";
 import { ProfilesCache } from "../profiles/ProfilesCache";
+import { ErrorCorrelator } from "../utils/ErrorCorrelator";
 
 /**
  * This interface can be used by other VS Code Extensions to access an alternative
@@ -45,4 +46,11 @@ export interface IApiExplorerExtender {
      * or to create them automatically if it is non-existant.
      */
     initForZowe(type: string, profileTypeConfigurations: imperative.ICommandProfileTypeConfiguration[]): void | Promise<void>;
+
+    /**
+     * Allows extenders to contribute error correlations, providing user-friendly
+     * summaries of API or network errors. Also gives extenders the opportunity to
+     * provide tips or additional resources for errors.
+     */
+    getErrorCorrelator?(): ErrorCorrelator;
 }

packages/zowe-explorer-api/src/fs/BaseProvider.ts

@@ -10,11 +10,12 @@
  */
 
 import * as vscode from "vscode";
-import { DirEntry, FileEntry, IFileSystemEntry, FS_PROVIDER_DELAY, ConflictViewSelection, DeleteMetadata } from "./types";
+import { DirEntry, FileEntry, IFileSystemEntry, FS_PROVIDER_DELAY, ConflictViewSelection, DeleteMetadata, HandleErrorOpts } from "./types";
 import * as path from "path";
 import { FsAbstractUtils } from "./utils";
 import { Gui } from "../globals/Gui";
 import { ZosEncoding } from "../tree";
+import { ErrorCorrelator, ZoweExplorerApiType } from "../utils/ErrorCorrelator";
 
 export class BaseProvider {
     // eslint-disable-next-line no-magic-numbers
@@ -417,6 +418,24 @@ export class BaseProvider {
         return entry;
     }
 
+    protected _handleError(err: Error, opts?: HandleErrorOpts): void {
+        ErrorCorrelator.getInstance()
+            .displayError(opts?.apiType ?? ZoweExplorerApiType.All, err, {
+                additionalContext: opts?.additionalContext,
+                allowRetry: opts?.retry?.fn != null,
+                profileType: opts?.profileType ?? "any",
+                templateArgs: opts?.templateArgs,
+            })
+            .then(async ({ userResponse }) => {
+                if (userResponse === "Retry" && opts?.retry?.fn != null) {
+                    await opts.retry.fn(...(opts?.retry.args ?? []));
+                }
+            })
+            .catch(() => {
+                throw err;
+            });
+    }
+
     protected _lookupAsDirectory(uri: vscode.Uri, silent: boolean): DirEntry {
         const entry = this.lookup(uri, silent);
         if (entry != null && !FsAbstractUtils.isDirectoryEntry(entry) && !silent) {

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

@@ -13,6 +13,7 @@ import { Duplex } from "stream";
 import { IProfileLoaded } from "@zowe/imperative";
 import * as vscode from "vscode";
 import { ZosEncoding } from "../../tree";
+import { ZoweExplorerApiType } from "../../utils/ErrorCorrelator";
 
 export enum ZoweScheme {
     DS = "zowe-ds",
@@ -147,3 +148,14 @@ export type UriFsInfo = {
     profileName: string;
     profile?: IProfileLoaded;
 };
+
+export interface HandleErrorOpts {
+    retry?: {
+        fn: (...args: any[]) => any | PromiseLike<any>;
+        args?: any[];
+    };
+    profileType?: string;
+    apiType?: ZoweExplorerApiType;
+    templateArgs?: Record<string, string>;
+    additionalContext?: string;
+}

packages/zowe-explorer-api/src/profiles/ProfilesCache.ts

@@ -184,7 +184,8 @@ export class ProfilesCache {
                     }
 
                     // Step 3: Update allProfiles list
-                    tmpAllProfiles.push(profileFix);
+                    const existingProfile = this.allProfiles.find((tmpProf) => tmpProf.name === prof.profName && tmpProf.type === prof.profType);
+                    tmpAllProfiles.push(existingProfile ? Object.assign(existingProfile, profileFix) : profileFix);
                 }
                 allProfiles.push(...tmpAllProfiles);
                 this.profilesByType.set(type, tmpAllProfiles);