vscgo: add a little helper program for vscode-go

github.com/golang/vscode-go/vscgo is a small go program
that the extension uses to delegate some tasks.
The program will be installed in the extension path
and its behavior will be tightly tied with the vscode
go extension version.

From v0.41.x the extension will use this to record go
telemetry counters defined in the extension. The extension
spawns a vsccode inc_counters process periodically and
passes accumulated counters (key/value pairs) to the program.

We plan to expand the functionality in the future,
such as tools installation, upgrade, developer
survey config check, that are not latency critical
and easier to write in Go.

For #3023
For #2891

Change-Id: I91427fc6a06dc2781ab21c12e0b8ed5957cba9b1
Reviewed-on: https://go-review.googlesource.com/c/vscode-go/+/549243
TryBot-Result: kokoro <[email protected]>
Commit-Queue: Hyang-Ah Hana Kim <[email protected]>
Reviewed-by: Alan Donovan <[email protected]>

Author: hyangah

.vscodeignore

@@ -12,11 +12,11 @@
 .vscode/
 .vscode-test/
 SECURITY.md
+bin/
 build/
 codereview.cfg
 docs/
-go.mod
-go.sum
+go.*
 node_modules/
 out/
 src/

vscgo/go.mod

@@ -0,0 +1,7 @@
+module github.com/golang/vscode-go/vscgo
+
+go 1.20
+
+require golang.org/x/telemetry v0.0.0-20231127153925-9e8199583d1d
+
+require golang.org/x/sys v0.15.0 // indirect

vscgo/go.sum

@@ -0,0 +1,4 @@
+golang.org/x/sys v0.15.0 h1:h48lPFYpsTvQJZF4EKyI4aLHaev3CxivZmv7yZig9pc=
+golang.org/x/sys v0.15.0/go.mod h1:/VUhepiaJMQUp4+oa/7Zr1D23ma6VTLIYjOOTFZPUcA=
+golang.org/x/telemetry v0.0.0-20231127153925-9e8199583d1d h1:ogNR6QNR4EYuxIiZ41ylPQHVyK6iFcGngiOqNHfTc/M=
+golang.org/x/telemetry v0.0.0-20231127153925-9e8199583d1d/go.mod h1:2hdX6fx9lgVpcqv/QJBJjwYNa2E/imfPNoTyf/a6vBo=

vscgo/main.go

@@ -0,0 +1,231 @@
+// Copyright 2023 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// The binary vscgo is a helper of the VS Code Go extension.
+// The source is distributed with the extension and compiled when
+// the extension is first activated.
+package main
+
+import (
+	"bufio"
+	"flag"
+	"fmt"
+	"log"
+	"os"
+	"runtime/debug"
+	"strings"
+	"time"
+
+	"golang.org/x/telemetry/counter"
+)
+
+type command struct {
+	usage   string
+	short   string
+	flags   *flag.FlagSet
+	hasArgs bool
+	run     func(args []string) error
+}
+
+func (c command) name() string {
+	name, _, _ := strings.Cut(c.usage, " ")
+	return name
+}
+
+var allCommands []*command
+
+func init() {
+	allCommands = []*command{
+		{
+			usage: "inc_counters",
+			short: "increment telemetry counters",
+			run:   runIncCounters,
+		},
+		{
+			usage: "version",
+			short: "print version information",
+			run:   runVersion,
+		},
+		{
+			usage:   "help <command>",
+			short:   "show help for a command",
+			hasArgs: true,
+			run:     runHelp, // accesses allCommands.
+		},
+	}
+
+	for _, cmd := range allCommands {
+		name := cmd.name()
+		if cmd.flags == nil {
+			cmd.flags = flag.NewFlagSet(name, flag.ExitOnError)
+		}
+		cmd.flags.Usage = func() {
+			help(name)
+		}
+	}
+}
+
+func main() {
+	counter.Open()
+	log.SetFlags(0)
+	flag.Usage = usage
+	flag.Parse()
+
+	args := flag.Args()
+	var cmd *command
+	if len(args) > 0 {
+		cmd = findCommand(args[0])
+	}
+	if cmd == nil {
+		flag.Usage()
+		os.Exit(2)
+	}
+	cmd.flags.Parse(args[1:]) // will exit on error
+	args = cmd.flags.Args()
+	if !cmd.hasArgs && len(args) > 0 {
+		help(cmd.name())
+		failf("\ncommand %q does not accept any arguments.\n", cmd.name())
+	}
+	if err := cmd.run(args); err != nil {
+		failf("%v\n", err)
+	}
+}
+
+func output(msgs ...interface{}) {
+	fmt.Fprintln(flag.CommandLine.Output(), msgs...)
+}
+
+func usage() {
+	printCommand := func(cmd *command) {
+		output(fmt.Sprintf("\t%s\t%s", cmd.name(), cmd.short))
+	}
+	output("vscgo is a helper tool for the VS Code Go extension, written in Go.")
+	output()
+	output("Usage:")
+	output()
+	output("\tvscgo <command> [arguments]")
+	output()
+	output("The commands are:")
+	output()
+	for _, cmd := range allCommands {
+		printCommand(cmd)
+	}
+	output()
+	output(`Use "vscgo help <command>" for details about any command.`)
+	output()
+}
+
+func failf(format string, args ...any) {
+	fmt.Fprintf(os.Stderr, format, args...)
+	os.Exit(1)
+}
+
+func findCommand(name string) *command {
+	for _, cmd := range allCommands {
+		if cmd.name() == name {
+			return cmd
+		}
+	}
+	return nil
+}
+
+func help(name string) {
+	cmd := findCommand(name)
+	if cmd == nil {
+		failf("unknown command %q\n", name)
+	}
+	output(fmt.Sprintf("Usage: vscgo %s", cmd.usage))
+	output()
+	output(fmt.Sprintf("%s is used to %s.", cmd.name(), cmd.short))
+	anyflags := false
+	cmd.flags.VisitAll(func(*flag.Flag) {
+		anyflags = true
+	})
+	if anyflags {
+		output()
+		output("Flags:")
+		output()
+		cmd.flags.PrintDefaults()
+	}
+}
+
+// runIncCounters increments telemetry counters read from stdin.
+func runIncCounters(_ []string) error {
+	scanner := bufio.NewScanner(os.Stdin)
+	return runIncCountersImpl(scanner, counter.Add)
+}
+
+const (
+	incCountersBadInput = "inc_counters_bad_input"
+)
+
+func incCountersInputLength(n int) string {
+	const name = "inc_counters_num_input"
+	for i := 1; i < 8; i *= 2 {
+		if n < i {
+			return fmt.Sprintf("%s:<%d", name, i)
+		}
+	}
+	return name + ":>=8"
+}
+
+func incCountersDuration(duration time.Duration) string {
+	const name = "inc_counters_duration"
+	switch {
+	case duration < 10*time.Millisecond:
+		return name + ":<10ms"
+	case duration < 100*time.Millisecond:
+		return name + ":<100ms"
+	case duration < 1*time.Second:
+		return name + ":<1s"
+	case duration < 10*time.Second:
+		return name + ":<10s"
+	}
+	return name + ":>=10s"
+}
+
+func runIncCountersImpl(scanner *bufio.Scanner, incCounter func(name string, count int64)) error {
+	start := time.Now()
+	linenum := 0
+	for scanner.Scan() {
+		line := strings.TrimSpace(scanner.Text())
+		if line == "" {
+			continue
+		}
+		var name string
+		var count int64
+		if _, err := fmt.Sscanf(line, "%s %d", &name, &count); err != nil || count < 0 {
+			incCounter(incCountersBadInput, 1)
+			return fmt.Errorf("invalid line: %q", line)
+		}
+		linenum++
+		incCounter(name, int64(count))
+	}
+	incCounter(incCountersInputLength(linenum), 1)
+	incCounter(incCountersDuration(time.Since(start)), 1)
+	return nil
+}
+
+func runVersion(_ []string) error {
+	info, ok := debug.ReadBuildInfo()
+	if !ok {
+		fmt.Println("vscgo: unknown")
+		fmt.Println("go: unknown")
+		return nil
+	}
+	fmt.Println("vscgo:", info.Main.Version)
+	fmt.Println("go:", info.GoVersion)
+	return nil
+}
+
+func runHelp(args []string) error {
+	switch len(args) {
+	case 1:
+		help(args[0])
+	default:
+		flag.Usage()
+		failf("too many arguments to \"help\"")
+	}
+	return nil
+}

vscgo/main_test.go

@@ -0,0 +1,93 @@
+// Copyright 2023 The Go Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+// The binary vscgo is a helper of the VS Code Go extension.
+// The source is distributed with the extension and compiled when
+// the extension is first activated.
+package main
+
+import (
+	"bufio"
+	"reflect"
+	"strings"
+	"testing"
+)
+
+func Test_runIncCounters(t *testing.T) {
+	tests := []struct {
+		name    string
+		in      string
+		want    map[string]int64
+		wantErr bool
+	}{
+		{
+			name: "empty",
+			in:   "",
+			want: map[string]int64{},
+		},
+		{
+			name: "single",
+			in:   "foo 7",
+			want: map[string]int64{"foo": 7},
+		},
+		{
+			name: "single",
+			in:   "\nfoo 7",
+			want: map[string]int64{"foo": 7},
+		},
+		{
+			name: "multiple",
+			in:   "foo 7\nbar 8\n",
+			want: map[string]int64{"foo": 7, "bar": 8},
+		},
+		{
+			name: "trim_space_in_name",
+			in:   " foo 1\n bar 3\n",
+			want: map[string]int64{"foo": 1, "bar": 3},
+		},
+		{
+			name: "nongraphic_char_in_name",
+			in:   "foo\u200b 1\nfoo 3\n",
+			want: map[string]int64{"foo\u200b": 1, "foo": 3},
+		},
+		{
+			name:    "invalid:missing_count",
+			in:      "\nfoo\nbar 1",
+			want:    map[string]int64{incCountersBadInput: 1},
+			wantErr: true,
+		},
+		{
+			name:    "invalid:missing_count2",
+			in:      "foo 1\n1",
+			want:    map[string]int64{"foo": 1, incCountersBadInput: 1},
+			wantErr: true,
+		},
+		{
+			name:    "invalid:negative_count",
+			in:      "foo 2\nbar -1\nbaz 8\n",
+			want:    map[string]int64{"foo": 2, incCountersBadInput: 1},
+			wantErr: true,
+		},
+	}
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			got := map[string]int64{}
+			incCounter := func(name string, count int64) {
+				if name != incCountersBadInput && strings.HasPrefix(name, "inc_counters_") {
+					// ignore our own counters, except the bad input counter.
+					return
+				}
+				got[name] = count
+			}
+			err := runIncCountersImpl(bufio.NewScanner(strings.NewReader(tt.in)), incCounter)
+			if (err != nil) != tt.wantErr {
+				t.Errorf("runIncCountersImpl(%q) = %v, wantErr=%v", tt.in, err, tt.wantErr)
+				return
+			}
+			if !reflect.DeepEqual(got, tt.want) {
+				t.Errorf("counters after runIncCountersImpl = %+v, want %+v", got, tt.want)
+			}
+		})
+	}
+}