test(bonfire): goldens for list, help and errors

- list, list --all, list --format=json and an --ansi styled list (D-13, D-16)
- admin:token:create help and a passthrough help; help <cmd> equals --help (D-14)
- error blocks: hint with {bin}, unknown command, -v chain on stderr (D-18)
- CheckDocs gaps in order and sorted; the version header and BuildVersion
- goldens render with color detection cleared; -update rewrites them

modules/bonfire/docs_test.go

@@ -0,0 +1,50 @@
+package bonfire
+
+import (
+	"reflect"
+	"testing"
+)
+
+// TestCheckDocs: every missing item is reported in a fixed order, blank
+// text counts as missing, results are sorted by command name and a fully
+// documented command reports nothing.
+func TestCheckDocs(t *testing.T) {
+	complete := Command{
+		Name: "acme:sync", Description: "Sync", Long: "Syncs.",
+		Args:     []Arg{{Name: "target", Description: "Where to"}},
+		Flags:    []Flag{{Name: "dry-run", Description: "Only print", Bare: true}},
+		Examples: []Example{{Command: "acme:sync prod"}},
+	}
+	if got := CheckDocs([]Command{complete}); len(got) != 0 {
+		t.Fatalf("complete command reported: %v", got)
+	}
+	if got := CheckDocs(nil); len(got) != 0 {
+		t.Fatalf("no commands reported: %v", got)
+	}
+
+	blank := complete
+	blank.Name, blank.Description, blank.Long = "acme:blank", "   ", "\n\t"
+	noExamples := complete
+	noExamples.Name, noExamples.Examples = "acme:noex", nil
+	undocumented := Command{
+		Name:  "acme:bare",
+		Args:  []Arg{{Name: "a"}, {Name: "b", Description: "B"}},
+		Flags: []Flag{{Name: "x"}, {Name: "y", Description: "Y"}, {Name: "z", Description: " "}},
+	}
+	got := CheckDocs([]Command{noExamples, complete, undocumented, blank})
+	want := []DocProblem{
+		{Command: "acme:bare", Missing: []string{"description", "long help", "examples", "argument a description", "option --x description", "option --z description"}},
+		{Command: "acme:blank", Missing: []string{"description", "long help"}},
+		{Command: "acme:noex", Missing: []string{"examples"}},
+	}
+	if !reflect.DeepEqual(got, want) {
+		t.Fatalf("CheckDocs =\n %v\nwant\n %v", got, want)
+	}
+	if s := got[1].String(); s != "acme:blank: missing description, long help" {
+		t.Errorf("String() = %q", s)
+	}
+	// The builtins list and help are documented.
+	if got := CheckDocs(builtinCommands()); len(got) != 0 {
+		t.Errorf("builtin commands reported: %v", got)
+	}
+}