Update Exception Handling Design Doc (#465)

Author: dennisseah

guides/command-implementation.md

@@ -109,4 +109,31 @@ E.g.
 > Value for organization name option was missing. Provide value for this option.
 
 2. We do not want pronoun in error messages. E.g.
+
    > You did not enter value for organization name. Please provide value for it.
+
+3. All error shall be created with the error builder,
+   https://github.com/CatalystCode/spk/blob/master/src/lib/errorBuilder.ts so
+   that we can generate the exception chain. In this manner, we can precisely
+   know the root cause of the problem. Error shall be logged at the end of the
+   command like this
+
+```
+export const execute = async (
+  config: ConfigYaml,
+  opts: CommandOptions,
+  exitFn: (status: number) => Promise<void>
+): Promise<void> => {
+  try {
+    ...;
+    await exitFn(0);
+  } catch (err) {
+    logError(
+      buildError(errorStatusCode.CMD_EXE_ERR, "infra-scaffold-cmd-failed", err)
+    );
+    await exitFn(1);
+  }
+};
+```
+
+[Reference](../technical-docs/designs/exceptionHandling.md)

technical-docs/designs/exceptionHandling.md

@@ -2,10 +2,11 @@
 
 Reference: Exception Handling<br> Authors: Andre Briggs, Dennis Seah
 
-| Revision | Date         | Author      | Remarks                          |
-| -------: | ------------ | ----------- | -------------------------------- |
-|      0.1 | Mar-04, 2020 | Dennis Seah | Initial Draft                    |
-|      1.0 | Mar-10, 2020 | Dennis Seah | Incorporate comments from Yvonne |
+| Revision | Date         | Author      | Remarks                                           |
+| -------: | ------------ | ----------- | ------------------------------------------------- |
+|      0.1 | Mar-04, 2020 | Dennis Seah | Initial Draft                                     |
+|      1.0 | Mar-10, 2020 | Dennis Seah | Incorporate comments from Yvonne                  |
+|      1.1 | Mar-27, 2020 | Dennis Seah | Amendments after first implementation is reviewed |
 
 ## 1. Overview
 
@@ -87,13 +88,15 @@ web client call. We would like to have a JSON object like this
 
 ```
 {
-  "statusCode": 101,
+  "errorCode": 1000,
   "message": "Execution of spk project install-lifecycle-pipeline could not be completed.",
-  "error": {
-    "message": "Execute of installPipeline function failed."
-    "error": {
-      "statusCode": 401,
-      "message": "Unauthorized access to pipeline...."
+  "parent": {
+    "errorCode": 1010,
+    "message": "Execute of installPipeline function failed.",
+    "parent": {
+      "errorCode": 1011,
+      "message": "Unauthorized access to pipeline....",
+      "details": "<exception message>"
     }
   }
 }
@@ -106,22 +109,47 @@ The typescript interface of this ErrorChain is
 
 ```
 interface ErrorChain {
-  statusCode?: number;
+  errorCode?: number;
   message: string;
-  error?: ErrorChain;
+  details: string | undefined;
+  parent?: ErrorChain | undefined;
 }
 ```
 
 ### 3.3 List of error codes
 
-To be completed
+Example of `enum` of status code
 
-| Error Code | Description                       |
-| ---------: | --------------------------------- |
-|        101 | Execution of command failed       |
-|        110 | Validation of input values failed |
-|        201 | Azure pipeline API call failed    |
-|        ... | ...                               |
+```typescript
+export enum errorStatusCode {
+  CMD_EXE_ERR = 1000,
+  VALIDATION_ERR = 1001,
+  EXE_FLOW_ERR = 1002,
+  ENV_SETTING_ERR = 1010,
+  GIT_OPS_ERR = 1100,
+}
+```
+
+### 3.4 Externalization of error messsage
+
+Example:
+
+```json
+  "errors": {
+    "infra-scaffold-cmd-failed": "Scaffold Command was not successfully executed.",
+    "infra-scaffold-cmd-src-missing": "Value for source is required because it cannot be constructed with properties in spk-config.yaml. Provide value for source.",
+    "infra-scaffold-cmd-values-missing": "Values for name, version and/or 'template were missing. Provide value for values for them.",
+    "infra-err-validating-remote-git": "Could not determine error when validating remote git source.",
+    "infra-err-retry-validating-remote-git": "Failure error thrown during retrying validating remote git source.",
+    "infra-err-locate-tf-env": "Could not find Terraform environment. Ensure template path {0} exists.",
+    "infra-err-tf-path-not-found": "Provided Terraform {0} path is invalid or cannot be found: {1}",
+    "infra-err-create-scaffold": "Could not create scaffold",
+    "infra-err-git-clone-failed": "Could not clone the source remote repository. The remote repo might not exist or you did not have the rights to access it",
+    "infra-git-source-no-exist": "Source path, {0} did not exist."
+  }
+```
+
+This allows us to localized error messages if needed.
 
 ## 4. Dependencies