styrainc / zed-rego Goto Github PK

View Code? Open in Web Editor NEW

16.0 2.0 1.0 2.03 MB

Zed extension for the Rego policy language from Open Policy Agent (OPA)

Home Page: https://github.com/StyraInc/zed-rego

License: Apache License 2.0

Rust 74.50% Scheme 24.31% Shell 1.19%

code-quality developer-experience editor open-policy-agent regal rego zed opa policy-as-code

zed-rego's Introduction

Zed Rego Extension

Zed extension for the Rego policy language from Open Policy Agent (OPA).

Features

Rego Syntax Support

Basic features like syntax highlighting and indentation works out of the box. More advanced features are provided by Regal.

Regal Language Server Support

This extension uses the Regal language server for Rego to provide most of its functionality. The following features of the language server are currently supported:

Diagnostics (linting)
Hover (inline docs on built-in functions)
Go to definition (cmd + click on a reference to go to definition)
Folding ranges (expand/collapse blocks, imports, comments)
Document and workspace symbols (cmd+t to navigate to rules, functions, packages)
Inlay hints (but may need to be enabled in settings "Toggle inlay hints")
Formatting
Code actions
Code completion

Installation

This extension is available in the Zed extension marketplace, and you'll find it by searching for "rego" in the extensions view.

Since the extension makes use of Regal for language server features, the extension will automatically try to download the latest version of Regal to use, unless the regal binary is found on $PATH.

If you want to have updates of Regal managed automatically, you can use Homebrew to install the regal binary instead (MacOS & Linux):

brew install styrainc/packages/regal

Tasks

This extension additionally provides two tasks for running tests. Note that both of the tasks assume that the workspace can be read as a bundle (similarly to what the OPA extension for VS Code expects).

opa test (workspace)

Runs all tests found in the workspace. This is a normal task made available in the command palette (task: spawn).

opa test (single test)

This is a special task (called a runnable) which is made available inside of test packages, and where a "play" button will appear next to any test rule. Pressing this button will run only that test.

opa eval ?

The opa eval command requires a query containing the full path to what should be evaluated. This is commonly the package path + the name of the rule to be evaluated. While we can use a tree-sitter query to extract the rule name — like we do for running single tests — we have yet to understand if it's possible / how to extract both the package path and the rule name and concatenate them to build a query.

You can however easily create a custom task for opa eval where you provide the query yourself, and use that in your project. Such a task may look something like the example below:

.zed/tasks.json

[
  {
    "label": "opa eval (data.policy.main)",
    "command": "opa",
    "args": ["eval", "--bundle", "$ZED_WORKTREE_ROOT", "--input", "$ZED_WORKTREE_ROOT/input.json", "data.policy.main"],
  }
]

Custom Tasks

See the Zed documentation tasks for information about how to easily add your own custom tasks, either globally or to a specific project. These docs also details which environment variables are available in the task execution context.

Development

See the docs on contributing if you're interested in hacking on this extension.

Credits

Tree-sitter grammar provided by the tree-sitter-rego project
Language server for Rego provided by Regal

Community

For questions, discussions and announcements related to Styra products, services and open source projects, please join the Styra community on Slack!

zed-rego's People

Contributors

Stargazers

Watchers

Forkers

anderseknert

zed-rego's Issues

Add tasks relevant to OPA / Rego

Extensions can ship tasks now too: https://zed.dev/blog/zed-decoded-tasks#language-specific-tasks

We should look into which ones we should ship with the extension. Things like opa build, opa eval and so on. Seems like there are still some limitations on what we can do from an extension, so I'm not sure we can do things like opa eval yet, as that requires us to build a query from the package + rule... but we can try, or at least add a few tasks that do work today already.

Investigate if we can use keywords like "opa" and "open policy agent" for marketplace search

Currently, the extension can only be found by searching for "rego". While this is alright, it's likely that some users will search for "opa" or "open policy agent" instead, and won't be able to find it, or at least not on the first attempt. We should investigate whether it's possible to add these keywords somewhere. If it isn't, let's create a feature request for that in the Zed project.

Integration Zed extension GitHub Action for updates

For details, see https://github.com/huacnlee/zed-extension-action

Prompt users to update Regal if their version is outdated

On start-up, when a Rego file is opened and Regal is started, if Regal is is not the latest release, then the user should be prompted to update. If the binary is managed by zed-rego, then I then it should complete the update for the user.

Indentation

From what we can see from the configuration of other languages, indentation rules should be provided in a languages/rego/indents.scm file, using tree-sitter queries. The contents of this directory, and the indents.scm file is not described in the Zed docs. In fact the only documentation provided on the languages directory is this single sentence:

Ugh.

But anyway, again looking at how other languages are configured, it would seem like a good starting point, and likely even good enough, to just increase indentation on {, [ and (, and decrease it on their closing counterparts. For a language like Clojure, this is represented as:

(_ "[" "]") @indent
(_ "{" "}") @indent
(_ "(" ")") @indent

Putting that in an a languages/rego/indents.scm file however breaks the extension on installation. From the logs:

2024-05-29T08:46:13+02:00 [ERROR] failed to load language rego:
Error loading indents query

Caused by:
    Query error at 1:5. Invalid node type

I've tried all of the alternatives I've found in the different language configurations, but the result is either an error, or indentation increase working but not decrease.

Strings should auto-close

I thought we did that already, but apparently not? Maybe something changed again, or I remember wrong.

Either way, typing something like:

foo := "

Should automatically add a closing quote:

foo := ""

Consider allowing configuring path to regal binary

I'm not sure whether it's considered a sin for a language extension to provide its own configuration, if that's even possible. But if it's cheap to try, we should. From what I can see, unknown configuration options are at least not treated as errors... but I'm not sure if they can be read by the Rust code doing the initialization.

The reason this would be useful is that sometimes you'll want to have stable Regal on $PATH, but test things out with a custom binary for development.

automate updating tree-sitter-rego commit in configuration file

Automate the creation of the following PR: #25

I'd imagine it would be similar to dependabot, perhaps a github action that checks weekly to get the latest commit and updates the file.

Add a basic build pipeline for CI

While most of the action happens elsewhere, we should at least have some basic verification in place to know that the code builds, and whatever else might be useful to track.

Runnables no longer visible in stable release

The "click to run test" runnable dissapeared after I installed the now released extension. Could possibly be that Zed was updated, and we were relying on an old way to achieve this (as the new way would previously not work).

We can follow the instructions here for trying if the new method works for us now, and if so update to use that.

Figure out how to link to docs for linter rules

A huge part of Regal's value is in its documentation. Particularly for people learning Rego, the short descriptions provided for the rules may tell the "what", but only in an extremely limited form, and certainly not the "why".

Screenshot showing typical violation description on hover:

Notice how not even the rule name is displayed here, making it unlikely that the user is even able to find it by searching online.

The "Problems" view is a little more detailed, as it at least will display the name of the rule, but that's about it:

We should try and figure out if there's any way that we can get Zed to display links to the Regal rules documentation, on hover and in the problems view. If that's not possible, we need to make the best of what we have, and adapt the messages so that at least the name of each rule is displayed in all views, and that the README/docs make it very clear how to find the documentation for any given linter rule.

Sadly, the Code Action "Go to documentation for rule X" is similarly broken, as Zed doesn't appear to have a built-in command for opening links, like vscode.open in VS Code.

One place where it looks like we can reliably show links is in the hover provider:

Shoehorning linter violations in there would be a huge hack, but...

Let's try and find a better way first.