chore: add pre-commit prettier check This ensures that our markdown is wrapped to 80cols, so that when help topics are presented by the CLI we don't have to do anything special to wrap them to fit
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index bc5ac02..3e15b9e 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml
@@ -1,12 +1,12 @@ name: CI -# Controls when the action will run. +# Controls when the action will run. on: # Triggers the workflow on push or pull request events but only for the main branch push: - branches: [ main ] + branches: [main] pull_request: - branches: [ main ] + branches: [main] # Allows you to run this workflow manually from the Actions tab workflow_dispatch: @@ -35,4 +35,6 @@ env: # Bazelisk will download bazel to here XDG_CACHE_HOME: ~/.cache/bazel-repo - run: bazel --bazelrc=.github/workflows/ci.bazelrc --bazelrc=.bazelrc test //... + run: + bazel --bazelrc=.github/workflows/ci.bazelrc --bazelrc=.bazelrc test + //...
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index d65b045..1d0c22a 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml
@@ -18,7 +18,9 @@ env: # Bazelisk will download bazel to here XDG_CACHE_HOME: ~/.cache/bazel-repo - run: bazel --bazelrc=.github/workflows/ci.bazelrc --bazelrc=.bazelrc test --config=release //... + run: + bazel --bazelrc=.github/workflows/ci.bazelrc --bazelrc=.bazelrc test + --config=release //... - name: Release uses: softprops/action-gh-release@v1 with: @@ -28,4 +30,4 @@ bazel-out/*-opt-*/bin/cmd/aspect/aspect-linux_arm64 bazel-out/*-opt-*/bin/cmd/aspect/aspect-darwin_amd64 bazel-out/*-opt-*/bin/cmd/aspect/aspect-darwin_arm64 - bazel-out/*-opt-*/bin/cmd/aspect/aspect-windows_amd64.exe \ No newline at end of file + bazel-out/*-opt-*/bin/cmd/aspect/aspect-windows_amd64.exe
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 7660034..0215438 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml
@@ -3,19 +3,19 @@ # See https://pre-commit.com/hooks.html for more hooks repos: # Locally-authored hooks for better hermeticity - - repo: local + - repo: local hooks: - - id: go-fmt - name: go fmt - description: Runs `go fmt` and asserts no changes are needed. - entry: ./hooks/go-fmt.sh - language: script - files: \.go$ + - id: go-fmt + name: go fmt + description: Runs `go fmt` and asserts no changes are needed. + entry: ./hooks/go-fmt.sh + language: script + files: \.go$ - repo: https://github.com/syntaqx/git-hooks rev: v0.0.17 hooks: - # Requires that shellcheck is already installed - - id: shellcheck + # Requires that shellcheck is already installed + - id: shellcheck - repo: https://github.com/commitizen-tools/commitizen rev: v2.18.0 hooks: @@ -30,4 +30,8 @@ args: &args - --warnings=all - id: buildifier-lint - args: *args \ No newline at end of file + args: *args + - repo: https://github.com/pre-commit/mirrors-prettier + rev: "v2.4.0" + hooks: + - id: prettier
diff --git a/.prettierignore b/.prettierignore new file mode 100644 index 0000000..db63a81 --- /dev/null +++ b/.prettierignore
@@ -0,0 +1,2 @@ +# These are generated by cobra +docs/*.md
diff --git a/.prettierrc b/.prettierrc new file mode 100644 index 0000000..1deb191 --- /dev/null +++ b/.prettierrc
@@ -0,0 +1 @@ +proseWrap: always
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 597ead9..e2fa7b8 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md
@@ -2,9 +2,8 @@ ## Formatting/linting -We suggest using a pre-commit hook to automate this. -First [install pre-commit](https://pre-commit.com/#installation), -then run +We suggest using a pre-commit hook to automate this. First +[install pre-commit](https://pre-commit.com/#installation), then run ```shell pre-commit install
diff --git a/README.md b/README.md index 4a719f4..d885460 100644 --- a/README.md +++ b/README.md
@@ -1,29 +1,35 @@ # aspect-cli -This is the frontend for the Aspect build tool. -It is currently just a wrapper around bazelisk or bazel, meant to install in tools/bazel. +This is the frontend for the Aspect build tool. It is currently just a wrapper +around bazelisk or bazel, meant to install in tools/bazel. -In the future, we might totally replace the bazel C++ client, and this tool would be a gRPC client of the bazel server. +In the future, we might totally replace the bazel C++ client, and this tool +would be a gRPC client of the bazel server. ## TODOs -- [ ] figure out how to cut and host a release - GH Action to cut/publish release whenever a tag is pushed upstream +- [ ] figure out how to cut and host a release GH Action to cut/publish release + whenever a tag is pushed upstream - [ ] document lots of ways to install, including a bash one-liner - [ ] help user ensure bash/zsh completion working -- [ ] warn user if Bazel version is floating - (no bazelisk, or using latest in .bazelversion, or no .bazelversion) +- [ ] warn user if Bazel version is floating (no bazelisk, or using latest in + .bazelversion, or no .bazelversion) # Use Cases ## When I am confused by bazel -I can find that Aspect is an easier-to-use wrapper and feel motivated and comfortable to try it immediately. +I can find that Aspect is an easier-to-use wrapper and feel motivated and +comfortable to try it immediately. -From aspect.build/install I quickly pick an Installation option, and am guided through to successful install. +From aspect.build/install I quickly pick an Installation option, and am guided +through to successful install. The first time I run `aspect` in interactive mode, -- I choose whether I want to install for all users of my workspace, in which case a bootstrap bit is added to tools/bazel ensuring that the tool is downloaded and spawned for anyone cloning my repo. + +- I choose whether I want to install for all users of my workspace, in which + case a bootstrap bit is added to tools/bazel ensuring that the tool is + downloaded and spawned for anyone cloning my repo. ## When I run bare `bazel`
diff --git a/cmd/aspect/root/root.go b/cmd/aspect/root/root.go index c621794..6f28856 100644 --- a/cmd/aspect/root/root.go +++ b/cmd/aspect/root/root.go
@@ -72,7 +72,7 @@ cmd.AddCommand(&cobra.Command{ Use: "target-syntax", Short: "Documentation on Bazel's syntax for targets", - Long: topics.Read("target-syntax"), + Long: topics.Read("target-syntax.md"), }) return cmd
diff --git a/cmd/docgen/README.md b/cmd/docgen/README.md index 1951d50..0b3a620 100644 --- a/cmd/docgen/README.md +++ b/cmd/docgen/README.md
@@ -5,4 +5,5 @@ Note that piping the command to less is required, so that it's not interactive. Otherwise we'll turn on coloring and put ANSI escape codes in our markdown. -The github.com/aspect-dev/docs repo will do the work of publishing the outputs of this docgen step. +The github.com/aspect-dev/docs repo will do the work of publishing the outputs +of this docgen step.
diff --git a/docs/help/topics/BUILD.bazel b/docs/help/topics/BUILD.bazel index 51797f1..ac71a13 100644 --- a/docs/help/topics/BUILD.bazel +++ b/docs/help/topics/BUILD.bazel
@@ -3,7 +3,7 @@ go_library( name = "topics", srcs = ["main.go"], - data = ["target-syntax"], + data = ["target-syntax.md"], importpath = "aspect.build/cli/docs/help/topics", visibility = ["//visibility:public"], deps = ["@io_bazel_rules_go//go/tools/bazel:go_default_library"],
diff --git a/docs/help/topics/target-syntax b/docs/help/topics/target-syntax deleted file mode 100644 index bc69f6f..0000000 --- a/docs/help/topics/target-syntax +++ /dev/null
@@ -1,83 +0,0 @@ -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.) - \ No newline at end of file
diff --git a/docs/help/topics/target-syntax.md b/docs/help/topics/target-syntax.md new file mode 100644 index 0000000..7806d11 --- /dev/null +++ b/docs/help/topics/target-syntax.md
@@ -0,0 +1,73 @@ +# 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.)