Starpls

starpls is a language server for Starlark, the configuration language used by Bazel and Buck2.

Installation

VSCode

Make sure you have at least the 0.10.0 version of the vscode-bazel extension installed, as it adds support for launching a language server.

If you're on a Mac with Apple Silicon, then you can install starpls with Homebrew and skip ahead to the section about configuring VSCode:

brew install withered-magic/brew/starpls

Otherwise, you can grab a release from the releases page. Make sure to download the appropriate version for your OS and architecture! After downloading the binary, make sure to adjust its permissions to make it executable, e.g.

chmod +x starpls-darwin-arm64

Additionally, on Mac OS, you may see an error similar to

“starpls-darwin-arm64” can’t be opened because Apple cannot check it for malicious software.

To fix this, click Show in Finder, then right-click on the starpls-darwin-arm64 executable, click Open, and select Open in the warning that comes up. This will cause the com.apple.quarantine xattr to be removed from the executable and will stop the warning from appearing further.

Either way, at this point you can put the executable somewhere on your $PATH.

Once done, add the following to your VSCode configuration and reload VSCode for it to take effect:

{
  "bazel.lsp.command": "starpls"
}

Experimental features are enabled through flags on the starpls server subcommand. For example:

{
    "bazel.lsp.command": "starpls",
    // Note the first argument is "server", which is required because the flags exist only
    // on the "starpls server" subcommand (and not the top-level "starpls" command).
    "bazel.lsp.args": ["server", "--experimental_infer_ctx_attributes"]
}

Note: If you don't put starpls directly on the $PATH, then for bazel.lsp.command you'll have to specify the absolute path to the starpls executable instead. Additionally, if your VSCode setup also has any tasks that run Bazel commands on open, those might temporarily block the server from starting up because of the Bazel lock; the server will still spin up once it is able to acquire the lock.

Alternatively, you can build starpls with Bazel:

bazel run -c opt //editors/code:copy_starpls

This builds the executable and copies it to <repository_root>/editors/code/bin/starpls. From there, you can add it to the $PATH or copy it to a different directory, remembering to update the extension settings as detailed above.

Zed

Install the zed-starlark extension.

Neovim via nvim-lspconfig

Make sure you've installed and configured nvim-lspconfig in a way that works for you.

Install using homebrew as described above, then do the following in your init.lua:

require("lspconfig").starpls.setup { }

You can see the config info here.

Tips and Tricks

Make sure to use PEP 484 type comments to document your function signatures. This helps a ton with autocomplete for situations like rule implementation functions. For example, if you add a type comment as in the following...

def _impl(ctx):
    # type: (ctx) -> Unknown
    ctx.
    #  ^ and this period was just typed...

then you'll get autocomplete suggestions for the attributes on ctx, like ctx.actions, ctx.attr, and so on!

Experimental features

Starpls has a number of experimental features that can be enabled via command-line arguments:

--experimental_infer_ctx_attributes

Infer attributes on a rule implementation function's ctx parameter.

def _foo_impl(ctx):
    ctx.attr.bar # type: int

foo = rule(
    implementation = _foo_impl,
    attrs = {
        "bar": attr.int(),
    },
)

--experimental_use_code_flow_analysis

Use code flow analysis to determine additional information about types.

if cond:
    x = 1
else:
    x = "abc"

x # type: int | string

--experimental_enable_label_completions

Enables completions for labels within Bazel files. For example, given the following BUILD.bazel file at the repository root:

my_rule(
    name = "foo"
)

my_rule(
    name = "bar",
    srcs = ["//:"],
              # ^ ... If the cursor is here, "foo" will be suggested.
)

Roadmap

• Parsing
  • Error resilient Starlark parser
  • Syntax error reporting
• Semantic highlighting
  • Unbound variables
  • Type mismatches
  • Function call argument validation
• Auto-completion
  • Variables/function parameters
  • Builtin type fields
  • Rule attributes
  • Custom provider fields
  • Custom struct fields
• Hover
  • Variable types
  • Function signatures
  • Function/method docs
• Go to definition
  • Variables (including loaded symbols)
  • Function definitions
  • Struct fields
  • Provider fields
  • Labels and targets
  • Rule attributes
• Document symbols
  • Variables, functions
  • Bazel targets
• Type inference
  • Basic type inference
  • Dataflow analysis
  • PEP-484 type comments
    • Variables
    • Parameters (only basic types currently supported)
    • Other constructs where type comments are supported
• Third-party integrations
  • Bazel builtins (partial, Bazel builtins are supported but still need to handle a number of edge cases)
  • Special handling for various Bazel constructs
    • structs (autocomplete fields)
    • providers (autocomplete and validate fields)
    • rules defined with rule and repository_rule (autocomplete and validate attributes)
• Projects
  • Type inference across multiple files
  • load support
    • Relative paths
    • Bazel workspace
  • Bazel external repositories
  • Nested local repositories

Development

starpls currently requires a nightly build of Rust, due to usage of trait_upcasting as specified by RFC3324.

Prerequisites

• pnpm, for managing Node dependencies
• protoc, for compiling builtin.proto

Steps to get up and running:

1. Run pnpm install in editors/code.
2. Open VSCode, Run and Debug > Run Extension (Debug Build).
3. In the extension development host, open a .star file and enjoy syntax highlighting and error messages!

Known Issues

• Type guards are not supported.
• Type checker shows some false positives, especially when the definitions from the builtins proto are incorrect.
  • Because of these two issues, some type checking diagnostics are currently set to display as warnings.
• Type checking + goto definition for symbols loaded from external dependencies will only work if those dependencies have already been fetched. If you see Could not resolve module warnings in load statements, make sure to run bazel fetch //... to make sure the external output base is up-to-date.
• When --enable-bzlmod is set, type checking/goto definition may be slow for a given file the first time it is loaded. This is because resolution of repo mappings, done with bazel mod dump_repo_mappings, is done lazily.
  • Additionally, when new dependencies are added, the language server needs to be restarted to refresh the mappings. This is due to the fact that repo mappings are cached, which is necessary to avoid slow type checking.

Acknowledgements

• starpls is heavily based on the rust-analyzer codebase; one might consider it a vastly simplified version of rust-analyzer that works on Starlark files! As such, major thanks to the rust-analyzer team, especially Aleksey Kladov, whose Explaining rust-analyzer series on YouTube proved invaluable as a learning resource!
• starpls's mechanism for carrying out type inference is heavily derived from that of Pyright.