diff --git a/pkg/cmdutil/args.go b/pkg/cmdutil/args.go index b0a22e9b5..41568b84b 100644 --- a/pkg/cmdutil/args.go +++ b/pkg/cmdutil/args.go @@ -8,6 +8,7 @@ import ( "github.com/spf13/pflag" ) +// MinimumArgs returns a PositionalArgs validator that requires at least n arguments. func MinimumArgs(n int, msg string) cobra.PositionalArgs { if msg == "" { return cobra.MinimumNArgs(1) @@ -21,6 +22,7 @@ func MinimumArgs(n int, msg string) cobra.PositionalArgs { } } +// ExactArgs returns a PositionalArgs validator that requires exactly n arguments. func ExactArgs(n int, msg string) cobra.PositionalArgs { return func(cmd *cobra.Command, args []string) error { if len(args) > n { @@ -35,6 +37,7 @@ func ExactArgs(n int, msg string) cobra.PositionalArgs { } } +// NoArgsQuoteReminder is a PositionalArgs validator that rejects arguments with a hint to quote values containing spaces. func NoArgsQuoteReminder(cmd *cobra.Command, args []string) error { if len(args) < 1 { return nil diff --git a/pkg/cmdutil/auth_check.go b/pkg/cmdutil/auth_check.go index d8a43176a..a2640beec 100644 --- a/pkg/cmdutil/auth_check.go +++ b/pkg/cmdutil/auth_check.go @@ -10,6 +10,7 @@ import ( const skipAuthCheckAnnotation = "skipAuthCheck" +// DisableAuthCheck annotates a command so that it skips the authentication check. func DisableAuthCheck(cmd *cobra.Command) { if cmd.Annotations == nil { cmd.Annotations = map[string]string{} @@ -18,6 +19,7 @@ func DisableAuthCheck(cmd *cobra.Command) { cmd.Annotations[skipAuthCheckAnnotation] = "true" } +// DisableAuthCheckFlag annotates a flag so that setting it skips the authentication check. func DisableAuthCheckFlag(flag *pflag.Flag) { if flag.Annotations == nil { flag.Annotations = map[string][]string{} @@ -26,6 +28,7 @@ func DisableAuthCheckFlag(flag *pflag.Flag) { flag.Annotations[skipAuthCheckAnnotation] = []string{"true"} } +// CheckAuth reports whether valid authentication credentials are available in the given config. func CheckAuth(cfg gh.Config) bool { if cfg.Authentication().HasEnvToken() { return true @@ -38,6 +41,7 @@ func CheckAuth(cfg gh.Config) bool { return false } +// IsAuthCheckEnabled reports whether the authentication check should run for the given command. func IsAuthCheckEnabled(cmd *cobra.Command) bool { switch cmd.Name() { case "help", cobra.ShellCompRequestCmd, cobra.ShellCompNoDescRequestCmd: diff --git a/pkg/cmdutil/cmdgroup.go b/pkg/cmdutil/cmdgroup.go index e1b7b2362..98d7bba12 100644 --- a/pkg/cmdutil/cmdgroup.go +++ b/pkg/cmdutil/cmdgroup.go @@ -2,6 +2,7 @@ package cmdutil import "github.com/spf13/cobra" +// AddGroup creates a new command group with the given title and adds the provided commands to it under the parent command. func AddGroup(parent *cobra.Command, title string, cmds ...*cobra.Command) { g := &cobra.Group{ Title: title, diff --git a/pkg/cmdutil/errors.go b/pkg/cmdutil/errors.go index edb97abcd..3ff450f33 100644 --- a/pkg/cmdutil/errors.go +++ b/pkg/cmdutil/errors.go @@ -23,10 +23,12 @@ type FlagError struct { err error } +// Error returns the underlying error message. func (fe *FlagError) Error() string { return fe.err.Error() } +// Unwrap returns the wrapped error. func (fe *FlagError) Unwrap() error { return fe.err } @@ -40,10 +42,12 @@ var CancelError = errors.New("CancelError") // PendingError signals nothing failed but something is pending var PendingError = errors.New("PendingError") +// IsUserCancellation reports whether err indicates that the user cancelled the operation. func IsUserCancellation(err error) bool { return errors.Is(err, CancelError) || errors.Is(err, terminal.InterruptErr) } +// MutuallyExclusive returns a FlagError with the given message if more than one of the conditions is true. func MutuallyExclusive(message string, conditions ...bool) error { numTrue := 0 for _, ok := range conditions { @@ -57,14 +61,17 @@ func MutuallyExclusive(message string, conditions ...bool) error { return nil } +// NoResultsError represents an error indicating that a query returned no results. type NoResultsError struct { message string } +// Error returns the no-results message. func (e NoResultsError) Error() string { return e.message } +// NewNoResultsError creates a NoResultsError with the given message. func NewNoResultsError(message string) NoResultsError { return NoResultsError{message: message} } diff --git a/pkg/cmdutil/factory.go b/pkg/cmdutil/factory.go index b90960b31..95026322b 100644 --- a/pkg/cmdutil/factory.go +++ b/pkg/cmdutil/factory.go @@ -16,6 +16,7 @@ import ( "github.com/cli/cli/v2/pkg/iostreams" ) +// Factory provides common dependencies for command constructors. type Factory struct { AppVersion string ExecutableName string diff --git a/pkg/cmdutil/file_input.go b/pkg/cmdutil/file_input.go index e4cfd218a..b35cd3cd0 100644 --- a/pkg/cmdutil/file_input.go +++ b/pkg/cmdutil/file_input.go @@ -5,6 +5,7 @@ import ( "os" ) +// ReadFile reads the contents of filename, or from stdin if filename is "-". func ReadFile(filename string, stdin io.ReadCloser) ([]byte, error) { if filename == "-" { b, err := io.ReadAll(stdin) diff --git a/pkg/cmdutil/flags.go b/pkg/cmdutil/flags.go index c0064099c..e45f5d25d 100644 --- a/pkg/cmdutil/flags.go +++ b/pkg/cmdutil/flags.go @@ -35,6 +35,7 @@ func StringEnumFlag(cmd *cobra.Command, p *string, name, shorthand, defaultValue return f } +// StringSliceEnumFlag defines a new string-slice flag that only allows values listed in options. func StringSliceEnumFlag(cmd *cobra.Command, p *[]string, name, shorthand string, defaultValues, options []string, usage string) *pflag.Flag { *p = defaultValues val := &enumMultiValue{value: p, options: options} @@ -77,11 +78,13 @@ func newStringValue(p **string) *stringValue { return &stringValue{p} } +// Set assigns the string value. func (s *stringValue) Set(value string) error { *s.string = &value return nil } +// String returns the current string value or an empty string if unset. func (s *stringValue) String() string { if s.string == nil || *s.string == nil { return "" @@ -89,6 +92,7 @@ func (s *stringValue) String() string { return **s.string } +// Type returns the flag type name "string". func (s *stringValue) Type() string { return "string" } @@ -101,12 +105,14 @@ func newBoolValue(p **bool) *boolValue { return &boolValue{p} } +// Set parses and assigns the boolean value. func (b *boolValue) Set(value string) error { v, err := strconv.ParseBool(value) *b.bool = &v return err } +// String returns the current boolean value as a string. func (b *boolValue) String() string { if b.bool == nil || *b.bool == nil { return "false" @@ -116,10 +122,12 @@ func (b *boolValue) String() string { return "false" } +// Type returns the flag type name "bool". func (b *boolValue) Type() string { return "bool" } +// IsBoolFlag returns true, indicating this flag does not require an argument. func (b *boolValue) IsBoolFlag() bool { return true } @@ -129,6 +137,7 @@ type enumValue struct { options []string } +// Set validates and assigns the value, returning an error if it is not in the allowed options. func (e *enumValue) Set(value string) error { if !isIncluded(value, e.options) { return fmt.Errorf("valid values are %s", formatValuesForUsageDocs(e.options)) @@ -137,10 +146,12 @@ func (e *enumValue) Set(value string) error { return nil } +// String returns the current enum value. func (e *enumValue) String() string { return *e.string } +// Type returns the flag type name "string". func (e *enumValue) Type() string { return "string" } @@ -150,6 +161,7 @@ type enumMultiValue struct { options []string } +// Set validates and appends comma-separated values, returning an error if any value is not in the allowed options. func (e *enumMultiValue) Set(value string) error { items := strings.Split(value, ",") for _, item := range items { @@ -161,6 +173,7 @@ func (e *enumMultiValue) Set(value string) error { return nil } +// String returns the current values formatted as a brace-enclosed, comma-separated list. func (e *enumMultiValue) String() string { if len(*e.value) == 0 { return "" @@ -168,6 +181,7 @@ func (e *enumMultiValue) String() string { return fmt.Sprintf("{%s}", strings.Join(*e.value, ", ")) } +// Type returns the flag type name "stringSlice". func (e *enumMultiValue) Type() string { return "stringSlice" } diff --git a/pkg/cmdutil/json_flags.go b/pkg/cmdutil/json_flags.go index 579d38552..1f477c3ae 100644 --- a/pkg/cmdutil/json_flags.go +++ b/pkg/cmdutil/json_flags.go @@ -19,10 +19,12 @@ import ( "github.com/spf13/pflag" ) +// JSONFlagError wraps an error related to JSON flag validation. type JSONFlagError struct { error } +// AddJSONFlags registers --json, --jq, and --template flags on the command. func AddJSONFlags(cmd *cobra.Command, exportTarget *Exporter, fields []string) { f := cmd.Flags() addJsonFlag(f) @@ -32,6 +34,7 @@ func AddJSONFlags(cmd *cobra.Command, exportTarget *Exporter, fields []string) { setupJsonFlags(cmd, exportTarget, fields) } +// AddJSONFlagsWithoutShorthand registers --json, --jq, and --template flags without short-hand aliases. func AddJSONFlagsWithoutShorthand(cmd *cobra.Command, exportTarget *Exporter, fields []string) { f := cmd.Flags() addJsonFlag(f) @@ -143,6 +146,7 @@ func checkJSONFlags(cmd *cobra.Command) (*jsonExporter, error) { return nil, nil } +// AddFormatFlags registers --format, --jq, and --template flags on the command. func AddFormatFlags(cmd *cobra.Command, exportTarget *Exporter) { var format string StringEnumFlag(cmd, &format, "format", "", "", []string{"json"}, "Output format") @@ -195,6 +199,7 @@ func checkFormatFlags(cmd *cobra.Command) (*jsonExporter, error) { return nil, nil } +// Exporter defines methods for writing structured output from commands. type Exporter interface { Fields() []string Write(io *iostreams.IOStreams, data interface{}) error @@ -211,10 +216,12 @@ func NewJSONExporter() *jsonExporter { return &jsonExporter{} } +// Fields returns the list of field names to export. func (e *jsonExporter) Fields() []string { return e.fields } +// SetFields sets the list of field names to export. func (e *jsonExporter) SetFields(fields []string) { e.fields = fields } diff --git a/pkg/cmdutil/repo_override.go b/pkg/cmdutil/repo_override.go index 791dd919a..6e66c5465 100644 --- a/pkg/cmdutil/repo_override.go +++ b/pkg/cmdutil/repo_override.go @@ -19,6 +19,7 @@ func executeParentHooks(cmd *cobra.Command, args []string) error { return nil } +// EnableRepoOverride adds a --repo flag to the command and configures the factory to use it. func EnableRepoOverride(cmd *cobra.Command, f *Factory) { cmd.PersistentFlags().StringP("repo", "R", "", "Select another repository using the `[HOST/]OWNER/REPO` format") _ = cmd.RegisterFlagCompletionFunc("repo", func(cmd *cobra.Command, args []string, toComplete string) ([]string, cobra.ShellCompDirective) { @@ -57,6 +58,7 @@ func EnableRepoOverride(cmd *cobra.Command, f *Factory) { } } +// OverrideBaseRepoFunc returns a BaseRepo function that resolves to the override repository when set. func OverrideBaseRepoFunc(f *Factory, override string) func() (ghrepo.Interface, error) { if override == "" { override = os.Getenv("GH_REPO")