Allow printing SCIP index as JSON (#147)

- Add `--json` flag to `scip print` command to output as JSON
- Manually update docs about CLI subcommands

Author: keynmol

cmd/convert.go

@@ -29,7 +29,7 @@ func convertCommand() cli.Command {
 				Name:        "to",
 				Usage:       "Output path for LSIF index",
 				Destination: &convertFlags.to,
-				Value: "dump.lsif",
+				Value:       "dump.lsif",
 			},
 		},
 		Action: func(c *cli.Context) error {

cmd/print.go

@@ -1,38 +1,59 @@
 package main
 
 import (
+	"io"
+	"math"
+
 	"github.com/k0kubun/pp/v3"
 	"github.com/urfave/cli/v2"
-	"math"
+	"google.golang.org/protobuf/encoding/protojson"
 
 	"github.com/sourcegraph/sourcegraph/lib/errors"
 )
 
 func printCommand() cli.Command {
+	var json bool
 	snapshot := cli.Command{
 		Name:  "print",
 		Usage: "Print a SCIP index in a human-readable format for debugging",
 		Description: `WARNING: The output may change over time.
 Do not rely on the output of this command in scripts`,
+		Flags: []cli.Flag{
+			&cli.BoolFlag{
+				Name:        "json",
+				Usage:       "Output in JSON format",
+				Destination: &json,
+			},
+		},
 		Action: func(c *cli.Context) error {
 			indexPath := c.Args().Get(0)
 			if indexPath == "" {
 				return errors.New("missing argument for path to SCIP index")
 			}
-			return printMain(indexPath)
+			return printMain(indexPath, json, c.App.Writer)
 		},
 	}
 	return snapshot
 }
 
-func printMain(indexPath string) error {
+func printMain(indexPath string, json bool, out io.Writer) error {
 	index, err := readFromOption(indexPath)
 	if err != nil {
 		return err
 	}
-	pp.BufferFoldThreshold = math.MaxInt
-	prettyPrinter := pp.New()
-	prettyPrinter.SetExportedOnly(true)
-	_, err = prettyPrinter.Print(index)
-	return err
+	if json {
+		pp.BufferFoldThreshold = math.MaxInt
+
+		options := protojson.MarshalOptions{}
+
+		jsonBytes, err := options.Marshal(index)
+		out.Write(jsonBytes)
+		return err
+	} else {
+		prettyPrinter := pp.New()
+		prettyPrinter.SetExportedOnly(true)
+		prettyPrinter.SetOutput(out)
+		_, err = prettyPrinter.Print(index)
+		return err
+	}
 }

cmd/print_test.go

@@ -0,0 +1,69 @@
+package main
+
+import (
+	"bytes"
+	"encoding/json"
+	"io"
+	"io/ioutil"
+	"log"
+	"os"
+	"testing"
+
+	"github.com/sourcegraph/scip/bindings/go/scip"
+	"github.com/stretchr/testify/require"
+	"google.golang.org/protobuf/proto"
+)
+
+func TestJSONPrinting(t *testing.T) {
+	app := scipApp()
+	// Redirect CLI writer to a buffer
+	var buff bytes.Buffer
+	app.Writer = io.Writer(&buff)
+	idx := makeIndex([]string{"a"}, stringMap{"f": {"b"}}, stringMap{"f": {"a", "b"}})
+
+	idx.Metadata = &scip.Metadata{ProjectRoot: "howdy"}
+
+	// Serialise SCIP index
+	indexBytes, err := proto.Marshal(idx)
+
+	// Write SCIP index to a temp file
+	dir := os.TempDir()
+	file, err := ioutil.TempFile(dir, "scip-cli-json-test*.scip")
+	if err != nil {
+		log.Fatal(err)
+	}
+	defer os.Remove(file.Name())
+
+	_, fErr := file.Write(indexBytes)
+	if fErr != nil {
+		log.Fatal(fErr)
+	}
+
+	// Run the JSON command with the temporary file
+	runErr := app.Run([]string{"scip", "print", "--json", file.Name()})
+	if runErr != nil {
+		log.Fatal(runErr)
+	}
+
+	type JsonIndex struct {
+		Metadata struct {
+			ProjectRoot string `json:"projectRoot"`
+		}
+		Documents []struct {
+			RelativePath string `json:"relativePath"`
+		} `json:"documents"`
+	}
+
+	var roundtripResult JsonIndex
+
+	bytes := buff.Bytes()
+
+	jsonErr := json.Unmarshal(bytes, &roundtripResult)
+	if jsonErr != nil {
+		log.Fatal(jsonErr)
+	}
+
+	require.Equal(t, roundtripResult.Metadata.ProjectRoot, "howdy")
+	require.Equal(t, len(roundtripResult.Documents), 1)
+	require.Equal(t, roundtripResult.Documents[0].RelativePath, "f")
+}

docs/CLI.md

@@ -1,5 +1,15 @@
 # SCIP CLI Reference
 
+<!--toc:start-->
+
+- [SCIP CLI Reference](#scip-cli-reference)
+  - [`scip convert`](#scip-convert)
+  - [`scip lint`](#scip-lint)
+  - [`scip print`](#scip-print)
+  - [`scip snapshot`](#scip-snapshot)
+  - [`scip stats`](#scip-stats)
+  <!--toc:end-->
+
 ```
 NAME:
    scip - SCIP Code Intelligence Protocol CLI
@@ -26,6 +36,7 @@ COMMANDS:
 GLOBAL OPTIONS:
    --help, -h     show help (default: false)
    --version, -v  print the version (default: false)
+
 ```
 
 ## `scip convert`
@@ -78,6 +89,7 @@ DESCRIPTION:
 
 OPTIONS:
    --help, -h  show help (default: false)
+   --json      Output in JSON format (default: false)
 ```
 
 ## `scip snapshot`
@@ -96,8 +108,12 @@ DESCRIPTION:
    and symbol information.
 
 OPTIONS:
-   --from value  Path to SCIP index file (default: index.scip)
-   --to value    Path to output directory for snapshot files (default: scip-snapshot)
+   --comment-syntax value  Comment syntax to use for snapshot files (default: "//")
+   --from value            Path to SCIP index file (default: "index.scip")
+   --help, -h              show help (default: false)
+   --project-root value    Override project root in the SCIP file. For example, this can be helpful when the SCIP index was created inside a Docker image or created on another computer
+   --strict                If true, fail fast on errors (default: true)
+   --to value              Path to output directory for snapshot files (default: "scip-snapshot")
 ```
 
 ## `scip stats`