Install shared reporting flags

internal/cobra/parse.go

@@ -77,8 +77,11 @@ func (session *Session) Parse(argv []string) commandmeta.Result {
 	}
 
 	remaining := append(commandpath.CloneTokens(unconsumed), tail...)
-	interpreted, spellings, interpretationFailure := interpretFlagTokens(remaining, selectedNode.Flags, session.flagAliases)
-	for _, flag := range selectedNode.Flags {
+	localFlags := make([]commandmeta.Flag, 0, len(selectedNode.Flags)+len(selectedNode.CoreFlags))
+	localFlags = append(localFlags, selectedNode.Flags...)
+	localFlags = append(localFlags, selectedNode.CoreFlags...)
+	interpreted, spellings, interpretationFailure := interpretFlagTokens(remaining, localFlags, session.flagAliases)
+	for _, flag := range localFlags {
 		if value := selected.Flags().Lookup(flag.Name); value != nil {
 			value.Value.(*rawValue).queueSpellings(spellings[flag.Name])
 		}
@@ -209,6 +212,12 @@ func appendHelpAliases(content string, commandAliases []commandmeta.CommandAlias
 
 func renderDiscoveryHelp(rootName string, view commandmeta.HelpView) string {
 	lines := []string{"Usage:", "  " + displayCommandPath(rootName, view.EnteredPath) + " [command]"}
+	if len(view.CoreFlags) > 0 {
+		lines = append(lines, "", "Reporting Flags:")
+		for _, flag := range view.CoreFlags {
+			lines = append(lines, "  --"+flag.Name+" — "+flag.Usage+" (default: "+flag.Default+")")
+		}
+	}
 	if len(view.CommandAliases) > 0 {
 		lines = append(lines, "", "Available Aliases:")
 		for _, alias := range view.CommandAliases {
@@ -309,7 +318,7 @@ func buildTree(root *commandmeta.Command, options commandmeta.ParseOptions) (*sp
 		helpFlag := backend.Flags().Lookup("help")
 		helpFlag.NoOptDefVal = "true"
 		helpFlag.Usage = "help for this command (default: false)"
-		for _, declarationFlag := range declaration.Flags {
+		for _, declarationFlag := range append(append([]commandmeta.Flag(nil), declaration.Flags...), declaration.CoreFlags...) {
 			value := &rawValue{boolean: declarationFlag.Boolean}
 			backend.Flags().VarP(value, declarationFlag.Name, declarationFlag.Short, flagUsage(declarationFlag))
 			backendFlag := backend.Flags().Lookup(declarationFlag.Name)

internal/cobra/parse_test.go

@@ -77,6 +77,62 @@ func TestParseInterspersedOperandsBooleanFlagsAndTerminator(t *testing.T) {
 	}
 }
 
+func TestReportingFlagsParseWithoutChangingConsumerFlagIndexes(t *testing.T) {
+	tree := &Command{Name: "app", CoreFlags: commandmeta.ReportingFlags(), Children: []*Command{
+		{Name: "config", CoreFlags: commandmeta.ReportingFlags(), Children: []*Command{
+			{Name: "show", Runnable: true, CoreFlags: commandmeta.ReportingFlags(), Flags: []Flag{{Name: "format"}}},
+		}},
+	}}
+	result := Parse(tree, []string{"config", "show", "--quiet", "-v", "--format=yaml"}, ParseOptions{
+		FlagAliases: []commandmeta.FlagAlias{{Source: "-v", Target: "--verbose"}},
+	})
+	if result.Failure != nil {
+		t.Fatalf("parse failed: %s", result.Failure.Message)
+	}
+	if !reflect.DeepEqual(result.FlagValues, [][]string{{"yaml"}}) {
+		t.Fatalf("consumer binding values = %#v", result.FlagValues)
+	}
+	if !reflect.DeepEqual(result.FlagSpellings, [][]string{{"--format"}}) {
+		t.Fatalf("consumer binding spellings = %#v", result.FlagSpellings)
+	}
+}
+
+func TestReportingFlagsAppearInCanonicalAndDiscoveryHelp(t *testing.T) {
+	flags := commandmeta.ReportingFlags()
+	root := &Command{Name: "app", CoreFlags: flags, Children: []*Command{
+		{Name: "group", CoreFlags: commandmeta.ReportingFlags(), Children: []*Command{
+			{Name: "run", Runnable: true, CoreFlags: commandmeta.ReportingFlags()},
+		}},
+		{Name: "version", Runnable: true, CoreFlags: commandmeta.ReportingFlags()},
+	}}
+	session := Prepare(root, ParseOptions{})
+	for _, path := range [][]string{nil, {"group"}, {"group", "run"}, {"version"}} {
+		help, failure := session.RenderHelp(path)
+		if failure != nil {
+			t.Fatalf("help for %v failed: %s", path, failure.Message)
+		}
+		for _, name := range []string{"quiet", "verbose", "debug", "progress"} {
+			if !strings.Contains(help, "--"+name) {
+				t.Errorf("help for %v omits --%s: %q", path, name, help)
+			}
+		}
+	}
+	discovery, failure := session.RenderHelpView(commandmeta.HelpView{
+		EnteredPath: []string{"shortcut"}, Discovery: true, CoreFlags: commandmeta.ReportingFlags(),
+	})
+	if failure != nil {
+		t.Fatal(failure.Message)
+	}
+	for _, name := range []string{"quiet", "verbose", "debug", "progress"} {
+		if !strings.Contains(discovery, "--"+name) {
+			t.Errorf("discovery help omits --%s: %q", name, discovery)
+		}
+	}
+	if strings.Contains(discovery, "Available Commands:") || len(session.Metadata().Children) != 2 {
+		t.Fatalf("discovery help manufactured canonical command metadata: %q", discovery)
+	}
+}
+
 func TestParseHelpIsLocalAndFalseDoesNotRequestHelp(t *testing.T) {
 	tree := &Command{Name: "app", Children: []*Command{
 		{Name: "run", Runnable: true, Flags: []Flag{{Name: "required", Required: true}}},

internal/commandmeta/metadata.go

@@ -18,8 +18,10 @@ type Command struct {
 	Description string
 	Runnable    bool
 	Flags       []Flag
-	Arguments   []Argument
-	Children    []*Command
+	// CoreFlags are parsed by CommandKit but do not occupy consumer binding indexes.
+	CoreFlags []Flag
+	Arguments []Argument
+	Children  []*Command
 }
 
 // Argument describes one positional input for usage rendering.
@@ -41,6 +43,26 @@ type Flag struct {
 	Required bool
 }
 
+var reportingFlags = [...]Flag{
+	{Name: "quiet", Usage: "suppress substantive output and optional messages; keep failures visible", Default: "false", Boolean: true},
+	{Name: "verbose", Usage: "show warning and informational messages", Default: "false", Boolean: true},
+	{Name: "debug", Usage: "show debugging messages", Default: "false", Boolean: true},
+	{Name: "progress", Usage: "show progress messages", Default: "false", Boolean: true},
+}
+
+// ReportingFlags returns the flags shared by CommandKit's invocation reporter.
+func ReportingFlags() []Flag { return append([]Flag(nil), reportingFlags[:]...) }
+
+// IsReportingFlag reports whether name is reserved for a shared reporting flag.
+func IsReportingFlag(name string) bool {
+	for _, flag := range reportingFlags {
+		if flag.Name == name {
+			return true
+		}
+	}
+	return false
+}
+
 // FlagAlias maps one option spelling to a canonical flag spelling.
 type FlagAlias struct {
 	Source string
@@ -58,6 +80,7 @@ type HelpView struct {
 	EnteredPath    []string
 	CanonicalPath  []string
 	Discovery      bool
+	CoreFlags      []Flag
 	CommandAliases []CommandAlias
 	FlagAliases    []FlagAlias
 }

internal/commandmeta/metadata_test.go

@@ -0,0 +1,28 @@
+package commandmeta
+
+import "testing"
+
+func TestReportingFlagsAreBooleanAndReturnedIndependently(t *testing.T) {
+	flags := ReportingFlags()
+	want := []string{"quiet", "verbose", "debug", "progress"}
+	if len(flags) != len(want) {
+		t.Fatalf("reporting flags = %#v", flags)
+	}
+	for index, name := range want {
+		if flags[index].Name != name || !flags[index].Boolean || flags[index].Short != "" || flags[index].Default != "false" {
+			t.Errorf("reporting flag %d = %#v", index, flags[index])
+		}
+		if !IsReportingFlag(name) {
+			t.Errorf("%q is not recognized as a reporting flag", name)
+		}
+	}
+	flags[0].Name = "changed"
+	if ReportingFlags()[0].Name != "quiet" {
+		t.Fatal("caller mutation changed shared reporting metadata")
+	}
+	for _, name := range []string{"help", "quietly", ""} {
+		if IsReportingFlag(name) {
+			t.Errorf("%q was incorrectly recognized as a reporting flag", name)
+		}
+	}
+}