diff --git a/CHANGELOG.md b/CHANGELOG.md index 4700ef0041..6f92cf03a7 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,8 @@ All notable changes to `src-cli` are documented in this file. ### Added +- `src doc -json -o FILE` writes the command reference as one JSON file: a tree of all commands with their help text and flags. + - `src` now prints a warning to stderr when it is older than the version recommended by your Sourcegraph instance. The recommended version is looked up at most once every 24 hours per instance. To disable the check, set the `SRC_SKIP_VERSION_CHECK` environment variable to any non-blank string. [#930](https://github.com/sourcegraph/src-cli/issues/930) ### Changed diff --git a/cmd/src/doc.go b/cmd/src/doc.go index d8108c4aa1..d6ea5f3d54 100644 --- a/cmd/src/doc.go +++ b/cmd/src/doc.go @@ -2,39 +2,49 @@ package main import ( "bytes" + "cmp" + "encoding/json" "flag" "fmt" "io" "maps" "os" "path" + "slices" "strings" "text/template" + "github.com/urfave/cli/v3" + "github.com/sourcegraph/sourcegraph/lib/docgen" "github.com/sourcegraph/sourcegraph/lib/errors" "github.com/sourcegraph/sourcegraph/lib/output" "github.com/sourcegraph/src-cli/internal/cmderrors" + "github.com/sourcegraph/src-cli/internal/version" ) func init() { flagSet := flag.NewFlagSet("doc", flag.ExitOnError) var ( - outputFlag = flagSet.String("o", "", "Output directory") + outputFlag = flagSet.String("o", "", "Output directory, or output file with -json") + jsonFlag = flagSet.Bool("json", false, "Write the reference as one JSON file instead of Markdown files") ) usage := ` -'src doc' is an internal command that generates the Markdown reference +'src doc' is an internal command that generates the Markdown or JSON reference documentation used within Sourcegraph. Usage: src doc -o DIR + src doc -json -o FILE Examples: $ src doc -o ~/sourcegraph/doc/integration/cli/reference + + $ src doc -json -o ~/sourcegraph/docs/cli/references.json ` handler := func(args []string) error { @@ -44,7 +54,7 @@ Examples: out := output.NewOutput(flagSet.Output(), output.OutputOpts{Verbose: *verbose}) if *outputFlag == "" { - out.WriteLine(output.Line(output.EmojiFailure, output.StyleWarning, "output directory must be set via -o")) + out.WriteLine(output.Line(output.EmojiFailure, output.StyleWarning, "output must be set via -o")) flagSet.Usage() return cmderrors.ExitCode(1, nil) } @@ -68,6 +78,34 @@ Examples: "snapshot": &snapshotCommands, } + if *jsonFlag { + // src has two kinds of commands: legacy flag.FlagSet commands, listed + // in commanders, and urfave/cli commands in migratedCommands. + root := &docCommand{Name: "src"} + if version.BuildTag != version.DefaultBuildTag { + root.Version = version.BuildTag + } + if root.Commands, err = legacyDocCommands(commanders, ""); err != nil { + return err + } + for _, cmd := range docgen.VisibleCommands(migratedRootCommand().Commands) { + root.Commands = append(root.Commands, migratedDocCommand("src "+cmd.Name, cmd)) + } + sortDocCommands(root.Commands) + var buf bytes.Buffer + enc := json.NewEncoder(&buf) + enc.SetEscapeHTML(false) + enc.SetIndent("", " ") + if err := enc.Encode(root); err != nil { + return err + } + content, err := sanitiseDocText(buf.String()) + if err != nil { + return err + } + return os.WriteFile(*outputFlag, []byte(content), 0644) + } + rootSubcommands := map[string]string{} count := 0 for groupName, cmdr := range commanders { @@ -184,6 +222,90 @@ Examples: }) } +// docCommand is one command in the reference that 'src doc -json' writes: a +// single tree of all visible commands, like gcloud's CLI tree. Only name is +// required. Only the root has a version: the src-cli release that wrote it. +// Flags are the command's own visible flags; hidden commands are skipped, and +// commands and flags are sorted by name. +type docCommand struct { + Name string `json:"name"` + Version string `json:"version,omitempty"` + Summary string `json:"summary,omitempty"` + Usage string `json:"usage,omitempty"` + Help string `json:"help,omitempty"` + Flags []docFlag `json:"flags,omitempty"` + Commands []*docCommand `json:"commands,omitempty"` +} + +type docFlag struct { + Name string `json:"name"` + Aliases []string `json:"aliases,omitempty"` + Default string `json:"default,omitempty"` + Description string `json:"description,omitempty"` +} + +func sortDocCommands(commands []*docCommand) { + slices.SortFunc(commands, func(a, b *docCommand) int { return cmp.Compare(a.Name, b.Name) }) +} + +// legacyDocCommands returns the group's visible legacy commands. Their help is +// the free text that their usage function prints. +func legacyDocCommands(commanders map[string]*commander, group string) ([]*docCommand, error) { + var commands []*docCommand + for _, cmd := range *commanders[group] { + if cmd.hidden { + continue + } + fqcn := strings.TrimSpace(group + " " + cmd.flagSet.Name()) + + // Most usage functions print "Usage of 'src ...':" and the flags + // before the help. Leave both out: the flags are listed separately. + cmd.flagSet.SetOutput(io.Discard) + usage, err := captureUsage(cmd) + cmd.flagSet.SetOutput(nil) + if err != nil { + return nil, err + } + usage = strings.TrimSpace(usage) + if first, rest, _ := strings.Cut(usage, "\n"); strings.HasPrefix(first, "Usage of ") { + usage = strings.Trim(rest, "\n") + } + + c := &docCommand{Name: "src " + fqcn, Summary: cmd.description, Help: usage} + cmd.flagSet.VisitAll(func(f *flag.Flag) { + c.Flags = append(c.Flags, docFlag{Name: f.Name, Default: f.DefValue, Description: f.Usage}) + }) + if _, ok := commanders[fqcn]; ok { + if c.Commands, err = legacyDocCommands(commanders, fqcn); err != nil { + return nil, err + } + } + commands = append(commands, c) + } + sortDocCommands(commands) + return commands, nil +} + +// migratedDocCommand returns the urfave/cli command and its visible +// subcommands. +func migratedDocCommand(name string, cmd *cli.Command) *docCommand { + c := &docCommand{ + Name: name, + Summary: cmd.Usage, + Usage: strings.TrimSpace(cmd.UsageText), + Help: strings.TrimSpace(cmd.Description), + } + for _, f := range cmd.Flags { + df := f.(cli.DocGenerationFlag) + c.Flags = append(c.Flags, docFlag{Name: f.Names()[0], Aliases: f.Names()[1:], Default: df.GetValue(), Description: df.GetUsage()}) + } + slices.SortFunc(c.Flags, func(a, b docFlag) int { return cmp.Compare(a.Name, b.Name) }) + for _, sub := range docgen.VisibleCommands(cmd.Commands) { + c.Commands = append(c.Commands, migratedDocCommand(name+" "+sub.Name, sub)) + } + return c +} + func openDocFile(base, fqcn string) (interface { io.StringWriter io.WriteCloser @@ -196,6 +318,34 @@ func openDocFile(base, fqcn string) (interface { return os.Create(cmdPath + ".md") } +// sanitiseDocText replaces the user's directories in v, such as in flag +// defaults, with generic ones. +func sanitiseDocText(v string) (string, error) { + // Just replacing the home directory will probably cover off most + // cases, but we'll do the user cache and config as well just to be + // safe. + cache, err := os.UserCacheDir() + if err != nil { + return "", errors.Wrap(err, "getting user cache dir") + } + + config, err := os.UserConfigDir() + if err != nil { + return "", errors.Wrap(err, "getting user config dir") + } + + home, err := os.UserHomeDir() + if err != nil { + return "", errors.Wrap(err, "getting home dir") + } + + v = strings.ReplaceAll(v, cache, "~/.cache") + v = strings.ReplaceAll(v, config, "~/.config") + v = strings.ReplaceAll(v, home, "~") + + return v, nil +} + type docRenderer struct { commandTemplate *template.Template groupTemplate *template.Template @@ -204,31 +354,7 @@ type docRenderer struct { func newDocRenderer() (*docRenderer, error) { ct := template.New("command") ct = ct.Funcs(template.FuncMap{ - "sanitise": func(v string) (string, error) { - // Just replacing the home directory will probably cover off most - // cases, but we'll do the user cache and config as well just to be - // safe. - cache, err := os.UserCacheDir() - if err != nil { - return "", errors.Wrap(err, "getting user cache dir") - } - - config, err := os.UserConfigDir() - if err != nil { - return "", errors.Wrap(err, "getting user config dir") - } - - home, err := os.UserHomeDir() - if err != nil { - return "", errors.Wrap(err, "getting home dir") - } - - v = strings.ReplaceAll(v, cache, "~/.cache") - v = strings.ReplaceAll(v, config, "~/.config") - v = strings.ReplaceAll(v, home, "~") - - return v, nil - }, + "sanitise": sanitiseDocText, }) ct, err := ct.Parse(docCommandTemplate) @@ -253,6 +379,25 @@ func (dr *docRenderer) RenderCommand(fqcn string, cmd *command) (string, error) flags = append(flags, f) }) + usage, err := captureUsage(cmd) + if err != nil { + return "", err + } + + buf := &bytes.Buffer{} + if err := dr.commandTemplate.Execute(buf, &docCommandContext{ + FQCN: fqcn, + Usage: usage, + Flags: flags, + }); err != nil { + return "", err + } + + return buf.String(), nil +} + +// captureUsage returns the output of the command's usage function. +func captureUsage(cmd *command) (string, error) { // The usage functions are, unfortunately, a bit of a mess right now. Some // output to flag.CommandLine.Output(), some to os.Stderr, some to // os.Stdout. So let's replace the stdout and stderr variables temporarily @@ -284,18 +429,7 @@ func (dr *docRenderer) RenderCommand(fqcn string, cmd *command) (string, error) cmd.flagSet.Usage() } w.Close() - usage := <-out - - buf := &bytes.Buffer{} - if err := dr.commandTemplate.Execute(buf, &docCommandContext{ - FQCN: fqcn, - Usage: usage, - Flags: flags, - }); err != nil { - return "", err - } - - return buf.String(), nil + return <-out, nil } func (dr *docRenderer) RenderGroup(fqcn string, commands map[string]string) (string, error) { diff --git a/cmd/src/doc_test.go b/cmd/src/doc_test.go index 75747ba874..0755b4dfa1 100644 --- a/cmd/src/doc_test.go +++ b/cmd/src/doc_test.go @@ -1,6 +1,7 @@ package main import ( + "encoding/json" "io/fs" "os" "path/filepath" @@ -217,3 +218,48 @@ func TestDocRootIndexMatchesHelp(t *testing.T) { t.Errorf("'src doc' root index does not match 'src help' (-help +index):\n%s", diff) } } + +// 'src doc -json' must write exactly the commands that have Markdown pages. +func TestDocJSONMatchesMarkdown(t *testing.T) { + var want []string + for _, rel := range expectedDocFiles { + name := strings.TrimSuffix(strings.TrimSuffix(rel, ".md"), "index") + want = append(want, strings.TrimSpace("src "+strings.ReplaceAll(name, "/", " "))) + } + sort.Strings(want) + setBuildTag(t, "6.4.1") + + file := filepath.Join(t.TempDir(), "reference.json") + for _, cmd := range commands { + if cmd.flagSet.Name() == "doc" { + if err := cmd.handler([]string{"-json", "-o", file}); err != nil { + t.Fatalf("src doc -json: %v", err) + } + } + } + data, err := os.ReadFile(file) + if err != nil { + t.Fatal(err) + } + var root docCommand + if err := json.Unmarshal(data, &root); err != nil { + t.Fatal(err) + } + if root.Version != "6.4.1" { + t.Errorf("'src doc -json' version is %q, want %q", root.Version, "6.4.1") + } + var got []string + var walk func(*docCommand) + walk = func(c *docCommand) { + got = append(got, c.Name) + for _, sub := range c.Commands { + walk(sub) + } + } + walk(&root) + sort.Strings(got) + + if diff := cmp.Diff(want, got); diff != "" { + t.Errorf("'src doc -json' commands do not match the Markdown pages (-markdown +json):\n%s", diff) + } +}