Repository: uber/prototool
Pull request #369 (2019-03-06 01:33:48)

Add x top-level command and move prototool inspect to prototool x inspect
This adds `prototool x` for experimental commands. This gives us some flexibility for commands that we aren't confident that we want forever, or that we are still playing with in terms of their API.

The `prototool x inspect` command falls into this category. This is useful functionality, but the API is a bit awkward right now, and we should iterate on it. However, we still want this to be available for now so we can refine it.

codecov-io: # [Codecov](https://codecov.io/gh/uber/prototool/pull/369?src=pr&el=h1) Report
> Merging [#369](https://codecov.io/gh/uber/prototool/pull/369?src=pr&el=desc) into [dev](https://codecov.io/gh/uber/prototool/commit/47f557a5717c87af87ff2b3697fda8144f917ca6?src=pr&el=desc) will **increase** coverage by `<.01%`.
> The diff coverage is `100%`.

[![Impacted file tree graph](https://codecov.io/gh/uber/prototool/pull/369/graphs/tree.svg?width=650&token=A9V0DApqZg&height=150&src=pr)](https://codecov.io/gh/uber/prototool/pull/369?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##              dev     #369      +/-   ##
==========================================
+ Coverage   73.31%   73.32%   +<.01%     
==========================================
  Files         143      143              
  Lines        6475     6477       +2     
==========================================
+ Hits         4747     4749       +2     
  Misses       1284     1284              
  Partials      444      444
```


| [Impacted Files](https://codecov.io/gh/uber/prototool/pull/369?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [internal/cmd/cmd.go](https://codecov.io/gh/uber/prototool/pull/369/diff?src=pr&el=tree#diff-aW50ZXJuYWwvY21kL2NtZC5nbw==) | `68.11% <100%> (+0.95%)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/uber/prototool/pull/369?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/uber/prototool/pull/369?src=pr&el=footer). Last update [47f557a...4f021cc](https://codecov.io/gh/uber/prototool/pull/369?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).


Patch:
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e70d25e..0db9664 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -36,8 +36,9 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Add `generate.plugins.include_imports` and
   `generate.plugins.include_source_info` to be used with the built-in
   `descriptor_set` plugin.
-- Add `inspect` top-level command with Protobuf inspection capabilities.
 - Add `cache` top-level command to allow management of the `protoc` cache.
+- Add `x` top-level command for experimental functionality.
+- Add `inspect` command under `x` with Protobuf inspection capabilities.
 - Add `--error-format` flag to allow specific error fields to be printed.
 - Add file locking around the `protoc` downloader to eliminate concurrency
   issues where multiple `prototool` invocations may be accessing the cache
diff --git a/README.md b/README.md
index 45668c5..5e1f9a4 100644
--- a/README.md
+++ b/README.md
@@ -206,6 +206,8 @@ This repository is a self-contained plugin for use with the [ALE Lint Engine](ht
 Prototool is generally available, and conforms to [SemVer](https://semver.org), so Prototool will not have any breaking changes on a given
 major version, with some exceptions:
 
+- Commands under the `x` top-level command are experimental, and may change or be deleted between minor versions of Prototool. We expect
+  such commands to be promoted to stable within a few minor releases, however development is still in-progress.
 - The output of the formatter may change between minor versions. This has not happened yet, but we may change the format in the future to
   reflect things such as max line lengths.
 - The breaking change detector's output format currently does not output filename, line, or column. This is an expected upgrade in the
diff --git a/internal/cmd/cmd.go b/internal/cmd/cmd.go
index 80b6075..a22650c 100644
--- a/internal/cmd/cmd.go
+++ b/internal/cmd/cmd.go
@@ -114,14 +114,16 @@ func getRootCommand(develMode bool, exitCodeAddr *int, args []string, stdin io.R
 	cacheCmd.AddCommand(cacheUpdateCmdTemplate.Build(develMode, exitCodeAddr, stdin, stdout, stderr, flags))
 	cacheCmd.AddCommand(cacheDeleteCmdTemplate.Build(develMode, exitCodeAddr, stdin, stdout, stderr, flags))
 	rootCmd.AddCommand(cacheCmd)
+	breakCmd := &cobra.Command{Use: "break", Short: "Top-level command for breaking change commands."}
+	breakCmd.AddCommand(breakCheckCmdTemplate.Build(develMode, exitCodeAddr, stdin, stdout, stderr, flags))
+	rootCmd.AddCommand(breakCmd)
+	experimentalCmd := &cobra.Command{Use: "x", Short: "Top-level command for experimental commands. These may change between minor versions."}
 	inspectCmd := &cobra.Command{Use: "inspect", Short: "Top-level command for inspection commands."}
 	inspectCmd.AddCommand(inspectPackagesCmdTemplate.Build(develMode, exitCodeAddr, stdin, stdout, stderr, flags))
 	inspectCmd.AddCommand(inspectPackageDepsCmdTemplate.Build(develMode, exitCodeAddr, stdin, stdout, stderr, flags))
 	inspectCmd.AddCommand(inspectPackageImportersCmdTemplate.Build(develMode, exitCodeAddr, stdin, stdout, stderr, flags))
-	rootCmd.AddCommand(inspectCmd)
-	breakCmd := &cobra.Command{Use: "break", Short: "Top-level command for breaking change commands."}
-	breakCmd.AddCommand(breakCheckCmdTemplate.Build(develMode, exitCodeAddr, stdin, stdout, stderr, flags))
-	rootCmd.AddCommand(breakCmd)
+	experimentalCmd.AddCommand(inspectCmd)
+	rootCmd.AddCommand(experimentalCmd)
 
 	// flags bound to rootCmd are global flags
 	flags.bindDebug(rootCmd.PersistentFlags())


Test patch:
diff --git a/internal/cmd/cmd_test.go b/internal/cmd/cmd_test.go
index 4033580..ac0b466 100644
--- a/internal/cmd/cmd_test.go
+++ b/internal/cmd/cmd_test.go
@@ -1196,7 +1196,7 @@ func TestInspectPackages(t *testing.T) {
 		`bar
 foo
 google.protobuf`,
-		"inspect", "packages", "testdata/foo",
+		"x", "inspect", "packages", "testdata/foo",
 	)
 }
 
@@ -1207,21 +1207,21 @@ func TestInspectPackageDeps(t *testing.T) {
 		0,
 		`bar
 google.protobuf`,
-		"inspect", "package-deps", "testdata/foo", "--name", "foo",
+		"x", "inspect", "package-deps", "testdata/foo", "--name", "foo",
 	)
 	assertExact(
 		t,
 		true,
 		0,
 		``,
-		"inspect", "package-deps", "testdata/foo", "--name", "bar",
+		"x", "inspect", "package-deps", "testdata/foo", "--name", "bar",
 	)
 	assertExact(
 		t,
 		true,
 		0,
 		``,
-		"inspect", "package-deps", "testdata/foo", "--name", "google.protobuf",
+		"x", "inspect", "package-deps", "testdata/foo", "--name", "google.protobuf",
 	)
 }
 
@@ -1231,21 +1231,21 @@ func TestInspectPackageImporters(t *testing.T) {
 		true,
 		0,
 		``,
-		"inspect", "package-importers", "testdata/foo", "--name", "foo",
+		"x", "inspect", "package-importers", "testdata/foo", "--name", "foo",
 	)
 	assertExact(
 		t,
 		true,
 		0,
 		`foo`,
-		"inspect", "package-importers", "testdata/foo", "--name", "bar",
+		"x", "inspect", "package-importers", "testdata/foo", "--name", "bar",
 	)
 	assertExact(
 		t,
 		true,
 		0,
 		`foo`,
-		"inspect", "package-importers", "testdata/foo", "--name", "google.protobuf",
+		"x", "inspect", "package-importers", "testdata/foo", "--name", "google.protobuf",
 	)
 }