Skip to content

Releases: StyraInc/regal

v0.26.0

04 Sep 19:12
@github-actions github-actions
v0.26.0
bf6e879
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.
Compare
Choose a tag to compare
v0.26.0

v0.26.0 brings 2 new linter rules to Regal, a debugger API backend, and noticeably faster linting.

Regal v0.26.0 is likely the first consumer of the new debugger API that landed in OPA v0.68.0 just last week — and in turn uses this to expose a first ever Debug Adapter Protocol (DAP) backend for Rego! Next release of the OPA VS Code extension will leverage Regal to provide developers a first-class debugging experience for Rego. Stay tuned!

Thanks to @johanfylling for tirelessly working to make this happen — in both OPA, Regal, and the OPA VS Code extension.

Rules

New rule: directory-package-mismatch

Category: idiomatic

The directory-package-mismatch rule is a first of its kind in Regal, as it reports issues in project structure rather than in code. This rule codifies an old best practice in Rego projects: the package name (path) should be mirrored in the directory structure a policy resides in. Put simply, a policy declaring package rbac.user.roles should be placed in a rbac/user/roles directory.

The directory-package-mismatch rule not only helps enforce this convention, but provides both CLI (regal fix) and editor support for fixing these issues automatically.

Note: When used on an existing project, this rule will likely result in a lot of violations being reported. While regal fix can remediate that in a matter of seconds (by moving policy files according to their package paths), make sure to commit or stash any existing changes before running it, and then review the result. Read the docs for details!

For more information, see the docs on directory-package-mismatch.

New Rule: sprintf-arguments-mismatch

Category: bugs

The new sprintf-arguments-mismatch rule checks that the formatting directives (%s, %d, etc) in a sprintf call match the supplied number arguments.

Wrong

msg := sprintf("number of issues (%d) must not be higher than %d", [count(issues)])

Correct

msg := sprintf("number of issues (%d) must not be higher than %d", [count(issues), 10])

For more information, see the docs on sprintf-arguments-mismatch.

Debug Adapter Protocol Backend

This release add support in Regal for the Debug Adapter Protocol. Similar to the language server protocol, this new functionality will support users of compatible clients to step-by-step debug their Rego projects in an interactive manner. Client implementation in the VS Code OPA extension soon to follow!

Language Server: auto-completion based on input.json

Both the OPA VS Code extension, and Regal supports placing an input.json file in the workspace and automatically have it used as input for evaluation. If found, Regal will now additionally use this to provide completion suggestions on input based on the fields found in that file. If you haven't made it a habit yet to keep an input.json file in your workspace, now is a good time to start!

New RoAST library for custom AST serialization

Regal now uses a new, custom and optimized AST format to improve the performance of Regal. The new library is integrated into Regal in this release and represents around a 50% reduction in AST JSON size, and a 25% performance improvement in linting over the previous implementation.

For more information, see the docs in the roast project repo.

Special thanks to our contributors from the community!

Changelog

Contributors

anderseknert, srenatus, and 5 other contributors
Assets 8
Loading

v0.25.0

15 Aug 13:33
@github-actions github-actions
v0.25.0
1e14d08
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.
Compare
Choose a tag to compare
v0.25.0

This release brings 2 new rules to the Regal linter as well as a number of improvements to the Regal Language Server.

Rules

New rule unused-output-variable

Category: bugs

In this example, if x is unused later in the rule, it is considered an unused output variable.

package policy

allow if {
    some x
    role := input.user.roles[x]

    # do something with "role", but not "x"
}

Unused output variables should be replaced by wildcards (_), as it makes it clear that the variable isn't going to be used.

For more information, see the docs on unused-output-variable.

New rule use-strings-count

Category: idiomatic

strings.count is a new OPA built-in function and should be used in place of counting indexes (count(indexof_n("foobarbaz", "a"))) as was common before.

Not only is strings.count more readable, but it also performs better.

For more information, see the docs on use-strings-count.

Other Rule Updates

The argument-always-wildcard rule will now ignore mock_ prefixed functions by default, as wildcard arguments are commonly used in mocked functions.

Linter

  • The JUnit XML output format is now a supported by regal lint. This can be used by e.g. GitLab CI/CD jobs to have linter violations printed in the code view in GitLab merge requests. Thanks @sebhoss for the work on this one!
  • Regal's version of OPA has been updated to v0.67.0, you'll need to be using this version to use the remediation for the use-strings-count rule.
  • The --var-values flag from opa test (added to OPA in v0.66.0) is now supported by the regal test command. This allows custom policy authors to see the the variable values in scope of a failed test.

Regal Language Server

Code Lens Support

Regal now provides a Code Lens for direct evaluation of packages or rules within the editor, providing immediate feedback. In supported editors, you can now evaluate a package or rule by pressing "Evaluate" above its declaration, with the results displayed in-line.

code.lens.eval.mov

Input data provided via input.json, and data.json/data.yaml files from bundle directories in the workspace are also available at evaluation time.

Improved Formatter

The language server can now be configured to use regal fix as a formatter when saving buffers. In VS Code, setting opa.formatter to regal-fix will enable this feature.

Other editors can use this by setting the initializationOptions.formatter.

New Contributors

Thanks @rinx for their work on creating the Regal Nix package! (and updating our docs) and @sebhoss for the JUnit output format.

Changelog

Contributors

sebhoss, anderseknert, and 3 other contributors
Assets 8
Loading

v0.24.0

16 Jul 17:23
@github-actions github-actions
v0.24.0
34202b5
Compare
Choose a tag to compare
v0.24.0

This release brings 4 new rules to Regal's linter as well as a number of improvements to the language server.

Rules

New Rule if-object-literal

This rule helps users avoid an error case where an object follows an if. Typically this represents an incomplete rule.

allow if {}

Read the docs on if-object-literal.

New Rule pointless-reassignment

Variables in Rego are immutable, so adding a new variable for an existing short variable only adds noise. Read the docs on pointless-reassignment.

New Rule argument-always-wildcard

Sometimes, particularly after refactoring, a function argument is always a wildcard (_):

my_func(name, _)
my_func("Alice", _)

This rule catches such cases as they typically offer an opportunity for further refactoring or an error where the argument should be used in one or more cases. Read the docs on argument-always-wildcard.

New Rule annotation-without-metadata

Rules containing METADATA annotation syntax without a METADATA header will not be parsed and represents a likely mistake.

# description: allow allows
allow if {  
	# ... some conditions  
}

Read the docs on annotation-without-metadata.

New Rule var-shadows-builtin

Variables that share the name of a built-in group or function should be renamed to avoid confusion.

# variable `http` shadows `http.send` built-in function  
allow if {  
	http := startswith(input.url, "http://")  
	# ...
}

Read the docs on var-shadows-builtin.

Regal Language Server

Snippet Completions

We have extended the support for completions to add snippets for some and every. Both key:value and collection formats are supported.

Screen.Recording.2024-07-16.at.17.31.42.mov

Example Links on Keyword and Built-in Hover

We've been building out a new documentation section called 'Rego By Example'. We have detailed guides here for some of the common keywords and built-in functions. Users can now browse directly to these from their editors by hovering over supported keywords and functions.

Screen.Recording.2024-07-16.at.17.34.05.mov

Supported:

  • Keywords some and every
  • Function Groups io.jwt, regex, time, and contains
  • (more coming soon!)

Suggestions for Variables in Local Scope

We've got lots of completions providers now, this new one suggestions previously defined local variables like this:

Screenshot 2024-07-16 at 18 02 10

Project Housekeeping

Start-up Version Check

With much work going into keeping a regular stream of updates, we felt it was important to help users stay up-to-date. In this release we have laid the groundwork for this by having Regal consult the latest releases on GitHub at startup and reporting if the current version is now outdated.

Please see Remote Features for more information and for instructions on how to disable this.

Use OSSF Scorecard

The OpenSSF Scorecard evaluates open source projects against security best practices to identify potential risks and areas for improvement. In this release we have added a workflow to scan the project on a schedule.

New Contributors

Thanks @maruloop for your first contribution to the project in #865 - and for working on this reviewdog integration for our project.

Changelog

Read more

Contributors

anderseknert, maruloop, and 3 other contributors
Assets 8
Loading

v0.23.1

10 Jun 13:58
@github-actions github-actions
v0.23.1
d0def34
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.
Compare
Choose a tag to compare
v0.23.1

This is a patch release containing a number of fixes. Most of the issues fixed in this release were not directly related to v0.23.0, but we simply don't like the idea of waiting for the next release to address known bugs.

Bugs fixed

  • Ignore directives (like # regal ignore:unresolved-import) didn't work properly for aggregate rules (i.e. rules that require multiple files to determine if the rule is violated or not). That's now been fixed. Thanks @nejec for bringing this to our attention!
  • Fix missing rule type in the header of the unresolved-import rule documentation
  • An empty .regal/config.yaml file would previously have Regal fail with an error. Now it'll simply print a warning and continue with the default configuration
  • Fix an issue in the language server where completion suggestions would sometimes repeat a word already typed in
  • Remove an init call in the language server that would take ~100 milliseconds to process, even for commands that didn't make use of the language server (like regal lint)
  • The regal lint --format json would previously output errors as pretty-printed text rather than JSON. That has now been fixed.
  • The textDocument/diagnostic response from the language server is now null rather than an empty object. This solves an issue observed with the Neovim client.

Changelog

Contributors

anderseknert, charlieegan3, and nejec
Assets 8
Loading

v0.23.0

05 Jun 19:41
@github-actions github-actions
v0.23.0
89d3a7a
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.
Compare
Choose a tag to compare
v0.23.0

This 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!

Changelog

Read more

Contributors

anderseknert, charlieegan3, and 4 other contributors
Assets 8
Loading

v0.22.0

22 May 11:35
@github-actions github-actions
v0.22.0
9d148de
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.
Compare
Choose a tag to compare
v0.22.0

This is a release brings 3 new linter rules, as well as some exciting new features, improvements and fixes to both the linter and the language server.

New rule: impossible-not

Category: bugs

The impossible-not rule will flag when the not keyword is used to test a partial (multi-value) rule. Even when a set contains no values, it isn't considered "falsey", so using not in that context is essentially a constant condition. This mistake is particularly common in tests:

package policy

import rego.v1

partial_rule contains item if {
    # ...
}
package policy_test

import rego.v1

test_partial_rule if {
    # This will now be flagged, as the not-condition is impossible
    not partial_rule with input as {
        # ...
    }
}

Future versions of this rule may detect even more impossible not conditions.

For more information, see the docs on impossible-not.

New rule: messy-rule

Category: style

Rules that are defined incrementally should be be placed in a sequence, and with no other rule definitions in between. The new messy-rule linter will help identify such cases, and suggest a re-organization.

Avoid

package policy

allow if something

unrelated_rule if {
    # ...
}

allow if something_else

Prefer

package policy

allow if something

allow if something_else

unrelated_rule if {
    # ...
}

For more information, see the docs on messy-rule.

New rule: trailing-default-rule

Category: style

The new trailing-default-rule linter will flag rules with default default conditions where the default assignment isn't placed before the other rules. Putting the default rule first makes it easier to read the policy, knowing there's a default fallback condition for the rules requiring more complex conditions to be met.

Avoid

package policy

import rego.v1

allow if {
    # some conditions
}

default allow := false

Prefer

package policy

import rego.v1

default allow := false

allow if {
    # some conditions
}

For more information, see the docs on trailing-default-rule.

Language server: Code completion suggestions

The Regal language server now provides a minimal implementation of the code completion feature. This first implementation will help suggest package name based on directory structure, the rego.v1 import and built-in functions at certain locations. This provides a big productivity boost, as users no longer need to jump back to the OPA docs to find the built-in function they need.

codecompletion

More completion suggestions will follow in the next releases, like references to rules and functions. Stay tuned!

Other improvements

  • The external-reference rule now detects more cases than previously (thanks @asleire for reporting this issue!)
  • The regal new rule command now also creates an empty documentation template for the rule
  • The regal fix command now provides documentation for which rules it can fix
  • The language server will now send a warning back to the client if CRLF line endings are detected in a file (thanks @asleire for the suggestion!)
  • The language server will now report parser errors on the whole line instead of just the first character, making them easier to spot
  • The language server will now provide links to documentation for any error encountered that has corresponding docs
  • Bump OPA version to v0.64.1

Bugs fixed

  • Fix issues with loading config file on Windows
  • Improve handling of inlay hints in files with parser errors
  • Fix bug where regal lint --profile would report wrong metrics
  • Where needed, the language server now properly returns null instead of empty object, as per the specification (thanks @sspaink for raising that!)
  • The language server "find definition" feature now honors ignore directives found in the .regal/config.yaml file
  • Fix false positive in redundant-existence-check rule when the with keyword is used (thanks @asleire for reporting this issue!)

Changelog

Contributors

anderseknert, asleire, and 3 other contributors
Assets 8
Loading

v0.21.3

26 Apr 10:24
@github-actions github-actions
v0.21.3
51c9a94
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.
Compare
Choose a tag to compare
v0.21.3

No one wants to wait for bugs to get fixed! So we don't. This third patch release following v0.21.0 fixes an issue where deleted or renamed files would still have violations reported by the language server.

Changelog

Contributors

anderseknert
Assets 8
Loading

v0.21.2

25 Apr 14:47
@github-actions github-actions
v0.21.2
0c3043d
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.
Compare
Choose a tag to compare
v0.21.2

This is patch release addressing two bugs reported by users.

The first bug fixed is in the new unresolved-import rule, where Regal would mistakenly report a reference to a map-generating rule as unresolved. Thanks @nevumx for making us aware of that issue!

The other bug fixed was a panic that could occur when Regal traverses directories looking for a config file. The cause of this is still not known, but at least we'll now fail gracefully and without a panic. Thanks @scoop96 for reporting the issue!

Changelog

Contributors

anderseknert, nevumx, and 2 other contributors
Assets 8
Loading

v0.21.1

24 Apr 15:15
@github-actions github-actions
v0.21.1
55a1294
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.
Compare
Choose a tag to compare
v0.21.1

This patch releases fixes an issue in the language server, which would previously send back an error to the client (i.e. your editor) when a new and empty file was created in the workspace. This would have the server fail to read any document symbols as a result. This has now been fixed to only log the error on the server without sending it back to the client.

Thanks @johanfylling for reporting the issue!

Changelog

Contributors

anderseknert, charlieegan3, and johanfylling
Assets 8
Loading

v0.21.0

23 Apr 12:01
@github-actions github-actions
v0.21.0
24c0b85
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Verified
Learn about vigilant mode.
Compare
Choose a tag to compare
v0.21.0

This is a big release, bringing new regal fix command, several features to the Regal language server, a new linter rule, and many improvements and fixes.

New command: regal fix

The regal fix command allows you to automatically fix some of the (style) issues reported by the Regal linter. This command is available in the CLI and can be run on a single file or a directory. The following linter rules are supported by the regal fix command:

More rules will be added in future releases.

The regal fix command respects the .regal/config.yaml file, and will only fix issues that aren't ignored by configuration.

New rule: unresolved-import

Category: imports

OPA does not resolve imports until runtime, and when it does, unresolved imports are simply undefined. The unresolved-import rule helps catch these issues early by flagging imports that can't be statically resolved by Regal. Since imports could refer to data documents or rules imported at runtime, this linter rule allows providing a list of of references that should be ignored by the linter.

For more information, see the docs on unresolved-import.

Language Server: Code Actions

Similarly to the regal fix command, code actions allows fixing some issues reported by Regal but directly from the editor. This release adds code actions to remediate the following linter rules:

Screenshot 2024-04-23 at 10 25 14

Language Server: Go to Definition

Ctrl/cmd + clicking a reference in the editor now navigates to the definition of the reference, as Regal now implements the "go to definition" feature of the language server protocol.

Screenshot 2024-04-23 at 10 37 02

Language Server: Formatting

The Regal language server now supports formatting Rego files using the opa fmt command. This can be triggered either by running the "Format document" command in your editor, or from where a opa-fmt linter violation is reported in the package.

Language Server: Document Symbols

Symbols — like packages, rules and functions, are now provided by Regal upon requests from an editor. This allows for a quick overview of the structure of a Rego file, and provides "breadcrumbs" to navigate the symbols of an open Rego document.

Screenshot 2024-04-23 at 14 00 14

Language Server: Workspace Symbols

Similarly to document symbols, Regal now reports symbols from the entire workspace, allowing users to search and navigate to any top-level symbol (i.e. package, rule or function) in the workspace.

Screenshot 2024-04-23 at 07 26 20

Language Server: Folding Ranges

Regal now provides folding ranges for Rego files in the workspace, allowing users to fold (i.e. expand or collapse) blocks of code, comments and imports in the editor.

Screenshot 2024-04-23 at 10 45 44

Other improvements

  • The language server now searches for the .regal/config.yaml file in directories above the workspace if not found before. This allows using a shared configuration file for multiple projects. Thanks @bdjgs for requesting this feature!
  • Report not just the line but the exact position of use-assignment-operator violations
  • The result of a hovering over a built-in function is now cached for faster rendering

Bugs fixed

  • Fix bug where whitespace in directory names caused the language server to stop working. Thanks @frittsy for reporting this issue!

Documentation

Changelog

Contributors

anderseknert, charlieegan3, and 2 other contributors
Assets 8
Loading