Mar 7, 2023 · Feb 25, 2023 · Feb 25, 2023 · Feb 25, 2023 · Feb 25, 2023 · Feb 25, 2023
diff --git a/.golangci.yaml b/.golangci.yaml
    - asciicheck
    - bidichk
    - bodyclose
    - deadcode
    - dogsled
    - errcheck
    - errname
    - typecheck
    - unconvert
    - unused
    - varcheck
diff --git a/Makefile b/Makefile
 yarn run format:write:only ../docs/admin/prometheus.md

 docs/cli.md: scripts/clidocgen/main.go $(GO_SRC_FILES) docs/manifest.json
 rm -rf ./docs/cli/*.md
 # TODO(@ammario): re-enable server.md once we finish clibase migration.
 ls ./docs/cli/*.md | grep -vP "\/coder_server" | xargs rm
 BASE_PATH="." go run ./scripts/clidocgen
 cd site
 yarn run format:write:only ../docs/cli.md ../docs/cli/*.md ../docs/manifest.json
diff --git a/cli/clibase/clibase.go b/cli/clibase/clibase.go
 // Package clibase offers an all-in-one solution for a highly configurable CLI
 // application. Within Coder, we use it for our `server` subcommand, which
 // demands more functionality than cobra/viper can offer.
 //
 // We will extend its usage to the rest of our application, completely replacing
 // cobra/viper. It's also a candidate to be broken out into its own open-source
 // library, so we avoid deep coupling with Coder concepts.
 package clibase

 import (
 "strings"

 "golang.org/x/exp/maps"
 )

 // Group describes a hierarchy of groups that an option or command belongs to.
 type Group struct {
 Parent      *Group  `json:"parent,omitempty"`
 Name        string  `json:"name,omitempty"`
 Children    []Group `json:"children,omitempty"`
 Description string  `json:"description,omitempty"`
 }

 func (g *Group) AddChild(child Group) {
 child.Parent = g
 g.Children = append(g.Children, child)
 }

 // Ancestry returns the group and all of its parents, in order.
 func (g *Group) Ancestry() []Group {
 if g == nil {
 return nil
 }

 groups := []Group{*g}
 for p := g.Parent; p != nil; p = p.Parent {
 // Prepend to the slice so that the order is correct.
 groups = append([]Group{*p}, groups...)
 }
 return groups
 }

 func (g *Group) FullName() string {
 var names []string
 for _, g := range g.Ancestry() {
 names = append(names, g.Name)
 }
 return strings.Join(names, " / ")
 }

 // Annotations is an arbitrary key-mapping used to extend the Option and Command types.
 // Its methods won't panic if the map is nil.
 type Annotations map[string]string

 // Mark sets a value on the annotations map, creating one
 // if it doesn't exist. Mark does not mutate the original and
 // returns a copy. It is suitable for chaining.
 func (a Annotations) Mark(key string, value string) Annotations {
 var aa Annotations
 if a != nil {
 aa = maps.Clone(a)
 } else {
 aa = make(Annotations)
 }
 aa[key] = value
 return aa
 }

 // IsSet returns true if the key is set in the annotations map.
 func (a Annotations) IsSet(key string) bool {
 if a == nil {
 return false
 }
 _, ok := a[key]
 return ok
 }

 // Get retrieves a key from the map, returning false if the key is not found
 // or the map is nil.
 func (a Annotations) Get(key string) (string, bool) {
 if a == nil {
 return "", false
 }
 v, ok := a[key]
 return v, ok
 }
diff --git a/cli/clibase/cmd.go b/cli/clibase/cmd.go
 package clibase

 import "strings"

 // Cmd describes an executable command.
 type Cmd struct {
 // Parent is the direct parent of the command.
 Parent *Cmd
 // Children is a list of direct descendants.
 Children []*Cmd
 // Use is provided in form "command [flags] [args...]".
 Use string
 // Short is a one-line description of the command.
 Short string
 // Long is a detailed description of the command,
 // presented on its help page. It may contain examples.
 Long        string
 Options     OptionSet
 Annotations Annotations
 }

 // Name returns the first word in the Use string.
 func (c *Cmd) Name() string {
 return strings.Split(c.Use, " ")[0]
 }

 // FullName returns the full invocation name of the command,
 // as seen on the command line.
 func (c *Cmd) FullName() string {
 var names []string

 if c.Parent != nil {
 names = append(names, c.Parent.FullName())
 }
 names = append(names, c.Name())
 return strings.Join(names, " ")
 }

 // FullName returns usage of the command, preceded
 // by the usage of its parents.
 func (c *Cmd) FullUsage() string {
 var uses []string
 if c.Parent != nil {
 uses = append(uses, c.Parent.FullUsage())
 }
 uses = append(uses, c.Use)
 return strings.Join(uses, " ")
 }
diff --git a/cli/clibase/env.go b/cli/clibase/env.go
 package clibase

 import "strings"

 // name returns the name of the environment variable.
 func envName(line string) string {
 return strings.ToUpper(
 strings.SplitN(line, "=", 2)[0],
 )
 }

 // value returns the value of the environment variable.
 func envValue(line string) string {
 tokens := strings.SplitN(line, "=", 2)
 if len(tokens) < 2 {
 return ""
 }
 return tokens[1]
 }

 // Var represents a single environment variable of form
 // NAME=VALUE.
 type EnvVar struct {
 Name  string
 Value string
 }

 // EnvsWithPrefix returns all environment variables starting with
 // prefix without said prefix.
 func EnvsWithPrefix(environ []string, prefix string) []EnvVar {
 var filtered []EnvVar
 for _, line := range environ {
 name := envName(line)
 if strings.HasPrefix(name, prefix) {
 filtered = append(filtered, EnvVar{
 Name:  strings.TrimPrefix(name, prefix),
 Value: envValue(line),
 })
 }
 }
 return filtered
 }
diff --git a/cli/clibase/env_test.go b/cli/clibase/env_test.go
 package clibase_test

 import (
 "reflect"
 "testing"

 "github.com/coder/coder/cli/clibase"
 )

 func TestFilterNamePrefix(t *testing.T) {
 t.Parallel()
 type args struct {
 environ []string
 prefix  string
 }
 tests := []struct {
 name string
 args args
 want []clibase.EnvVar
 }{
 {"empty", args{[]string{}, "SHIRE"}, nil},
 {
 "ONE",
 args{
 []string{
 "SHIRE_BRANDYBUCK=hmm",
 },
 "SHIRE_",
 },
 []clibase.EnvVar{
 {Name: "BRANDYBUCK", Value: "hmm"},
 },
 },
 }
 for _, tt := range tests {
 tt := tt
 t.Run(tt.name, func(t *testing.T) {
 t.Parallel()
 if got := clibase.EnvsWithPrefix(tt.args.environ, tt.args.prefix); !reflect.DeepEqual(got, tt.want) {
 t.Errorf("EnvsWithPrefix() = %v, want %v", got, tt.want)
 }
 })
 }
 }
diff --git a/cli/clibase/option.go b/cli/clibase/option.go
 package clibase

 import (
 "os"

 "github.com/hashicorp/go-multierror"
 "github.com/spf13/pflag"
 "golang.org/x/xerrors"
 )

 // Option is a configuration option for a CLI application.
 type Option struct {
 Name        string `json:"name,omitempty"`
 Description string `json:"description,omitempty"`

 // Flag is the long name of the flag used to configure this option. If unset,
 // flag configuring is disabled.
 Flag string `json:"flag,omitempty"`
 // FlagShorthand is the one-character shorthand for the flag. If unset, no
 // shorthand is used.
 FlagShorthand string `json:"flag_shorthand,omitempty"`

 // Env is the environment variable used to configure this option. If unset,
 // environment configuring is disabled.
 Env string `json:"env,omitempty"`

 // YAML is the YAML key used to configure this option. If unset, YAML
 // configuring is disabled.
 YAML string `json:"yaml,omitempty"`

 // Default is parsed into Value if set.
 Default string `json:"default,omitempty"`
 // Value includes the types listed in values.go.
 Value pflag.Value `json:"value,omitempty"`

 // Annotations enable extensions to clibase higher up in the stack. It's useful for
 // help formatting and documentation generation.
 Annotations Annotations `json:"annotations,omitempty"`

 // Group is a group hierarchy that helps organize this option in help, configs
 // and other documentation.
 Group *Group `json:"group,omitempty"`

 // UseInstead is a list of options that should be used instead of this one.
 // The field is used to generate a deprecation warning.
 UseInstead []Option `json:"use_instead,omitempty"`

 Hidden bool `json:"hidden,omitempty"`
 }

 // OptionSet is a group of options that can be applied to a command.
 type OptionSet []Option

 // Add adds the given Options to the OptionSet.
 func (s *OptionSet) Add(opts ...Option) {
 *s = append(*s, opts...)
 }

 // FlagSet returns a pflag.FlagSet for the OptionSet.
 func (s *OptionSet) FlagSet() *pflag.FlagSet {
 fs := pflag.NewFlagSet("", pflag.ContinueOnError)
 for _, opt := range *s {
 if opt.Flag == "" {
 continue
 }
 var noOptDefValue string
 {
 no, ok := opt.Value.(NoOptDefValuer)
 if ok {
 noOptDefValue = no.NoOptDefValue()
 }
 }

 fs.AddFlag(&pflag.Flag{
 Name:        opt.Flag,
 Shorthand:   opt.FlagShorthand,
 Usage:       opt.Description,
 Value:       opt.Value,
 DefValue:    "",
 Changed:     false,
 Deprecated:  "",
 NoOptDefVal: noOptDefValue,
 Hidden:      opt.Hidden,
 })
 }
 fs.Usage = func() {
 _, _ = os.Stderr.WriteString("Override (*FlagSet).Usage() to print help text.\n")
 }
 return fs
 }

 // ParseEnv parses the given environment variables into the OptionSet.
 func (s *OptionSet) ParseEnv(globalPrefix string, environ []string) error {
 var merr *multierror.Error

 // We parse environment variables first instead of using a nested loop to
 // avoid N*M complexity when there are a lot of options and environment
 // variables.
 envs := make(map[string]string)
 for _, v := range EnvsWithPrefix(environ, globalPrefix) {
 envs[v.Name] = v.Value
 }

 for _, opt := range *s {
 if opt.Env == "" {
 continue
 }

 envVal, ok := envs[opt.Env]
 if !ok {
 continue
 }

 if err := opt.Value.Set(envVal); err != nil {
 merr = multierror.Append(
 merr, xerrors.Errorf("parse %q: %w", opt.Name, err),
 )
 }
 }

 return merr.ErrorOrNil()
 }

 // SetDefaults sets the default values for each Option.
 // It should be called before all parsing (e.g. ParseFlags, ParseEnv).
 func (s *OptionSet) SetDefaults() error {
 var merr *multierror.Error
 for _, opt := range *s {
 if opt.Default == "" {
 continue
 }
 if opt.Value == nil {
 merr = multierror.Append(
 merr,
 xerrors.Errorf(
 "parse %q: no Value field set\nFull opt: %+v",
 opt.Name, opt,
 ),
 )
 continue
 }
 if err := opt.Value.Set(opt.Default); err != nil {
 merr = multierror.Append(
 merr, xerrors.Errorf("parse %q: %w", opt.Name, err),
 )
 }
 }
 return merr.ErrorOrNil()
 }
Original file line number	Diff line number	Diff line change
Expand Up		@@ -215,7 +215,6 @@ linters:
		- asciicheck
		- bidichk
		- bodyclose
		- deadcode
		- dogsled
		- errcheck
		- errname
Expand DownExpand Up		@@ -259,4 +258,3 @@ linters:
		- typecheck
		- unconvert
		- unused
		- varcheck
Original file line number	Diff line number	Diff line change
Expand Up		@@ -501,7 +501,8 @@ docs/admin/prometheus.md: scripts/metricsdocgen/main.go scripts/metricsdocgen/me
		yarn run format:write:only ../docs/admin/prometheus.md

		docs/cli.md: scripts/clidocgen/main.go $(GO_SRC_FILES) docs/manifest.json
		rm -rf ./docs/cli/*.md
		# TODO(@ammario): re-enable server.md once we finish clibase migration.
		ls ./docs/cli/*.md \| grep -vP "\/coder_server" \| xargs rm
		BASE_PATH="." go run ./scripts/clidocgen
		cd site
		yarn run format:write:only ../docs/cli.md ../docs/cli/*.md ../docs/manifest.json
Expand Down
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,86 @@
		// Package clibase offers an all-in-one solution for a highly configurable CLI
		// application. Within Coder, we use it for our `server` subcommand, which
		// demands more functionality than cobra/viper can offer.
		//
		// We will extend its usage to the rest of our application, completely replacing
		// cobra/viper. It's also a candidate to be broken out into its own open-source
		// library, so we avoid deep coupling with Coder concepts.
		package clibase

		import (
		"strings"

		"golang.org/x/exp/maps"
		)

		// Group describes a hierarchy of groups that an option or command belongs to.
		type Group struct {
		Parent *Group `json:"parent,omitempty"`
		Name string `json:"name,omitempty"`
		Children []Group `json:"children,omitempty"`
		Description string `json:"description,omitempty"`
		}

		func (g *Group) AddChild(child Group) {
		child.Parent = g
		g.Children = append(g.Children, child)
		}

		// Ancestry returns the group and all of its parents, in order.
		func (g *Group) Ancestry() []Group {
		if g == nil {
		return nil
		}

		groups := []Group{*g}
		for p := g.Parent; p != nil; p = p.Parent {
		// Prepend to the slice so that the order is correct.
		groups = append([]Group{*p}, groups...)
		}
		return groups
		}

		func (g *Group) FullName() string {
		var names []string
		for _, g := range g.Ancestry() {
		names = append(names, g.Name)
		}
		return strings.Join(names, " / ")
		}

		// Annotations is an arbitrary key-mapping used to extend the Option and Command types.
		// Its methods won't panic if the map is nil.
		type Annotations map[string]string

		// Mark sets a value on the annotations map, creating one
		// if it doesn't exist. Mark does not mutate the original and
		// returns a copy. It is suitable for chaining.
		func (a Annotations) Mark(key string, value string) Annotations {
		var aa Annotations
		if a != nil {
		aa = maps.Clone(a)
		} else {
		aa = make(Annotations)
		}
		aa[key] = value
		return aa
		}

		// IsSet returns true if the key is set in the annotations map.
		func (a Annotations) IsSet(key string) bool {
		if a == nil {
		return false
		}
		_, ok := a[key]
		return ok
		}

		// Get retrieves a key from the map, returning false if the key is not found
		// or the map is nil.
		func (a Annotations) Get(key string) (string, bool) {
		if a == nil {
		return "", false
		}
		v, ok := a[key]
		return v, ok
		}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,48 @@
		package clibase

		import "strings"

		// Cmd describes an executable command.
		type Cmd struct {
		// Parent is the direct parent of the command.
		Parent *Cmd
		// Children is a list of direct descendants.
		Children []*Cmd
		// Use is provided in form "command [flags] [args...]".
		Use string
		// Short is a one-line description of the command.
		Short string
		// Long is a detailed description of the command,
		// presented on its help page. It may contain examples.
		Long string
		Options OptionSet
		Annotations Annotations
		}

		// Name returns the first word in the Use string.
		func (c *Cmd) Name() string {
		return strings.Split(c.Use, " ")[0]
		}

		// FullName returns the full invocation name of the command,
		// as seen on the command line.
		func (c *Cmd) FullName() string {
		var names []string

		if c.Parent != nil {
		names = append(names, c.Parent.FullName())
		}
		names = append(names, c.Name())
		return strings.Join(names, " ")
		}

		// FullName returns usage of the command, preceded
		// by the usage of its parents.
		func (c *Cmd) FullUsage() string {
		var uses []string
		if c.Parent != nil {
		uses = append(uses, c.Parent.FullUsage())
		}
		uses = append(uses, c.Use)
		return strings.Join(uses, " ")
		}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,42 @@
		package clibase
ammario marked this conversation as resolved. Show resolvedHide resolved

		import "strings"

		// name returns the name of the environment variable.
		func envName(line string) string {
		return strings.ToUpper(
		strings.SplitN(line, "=", 2)[0],
		)
		}

		// value returns the value of the environment variable.
		func envValue(line string) string {
		tokens := strings.SplitN(line, "=", 2)
		if len(tokens) < 2 {
		return ""
		}
		return tokens[1]
		}

		// Var represents a single environment variable of form
		// NAME=VALUE.
		type EnvVar struct {
		Name string
		Value string
		}

		// EnvsWithPrefix returns all environment variables starting with
		// prefix without said prefix.
		func EnvsWithPrefix(environ []string, prefix string) []EnvVar {
		var filtered []EnvVar
		for _, line := range environ {
		name := envName(line)
		if strings.HasPrefix(name, prefix) {
		filtered = append(filtered, EnvVar{
		Name: strings.TrimPrefix(name, prefix),
		Value: envValue(line),
		})
		}
		}
		return filtered
		}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,44 @@
		package clibase_test

		import (
		"reflect"
		"testing"

		"github.com/coder/coder/cli/clibase"
		)

		func TestFilterNamePrefix(t *testing.T) {
		t.Parallel()
		type args struct {
		environ []string
		prefix string
		}
		tests := []struct {
		name string
		args args
		want []clibase.EnvVar
		}{
		{"empty", args{[]string{}, "SHIRE"}, nil},
		{
		"ONE",
		args{
		[]string{
		"SHIRE_BRANDYBUCK=hmm",
		},
		"SHIRE_",
		},
		[]clibase.EnvVar{
		{Name: "BRANDYBUCK", Value: "hmm"},
		},
		},
		}
		for _, tt := range tests {
		tt := tt
		t.Run(tt.name, func(t *testing.T) {
		t.Parallel()
		if got := clibase.EnvsWithPrefix(tt.args.environ, tt.args.prefix); !reflect.DeepEqual(got, tt.want) {
		t.Errorf("EnvsWithPrefix() = %v, want %v", got, tt.want)
		}
		})
		}
		}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,149 @@
		package clibase

		import (
		"os"

		"github.com/hashicorp/go-multierror"
		"github.com/spf13/pflag"
		"golang.org/x/xerrors"
		)

		// Option is a configuration option for a CLI application.
		type Option struct {
		Name string `json:"name,omitempty"`
		Description string `json:"description,omitempty"`

		// Flag is the long name of the flag used to configure this option. If unset,
		// flag configuring is disabled.
		Flag string `json:"flag,omitempty"`
		// FlagShorthand is the one-character shorthand for the flag. If unset, no
		// shorthand is used.
		FlagShorthand string `json:"flag_shorthand,omitempty"`

		// Env is the environment variable used to configure this option. If unset,
		// environment configuring is disabled.
		Env string `json:"env,omitempty"`

		// YAML is the YAML key used to configure this option. If unset, YAML
		// configuring is disabled.
		YAML string `json:"yaml,omitempty"`

		// Default is parsed into Value if set.
		Default string `json:"default,omitempty"`
		// Value includes the types listed in values.go.
		Value pflag.Value `json:"value,omitempty"`

		// Annotations enable extensions to clibase higher up in the stack. It's useful for
		// help formatting and documentation generation.
		Annotations Annotations `json:"annotations,omitempty"`

		// Group is a group hierarchy that helps organize this option in help, configs
		// and other documentation.
		Group *Group `json:"group,omitempty"`

		// UseInstead is a list of options that should be used instead of this one.
		// The field is used to generate a deprecation warning.
		UseInstead []Option `json:"use_instead,omitempty"`

		Hidden bool `json:"hidden,omitempty"`
		}

		// OptionSet is a group of options that can be applied to a command.
		type OptionSet []Option

		// Add adds the given Options to the OptionSet.
		func (s *OptionSet) Add(opts ...Option) {
		s = append(s, opts...)
		}

		// FlagSet returns a pflag.FlagSet for the OptionSet.
		func (s OptionSet) FlagSet() pflag.FlagSet {
		fs := pflag.NewFlagSet("", pflag.ContinueOnError)
		for _, opt := range *s {
		if opt.Flag == "" {
		continue
		}
		var noOptDefValue string
		{
		no, ok := opt.Value.(NoOptDefValuer)
		if ok {
		noOptDefValue = no.NoOptDefValue()
		}
		}

		fs.AddFlag(&pflag.Flag{
		Name: opt.Flag,
		Shorthand: opt.FlagShorthand,
		Usage: opt.Description,
		Value: opt.Value,
		DefValue: "",
		Changed: false,
		Deprecated: "",
		NoOptDefVal: noOptDefValue,
		Hidden: opt.Hidden,
		})
		}
		fs.Usage = func() {
		_, _ = os.Stderr.WriteString("Override (*FlagSet).Usage() to print help text.\n")
		}
		return fs
		}

		// ParseEnv parses the given environment variables into the OptionSet.
		func (s *OptionSet) ParseEnv(globalPrefix string, environ []string) error {
		var merr *multierror.Error

		// We parse environment variables first instead of using a nested loop to
		// avoid N*M complexity when there are a lot of options and environment
		// variables.
		envs := make(map[string]string)
		for _, v := range EnvsWithPrefix(environ, globalPrefix) {
		envs[v.Name] = v.Value
		}

		for _, opt := range *s {
		if opt.Env == "" {
		continue
		}

		envVal, ok := envs[opt.Env]
		if !ok {
		continue
		}

		if err := opt.Value.Set(envVal); err != nil {
		merr = multierror.Append(
		merr, xerrors.Errorf("parse %q: %w", opt.Name, err),
		)
		}
		}

		return merr.ErrorOrNil()
		}

		// SetDefaults sets the default values for each Option.
		// It should be called before all parsing (e.g. ParseFlags, ParseEnv).
		func (s *OptionSet) SetDefaults() error {
		var merr *multierror.Error
		for _, opt := range *s {
		if opt.Default == "" {
		continue
		}
		if opt.Value == nil {
		merr = multierror.Append(
		merr,
		xerrors.Errorf(
		"parse %q: no Value field set\nFull opt: %+v",
		opt.Name, opt,
		),
		)
		continue
		}
		if err := opt.Value.Set(opt.Default); err != nil {
		merr = multierror.Append(
		merr, xerrors.Errorf("parse %q: %w", opt.Name, err),
		)
		}
		}
		return merr.ErrorOrNil()
		}