From 07d5a06d83e952e472256fda0b50ba1ed66ba56e Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 20 Oct 2026 05:14:42 +0000 Subject: [PATCH] docs(editor-setup): document language server completion sites, broken-file behavior and workspace scope Co-Authored-By: Claude Sonnet 5.5 Claude-Session: https://claude.ai/code/session_01F8xcozKkdp6eHY8imo4F6C --- website/docs/guides/editor-setup.md | 33 +++++++++++++++++++++++++---- 1 file changed, 29 insertions(+), 4 deletions(-) diff --git a/website/docs/guides/editor-setup.md b/website/docs/guides/editor-setup.md index e9569f0..5d59f8f 100644 --- a/website/docs/guides/editor-setup.md +++ b/website/docs/guides/editor-setup.md @@ -14,12 +14,31 @@ go-to-definition, and document formatting. | Feature | What you get | |---------|-------------| -| Diagnostics | Flags a `target()` or `provider_state()` call that's missing a required field — a base field like `name`, or, once `driver`/`provider` is set, a field required by that driver or provider. | -| Completion | `target`, `file`, `glob`, `struct`, `provider_state`, `heph.core.*`, and every provider function complete with their signatures and inline docs. Address strings (`//pkg:name`) complete packages and target names as you type. Inside a `target(driver="exec", …)` call, the driver's accepted fields complete with types and descriptions. | -| Hover | Signature and documentation for any builtin or provider function. Hover a `target()` call to see the addresses it produced and, once its `driver` is set, that driver's config fields with their types and descriptions. Same for `provider_state()`: once its `provider` is set, hover shows that provider's state fields instead of a generic signature. | -| Go-to-definition | Jump to the BUILD file that defines an address — both `//pkg:name` and relative `:name` forms. | +| Diagnostics | Syntax errors as you type (the first error on each line), and a `target()` or `provider_state()` call that's missing a required field — a base field like `name`, or, once `driver`/`provider` is set, a field required by that driver or provider. | +| Completion | See [Completion](#completion). | +| Hover | Signature and documentation for any builtin or provider function. Hover a `target()` call to see the addresses it produced and, once its `driver` is set, that driver's config fields with their types and descriptions. Same for `provider_state()`: once its `provider` is set, hover shows that provider's state fields instead of a generic signature. Hover a field name for its type and description, and a `heph..` name for its signature. | +| Go-to-definition | Jump to the BUILD file that defines an address — both `//pkg:name` and relative `:name` forms. Also jumps from a `load()` path to the loaded file, from a loaded symbol to its `def`, and from a name to its `def` elsewhere in the package. | | Formatting | Format-on-save rewrites the open BUILD file to canonical style. Uses the same rules as [`heph tool build-fmt`](/docs/guides/formatting-build-files), respecting the workspace `indent` setting and the `# heph:fmt skip-file` directive. | +## Completion + +| Where the cursor is | What completes | +|---------------------|----------------| +| `driver = "` in `target()` | Driver names | +| `provider = "` in `provider_state()` | Provider names | +| A keyword name in `target()` | The base fields plus the selected driver's fields, minus the ones already written | +| A keyword name in `provider_state()` | `provider` plus the selected provider's fields, minus the ones already written | +| A keyword name in a call to another function (`my_rule(`, `glob(`) | The function's remaining parameters, inserted as `name = `, ahead of the usual suggestions | +| After `heph.` | Plugin names and `core` | +| After `heph..` | That plugin's functions | +| A string starting with `//` or `:` | Packages and targets | +| The first argument of `load(` | Package paths | +| A later string argument of `load(` | The `def`s exported by the loaded file | + +Completion keeps working while the file doesn't parse — typically when you are +midway through typing a call or string. An error later in the file doesn't +affect the suggestions at the cursor. + ## VS Code Install the [heph extension](https://marketplace.visualstudio.com/items?itemName=hephbuild.heph-nightly) from the marketplace. It configures the language server automatically. @@ -48,6 +67,12 @@ vim.api.nvim_create_autocmd("BufRead", { }) ``` +### Workspaces + +The server handles a single workspace: the first workspace folder your editor +sends, which must be inside the heph repository it was started in. A BUILD file +outside that repository only gets generic Starlark completion and hover. + ### Other editors Any editor with LSP support works. The relevant settings are: