cmd/lava: implement built-in docs

cmd/lava/internal/help/help.go

@@ -19,7 +19,7 @@ func Help(args []string) {
 		return
 	}
 	if len(args) != 1 {
-		fmt.Fprintf(os.Stderr, "usage: lava help command\n\nToo many arguments given.\n")
+		fmt.Fprintf(os.Stderr, "usage: lava help <topic>\n\nToo many arguments given.\n")
 		os.Exit(2)
 	}
 
@@ -32,7 +32,7 @@ func Help(args []string) {
 		}
 	}
 
-	fmt.Fprintf(os.Stderr, "Unknown command %q. Run 'lava help'.\n", arg)
+	fmt.Fprintf(os.Stderr, "Unknown help topic %q. Run 'lava help'.\n", arg)
 	os.Exit(2)
 }
 
@@ -55,16 +55,22 @@ const usageTemplate = `Lava runs Vulcan checks locally
 
 Usage:
 
-	lava command [arguments]
+	lava <command> [arguments]
 
 The commands are:
-{{range .}}
-	{{.Name | printf "%-11s"}} {{.Short}}{{end}}
+{{range .}}{{ if .Run}}
+	{{.Name | printf "%-11s"}} {{.Short}}{{end}}{{end}}
 
-Use "lava help [command]" for more information about a command.
+Use 'lava help <command>' for more information about a command.
+
+Additional help topics:
+{{range .}}{{if not .Run}}
+	{{.Name | printf "%-11s"}} {{.Short}}{{end}}{{end}}
+
+Use 'lava help <topic>' for more information about that topic.
 `
 
-const helpTemplate = `usage: lava {{.UsageLine}}
+const helpTemplate = `{{if .Run}}usage: lava {{.UsageLine}}
 
-{{.Long | trim}}
+{{end}}{{.Long | trim}}
 `

cmd/lava/internal/help/helpdoc.go

@@ -0,0 +1,14 @@
+// Copyright 2023 Adevinta
+
+package help
+
+import "github.com/adevinta/lava/cmd/lava/internal/base"
+
+// HelpConfigfile documents the configuration file format.
+var HelpConfigfile = &base.Command{
+	UsageLine: "configfile",
+	Short:     "configuration file format",
+	Long: `
+TODO(rm): add documentation about the Lava configuration file format.
+	`,
+}

cmd/lava/main.go

@@ -21,6 +21,8 @@ func init() {
 	base.Commands = []*base.Command{
 		scan.CmdScan,
 		initialize.CmdInit,
+
+		help.HelpConfigfile,
 	}
 }
 
@@ -43,6 +45,9 @@ func main() {
 	}
 
 	for _, cmd := range base.Commands {
+		if cmd.Run == nil {
+			continue
+		}
 		cmd.Flag.Usage = cmd.Usage
 		if cmd.Name() == args[0] {
 			cmd.Flag.Parse(args[1:]) //nolint:errcheck
@@ -55,6 +60,6 @@ func main() {
 		}
 	}
 
-	fmt.Fprintf(os.Stderr, "lava: unknown command %q\nRun 'lava help' for usage.\n", args[0])
+	fmt.Fprintf(os.Stderr, "Unknown command %q. Run 'lava help'.\n", args[0])
 	os.Exit(2)
 }