Regal v0.23.0 released!

[anderseknert]

This is a release adds 3 new linter rules to Regal, greatly improved completion suggestions in the language server, and a number of other improvements and fixes.

New rule: leaked-internal-reference

Category: bugs

Following the recently added style guide recommendation to use underscore prefixes to denote internal rules and functions, this was the first rule to help enforce that convention. The leaked-internal-reference rule will flag any reference to a rule or function with an underscore prefix that is not defined in the same package:

package policy

import rego.v1

# this will be flagged, as `_allow` is considered internal to the `authz` package
allow if data.authz._allow

For more information, see the docs on leaked-internal-reference.

New rule: internal-entrypoint

Category: bugs

Rules annotated as entrypoints are public by definition and must not be prefixed with an underscore.

Avoid

package policy

import rego.v1

# METADATA
# entrypoint: true
_authorize if {
    # some conditions
}

Prefer

package policy

import rego.v1

# METADATA
# entrypoint: true
allow if _authorize

_authorize if {
    # some conditions
}

For more information, see the docs on internal-entrypoint.

New rule: ambiguous-scope

Category: idiomatic

The default scope for metadata annotating a rule is the rule scope, which applies to the individual rule statement only. This default is sensible for a rule defined only once, but is somewhat ambiguous for a rule defined incrementally, like the allow rule in the examples below. Was the intention really to annotate that single definition, or the rule as whole? Most likely the latter.

If only a single rule in a group of incremental rule definitions is annotated, it should have it's scope set explicitly to either document or rule. If all incremental definitions are annotated, explicit scope: rule is not required.

Avoid

# METADATA
# description: allow is true if the user is admin, or the requested resource is public
allow if user_is_admin

allow if public_resource

Prefer

# METADATA
# description: allow is true if the user is admin, or the requested resource is public
# scope: document
allow if user_is_admin

allow if public_resource

Or (scope rule implied, but all incremental definitions annotated)

# METADATA
# description: allow is true if the user is admin
allow if user_is_admin

# METADATA
# description: allow is true if the requested resource is public
allow if public_resource

Or (scope rule explicit)

# METADATA
# description: allow is true if the user is admin
# scope: rule
allow if user_is_admin

allow if public_resource

For more information, see the docs on ambiguous-scope.

For more information about the scope metadata attribute, see the OPA docs.

Language server: Greatly improved completion suggestions

Last release introduced a minimal implementation of code completion, which means that the language server supports providing completion suggestions while editing Rego in an editor that supports the Regal languge server, such as VS Code using the OPA VS Code extension.

This release provides greatly improved completion suggestions, including:

• References to packages, rules and functions (both imported and complete references)
• Keywords like import, default, contains, if
• Completions on input attributes based on those previously used
• Common rule names like allow and deny
• New package names based on directory structure
• Many more suggestions based on the context of the cursor position

Using completion suggestions now feels like a total game changer for productivity, and we really recommend trying it out!

Other improvements

• Bump OPA version to v0.65.0
• Improve LSP implementation to better handle different clients
• Don't show completion suggestions for internal references outside of their package
• Show different types of icons in completion suggestions based on what's suggested

Docs

• Update README to reflect current LSP features
• Add new documentation page for integrating Regal in build pipelines (thanks @Parsifal-M!)
• Fix typo in messy-rule documentation (thanks @Parsifal-M!)
• Add instructions for installing Regal via asdf (thanks @smorimoto for providing the plugin!)
• Rename development.md -> CONTRIBUTING.md to align with convention
• Add SECURITY.md doc under docs directory

Bugs fixed

• Fixed false positive when importing input or data in ignored-import
• Fix possible concurrent read of maps in completion provider
• Filter out ignored files in regal fix command (thanks @oren-zohar for reporting the issue!)

Breaking changes

These changes do not affect regular users of Regal, but possibly power users that have built their own custom rules relying on these helpers.

• Remove the regal.json_pretty built-in function. Users can now use json.marshal_with_options from OPA instead.
• Remove the ast.name function in favor of ast.ref_to_string

Thank you to all contributors, community members and users! 🎉

If you have any questions, would like to discuss the release, or talk about Regal in general, you'll find us in the Styra Community Slack!

Full changelog and downloads here.