{"id":19939023,"url":"https://github.com/withered-magic/starpls","last_synced_at":"2025-07-01T02:03:20.727Z","repository":{"id":213439652,"uuid":"733640307","full_name":"withered-magic/starpls","owner":"withered-magic","description":"An LSP implementation for Starlark, the configuration language used by Bazel and Buck2.","archived":false,"fork":false,"pushed_at":"2025-06-28T07:09:18.000Z","size":1767,"stargazers_count":149,"open_issues_count":53,"forks_count":15,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-06-28T08:21:15.670Z","etag":null,"topics":["bazel","lsp","starlark"],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/withered-magic.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-APACHE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2023-12-19T19:37:22.000Z","updated_at":"2025-06-28T07:09:21.000Z","dependencies_parsed_at":"2023-12-27T10:29:17.474Z","dependency_job_id":"47573bd6-117d-4a5e-87f6-a471b40e356a","html_url":"https://github.com/withered-magic/starpls","commit_stats":null,"previous_names":["withered-magic/starpls"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/withered-magic/starpls","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/withered-magic%2Fstarpls","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/withered-magic%2Fstarpls/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/withered-magic%2Fstarpls/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/withered-magic%2Fstarpls/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/withered-magic","download_url":"https://codeload.github.com/withered-magic/starpls/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/withered-magic%2Fstarpls/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262881806,"owners_count":23378923,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bazel","lsp","starlark"],"created_at":"2024-11-12T23:42:44.031Z","updated_at":"2025-07-01T02:03:20.690Z","avatar_url":"https://github.com/withered-magic.png","language":"Rust","funding_links":[],"categories":["IDEs","Rust"],"sub_categories":[],"readme":"# Starpls\n`starpls` is a language server for [Starlark](https://github.com/bazelbuild/starlark), the configuration language used by Bazel and Buck2.\n\n## Installation\n\n### VSCode\n\nMake sure you have at least the [0.10.0](https://github.com/bazelbuild/vscode-bazel/releases/tag/0.10.0) version of the [vscode-bazel](https://github.com/bazelbuild/vscode-bazel) extension installed, as it adds support for launching a language server.\n\nIf you're on a Mac with Apple Silicon, then you can install `starpls` with Homebrew and skip ahead to the section about configuring VSCode:\n\n```sh\nbrew install withered-magic/brew/starpls\n```\n\nOtherwise, you can grab a release from the [releases page](https://github.com/withered-magic/starpls/releases). 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.\n\n```sh\nchmod +x starpls-darwin-arm64\n```\n\nAdditionally, on Mac OS, you may see an error similar to\n\n```\n“starpls-darwin-arm64” can’t be opened because Apple cannot check it for malicious software.\n```\n\nTo 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.\n\nEither way, at this point you can put the executable somewhere on your `$PATH`.\n\nOnce done, add the following to your VSCode configuration and reload VSCode for it to take effect:\n\n```json\n{\n  \"bazel.lsp.command\": \"starpls\"\n}\n```\n\nExperimental features are enabled through flags on the `starpls server` subcommand. For example:\n\n```jsonc\n{\n    \"bazel.lsp.command\": \"starpls\",\n    // Note the first argument is \"server\", which is required because the flags exist only\n    // on the \"starpls server\" subcommand (and not the top-level \"starpls\" command).\n    \"bazel.lsp.args\": [\"server\", \"--experimental_infer_ctx_attributes\"]\n}\n```\n\nNote: 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.\n\nAlternatively, you can build `starpls` with Bazel:\n\n```\nbazel run -c opt //editors/code:copy_starpls\n```\n\nThis builds the executable and copies it to `\u003crepository_root\u003e/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.\n\n### Zed\n\nInstall the [zed-starlark](https://github.com/zaucy/zed-starlark) extension.\n\n### Neovim via nvim-lspconfig\nMake sure you've installed and configured [nvim-lspconfig](https://github.com/neovim/nvim-lspconfig) in a way that works for you.\n\nInstall using homebrew as described above, then do the following in your init.lua:\n```lua\nrequire(\"lspconfig\").starpls.setup { }\n```\n\nYou can see the config info [here](https://github.com/neovim/nvim-lspconfig/blob/master/lua/lspconfig/configs/starpls.lua).\n\n## Tips and Tricks\n\nMake sure to use [PEP 484 type comments](https://peps.python.org/pep-0484/#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...\n\n```python\ndef _impl(ctx):\n    # type: (ctx) -\u003e Unknown\n    ctx.\n    #  ^ and this period was just typed...\n```\n\nthen you'll get autocomplete suggestions for the attributes on `ctx`, like `ctx.actions`, `ctx.attr`, and so on!\n\n## Experimental features\n\nStarpls has a number of experimental features that can be enabled via command-line arguments:\n\n### `--experimental_infer_ctx_attributes`\n\nInfer attributes on a rule implementation function's `ctx` parameter.\n\n```python\ndef _foo_impl(ctx):\n    ctx.attr.bar # type: int\n\nfoo = rule(\n    implementation = _foo_impl,\n    attrs = {\n        \"bar\": attr.int(),\n    },\n)\n```\n\n### `--experimental_use_code_flow_analysis`\n\nUse code flow analysis to determine additional information about types.\n\n```python\nif cond:\n    x = 1\nelse:\n    x = \"abc\"\n\nx # type: int | string\n```\n\n### `--experimental_enable_label_completions`\n\nEnables completions for labels within Bazel files. For example, given the following `BUILD.bazel` file at the repository root:\n\n```python\nmy_rule(\n    name = \"foo\"\n)\n\nmy_rule(\n    name = \"bar\",\n    srcs = [\"//:\"],\n              # ^ ... If the cursor is here, \"foo\" will be suggested.\n)\n```\n\n## Roadmap\n\n- Parsing\n    - [x] Error resilient Starlark parser\n    - [x] Syntax error reporting\n- Semantic highlighting\n    - [x] Unbound variables\n    - [x] Type mismatches\n    - [x] Function call argument validation\n- Auto-completion\n    - [x] Variables/function parameters\n    - [x] Builtin type fields\n    - [x] Rule attributes\n    - [x] Custom provider fields\n    - [x] Custom struct fields\n- Hover\n    - [x] Variable types\n    - [x] Function signatures\n    - [x] Function/method docs\n- Go to definition\n    - [x] Variables (including `load`ed symbols)\n    - [x] Function definitions\n    - [x] Struct fields\n    - [x] Provider fields\n    - [x] Labels and targets\n    - [ ] Rule attributes\n- Document symbols\n    - [x] Variables, functions\n    - [x] Bazel targets\n- Type inference\n    - [x] Basic type inference\n    - [ ] Dataflow analysis\n    - [x] PEP-484 type comments\n        - [x] Variables\n        - [x] Parameters (only basic types currently supported)\n        - [x] Other constructs where type comments are supported\n- Third-party integrations\n    - [x] Bazel builtins (partial, Bazel builtins are supported but still need to handle a number of edge cases)\n    - Special handling for various Bazel constructs\n        - [x] `struct`s (autocomplete fields)\n        - [x] providers (autocomplete and validate fields)\n        - [x] rules defined with `rule` and `repository_rule` (autocomplete and validate attributes)\n- Projects\n    - [x] Type inference across multiple files\n    - [x] `load` support\n        - [x] Relative paths\n        - [x] Bazel workspace\n    - [x] Bazel external repositories\n    - [ ] Nested local repositories\n\n## Development\n\n`starpls` currently requires a nightly build of Rust, due to usage of `trait_upcasting` as specified by [RFC3324](https://rust-lang.github.io/rfcs/3324-dyn-upcasting.html).\n\n### Prerequisites\n\n- `pnpm`, for managing Node dependencies\n- `protoc`, for compiling `builtin.proto`\n\nSteps to get up and running:\n1. Run `pnpm install` in `editors/code`.\n2. Open VSCode, `Run and Debug \u003e Run Extension (Debug Build)`.\n3. In the extension development host, open a `.star` file and enjoy syntax highlighting and error messages!\n\n## Known Issues\n\n- Type guards are not supported.\n- Type checker shows some false positives, especially when the definitions from the builtins proto are incorrect.\n    - Because of these two issues, some type checking diagnostics are currently set to display as warnings.\n- 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.\n- 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.\n    - 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.\n\n## Acknowledgements\n\n- `starpls` is heavily based on the [rust-analyzer](https://github.com/rust-lang/rust-analyzer/tree/master) 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](https://matklad.github.io/), whose [Explaining rust-analyzer](https://www.youtube.com/playlist?list=PLhb66M_x9UmrqXhQuIpWC5VgTdrGxMx3y) series on YouTube proved invaluable as a learning resource!\n- `starpls`'s mechanism for carrying out type inference is heavily derived from that of [Pyright](https://github.com/microsoft/pyright).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwithered-magic%2Fstarpls","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwithered-magic%2Fstarpls","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwithered-magic%2Fstarpls/lists"}