* docs: generate CLI reference from live help * docs(cli): move bd version stamp from per-command pages to index only Drops the `(bd version X.Y.Z)` suffix from the auto-generated header on every per-command CLI reference page (writeSingleCommandDoc) and the docs/CLI_REFERENCE.md preamble (writeAllHelp). The version label now lives only on the index page emitted by scripts/generate-cli-docs.sh: - Dev tree (website/docs/cli-reference/index.md, docs/CLI_REFERENCE.md): labelled "Latest" - Versioned snapshots (website/versioned_docs/version-X.Y.Z/...): labelled with the explicit semver tag parsed from the directory name This eliminates the 100+-file no-signal diff a release version bump otherwise produces, restoring the "regen as a separate small commit" workflow PR #3704 enables. After this change a version bump alone yields zero diff on the dev tree; only the new versioned snapshot created at release-cut time carries the new tag. No datestamps are introduced anywhere — scripts/generate-cli-docs.sh --check remains deterministic across CI runs. Refs: mybd-afb, PR #3704 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: CI Bot <ci@beads.test> Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
165 lines
4.4 KiB
Go
165 lines
4.4 KiB
Go
package main
|
|
|
|
import (
|
|
"bytes"
|
|
"strings"
|
|
"testing"
|
|
|
|
"github.com/spf13/cobra"
|
|
)
|
|
|
|
func TestHelpListOutputsSortedTopLevelCommands(t *testing.T) {
|
|
root := &cobra.Command{Use: "bd"}
|
|
root.AddCommand(
|
|
testHelpCmd("show", "Show an issue"),
|
|
testHelpCmd("create", "Create an issue"),
|
|
testHelpCmd("mol", "Molecule commands"),
|
|
)
|
|
|
|
var out bytes.Buffer
|
|
listAllCommands(&out, root)
|
|
|
|
got := strings.TrimSpace(out.String())
|
|
want := "create\nmol\nshow"
|
|
if got != want {
|
|
t.Fatalf("listAllCommands() = %q, want %q", got, want)
|
|
}
|
|
}
|
|
|
|
func TestHelpAllIncludesTopLevelAndNestedCommands(t *testing.T) {
|
|
root := &cobra.Command{Use: "bd"}
|
|
mol := testHelpCmd("mol", "Molecule commands")
|
|
mol.AddCommand(testHelpCmd("pour", "Start a workflow"))
|
|
root.AddCommand(mol)
|
|
|
|
var out bytes.Buffer
|
|
writeAllHelp(&out, root)
|
|
got := out.String()
|
|
|
|
for _, want := range []string{
|
|
"# bd — Complete Command Reference",
|
|
"[bd mol](#bd-mol)",
|
|
"[bd mol pour](#bd-mol-pour)",
|
|
"### bd mol",
|
|
"#### bd mol pour",
|
|
} {
|
|
if !strings.Contains(got, want) {
|
|
t.Fatalf("writeAllHelp() missing %q in:\n%s", want, got)
|
|
}
|
|
}
|
|
}
|
|
|
|
func TestHelpDocWritesSingleCommandMarkdownToProvidedWriter(t *testing.T) {
|
|
root := &cobra.Command{Use: "bd"}
|
|
show := testHelpCmd("show <id>", "Show an issue")
|
|
root.AddCommand(show)
|
|
|
|
var out bytes.Buffer
|
|
if err := writeSingleCommandDoc(&out, root, "show"); err != nil {
|
|
t.Fatalf("writeSingleCommandDoc() error = %v", err)
|
|
}
|
|
got := out.String()
|
|
|
|
for _, want := range []string{
|
|
"id: show",
|
|
"title: bd show",
|
|
"slug: /cli-reference/show",
|
|
"Generated from `bd help --doc show`",
|
|
"## bd show",
|
|
"bd show <id>",
|
|
} {
|
|
if !strings.Contains(got, want) {
|
|
t.Fatalf("writeSingleCommandDoc() missing %q in:\n%s", want, got)
|
|
}
|
|
}
|
|
}
|
|
|
|
func TestHelpDocNestedCommandUsesSafeIDAndFullCommandPath(t *testing.T) {
|
|
root := &cobra.Command{Use: "bd"}
|
|
mol := testHelpCmd("mol", "Molecule commands")
|
|
pour := testHelpCmd("pour <formula>", "Start a workflow")
|
|
mol.AddCommand(pour)
|
|
root.AddCommand(mol)
|
|
|
|
var out bytes.Buffer
|
|
if err := writeSingleCommandDoc(&out, root, "mol pour"); err != nil {
|
|
t.Fatalf("writeSingleCommandDoc() error = %v", err)
|
|
}
|
|
got := out.String()
|
|
|
|
for _, want := range []string{
|
|
"id: mol-pour",
|
|
"title: bd mol pour",
|
|
"slug: /cli-reference/mol-pour",
|
|
"Generated from `bd help --doc mol pour`",
|
|
"## bd mol pour",
|
|
"bd mol pour <formula>",
|
|
} {
|
|
if !strings.Contains(got, want) {
|
|
t.Fatalf("writeSingleCommandDoc() missing %q in:\n%s", want, got)
|
|
}
|
|
}
|
|
if strings.Contains(got, "## bd pour") {
|
|
t.Fatalf("nested doc collapsed command path:\n%s", got)
|
|
}
|
|
}
|
|
|
|
func TestHelpDocInvalidCommandReturnsError(t *testing.T) {
|
|
root := &cobra.Command{Use: "bd"}
|
|
root.AddCommand(testHelpCmd("show", "Show an issue"))
|
|
|
|
var out bytes.Buffer
|
|
err := writeSingleCommandDoc(&out, root, "missing")
|
|
if err == nil {
|
|
t.Fatal("writeSingleCommandDoc() error = nil, want command-not-found error")
|
|
}
|
|
if !strings.Contains(err.Error(), "command not found: missing") {
|
|
t.Fatalf("writeSingleCommandDoc() error = %q", err)
|
|
}
|
|
if out.Len() != 0 {
|
|
t.Fatalf("writeSingleCommandDoc() wrote output for invalid command:\n%s", out.String())
|
|
}
|
|
}
|
|
|
|
func testHelpCmd(use, short string) *cobra.Command {
|
|
return &cobra.Command{
|
|
Use: use,
|
|
Short: short,
|
|
Run: func(cmd *cobra.Command, args []string) {},
|
|
}
|
|
}
|
|
|
|
func TestHelpDocEscapesMDXProse(t *testing.T) {
|
|
root := &cobra.Command{Use: "bd"}
|
|
root.AddCommand(testHelpCmd("assign <id> <name>", "Assign <id> to {name}"))
|
|
|
|
var out bytes.Buffer
|
|
if err := writeSingleCommandDoc(&out, root, "assign"); err != nil {
|
|
t.Fatalf("writeSingleCommandDoc() error = %v", err)
|
|
}
|
|
got := out.String()
|
|
|
|
if !strings.Contains(got, "Assign <id> to {name}") {
|
|
t.Fatalf("writeSingleCommandDoc() did not escape MDX prose:\n%s", got)
|
|
}
|
|
if !strings.Contains(got, "bd assign <id> <name>") {
|
|
t.Fatalf("writeSingleCommandDoc() should keep usage code fences unescaped:\n%s", got)
|
|
}
|
|
}
|
|
|
|
func TestHelpDocFlagTextDoesNotClaimDashMeansStdout(t *testing.T) {
|
|
rootCmd.InitDefaultHelpCmd()
|
|
registerHelpAllFlag()
|
|
|
|
helpCmd, _, err := rootCmd.Find([]string{"help"})
|
|
if err != nil {
|
|
t.Fatalf("find help command: %v", err)
|
|
}
|
|
flag := helpCmd.Flags().Lookup("doc")
|
|
if flag == nil {
|
|
t.Fatal("help --doc flag is not registered")
|
|
}
|
|
if strings.Contains(flag.Usage, "use - for stdout") {
|
|
t.Fatalf("help --doc flag still documents unsupported '-' stdout sentinel: %q", flag.Usage)
|
|
}
|
|
}
|