cmd/cue: fail when requesting a missing help topic

We cover all edge cases now; a missing help command, sub-command,
and "cmd" command, as well as all the valid help combinations.

Note that for unknown "cmd" commands we print a more precise error,
and we also check that custom commands are added to the help text
in all cases where we print help text for cmd.

We join help_hello.txtar with help_cmd.txtar given their overlap.

Thanks to Naoki Kuroda for proposing a version of the fix in #2759
which was adapted here, along with more testscript coverage.

Fixes #2560.
Fixes #2918.
Closes #2759 as partially merged.

Signed-off-by: Daniel Martí <mvdan@mvdan.cc>
Change-Id: I252e57c59eab499e40daea45355f1da75acba249
Reviewed-on: https://review.gerrithub.io/c/cue-lang/cue/+/1194247
TryBot-Result: CUEcueckoo <cueckoo@cuelang.org>
Reviewed-by: Paul Jolly <paul@myitcv.io>

cmd/cue/cmd/help.go

@@ -16,6 +16,7 @@ package cmd
 
 import (
 	"bufio"
+	"fmt"
 	"strings"
 
 	"github.com/spf13/cobra"
@@ -40,8 +41,14 @@ func newHelpCmd(c *Command) *cobra.Command {
 		Long: `Help provides help for any command in the application.
 Simply type ` + c.Name() + ` help [path to command] for full details.`,
 		Run: func(_ *cobra.Command, args []string) {
-			cmd, _, e := c.Root().Find(args)
-			if len(args) > 0 && args[0] == "cmd" {
+			findCmd := func() (*cobra.Command, bool) {
+				cmd, rest, err := c.Root().Find(args)
+				found := cmd != nil && err == nil && len(rest) == 0
+				return cmd, found
+			}
+			cmd, found := findCmd()
+			isCmd := len(args) > 0 && args[0] == "cmd"
+			if isCmd {
 				// args is one of:
 				//
 				//	["cmd"]
@@ -58,12 +65,21 @@ Simply type ` + c.Name() + ` help [path to command] for full details.`,
 				if err == nil {
 					addCustomCommands(c, cmd, commandSection, tools)
 					// For the sake of `cue help cmd mycmd`, find the command again.
-					cmd, _, e = c.Root().Find(args)
+					cmd, found = findCmd()
 				}
 			}
-			if cmd == nil || e != nil {
-				c.Printf("Unknown help topic %#q\n", args)
-				cobra.CheckErr(c.Root().Usage())
+			if !found {
+				if isCmd {
+					// Note that for args ["cmd", "mycmd", "./mypkg"] we only want "mycmd".
+					fmt.Fprintf(c.Stderr(), "Unknown cmd command: %s\n", args[1])
+				} else {
+					fmt.Fprintf(c.Stderr(), "Unknown help topic: %s\n", strings.Join(args, " "))
+				}
+				if cmd == nil {
+					cobra.CheckErr(c.Root().Usage())
+				} else {
+					cobra.CheckErr(cmd.Usage())
+				}
 			} else {
 				cobra.CheckErr(cmd.Help())
 			}

cmd/cue/cmd/testdata/script/help.txtar

@@ -1,4 +1,4 @@
-# Verify that the various forms of requesting help work
+# Verify that the various forms of requesting the top-level help.
 
 exec cue
 cmp stdout stdout.golden
@@ -12,6 +12,42 @@ cmp stdout stdout.golden
 exec cue -h
 cmp stdout stdout.golden
 
+# Requesting help for commands and sub-commands.
+
+exec cue help mod
+stdout -count=1 'groups commands which operate on CUE modules'
+stdout -count=1 'publish *publish the current module to a registry$'
+
+exec cue mod --help
+stdout -count=1 'groups commands which operate on CUE modules'
+stdout -count=1 'publish *publish the current module to a registry$'
+
+exec cue help mod publish
+stdout -count=1 '^Publish the current module to an OCI registry\.'
+
+exec cue mod publish --help
+stdout -count=1 '^Publish the current module to an OCI registry\.'
+
+# Requesting additional help topics, with or without "help" in between.
+
+exec cue help filetypes
+stdout -count=1 '^The cue tools supports the following file types:$'
+
+exec cue filetypes
+stdout -count=1 '^The cue tools supports the following file types:$'
+
+# Requesting help for missing commands and sub-commands fails and prints the help text.
+
+! exec cue help missing
+! stdout .
+stderr -count=1 'Unknown help topic: missing'
+stderr -count=1 '^Available Commands:$'
+
+! exec cue help mod missing
+! stdout .
+stderr -count=1 'Unknown help topic: mod missing'
+stderr -count=1 '^Available Commands:$'
+
 -- stdout.golden --
 cue evaluates CUE files, an extension of JSON, and sends them
 to user-defined commands for processing.

cmd/cue/cmd/testdata/script/help_cmd.txtar

@@ -5,13 +5,25 @@ cmp stderr cue-cmd.stderr
 exec cue help cmd
 cmp stdout cue-help-cmd.stdout
 
+exec cue help cmd hello
+cmp stdout cue-help-cmd-hello.stdout
+
+! exec cue help cmd missing
+stderr -count=1 'Unknown cmd command: missing'
+stderr -count=1 '^Available Commands:$'
+stderr -count=1 'hello *say hello to someone'
+
 -- cue.mod/module.cue --
 -- task_tool.cue --
 package home
 
 import "tool/cli"
 
 // say hello to someone
+//
+//   Usage: hello
+//
+// Hello can be used to say hello to the world.
 command: hello: {
     task: say: {
         cli.Print
@@ -157,3 +169,16 @@ Global Flags:
   -v, --verbose      print information about progress
 
 Use "cue cmd [command] --help" for more information about a command.
+-- cue-help-cmd-hello.stdout --
+Hello can be used to say hello to the world.
+
+Usage:
+  cue cmd hello [flags]
+
+Global Flags:
+  -E, --all-errors   print all available errors
+  -i, --ignore       proceed in the presence of errors
+  -s, --simplify     simplify output
+      --strict       report errors for lossy mappings
+      --trace        trace computation
+  -v, --verbose      print information about progress