Various improvements for release (#136)

- Revert disabling of `style` rules — most will try this on small libs
- Include download/installation instructions in README
- Including the "level" in the default report is unnecessary
- Add roadmap

Signed-off-by: Anders Eknert <[email protected]>

.github/workflows/build.yaml

@@ -15,6 +15,8 @@ jobs:
         with:
           go-version: 1.20.1
       - uses: golangci/golangci-lint-action@v3
+        with:
+          version: v1.52.2
       - run: go test ./...
       - run: go build
       - run: chmod +x regal

README.md

@@ -25,28 +25,103 @@ using the JSON representation of the Rego abstract syntax tree (AST) as input, a
 few additional custom built-in functions and some indexed data structures to help
 with linting.
 
-## Status
+## Getting Started
+
+### Download Regal
+
+**MacOS and Linux**
+```shell
+brew install styrainc/packages/regal
+```
+
+<details>
+  <summary><strong>Manual download options</strong></summary>
+
+**MacOS (Apple Silicon)**
+```shell
+curl -L -o regal "https://github.com/StyraInc/regal/releases/latest/download/regal_Darwin_arm64"
+```
+
+**MacOS (x86_64)**
+```shell
+curl -L -o regal "https://github.com/StyraInc/regal/releases/latest/download/regal_Darwin_x86_64"
+```
+
+**Linux (x86_64)**
+```shell
+curl -L -o regal "https://github.com/StyraInc/regal/releases/latest/download/regal_Linux_x86_64"
+chmod +x regal
+```
+
+**Windows**
+```shell
+curl.exe -L -o regal.exe "https://github.com/StyraInc/regal/releases/latest/download/regal_Windows_x86_64.exe"
+```
+
+See all versions, and checksum files, at the Regal [releases](https://github.com/StyraInc/regal/releases/) page.
+
+</details><br/>
 
-Regal is currently in an alpha stage. While we'd like to think of it as helpful already, **every** feature, API, name,
-config attribute and paragraph of documentation is subject to change. If you'd still like to use it, we'd love to hear
-what you think!
+### Try it out!
 
-## Try it out!
+First, author some Rego!
+
+**policy/authz.rego**
+```rego
+package authz
+
+import future.keywords
+
+default deny = true
+
+deny if {
+	"admin" != input.user.roles[_]
+}
+```
 
-Run `regal lint` pointed at one or more files or directories to have them linted:
+Next, run `regal lint` pointed at one or more files or directories to have them linted.
 
 ```shell
 regal lint policy/
 ```
+```text
+Rule:         	not-equals-in-loop
+Description:  	Use of != in loop
+Category:     	bugs
+Location:     	p.rego:8:10
+Text:         	"admin" != input.user.roles[_]
+Documentation:	https://github.com/StyraInc/regal/blob/main/docs/rules/bugs/not-equals-in-loop.md
+
+Rule:         	implicit-future-keywords
+Description:  	Use explicit future keyword imports
+Category:     	imports
+Location:     	p.rego:3:8
+Text:         	import future.keywords
+Documentation:	https://github.com/StyraInc/regal/blob/main/docs/rules/imports/implicit-future-keywords.md
+
+Rule:         	use-assignment-operator
+Description:  	Prefer := over = for assignment
+Category:     	style
+Location:     	p.rego:5:1
+Text:         	default deny = true
+Documentation:	https://github.com/StyraInc/regal/blob/main/docs/rules/style/use-assignment-operator.md
+
+1 file linted. 3 violations found.
+```
+
+> **Note**
+> If you're running Regal on an existing policy library, you may want to disable the `style` category initially, as it
+> will likely generate a lot of violations. You can do this by passing the `--disable-category style` flag to
+> `regal lint`.
 
 ## Rules
 
 Regal comes with a set of built-in rules, grouped by category.
 
-- **bugs**: Common mistakes, potential bugs and inefficiencies in Rego policies. All rules **enabled** by default.
-- **imports**: Best practices for imports. All rules **enabled** by default.
-- **style**: [Rego Style Guide](https://github.com/StyraInc/rego-style-guide) rules. All rules **disabled** by default.
-- **testing**: Rules for testing and development. All rules **enabled** by default. 
+- **bugs**: Common mistakes, potential bugs and inefficiencies in Rego policies.
+- **imports**: Best practices for imports.
+- **style**: [Rego Style Guide](https://github.com/StyraInc/rego-style-guide) rules.
+- **testing**: Rules for testing and development.
 
 The following rules are currently available:
 
@@ -81,6 +156,8 @@ The following rules are currently available:
 
 <!-- RULES_TABLE_END -->
 
+By default, all rules are currently **enabled**.
+
 If you'd like to see more rules, please [open an issue](https://github.com/StyraInc/regal/issues) for your feature
 request, or better yet, submit a PR! See the [custom rules](#custom-rules) section for more information on how to
 develop your own rules, for yourself or for inclusion in Regal.
@@ -181,6 +258,20 @@ rules altogether.
 - [Development](/docs/development) for info about how to hack on Regal itself
 - [Rego Style Guide](/docs/rego-style-guide) contains notes on implementing the [Rego Style Guide](https://github.com/StyraInc/rego-style-guide) rules
 
+## Status
+
+Regal is currently in beta. End-users should not expect any drastic changes, but any API may change without notice.
+
+## Roadmap
+
+- [ ] More rules!
+- [ ] Add `custom` category for built-in "custom", or customizable rules, to enforce things like naming conventions
+- [ ] Simplify custom rules authoring by providing command for scaffolding
+- [ ] Improvements to assist writing rules that can't be enforced using the AST alone
+- [ ] Make more rules consider nesting
+- [ ] GitHub Action
+- [ ] VS Code extension
+
 ## Community
 
 For questions, discussions and announcements related to Styra products, services and open source projects, please join

bundle/regal/config/provided/data.yaml

@@ -23,24 +23,24 @@ rules:
       level: error
   style:
     avoid-get-and-list-prefix:
-      level: ignore
+      level: error
     external-reference:
-      level: ignore
+      level: error
     line-length:
-      level: ignore
+      level: error
       max-line-length: 120
     opa-fmt:
-      level: ignore
+      level: error
     prefer-snake-case:
-      level: ignore
+      level: error
     todo-comment:
-      level: ignore
+      level: error
     unconditional-assignment:
-      level: ignore
+      level: error
     use-assignment-operator:
-      level: ignore
+      level: error
     use-in-operator:
-      level: ignore
+      level: error
   testing:
     file-missing-test-suffix:
       level: error

docs/rules/rules/rule-shadows-builtin.md → docs/rules/bugs/rule-shadows-builtin.md

@@ -2,7 +2,7 @@
 
 **Summary**: Rule name shadows built-in
 
-**Category**: Rules
+**Category**: Bugs
 
 **Avoid**
 ```rego
@@ -26,7 +26,7 @@ This linter rule provides the following configuration options:
 
 ```yaml
 rules: 
-  rules:
+  bugs:
     rule-shadows-builtin:
       # one of "error", "warning", "ignore"
       level: error

docs/rules/rules/avoid-get-and-list-prefix.md → docs/rules/style/avoid-get-and-list-prefix.md

@@ -2,7 +2,7 @@
 
 **Summary**: Avoid `get_` and `list_` prefix for rules and functions
 
-**Category**: Rules
+**Category**: Style
 
 **Avoid**
 ```rego
@@ -49,7 +49,7 @@ This linter rule provides the following configuration options:
 
 ```yaml
 rules: 
-  rules:
+  style:
     avoid-get-and-list-prefix:
       # one of "error", "warning", "ignore"
       level: error

docs/rules/functions/external-reference.md → docs/rules/style/external-reference.md

@@ -2,7 +2,7 @@
 
 **Summary**: Reference to input, data or rule ref in function body
 
-**Category**: Functions
+**Category**: Style
 
 **Avoid**
 ```rego
@@ -46,7 +46,7 @@ This linter rule provides the following configuration options:
 
 ```yaml
 rules: 
-  functions:
+  style:
     external-reference:
       # one of "error", "warning", "ignore"
       level: error

docs/rules/comments/todo-comment.md → docs/rules/style/todo-comment.md

@@ -2,7 +2,7 @@
 
 **Summary**: Avoid TODO Comments
 
-**Category**: Comments
+**Category**: Style
 
 **Avoid**
 ```rego
@@ -40,7 +40,7 @@ This linter rule provides the following configuration options:
 
 ```yaml
 rules: 
-  comments:
+  style:
     todo-comment:
       # one of "error", "warning", "ignore"
       level: error

docs/rules/variables/unconditional-assignment.md → docs/rules/style/unconditional-assignment.md

@@ -2,7 +2,7 @@
 
 **Summary**: Unconditional assignment in rule body
 
-**Category**: Variables
+**Category**: Style
 
 **Avoid**
 ```rego
@@ -37,7 +37,7 @@ This linter rule provides the following configuration options:
 
 ```yaml
 rules: 
-  variables:
+  style:
     unconditional-assignment:
       # one of "error", "warning", "ignore"
       level: error

docs/rules/assignment/use-assignment-operator.md → docs/rules/style/use-assignment-operator.md

@@ -2,7 +2,7 @@
 
 **Summary**: Prefer `:=` over `=` for assignment
 
-**Category**: Assignment
+**Category**: Style
 
 **Avoid**
 ```rego
@@ -74,7 +74,7 @@ This linter rule provides the following configuration options:
 
 ```yaml
 rules: 
-  assignment:
+  style:
     use-assignment-operator:
       # one of "error", "warning", "ignore"
       level: error

docs/rules/functions/print-or-trace-call.md → docs/rules/testing/print-or-trace-call.md

@@ -2,7 +2,7 @@
 
 **Summary**: Call to `print` or `trace` function
 
-**Category**: Functions
+**Category**: Testing
 
 **Avoid**
 ```rego
@@ -35,7 +35,7 @@ This linter rule provides the following configuration options:
 
 ```yaml
 rules:
-  functions:
+  testing:
     print-or-trace-call:
       # one of "error", "warning", "ignore"
       level: error

pkg/linter/linter_test.go

@@ -71,7 +71,7 @@ func TestLintWithUserConfig(t *testing.T) {
 	policy := `package p
 
 foo := input.bar[_]
-	
+
 or := 1
 `
 

pkg/reporter/reporter.go

@@ -96,16 +96,15 @@ func buildPrettyViolationsTable(violations []report.Violation) string {
 	red := color.New(color.FgRed).SprintFunc()
 
 	for i, violation := range violations {
-		level := red(violation.Level)
+		description := red(violation.Description)
 		if violation.Level == "warning" {
-			level = yellow(violation.Level)
+			description = yellow(violation.Description)
 		}
 
 		table.AddRow(yellow("Rule:"), violation.Title)
-		table.AddRow(yellow("Description:"), red(violation.Description))
+		table.AddRow(yellow("Description:"), description)
 		table.AddRow(yellow("Category:"), violation.Category)
 		table.AddRow(yellow("Location:"), cyan(violation.Location.String()))
-		table.AddRow(yellow("Level:"), level)
 
 		if violation.Location.Text != nil {
 			table.AddRow(yellow("Text:"), strings.TrimSpace(*violation.Location.Text))

pkg/reporter/reporter_test.go

@@ -71,8 +71,7 @@ func TestPrettyReporterPublish(t *testing.T) {
 	}
 
 	// TODO(anders): I cannot for the life of me get this to work using a raw string 🫠
-	expect := "Rule:         \tbreaking-the-law                \nDescription:  \tRego must not break the law!    \nCategory:     \tlegal                           \nLocation:     \ta.rego:1:1                      \nLevel:        \terror                           \nText:         \tpackage illegal                 \nDocumentation:\thttps://example.com/illegal     \n              \nRule:         \tquestionable-decision           \nDescription:  \tQuestionable decision found     \nCategory:     \treally?                         \nLocation:     \tb.rego:22:18                    \nLevel:        \twarning                         \nText:         \tdefault allow = true            \nDocumentation:\thttps://example.com/questionable\n\n3 files linted. 2 violations found in 2 files.\n" //nolint:lll
-
+	expect := "Rule:         \tbreaking-the-law                \nDescription:  \tRego must not break the law!    \nCategory:     \tlegal                           \nLocation:     \ta.rego:1:1                      \nText:         \tpackage illegal                 \nDocumentation:\thttps://example.com/illegal     \n              \nRule:         \tquestionable-decision           \nDescription:  \tQuestionable decision found     \nCategory:     \treally?                         \nLocation:     \tb.rego:22:18                    \nText:         \tdefault allow = true            \nDocumentation:\thttps://example.com/questionable\n\n3 files linted. 2 violations found in 2 files.\n" //nolint: lll
 	if buf.String() != expect {
 		t.Errorf("expected %q, got %q", expect, buf.String())
 	}