tools/generate: generate debug configuration table

Ignores properties whose description fields include
'Not applicable when using `dlv-dap` mode.'

Change-Id: Ibc3d9ff44462baaba9c27e7afebd92cc03282e1c
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/328492
Trust: Hyang-Ah Hana Kim <[email protected]>
Trust: Suzy Mueller <[email protected]>
Run-TryBot: Hyang-Ah Hana Kim <[email protected]>
TryBot-Result: kokoro <[email protected]>
Reviewed-by: Suzy Mueller <[email protected]>

Author: hyangah

docs/dlv-dap.md

@@ -64,23 +64,17 @@ $ mv /tmp/dlv $GOPATH/bin/dlv-dap
 * Robust `call` evaluation.
 * Good test coverage.
 
-
 Most of all, the new adapter is written in Go and integrated in `dlv`. That will make it easier for the Go community to contribute. </br>
 Because it is native, we hope for improvement in speed and reliability.
 
-⚒️ The following features are still under development. 
-
-* Pause/restart while the debugged program is running does not work yet.
-* Setting breakpoints while the debugged program is running does not work yet.
-* `SetVariable` does not work yet.
-* `dlvLoadConfig` to configure max string/bytes length in [`"go.delveConfig"`](https://github.com/golang/vscode-go/blob/master/docs/debugging.md#configuration) does not work.
-* Traditional [remote debugging](https://github.com/golang/vscode-go/blob/master/docs/debugging.md#remote-debugging) is not supported.
+💡 Notes:
 
-Follow along with [golang/vscode-go#23](https://github.com/golang/vscode-go/issues/23) and the [project dashboard](https://github.com/golang/vscode-go/projects/3) for updates on the implementation.
+* `dlvLoadConfig` to configure max string/bytes length in [`"go.delveConfig"`](https://github.com/golang/vscode-go/blob/master/docs/debugging.md#configuration) does not work. For large strings, use `DEBUG CONSOLE`, "Copy Value", or hover in editor. The new debug adapter supports [paging of large arrays, bytes, and maps](https://github.com/go-delve/delve/pull/2512#issuecomment-849021775) instead.
+* Traditional [remote debugging](https://github.com/golang/vscode-go/blob/master/docs/debugging.md#remote-debugging) is not supported yet (Work-In-Progress).
 
 ## Reporting issues
 
-The VS Code Go maintainers are reachable via the issue tracker and the #vscode-dev channel in the Gophers Slack. </br>
+The VS Code Go maintainers are reachable via the issue tracker and the `#vscode-dev` channel in the Gophers Slack. </br>
 Please reach out on Slack with questions, suggestions, or ideas. If you have trouble getting started on an issue, we'd be happy to give pointers and advice.
 
 When you are having issues in `dlv-dap` mode, first check if the problems are reproducible after updating `dlv-dap`. It's possible that the issues are already fixed. Follow the instruction for [updating dlv-dap](#updating-dlv-dap)) and [updating extension](https://code.visualstudio.com/docs/editor/extension-gallery#_extension-autoupdate).
@@ -92,6 +86,35 @@ Please report issues in [our issue tracker](https://github.com/golang/vscode-go/
 * VS Code and VS Code Go version.
 * Instruction to reproduce the issue (code snippets, your `launch.json`, screenshot)
 
+## Configuration
+<!-- DO NOT EDIT: Auto-generated by go run tools/generate -->
+<!-- SETTINGS BEGIN -->
+| Property | Launch | Attach |
+| --- | --- | --- |
+| `args` | Command line arguments passed to the debugged program.<br/> | <center>_n/a_</center> |
+| `backend` | Backend used by delve. Maps to `dlv`'s `--backend` flag.<br/><p>Allowed Values: `"default"`, `"native"`, `"lldb"`<br/> | <center>_same as Launch_</center>|
+| `buildFlags` | Build flags, to be passed to the Go compiler. Maps to dlv's `--build-flags` flag.<br/>(Default: `""`)<br/> | <center>_n/a_</center> |
+| `cwd` | Workspace relative or absolute path to the working directory of the program being debugged if a non-empty value is specified. The `program` folder is used as the working directory if `cwd` is omitted or empty.<br/>(Default: `""`)<br/> | Workspace relative or absolute path to the working directory of the program being debugged. Default is the current workspace.<br/>(Default: `"${workspaceFolder}"`)<br/> |
+| `debugAdapter` | Select which debug adapter to use with this launch configuration.<br/><p>Allowed Values: `"legacy"`, `"dlv-dap"`<br/>(Default: `legacy`)<br/> | <center>_same as Launch_</center>|
+| `dlvFlags` | Extra flags for `dlv`. See `dlv help` for the full list of supported. Flags such as `--log-output`, `--log`, `--log-dest`, `--api-version`, `--output`, `--backend` already have corresponding properties in the debug configuration, and flags such as `--listen` and `--headless` are used internally. If they are specified in `dlvFlags`, they may be ignored or cause an error.<br/> | <center>_same as Launch_</center>|
+| `env` | Environment variables passed to the program.<br/> | <center>_n/a_</center> |
+| `envFile` | Absolute path to a file containing environment variable definitions. Multiple files can be specified by provided an array of absolute paths<br/>(Default: `${workspaceFolder}/.env`)<br/> | <center>_n/a_</center> |
+| `host` | The host name of the machine the delve debugger will be listening on. In `dlv-dap` mode, the extension will look for a delve DAP server running on the specified host:port so users are responsible for starting the server.<br/>(Default: `"127.0.0.1"`)<br/> | <center>_same as Launch_</center>|
+| `logDest` | dlv's `--log-dest` flag. See `dlv log` for details. Number argument is not allowed. Supported only in `dlv-dap` mode, and on Linux and Mac OS.<br/> | dlv's `--log-dest` flag. See `dlv log` for details. Number argument is not allowed. Supported only in `dlv-dap` mode and on Linux and Mac OS.<br/> |
+| `logOutput` | Comma separated list of components that should produce debug output. Maps to dlv's `--log-output` flag. Check `dlv log` for details.<br/><p>Allowed Values: `"debugger"`, `"gdbwire"`, `"lldbout"`, `"debuglineerr"`, `"rpc"`, `"dap"`<br/>(Default: `"debugger"`)<br/> | <center>_same as Launch_</center>|
+| `mode` | One of `auto`, `debug`, `test`, `exec`. In `auto` mode, the extension will choose either `debug` or `test` depending on active editor window.<br/><p>Allowed Values: `"auto"`, `"debug"`, `"test"`, `"exec"`<br/>(Default: `auto`)<br/> | Indicates local or remote debugging. Local maps to the `dlv attach` command, remote maps to `connect`. `remote` is not supported in `dlv-dap` mode currently. Use `host` and `port` instead.<br/><p>Allowed Values: `"local"`, `"remote"`<br/>(Default: `local`)<br/> |
+| `output` | Output path for the binary of the debugee.<br/>(Default: `"debug"`)<br/> | <center>_n/a_</center> |
+| `port` | The port that the delve debugger will be listening on. In `dlv-dap` mode, the extension will look for a delve DAP server running on the specified host:port so users are responsible for starting the server.<br/>(Default: `2345`)<br/> | <center>_same as Launch_</center>|
+| `processId` | <center>_n/a_</center> | <br/><p><b>Option 1:</b> Use process picker to select a process to attach, or Process ID as integer.<br/><p>Allowed Values: `"${command:pickProcess}"`, `"${command:pickGoProcess}"`<br/><br/><p><b>Option 2:</b> Attach to a process by name. If more than one process matches the name, use the process picker to select a process.<br/><br/><p><b>Option 3:</b> The numeric ID of the process to be debugged. If 0, use the process picker to select a process.<br/><br/>(Default: `0`)<br/> |
+| `program` | Path to the program folder (or any go file within that folder) when in `debug` or `test` mode, and to the pre-built binary file to debug in `exec` mode. If it is not an absolute path, the extension interpretes it as a workspace relative path.<br/>(Default: `"${workspaceFolder}"`)<br/> | <center>_n/a_</center> |
+| `remotePath` | <center>_n/a_</center> | (Deprecated) *Use `substitutePath` instead.*<br/>The path to the source code on the remote machine, when the remote path is different from the local machine. If specified, becomes the first entry in substitutePath.<br/>(Default: `""`)<br/> |
+| `showGlobalVariables` | Boolean value to indicate whether global package variables should be shown in the variables pane or not.<br/>(Default: `false`)<br/> | <center>_same as Launch_</center>|
+| `showLog` | Show log output from the delve debugger. Maps to dlv's `--log` flag.<br/>(Default: `false`)<br/> | <center>_same as Launch_</center>|
+| `stackTraceDepth` | Maximum depth of stack trace collected from Delve.<br/>(Default: `50`)<br/> | <center>_same as Launch_</center>|
+| `stopOnEntry` | Automatically stop program after launch.<br/>(Default: `false`)<br/> | Automatically stop program after attach.<br/>(Default: `false`)<br/> |
+| `substitutePath` | An array of mappings from a local path (editor) to the remote path (debugee). This setting is useful when working in a file system with symbolic links, running remote debugging, or debugging an executable compiled externally. The debug adapter will replace the local path with the remote path in all of the calls.<br/><p><br/><ul><li>`"from"`: The absolute local path to be replaced when passing paths to the debugger.<br/>(Default: `""`)<br/></li><li>`"to"`: The absolute remote path to be replaced when passing paths back to the client.<br/>(Default: `""`)<br/></li></ul><br/> | An array of mappings from a local path (editor) to the remote path (debugee). This setting is useful when working in a file system with symbolic links, running remote debugging, or debugging an executable compiled externally. The debug adapter will replace the local path with the remote path in all of the calls.  Overriden by `remotePath`.<br/><p><br/><ul><li>`"from"`: The absolute local path to be replaced when passing paths to the debugger.<br/>(Default: `""`)<br/></li><li>`"to"`: The absolute remote path to be replaced when passing paths back to the client.<br/>(Default: `""`)<br/></li></ul><br/> |
+| `trace` | Various levels of logging shown in the debug console & 'Go Debug' output channel. When using the `legacy` debug adapter, the logs will also be written to a file if it is set to a value other than `error`.<br/><p>Allowed Values: `"verbose"`, `"trace"`, `"log"`, `"info"`, `"warn"`, `"error"`<br/>(Default: `"error"`)<br/> | <center>_same as Launch_</center>|
+<!-- SETTINGS END -->
 ## Developing
 
 ### Code location

tools/generate.go

@@ -17,6 +17,7 @@ import (
 	"encoding/json"
 	"flag"
 	"fmt"
+	"io"
 	"io/ioutil"
 	"log"
 	"os"
@@ -36,12 +37,34 @@ var (
 	debugFlag = flag.Bool("debug", false, "If true, enable extra logging and skip deletion of intermediate files.")
 )
 
+func checkAndWrite(filename string, oldContent, newContent []byte) {
+	// Return early if the contents are unchanged.
+	if bytes.Equal(oldContent, newContent) {
+		return
+	}
+
+	// Either write out new contents or report an error (if in CI).
+	if *writeFlag {
+		if err := ioutil.WriteFile(filename, newContent, 0644); err != nil {
+			log.Fatal(err)
+		}
+		fmt.Printf("updated %s\n", filename)
+	} else {
+		base := filepath.Join("docs", filepath.Base(filename))
+		fmt.Printf(`%s have changed in the package.json, but documentation in %s was not updated.
+To update the settings, run "go run tools/generate.go -w".
+`, strings.TrimSuffix(base, ".md"), base)
+		os.Exit(1) // causes CI to break.
+	}
+}
+
 type PackageJSON struct {
 	Contributes struct {
 		Commands      []Command `json:"commands,omitempty"`
 		Configuration struct {
 			Properties map[string]*Property `json:"properties,omitempty"`
 		} `json:"configuration,omitempty"`
+		Debuggers []Debugger `json:"debuggers,omitempty"`
 	} `json:"contributes,omitempty"`
 }
 
@@ -69,6 +92,19 @@ type Property struct {
 	Items                      *Property            `json:"items,omitempty"`
 }
 
+type Debugger struct {
+	Type                    string `json:"type,omitempty"`
+	Label                   string `json:"label,omitempty"`
+	ConfigurationAttributes struct {
+		Launch Configuration
+		Attach Configuration
+	} `json:"configurationAttributes,omitempty"`
+}
+
+type Configuration struct {
+	Properties map[string]*Property `json:"properties,omitempty"`
+}
+
 type moduleVersion struct {
 	Path     string   `json:",omitempty"`
 	Version  string   `json:",omitempty"`
@@ -132,26 +168,9 @@ func main() {
 			}, []byte("\n\n"))
 		}
 		newContent := append(s, '\n')
-
-		// Return early if the contents are unchanged.
-		if bytes.Equal(oldContent, newContent) {
-			return
-		}
-
-		// Either write out new contents or report an error (if in CI).
-		if *writeFlag {
-			if err := ioutil.WriteFile(filename, newContent, 0644); err != nil {
-				log.Fatal(err)
-			}
-			fmt.Printf("updated %s\n", filename)
-		} else {
-			base := filepath.Join("docs", filepath.Base(filename))
-			fmt.Printf(`%s have changed in the package.json, but documentation in %s was not updated.
-To update the settings, run "go run tools/generate.go -w".
-`, strings.TrimSuffix(base, ".md"), base)
-			os.Exit(1) // causes CI to break.
-		}
+		checkAndWrite(filename, oldContent, newContent)
 	}
+
 	b := &bytes.Buffer{}
 	for i, c := range pkgJSON.Contributes.Commands {
 		fmt.Fprintf(b, "### `%s`\n\n%s", c.Title, c.Description)
@@ -199,6 +218,10 @@ To update the settings, run "go run tools/generate.go -w".
 
 	rewrite(filepath.Join(dir, "docs", "settings.md"), b.Bytes())
 
+	b.Reset()
+	generateDebugConfigTable(b, pkgJSON)
+	rewriteDebugDoc(filepath.Join(dir, "docs", "dlv-dap.md"), b.Bytes())
+
 	// Only update the latest tool versions if the flag is set.
 	if !*updateLatestToolVersionsFlag {
 		return
@@ -336,11 +359,7 @@ func defaultDescriptionSnippet(p *Property) string {
 			fmt.Fprintf(b, "%v", p.Default)
 		}
 	default:
-		if _, ok := p.Type.([]interface{}); ok {
-			fmt.Fprintf(b, "%v", p.Default)
-			break
-		}
-		log.Fatalf("implement default when p.Type is %q in %#v %T", p.Type, p, p.Default)
+		fmt.Fprintf(b, "%v", p.Default)
 	}
 	return b.String()
 }
@@ -539,3 +558,122 @@ func updateGoplsSettings(oldData []byte, packageJSONFile string, debug bool) (ne
 	}
 	return newData, nil
 }
+
+func rewriteDebugDoc(filename string, toAdd []byte) {
+	oldContent, err := ioutil.ReadFile(filename)
+	if err != nil {
+		log.Fatal(err)
+	}
+	startSep := []byte(`<!-- SETTINGS BEGIN -->`)
+	endSep := []byte(`<!-- SETTINGS END -->`)
+	startIdx := bytes.Index(oldContent, startSep)
+	endIdx := bytes.Index(oldContent, endSep)
+	if startIdx <= 0 || endIdx <= startIdx {
+		log.Fatalf("Missing valid SETTINGS BEGIN/END markers in %v", filename)
+	}
+	part1 := oldContent[:startIdx+len(startSep)+1]
+	part3 := oldContent[endIdx:]
+
+	newContent := bytes.Join([][]byte{
+		part1,
+		toAdd,
+		part3,
+	}, []byte{})
+	checkAndWrite(filename, oldContent, newContent)
+}
+
+func generateDebugConfigTable(w io.Writer, pkgJSON *PackageJSON) {
+	for _, d := range pkgJSON.Contributes.Debuggers {
+		table := map[string]bool{}
+
+		for k := range d.ConfigurationAttributes.Attach.Properties {
+			table[k] = true
+		}
+		for k := range d.ConfigurationAttributes.Launch.Properties {
+			table[k] = true
+		}
+
+		keys := make([]string, 0, len(table))
+		for k := range table {
+			keys = append(keys, k)
+		}
+		sort.Strings(keys)
+
+		fmt.Fprintln(w, "| Property | Launch | Attach |")
+		fmt.Fprintln(w, "| --- | --- | --- |")
+
+		for _, k := range keys {
+			launch := describeDebugProperty(d.ConfigurationAttributes.Launch.Properties[k])
+			attach := describeDebugProperty(d.ConfigurationAttributes.Attach.Properties[k])
+
+			if launch != "" && attach != "" {
+				if launch != attach {
+					fmt.Fprintf(w, "| `%v` | %v | %v |\n", k, launch, attach)
+				} else {
+					fmt.Fprintf(w, "| `%v` | %v | <center>_same as Launch_</center>|\n", k, launch)
+				}
+			} else if launch != "" {
+				fmt.Fprintf(w, "| `%v` | %v | <center>_n/a_</center> |\n", k, launch)
+			} else if attach != "" {
+				fmt.Fprintf(w, "| `%v` | <center>_n/a_</center> | %v |\n", k, attach)
+			}
+		}
+	}
+}
+
+func describeDebugProperty(p *Property) string {
+	if p == nil {
+		return ""
+	}
+	b := &bytes.Buffer{}
+
+	desc := p.Description
+	if p.MarkdownDescription != "" {
+		desc = p.MarkdownDescription
+	}
+	if p == nil || strings.Contains(desc, "Not applicable when using `dlv-dap` mode.") {
+		return ""
+	}
+
+	deprecation := p.DeprecationMessage
+	if p.MarkdownDeprecationMessage != "" {
+		deprecation = p.MarkdownDeprecationMessage
+	}
+
+	if deprecation != "" {
+		fmt.Fprintf(b, "(Deprecated) *%v*<br/>", deprecation)
+	}
+	fmt.Fprintf(b, "%v<br/>", desc)
+
+	if len(p.AnyOf) > 0 {
+		for i, a := range p.AnyOf {
+			fmt.Fprintf(b, "<p><b>Option %d:</b> %v<br/>", i+1, describeDebugProperty(&a))
+		}
+	}
+
+	if len(p.Enum) > 0 {
+		var enums []string
+		for _, i := range p.Enum {
+			enums = append(enums, fmt.Sprintf("`%#v`", i))
+		}
+		fmt.Fprintf(b, "<p>Allowed Values: %v<br/>", strings.Join(enums, ", "))
+	}
+
+	if p.Type == "object" && len(p.Properties) > 0 {
+		fmt.Fprintf(b, "<ul>")
+		for k, v := range p.Properties {
+			fmt.Fprintf(b, "<li>`%q`: %v</li>", k, describeDebugProperty(v))
+		}
+		fmt.Fprintf(b, "</ul>")
+	}
+
+	if p.Type == "array" && p.Items != nil && p.Items.Type == "object" {
+		fmt.Fprintf(b, "<p>%v<br/>", describeDebugProperty(p.Items))
+	}
+
+	// Default
+	if d := defaultDescriptionSnippet(p); d != "" {
+		fmt.Fprintf(b, "(Default: `%v`)<br/>", d)
+	}
+	return b.String()
+}