chore: improve custom lsp extension docs

Update README with more examples of custom notifications and types which
may be useful to integrating with the Snyk Language Server.

Rename "payload" to "params", "response" to "example" in notification docs.

README.md

@@ -57,23 +57,117 @@ Right now the language server supports the following actions:
 
 - $/progress
 - textDocument/publishDiagnostics
+  - params: `types.PublishDiagnosticsParams`
+  - example: Snyk Open Source
+  ```json5
+  {
+    "uri": "file:///path/to/file",
+    "diagnostics": [
+      {
+        "range": {
+          "start": { "line": 1, "character": 0 },
+          "end": { "line": 2, "character": 0 },
+        },
+        "severity": 1,
+        "code": "S100",
+        "source": "Snyk",
+        "message": "Message",
+        "tags": ["security"],
+        "data": {
+          "scanIssue": {
+            "id": "123",
+            "issueType": "vulnerability",
+            "packageName": "packageName",
+            "packageVersion": "packageVersion",
+            "issue": "issue",
+            "additionalData": {
+              "ruleId": "ruleId",
+              "identifiers": {
+                "cwe": ["cwe"],
+                "cve": ["cve"]
+              },
+              "description": "description",
+              "language": "language",
+              "packageManager": "packageManager",
+              "packageName": "packageName"
+            }
+          }
+        }
+      }
+    ]
+  }
+  ```
+  - example: Snyk Code
+  ```json5
+  {
+    "uri": "file:///path/to/file",
+    "diagnostics": [
+      {
+        "range": {
+          "start": { "line": 1, "character": 0 },
+          "end": { "line": 2, "character": 0 },
+        },
+        "severity": 1,
+        "code": "S100",
+        "source": "Snyk",
+        "message": "Message",
+        "tags": ["security"],
+        "data": {
+          "scanIssue": {
+            "id": "123",
+            "filePath": "filePath",
+            "range": {
+              "start": { "line": 1, "character": 0 },
+              "end": { "line": 2, "character": 0 },
+            },
+            "additionalData": {
+              "message": "message",
+              "rule": "rule",
+              "ruleId": "ruleId",
+              "dataFlow": [
+                {
+                  "filePath": "filePath",
+                  "range": {
+                    "start": { "line": 1, "character": 0 },
+                    "end": { "line": 2, "character": 0 },
+                  },
+                }
+              ],
+              "exampleCommitFixes": [
+                {
+                  "commit": "commit",
+                  "diff": "diff"
+                }
+              ],
+              "cwe": "cwe",
+              "isSecurityType": true
+            }
+          }
+        }
+      }
+    ]
+  }
+  ```
+
 - window/logMessage
 - window/showMessage
 
 ### Custom additions to Language Server Protocol (server -> client)
 - SDKs callback to retrieve configured SDKs from the client
   - method: `workspace/snyk.sdks`
-  - payload: WorkspaceFolder
-  - response: 
+  - params: `types.WorkspaceFolder`
+  - example:
   ```json5
   [{
-  	"type": "java", // or python or go
-	  "path": "/path/to/sdk" // JAVA_HOME for java, GOROOT for Go, Python executable for Python
+    "type": "java", // or python or go
+    "path": "/path/to/sdk" // JAVA_HOME for java, GOROOT for Go, Python executable for Python
   }]
   ```
+
 - Folder Config Notification
   - method: `$/snyk.folderConfigs`
-  - payload:
+  - params: `types.FolderConfigsParam`
+  - example:
   ```json5
   {
       "folderConfigs":
@@ -86,37 +180,48 @@ Right now the language server supports the following actions:
       ]
   }
   ```
+
 - Custom Publish Diagnostics Notification
-- method: `$/snyk.publishDiagnostics316`
-  - payload:
-  ```json5
-  {
-  "uri": "/path/to/file",
-  "diagnostics": [], 
-  }
-  ```
+  - method: `$/snyk.publishDiagnostics316`
+  - params: `types.PublishDiagnosticsParams`
+  - note: alias for textDocument/publishDiagnostics
+
 - Authentication Notification
   - method: `$/snyk.hasAuthenticated`
-  - payload:
+  - params: `types.AuthenticationParams`
+  - example:
   ```json5
   {
     "token": "the snyk token" // this can be an oauth2.Token string or a legacy token
   }
   ```
   - See https://pkg.go.dev/golang.org/x/[email protected]#Token for more details regarding oauth tokens.
 
-- Cli Path Notification
+- CLI Path Notification
   - method: `$/snyk.isAvailableCli`
-  - payload:
+  - params: `types.SnykIsAvailableCli`
+  - example:
   ```json5
   {
     "cliPath": "/a/path/to/cli-executable"
   }
   ```
 
-- Trust Notification
+- Diagnostics Overview (tabbed tree view)
+  - method: `$/snyk.diagnosticsOverview`
+  - params: `types.DiagnosticsOverviewParams`
+  - example:
+  ```json5
+  {
+  "product": "oss", // or "code" or "iac"
+  "html": "<html>...</html>", // the html to display the overview tabs/tree
+  }
+  ```
+
+- Trusted Folder Notification
   - method: `$/snyk.addTrustedFolders`
-  - payload:
+  - params: `types.SnykTrustedFoldersParams`
+  - example:
   ```json5
   {
     "trustedFolders": ["/a/path/to/trust"]
@@ -125,14 +230,26 @@ Right now the language server supports the following actions:
 
 - Scan Notification
   - method: `$/snyk.scan`
-  - payload:
+  - params: `types.ScanParams`
+  - example: Successful scan
   ```json5
   {
-    "status": "inProgress", // possible values: "error", "inProgress", "success"
+    "status": "success", // possible values: "error", "inProgress", "success"
     "product": "code", // possible values: "code", "oss", "iac"
-    "results" : [
-      // TBD
-    ]
+    "folderPath": "/a/path/to/folder",
+  }
+  ```
+  - example: Failed scan with errors
+  ```json5
+  {
+    "status": "error",
+    "product": "code",
+    "folderPath": "/a/path/to/folder",
+    "errorMessage": "An error occurred",
+    "cliError": {
+      "code": "CLI_ERROR_CODE",
+      "message": "An error occurred"
+    },
   }
   ```
 
@@ -267,19 +384,19 @@ Right now the language server supports the following actions:
   ```
   - Diff Example:
   ```
-  
+
   --- /var/folders/vn/77lwfy3974g7vykcm5lr6mkh0000gn/T/Test_SmokeWorkspaceScanOssAndCode952013010/001/1
   +++ /var/folders/vn/77lwfy3974g7vykcm5lr6mkh0000gn/T/Test_SmokeWorkspaceScanOssAndCode952013010/001/1-fixed
   @@ -32,7 +32,8 @@
-  
+
        test('should set success to OK upon success', function() {
          // GIVEN
-  
+
   -      comp.password = comp.confirmPassword = 'myPassword';
-  
+
   +      comp.password = process.env.TEST_PASSWORD;
   +      comp.confirmPassword = process.env.TEST_PASSWORD;
-  
+
          // WHEN
          comp.changePassword();
   ```
@@ -389,7 +506,7 @@ within `initializationOptions?: LSPAny;` we support the following settings:
     "baseBranch": "main", // the base branch for delta scanning
     "folderPath": "a/b/c", // the workspace folder path
     "additionalParameters": "--file=pom.xml" // additional parameters for CLI scans
-  }], // an array of folder configurations, defining the desired base branch of a workspaceFolder 
+  }], // an array of folder configurations, defining the desired base branch of a workspaceFolder
 }
 ```