Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
214 changes: 174 additions & 40 deletions cmd/src/doc.go
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -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)
}
Expand All @@ -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 {
Expand Down Expand Up @@ -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
Expand All @@ -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
Expand All @@ -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)
Expand All @@ -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
Expand Down Expand Up @@ -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) {
Expand Down
46 changes: 46 additions & 0 deletions cmd/src/doc_test.go
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package main

import (
"encoding/json"
"io/fs"
"os"
"path/filepath"
Expand Down Expand Up @@ -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)
}
}
Loading