feat(help): Add target-syntax help topic

cmd/aspect/BUILD.bazel

@@ -10,6 +10,7 @@ go_library(
     visibility = ["//visibility:private"],
     deps = [
         "//cmd/aspect/version",
+        "//docs/help/topics",
         "//pkg/ioutils",
         "@com_github_fatih_color//:color",
         "@com_github_mattn_go_isatty//:go-isatty",

cmd/aspect/root.go

@@ -17,6 +17,7 @@ import (
 	"github.com/spf13/viper"
 
 	"aspect.build/cli/cmd/aspect/version"
+	"aspect.build/cli/docs/help/topics"
 	"aspect.build/cli/pkg/ioutils"
 )
 
@@ -37,7 +38,7 @@ func NewRootCmd(streams ioutils.Streams, defaultInteractive bool) *cobra.Command
 	var interactive bool
 	cmd.PersistentFlags().StringVar(&cfgFile, "config", "", "config file (default is $HOME/.aspect.yaml)")
 	cmd.PersistentFlags().BoolVar(&interactive, "interactive", defaultInteractive, "Interactive mode (e.g. prompts for user input)")
-
+	
 	// ### Viper
 	if cfgFile != "" {
 		// Use config file from the flag.
@@ -58,6 +59,14 @@ func NewRootCmd(streams ioutils.Streams, defaultInteractive bool) *cobra.Command
 
 	// ### Child commands
 	cmd.AddCommand(version.NewDefaultVersionCmd())
+
+	// ### "Additional help topic commands" which are not runnable
+	// https://pkg.go.dev/github.com/spf13/cobra#Command.IsAdditionalHelpTopicCommand
+	cmd.AddCommand(&cobra.Command{
+		Use: "target-syntax",
+		Short: "Documentation on Bazel's syntax for targets",
+		Long: topics.Read("target-syntax"),
+	})
 
 	return cmd
 }

docs/help/topics/BUILD.bazel

@@ -0,0 +1,10 @@
+load("@io_bazel_rules_go//go:def.bzl", "go_library")
+
+go_library(
+    name = "topics",
+    srcs = ["main.go"],
+    data = ["target-syntax"],
+    importpath = "aspect.build/cli/docs/help/topics",
+    visibility = ["//visibility:public"],
+    deps = ["@io_bazel_rules_go//go/tools/bazel:go_default_library"],
+)

docs/help/topics/main.go

@@ -0,0 +1,20 @@
+package topics
+
+import (
+	"github.com/bazelbuild/rules_go/go/tools/bazel"
+	"fmt"
+	"os"
+)
+
+func Read(topic string) string {
+	rpath := "docs/help/topics/" + topic
+	r, err := bazel.Runfile(rpath)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Unable to locate %s in runfiles: %v\n", rpath, err)
+	}
+	c, err := os.ReadFile(r)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Failed to read %s: %v\n", r, err)
+	}
+	return string(c)
+}

docs/help/topics/target-syntax

@@ -0,0 +1,83 @@
+Target pattern syntax
+=====================
+
+The BUILD file label syntax is used to specify a single target. Target
+patterns generalize this syntax to sets of targets, and also support
+working-directory-relative forms, recursion, subtraction and filtering.
+Examples:
+
+Specifying a single target:
+
+  //foo/bar:wiz     The single target '//foo/bar:wiz'.
+  foo/bar/wiz       Equivalent to:
+                      '//foo/bar/wiz:wiz' if foo/bar/wiz is a package,
+                      '//foo/bar:wiz' if foo/bar is a package,
+                      '//foo:bar/wiz' otherwise.
+  //foo/bar         Equivalent to '//foo/bar:bar'.
+
+Specifying all rules in a package:
+
+  //foo/bar:all       Matches all rules in package 'foo/bar'.
+
+Specifying all rules recursively beneath a package:
+
+  //foo/...:all     Matches all rules in all packages beneath directory 'foo'.
+  //foo/...           (ditto)
+
+  By default, directory symlinks are followed when performing this recursive traversal, except
+  those that point to under the output base (for example, the convenience symlinks that are created
+  in the root directory of the workspace) But we understand that your workspace may intentionally
+  contain directories with weird symlink structures that you don't want consumed. As such, if a
+  directory has a file named
+  'DONT_FOLLOW_SYMLINKS_WHEN_TRAVERSING_THIS_DIRECTORY_VIA_A_RECURSIVE_TARGET_PATTERN'
+  then symlinks in that directory won't be followed when evaluating recursive
+  target patterns.
+
+Working-directory relative forms:  (assume cwd = 'workspace/foo')
+
+  Target patterns which do not begin with '//' are taken relative to
+  the working directory.  Patterns which begin with '//' are always
+  absolute.
+
+  ...:all           Equivalent to  '//foo/...:all'.
+  ...                 (ditto)
+
+  bar/...:all       Equivalent to  '//foo/bar/...:all'.
+  bar/...             (ditto)
+
+  bar:wiz           Equivalent to '//foo/bar:wiz'.
+  :foo              Equivalent to '//foo:foo'.
+
+  bar               Equivalent to '//foo/bar:bar'.
+  foo/bar           Equivalent to '//foo/foo/bar:bar'.
+
+  bar:all           Equivalent to '//foo/bar:all'.
+  :all              Equivalent to '//foo:all'.
+
+Summary of target wildcards:
+
+  :all,             Match all rules in the specified packages.
+  :*, :all-targets  Match all targets (rules and files) in the specified
+                      packages, including .par and _deploy.jar files.
+
+Subtractive patterns:
+
+  Target patterns may be preceded by '-', meaning they should be
+  subtracted from the set of targets accumulated by preceding
+  patterns. (Note that this means order matters.) For example:
+
+    % bazel build -- foo/... -foo/contrib/...
+
+  builds everything in 'foo', except 'contrib'.  In case a target not
+  under 'contrib' depends on something under 'contrib' though, in order to
+  build the former bazel has to build the latter too. As usual, the '--' is
+  required to prevent '-f' from being interpreted as an option.
+
+  When running the test command, test suite expansion is applied to each target
+  pattern in sequence as the set of targets is evaluated. This means that
+  individual tests from a test suite can be excluded by a later target pattern.
+  It also means that an exclusion target pattern which matches a test suite will
+  exclude all tests which that test suite references. (Targets that would be
+  matched by the list of target patterns without any test suite expansion are
+  also built unless --build_tests_only is set.)
+