Skip to content

Releases: StyraInc/regal

v0.28.0

07 Oct 15:31
@github-actions github-actions
v0.28.0
9503967
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.
Compare
Choose a tag to compare
v0.28.0 Latest
Latest

New Rule: missing-metadata #1131

The new missing-metadata rule helps ensure policies are documented by requiring METADATA comments on public packages and rules. Metadata comments are used to explain functionality and annotate Rego constructs with other data.

Note: missing-metadata is a custom rule and so is not enabled by default for all users.

fixer: Automated fixing of directory-package-mismatch

This release brings improvements to regal fix, the command to automatically fix supported violations (#1120, #1127).

Fixes for the directory-package-mismatch violations involve moving files based on their packages. For example a file with package foo.bar in policies/policy.rego would need to be moved to foo/policy.rego. In previous versions of Regal, when multiple files in a large code base with the same filename needed to be moved to the same package directory, Regal would output a confusing error message.

Regal v0.28.0 outputs a clear error message by default and adds a new --on-conflict=rename modifying flag to allow conflicting files to automatically be renamed when this scenario is encountered.

Linter Improvements

Language Server Performance Improvements

Dependency Updates

  • anderseknert/roast v0.2.0 -> v0.4.2 #1140, #1170
  • open-policy-agent/opa v0.68.0 -> v0.69.0 #1152

Github Actions Updates

  • golangci/golangci-lint-action 6.1.0 -> 6.1.1 #1163
  • peter-evans/create-pull-request 7.0.3 -> 7.0.5 #1114
  • github/codeql-action 3.26.7 -> 3.26.11 #1117, #1137, #1157, #1174
  • actions/checkout 4.1.7 -> 4.2.0 #1142
  • codecov/codecov-action 4.5.0 -> 4.6.0 #1162, #1164
  • actions/cache 4.0.2 -> 4.1.0 #1179

Changelog

Contributors

anderseknert, srenatus, and 4 other contributors
Assets 8
Loading

v0.27.0

17 Sep 15:25
@github-actions github-actions
v0.27.0
f1606de
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.
Compare
Choose a tag to compare
v0.27.0

Debug Adapter Protocol Support

Back in #926 (v0.26.0), support was added for the Debug Adapter Protocol (DAP), based on the new OPA SDK added in #6876 (documentation). This release improves on this making it ready for consumption in clients. Namely, the addition of a new Debug Code Lens in #1103 and a bug fix for ast.ref_to_string which brings the Regal implementation inline with OPA’s (#1106).

Please see our documentation here to get started.

Screenshot 2024-09-17 at 15 01 08

Neovim DAP Support

Thanks to community member @rinx, DAP support is also available in the Neovim editor. This is based on nvim-dap, and @rinx’s own project nvim-dap-rego. This is an awesome contribution which represents an important improvement for Neovim users of Regal. Thank you Rintaro Okamura for all your work here, it is appreciated.

Screenshot 2024-09-17 at 16 04 45

New Rule: comprehension-term-assignment

This rule flags cases where an intermediate assignment is used within a comprehension body when the value can be directly used as the comprehension term. It enforces the removal of redundant assignments, encouraging more concise and readable code.

# avoid
names := [name |
    some user in input.users
    name := user.name
]

# prefer
names := [user.name | some user in input.users]

Compiler Stage Source Explorer

A new Source Action has been added to allow users of compatible clients to explore the compiler stages of the Rego code they’re working on.

By integrating opa-explorer with Regal, it’s now possible to launch a web server to view the explorer output. Users will see a "Source Action" in the context menu of Rego files, which opens the explorer for that file. This feature is currently limited to VS Code due to available commands. Currently, only a single file is loaded into the explorer for compilation.

Screenshot 2024-09-17 at 15 21 02

Source Action shown in VS Code

Screenshot 2024-09-17 at 15 22 14

Browser showing the given file's compiler explorer

Test Flake Fixes

This release contains a number of fixes for flakey tests that have been disrupting the contributor experience. If you experience flakes and re-run checks on a PR, please leave a comment to let us know so we can look into it. #1112, #1102, #1101

Changelog

Contributors

anderseknert, rinx, and 2 other contributors
Assets 8
Loading

v0.26.2

10 Sep 14:58
@github-actions github-actions
v0.26.2
6f9b32f
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.
Compare
Choose a tag to compare
v0.26.2

This releases contains a bug fixes for an issue introduced in v0.26.0 as well as a number of other minor improvements.

Notable Bug fixes:

  • #1087 fixes an issue in the marshalling of ASTs using RoAST
  • #1056 Makes a change to no longer suggest built in functions for default rules
  • #1065 fixes an issue where git was required even when fixing in dry run mode
  • #1069 fixes an edge case in use-some-for-output-vars
  • #1078, #1080, #1083, #1085 fix issues relating to file rename updates from the client
  • #1093 addresses an issue where the fix command produced the incorrect result due to relative paths
  • #1081 ensures that .manifest files are correctly detected as 'roots' when fixing

New features:

  • #1059 updates the language server to suggest boolean values at relevant times
  • #1088 adds a new feature for rule authors to use the files from their project as input for evaluation

Changelog

Contributors

anderseknert, srenatus, and 2 other contributors
Assets 8
Loading

v0.26.1

05 Sep 08:43
@github-actions github-actions
v0.26.1
1cfdee9
This commit was created on GitHub.com and signed with GitHub’s verified signature.
GPG key ID: B5690EEEBB952194
Learn about vigilant mode.
Compare
Choose a tag to compare
v0.26.1

This releases contains a bug fix for an issue introduced in v0.26.0. The bug was caused by a change the required data to complete a formatting Rego 'fix'.

Changelog

Contributors

anderseknert
Assets 8
Loading

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