feat: add opt-in help-all command (ref #2362)

helpall.go

@@ -0,0 +1,180 @@
+// Copyright 2013-2023 The Cobra Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package cobra
+
+import (
+	"fmt"
+	"strings"
+
+	"github.com/spf13/pflag"
+)
+
+// commandInfo is extracted data for one entry in the help-all reference output.
+type commandInfo struct {
+	Path  string   // full command path, e.g. "app serve"
+	Args  string   // argument spec from Use field, e.g. "[session_id]"
+	Flags []string // formatted flag placeholders, e.g. "[--all]"
+	Short string   // one-line description
+}
+
+// collectCommands walks the command tree and returns a commandInfo for each
+// visible, runnable command (those where Runnable() is true). Hidden commands
+// and their subtrees are skipped. Deprecated commands are included.
+func collectCommands(root *Command) []commandInfo {
+	if root == nil {
+		return nil
+	}
+	var out []commandInfo
+	walkCommands(root, &out)
+	return out
+}
+
+// walkCommands recursively visits cmd and its children, appending a
+// commandInfo for each visible, runnable command. Hidden commands are
+// pruned along with their entire subtree.
+func walkCommands(cmd *Command, out *[]commandInfo) {
+	if cmd.Hidden {
+		return
+	}
+
+	if cmd.Runnable() {
+		info := commandInfo{
+			Path:  cmd.CommandPath(),
+			Args:  extractArgs(cmd.Use),
+			Short: cmd.Short,
+		}
+
+		cmd.LocalFlags().VisitAll(func(f *pflag.Flag) {
+			if f.Hidden {
+				return
+			}
+			info.Flags = append(info.Flags, formatFlag(f))
+		})
+
+		*out = append(*out, info)
+	}
+
+	for _, child := range cmd.Commands() {
+		walkCommands(child, out)
+	}
+}
+
+// extractArgs returns everything after the first space in a Use string,
+// which represents the argument placeholders.
+func extractArgs(use string) string {
+	if i := strings.IndexByte(use, ' '); i >= 0 {
+		return use[i+1:]
+	}
+	return ""
+}
+
+// formatFlag returns a bracket-wrapped flag placeholder appropriate for the
+// flag's type (bool/count get no value, int/duration/string get a placeholder).
+func formatFlag(f *pflag.Flag) string {
+	long := f.Name
+	short := f.Shorthand
+
+	switch f.Value.Type() {
+	case "bool", "count":
+		if short != "" {
+			return fmt.Sprintf("[-%s, --%s]", short, long)
+		}
+		return fmt.Sprintf("[--%s]", long)
+	case "int":
+		if short != "" {
+			return fmt.Sprintf("[-%s, --%s N]", short, long)
+		}
+		return fmt.Sprintf("[--%s N]", long)
+	case "duration":
+		if short != "" {
+			return fmt.Sprintf("[-%s, --%s DURATION]", short, long)
+		}
+		return fmt.Sprintf("[--%s DURATION]", long)
+	default:
+		placeholder := strings.ToUpper(long)
+		if short != "" {
+			return fmt.Sprintf("[-%s, --%s %s]", short, long, placeholder)
+		}
+		return fmt.Sprintf("[--%s %s]", long, placeholder)
+	}
+}
+
+// renderCommands formats command info into aligned, indented lines. When
+// verbose is true, flag placeholders are included before the description.
+func renderCommands(cmds []commandInfo, verbose bool) string {
+	if len(cmds) == 0 {
+		return ""
+	}
+
+	lefts := make([]string, len(cmds))
+	maxLen := 0
+	for i, c := range cmds {
+		parts := []string{c.Path}
+		if c.Args != "" {
+			parts = append(parts, c.Args)
+		}
+		if verbose {
+			parts = append(parts, c.Flags...)
+		}
+		lefts[i] = strings.Join(parts, " ")
+		if len(lefts[i]) > maxLen {
+			maxLen = len(lefts[i])
+		}
+	}
+
+	var b strings.Builder
+	indent := "    "
+	for i, c := range cmds {
+		padding := strings.Repeat(" ", maxLen-len(lefts[i])+2)
+		fmt.Fprintf(&b, "%s%s%s# %s", indent, lefts[i], padding, c.Short)
+		if i < len(cmds)-1 {
+			b.WriteByte('\n')
+		}
+	}
+	return b.String()
+}
+
+// NewHelpAllCommand returns a help-all command that prints a complete, aligned
+// command reference. Add it to root with root.AddCommand(). Pass --verbose to
+// include flag placeholders in the output.
+//
+//	rootCmd.AddCommand(cobra.NewHelpAllCommand())
+//
+//	// or with a custom name:
+//	cmd := cobra.NewHelpAllCommand()
+//	cmd.Use = "my-custom-name"
+//	rootCmd.AddCommand(cmd)
+func NewHelpAllCommand() *Command {
+	var verbose bool
+
+	cmd := &Command{
+		Use:    "help-all",
+		Short:  "List all commands with their arguments and descriptions",
+		Args: NoArgs,
+		RunE: func(cmd *Command, args []string) error {
+			cmds := collectCommands(cmd.Root())
+			out := renderCommands(cmds, verbose)
+			if out != "" {
+				_, err := fmt.Fprintln(cmd.OutOrStdout(), out)
+				return err
+			}
+			return nil
+		},
+	}
+
+	cmd.Flags().BoolVar(&verbose, "verbose", false, "Include flags in output")
+
+	return cmd
+}